Changeset 22768

Show
Ignore:
Timestamp:
07/02/09 12:56:35 (1 year ago)
Author:
piotras
Message:

Query Builder docs ported from Doxygen to gtk-doc

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/midgard/core/midgard/doc/C/tmpl/midgard-2.0-unused.sgml

    r22602 r22768  
    821821@Returns:  
    822822 
     823<!-- ##### FUNCTION midgard_query_builder_free ##### --> 
     824<para> 
     825 
     826</para> 
     827 
     828@builder:  
     829 
     830<!-- ##### FUNCTION midgard_query_builder_get_guid ##### --> 
     831<para> 
     832 
     833</para> 
     834 
     835@builder:  
     836@Returns:  
     837 
     838<!-- ##### FUNCTION midgard_query_builder_join ##### --> 
     839<para> 
     840 
     841</para> 
     842 
     843@builder:  
     844@prop:  
     845@jobject:  
     846@jprop:  
     847@Returns:  
     848 
    823849<!-- ##### TYPEDEF midgard_storage ##### --> 
    824850<para> 

  • trunk/midgard/core/midgard/doc/C/tmpl/query_builder.sgml

    r21849 r22768  
    77<!-- ##### SECTION Long_Description ##### --> 
    88<para> 
    9  
     9The #MidgardQueryBuilder allows an application to construct and execute 
     10queries against any database, which Midgard is connected to.   
     11</para> 
     12 
     13<para> 
     14Main #MidgardQueryBuilder conveniences: 
     15<itemizedlist> 
     16<listitem><para> 
     17It doesn't require any SQL  
     18</para></listitem> 
     19<listitem><para> 
     20Object properties are used as query constraints 
     21</para></listitem> 
     22<listitem><para> 
     23Objects' array is returned instead of raw records 
     24</para></listitem> 
     25</itemizedlist> 
     26</para> 
     27 
     28<para> 
     29The main steps of using the query builder are: 
     30<itemizedlist> 
     31<listitem><para> 
     32create a query builder instance, midgard_query_builder_new() 
     33</para></listitem> 
     34<listitem><para> 
     35add constraints and other options to the query, midgard_query_builder_add_constraint() 
     36</para></listitem> 
     37<listitem><para> 
     38execute the query, midgard_query_builder_execute() 
     39</para></listitem> 
     40</itemizedlist> 
     41</para> 
     42 
     43<para> 
     44Each query is represented by an instance of the #MidgardQueryBuilderClass class. 
     45The #MidgardQueryBuilder methods can be used to manipulate  the queries. 
    1046</para> 
    1147 
    …… 
    74110 
    75111 
    76 <!-- ##### FUNCTION midgard_query_builder_free ##### --> 
    77 <para> 
    78  
    79 </para> 
    80  
    81 @builder:  
    82  
    83  
    84112<!-- ##### FUNCTION midgard_query_builder_set_lang ##### --> 
    85113<para> 
    …… 
    190218 
    191219 
    192 <!-- ##### FUNCTION midgard_query_builder_join ##### --> 
    193 <para> 
    194  
    195 </para> 
    196  
    197 @builder:  
    198 @prop:  
    199 @jobject:  
    200 @jprop:  
    201 @Returns:  
    202  
    203  
    204 <!-- ##### FUNCTION midgard_query_builder_get_guid ##### --> 
    205 <para> 
    206  
    207 </para> 
    208  
    209 @builder:  
    210 @Returns:  
    211  
    212  
    213220<!-- ##### FUNCTION midgard_query_builder_get_type_name ##### --> 
    214221<para> 

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

    r22615 r22768  
    11/* 
    22 * Copyright (c) 2005 Jukka Zitting <jz@yukatan.fi> 
    3  * Copyright (c) 2005,2007 Piotr Pokora <piotr.pokora@infoglob.pl> 
     3 * Copyright (c) 2005, 2007, 2009 Piotr Pokora <piotrek.pokora@gmail.com> 
    44 * 
    55 * This program is free software; you can redistribute it and/or modify it 
    …… 
    8686} 
    8787 
     88/** 
     89 * midgard_query_builder_new(): 
     90 * @mgd: #MidgardConnection instance 
     91 * @classname: any #MidgardDBObjectClass derived class' name 
     92 * 
     93 * Returns: new #MidgardQueryBuilder instance or %NULL if target class is not registered in GType system  
     94 * or it's not #MidgardDBObjectClass class derived one. 
     95 */ 
    8896MidgardQueryBuilder *midgard_query_builder_new( 
    8997        MidgardConnection *mgd, const gchar *classname) 
    …… 
    153161} 
    154162 
     163/** 
     164 * midgard_query_builder_add_constraint(): 
     165 * @builder: #MidgardQueryBuilder instance 
     166 * @name: property name used for this constraint  
     167 * @op: comparison operator 
     168 * @value: value used in comparison 
     169 * 
     170 * Adds a constraint to the given query builder. The constraint is 
     171 * expressed as a triple of a field name, a comparison operator, and 
     172 * a comparison value.  
     173 *  
     174 * <para> 
     175 * @name referes to a property of the queried Midgard object class.  
     176 * For example: #MidgardQueryBuilder has been initialized for person  
     177 * class which has lastname property registered. 
     178 * <example> 
     179 * <programlisting> 
     180 *  
     181 * GValue value = {0, }; 
     182 * g_value_init(&value, G_TYPE_STRING); 
     183 * g_value_set_string(&value, "smith"); 
     184 * 
     185 * midgard_query_builder_add_constraint(builder, "lastname", "=", &value); 
     186 *  
     187 * </programlisting> 
     188 * </example> 
     189 * </para> 
     190 * <para> 
     191 * It also can be name of the linked class property or reserved one.  
     192 * A dot '.' is used to separate properties for special constraints. 
     193 * If such special constraint property is used, #MidgardQueryBuilder 
     194 * performs right join. 
     195 * <itemizedlist> 
     196 * <listitem><para> 
     197 * First property is the one registered for given class which is a link 
     198 * to property of different class. Second is a property of target class. 
     199 * For example: person object has property 'friend' which holds some identifier 
     200 * (id or guid) to friend class property, and friend class has property 'nick'. 
     201 * In such case we can use constraint and comparison using friend property, 
     202 * even if #MidgardQueryBuilder has been initialized for person class. 
     203 * <example> 
     204 * <programlisting> 
     205 *  
     206 * GValue value = {0, }; 
     207 * g_value_init(&value, G_TYPE_STRING); 
     208 * g_value_set_string(&value, "Lancelot"); 
     209 * 
     210 * midgard_query_builder_add_constraint(builder, "friend.nick", "=", &value); 
     211 * 
     212 * </programlisting> 
     213 * </example> 
     214 * </para></listitem> 
     215 * <listitem><para> 
     216 * There are three reserved words which have special meaning for query builder. 
     217 * 'metadata', 'parameter' and 'attachment'. If one of them is used, query builder 
     218 * will make (if necessary) right join and query objects against dependent class table. 
     219 * <example> 
     220 * <programlisting> 
     221 *  
     222 * GValue value = {0, }; 
     223 * g_value_init(&value, G_TYPE_STRING); 
     224 * g_value_set_string(&value, "avatar"); 
     225 * 
     226 * midgard_query_builder_add_constraint(builder, "attachment.name", "=", &value); 
     227 * 
     228 * </programlisting> 
     229 * </example> 
     230 * </para></listitem> 
     231 * </itemizedlist> 
     232 * </para> 
     233 * 
     234 * <para> 
     235 * The comparison operator is a string representation of the requested comparison.  
     236 * Available operators are =, <>, <, >, <=, >=, LIKE, NOT LIKE, IN, INTREE.  
     237 * </para> 
     238 *  
     239 * <para> 
     240 * The given @value is copied and converted into the property type before comparison. 
     241 * </para> 
     242 *   
     243 * Returns: %TRUE if constraint is valid, %FALSE otherwise 
     244 */ 
    155245gboolean midgard_query_builder_add_constraint( 
    156246        MidgardQueryBuilder *builder, 
    …… 
    194284} 
    195285 
     286/** 
     287 * midgard_query_builder_add_constraint_with_property: 
     288 * @builder: #MidgardQueryBuilder instance 
     289 * @property_a: property name 
     290 * @op: comparison operator 
     291 * @property_b: property name 
     292 * 
     293 * Adds named property constraint to the given query builder. 
     294 * Unlike add_constraint method, this one accepts property name 
     295 * instead of scalar value. The difference is that with add_constraint 
     296 * method you can compare property with particular value, while using  
     297 * add_constraint_with_property method you can compare two different  
     298 * properties without any need to know their values.  
     299 * For example, you should use this method if you want to select only  
     300 * those objects which has been revised after publication time, and particular  
     301 * date doesn't matter. 
     302 * 
     303 * <example> 
     304 * <programlisting> 
     305 *  
     306 * midgard_query_builder_add_constraint_with_property(builder, "metadata.revised", ">", "metadata.published"); 
     307 * 
     308 * </programlisting> 
     309 * </example> 
     310 * 
     311 * @See: midgard_query_builder_add_constraint() 
     312 * 
     313 * Returns: %TRUE if properties' names are valid, %FALSE otherwise 
     314 */  
    196315gboolean midgard_query_builder_add_constraint_with_property( 
    197316                MidgardQueryBuilder *builder, const gchar *property_a, 
    …… 
    236355} 
    237356 
    238 gboolean midgard_query_builder_begin_group( 
    239                 MidgardQueryBuilder *builder, const gchar *type)  
     357/** 
     358 * midgard_query_builder_begin_group: 
     359 * @builder: #MidgardQueryBuilder instance 
     360 * @type: group type 
     361 * 
     362 * Starts a constraint group of the given type. A conjunctive constraint 
     363 * group @type (AND) requires that all component constraints match the 
     364 * queried objects, while a disjunctive group @type (OR) requires just 
     365 * one of the component constraints to match. 
     366 * 
     367 * Allowed group @type: 'AND' or 'OR' 
     368 * 
     369 * Returns: %TRUE if the @type is valid, %FALSE otherwise 
     370 */ 
     371gboolean  
     372midgard_query_builder_begin_group(MidgardQueryBuilder *builder, const gchar *type)  
    240373{ 
    241374        g_assert(builder != NULL); 
    …… 
    272405} 
    273406 
    274 gboolean midgard_query_builder_end_group(MidgardQueryBuilder *builder)  
     407/** 
     408 * midgard_query_builder_end_group: 
     409 * @builder: #MidgardQueryBuilder instance 
     410 *  
     411 * Closes the most recently opened constraint group. The client should 
     412 * ensure proper nesting by closing all constraint groups before the 
     413 * containing query is executed. 
     414 * 
     415 * Returns: %TRUE if a constraint group was closed, or %FALSE if no 
     416 * open constraint groups were found 
     417 * 
     418 */ 
     419gboolean  
     420midgard_query_builder_end_group (MidgardQueryBuilder *builder)  
    275421{ 
    276422        g_assert(builder != NULL); 
    …… 
    301447} 
    302448 
    303 gboolean midgard_query_builder_add_order( 
    304         MidgardQueryBuilder *builder, const gchar *name, const gchar *dir) 
     449/** 
     450 * midgard_query_builder_add_order: 
     451 * @builder: #MidgardQueryBuilder instance 
     452 * @name: property name 
     453 * @dir: sort direction 
     454 * 
     455 * Adds an ordering constraint to the query. An ordering constraint consists 
     456 * of a property name and a sort direction. The objects returned by this 
     457 * query will be sorted by the given property in the given direction 
     458 * (ascending or descending). Multiple ordering constraints are applied in 
     459 * the order they were added. 
     460 * 
     461 * Allowed sort directions: 'ASC' or 'DESC' 
     462 *  
     463 * Property name pattern is described in midgard_query_builder_add_constraint() 
     464 *  
     465 * Returns: %TRUE if the ordering constraint is valid, %FALSE otherwise 
     466 * 
     467 */ 
     468gboolean  
     469midgard_query_builder_add_order (MidgardQueryBuilder *builder, const gchar *name, const gchar *dir) 
    305470{ 
    306471        g_assert(builder != NULL); 
    …… 
    322487} 
    323488 
    324 void midgard_query_builder_set_limit( 
    325         MidgardQueryBuilder *builder, guint limit) 
     489/** 
     490 * midgard_query_builder_set_limit: 
     491 * @builder: #MidgardQueryBuilder instance 
     492 * @limit: query limit 
     493 *  
     494 * Sets the maximum number of objects to return when the query is executed. 
     495 * A query will by default return all matching objects, but the @limit setting 
     496 * can be used to restrict the potentially large number of returned objects. 
     497 * The @limit is applied only after the matching objects have been identified 
     498 * and sorted and after the optional start offset has been applied. 
     499 * 
     500 * Setting a @limit on the number of returned objects is normally only 
     501 * reasonable when one or more ordering constraints and optionally an offset 
     502 * setting are applied to the query.  
     503 * 
     504 * @See: midgard_query_builder_set_offset() 
     505 */ 
     506void  
     507midgard_query_builder_set_limit (MidgardQueryBuilder *builder, guint limit) 
    326508{ 
    327509        g_assert(builder != NULL); 
    …… 
    330512} 
    331513 
    332 void midgard_query_builder_set_offset( 
    333         MidgardQueryBuilder *builder, guint offset) 
     514/** 
     515 * midgard_query_builder_set_offset: 
     516 * @builder: #MidgardQueryBuilder instance 
     517 * @offset: query offset 
     518 * 
     519 * Sets the start @offset of the objects to return when the query is executed. 
     520 * The start @offset is applied after all the matching objects have been 
     521 * identified and sorted according to the given ordering constraints. The 
     522 * first @offset objects are skipped and only the remaining (if any) objects 
     523 * are returned to the client. 
     524 * 
     525 * Setting a start offset is normally only reasonable when one or more 
     526 * ordering constraints are applied to the query. A start offset is usually 
     527 * accompanied by a limit setting. 
     528 *  
     529 * @See: midgard_query_builder_set_offset() 
     530 */ 
     531void  
     532midgard_query_builder_set_offset (MidgardQueryBuilder *builder, guint offset) 
    334533{ 
    335534        g_assert(builder != NULL); 
    …… 
    338537} 
    339538 
    340 void midgard_query_builder_set_lang(MidgardQueryBuilder *builder, gint lang) 
     539/** 
     540 * midgard_query_builder_set_lang: 
     541 * @builder: #MidgardQueryBuilder instance 
     542 * @lang: language id 
     543 * 
     544 * Sets #MidgardQueryBuilder language.  
     545 * If one is set, global Midgard language context is ignored. 
     546 * 
     547 */  
     548void  
     549midgard_query_builder_set_lang (MidgardQueryBuilder *builder, gint lang) 
    341550{ 
    342551        g_assert(builder != NULL); 
    …… 
    345554} 
    346555 
    347 void midgard_query_builder_unset_languages(MidgardQueryBuilder *builder) 
     556/** 
     557 * midgard_query_builder_unset_languages: 
     558 * @builder: #MidgardQueryBuilder instance 
     559 *  
     560 * Unset all languages used by given Query Builder instance. 
     561 * 
     562 * All languages ( current and default one ) are unset for QB instance. 
     563 * SQL query is executed without language context. 
     564 */ 
     565void  
     566midgard_query_builder_unset_languages (MidgardQueryBuilder *builder) 
    348567{ 
    349568        g_assert(builder); 
    …… 
    415634} 
    416635 
     636/** 
     637 * midgard_query_builder_execute: 
     638 * @builder: #MidgardQueryBuilder instance 
     639 * @n_objects: a pointer to store number of returned objects 
     640 *  
     641 * Executes the built query. 
     642 *  
     643 * Objects in returned array are #MidgardDBObject derived ones, 
     644 * and typecasted to base GObject. You can safely typecast them to  
     645 * the type, which #MidgardQueryBuilder has been initialized for. 
     646 *  
     647 * In case of any error, #MidgardConnection error is set. 
     648 *  
     649 * Returns: NULL terminated array of objects, or NULL if none found 
     650 */   
    417651GObject **midgard_query_builder_execute( 
    418652        MidgardQueryBuilder *builder, guint *n_objects) 
    …… 
    452686} 
    453687 
    454 guint midgard_query_builder_count(MidgardQueryBuilder *builder) 
     688/**  
     689 * midgard_query_builder_count: 
     690 * @builder: #MidgardQueryBuilder instance 
     691 * 
     692 * Returns the number of objects that this query would return when executed 
     693 * without limit or start offset settings. 
     694 * 
     695 * Returns: number of object matched by this query 
     696 */ 
     697guint  
     698midgard_query_builder_count (MidgardQueryBuilder *builder) 
    455699{ 
    456700        g_assert(builder != NULL); 
    …… 
    477721        return elements; 
    478722} 
    479  
    480 GList *midgard_query_builder_get_guid( 
    481                 MidgardQueryBuilder *builder) 
    482 { 
    483         g_assert(builder != NULL); 
    484          
    485         GList *list =  
    486                 midgard_query_builder_execute_or_count(builder, NULL, MQB_SELECT_GUID); 
    487          
    488         return list;     
    489 } 
    490  
    491723 
    492724gchar *midgard_query_builder_get_object_select( 
    …… 
    9291161        return list;     
    9301162} 
    931  
    932 gboolean midgard_query_builder_join( 
    933                 MidgardQueryBuilder *builder, const gchar *prop,  
    934                 const gchar *jobject, const gchar *jprop) 
    935 { 
    936         g_assert(prop != NULL); 
    937         g_assert(jobject != NULL); 
    938         g_assert(jprop != NULL); 
    939  
    940         g_warning("FIXME"); 
    941 } 
    942  
    9431163  
    944 /* Returns type name of the type which is currently used by Query Builder. */ 
    945 const gchar *midgard_query_builder_get_type_name( 
    946                 MidgardQueryBuilder *builder) 
     1164/** 
     1165 * midgard_query_builder_get_type_name: 
     1166 * @builder: #MidgardQueryBuilder instance 
     1167 *  
     1168 * Returns type name of the type which is currently used by Query Builder. 
     1169 *  
     1170 * This function should be used on language binding level , when internal 
     1171 * Query Builder's instance is already created and language binding object  
     1172 * should be instanciated. 
     1173 * 
     1174 * Returned type name is a pointer and is owned by GLib system. 
     1175 * Caller shouldn't free it. 
     1176 * 
     1177 * Returns: name of the class, which query builder is initialized for. 
     1178 */  
     1179const gchar* 
     1180midgard_query_builder_get_type_name (MidgardQueryBuilder *builder) 
    9471181{ 
    9481182        g_assert(builder != NULL); 
    …… 
    9501184} 
    9511185 
    952 void midgard_query_builder_include_deleted(MidgardQueryBuilder *builder) 
     1186/** 
     1187 * midgard_query_builder_include_deleted: 
     1188 * @builder: #MidgardQueryBuilder instance 
     1189 *  
     1190 * Query all objects, deleted and undeleted.  
     1191 */  
     1192void  
     1193midgard_query_builder_include_deleted (MidgardQueryBuilder *builder) 
    9531194{ 
    9541195        g_assert(builder); 

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

    r21400 r22768  
    11/* 
    22 * Copyright (c) 2005 Jukka Zitting <jz@yukatan.fi> 
    3  * Copyright (c) 2005 Piotr Pokora <piotr.pokora@infoglob.pl> 
     3 * Copyright (c) 2005, 2009 Piotr Pokora <piotrek.pokora@gmail.com> 
    44 * 
    55 * This program is free software; you can redistribute it and/or modify it 
    …… 
    2121#define MIDGARD_QUERY_BUILDER_H 
    2222 
    23 /** 
    24  * \defgroup qb Midgard Query Builder 
    25  * 
    26  * The Midgard Query Builder allows an application to construct and execute 
    27  * queries against the Midgard database. The main steps of using the query 
    28  * builder are: 
    29  * 
    30  * \li create a query builder instance 
    31  * \li add constraints and other options to the query 
    32  * \li execute the query 
    33  * 
    34  * Each query is represented by an instance of the opaque MidgardQueryBuilder 
    35  * structure. The \c midgard_query_builder functions can be used to manipulate 
    36  * the queries. 
    37  */ 
    38  
    3923#include "midgard_connection.h" 
    4024 
    …… 
    5236        (G_TYPE_INSTANCE_GET_CLASS ((obj), MIDGARD_TYPE_QUERY_BUILDER, MidgardQueryBuilderClass)) 
    5337 
    54 /** 
    55  * \ingroup qb 
    56  * The opaque Midgard Query Builder type. Instances are used to track 
    57  * the state of a query builder. 
    58  */ 
    5938typedef struct _MidgardQueryBuilder MidgardQueryBuilder; 
    6039typedef struct _MidgardQueryBuilder midgard_query_builder; 
    …… 
    6746}; 
    6847 
    69 /** 
    70  * \ingroup qb 
    71  * The opaque Midgard Query Builder class. 
    72  */  
    7348typedef struct MidgardQueryBuilderClass MidgardQueryBuilderClass; 
    7449 
    75 /**  
    76  * \ingroup qb 
    77  * The class structure for Midgard Query Builder class. 
    78  */ 
    7950struct MidgardQueryBuilderClass{ 
    8051        GObjectClass parent; 
    8152 
    82         void (*set_lang) ( 
    83                 MidgardQueryBuilder *builder, gint lang); 
    84  
    85         void (*unset_languages) ( 
    86                 MidgardQueryBuilder *builder); 
    87          
    88         gboolean (*add_constraint) ( 
    89                 MidgardQueryBuilder *builder, 
    90                 const gchar *name, const gchar *op, const GValue *value); 
    91          
    92         gboolean (*add_constraint_with_property) ( 
    93                 MidgardQueryBuilder *builder, 
    94                 const gchar *property_a, const gchar *op, const gchar *property_b); 
    95  
    96         gboolean (*begin_group) ( 
    97                 MidgardQueryBuilder *builder, const gchar *type); 
    98  
    99         gboolean (*end_group) ( 
    100                 MidgardQueryBuilder *builder); 
    101  
    102         gboolean (*add_order) ( 
    103                 MidgardQueryBuilder *builder,  
    104                 const gchar *name, const gchar *dir); 
    105  
    106         void (*set_offset) ( 
    107                 MidgardQueryBuilder *builder, guint offset); 
    108  
    109         void (*set_limit) ( 
    110                 MidgardQueryBuilder *builder, guint limit); 
    111  
    112         void (*include_deleted) ( 
    113                 MidgardQueryBuilder *builder); 
    114  
    115         GObject **(*execute) ( 
    116                 MidgardQueryBuilder *builder, guint *n_objects); 
    117  
    118         guint (*count) ( 
    119                 MidgardQueryBuilder *builder); 
     53        void            (*set_lang)             (MidgardQueryBuilder *builder, gint lang); 
     54        void            (*unset_languages)      (MidgardQueryBuilder *builder); 
     55        gboolean        (*add_constraint)       (MidgardQueryBuilder *builder, const gchar *name, const gchar *op, const GValue *value); 
     56        gboolean        (*add_constraint_with_property) (MidgardQueryBuilder *builder, const gchar *property_a, const gchar *op, const gchar *property_b); 
     57        gboolean        (*begin_group)          (MidgardQueryBuilder *builder, const gchar *type); 
     58        gboolean        (*end_group)            (MidgardQueryBuilder *builder); 
     59        gboolean        (*add_order)            (MidgardQueryBuilder *builder, const gchar *name, const gchar *dir); 
     60        void            (*set_offset)           (MidgardQueryBuilder *builder, guint offset); 
     61        void            (*set_limit)            (MidgardQueryBuilder *builder, guint limit); 
     62        void            (*include_deleted)      (MidgardQueryBuilder *builder); 
     63        GObject         **(*execute)            (MidgardQueryBuilder *builder, guint *n_objects); 
     64        guint           (*count)                (MidgardQueryBuilder *builder); 
    12065}; 
    12166 
    122 /** 
    123  * \ingroup qb 
    124  * 
    125  * Returns MidgardQueryBuilder type. 
    126  * Registers the type as  a fundamental GType unless already registered. 
    127  */ 
    128 extern GType midgard_query_builder_get_type(void); 
    129  
    130 /** 
    131  * \ingroup qb 
    132  * Creates a new query builder for the given Midgard connection and 
    133  * MgdSchema class. Returns \c NULL if the named MgdSchema class is not found. 
    134  * 
    135  * \param     mgd       Midgard connection 
    136  * \param[in] classname MgdSchema class name 
    137  * \return query builder, or \c NULL if the named class is not found 
    138  */ 
    139 extern MidgardQueryBuilder *midgard_query_builder_new( 
    140         MidgardConnection *mgd, const gchar *classname); 
    141  
    142 /** 
    143  * \ingroup qb 
    144  * Releases the given query builder and all associated resources. 
    145  * 
    146  * \param builder query builder 
    147  */ 
    148 extern void midgard_query_builder_free(MidgardQueryBuilder *builder); 
    149  
    150 /** 
    151  * \ingroup qb 
    152  * Sets internal lang used by Query Builder. 
    153  *  
    154  * \param     builder query builder 
    155  * \param[in] lang    Sets object's lang 
    156  * 
    157  * SQL query used by Query Builder will use set language explicitly. 
    158  * Objects in other languages will be not queried from database. 
    159  */ 
    160 extern void midgard_query_builder_set_lang( 
    161         MidgardQueryBuilder *builder, gint lang); 
    162  
    163 /** 
    164  * \ingroup qb 
    165  * 
    166  * Unset all languages used by given Query Builder instance. 
    167  * 
    168  * \param builder MidgardQueryBuidler instance. 
    169  * 
    170  * All languages ( current and default one ) are unset for QB instance. 
    171  * SQL query is executed without language context. 
    172  */ 
    173 extern void midgard_query_builder_unset_languages( 
    174         MidgardQueryBuilder *builder); 
    175  
    176 /** 
    177  * \ingroup qb 
    178  * Adds a constraint to the given query builder. The constraint is 
    179  * expressed as a triple of a field name, a comparison operator, and 
    180  * a scalar comparison value. The field name referes to a property of 
    181  * the queried Midgard object class. The comparison operator is a 
    182  * string representation of the requested comparison. Available operators 
    183  * are =, <>, <, >, <=, >=, and LIKE. The given scalar value is copied and 
    184  * converted into the property type before comparison. 
    185  * 
    186  * This method returns \c TRUE if the given constraint is valid (refers to 
    187  * a valid field, uses a valid operator, and contains a valid value). 
    188  * Otherwise this method returns \c FALSE and does not change the state 
    189  * of the query builder. 
    190  * 
    191  * \param     builder query builder 
    192  * \param[in] name    name of the field used for the constraint 
    193  * \param[in] op      comparison operator 
    194  * \param[in] value   scalar value used in comparison 
    195  * \return \c TRUE if the constraint is valid, \c FALSE otherwise 
    196  */ 
    197 extern gboolean midgard_query_builder_add_constraint( 
    198         MidgardQueryBuilder *builder, 
    199         const gchar *name, const gchar *op, const GValue *value); 
    200  
    201 /** 
    202  * \ingroup qb 
    203  * 
    204  * Adds named property constraint to the given query builder. 
    205  * Unlike add_constraint method, this one accepts property name 
    206  * instead of scalar value. The difference is that with add_constraint 
    207  * method you can compare property with particular value, while using  
    208  * add_constraint_with_property method you can compare two different  
    209  * properties without need to know their values.  
    210  * For example, you should use this method if you want to select only  
    211  * those objects which has been revised after publication time, and particular  
    212  * date doesn't matter: (metadata.revised > metadata.published). 
    213  *  
    214  * \param builder, MidgardQueryBuilder object 
    215  * \param property_a, name of the first property 
    216  * \param op, comparison operator 
    217  * \param property_b, a name of the second property 
    218  * \return \c TRUE if properties' names are valid, \c FALSE otherwise 
    219  */ 
    220 extern gboolean midgard_query_builder_add_constraint_with_property( 
    221         MidgardQueryBuilder *builder, const gchar *property_a, 
    222                 const gchar *op, const gchar *property_b); 
    223  
    224 /** 
    225  * \ingroup qb 
    226  * Starts a constraint group of the given type. A conjunctive constraint 
    227  * group (type \c AND) requires that all component constraints match the 
    228  * queried objects, while a disjunctive group (type \c OR) requires just 
    229  * one of the component constraints to match. 
    230  * 
    231  * \param     builder query builder 
    232  * \param[in] type    group type (\c AND or \c OR) 
    233  * \return \c TRUE if the type is valid (\c AND or \c OR), \c FALSE otherwise 
    234  */ 
    235 extern gboolean midgard_query_builder_begin_group( 
    236         MidgardQueryBuilder *builder, const gchar *type); 
    237  
    238 /** 
    239  * \ingroup qb 
    240  * Closes the most recently opened constraint group. The client should 
    241  * ensure proper nesting by closing all constraint groups before the 
    242  * containing query is executed. 
    243  * 
    244  * \param builder query builder 
    245  * \return \c TRUE if a constraint group was closed, or \c FALSE if no 
    246  *         open constraint groups were found 
    247  */ 
    248 extern gboolean midgard_query_builder_end_group(MidgardQueryBuilder *builder); 
    249  
    250 /** 
    251  * \ingroup qb 
    252  * Adds an ordering constraint to the query. An ordering constraint consists 
    253  * of a property name and a sort direction. The objects returned by this 
    254  * query will be sorted by the given property in the given direction 
    255  * (ascending or descending). Multiple ordering constraints are applied in 
    256  * the order they were added. 
    257  * 
    258  * \param     builder query builder 
    259  * \param[in] name    name of the order property 
    260  * \param[in] dir     sort direction (\c ASC or \c DESC) 
    261  * \return \c TRUE if the ordering constraint is valid, \c FALSE otherwise 
    262  */ 
    263 extern gboolean midgard_query_builder_add_order( 
    264         MidgardQueryBuilder *builder, const gchar *name, const gchar *dir); 
    265  
    266 /** 
    267  * \ingroup qb 
    268  * Sets the start offset of the objects to return when the query is executed. 
    269  * The start offset is applied after all the matching objects have been 
    270  * identified and sorted according to the given ordering constraints. The 
    271  * first \c offset objects are skipped and only the remaining (if any) objects 
    272  * are returned to the client. 
    273  * 
    274  * Setting a start offset is normally only reasonable when one or more 
    275  * ordering constraints are applied to the query. A start offset is usually 
    276  * accompanied by a limit setting. 
    277  * 
    278  * \param     builder query builder 
    279  * \param[in] offset  query offset 
    280  */ 
    281 extern void midgard_query_builder_set_offset( 
    282         MidgardQueryBuilder *builder, guint offset); 
    283  
    284 /** 
    285  * \ingroup qb 
    286  * Sets the maximum number of objects to return when the query is executed. 
    287  * A query will by default return all matching objects, but the limit setting 
    288  * can be used to restrict the potentially large number of returned objects. 
    289  * The limit is applied only after the matching objects have been identified 
    290  * and sorted and after the optional start offset has been applied. 
    291  * 
    292  * Setting a limit on the number of returned objects is normally only 
    293  * reasonable when one or more ordering constraints and optionally an offset 
    294  * setting are applied to the query. 
    295  * 
    296  * \param     builder query builder 
    297  * \param[in] limit   query limit 
    298  */ 
    299 extern void midgard_query_builder_set_limit( 
    300         MidgardQueryBuilder *builder, guint limit); 
    301  
    302 /** 
    303  * \ingroup qb 
    304  * Executes the built query. The matched recors are returned as full 
    305  * MgdObjects. 
    306  * 
    307  * \param      builder   query builder 
    308  * \param[out] holder place to store the number of returned objects 
    309  * \return objects matched by the query terminated by NULL. 
    310  * 
    311  * Number of returned objects are available as holder->elements member. 
    312  * You should free holder's struct when no longer needed. 
    313  * Holder is also optionally. 
    314  * 
    315  */ 
    316 extern GObject **midgard_query_builder_execute( 
    317         MidgardQueryBuilder *builder, guint *n_objects); 
    318  
    319 /** 
    320  * \ingroup qb 
    321  * Returns the number of objects that this query would return when executed 
    322  * without limit or start offset settings. 
    323  * 
    324  * \warning At the moment this function is implemented by simply calling 
    325  * midgard_query_builder_execute and discarding all the returned objects. 
    326  * An optimized version of this function is however being planned, so 
    327  * applications should feel free to start using this function. 
    328  * 
    329  * \return number of objects matched by this query 
    330  */ 
    331 extern guint midgard_query_builder_count(MidgardQueryBuilder *builder);  
    332  
    333  
    334 /** 
    335  * \ingroup qb 
    336  * Joins type's properties' fields in query. 
    337  * 
    338  * \param builder Midgard Query Builder object's instance 
    339  * \param prop property which is a memeber of builder type 
    340  * \param jobject typename which property should be joined 
    341  * \param jprop property which should be joined 
    342  *  
    343  * \return \c TRUE if properties are valid for defined types and query can be built 
    344  * , \c FALSE otherwise 
    345  *  
    346  */ 
    347 gboolean midgard_query_builder_join( 
    348                 MidgardQueryBuilder *builder, const gchar *prop, 
    349                 const gchar *jobject, const gchar *jprop); 
    350 /** 
    351  * \ingroup qb 
    352  * 
    353  * Executes the built query. The matched recors are returned as object's guid. 
    354  * Look at midgard_query_builder_execute which returns full objects. 
    355  * 
    356  * \param builder Midgard Query Builder object's instance 
    357  * 
    358  * \return Glist  
    359  * 
    360  * Data member of returned list contains object's guid. Caller is responsible  
    361  * to free memory allocated by all list's data and list itself. 
    362  */  
    363 GList *midgard_query_builder_get_guid(MidgardQueryBuilder *builder); 
    364  
    365 /** 
    366  * \ingroup qb 
    367  * 
    368  * Returns type name of the type which is currently used by Query Builder. 
    369  *  
    370  * This function should be used on language binding level , when internal 
    371  * Query Builder's instance is already created and language binding object  
    372  * should be instanciated. 
    373  * 
    374  * \param builder Midgard Query Builder object's instance 
    375  * 
    376  * \return type name 
    377  * 
    378  * Returned type name is a pointer and is owned by GLib system. 
    379  * Caller shouldn't free it. 
    380  */ 
    381 const gchar *midgard_query_builder_get_type_name(MidgardQueryBuilder *builder); 
    382  
    383 /** 
    384  * \ingroup qb 
    385  * 
    386  * Include deleted objects. 
    387  * 
    388  * \param builder , MidgardQueryBuilder instance pointer 
    389  * 
    390  * Normally Query Builder queries only undeleted objects. This method 
    391  * forces QB instance to query both, deleted and undeleted objects. 
    392  */ 
    393 extern void midgard_query_builder_include_deleted(MidgardQueryBuilder *builder); 
     67GType                   midgard_query_builder_get_type          (void); 
     68MidgardQueryBuilder     *midgard_query_builder_new              (MidgardConnection *mgd, const gchar *classname); 
     69void                    midgard_query_builder_set_lang          (MidgardQueryBuilder *builder, gint lang); 
     70void                    midgard_query_builder_unset_languages   (MidgardQueryBuilder *builder); 
     71gboolean                midgard_query_builder_add_constraint    (MidgardQueryBuilder *builder, const gchar *name, const gchar *op, const GValue *value); 
     72gboolean                midgard_query_builder_add_constraint_with_property      (MidgardQueryBuilder *builder, const gchar *property_a, const gchar *op, const gchar *property_b); 
     73gboolean                midgard_query_builder_begin_group       (MidgardQueryBuilder *builder, const gchar *type); 
     74gboolean                midgard_query_builder_end_group         (MidgardQueryBuilder *builder); 
     75gboolean                midgard_query_builder_add_order         (MidgardQueryBuilder *builder, const gchar *name, const gchar *dir); 
     76void                    midgard_query_builder_set_offset        (MidgardQueryBuilder *builder, guint offset); 
     77void                    midgard_query_builder_set_limit         (MidgardQueryBuilder *builder, guint limit); 
     78GObject                 **midgard_query_builder_execute         (MidgardQueryBuilder *builder, guint *n_objects); 
     79guint                   midgard_query_builder_count             (MidgardQueryBuilder *builder);  
     80const gchar             *midgard_query_builder_get_type_name    (MidgardQueryBuilder *builder); 
     81void                    midgard_query_builder_include_deleted   (MidgardQueryBuilder *builder); 
    39482 
    39583#endif