midgard_object

midgard_object

Synopsis


#include <midgard/midgard.h>

#define             MIDGARD_OBJECT_GET_CLASS_BY_NAME    (name)
                    MgdObject;
typedef             MidgardObject;
typedef             midgard_object;
                    MidgardObjectPrivate;
                    MidgardObjectClassPrivate;
MgdObject *         midgard_object_new                  (MidgardConnection *mgd,
                                                         const gchar *name,
                                                         GValue *value);
gboolean            midgard_object_get_by_id            (MgdObject *object,
                                                         guint id);
gboolean            midgard_object_update               (MgdObject *self);
gboolean            midgard_object_create               (MgdObject *object);
gboolean            midgard_object_is_in_parent_tree    (MgdObject *self,
                                                         guint rootid,
                                                         guint id);
gboolean            midgard_object_is_in_tree           (MgdObject *self,
                                                         guint rootid,
                                                         guint id);
gchar *             midgard_object_get_tree             (MgdObject *object,
                                                         GSList *tnodes);
gboolean            midgard_object_get_by_guid          (MgdObject *object,
                                                         const gchar *guid);
gboolean            midgard_object_delete               (MgdObject *object);
gboolean            midgard_object_purge                (MgdObject *object);
MgdObject *         midgard_object_get_parent           (MgdObject *self);
GObject **          midgard_object_list                 (MgdObject *self,
                                                         guint *n_objects);
GObject **          midgard_object_list_children        (MgdObject *object,
                                                         const gchar *childname,
                                                         guint *n_objects);
gboolean            midgard_object_get_by_path          (MgdObject *self,
                                                         const gchar *path);
const gchar *       midgard_object_parent               (MgdObject *self);
gboolean            midgard_object_undelete             (MidgardConnection *mgd,
                                                         const gchar *guid);
gboolean            midgard_object_set_guid             (MgdObject *self,
                                                         const gchar *guid);
void                midgard_object_set_connection       (MgdObject *self,
                                                         MidgardConnection *mgd);
gboolean            midgard_object_lock                 (MgdObject *self);
gboolean            midgard_object_unlock               (MgdObject *self);
gboolean            midgard_object_is_locked            (MgdObject *self);
gboolean            midgard_object_approve              (MgdObject *self);
gboolean            midgard_object_unapprove            (MgdObject *self);
gboolean            midgard_object_is_approved          (MgdObject *self);

Object Hierarchy

  GObject
   +----midgard_dbobject
         +----midgard_object

Properties

  "action"                   gchar*                : Read / Write
  "guid"                     gchar*                : Read
  "metadata"                 GObject*              : Read / Write

Signals

  "action-approve"                                 : Action
  "action-approve-hook"                            : Action
  "action-approved"                                : Action
  "action-create"                                  : Action
  "action-create-hook"                             : Action
  "action-created"                                 : Action
  "action-delete"                                  : Action
  "action-delete-hook"                             : Action
  "action-deleted"                                 : Action
  "action-export"                                  : Action
  "action-export-hook"                             : Action
  "action-exported"                                : Action
  "action-import"                                  : Action
  "action-import-hook"                             : Action
  "action-imported"                                : Action
  "action-loaded"                                  : Action
  "action-loaded-hook"                             : Action
  "action-lock"                                    : Action
  "action-lock-hook"                               : Action
  "action-locked"                                  : Action
  "action-purge"                                   : Action
  "action-purge-hook"                              : Action
  "action-purged"                                  : Action
  "action-unapprove"                               : Action
  "action-unapprove-hook"                          : Action
  "action-unapproved"                              : Action
  "action-unlock"                                  : Action
  "action-unlock-hook"                             : Action
  "action-unlocked"                                : Action
  "action-update"                                  : Action
  "action-update-hook"                             : Action
  "action-updated"                                 : Action

Description

Details

MIDGARD_OBJECT_GET_CLASS_BY_NAME()

#define MIDGARD_OBJECT_GET_CLASS_BY_NAME(name) ((MidgardObjectClass*) g_type_class_peek(g_type_from_name(name)))

name :

MgdObject

typedef struct {
	GObject parent;
	MidgardDBObjectPrivate *dbpriv;
	MidgardObjectPrivate *priv;	
	MidgardMetadata *metadata;	
} MgdObject;

MidgardObject

typedef struct _MgdObject MidgardObject;

midgard_object

typedef struct _MgdObject midgard_object;

MidgardObjectPrivate

typedef struct _MidgardObjectPrivate MidgardObjectPrivate;

MidgardObjectClassPrivate

typedef struct _MidgardObjectClassPrivate MidgardObjectClassPrivate;

midgard_object_new ()

