MidgardObject

MidgardObject

Synopsis

#include <midgard/midgard.h>

#define             MIDGARD_OBJECT_GET_CLASS_BY_NAME    (name)
struct              MidgardObject;
                    MidgardObjectPrivate;
                    MidgardObjectClassPrivate;
MidgardObject *     midgard_object_new                  (MidgardConnection *mgd,
                                                         const gchar *name,
                                                         GValue *value);
gboolean            midgard_object_get_by_id            (MidgardObject *object,
                                                         guint id);
gboolean            midgard_object_save                 (MidgardObject *self);
gboolean            midgard_object_update               (MidgardObject *self);
gboolean            midgard_object_create               (MidgardObject *object);
gboolean            midgard_object_get_by_guid          (MidgardObject *object,
                                                         const gchar *guid);
gboolean            midgard_object_delete               (MidgardObject *object,
                                                         gboolean check_dependents);
gboolean            midgard_object_purge                (MidgardObject *object,
                                                         gboolean check_dependents);
gboolean            midgard_object_get_by_path          (MidgardObject *self,
                                                         const gchar *path);
gboolean            midgard_object_set_guid             (MidgardObject *self,
                                                         const gchar *guid);
void                midgard_object_set_connection       (MidgardObject *self,
                                                         MidgardConnection *mgd);
gboolean            midgard_object_lock                 (MidgardObject *self);
gboolean            midgard_object_unlock               (MidgardObject *self);
gboolean            midgard_object_is_locked            (MidgardObject *self);
gboolean            midgard_object_approve              (MidgardObject *self);
gboolean            midgard_object_unapprove            (MidgardObject *self);
gboolean            midgard_object_is_approved          (MidgardObject *self);
MidgardWorkspace *  midgard_object_get_workspace        (MidgardObject *self);

Object Hierarchy

  GObject
   +----MidgardDBObject
         +----MidgardObject

Properties

  "action"                   gchar*                : Read / Write
  "guid"                     gchar*                : Read
  "metadata"                 MidgardMetadata*      : 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-load"                                    : 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)))

struct MidgardObject

struct MidgardObject;

MidgardObjectPrivate

typedef struct _MidgardObjectPrivate MidgardObjectPrivate;

MidgardObjectClassPrivate

typedef struct _MidgardObjectClassPrivate MidgardObjectClassPrivate;

midgard_object_new ()

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

