Changeset 16578

Timestamp:

06/11/08 17:49:24 (4 months ago)

Author:

piotras

Message:

Documentation ported from doxygen to gtk-doc

Files:

• trunk/midgard/core/midgard/src/midgard_object.c (modified) (23 diffs)
• trunk/midgard/core/midgard/src/midgard_object.h (modified) (4 diffs)
• trunk/midgard/core/midgard/src/midgard_tree.c (modified) (2 diffs)

trunk/midgard/core/midgard/src/midgard_object.c

@@ -1 +1 @@
-/* 
- Piotr Pokora <piotr.pokora@infoglob.pl
+,2008 Piotr Pokora <piotrek.pokora@gmail.com
-Copyright (C) 2004 Alexander Bokovoy <ab@samba.org>
-
@@ -556 +556 @@
-}
-
+/**
+ * midgard_object_set_guid:
+ * @self: #MgdObject instance
+ * @guid: guid to set
+ * 
+ * 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 ) 
+ * 
+ * Returns: %TRUE on success, %FALSE otherwise
+ */
-gboolean midgard_object_set_guid(MgdObject *self, const gchar *guid)
-{
@@ -772 +786 @@
-}
-
+/**
+ * midgard_object_update:
+ * @self: #MgdObject instance
+ *
+ * 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 ) 
+ * 
+ * Returns: %TRUE if object's record(s) is successfully updated, %FALSE otherwise.
+ */ 
-gboolean midgard_object_update(MgdObject *self)
-{
@@ -1112 +1145 @@
-}
-
+/**
+ * midgard_object_create:
+ * @object: #MgdObject instance
+ *
+ * Creates new database record(s) for object.
+ *
+ * Internally such properties are set (overwritten):
+ * - sitegroup
+ * - guid (if not set by root)
+ * - id (if set as primary property)
+* 
+ * Metadata 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 ) 
+ * 
+ * Returns: %TRUE on success, %FALSE otherwise
+ */
-gboolean midgard_object_create(MgdObject *object)
-{
@@ -1181 +1241 @@
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-{
-        g_assert(object != NULL);
@@ -1196 +1279 @@
-        
-        /* Find "primary" property , just in case of fatal error */
-
-
-
+
+
-        if(prop == NULL){
-                MIDGARD_ERRNO_SET(object->dbpriv->mgd, MGD_ERR_INTERNAL);
@@ -1251 +1333 @@
-        return FALSE;
-}
-
-GObject **midgard_object_find(MgdObject *object, MidgardTypeHolder *holder)
-{
-        GParamSpec **props;
-        guint propn, i;
-        GValue pval = {0,};
-        
-        MIDGARD_ERRNO_SET(object->dbpriv->mgd, MGD_ERR_OK);
-
-        props = g_object_class_list_properties(
-                        G_OBJECT_CLASS(MIDGARD_OBJECT_GET_CLASS(object)), &propn);
-        if(!props){
-                g_warning("No properties found for %s class!",
-                                G_OBJECT_TYPE_NAME(object));
-                MIDGARD_ERRNO_SET(object->dbpriv->mgd, MGD_ERR_INTERNAL);
-                return NULL;
-        }
-        
-        MidgardQueryBuilder *builder =
-                        midgard_query_builder_new(object->dbpriv->mgd, G_OBJECT_TYPE_NAME(object));
-        if(!builder){
-                MIDGARD_ERRNO_SET(object->dbpriv->mgd, MGD_ERR_INTERNAL);
-                return NULL;
-        }
-
-        for(i = 0; i < propn; i++) {
-                g_value_init(&pval,props[i]->value_type);
-                g_object_get_property(G_OBJECT(object),                                                                             props[i]->name, &pval);
-                switch (props[i]->value_type) {
-                        
-                        case G_TYPE_STRING:
-                                if(g_value_get_string(&pval))
-                                        midgard_query_builder_add_constraint(builder,
-                                                        props[i]->name, "=", &pval);
-                                break;
-
-                        case G_TYPE_UINT:
-                                if(g_value_get_uint(&pval))
-                                        midgard_query_builder_add_constraint(builder,
-                                                        props[i]->name, "=", &pval);
-                                break;
-                        
-                        case G_TYPE_INT:
-                                if(g_value_get_int(&pval))
-                                        midgard_query_builder_add_constraint(builder,
-                                                        props[i]->name, "=", &pval);
-                                break;
-
-                        case G_TYPE_FLOAT:
-                                if(g_value_get_float(&pval))
-                                        midgard_query_builder_add_constraint(builder,
-                                                        props[i]->name, "=", &pval);
-                                break;
-
-                        case G_TYPE_BOOLEAN:
-                                if(g_value_get_boolean(&pval))
-                                        midgard_query_builder_add_constraint(builder,
-                                                        props[i]->name, "=", &pval);
-                                break;
-
-                        case G_TYPE_OBJECT:
-                                /* TODO */
-                                break;
-
-                        default:
-                                if(g_value_get_string(&pval))
-                                        midgard_query_builder_add_constraint(builder,
-                                                        props[i]->name, "=", &pval);
-                                break;                  
-                }
-                g_value_unset(&pval);
-        }
-        
-        GObject **objects = midgard_query_builder_execute(builder, holder);     
-        g_object_unref(builder);
-        return objects;
-}
-
-
-/* Initialize class. 
@@ -1714 +1718 @@
-}
-
+/**
+ * midgard_object_new:
+ * @mgd: #MidgardConnection handler
+ * @name: name of the class 
+ * @value: optional value which holds id or guid of an object 
+ * 
+ * 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' property of an object is being set
+ * 
+ * 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 ) 
+ * 
+ * Returns: New #MgdObject object or %NULL on failure 
+ */ 
-MgdObject *
-midgard_object_new(MidgardConnection *mgd, const gchar *name, GValue *value)
-{
-        g_assert(mgd != NULL);
+
+        MIDGARD_ERRNO_SET(mgd, MGD_ERR_OK);
-
-        GType type;
@@ -1752 +1797 @@
-
-                        if(!objects) {
-
+
+
-                                return NULL;
-                        }
@@ -1779 +1825 @@
-                }
-
-
+
+
-                        return NULL;
+                }
-
-                self->dbpriv->storage_data = 
@@ -1787 +1835 @@
-                if (!g_type_class_peek(type)) {
-                        g_object_unref(self);
+                        MIDGARD_ERRNO_SET(mgd, MGD_ERR_INTERNAL);
-                        return NULL;
-                }
@@ -1804 +1853 @@
-}
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        g_assert(mobj != NULL);
-        
@@ -1986 +2015 @@
-}
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-gboolean midgard_object_get_by_guid(MgdObject *object, const gchar *guid)
-{
@@ -2042 +2089 @@
-}
-
+/**
+ * midgard_object_delete:
+ * @object: #MgdObject instance
+ *
+ * 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_undelete.
+ *
+ * If object's klass is defined as multilingual , and there is more than one 
+ * language content in database , then only particular object's content is
+ * removed. In such case object is not marked as deleted. 
+ * Content itself is not removed if language is set to 0.
+ *
+ * Use #midgard_object_purge if you need to purge object's data from database.
+ * 
+ * FALSE is returned in such cases:
+ *
+ * - Object's has no storage defined ( MGD_ERR_OBJECT_NO_STORAGE )
+ * - Object's property guid is empty ( MGD_ERR_INVALID_PROPERTY_VALUE )
+ * - Unspecified internal error ( MGD_ERR_INTERNAL ) 
+ *  
+ * Returns: %TRUE if object is successfully deleted from database, %FALSE otherwise.
+ */ 
-gboolean midgard_object_delete(MgdObject *object)
-{
@@ -2194 +2264 @@
-}
-
+/**
+ * midgard_object_purge:
+ * @object: #MgdObject instance
+ *
+ * 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 is empty ( MGD_ERR_INVALID_PROPERTY_VALUE ) 
+ * - No record has been deleted from database ( MGD_ERR_NOT_EXISTS )
+ * - Unspecified internal error ( MGD_ERR_INTERNAL ) 
+ *
+ * Returns: %TRUE if object has been succesfully purged from database, %FALSE otherwise.
+ */ 
-gboolean midgard_object_purge(MgdObject *object)
-{
@@ -2214 +2302 @@
-        table = _midgard_core_class_get_table(MIDGARD_DBOBJECT_CLASS(klass));   
-        if(table == NULL) {
--1
+FALSE
-                g_warning("Object '%s' has no table or storage defined!", 
-                                G_OBJECT_TYPE_NAME(object));    
@@ -2412 +2500 @@
-}
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        g_assert(object != NULL);
-        GParamSpec *fprop, *uprop;
@@ -2464 +2565 @@
-}
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-GObject **midgard_object_list_children(MgdObject *object, 
-                const gchar *childcname, MidgardTypeHolder *holder)
@@ -2536 +2647 @@
-}
-
+/**
+ * midgard_object_get_languages:
+ * @self: #MgdObject instance
+ * @holder: #MidgardTypeHolder which stores number of returned objects
+ *
+ * Returns midgard_language objects for the given Midgard Object instance.
+ * Returned array is limited to midgard_language objects for which content
+ * exists for the given Midgard Object instance.
+ * 
+ * @holder parameter is optional ( may be passed as NULL ).
+ * If used, should be freed when no longer needed.
+ * holder->elements stores number of returned objects
+ * 
+ * Cases to return %NULL:
+ * - object is not multilang ( MGD_ERR_USER_DATA ) 
+ * - object has invalid guid ( MGD_ERR_INVALID_PROPERTY ) 
+ * 
+ * Returns: newly allocated, %NULL terminated array of #MgdObject objects or %NULL
+ */ 
-GObject **midgard_object_get_languages(MgdObject *self, MidgardTypeHolder *holder)
-{
@@ -2635 +2765 @@
-}
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-        
-        return NULL;    
-}
-
+/** 
+ * midgard_object_get_by_path:
+ * @self: #MgdObject instance
+ * @path: path at which object should be found
+ *
+ * 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.
+ * 
+ * Returns: %TRUE if object is found, %FALSE otherwise.
+ */ 
-gboolean midgard_object_get_by_path(MgdObject *self, const gchar *path)
-{
@@ -2666 +2818 @@
-}
-
+
+/**
+ * midgard_object_undelete:
+ * @mgd: #MidgardConnection handler
+ * @guid: identifier of deleted object
+ * 
+ * Deprecated. See #midgard_object_class_undelete
+ * 
+ * Returns: %TRUE if object has been undeleted, %FALSE otherwise.
+ */
-gboolean midgard_object_undelete(MidgardConnection *mgd, const gchar *guid)
-{
@@ -2671 +2833 @@
-}
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-void midgard_object_set_connection(MgdObject *self, MidgardConnection *mgd)
-{
@@ -2684 +2861 @@
-        self->dbpriv->sg = midgard_connection_get_sitegroup_id(mgd);
-}
-
-gchar *midgard_object_export(MgdObject *self)
-{
-        g_assert(self);
-        
-        MIDGARD_ERRNO_SET(self->dbpriv->mgd, MGD_ERR_OK);
-
-        gchar *guid;
-        g_object_get(G_OBJECT(self), "guid", &guid, NULL);
-
-        if(!guid){
-                midgard_set_error(self->dbpriv->mgd,
-                                MGD_GENERIC_ERROR,
-                                MGD_ERR_INVALID_PROPERTY_VALUE,
-                                "Empty guid value! ");
-                g_warning("%s", self->dbpriv->mgd->errstr);
-                g_clear_error(&self->dbpriv->mgd->err);
-
-                return NULL;
-        }
-
-        /* FIXME , remove this select when PHP language bindings use 1:1
-         * for zend and gobject objects , REMOVE */
-        /*
-        midgard_res *res;
-        MidgardObjectClass *klass = 
-                MIDGARD_OBJECT_GET_CLASS(self);
-        
-        GString *sql = g_string_new("SELECT ");
-        g_string_append_printf(sql,
-                        "NULLIF(metadata_exported,'0000-00-00 00:00:00') "
-                        "AS metadata_exported FROM %s "
-                        "WHERE guid = '%s' ",
-                        midgard_object_class_get_table(klass),
-                        guid);
-
-        if(!midgard_core_isroot(self)){
-                g_string_append_printf(sql,
-                                " AND sitegroup = %d",
-                                _midgard_core_sitegroup(self));
-        }
-        
-        gchar *query = g_string_free(sql, FALSE);
-        res = mgd_query(self, query);
-        g_free(query);
-        
-        if (!res || !mgd_fetch(res)) {
-                if(res) mgd_release(res);
-                MIDGARD_ERRNO_SET(self, MGD_ERR_NOT_EXISTS);
-                return NULL;
-        }       
-        self->priv->exported = g_strdup((gchar *)mgd_colvalue(res, 0));
-        mgd_release(res);
-        */
-        /* REMOVE end*/
-        
-        g_free(guid);   
-        
-        /* Update object */
-        if(_midgard_object_update(self, OBJECT_UPDATE_EXPORTED))
-                return _midgard_core_object_to_xml(self);
-
-        return NULL;
-}