MgdObject *         midgard_object_new                  (MidgardConnection *mgd,
                                                         const gchar *name,
                                                         GValue *value);

Creates new MgdObject object instance.

This function is mandatory one for new midgard object initialization. Unlike g_object_new ( which is typical function to create new GObject instance ), midgard_object_new initializes data which are accessible internally by object instance itself or by object's class:

- midgard connection handler is associated with object

Sitegroup value is returned from midgard connection handler and may be overwritten only by SG0 Midgard Administrator only when object is created. Setting this property is forbidden when object is already fetched from database.

Object's contructor tries to determine third optional parameter value. If it's of G_TYPE_STRING type , then midgard_is_guid() is called to check weather passed string is a guid , in any other case id property is used with G_TYPE_UINT type. New "empty" instance is created (without fetching data from database) if value parameter is explicitly set to NULL.

Any object instance created with this function should be freed using typical g_object_unref function.

Cases to return NULL:

  • value holds string but it's not a valid guid

  • value holds valid id or guid but object doesn't exists in database ( MGD_ERR_NOT_EXISTS )

  • more than one object identified by particular id or guid returned ( case possible if logged in user is root ) ( MGD_ERR_SITEGROUP_VIOLATION )

  • unspecified internal error ( MGD_ERR_INTERNAL )

mgd :

 MidgardConnection handler

name :

 name of the class

value :

 optional value which holds id or guid of an object

Returns :

 New MgdObject object or NULL on failure

midgard_object_get_by_id ()

gboolean            midgard_object_get_by_id            (MgdObject *object,
                                                         guint id);

Fetch object's record(s) from database using 'id' property.

This is common practice to use 'id' property with integer type when table's id column stores unique, primary key value which identifies object and its record(s). However primary property with integer type is freely defined by user.

MgdObject object instance must be created with midgard_object_new function. When midgard connection handler is not associated with object instance, application is terminated with 'assertion fails' error message being logged.

Object instance created with this function should be freed using g_object_unref.

Cases to return FALSE:

  • There's no 'id' primary property registered for object's class ( MGD_ERR_INTERNAL )

  • Object's record can not be fetched from database ( MGD_ERR_NOT_EXISTS )

  • unspecified internal error ( MGD_ERR_INTERNAL )

object :

 MgdObject instance

id :

 object's integer identifier

Returns :

 TRUE if object is successfully fetched from database, FALSE otherwise.

midgard_object_update ()

gboolean            midgard_object_update               (MgdObject *self);

Update object's record(s).

Internally such metadata properties are set (overwritten):

  • revisor

  • revision ( increased by one )

  • revised

Cases to return FALSE:

  • Property registered with MGD_TYPE_GUID doesn't hold valid guid ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • Object's class is registered with tree facilities and there is already such object in midgard tree ( MGD_ERR_DUPLICATE )

  • Quota is activated and its limit is reached ( MGD_ERR_QUOTA )

  • Unspecified internal error ( MGD_ERR_INTERNAL )

self :

 MgdObject instance

Returns :

 TRUE if object's record(s) is successfully updated, FALSE otherwise.

midgard_object_create ()

gboolean            midgard_object_create               (MgdObject *object);

Creates new database record(s) for object.

Internally such properties are set (overwritten):

  • guid (if not set by root)

  • id (if set as primary property)

Metadata overwritten properties:

  • creator

  • created

  • revisor

  • revised

  • revision

  • published ( set only, if not defined by user )

Cases to return FALSE:

  • Property registered with MGD_TYPE_GUID doesn't hold valid guid ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • Object's class is registered with tree facilities and there is already such object in midgard tree ( MGD_ERR_DUPLICATE )

  • Quota is activated and its limit is reached ( MGD_ERR_QUOTA )

  • Unspecified internal error ( MGD_ERR_INTERNAL )

object :

 MgdObject instance

Returns :

 TRUE on success, FALSE otherwise

midgard_object_is_in_parent_tree ()

gboolean            midgard_object_is_in_parent_tree    (MgdObject *self,
                                                         guint rootid,
                                                         guint id);

Checks whether object exists in parent's type tree.

Midgard tree in #MgdSchema reference

Parent type in midgard tree is a type which can be "container" with object nodes of different types.

self :

 MgdObject instance

rootid :

 guint which identifies parent's type primary property

id :

 guint which identify object's primary property

Returns :

 TRUE if object exists in parent tree, FALSE otherwise.

midgard_object_is_in_tree ()

gboolean            midgard_object_is_in_tree           (MgdObject *self,
                                                         guint rootid,
                                                         guint id);

Checks whether object exists in tree ( of the same type ).

Midgard tree in MgdSchema reference: http://www.midgard-project.org/midcom-permalink-a4e185a08fb2d0e278ef1ba3a739f77e