Creates new MidgardObject 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. Or if given string is empty one, or given integer is 0.

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 )

  • 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. [allow-none]

    Returns :

    		 New MidgardObject object or NULL on failure

    midgard_object_get_by_id ()

    gboolean            midgard_object_get_by_id            (MidgardObject *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.

    MidgardObject 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 :

    		 MidgardObject instance

    id :

    		 object's integer identifier

    Returns :

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

    midgard_object_save ()

    gboolean            midgard_object_save                 (MidgardObject *self);

    This method combines update and create routines. It tries to update object, and if this one fails because object's record doesn't exist, it creates it. It's helper routine for application which needs to store object, though it might be a bit slower than create or update method.

    self :

    		 MidgardObject instance

    Returns :

    		 TRUE on success, FALSE otherwise

    Since 10.05.5

    midgard_object_update ()

    gboolean            midgard_object_update               (MidgardObject *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 :

    		 MidgardObject instance

    Returns :

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

    midgard_object_create ()

    gboolean            midgard_object_create               (MidgardObject *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 object with the same name in midgard tree. ( MGD_ERR_DUPLICATE )

    • Object has guid property set already. ( MGD_ERR_DUPLICATE )

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

    • Unspecified internal error ( MGD_ERR_INTERNAL )

    object :

    		 MidgardObject instance

    Returns :

    		 TRUE on success, FALSE otherwise

    midgard_object_get_by_guid ()

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

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

    MidgardObject 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 :

    		 MidgardObject 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               (MidgardObject *object,
                                                         gboolean check_dependents);

    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 midgard_schema_object_factory_object_undelete().

    To perform valid delete operation, object's class has to have either 'metadata' (of MidgardMetadata type) or 'delete' property installed. The latter is not taken into account if metadata object provides own 'deleted' property.

    If check_dependents toggle is TRUE, parameters and attachments storage will be queried, if any of such exist and depend on deleted object.

    If given object's class has no metadata defined, object will be purged.

    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 )

    • Object's class has neither metadata nor deleted property installed ( MGD_ERR_INVALID_PROPERTY_VALUE )

    • There are still dependent objects in database ( MGD_ERR_HAS_DEPENDENTS )

    • Unspecified internal error ( MGD_ERR_INTERNAL )

    object :

    		 MidgardObject instance

    check_dependents :

    		 dependents' check toggle

    Returns :

    		 TRUE if object is successfully marked as deleted, FALSE otherwise.

    midgard_object_purge ()

    gboolean            midgard_object_purge                (MidgardObject *object,
                                                         gboolean check_dependents);

    Purge object's record(s) from database.

    If check_dependents toggle is TRUE, parameters and attachments storage will be queried, if any of such exist and depend on deleted object.

    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 :

    		 MidgardObject instance

    check_dependents :

    		 dependents' check toggle

    Returns :

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

    midgard_object_get_by_path ()

    gboolean            midgard_object_get_by_path          (MidgardObject *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.

    MidgardErrorGeneric is set by midgard_schema_object_factory_get_object_by_path in this case. Read about midgard_schema_object_factory_get_object_by_path() for more details.

    self :

    		 MidgardObject instance

    path :

    		 path at which object should be found

    Returns :

    		 TRUE if object is found, FALSE otherwise.

    midgard_object_set_guid ()

    gboolean            midgard_object_set_guid             (MidgardObject *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 )

    • object is deleted or purged ( MGD_ERR_OBJECT_DELETED or MGD_ERR_OBJECT_PURGED )

    self :

    		 MidgardObject instance

    guid :

    		 guid to set

    Returns :

    		 TRUE on success, FALSE otherwise

    midgard_object_set_connection ()

    void                midgard_object_set_connection       (MidgardObject *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 :

    		 MidgardObject instance

    mgd :

    		 MidgardConnection instance

    midgard_object_lock ()

    gboolean            midgard_object_lock                 (MidgardObject *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 :

    		 MidgardObject instance

    Returns :

    		 TRUE on success, FALSE otherwise

    midgard_object_unlock ()

    gboolean            midgard_object_unlock               (MidgardObject *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 :

    		 MidgardObject instance

    Returns :

    		 TRUE on success, FALSE otherwise

    midgard_object_is_locked ()

    gboolean            midgard_object_is_locked            (MidgardObject *self);

    Check whether object is locked

    Cases to return FALSE:

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

    self :

    		 MidgardObject instance

    Returns :

    		 TRUE on success, FALSE otherwise

    midgard_object_approve ()

    gboolean            midgard_object_approve              (MidgardObject *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 :

    		 MidgardObject instance

    Returns :

    		 TRUE if object has been approved, FALSE otherwise

    midgard_object_unapprove ()

    gboolean            midgard_object_unapprove            (MidgardObject *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 :

    		 MidgardObject instance

    Returns :

    		 TRUE on success, FALSE otherwise

    midgard_object_is_approved ()

    gboolean            midgard_object_is_approved          (MidgardObject *self);

    Check whether object is approved.

    self :

    		 MidgardObject instance

    Returns :

    		 TRUE if object is approved, FALSE otherwise

    midgard_object_get_workspace ()

    MidgardWorkspace *  midgard_object_get_workspace        (MidgardObject *self);

    self :

    		 MidgardObject instance

    Returns :

    		 new MidgardWorkspace object or NULL

    Since 10.05.5

    Property Details

    The "action" property

      "action"                   gchar*                : Read / Write

    Last action done to the object.

    Default value: ""

    The "guid" property

      "guid"                     gchar*                : Read

    GUID identifier of the object.

    Default value: ""

    The "metadata" property

      "metadata"                 MidgardMetadata*      : Read / Write

    midgard_metadata for the object.

    Signal Details

    The "action-approve" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-approved" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-create" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-created" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-delete" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-deleted" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-export" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-exported" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-import" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-imported" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-load" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-loaded" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-lock" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-locked" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-purge" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-purged" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-unapprove" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-unapproved" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-unlock" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-unlocked" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-update" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 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                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

    		 user data set when the signal handler was connected.

    The "action-updated" signal

    void                user_function                      (MidgardObject *midgardobject,
                                                        gpointer       user_data)          : Action

    midgardobject :

    		 the object which received the signal.

    user_data :

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