trunk/midgard/core/midgard/src/midgard_object.h

@@ -1 +1 @@
-/* 
- Piotr Pokora <piotr.pokora@infoglob.pl
+,2007,2008 Piotr Pokora <piotrek.pokora@gmail.com
-Copyright (C) 2004 Alexander Bokovoy <ab@samba.org>
-
@@ -18 +18 @@
-*/
-
-TYPES
-TYPES
+MIDGARD_OBJECT
+MIDGARD_OBJECT
-
-/** 
@@ -59 +59 @@
-typedef struct MidgardMetadata MidgardMetadata;
-typedef struct MidgardMetadataClass MidgardMetadataClass;
-
-/* Get object by id and by type , only for backwards compatibility */
-
-#define _MIDGARD_OBJECT_GET_BY_TYPE(klassname) \
-    if ((object = midgard_object_new(mgd, klassname, NULL)) != NULL ) { \
-        if ((midgard_object_get_by_id(object, (guint) id)) == 0);  \
-                return object; \
-        return NULL; \
-    } else { \
-        return NULL; \
-    } \
-
-struct _MgdObject {
@@ -130 +119 @@
-};
-
-extern void midgard_get_midgard(MgdObject *mobj, MidgardConnection *mg
+GType midgard_object_get_type(voi
-
-/**
- * \ingroup MgdObject
- *
- * Returns Midgard Object type. 
- * Registers the type as a fundamental GType unless already registered.
- */
-extern GType midgard_object_get_type(void);
-
-/** 
- * \ingroup MgdObject
- *
- * MidgardObjectAction defines current state of an object if object
- * is instatiated only by guid without type name information.
- *
- * <pre>
- * enum
- * {
- *           MGD_OBJECT_ACTION_NONE = 0,
- *           MGD_OBJECT_ACTION_CREATE,
- *           MGD_OBJECT_ACTION_UPDATE, 
- *           MGD_OBJECT_ACTION_DELETE,
- *           MGD_OBJECT_ACTION_PURGE
- * }MidgardObjectAction;
- * </pre>
- * 
- * - MGD_OBJECT_ACTION_NONE , typical object state
- * - MGD_OBJECT_ACTION_DELETE, object has been deleted and can be undeleted
- * - MGD_OBJECT_ACTION_PURGE, object has been purged ( no recovery or undelete )  
- *
- */
-extern enum
-{
-        MGD_OBJECT_ACTION_NONE = 0,
-
-
-
-
+ /**< Object has been deleted and can be undeleted >*/
+ /**< Object has been purged ( no recovery or undelete ) >*/
+ /**< Object has been created >*/
+ /**< Object has been updated >*/
-}MidgardObjectAction;
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-