This function checks only objects of the same type.

self :

 MgdObject instance

rootid :

 guint value which identifies type's primary property

id :

 guint value which identifies object's primary property

Returns :

 TRUE if object exists in tree, FALSE otherwise.

midgard_object_get_tree ()

gchar *             midgard_object_get_tree             (MgdObject *object,
                                                         GSList *tnodes);

object :

tnodes :

Returns :

midgard_object_get_by_guid ()

gboolean            midgard_object_get_by_guid          (MgdObject *object,
                                                         const gchar *guid);

Fetch object's record(s) from database using 'guid' property constraint.

MgdObject object instance must be created with midgard_object_new function. When midgard connection handler is not associated with object instance, application is terminated with 'assertion fails' error message being logged.

Object instance created with this function should be freed using g_object_unref. Cases to return FALSE:

  • Object's record can not be fetched from database ( MGD_ERR_NOT_EXISTS )

  • unspecified internal error ( MGD_ERR_INTERNAL )

object :

 MgdObject instance

guid :

 string value which should identify object

Returns :

 TRUE if object is successfully fetched from database, FALSE otherwise.

midgard_object_delete ()

gboolean            midgard_object_delete               (MgdObject *object);

Delete object's record(s) from database, but object's record is not fully deleted from database. Instead, it is marked as deleted , thus it is possible to undelete object later with static method midgard_object_class_undelete().

Use midgard_object_purge() if you need to purge object's data from database.

Cases to return FALSE:

  • Object's has no storage defined ( MGD_ERR_OBJECT_NO_STORAGE )

  • Object's property guid is empty ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • There are still dependent objects in database ( MGD_ERR_HAS_DEPENDENTS )

  • Unspecified internal error ( MGD_ERR_INTERNAL )

object :

 MgdObject instance

Returns :

 TRUE if object is successfully deleted from database, FALSE otherwise.

midgard_object_purge ()

gboolean            midgard_object_purge                (MgdObject *object);

Purge object's record(s) from database.

Object's record(s) are purged from database without any possibility to recover. After successfull call, only repligard table holds information about object's state. Use midgard_object_delete(), if undelete facility is needed.

Cases to return FALSE:

  • Object has no storage defined ( MGD_ERR_OBJECT_NO_STORAGE )

  • Object's property guid value is empty ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • There are still dependent objects in database ( MGD_ERR_HAS_DEPENDANTS )

  • No record has been deleted from database ( MGD_ERR_NOT_EXISTS )

  • Unspecified internal error ( MGD_ERR_INTERNAL )

object :

 MgdObject instance

Returns :

 TRUE if object has been succesfully purged from database, FALSE otherwise.

midgard_object_get_parent ()

MgdObject *         midgard_object_get_parent           (MgdObject *self);

Fetch parent ( in midgard tree ) object.

This function fetches "upper" object of the same type, and then parent object if object's up property holds empty value. Object is root object in tree when NULL is returned.

self :

 MgdObject instance

Returns :

 new MgdObject object instance or NULL

midgard_object_list ()

GObject **          midgard_object_list                 (MgdObject *self,
                                                         guint *n_objects);

Returned array stores object(s) which up property is equal to self primary property

self :

 MgdObject instance

n_objects :

 stores the length of returned array of objects

Returns :

 newly allocated, NULL terminated array of MgdObject objects

midgard_object_list_children ()

GObject **          midgard_object_list_children        (MgdObject *object,
                                                         const gchar *childname,
                                                         guint *n_objects);

object :

 MgdObject instance

childname :

 child typename

n_objects :

 stores the length of returned array of objects

Returns :

 newly allocated, NULL terminated children objects array

midgard_object_get_by_path ()

gboolean            midgard_object_get_by_path          (MgdObject *self,
                                                         const gchar *path);

Fetch object's record by path

This function is slower than midgard_object_class_get_object_by_path, as it has to create new object instance and copy all properties.

MidgardError is set by midgard_object_class_get_object_by_path in this case. Read about midgard_object_class_get_object_by_path() for more details.

self :

 MgdObject instance

path :

 path at which object should be found

Returns :

 TRUE if object is found, FALSE otherwise.

midgard_object_parent ()

const gchar *       midgard_object_parent               (MgdObject *self);

Returned class name is owned by midgard and should not be freed.

self :

 MidgardObject instance

Returns :

 class name of parent object ( in content tree ).

midgard_object_undelete ()

gboolean            midgard_object_undelete             (MidgardConnection *mgd,
                                                         const gchar *guid);

Deprecated. See midgard_object_class_undelete()

mgd :

 MidgardConnection handler

guid :

 identifier of deleted object

Returns :

 TRUE if object has been undeleted, FALSE otherwise.

