diff options
author | Owen W. Taylor <otaylor@fishsoup.net> | 2010-09-07 16:05:32 -0400 |
---|---|---|
committer | Owen W. Taylor <otaylor@fishsoup.net> | 2010-09-08 09:13:22 -0400 |
commit | b444c90d281ca33d87d4a1c6b8062ef7103ef0e8 (patch) | |
tree | d2cf950965adf0e272c514292238d8e8016233fa | |
parent | 900371e187a6b93e0b67cd03571adedc5e6057b5 (diff) | |
download | gconf-b444c90d281ca33d87d4a1c6b8062ef7103ef0e8.tar.gz |
introspection: Add annotations to fix warnings
Add (skip) (transfer) and (element-type) annotations to fix
almost all warnings from introspection (there is one bug left in
the scanner causing a warning about GConfError.)
Docs for the functions being annotated are moved to the source files.
All types that are not currently boxed or GObject are skipped; some
of these could be made boxed with only a small amount of work.
-rw-r--r-- | doc/gconf/tmpl/gconf-changeset.sgml | 27 | ||||
-rw-r--r-- | doc/gconf/tmpl/gconf-client.sgml | 121 | ||||
-rw-r--r-- | doc/gconf/tmpl/gconf-engine.sgml | 12 | ||||
-rw-r--r-- | doc/gconf/tmpl/gconf-listeners.sgml | 6 | ||||
-rw-r--r-- | doc/gconf/tmpl/gconf-schema.sgml | 2 | ||||
-rw-r--r-- | doc/gconf/tmpl/gconf-value.sgml | 10 | ||||
-rw-r--r-- | doc/gconf/tmpl/gconf.sgml | 133 | ||||
-rw-r--r-- | gconf/gconf-changeset.c | 29 | ||||
-rw-r--r-- | gconf/gconf-client.c | 127 | ||||
-rw-r--r-- | gconf/gconf-engine.h | 7 | ||||
-rw-r--r-- | gconf/gconf-listeners.h | 11 | ||||
-rw-r--r-- | gconf/gconf-schema.h | 7 | ||||
-rw-r--r-- | gconf/gconf-value.c | 12 | ||||
-rw-r--r-- | gconf/gconf-value.h | 5 | ||||
-rw-r--r-- | gconf/gconf.c | 141 |
15 files changed, 408 insertions, 242 deletions
diff --git a/doc/gconf/tmpl/gconf-changeset.sgml b/doc/gconf/tmpl/gconf-changeset.sgml index df1bec88..af33f9a5 100644 --- a/doc/gconf/tmpl/gconf-changeset.sgml +++ b/doc/gconf/tmpl/gconf-changeset.sgml @@ -178,16 +178,12 @@ If @key is not in the change set, this function has no effect. <!-- ##### FUNCTION gconf_change_set_foreach ##### --> <para> -Iterates over a #GConfChangeSet by calling a -#GConfChangeSetForeachFunc for each change in the set. See the -description of #GConfChangeSetForeachFunc for details. You may not -call gconf_change_set_remove() during the iteration, because you'll -confuse the internal data structures and cause memory corruption. + </para> -@cs: a #GConfChangeSet. -@func: function to call for each change in the change set. -@user_data: user data to pass to the #GConfChangeSetForeachFunc. +@cs: +@func: +@user_data: <!-- ##### FUNCTION gconf_change_set_check_value ##### --> @@ -323,21 +319,20 @@ the pair of values being set for the key. <!-- ##### FUNCTION gconf_change_set_set_user_data ##### --> <para> -Sets the user_data and the destroy notification function fields of the -#GConfChangeSet. + </para> -@cs: a #GConfChangeSet. -@data: a #gpointer. -@dnotify: a pointer to the function to be called during destroy. +@cs: +@data: +@dnotify: <!-- ##### FUNCTION gconf_change_set_get_user_data ##### --> <para> -Returns the user_data field of the #GConfChangeSet. + </para> -@cs: a #GConfChangeSet. -@Returns: a pointer to the user_data. +@cs: +@Returns: diff --git a/doc/gconf/tmpl/gconf-client.sgml b/doc/gconf/tmpl/gconf-client.sgml index 43aeb492..1dc19075 100644 --- a/doc/gconf/tmpl/gconf-client.sgml +++ b/doc/gconf/tmpl/gconf-client.sgml @@ -191,31 +191,20 @@ Casts a pointer to a #GConfClient*. <!-- ##### FUNCTION gconf_client_get_default ##### --> <para> -Creates a new #GConfClient using the default #GConfEngine. Normally this is the -engine you want. If someone else is already using the default -#GConfClient, this function returns the same one they're using, but -with the reference count incremented. So you have to unref either way. -</para> -<para> -It's important to call g_type_init() before using this GObject, to initialize the type system. </para> @void: -@Returns: a new #GConfClient. g_object_unref() when you're done. +@Returns: <!-- ##### FUNCTION gconf_client_get_for_engine ##### --> <para> -Creates a new #GConfClient with a specific #GConfEngine. Only specialized -configuration-related programs should need to call this function. The -returned #GConfClient should be unref'd when you're done with g_object_unref(). -Remember to avoid using the #GConfEngine directly once you have a #GConfClient -wrapper. + </para> -@engine: the #GConfEngine to use. -@Returns: a new #GConfClient. +@engine: +@Returns: <!-- ##### FUNCTION gconf_client_add_dir ##### --> @@ -329,11 +318,10 @@ Controls the default error handling for #GConfClient. See <!-- ##### FUNCTION gconf_client_set_global_default_error_handler ##### --> <para> -Set @func as the default error handler for the #GConfClient. This handler would be called -for all #GConfClient internal errors. + </para> -@func: pointer to the function to be called for error handling. +@func: <!-- ##### FUNCTION gconf_client_clear_cache ##### --> @@ -456,32 +444,24 @@ but uses #GConfClient caching and error-handling features. <!-- ##### FUNCTION gconf_client_all_entries ##### --> <para> -Lists the key-value pairs in @dir. Does not list subdirectories; for -that use gconf_client_all_dirs(). The returned list contains #GConfEntry -objects. A #GConfEntry contains an <emphasis>absolute</emphasis> key -and a value. The list is not recursive, it contains only the immediate -children of @dir. To free the returned list, gconf_entry_free() -each list element, then g_slist_free() the list itself. -Just like gconf_engine_all_entries (), but uses #GConfClient caching and error-handling features. + </para> -@client: a #GConfClient. -@dir: directory to list. -@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. -@Returns: List of #GConfEntry. +@client: +@dir: +@err: +@Returns: <!-- ##### FUNCTION gconf_client_all_dirs ##### --> <para> -Lists the subdirectories in @dir. The returned list contains allocated -strings. Each string is the absolute path of a subdirectory. You should g_free() each string in the list, then g_slist_free() the list itself. -Just like gconf_engine_all_dirs (), but uses #GConfClient caching and error-handling features. + </para> -@client: a #GConfClient. -@dir: directory to get subdirectories from. -@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. -@Returns: List of allocated subdirectory names. +@client: +@dir: +@err: +@Returns: <!-- ##### FUNCTION gconf_client_suggest_sync ##### --> @@ -601,73 +581,14 @@ Just like gconf_engine_get_schema (), but uses #GConfClient caching and error-ha <!-- ##### FUNCTION gconf_client_get_list ##### --> <para> -Requests the list (%GCONF_VALUE_LIST) stored at @key. Automatically -performs type-checking, so if a non-list is stored at @key, or the -list does not contain elements of type @list_type, an error is -returned. If no value is set or an error occurs, <symbol>NULL</symbol> -is returned. Note that <symbol>NULL</symbol> is also the empty list, -so if you need to distinguish the empty list from an unset value, you -must use gconf_client_get () to obtain a raw #GConfValue. -</para> - -<para> -<emphasis>Remember that GConf lists can only store primitive types: -%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL, -%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember -that lists must be uniform, you may not mix types in the same list. -</para> - -<para> -The type of the list elements depends on @list_type. A #GConfValue -with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue -objects. gconf_client_get_list() automatically converts to primitive C -types. Thus, the list->data fields in the returned list -contain: - -<informaltable pgwide="1" frame="none"> -<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/> -<tbody> - -<row> -<entry>%GCONF_VALUE_INT</entry> -<entry>The integer itself, converted with GINT_TO_POINTER()</entry> -</row> - -<row> -<entry>%GCONF_VALUE_BOOL</entry> -<entry>The bool itself, converted with GINT_TO_POINTER()</entry> -</row> - -<row> -<entry>%GCONF_VALUE_FLOAT</entry> -<entry>A pointer to #gdouble, which should be freed with g_free()</entry> -</row> - -<row> -<entry>%GCONF_VALUE_STRING</entry> -<entry>A pointer to #gchar, which should be freed with g_free()</entry> -</row> - -<row> -<entry>%GCONF_VALUE_SCHEMA</entry> -<entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry> -</row> - -</tbody></tgroup></informaltable> - -In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must -g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must -gconf_schema_free() each element. In all cases you must free the -list itself with g_slist_free(). -Just like gconf_engine_get_list (), but uses #GConfClient caching and error-handling features. </para> -@client: a #GConfClient. -@key: key you want the value of. -@list_type: type of each list element. -@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. -@Returns: an allocated list, with elements as described above. +@client: +@key: +@list_type: +@err: +@Returns: <!-- ##### FUNCTION gconf_client_get_pair ##### --> diff --git a/doc/gconf/tmpl/gconf-engine.sgml b/doc/gconf/tmpl/gconf-engine.sgml index adff9160..92fce0ad 100644 --- a/doc/gconf/tmpl/gconf-engine.sgml +++ b/doc/gconf/tmpl/gconf-engine.sgml @@ -33,23 +33,17 @@ configuration values. <!-- ##### STRUCT GConfEngine ##### --> <para> -An opaque data type representing one or more configuration sources. + </para> <!-- ##### FUNCTION gconf_engine_get_default ##### --> <para> -Returns the default #GConfEngine. All clients should use this, unless -they are special configuration-related tools. The caller of this -function assumes one reference count, and must call -gconf_engine_unref() at some point. It's fairly important to unref the -#GConfEngine, to cleanly close the connection to -<application>gconfd</application>. So if possible close the connection -before exiting your application. see ? printf() <function>printf()</function> + </para> @void: -@Returns: the default #GConfEngine. +@Returns: <!-- ##### FUNCTION gconf_engine_get_for_address ##### --> diff --git a/doc/gconf/tmpl/gconf-listeners.sgml b/doc/gconf/tmpl/gconf-listeners.sgml index 37d2ac8a..d2d5782c 100644 --- a/doc/gconf/tmpl/gconf-listeners.sgml +++ b/doc/gconf/tmpl/gconf-listeners.sgml @@ -24,11 +24,7 @@ convenience wrapper. <!-- ##### STRUCT GConfListeners ##### --> <para> -The #GConfListeners structure contains nothing other than a dummy pointer. Internally -the data about listeners is maintained through a listener table structure, -LTable which contains data like the namespace, an array to hold the listeners, count of -active listeners,value to be given to the next connection and the list of connection indices -to be recycled. There is also a Listener structure maintaining data pertaining to listeners. + </para> diff --git a/doc/gconf/tmpl/gconf-schema.sgml b/doc/gconf/tmpl/gconf-schema.sgml index a034d42e..f0d2ec14 100644 --- a/doc/gconf/tmpl/gconf-schema.sgml +++ b/doc/gconf/tmpl/gconf-schema.sgml @@ -32,7 +32,7 @@ be</emphasis>, not what the type actually is. <!-- ##### STRUCT GConfSchema ##### --> <para> -An opaque data type representing a description of a key-value pair. + </para> diff --git a/doc/gconf/tmpl/gconf-value.sgml b/doc/gconf/tmpl/gconf-value.sgml index 93eb5417..91d67983 100644 --- a/doc/gconf/tmpl/gconf-value.sgml +++ b/doc/gconf/tmpl/gconf-value.sgml @@ -131,15 +131,11 @@ Returns the type of the list elements in a #GConfValue with type <!-- ##### FUNCTION gconf_value_get_list ##### --> <para> -Returns a #GSList containing #GConfValue objects. Each #GConfValue in -the returned list will have the type returned by -gconf_value_get_list_type(). Remember that the empty #GSList is equal to -<symbol>NULL</symbol>. The list is not a copy; it is "owned" by the -#GConfValue and will be destroyed when the #GConfValue is destroyed. + </para> -@value: a #GConfValue. -@Returns: a #GList. +@value: +@Returns: <!-- ##### FUNCTION gconf_value_get_car ##### --> diff --git a/doc/gconf/tmpl/gconf.sgml b/doc/gconf/tmpl/gconf.sgml index d936dbec..7b802ddc 100644 --- a/doc/gconf/tmpl/gconf.sgml +++ b/doc/gconf/tmpl/gconf.sgml @@ -95,24 +95,15 @@ gconf_engine_notify_add(). <!-- ##### FUNCTION gconf_engine_notify_add ##### --> <para> -Registers a notification request with the <application>gconfd</application> -server. The server will notify the client when any key at or below -@namespace_section is set or unset. Try to watch the smallest possible part of -the namespace; otherwise you will slow down the server and your application with -unnecessary notifications. Note that you should prefer gconf_client_notify_add() -if you're using the #GObject wrapper library, because -gconf_client_notify_add() does not require a client-server conversation for -every callback. gconf_engine_notify_add() requests a different server notification for -every callback. The function returns an ID you can use to remove the -notification request; 0 is an invalid ID, and is returned if an error occurs. -</para> - -@conf: a #GConfEngine to monitor for changes. -@namespace_section: the directory or key to watch; you will be notified of changes at or below this point. -@func: the callback to invoke when a notification is received from the server. -@user_data: the data to pass to the callback. -@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. -@Returns: an ID for the notification request, or 0 on error. + +</para> + +@conf: +@namespace_section: +@func: +@user_data: +@err: +@Returns: <!-- ##### FUNCTION gconf_engine_notify_remove ##### --> @@ -256,30 +247,24 @@ schema associations into the database during "make install." <!-- ##### FUNCTION gconf_engine_all_entries ##### --> <para> -Lists the key-value pairs in @dir. Does not list subdirectories; for -that use gconf_engine_all_dirs(). The returned list contains #GConfEntry -objects. A #GConfEntry contains an <emphasis>absolute</emphasis> key -and a value. The list is not recursive, it contains only the immediate -children of @dir. To free the returned list, gconf_entry_free() -each list element, then g_slist_free() the list itself. + </para> -@conf: a #GConfEngine. -@dir: Directory to list. -@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. -@Returns: List of #GConfEntry. +@conf: +@dir: +@err: +@Returns: <!-- ##### FUNCTION gconf_engine_all_dirs ##### --> <para> -Lists the subdirectories in @dir. The returned list contains allocated -strings. Each string is the absolute path of a subdirectory. You should g_free() each string in the list, then g_slist_free() the list itself. + </para> -@conf: a #GConfEngine. -@dir: Directory to get subdirectories from. -@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. -@Returns: List of allocated subdirectory names. +@conf: +@dir: +@err: +@Returns: <!-- ##### FUNCTION gconf_engine_suggest_sync ##### --> @@ -464,85 +449,25 @@ stored at @key, an error is returned. On error, or if @key is unset, <!-- ##### FUNCTION gconf_engine_get_schema ##### --> <para> -Requests the schema (%GCONF_VALUE_SCHEMA) stored at @key. -Automatically performs type-checking, so if a non-schema is stored at -@key, an error is returned. If no value is set or an error occurs, -<symbol>NULL</symbol> is returned. + </para> -@conf: a #GConfEngine. -@key: key you want the value of. -@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. -@Returns: the value of @key as an allocated #GConfSchema, or <symbol>NULL</symbol> if no value was obtained. +@conf: +@key: +@err: +@Returns: <!-- ##### FUNCTION gconf_engine_get_list ##### --> <para> -Requests the list (%GCONF_VALUE_LIST) stored at @key. Automatically -performs type-checking, so if a non-list is stored at @key, or the -list does not contain elements of type @list_type, an error is -returned. If no value is set or an error occurs, <symbol>NULL</symbol> -is returned. Note that <symbol>NULL</symbol> is also the empty list, -so if you need to distinguish the empty list from an unset value, you -must use gconf_engine_get () to obtain a raw #GConfValue. -</para> -<para> -<emphasis>Remember that GConf lists can only store primitive types: -%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL, -%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember -that lists must be uniform, you may not mix types in the same list. </para> -<para> -The type of the list elements depends on @list_type. A #GConfValue -with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue -objects. gconf_engine_get_list() automatically converts to primitive C -types. Thus, the list->data fields in the returned list -contain: - -<informaltable pgwide="1" frame="none"> -<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/> -<tbody> - -<row> -<entry>%GCONF_VALUE_INT</entry> -<entry>The integer itself, converted with GINT_TO_POINTER()</entry> -</row> - -<row> -<entry>%GCONF_VALUE_BOOL</entry> -<entry>The bool itself, converted with GINT_TO_POINTER()</entry> -</row> - -<row> -<entry>%GCONF_VALUE_FLOAT</entry> -<entry>A pointer to #gdouble, which should be freed with g_free()</entry> -</row> - -<row> -<entry>%GCONF_VALUE_STRING</entry> -<entry>A pointer to #gchar, which should be freed with g_free()</entry> -</row> - -<row> -<entry>%GCONF_VALUE_SCHEMA</entry> -<entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry> -</row> - -</tbody></tgroup></informaltable> - -In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must -g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must -gconf_schema_free() each element. In all cases you must free the -list itself with g_slist_free(). -</para> - -@conf: a #GConfEngine. -@key: key you want the value of. -@list_type: type of each list element. -@err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. -@Returns: an allocated list, with elements as described above. +@conf: +@key: +@list_type: +@err: +@Returns: <!-- ##### FUNCTION gconf_engine_get_pair ##### --> diff --git a/gconf/gconf-changeset.c b/gconf/gconf-changeset.c index c797d818..4890fce7 100644 --- a/gconf/gconf-changeset.c +++ b/gconf/gconf-changeset.c @@ -106,6 +106,15 @@ gconf_change_set_unref (GConfChangeSet* cs) } } +/** + * gconf_change_set_set_user_data: (skip) + * @cs: a #GConfChangeSet. + * @data: a #gpointer. + * @dnotify: a pointer to the function to be called during destroy. + * + * Sets the user_data and the destroy notification function fields of the + * #GConfChangeSet. + */ void gconf_change_set_set_user_data (GConfChangeSet *cs, gpointer data, @@ -118,6 +127,14 @@ gconf_change_set_set_user_data (GConfChangeSet *cs, cs->dnotify = dnotify; } +/** + * gconf_change_set_get_user_data: (skip) + * @cs: a #GConfChangeSet. + * + * Returns the user_data field of the #GConfChangeSet. + * + * Return value: a pointer to the user_data. + */ gpointer gconf_change_set_get_user_data (GConfChangeSet *cs) { @@ -207,6 +224,18 @@ foreach(gpointer key, gpointer value, gpointer user_data) (* fd->func) (fd->cs, c->key, c->value, fd->user_data); } +/** + * gconf_change_set_foreach: + * @cs: a #GConfChangeSet. + * @func: (scope call): function to call for each change in the change set. + * @user_data: user data to pass to the #GConfChangeSetForeachFunc. + * + * Iterates over a #GConfChangeSet by calling a + * #GConfChangeSetForeachFunc for each change in the set. See the + * description of #GConfChangeSetForeachFunc for details. You may not + * call gconf_change_set_remove() during the iteration, because you'll + * confuse the internal data structures and cause memory corruption. + */ void gconf_change_set_foreach (GConfChangeSet* cs, GConfChangeSetForeachFunc func, diff --git a/gconf/gconf-client.c b/gconf/gconf-client.c index d22c3267..f1df54ac 100644 --- a/gconf/gconf-client.c +++ b/gconf/gconf-client.c @@ -56,6 +56,13 @@ trace (const char *format, ...) static GConfClientErrorHandlerFunc global_error_handler = NULL; +/** + * gconf_client_set_global_default_error_handler: (skip) + * @func: pointer to the function to be called for error handling. + * + * Set @func as the default error handler for the #GConfClient. This handler would be called + * for all #GConfClient internal errors. + */ void gconf_client_set_global_default_error_handler(GConfClientErrorHandlerFunc func) { @@ -422,6 +429,18 @@ notify_from_server_callback (GConfEngine* conf, guint cnxn_id, */ +/** + * gconf_client_get_default: + * + * Creates a new #GConfClient using the default #GConfEngine. Normally this is the + * engine you want. If someone else is already using the default + * #GConfClient, this function returns the same one they're using, but + * with the reference count incremented. So you have to unref either way. + * + * It's important to call g_type_init() before using this GObject, to initialize the type system. + * + * Return value: (transfer full): a new #GConfClient. g_object_unref() when you're done. + */ GConfClient* gconf_client_get_default (void) { @@ -451,6 +470,18 @@ gconf_client_get_default (void) return client; } +/** + * gconf_client_get_for_engine: + * @engine: the #GConfEngine to use. + * + * Creates a new #GConfClient with a specific #GConfEngine. Only specialized + * configuration-related programs should need to call this function. The + * returned #GConfClient should be unref'd when you're done with g_object_unref(). + * Remember to avoid using the #GConfEngine directly once you have a #GConfClient + * wrapper. + * + * Return value: (transfer full): a new #GConfClient. + */ GConfClient* gconf_client_get_for_engine (GConfEngine* engine) { @@ -1086,6 +1117,22 @@ copy_entry_list (GSList *list) return copy; } +/** + * gconf_client_all_entries: + * @client: a #GConfClient. + * @dir: directory to list. + * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. + * + * Lists the key-value pairs in @dir. Does not list subdirectories; for + * that use gconf_client_all_dirs(). The returned list contains #GConfEntry + * objects. A #GConfEntry contains an <emphasis>absolute</emphasis> key + * and a value. The list is not recursive, it contains only the immediate + * children of @dir. To free the returned list, gconf_entry_free() + * each list element, then g_slist_free() the list itself. + * Just like gconf_engine_all_entries (), but uses #GConfClient caching and error-handling features. + * + * Return value: (element-type GConfEntry) (transfer full): List of #GConfEntry. + */ GSList* gconf_client_all_entries (GConfClient* client, const gchar* dir, @@ -1138,6 +1185,20 @@ gconf_client_all_entries (GConfClient* client, return retval; } +/** + * gconf_client_all_dirs: + * @client: a #GConfClient. + * @dir: directory to get subdirectories from. + * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. + * + * Lists the subdirectories in @dir. The returned list contains + * allocated strings. Each string is the absolute path of a + * subdirectory. You should g_free() each string in the list, then + * g_slist_free() the list itself. Just like gconf_engine_all_dirs(), + * but uses #GConfClient caching and error-handling features. + * + * Return value: (element-type utf8) (transfer full): List of allocated subdirectory names. + */ GSList* gconf_client_all_dirs (GConfClient* client, const gchar* dir, GError** err) @@ -1628,6 +1689,72 @@ gconf_client_get_schema (GConfClient* client, } } +/** + * gconf_client_get_list: (skip) + * @client: a #GConfClient. + * @key: key you want the value of. + * @list_type: type of each list element. + * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. + * + * Requests the list (%GCONF_VALUE_LIST) stored at @key. Automatically + * performs type-checking, so if a non-list is stored at @key, or the + * list does not contain elements of type @list_type, an error is + * returned. If no value is set or an error occurs, <symbol>NULL</symbol> + * is returned. Note that <symbol>NULL</symbol> is also the empty list, + * so if you need to distinguish the empty list from an unset value, you + * must use gconf_client_get () to obtain a raw #GConfValue. + * + * <emphasis>Remember that GConf lists can only store primitive types: + * %GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL, + * %GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember + * that lists must be uniform, you may not mix types in the same list. + * + * The type of the list elements depends on @list_type. A #GConfValue + * with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue + * objects. gconf_client_get_list() automatically converts to primitive C + * types. Thus, the list->data fields in the returned list + * contain: + * + * <informaltable pgwide="1" frame="none"> + * <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/> + * <tbody> + * + * <row> + * <entry>%GCONF_VALUE_INT</entry> + * <entry>The integer itself, converted with GINT_TO_POINTER()</entry> + * </row> + * + * <row> + * <entry>%GCONF_VALUE_BOOL</entry> + * <entry>The bool itself, converted with GINT_TO_POINTER()</entry> + * </row> + * + * <row> + * <entry>%GCONF_VALUE_FLOAT</entry> + * <entry>A pointer to #gdouble, which should be freed with g_free()</entry> + * </row> + * + * <row> + * <entry>%GCONF_VALUE_STRING</entry> + * <entry>A pointer to #gchar, which should be freed with g_free()</entry> + * </row> + * + * <row> + * <entry>%GCONF_VALUE_SCHEMA</entry> + * <entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry> + * </row> + * + * </tbody></tgroup></informaltable> + * + * In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must + * g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must + * gconf_schema_free() each element. In all cases you must free the + * list itself with g_slist_free(). + * + * Just like gconf_engine_get_list (), but uses #GConfClient caching and error-handling features. + * +* Return value: an allocated list, with elements as described above. +*/ GSList* gconf_client_get_list (GConfClient* client, const gchar* key, GConfValueType list_type, GError** err) diff --git a/gconf/gconf-engine.h b/gconf/gconf-engine.h index 4185d96b..91a3ab5a 100644 --- a/gconf/gconf-engine.h +++ b/gconf/gconf-engine.h @@ -25,6 +25,13 @@ G_BEGIN_DECLS +/* Skipped from introspection because it's not an object or registered as boxed */ +/** + * GConfEngine: (skip) + * + * An opaque data type representing one or more configuration sources. + */ + /* A configuration engine (stack of config sources); normally there's * just one of these on the system. */ diff --git a/gconf/gconf-listeners.h b/gconf/gconf-listeners.h index 69f7bad8..eb06f1d7 100644 --- a/gconf/gconf-listeners.h +++ b/gconf/gconf-listeners.h @@ -24,6 +24,17 @@ G_BEGIN_DECLS +/* Skipped from introspection because it's not registered as boxed */ +/** + * GConfListeners: (skip) + * + * The #GConfListeners structure contains nothing other than a dummy pointer. Internally + * the data about listeners is maintained through a listener table structure, + * LTable which contains data like the namespace, an array to hold the listeners, count of + * active listeners,value to be given to the next connection and the list of connection indices + * to be recycled. There is also a Listener structure maintaining data pertaining to listeners. + */ + /* * The listeners object is used to store listeners who want notification * of changes in a namespace section. diff --git a/gconf/gconf-schema.h b/gconf/gconf-schema.h index fe6975c6..4821a65d 100644 --- a/gconf/gconf-schema.h +++ b/gconf/gconf-schema.h @@ -27,6 +27,13 @@ G_BEGIN_DECLS +/* Skipped from introspection because it's not registered as boxed */ +/** + * GConfSchema: (skip) + * + * An opaque data type representing a description of a key-value pair. + */ + /* * A "schema" is a value that describes a key-value pair. * It might include the type of the pair, documentation describing diff --git a/gconf/gconf-value.c b/gconf/gconf-value.c index 499403db..da9d7435 100644 --- a/gconf/gconf-value.c +++ b/gconf/gconf-value.c @@ -895,6 +895,18 @@ gconf_value_get_list_type (const GConfValue *value) return REAL_VALUE (value)->d.list_data.type; } +/** + * gconf_value_get_list: + * @value: a #GConfValue. + * + * Returns a #GSList containing #GConfValue objects. Each #GConfValue in + * the returned list will have the type returned by + * gconf_value_get_list_type(). Remember that the empty #GSList is equal to + * <symbol>NULL</symbol>. The list is not a copy; it is "owned" by the + * #GConfValue and will be destroyed when the #GConfValue is destroyed. + * + * Return value: (element-type GConfValue) (transfer none): a #GList. + */ GSList* gconf_value_get_list (const GConfValue *value) { diff --git a/gconf/gconf-value.h b/gconf/gconf-value.h index 1f575107..d8d3c82e 100644 --- a/gconf/gconf-value.h +++ b/gconf/gconf-value.h @@ -126,6 +126,11 @@ gchar* gconf_value_encode (GConfValue *val); * info into GConfEntry, though the transition isn't complete. */ +/* Skipped from introspection because it's not registered as boxed */ +/** + * GConfMetaInfo: (skip) + * + */ typedef struct _GConfMetaInfo GConfMetaInfo; struct _GConfMetaInfo { diff --git a/gconf/gconf.c b/gconf/gconf.c index 4261524b..0b599446 100644 --- a/gconf/gconf.c +++ b/gconf/gconf.c @@ -558,6 +558,19 @@ gconf_engine_get_local_for_addresses (GSList *addresses, return conf; } +/** + * gconf_engine_get_default: (skip) + * + * Returns the default #GConfEngine. All clients should use this, unless + * they are special configuration-related tools. The caller of this + * function assumes one reference count, and must call + * gconf_engine_unref() at some point. It's fairly important to unref the + * #GConfEngine, to cleanly close the connection to + * <application>gconfd</application>. So if possible close the connection + * before exiting your application. + * + * Return value: (transfer full): the default #GConfEngine. + */ GConfEngine* gconf_engine_get_default (void) { @@ -791,6 +804,28 @@ gconf_engine_get_user_data (GConfEngine *engine) return engine->user_data; } +/** + * gconf_engine_notify_add: (skip) + * @conf: a #GConfEngine to monitor for changes. + * @namespace_section: the directory or key to watch; you will be notified of changes at or below this point. + * @func: the callback to invoke when a notification is received from the server. + * @user_data: the data to pass to the callback. + * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. + * Return value: an ID for the notification request, or 0 on error. + * + * Registers a notification request with the <application>gconfd</application> + * server. The server will notify the client when any key at or below + * @namespace_section is set or unset. Try to watch the smallest possible part of + * the namespace; otherwise you will slow down the server and your application with + * unnecessary notifications. Note that you should prefer gconf_client_notify_add() + * if you're using the #GObject wrapper library, because + * gconf_client_notify_add() does not require a client-server conversation for + * every callback. gconf_engine_notify_add() requests a different server notification for + * every callback. The function returns an ID you can use to remove the + * notification request; 0 is an invalid ID, and is returned if an error occurs. + * + * Returns value: an ID for the notification request, or 0 on error. + */ guint gconf_engine_notify_add(GConfEngine* conf, const gchar* namespace_section, @@ -1604,6 +1639,21 @@ qualify_entries (GSList *entries, const char *dir) } } +/** + * gconf_engine_all_entries: + * @conf: a #GConfEngine. + * @dir: Directory to list. + * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. + * + * Lists the key-value pairs in @dir. Does not list subdirectories; for + * that use gconf_engine_all_dirs(). The returned list contains #GConfEntry + * objects. A #GConfEntry contains an <emphasis>absolute</emphasis> key + * and a value. The list is not recursive, it contains only the immediate + * children of @dir. To free the returned list, gconf_entry_free() + * each list element, then g_slist_free() the list itself. + * + * Returns value: (element-type GConfEntry) (transfer full): List of #GConfEntry. + */ GSList* gconf_engine_all_entries(GConfEngine* conf, const gchar* dir, GError** err) { @@ -1774,6 +1824,19 @@ qualify_keys (GSList *keys, const char *dir) } } +/** + * gconf_engine_all_dirs: + * @conf: a #GConfEngine. + * @dir: Directory to get subdirectories from. + * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. + * + * Lists the subdirectories in @dir. The returned list contains + * allocated strings. Each string is the absolute path of a + * subdirectory. You should g_free() each string in the list, then + * g_slist_free() the list itself. + * + * Returns value: (element-type utf8) (transfer full): List of allocated subdirectory names. + */ GSList* gconf_engine_all_dirs(GConfEngine* conf, const gchar* dir, GError** err) { @@ -3256,6 +3319,20 @@ gconf_engine_get_bool (GConfEngine* conf, const gchar* key, } } +/** + * gconf_engine_get_schema: (skip) + * @conf: a #GConfEngine. + * @key: key you want the value of. + * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. + * @Returns: the value of @key as an allocated #GConfSchema, or <symbol>NULL</symbol> if no value was obtained. + * + * Requests the schema (%GCONF_VALUE_SCHEMA) stored at @key. + * Automatically performs type-checking, so if a non-schema is stored at + * @key, an error is returned. If no value is set or an error occurs, + * <symbol>NULL</symbol> is returned. + * + * Return value: (transfer full): the value of @key as an allocated #GConfSchema, or <symbol>NULL</symbol> if no value was obtained. + */ GConfSchema* gconf_engine_get_schema (GConfEngine* conf, const gchar* key, GError** err) { @@ -3288,6 +3365,70 @@ gconf_engine_get_schema (GConfEngine* conf, const gchar* key, GError** err) } } +/** + * gconf_engine_get_list: (skip) + * @conf: a #GConfEngine. + * @key: key you want the value of. + * @list_type: type of each list element. + * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors. + * + * Requests the list (%GCONF_VALUE_LIST) stored at @key. Automatically + * performs type-checking, so if a non-list is stored at @key, or the + * list does not contain elements of type @list_type, an error is + * returned. If no value is set or an error occurs, <symbol>NULL</symbol> + * is returned. Note that <symbol>NULL</symbol> is also the empty list, + * so if you need to distinguish the empty list from an unset value, you + * must use gconf_engine_get () to obtain a raw #GConfValue. + * + * <emphasis>Remember that GConf lists can only store primitive types: + * %GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL, + * %GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember + * that lists must be uniform, you may not mix types in the same list. + * + * The type of the list elements depends on @list_type. A #GConfValue + * with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue + * objects. gconf_engine_get_list() automatically converts to primitive C + * types. Thus, the list->data fields in the returned list + * contain: + * + * <informaltable pgwide="1" frame="none"> + * <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/> + * <tbody> + * + * <row> + * <entry>%GCONF_VALUE_INT</entry> + * <entry>The integer itself, converted with GINT_TO_POINTER()</entry> + * </row> + * + * <row> + * <entry>%GCONF_VALUE_BOOL</entry> + * <entry>The bool itself, converted with GINT_TO_POINTER()</entry> + * </row> + * + * <row> + * <entry>%GCONF_VALUE_FLOAT</entry> + * <entry>A pointer to #gdouble, which should be freed with g_free()</entry> + * </row> + * + * <row> + * <entry>%GCONF_VALUE_STRING</entry> + * <entry>A pointer to #gchar, which should be freed with g_free()</entry> + * </row> + * + * <row> + * <entry>%GCONF_VALUE_SCHEMA</entry> + * <entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry> + * </row> + * + * </tbody></tgroup></informaltable> + * + * In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must + * g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must + * gconf_schema_free() each element. In all cases you must free the + * list itself with g_slist_free(). + * + * Return value: an allocated list, with elements as described above. + */ GSList* gconf_engine_get_list (GConfEngine* conf, const gchar* key, GConfValueType list_type, GError** err) |