Changeset 16574

Show
Ignore:
Timestamp:
06/10/08 18:13:42 (4 months ago)
Author:
piotras
Message:

Removed extern definitions from public headers ( to help mono bindings ).
Documentation part ported from doxygen to gtk-doc.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/midgard/core/midgard/src/midgard_blob.c

    r15807 r16574  
    11/*  
    2  * Copyright (C) 2006,2007,2008 Piotr Pokora <piotrek.pokora@gmail.com> 
     2 * Copyright (C) 2006, 2007, 2008 Piotr Pokora <piotrek.pokora@gmail.com> 
    33 * 
    44 * This program is free software; you can redistribute it and/or modify it 
    …… 
    116116} 
    117117 
    118  
    119 /* Instatiate new Midgard Blob. */ 
     118/** 
     119 * midgard_blob_new:  
     120 * @attachment: #MgdObject of MIDGARD_TYPE_ATTACHMENT type. 
     121 *  
     122 * Instatiate new Midgard Blob object for the given midgard_attachment object.  
     123 * This is almost the same constructor as g_object_new, but unlike that one, 
     124 * midgard_blob_new requires MgdObject (midgard_attachment) object's pointer. 
     125 * 
     126 * This constructor defines new relative path for attachment, if midgard_attachment  
     127 * is associated with midgard_blob and its location is empty.  
     128 * In any other case, location is not changed. 
     129 *  
     130 * Returns: newly instatiated #MidgardBlob object or %NULL on failure 
     131 */ 
    120132MidgardBlob *midgard_blob_new(MgdObject *attachment) 
    121133{ 
    …… 
    161173} 
    162174 
    163 /* Returns file's content. */  
     175/** 
     176 * midgard_blob_read_content: 
     177 * @self: MidgardBlob self instance 
     178 * @bytes_read: number of bytes read 
     179 * 
     180 * Returned content should be freed when no longer needed. 
     181 * @bytes_read holds size of returned content.  
     182 * 
     183 * This function should be used to get content of small files. 
     184 * For large and huge ones midgard_blob_get_handler should be used 
     185 * to get file handle. 
     186 *  
     187 * Returns: content of the file, or %NULL on failure 
     188 */  
    164189gchar *midgard_blob_read_content(MidgardBlob *self, gsize *bytes_read) 
    165190{ 
    …… 
    250275} 
    251276 
    252 /* Write given content to a file */  
     277/** 
     278 * midgard_blob_write_content: 
     279 * @self: #MidgardBlob self instance. 
     280 * @content: content which should be written to file. 
     281 *  
     282 * Write given @content to a file. 
     283 *  
     284 * Returns: %TRUE if content has been written to file, %FALSE otherwise. 
     285 */  
    253286gboolean  midgard_blob_write_content(MidgardBlob *self, const gchar *content) 
    254287{ 
    …… 
    297330} 
    298331 
    299 /* Get GIOChannel */ 
     332/** 
     333 * midgard_blob_get_handler: 
     334 * @self: #MidgardBlob instance 
     335 * 
     336 * \return GIOChannel 
     337 * 
     338 * The main idea is to get file handler. On C level it returns 
     339 * GIOChannel, but language bindings could return typical file handler  
     340 * or anything else which is needed for particular language. 
     341 * 
     342 * Returned channel is owned by midgard_blob and should not be freed 
     343 * or unreferenced. 
     344 */ 
    300345GIOChannel *midgard_blob_get_handler(MidgardBlob *self) 
    301346{ 
    …… 
    312357} 
    313358 
    314 /* Get absolute path of a file */ 
     359/**  
     360 * midgard_blob_get_path: 
     361 * @self: #MidgardBlob instance 
     362 * 
     363 * Returned path is owned by midgard_blob and should not be freed. 
     364 * It basically contains blobdir and relative file's location. 
     365 * 
     366 * Returns: absolute path or %NULL if path is not set yet. 
     367 */  
    315368const gchar *midgard_blob_get_path(MidgardBlob *self) 
    316369{ 
    …… 
    327380} 
    328381 
    329 /* Check if file exists */ 
     382/** 
     383 * midgard_blob_exists: 
     384 * @self: #MidgardBlob instance 
     385 * 
     386 * Check if file associated with midgard_blob exists. 
     387 * This function will also return FALSE, if file is not yet associated. 
     388 * 
     389 * Returns: %TRUE if file exists, %FALSE otherwise 
     390 */  
    330391gboolean midgard_blob_exists(MidgardBlob *self) 
    331392{ 
    …… 
    353414} 
    354415 
    355 /* Delete file associated wtih MidgardBlob instance. */ 
     416/** 
     417 * midgard_blob_remove_file: 
     418 * @self: #MidgardBlob self instance. 
     419 * 
     420 * Deletes a file which is associated with blob and located at 
     421 * attachment's location which is initialized for blob. 
     422 * #midgard_blob_exists should be invoked if file may be already  
     423 * deleted, for example when one file is shared among many attachments. 
     424 * 
     425 * Returns: %TRUE on success, %FALSE otherwise 
     426 */  
    356427gboolean midgard_blob_remove_file(MidgardBlob *self) 
    357428{ 

  • trunk/midgard/core/midgard/src/midgard_blob.h

    r15473 r16574  
    11/*  
    2  * Copyright (C) 2006, 2008 Piotr Pokora <piotr.pokora@infoglob.pl> 
     2 * Copyright (C) 2006, 2008 Piotr Pokora <piotrek.pokora@gmail.com> 
    33 * 
    44 * This program is free software; you can redistribute it and/or modify it 
    …… 
    2929 */ 
    3030 
    31  
    3231#include "midgard_connection.h" 
    3332#include "midgard_object.h" 
    …… 
    5251typedef struct _MidgardBlobPrivate MidgardBlobPrivate; 
    5352 
    54 /** 
    55  * \ingroup midgard_blob 
    56  * 
    57  * MidgardObjectClass structure. 
    58  */  
    5953struct MidgardBlobClass { 
    6054        GObjectClass parent; 
    …… 
    6862}; 
    6963 
    70 /** 
    71  * \ingroup midgard_blob 
    72  * 
    73  * MidgardObject structure 
    74  */  
    7564struct MidgardBlob { 
    7665        GObject parent; 
    …… 
    7968}; 
    8069 
    81 /** 
    82  * \ingroup midgard_blob 
    83  * 
    84  * Returns Midgard Blob Gtype value. 
    85  * Registers this type unless already registered. 
    86  */  
    87 extern GType  
    88 midgard_blob_get_type(void); 
    89  
    90 /** 
    91  * \ingroup midgard_blob 
    92  *  
    93  * Instatiate new Midgard Blob. 
    94  * 
    95  * \param attachment , MidgardObject of MIDGARD_TYPE_ATTACHMENT type. 
    96  *  
    97  * \return MidgardBlob, newly instatiated MidgardBlob object. 
    98  *  
    99  * Instatiate new Midgard Blob object for the given midgard_attachment object.  
    100  * This is almost the same constructor as g_object_new, but unlike that one, 
    101  * midgard_object_new requires  MgdObject object's pointer. 
    102  * 
    103  * This constructor defines new relative path for attachment, if midgard_attachment  
    104  * is associated with midgard_blob and its location is empty.  
    105  * In any other case, location is not changed. 
    106  */ 
    107 extern MidgardBlob * 
    108 midgard_blob_new(MgdObject *attachment); 
    109  
    110 /** 
    111  * \ingroup midgard_blob 
    112  * 
    113  * Returns content of the file. 
    114  * 
    115  * \param self, MidgardBlob self instance 
    116  * \param bytes_read, number of bytes read 
    117  *  
    118  * \return file's content or NULL. 
    119  * 
    120  * Returned content should be freed when no longer needed. 
    121  * \c bytes_read returned content's size. It should be used if content 
    122  * is passed to function which requires its size. In such case, there's 
    123  * no need to count content size once again. 
    124  * 
    125  * This function should be used to get content of small files. 
    126  * For large and huge ones midgard_blob_get_handler should be used 
    127  * to get file handle. 
    128  */  
    129 extern gchar * 
    130 midgard_blob_read_content(MidgardBlob *self, gsize *bytes_read); 
    131  
    132 /** 
    133  * \ingroup midgard_blob 
    134  * 
    135  * Write given content to a file. 
    136  * 
    137  * \param self, MidgardBlob self instance. 
    138  * \param content, content which should be written to file. 
    139  * 
    140  * \return TRUE if content has been written to file, FALSE otherwise. 
    141  */  
    142 extern gboolean 
    143 midgard_blob_write_content(MidgardBlob *self, 
    144                                 const gchar *content); 
    145  
    146 /** 
    147  * \ingroup midgard_blob 
    148  * 
    149  * Get GIOChannel 
    150  * 
    151  * \param self, MidgardBlob instance 
    152  * 
    153  * \return GIOChannel 
    154  * 
    155  * The main idea is to get file handler. On C level it returns 
    156  * GIOChannel, but language bindings could return typical file handler  
    157  * or anything else which is needed for particular language. 
    158  * 
    159  * Returned channel is owned by midgard_blob and should not be freed 
    160  * or unreferenced. 
    161  */ 
    162 extern GIOChannel *midgard_blob_get_handler(MidgardBlob *self); 
    163  
    164 /**  
    165  * \ingroup midgard_blob 
    166  * 
    167  * Get absolute path of a file 
    168  * 
    169  * \param self, MidgardBlob instance 
    170  *  
    171  * \return absolute path or NULL in case of failure 
    172  * 
    173  * Returned path is owned by midgard_blob and should not be freed. 
    174  * It basically contains blobdir and relative file's location. 
    175  */  
    176 extern const gchar *midgard_blob_get_path(MidgardBlob *self); 
    177  
    178 /** 
    179  * \ingroup midgard_blob 
    180  * 
    181  * Check if file exists 
    182  * 
    183  * \param self, MidgardBlob instance 
    184  * \return TRUE if file exists, FALSE otherwise 
    185  * 
    186  * Check if file associated with midgard_blob exists. 
    187  * This function will also return FALSE, if file is not yet  
    188  * associated. 
    189  */  
    190 extern gboolean midgard_blob_exists(MidgardBlob *self); 
    191  
    192 /** 
    193  * \ingroup midgard_blob 
    194  *  
    195  * Delete file associated wtih MidgardBlob instance. 
    196  * 
    197  * \param self, MidgardBlob self instance. 
    198  * 
    199  * \return TRUE on success, FALSE otherwise 
    200  * 
    201  * Deletes a file which is associated with blob and located 
    202  * in attachment's location which is initialized for blob. 
    203  * midgard_blob_exists should be invoked if file may be already  
    204  * deleted, for example when one file is shared among many attachments. 
    205  */  
    206 extern gboolean midgard_blob_remove_file(MidgardBlob *self); 
     70GType midgard_blob_get_type(void); 
     71MidgardBlob *midgard_blob_new(MgdObject *attachment); 
     72gchar *midgard_blob_read_content(MidgardBlob *self, gsize *bytes_read); 
     73gboolean midgard_blob_write_content(MidgardBlob *self, const gchar *content); 
     74GIOChannel *midgard_blob_get_handler(MidgardBlob *self); 
     75const gchar *midgard_blob_get_path(MidgardBlob *self); 
     76gboolean midgard_blob_exists(MidgardBlob *self); 
     77gboolean midgard_blob_remove_file(MidgardBlob *self); 
    20778 
    20879G_END_DECLS 
    209  
    21080#endif /* _MIDGARD_BLOB_H */ 

  • trunk/midgard/core/midgard/src/midgard_dbus.h

    r16468 r16574  
    6161}; 
    6262 
    63 extern GType midgard_dbus_get_type(void); 
     63GType midgard_dbus_get_type(void); 
    6464 
    65 extern MidgardDbus *midgard_dbus_new(MidgardConnection *mgd, const gchar *path); 
    66  
    67 extern void midgard_dbus_send(MidgardConnection *mgd, const gchar *path, const gchar *message); 
    68  
    69 extern const gchar *midgard_dbus_get_message(MidgardDbus *self); 
    70  
    71 extern const gchar *midgard_dbus_get_name(void); 
     65MidgardDbus *midgard_dbus_new(MidgardConnection *mgd, const gchar *path); 
     66void midgard_dbus_send(MidgardConnection *mgd, const gchar *path, const gchar *message); 
     67const gchar *midgard_dbus_get_message(MidgardDbus *self); 
     68const gchar *midgard_dbus_get_name(void); 
    7269 
    7370G_END_DECLS 

  • trunk/midgard/core/midgard/src/midgard_error.c

    r16260 r16574  
    11/*  
    2  * Copyright (C) 2006 Piotr Pokora <piotr.pokora@infoglob.pl> 
     2 * Copyright (C) 2006 Piotr Pokora <piotrek.pokora@gmail.com> 
    33 * 
    44 * This program is free software; you can redistribute it and/or modify it 
    …… 
    2323#include <unistd.h> 
    2424 
     25/** 
     26 * midgard_error_generic: 
     27 * 
     28 * GQuark for Midgard Error. It's used by Midgard Error implementation, and  
     29 * probably not needed to use by any application. 
     30 * 
     31 * Returns: MGD_GENERIC_ERROR GQuark 
     32 */ 
    2533GQuark midgard_error_generic(void) 
    2634{ 
    …… 
    3139} 
    3240 
     41/** 
     42 * midgard_error_string: 
     43 * @domain, GQuark which represents MidgardError domain. 
     44 * @errcode, MidgardErrorGeneric enum value. 
     45 * 
     46 * Get error message for the given error code. 
     47 * 
     48 * Returns: error messages which is owned by midgard-core and should not be freed. 
     49 */  
    3350const gchar *midgard_error_string(GQuark domain, gint errcode) 
    3451{ 
    …… 
    156173} 
    157174 
     175/** 
     176 * midgard_set_error: 
     177 * @mgd: #MidgardConnection instance  
     178 * @domain: GQuark which represents MidgardError domain 
     179 * @errcode: #MidgardErrorGeneric enum value 
     180 * @msg: a message which should be appended to string represented by errcode 
     181 * @...: message argument list ( if required ) 
     182 * 
     183 * This function sets internal error constant, and creates new error message. 
     184 * User defined message is appended to internal one. 
     185 * Any message created by application ( and its corresponding constant ) are destroyed  
     186 * and reset to MGD_ERR_OK when any API function is invoked. 
     187 * Second @domain parameter is optional , and can be safely defined as NULL for  
     188 * MGD_GENERIC_ERROR domain. 
     189 * 
     190 * <strong> Example: </strong> 
     191 * @code 
     192 *       
     193 *      void set_wrong_property(MidgardConnection *mgd, gchar *prop) 
     194 *      { 
     195 *              midgard_set_error(mgd, NULL,  
     196 *                              MGD_ERR_INVALID_PROPERTY_VALUE, 
     197 *                              "My application doesn't accept %s property", 
     198 *                              prop); 
     199 *      } 
     200 * @endcode 
     201 */  
    158202void midgard_set_error( 
    159203                MidgardConnection *mgd, GQuark domain, gint errcode, const gchar *msg, ...) 
    …… 
    196240} 
    197241 
    198 /* Default function for log messages. */ 
     242/** 
     243 * midgard_error_default_log: 
     244 * @domain: domain for the given log message 
     245 * @level: GLogLevelFlags 
     246 * @msg: log message 
     247 * @ptr: pointer to structure which holds loglevel  
     248 * 
     249 * @ptr pointer may be a pointer to #MidgardConnection or #MidgardTypeHolder 
     250 * structure. This function checks pointer type using MIDGARD_IS_CONNECTION 
     251 * convention macro. Next midgard_connection_get_loglevel is called to get loglevel. 
     252 * If MidgardConnection check fails , a typecast to MidgardTypeHolder is made. 
     253 * In this case, level member is used to get loglevel. 
     254 * 
     255 * You are responsible to correctly set MidgardConnection or MidgardTypeHolder 
     256 * before passing ptr argument. The main approach is to follow configuration's 
     257 * loglevel even if MidgardConnection pointer is not yet available. 
     258 * 
     259 * @see #midgard_connection_set_loglevel to set log level.       
     260 */ 
    199261void midgard_error_default_log(const gchar *domain, GLogLevelFlags level, 
    200262                const gchar *msg, gpointer ptr) 
    …… 
    295357} 
    296358 
    297 /* Get GLogLevelFlags value from loglevel string */ 
     359 
     360/** 
     361 * midgard_error_parse_loglevel: 
     362 * @levelstring: string which should be parsed 
     363 * 
     364 * This function returns level registered in GLib.  
     365 * 
     366 * Returns: #GLogLevelFlags or -1 on failure 
     367 */ 
    298368gint midgard_error_parse_loglevel(const gchar *levelstring) 
    299369{ 

  • trunk/midgard/core/midgard/src/midgard_error.h

    r16187 r16574  
    11/*  
    2  * Copyright (C) 2006 Piotr Pokora <piotr.pokora@infoglob.pl> 
     2 * Copyright (C) 2006 Piotr Pokora <piotrek.pokora@gmail.com> 
    33 * 
    44 * This program is free software; you can redistribute it and/or modify it 
    …… 
    7070}MgdErrorGeneric; 
    7171 
    72 /** 
    73  * \ingroup midgard_error 
    74  * 
    75  * GQuark for Midgard Error. It's used by Midgard Error implementation, and  
    76  * probably is not needed to use by any application. 
    77  * 
    78  * \return MGD_GENERIC_ERROR GQuark 
    79  */ 
    80 extern GQuark midgard_error_generic(void); 
    81  
    82 /** 
    83  * \ingroup midgard_error 
    84  * 
    85  * Get error message for the given error code. 
    86  * 
    87  * \param domain , GQuark which represents MidgardError domain. 
    88  * \param errcode, MidgardErrorGeneric enum value. 
    89  * 
    90  * \return error messages which is owned by midgard-core and should not be freed. 
    91  */  
    92 extern const gchar *midgard_error_string(GQuark domain, gint errcode); 
    93  
    94 /** 
    95  * \ingroup midgard_error 
    96  * 
    97  * Sets internal error constant and error message. 
    98  * 
    99  * \param mgd, MidgardConnection instance  
    100  * \param domain, GQuark which represents MidgardError domain 
    101  * \param errcode, MidgardErrorGeneric enum value 
    102  * \param msg, a message which should be appended to string represented by errcode 
    103  * \param ..., message argument list ( if required ) 
    104  * 
    105  * This function sets internal error constant, and creates new error message. 
    106  * User defined message is appended to internal one. 
    107  * Any message created by application ( and its corresponding constant ) are destroyed  
    108  * and reset to MGD_ERR_OK when any API function is invoked. 
    109  * Second \c domain parameter is optional , and can be safely defined as NULL for  
    110  * MGD_GENERIC_ERROR domain. 
    111  * 
    112  * <strong> Example: </strong> 
    113  * @code 
    114  *       
    115  *      void set_wrong_property(MidgardConnection *mgd, gchar *prop) 
    116  *      { 
    117  *              midgard_set_error(mgd, NULL,  
    118  *                              MGD_ERR_INVALID_PROPERTY_VALUE, 
    119  *                              "My application doesn't accept %s property", 
    120  *                              prop); 
    121  *      } 
    122  * @endcode 
    123  */  
    124 extern void midgard_set_error( 
     72GQuark midgard_error_generic(void); 
     73const gchar *midgard_error_string(GQuark domain, gint errcode); 
     74void midgard_set_error( 
    12575                MidgardConnection *mgd, GQuark domain,  
    12676                gint errcode, const gchar *msg, ...); 
     77void midgard_error_default_log(const gchar *domain, GLogLevelFlags level, 
     78                const gchar *msg, gpointer ptr); 
     79gint midgard_error_parse_loglevel(const gchar *levelstring); 
    12780 
    128 /** 
    129  * \ingroup midgard_error 
    130  * 
    131  * Default function for log messages. 
    132  * 
    133  * \param domain, domain for the given log message 
    134  * \param level, GLogLevelFlags 
    135  * \param msg, log message 
    136  * \param ptr, pointer to structure which holds loglevel  
    137  * 
    138  * \c ptr pointer may be a pointer to MidgardConnection or MidgardTypeHolder 
    139  * structure. This function checks pointer type using MIDGARD_IS_CONNECTION 
    140  * convention macro. Next midgard_connection_get_loglevel is called to get loglevel. 
    141  * If MidgardConnection check fails , a typecast to MidgardTypeHolder is made. 
    142  * In this case, level member is used to get loglevel. 
    143  * 
    144  * You are responsible to correctly set MidgardConnection or MidgardTypeHolder 
    145  * before passing ptr argument. The main approach is to follow configuration's 
    146  * loglevel even if MidgardConnection pointer is not yet available. 
    147  * 
    148  * Use midgard_connection_set_loglevel to set log level.         
    149  * 
    150  */ 
    151 extern void midgard_error_default_log(const gchar *domain, GLogLevelFlags level, 
    152                 const gchar *msg, gpointer ptr); 
    153  
    154 /** 
    155  * \ingroup midgard_error 
    156  * 
    157  * Get GLogLevelFlags value from loglevel string. 
    158  * 
    159  * \param levelstring, string which should be parsed 
    160  * 
    161  * \return GLogLevelFlags or -1 on failure 
    162  * 
    163  */ 
    164 extern gint midgard_error_parse_loglevel(const gchar *levelstring); 
    165  
    166 /** 
    167  * \ingroup midgard_error  
    168  * 
    169  * #define MIDGARD_ERRNO_SET(mgd, errcode) 
    170  * 
    171  * A simplified macro to set default error 
    172  */  
    17381 
    17482#define MIDGARD_ERRNO_SET(str, errcode)  \ 
    …… 
    18088        g_signal_emit_by_name(str, "error");     
    18189 
    182  
    183 extern void mgd_info(const gchar *format, ...); 
     90void mgd_info(const gchar *format, ...); 
    18491 
    18592G_END_DECLS 

  • trunk/midgard/core/midgard/src/midgard_metadata.c

    r16346 r16574  
    184184} 
    185185 
     186/** 
     187 * midgard_metadata_new: 
     188 * @object: #MgdObject for which metadata is created 
     189 *  
     190 * Creates new midgard_metadata instance for the given MgdObject instance. 
     191 * 
     192 * Do not use #g_object_new as metadata constructor. MgdObject pointer is internally  
     193 * assigned as a pointer to midgard object for which particular metadata object  
     194 * instance was created. 
     195 *  
     196 * Midgard Metadata object has two "kinds" of properties. 
     197 * The first one is settable ( and overwritten ) only by metadata implementation. 
     198 * The second one is freely settable by application. In this case midgard core 
     199 * keep value of such property "as is". There is no change or update made for such  
     200 * property even if its value hasn't been changed by application. 
     201 * 
     202 * Do not free MidgardMetadata object's memory as it is automatically 
     203 * freed when particular object's instance memory is freed.  
     204 * 
     205 * Returns: newly allocated midgard_metadata instance 
     206 */  
    186207MidgardMetadata *midgard_metadata_new(MgdObject *object) 
    187208{ 

  • trunk/midgard/core/midgard/src/midgard_metadata.h

    r15473 r16574  
    4848                                    MIDGARD_TYPE_METADATA, MidgardMetadataClass)) 
    4949 
    50 /** 
    51  * \ingroup midgard_metadata 
    52  *  
    53  * Returns the MidgardMetadata  value type.  
    54  * Registers the type as a fundamental GType unless already registered. 
    55  */ 
    5650GType midgard_metadata_get_type (void); 
    5751 
    58 /**  
    59  * \ingroup midgard_metadata 
    60  * 
    61  * Midgard Metadata Class structure. 
    62  * 
    63  */ 
    6452struct MidgardMetadataClass { 
    6553        GObjectClass parent; 
    …… 
    7361}; 
    7462 
    75 /** 
    76  * \ingroup midgard_metadata 
    77  * 
    78  * Private Midgard Metadata structure. 
    79  */ 
    8063typedef struct _MidgardMetadataPrivate MidgardMetadataPrivate; 
    8164 
    82 /** 
    83  * \ingroup midgard_metadata 
    84  * 
    85  * Midgard Metadata object structure. 
    86  */ 
    8765struct MidgardMetadata { 
    88         GObject parent; 
     66        GObject parent;         
    8967        MidgardDBObjectPrivate *dbpriv; 
    9068        MidgardMetadataPrivate *priv; 
    9169}; 
    9270 
    93 /* 
    94  * \ingroup midgard_metadata 
    95  * 
    96  * Creates new midgard_metadata instance for the given MgdObject instance. 
    97  * 
    98  * \param[in] klass MidgardObjectClass pointer 
    99  * 
    100  * \return newly allocated MidgardMetadata object 
    101  * 
    102  * Function g_object_new may be used as well as object's constructor however 
    103  * it's recommended to use this constructor. MgdObject pointer is internally  
    104  * assigned as a pointer to midgard object for which particular metadata object  
    105  * instance was created. 
    106  *  
    107  * Midgard Metadata object has two "kinds" of properties. 
    108  * The first one is settable ( and overwritten ) only by metadata implementation. 
    109  * The second one is freely settable by application. In this case midgard core 
    110  * keep value of such property "as is". There is no change or update made for such  
    111  * property even if its value hasn't been changed by application. 
    112  *  
    113  * Properties of an object: 
    114  * 
    115  * - creator 
    116  *   Holds a string value with midgard_person object guid. 
    117  *   This property can not be overwritten by application.  
    118  *   It is set once when particular schema object's record(s) is created. 
    119  * - created 
    120  *   Holds an ISO date value ( stored in UTC ). 
    121  *   This property can not be overwritten by application.  
    122  *   It is set once when particular schema object's record(s) is created. 
    123  * - revisor 
    124  *   Holds a string value with midgard_person object guid. 
    125  *   This property can not be overwritten by application. 
    126  *   It is set when update method is invoked for particular schema object. 
    127  * - revised 
    128  *   Holds an ISO date value ( stored in UTC ). 
    129  *   This property can not be overwritten by application. 
    130  *   It is set when update method is invoked for particular schema object. 
    131  * - revision 
    132  *   Holds unsigned integer value with revision number. 
    133  *   This property can not be overwritten by application. 
    134  *   It is set ( increased by one ) when update method is invoked for  
    135  *   particular schema object. 
    136  * - locker 
    137  *   Holds a string value with midgard_person object guid. 
    138  *   This property can be set by application. 
    139  * - locked 
    140  *   Holds an ISO date value ( stored in UTC ). 
    141  *   This property can be set by application. 
    142  * - approver 
    143  *   Holds a string value with midgard_person object guid. 
    144  *   This property can be set by application. 
    145  * - approved 
    146  *   Holds an ISO date value ( stored in UTC ). 
    147  *   This property can be set by application. 
    148  * - author 
    149  *   Holds a string value with midgard_person object guid. 
    150  *   This property can be set by application. 
    151  * - owner 
    152  *   Holds a string value with midgard_person object guid. 
    153  *   This property can be set by application. 
    154  * - schedulestart 
    155  *   Holds an ISO date value ( stored in UTC ). 
    156  *   This property can be set by application. 
    157  * - scheduleend 
    158  *   Holds an ISO date value ( stored in UTC ). 
    159  *   This property can be set by application. 
    160  * - hidden 
    161  *   Holds boolean value. 
    162  *   This property can be set by application. 
    163  * - navnoentry 
    164  *   Holds boolean value. 
    165  *   This property can be set by application. 
    166  * - size 
    167  *   Holds unsigned integer value of object's size ( in bytes ). 
    168  *   This property can not be set by application.  
    169  *   Object's size may vary depending on database storage and its optimized 
    170  *   for MySQL database engine now. When object is midgard_attachment type 
    171  *   then size is file size + object's database record size. 
    172  * - published 
    173  *   Holds an ISO date value ( stored in UTC ). 
    174  *   This property can be set by application. 
    175  * 
    176  * There is no need to free MidgardMetadata object's memory as it is automatically 
    177  * freed when particular object's instance memory is freed.  
    178  *   
    179  */  
    18071MidgardMetadata *midgard_metadata_new(MgdObject *object); 
    18172 
    182 /*  
    183  * \ingroup midgard_metadata 
    184  * 
    185  * Returns MidgardObjectClass pointer. 
    186  * 
    187  * \param object MidgardMetadata instance 
    188  * 
    189  * \return MidgardObjectClass which the given MidgardMetadata object was created for. 
    190  * 
    191  */ 
    192 MidgardObjectClass *midgard_metadata_get_class(MidgardMetadata *object); 
    193  
    19473#endif /* MIDGARD_METADATA_H */ 

  • trunk/midgard/core/midgard/src/midgard_object_attachment.h

    r15808 r16574  
    2222G_BEGIN_DECLS 
    2323 
    24 extern MgdObject **midgard_object_list_attachments(MgdObject *self); 
    25  
    26 extern MgdObject *midgard_object_create_attachment(MgdObject *self, 
     24MgdObject **midgard_object_list_attachments(MgdObject *self); 
     25MgdObject *midgard_object_create_attachment(MgdObject *self, 
    2726                const gchar *name, const gchar *title, const gchar *mimetype); 
    28  
    29 extern gboolean midgard_object_delete_attachments(MgdObject *self, 
     27gboolean midgard_object_delete_attachments(MgdObject *self, 
    3028                guint n_params, const GParameter *parameters); 
    31  
    32 extern gboolean midgard_object_purge_attachments(MgdObject *self,  
     29gboolean midgard_object_purge_attachments(MgdObject *self,  
    3330                gboolean delete_blob, guint n_params, const GParameter *parameters); 
    34  
    35 extern MgdObject **midgard_object_find_attachments(MgdObject *self, 
     31MgdObject **midgard_object_find_attachments(MgdObject *self, 
    3632                guint n_params, const GParameter *parameters); 
    37  
    3833G_END_DECLS 
    3934 

  • trunk/midgard/core/midgard/src/midgard_object_class.c

    r15473 r16574  
    11/*  
    2  * Copyright (C) 2005 Piotr Pokora <piotr.pokora@infoglob.pl> 
     2 * Copyright (C) 2005, 2008 Piotr Pokora <piotrek.pokora@gmail.com> 
    33 * 
    44 * This program is free software; you can redistribute it and/or modify it 
    …… 
    1515 * along with this program; if not, write to the Free Software 
    1616 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
    17  *   */ 
     17 */ 
    1818 
    1919#include "midgard_object_class.h" 
    …… 
    3232                _midgard_core_class_get_type_attr(MIDGARD_DBOBJECT_CLASS(__klass)) 
    3333 
    34 /* Returns the name of object's primary property. */ 
    3534const gchar *midgard_object_class_get_primary_property( 
    3635                MidgardObjectClass *klass) 
    …… 
    4241}  
    4342 
    44 /* Returns the name of object's parent property. */   
     43 
     44/** 
     45 * midgard_object_class_get_property_parent: 
     46 * @klass: #MidgardObjectClass 
     47 * 
     48 * Returned string is a pointer to object's parent property, and you should not  
     49 * free it. Parent property is a property which holds value of field which points to  
     50 * parent object's identifier. Parent property always points to object's  
     51 * identifier which is not the same type as given MidgardObjectClass klass. 
     52 * 
     53 * This is static method. 
     54 * NULL is returned if parent property is not found. 
     55 * 
     56 * Returns: the name of object's parent property or %NULL. 
     57 */ 
    4558const gchar *midgard_object_class_get_property_parent( 
    4659                MidgardObjectClass *klass) 
    …… 
    5265} 
    5366 
    54 /* Returns the name of object's up property. */ 
     67 
     68/** 
     69 * midgard_object_class_get_property_up: 
     70 * @klass: #MidgardObjectClass 
     71 *  
     72 * /param klass MidgardObjectClass pointer 
     73 *  
     74 * Returned string is a pointer to object's up property. 
     75 * Up property is a property which holds value of field which points to  
     76 * "upper" object's identifier. Up property always points to object's 
     77 * identifier which is the same type as given MidgardObjectClass klass. 
     78 * 
     79 * This is static method. 
     80 * 
     81 * NULL is returned if up property is not registered for given class. 
     82 * 
     83 * Returns: the name of object's up property or %NULL. 
     84 */ 
    5585const gchar *midgard_object_class_get_property_up( 
    5686                MidgardObjectClass *klass) 
    …… 
    6292} 
    6393 
    64 /* Returns class' lang usage information. */ 
     94 
     95/** 
     96 * midgard_object_class_is_multilang: 
     97 * @klass: MidgardObjectClass 
     98 *  
     99 * Checks whether given MidgardObjectClass is multilingual. 
     100 * 
     101 * This is static method. 
     102 *  
     103 * Returns: %TRUE if MidgardObjectClass is mutlilingual, %FALSE otherwise. 
     104 */ 
    65105gboolean midgard_object_class_is_multilang( 
    66106                MidgardObjectClass *klass) 
    …… 
    75115} 
    76116 
    77 /* Returns children ( in tree ) classes' pointers */ 
     117/** 
     118 * midgard_object_class_list_children: 
     119 * @klass: MidgardObjectClass 
     120 * 
     121 * Returns newly allocated and NULL terminated children ( in midgard tree ) classes' pointers .  
     122 * Returned array should be freed if no longer needed without freeing array's elements.  
     123 * Elements are static pointers owned by GLib. 
     124 * 
     125 * This is static method. 
     126 * 
     127 * Returns: array of childreen ( in midgard tree ) classes of the given MidgardObjectClass. 
     128 */ 
    78129MidgardObjectClass **midgard_object_class_list_children( 
    79130                        MidgardObjectClass *klass) 
    …… 
    102153} 
    103154 
    104 /* Returns Midgard Object identified by guid */ 
     155/** 
     156 * midgard_object_class_get_object_by_guid: 
     157 * @mgd: #MidgardConnection handler  
     158 * @guid: guid string which should identify an object 
     159 * 
     160 * #MidgardError set by this function: 
     161 *   - MGD_ERR_NOT_EXISTS: object is not found 
     162 *   - MGD_ERR_OBJECT_DELETED: object is already deleted 
     163 *   - MGD_ERR_OBJECT_PURGED: object is purged 
     164 *   - MGD_ERR_SITEGROUP_VIOLATION if more than one record exists  
     165 * 
     166 * This is static method. 
     167 * 
     168 * Returns: #MgdObject object identified by given @guid 
     169 */ 
    105170MgdObject *midgard_object_class_get_object_by_guid (    MidgardConnection *mgd, 
    106171                                                        const gchar *guid) 
    …… 
    249314} 
    250315 
     316/**  
     317 * midgard_object_class_get_object_by_path: 
     318 * @mgd: #MidgardConnection holder 
     319 * @classname: name of the class for which object should be returned 
     320 * @object_path: a path, at which object should be found 
     321 * 
     322 * This is static method. 
     323 * 
     324 * Cases to set NULL: 
     325 *  - object is not found by path 
     326 *  - object's class has neither name nor id member 
     327 *  - object's class doesn't have both: parent and up property 
     328 * 
     329 * MidgardError set by this method: 
     330 *  - MGD_ERR_INTERNAL  
     331 *  - MGD_ERR_NOT_EXISTS 
     332 *  
     333 * Returns: #MgdObject instance of @classname or %NULL if object is not found 
     334 */ 
    251335MgdObject *midgard_object_class_get_object_by_path(MidgardConnection *mgd, 
    252336                const gchar *classname, const gchar *object_path) 
    …… 
    382466} 
    383467 
     468/** 
     469 * midgard_object_class_undelete: 
     470 * @mgd: MidgardConnection object 
     471 * @guid: string which should identify object 
     472 * 
     473 * Undelete midgard object identified by given @guid 
     474 * 
     475 * MidgardError set by this method: 
     476 *  - MGD_ERR_NOT_EXISTS 
     477 *  - MGD_ERR_OBJECT_PURGED 
     478 *  - MGD_ERR_INTERNAL 
     479 * 
     480 * Returns: %TRUE on success, %FALSE otherwise 
     481 */ 
    384482gboolean midgard_object_class_undelete(MidgardConnection *mgd, const gchar *guid) 
    385483{ 

  • trunk/midgard/core/midgard/src/midgard_object_class.h

    r15473 r16574  
    11/*  
    2  * Copyright (C) 2005 Piotr Pokora <piotr.pokora@infoglob.pl> 
     2 * Copyright (C) 2005, 2008 Piotr Pokora <piotrek.pokora@gmail.com> 
    33 * 
    44 * This program is free software; you can redistribute it and/or modify it 
    …… 
    3232#include "midgard_object.h" 
    3333 
    34 /* 
    35  * \ingroup moc 
    36  * 
    37  * Returns the name of object's primary property. 
    38  * 
    39  * This is static method. 
    40  *  
    41  * /param klass MidgardObjectClass pointer 
    42  *   
    43  * /return primary property name 
    44  *  
    45  * Returned string is a pointer to object's primary property. 
    46  * By default , 'guid' property is primary property which uniquely identifies 
    47  * object's record and object itself. However in some circumstances ( like  
    48  * backward compatibility ) id property can be defined as primary property. 
    49  * 
    50  * You should not use this function.   
    51  * 
    52  */            
    53 extern const gchar *midgard_object_class_get_primary_property(MidgardObjectClass *klass);  
    54  
    55 /* 
    56  * \ingroup moc 
    57  * 
    58  * Returns the name of object's parent property. 
    59  * 
    60  * This is static method. 
    61  *   
    62  * /param klass MidgardObjectClass pointer 
    63  * 
    64  * /return parent property name 
    65  *  
    66  * Returned string is a pointer to object's parent property. 
    67  * Parent property is a property which holds value of field which points to  
    68  * parent object's identifier. Parent property always points to object's  
    69  * identifier which is not the same type as given MidgardObjectClass klass. 
    70  * 
    71  * NULL is returned if parent property is not found. 
    72  */ 
    73 extern const gchar *midgard_object_class_get_property_parent(MidgardObjectClass *klass); 
    74  
    75 /* 
    76  * \ingroup moc 
    77  * 
    78  * Returns the name of object's up property. 
    79  * 
    80  * This is static method. 
    81  *  
    82  * /param klass MidgardObjectClass pointer 
    83  *  
    84  * /return up property name 
    85  *  
    86  * Returned string is a pointer to object's up property. 
    87  * Up property is a property which holds value of field which points to  
    88  * "upper" object's identifier. Up property always points to object's 
    89  * dentifier which is the same type as given MidgardObjectClass klass. 
    90  * 
    91  * NULL is returned if up property is not found. 
    92  * 
    93  */ 
    94 extern const gchar *midgard_object_class_get_property_up(MidgardObjectClass *klass); 
    95  
    96 /** 
    97  * \ingruop moc 
    98  * 
    99  * Returns array of childreen tree classes for the given MidgardObjectClass. 
    100  * 
    101  * This is static method. 
    102  * 
    103  * \param klass , MidgardObjectClass pointer 
    104  * 
    105  * Returns newly allocated children tree classes' pointers.  
    106  * NULL is added as the last array element.  
    107  * Returned array should be freed if no longer needed without freeing array's elements.  
    108  * ( Use g_free instead of g_strfreev ) 
    109  */ 
    110 extern MidgardObjectClass **midgard_object_class_list_children( 
     34const gchar *midgard_object_class_get_primary_property(MidgardObjectClass *klass);  
     35const gchar *midgard_object_class_get_property_parent(MidgardObjectClass *klass); 
     36const gchar *midgard_object_class_get_property_up(MidgardObjectClass *klass); 
     37MidgardObjectClass **midgard_object_class_list_children( 
    11138        MidgardObjectClass *klass); 
    112  
    113 /** 
    114  * \ingroup moc 
    115  *  
    116  * Checks whether given MidgardObjectClass is multilingual. 
    117  * 
    118  * This is static method. 
    119  *  
    120  * \param[in] object MidgardObjectClass 
    121  *  
    122  * \return TRUE if MidgardObjectClass is mutlilingual, FALSE otherwise. 
    123  */ 
    124 extern gboolean midgard_object_class_is_multilang(MidgardObjectClass *klass); 
    125  
    126 /** 
    127  * \ingruop moc 
    128  * 
    129  * Returns Midgard Object identified by guid 
    130  * 
    131  * This is static method. 
    132  * 
    133  * \param mgd, MidgardConnection object 
    134  * \param guid, guid string which identifies object 
    135  *  
    136  * \return MgdObject or NULL 
    137  * 
    138  * MidgardError set by this function: 
    139  *   - MGD_ERR_NOT_EXISTS if object is not found 
    140  *   - MGD_ERR_OBJECT_DELETED is object is already deleted 
    141  *   - MGD_ERR_OBJECT_PURGED is object is purged 
    142  *   - MGD_ERR_SITEGROUP_VIOLATION if more than one record exists  
    143  * 
    144  *   MGD_ERR_SITEGROUP_VIOLATION is returned if function is invoked by root 
    145  *   user and additional sitegroup constraint has been not defined. 
    146  * 
    147  */ 
    148 extern MgdObject *midgard_object_class_get_object_by_guid( 
     39gboolean midgard_object_class_is_multilang(MidgardObjectClass *klass); 
     40MgdObject *midgard_object_class_get_object_by_guid( 
    14941                        MidgardConnection *mgd, const gchar *guid); 
    150  
    151 /**  
    152  * \ingroup moc 
    153  * 
    154  * Get Midgard Object for the given path. 
    155  * 
    156  * This is static method. 
    157  * 
    158  * \param mgd, MidgardConnection object 
    159  * \param classname, name of the class for which object should be returned 
    160  * \param object_path, a path where object should be found 
    161  * 
    162  * \return MgdObject's /c classname instance or NULL if object is not found 
    163  * 
    164  * Cases to set NULL: 
    165  *  - object is not found by path 
    166  *  - object's class has no name or id member 
    167  *  - object's class has no parent and up property 
    168  * 
    169  * MidgardError set by this method: 
    170  *  - MGD_ERR_INTERNAL  
    171  */ 
    172 extern MgdObject *midgard_object_class_get_object_by_path(MidgardConnection *mgd, 
     42MgdObject *midgard_object_class_get_object_by_path(MidgardConnection *mgd, 
    17343                const gchar *classname, const gchar *object_path); 
    174  
    175 /** 
    176  * \ingroup moc 
    177  * 
    178  * Undelete midgard object identified by given guid 
    179  * 
    180  * \param mgd, MidgardConnection object 
    181  * \param guid, string which identifies object 
    182  * 
    183  * \return TRUE on success, FALSE otherwise 
    184  * 
    185  * MidgardError set by this method: 
    186  *  - MGD_ERR_NOT_EXISTS 
    187  *  - MGD_ERR_OBJECT_PURGED 
    188  *  - MGD_ERR_INTERNAL 
    189  */ 
    190 extern gboolean midgard_object_class_undelete(MidgardConnection *mgd, const gchar *guid);