midgard_object_set_guid ()

gboolean            midgard_object_set_guid             (MgdObject *self,
                                                         const gchar *guid);

Sets object's guid

Cases to return FALSE:

  • given guid already exists in database ( MGD_ERR_DUPLICATE )

  • given guid is invalid ( MGD_ERR_INVALID_PROPERTY_VALUE )

  • object has already set guid property ( MGD_ERR_INVALID_PROPERTY_VALUE )

self :

 MgdObject instance

guid :

 guid to set

Returns :

 TRUE on success, FALSE otherwise

midgard_object_set_connection ()

void                midgard_object_set_connection       (MgdObject *self,
                                                         MidgardConnection *mgd);

Set object's connection.

This method associate object with connection being already initialized. It's not required to use it in every aplication, however it's mandatory when object has been initialized by some underlying library. For example, object pointer is available from g_object_new instead of midgard_object_new.

Already associated connection is silently ignored.

self :

 MgdObject instance

mgd :

 MidgardConnection instance

midgard_object_lock ()

gboolean            midgard_object_lock                 (MgdObject *self);

Lock object.

This method doesn't affect any core's functionality like midgard_object_approve. You should create own locking workflow and logic with methods: midgard_object_is_locked(), midgard_object_unlock() and this one.

Updates metadata properties: locker, locked, revisor, revised and revision

Cases to return FALSE:

  • No user logged in ( MGD_ERR_ACCESS_DENIED )

  • Metadata class not defined for given object's class ( MGD_ERR_NO_METADATA )

  • Object is already locked ( MGD_ERR_OBJECT_IS_LOCKED )

self :

 MgdObject instance

Returns :

 TRUE on success, FALSE otherwise

midgard_object_unlock ()

gboolean            midgard_object_unlock               (MgdObject *self);

Unlock object.

Cases to return FALSE:

  • No user logged in ( MGD_ERR_ACCESS_DENIED )

  • Object is not locked ( FIXME )

  • Metadata class not defined for given object's class ( MGD_ERR_NO_METADATA )

self :

 MgdObject instance

Returns :

 TRUE on success, FALSE otherwise

midgard_object_is_locked ()

gboolean            midgard_object_is_locked            (MgdObject *self);

Check whether object is locked

Cases to return FALSE:

  • Metadata class not defined for given object's class ( MGD_ERR_NO_METADATA )

self :

 MgdObject instance

Returns :

 TRUE on success, FALSE otherwise

midgard_object_approve ()

gboolean            midgard_object_approve              (MgdObject *self);

Approve object.

Approval functionality is not used by midgard core itself. Instead, it supports higher level's applications. It means, that there are no core methods ( like update or delete ) which do real check if object is approved. You should create own approval workflow and logic with methods: midgard_object_is_approved(), midgard_object_unapprove() and this one.

This method updates metadata properties: revisor, revised, revision, approver and approved.

Cases to return FALSE:

  • No user logged in ( MGD_ERR_ACCESS_DENIED )

  • No active person ( MGD_ERR_INTERNAL )

  • Object is already approved

self :

 MgdObject instance

Returns :

 TRUE if object has been approved, FALSE otherwise

midgard_object_unapprove ()

gboolean            midgard_object_unapprove            (MgdObject *self);

Simply unapprove object. It doesn't affect any core functionality, like midgard_object_approve().

This method updates metadata properties: revisor, revised, revision, approver and approved

Cases to return FALSE:

  • No user logged in ( MGD_ERR_ACCESS_DENIED )

  • Object is not approved

self :

 MgdObject instance

Returns :

 TRUE on success, FALSE otherwise

midgard_object_is_approved ()

gboolean            midgard_object_is_approved          (MgdObject *self);

Check whether object is approved.

self :

 MgdObject instance

Returns :

 TRUE if object is approved, FALSE otherwise

Property Details

The "action" property

  "action"                   gchar*                : Read / Write

What was done with object.

Default value: ""

The "guid" property

  "guid"                     gchar*                : Read

GUID.

Default value: " "

The "metadata" property

  "metadata"                 GObject*              : Read / Write

Property which holds MidgardMetadata object.

Signal Details

The "action-approve" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-approve-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-approved" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-create" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-create-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-created" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-delete" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-delete-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-deleted" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-export" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-export-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-exported" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-import" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-import-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-imported" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-loaded" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-loaded-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-lock" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-lock-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-locked" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-purge" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-purge-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-purged" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-unapprove" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-unapprove-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-unapproved" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-unlock" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-unlock-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-unlocked" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-update" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-update-hook" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "action-updated" signal

void                user_function                      (midgard_object *midgard_object,
                                                        gpointer        user_data)           : Action

midgard_object :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.11