[gobject-introspection] Regenerate Gio/GLib/GObject annotations
- From: Martin Pitt <martinpitt src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] Regenerate Gio/GLib/GObject annotations
- Date: Thu, 18 Aug 2011 15:40:15 +0000 (UTC)
commit 73077ec28b79c8c3ced2d1ec40255fbf51728817
Author: Martin Pitt <martin pitt ubuntu com>
Date: Thu Aug 18 17:39:32 2011 +0200
Regenerate Gio/GLib/GObject annotations
Ran misc/update-glib-annotations.py against current glib master.
gir/gio-2.0.c | 3163 ++++++++++++++++++++++++++++++++++++++++++++++++++---
gir/glib-2.0.c | 2882 ++++++++++++++++++++++++++++++++++++++++++++----
gir/gobject-2.0.c | 523 ++++++++-
3 files changed, 6133 insertions(+), 435 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 84e5d86..fc64624 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -6,6 +6,7 @@
* GAction:enabled:
*
* If @action is currently enabled.
+ *
* If the action is disabled then calls to g_action_activate() and
* g_action_change_state() have no effect.
*
@@ -62,11 +63,13 @@
*
* This struct defines a single action. It is for use with
* g_simple_action_group_add_entries().
+ *
* The order of the items in the structure are intended to reflect
* frequency of use. It is permissible to use an incomplete initialiser
* in order to leave some of the later values as %NULL. All values
* after @name are optional. Additional optional fields may be added in
* the future.
+ *
* See g_simple_action_group_add_entries() for an example.
*/
@@ -244,6 +247,7 @@
* The ::command-line signal is emitted on the primary instance when
* a commandline is not handled locally. See g_application_run() and
* the #GApplicationCommandline documentation for more information.
+ *
* process. See g_application_command_line_set_exit_status().
*
* Returns: An integer that is set as the exit status for the calling
@@ -437,6 +441,7 @@
*
* Flags to be passed to g_object_bind_property() or
* g_object_bind_property_full().
+ *
* This enumeration can be extended at later date.
*
* Since: 2.26
@@ -453,6 +458,7 @@
* A function to be called to transform the source property of @source
* from @source_value into the target property of @target
* using @target_value.
+ *
* otherwise
*
* Returns: %TRUE if the transformation was successful, and %FALSE
@@ -646,48 +652,58 @@
* @cancellable: a #GCancellable.
*
* Emitted when the operation has been cancelled.
+ *
* Can be used by implementations of cancellable operations. If the
* operation is cancelled from another thread, the signal will be
* emitted in the thread that cancelled the operation, not the
* thread that is running the operation.
+ *
* Note that disconnecting from this signal (or any signal) in a
* multi-threaded program is prone to race conditions. For instance
* it is possible that a signal handler may be invoked even
* <emphasis>after</emphasis> a call to
* g_signal_handler_disconnect() for that handler has already
* returned.
+ *
* There is also a problem when cancellation happen
* right before connecting to the signal. If this happens the
* signal will unexpectedly not be emitted, and checking before
* connecting to the signal leaves a race condition where this is
* still happening.
+ *
* In order to make it safe and easy to connect handlers there
+ * are two helper functions: g_cancellable_connect() and
* g_cancellable_disconnect() which protect against problems
* like this.
+ *
* An example of how to us this:
* |[
* /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
* if (g_cancellable_set_error_if_cancelled (cancellable))
* return;
+ *
* /<!-- -->* Set up all the data needed to be able to
* * handle cancellation of the operation *<!-- -->/
* my_data = my_data_new (...);
+ *
* id = 0;
* if (cancellable)
* id = g_cancellable_connect (cancellable,
* G_CALLBACK (cancelled_handler)
* data, NULL);
+ *
* /<!-- -->* cancellable operation here... *<!-- -->/
+ *
* g_cancellable_disconnect (cancellable, id);
+ *
* /<!-- -->* cancelled_handler is never called after this, it
* * is now safe to free the data *<!-- -->/
* my_data_free (my_data);
* ]|
+ *
* Note that the cancelled signal is emitted in the thread that
* the user cancelled from, which may be the main thread. So, the
* cancellable signal should not do something that can block.
- *
- * Are two helper functions: g_cancellable_connect() and
*/
@@ -730,6 +746,7 @@
*
* The hashing algorithm to be used by #GChecksum when performing the
* digest of some data.
+ *
* Note that the #GChecksumType enumeration may be extended at a later
* date to include new hashing algorithm types.
*
@@ -800,6 +817,7 @@
* is performed for class initialization of derived types as well.
* An example may help to correspond the intend of the different class
* initializers:
+ *
* |[
* typedef struct {
* GObjectClass parent_class;
@@ -821,6 +839,7 @@
* {
* class->static_integer = 42;
* }
+ *
* typedef struct {
* TypeAClass parent_class;
* gfloat static_float;
@@ -1061,6 +1080,7 @@
*
* If authenticating as a server, this property contains the
* received credentials, if any.
+ *
* If authenticating as a client, the property contains the
* credentials that were sent, if any.
*/
@@ -1139,13 +1159,16 @@
* @error: A #GError with more details about the event or %NULL.
*
* Emitted when the connection is closed.
+ *
* The cause of this event can be
* <itemizedlist>
* <listitem><para>
* If g_dbus_connection_close() is called. In this case
+ * @remote_peer_vanished is set to %FALSE and @error is %NULL.
* </para></listitem>
* <listitem><para>
* If the remote peer closes the connection. In this case
+ * @remote_peer_vanished is set to %TRUE and @error is set.
* </para></listitem>
* <listitem><para>
* If the remote peer sends invalid or malformed data. In this
@@ -1153,7 +1176,9 @@
* is set.
* </para></listitem>
* </itemizedlist>
+ *
* Upon receiving this signal, you should give up your reference to
+ * @connection. You are guaranteed that this signal is emitted only
* once.
*
* Since: 2.26
@@ -1223,10 +1248,12 @@
*
* The GUID of the peer performing the role of server when
* authenticating.
+ *
* If you are constructing a #GDBusConnection and pass
* %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
* #GDBusConnection:flags property then you MUST also set this
* property to a valid guid.
+ *
* If you are constructing a #GDBusConnection and pass
* %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
* #GDBusConnection:flags property you will be able to read the GUID
@@ -1250,6 +1277,7 @@
* GDBusConnection:stream:
*
* The underlying #GIOStream used for I/O.
+ *
* If this is passed on construction and is a #GSocketConnection,
* then the corresponding #GSocket will be put into non-blocking mode.
*
@@ -1295,59 +1323,9 @@
/**
* GDBusError:
*
- * A generic error; "something went wrong" - see the error message for
- * more.
- * There was not enough memory to complete an operation.
- * The bus doesn't know how to launch a service to supply the bus name
- * you wanted.
- * The bus name you referenced doesn't exist (i.e. no application owns
- * it).
- * No reply to a message expecting one, usually means a timeout occurred.
- * Something went wrong reading or writing to a socket, for example.
- * A D-Bus bus address was malformed.
- * Requested operation isn't supported (like ENOSYS on UNIX).
- * Some limited resource is exhausted.
- * Security restrictions don't allow doing what you're trying to do.
- * Authentication didn't work.
- * Unable to connect to server (probably caused by ECONNREFUSED on a
- * socket).
- * Certain timeout errors, possibly ETIMEDOUT on a socket. Note that
- * %G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning:
- * this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also
- * exists. We can't fix it for compatibility reasons so just be
- * careful.
- * No network access (probably ENETUNREACH on a socket).
- * Can't bind a socket since its address is in use (i.e. EADDRINUSE).
- * The connection is disconnected and you're trying to use it.
- * Invalid arguments passed to a method call.
- * Missing file.
- * Existing file and the operation you're using does not silently overwrite.
- * Method name you invoked isn't known by the object you invoked it on.
- * confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We
- * can't fix it for compatibility reasons so just be careful.
- * Tried to remove or modify a match rule that didn't exist.
- * The match rule isn't syntactically valid.
- * While starting a new process, the exec() call failed.
- * While starting a new process, the fork() call failed.
- * While starting a new process, the child exited with a status code.
- * While starting a new process, the child exited on a signal.
- * While starting a new process, something went wrong.
- * We failed to setup the environment correctly.
- * We failed to setup the config parser correctly.
- * Bus name was not valid.
- * Service file not found in system-services directory.
- * Permissions are incorrect on the setuid helper.
- * Service file invalid (Name, User or Exec missing).
- * Tried to get a UNIX process ID and it wasn't available.
- * Tried to get a UNIX process ID and it wasn't available.
- * A type signature is not valid.
- * A file contains invalid syntax or is otherwise broken.
- * Asked for SELinux security context and it wasn't available.
- * Asked for ADT audit data and it wasn't available.
- * There's already an object with the requested object path.
+ * Certain timeout errors, e.g. while starting a service. Warning: this is
* Error codes for the %G_DBUS_ERROR error domain.
*
- * Certain timeout errors, e.g. while starting a service. warning: this is
* Since: 2.26
*/
@@ -1383,6 +1361,8 @@
* @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
*
* The type of the @get_property function in #GDBusInterfaceVTable.
+ *
+ * @error is set. If the returned #GVariant is floating, it is
* consumed - otherwise its reference count is decreased by one.
*
* Returns: A #GVariant with the value for @property_name or %NULL if
@@ -1470,6 +1450,7 @@
*
* Emitted when a method is invoked by a remote caller and used to
* determine if the method call is authorized.
+ *
* Note that this signal is emitted in a thread dedicated to
* handling the method call so handlers are allowed to perform
* blocking IO. This means that it is appropriate to call
@@ -1477,15 +1458,21 @@
* url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync";>polkit_authority_check_authorization_sync()</ulink>
* with the <ulink
* url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS";>POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION</ulink> flag set.
+ *
* If %FALSE is returned then no further handlers are run and the
* signal handler must take a reference to @invocation and finish
* handling the call (e.g. return an error via
* g_dbus_method_invocation_return_error()).
+ *
* Otherwise, if %TRUE is returned, signal emission continues. If no
* handlers return %FALSE, then the method is dispatched. If
+ * @interface has an enclosing #GDBusObjectSkeleton, then the
* #GDBusObjectSkeleton::authorize-method signal handlers run before
* the handlers for this signal.
+ *
* The default class handler just returns %TRUE.
+ *
+ * Please note that the common case is optimized: if no signals
* handlers are connected and the default class handler isn't
* overridden (for both @interface and the enclosing
* #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
@@ -1495,7 +1482,6 @@
* handled in the same thread as the object that @interface belongs
* to was exported in.
*
- * Please note that the common case is optimized: if no signals
* Returns: %TRUE if the call is authorized, %FALSE otherwise.
* Since: 2.30
*/
@@ -1544,6 +1530,7 @@
*
* Virtual table for handling properties and method calls for a D-Bus
* interface.
+ *
* If you want to handle getting/setting D-Bus properties asynchronously, simply
* register an object with the <literal>org.freedesktop.DBus.Properties</literal>
* D-Bus interface using g_dbus_connection_register_object().
@@ -1590,6 +1577,7 @@
* @user_data: User data passed when adding the filter.
*
* Signature for function used in g_dbus_connection_add_filter().
+ *
* A filter function is passed a #GDBusMessage and expected to return
* a #GDBusMessage too. Passive filter functions that don't modify the
* message can simply return the @message object:
@@ -1630,11 +1618,14 @@
* {
* GDBusMessage *copy;
* GError *error;
+ *
* error = NULL;
* copy = g_dbus_message_copy (message, &error);
* /<!-- -->* handle @error being is set *<!-- -->/
* g_object_unref (message);
+ *
* /<!-- -->* modify @copy *<!-- -->/
+ *
* return copy;
* }
* ]|
@@ -1644,6 +1635,7 @@
* logged to <emphasis>standard error</emphasis>. Applications can
* check this ahead of time using g_dbus_message_to_blob() passing a
* #GDBusCapabilityFlags value obtained from @connection.
+ *
* g_object_unref() or %NULL to drop the message. Passive filter
* functions can simply return the passed @message object.
*
@@ -1788,6 +1780,7 @@
* @interface: The #GDBusInterface that was added.
*
* Emitted when @interface is added to @object.
+ *
* This signal exists purely as a convenience to avoid having to
* connect signals to all objects managed by @manager.
*
@@ -1802,6 +1795,7 @@
* @interface: The #GDBusInterface that was removed.
*
* Emitted when @interface has been removed from @object.
+ *
* This signal exists purely as a convenience to avoid having to
* connect signals to all objects managed by @manager.
*
@@ -1853,8 +1847,10 @@
* local cache has already been updated when this signal fires. Note
* that both @changed_properties and @invalidated_properties are
* guaranteed to never be %NULL (either may be empty though).
+ *
* This signal exists purely as a convenience to avoid having to
* connect signals to all interface proxies managed by @manager.
+ *
* This signal is emitted in the
* <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
* that @manager was constructed in.
@@ -1873,8 +1869,10 @@
* @parameters: A #GVariant tuple with parameters for the signal.
*
* Emitted when a D-Bus signal is received on @interface_proxy.
+ *
* This signal exists purely as a convenience to avoid having to
* connect signals to all interface proxies managed by @manager.
+ *
* This signal is emitted in the
* <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
* that @manager was constructed in.
@@ -2105,9 +2103,11 @@
*
* Emitted when a method is invoked by a remote caller and used to
* determine if the method call is authorized.
+ *
* This signal is like #GDBusInterfaceSkeleton<!-- -->'s
* #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is
* for the enclosing object.
+ *
* The default class handler just returns %TRUE.
*
* Returns: %TRUE if the call is authorized, %FALSE otherwise.
@@ -2181,6 +2181,7 @@
* local cache has already been updated when this signal fires. Note
* that both @changed_properties and @invalidated_properties are
* guaranteed to never be %NULL (either may be empty though).
+ *
* This signal corresponds to the
* <literal>PropertiesChanged</literal> D-Bus signal on the
* <literal>org.freedesktop.DBus.Properties</literal> interface.
@@ -2229,6 +2230,7 @@
* The timeout to use if -1 (specifying default timeout) is passed
* as @timeout_msec in the g_dbus_proxy_call() and
* g_dbus_proxy_call_sync() functions.
+ *
* This allows applications to set a proxy-wide timeout for all
* remote method invocations on the proxy. If this property is -1,
* the default timeout (typically 25 seconds) is used. If set to
@@ -2332,9 +2334,11 @@
* Function signature for a function used to determine the #GType to
* use for an interface proxy (if @interface_name is not %NULL) or
* object proxy (if @interface_name is %NULL).
+ *
* This function is called in the
* <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
* that @manager was constructed in.
+ *
* must be a #GDBusProxy<!-- -->- or #GDBusObjectProxy<!-- -->-derived
* type.
*
@@ -2372,20 +2376,25 @@
* Emitted when a new authenticated connection has been made. Use
* g_dbus_connection_get_peer_credentials() to figure out what
* identity (if any), was authenticated.
+ *
* If you want to accept the connection, take a reference to the
+ * @connection object and return %TRUE. When you are done with the
* connection call g_dbus_connection_close() and give up your
* reference. Note that the other peer may disconnect at any time -
* a typical thing to do when accepting a connection is to listen to
* the #GDBusConnection::closed signal.
+ *
* If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
* then the signal is emitted in a new thread dedicated to the
* connection. Otherwise the signal is emitted in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread that @server was constructed in.
+ *
* You are guaranteed that signal handlers for this signal runs
* before incoming messages on @connection are processed. This means
* that it's suitable to call g_dbus_connection_register_object() or
* similar from the signal handler.
+ *
* run.
*
* Returns: %TRUE to claim @connection, %FALSE to let other handlers
@@ -2520,9 +2529,10 @@
* @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
*
* The type of the @dispatch function in #GDBusSubtreeVTable.
+ *
* Subtrees are flat. @node, if non-%NULL, is always exactly one
+ * segment of the object path (ie: it never contains a slash).
*
- * Segment of the object path (ie: it never contains a slash).
* Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
* Since: 2.26
*/
@@ -2536,14 +2546,17 @@
* @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
*
* The type of the @enumerate function in #GDBusSubtreeVTable.
+ *
* This function is called when generating introspection data and also
* when preparing to dispatch incoming messages in the event that the
* %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
+ * specified (ie: to verify that the object path is valid).
+ *
* Hierarchies are not supported; the items that you return should not
* contain the '/' character.
+ *
* The return value will be freed with g_strfreev().
*
- * Specified (ie: to verify that the object path is valid).
* Returns: A newly allocated array of strings for node names that are children of @object_path.
* Since: 2.26
*/
@@ -2569,20 +2582,24 @@
* @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
*
* The type of the @introspect function in #GDBusSubtreeVTable.
+ *
* Subtrees are flat. @node, if non-%NULL, is always exactly one
+ * segment of the object path (ie: it never contains a slash).
+ *
* This function should return %NULL to indicate that there is no object
* at this node.
+ *
* If this function returns non-%NULL, the return value is expected to
* be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
* structures describing the interfaces implemented by @node. This
* array will have g_dbus_interface_info_unref() called on each item
* before being freed with g_free().
+ *
* The difference between returning %NULL and an array containing zero
* items is that the standard DBus interfaces will returned to the
* remote introspector in the empty array case, but not in the %NULL
* case.
*
- * Segment of the object path (ie: it never contains a slash).
* Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
* Since: 2.26
*/
@@ -2976,6 +2993,7 @@
*
* A subclass of GIOStream for opened files. This adds
* a few file-specific operations and seeking and truncating.
+ *
* #GFileIOStream implements GSeekable.
*/
@@ -3114,6 +3132,7 @@
*
* A subclass of GInputStream for opened files. This adds
* a few file-specific operations and seeking.
+ *
* #GFileInputStream implements #GSeekable.
*/
@@ -3133,9 +3152,11 @@
* @event_type: a #GFileMonitorEvent.
*
* Emitted when @file has been changed.
+ *
* If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is
* #G_FILE_MONITOR_SEND_MOVED, @file will be set to a #GFile containing the
* old path, and @other_file will be set to a #GFile containing the new path.
+ *
* In all the other cases, @other_file will be set to #NULL.
*/
@@ -3170,6 +3191,7 @@
*
* A subclass of GOutputStream for opened files. This adds
* a few file-specific operations and seeking and truncating.
+ *
* #GFileOutputStream implements GSeekable.
*/
@@ -3298,6 +3320,17 @@
/**
+ * GHmac:
+ *
+ * An opaque structure representing a HMAC operation.
+ * To create a new GHmac, use g_hmac_new(). To free
+ * a GHmac, use g_hmac_unref().
+ *
+ * Since: 2.30
+ */
+
+
+/**
* GIOErrorEnum:
* @G_IO_ERROR_FAILED: Generic error condition for when any operation fails.
* @G_IO_ERROR_NOT_FOUND: File not found error.
@@ -3369,11 +3402,14 @@
* @user_data: the data to pass to callback function
*
* I/O Job function.
+ *
* Note that depending on whether threads are available, the
* #GIOScheduler may run jobs in separate threads or in an idle
* in the mainloop.
+ *
* Long-running jobs should periodically check the @cancellable
* to see if they have been cancelled.
+ *
* complete the job, %FALSE if the job is complete (or cancelled)
*
* Returns: %TRUE if this function should be called again to
@@ -3659,6 +3695,7 @@
*
* Checks the version of the GLib library that is being compiled
* against.
+ *
* <example>
* <title>Checking the version of the GLib library</title>
* <programlisting>
@@ -3666,7 +3703,9 @@
* g_error ("GLib version 1.2.0 or above is needed");
* </programlisting>
* </example>
+ *
* See glib_check_version() for a runtime check.
+ *
* is the same as or newer than the passed-in version.
*
* Returns: %TRUE if the version of the GLib header files
@@ -3727,6 +3766,7 @@
*
* A parse context is used to parse a stream of bytes that
* you expect to contain marked-up text.
+ *
* See g_markup_parse_context_new(), #GMarkupParser, and so
* on for more details.
*/
@@ -3925,6 +3965,7 @@
*
* Emitted by the backend when e.g. a device becomes unavailable
* while a mount operation is in progress.
+ *
* Implementations of GMountOperation should handle this signal
* by dismissing open password dialogs.
*
@@ -3941,6 +3982,7 @@
* @flags: a set of #GAskPasswordFlags.
*
* Emitted when a mount operation asks the user for a password.
+ *
* If the message contains a line break, the first line should be
* presented as a heading. For example, it may be used as the
* primary text in a #GtkMessageDialog.
@@ -3955,6 +3997,7 @@
*
* Emitted when asking the user a question and gives a list of
* choices for the user to choose from.
+ *
* If the message contains a line break, the first line should be
* presented as a heading. For example, it may be used as the
* primary text in a #GtkMessageDialog.
@@ -3979,11 +4022,13 @@
*
* Emitted when one or more processes are blocking an operation
* e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
+ *
* Note that this signal may be emitted several times to update the
* list of blocking processes as processes close files. The
* application should only respond with g_mount_operation_reply() to
* the latest signal (setting #GMountOperation:choice to the choice
* the user made).
+ *
* If the message contains a line break, the first line should be
* presented as a heading. For example, it may be used as the
* primary text in a #GtkMessageDialog.
@@ -4103,7 +4148,7 @@
/**
* GObjectClass:
* @g_type_class: the parent class
- * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons.
+ * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the @constructor of the parent class. Overriding @constructor should be rarely needed, e.g. to handle construct properties, or to implement singletons.
* @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system.
* @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties.
* @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class.
@@ -4113,16 +4158,19 @@
* @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation.
*
* The class structure for the <structname>GObject</structname> type.
+ *
* <example>
* <title>Implementing singletons using a constructor</title>
* <programlisting>
* static MySingleton *the_singleton = NULL;
+ *
* static GObject*
* my_singleton_constructor (GType type,
* guint n_construct_params,
* GObjectConstructParam *construct_params)
* {
* GObject *object;
+ *
* if (!the_singleton)
* {
* object = G_OBJECT_CLASS (parent_class)->constructor (type,
@@ -4132,6 +4180,7 @@
* }
* else
* object = g_object_ref (G_OBJECT (the_singleton));
+ *
* return object;
* }
* </programlisting></example>
@@ -4195,8 +4244,7 @@
* options expect to find. If an option expects an extra argument, it
* can be specified in several ways; with a short option:
* <option>-x arg</option>, with a long option: <option>--name arg</option>
- *
- * Or combined in a single argument: <option>--name=arg</option>.
+ * or combined in a single argument: <option>--name=arg</option>.
*/
@@ -4209,6 +4257,7 @@
*
* The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
* options.
+ *
* occurred, in which case @error should be set with g_set_error()
*
* Returns: %TRUE if the option was successfully parsed, %FALSE if an error
@@ -4280,6 +4329,7 @@
*
* A <structname>GOptionGroup</structname> struct defines the options in a single
* group. The struct has only private fields and should not be directly accessed.
+ *
* All options in a group share the same translation function. Libraries which
* need to parse commandline options are expected to provide a function for
* getting a <structname>GOptionGroup</structname> holding their options, which
@@ -4295,6 +4345,7 @@
* @error: A return location for error details
*
* The type of function that can be called before and after parsing.
+ *
* occurred, in which case @error should be set with g_set_error()
*
* Returns: %TRUE if the function completed successfully, %FALSE if an error
@@ -4305,6 +4356,7 @@
* GOutputStream:
*
* Base class for writing output.
+ *
* All classes derived from GOutputStream should implement synchronous
* writing, splicing, flushing and closing streams, but may implement
* asynchronous versions.
@@ -4668,6 +4720,7 @@
* @G_PASSWORD_SAVE_PERMANENTLY: save a password permanently.
*
* #GPasswordSave is used to indicate the lifespan of a saved password.
+ *
* #Gvfs stores passwords in the Gnome keyring when this flag allows it
* to, and later retrieves it again from there.
*/
@@ -4685,6 +4738,7 @@
* GPermission:allowed:
*
* %TRUE if the caller currently has permission to perform the action that
+ * @permission represents the permission to perform.
*/
@@ -4708,6 +4762,7 @@
* GPid:
*
* A type which is used to hold a process identification.
+ *
* On UNIX, processes are identified by a process id (an integer),
* while Windows uses process handles (which are pointers).
*/
@@ -4731,6 +4786,7 @@
*
* Specifies the type of function passed to g_main_context_set_poll_func().
* The semantics of the function should match those of the poll() system call.
+ *
* reported, or -1 if an error occurred.
*
* Returns: the number of #GPollFD elements which have events or errors
@@ -4755,7 +4811,9 @@
* @read_nonblocking: Does a non-blocking read or returns %G_IO_ERROR_WOULD_BLOCK
*
* The interface for pollable input streams.
+ *
* The default implementation of @can_poll always returns %TRUE.
+ *
* The default implementation of @read_nonblocking calls
* g_pollable_input_stream_is_readable(), and then calls
* g_input_stream_read() if it returns %TRUE. This means you only need
@@ -4785,7 +4843,9 @@
* @write_nonblocking: Does a non-blocking write or returns %G_IO_ERROR_WOULD_BLOCK
*
* The interface for pollable output streams.
+ *
* The default implementation of @can_poll always returns %TRUE.
+ *
* The default implementation of @write_nonblocking calls
* g_pollable_output_stream_is_writable(), and then calls
* g_output_stream_write() if it returns %TRUE. This means you only
@@ -4884,6 +4944,8 @@
* @size: size to reallocate @data to
*
* Changes the size of the memory block pointed to by @data to
+ * @size bytes.
+ *
* The function should have the same semantics as realloc().
*
* Returns: a pointer to the reallocated memory
@@ -4909,8 +4971,7 @@
* @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
* @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set.
* @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern.
- * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes.
- * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
+ * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
* @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches.
* @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched.
* @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
@@ -4983,6 +5044,7 @@
* Specifies the type of the function passed to g_regex_replace_eval().
* It is called for each occurance of the pattern in the string passed
* to g_regex_replace_eval(), and it should append the replacement to
+ * @result.
*
* Returns: %FALSE to continue the replacement process, %TRUE to stop it
* Since: 2.14
@@ -5069,15 +5131,16 @@
* only if you are interested in viewing groups of changes before they
* are split out into multiple emissions of the "changed" signal.
* For most use cases it is more appropriate to use the "changed" signal.
+ *
* In the event that the change event applies to one or more specified
* keys, @keys will be an array of #GQuark of length @n_keys. In the
* event that the change event applies to the #GSettings object as a
+ * whole (ie: potentially every key has been changed) then @keys will
* be %NULL and @n_keys will be 0.
+ *
* The default handler for this signal invokes the "changed" signal
* for each affected key. If any other connected handler returns
* %TRUE then this default functionality will be supressed.
- *
- * Whole (ie: potentially every key has been changed) then @keys will
*/
@@ -5089,6 +5152,7 @@
* The "changed" signal is emitted when a key has potentially changed.
* You should call one of the g_settings_get() calls to check the new
* value.
+ *
* This signal supports detailed connections. You can connect to the
* detailed signal "changed::x" in order to only receive callbacks
* when key "x" changes.
@@ -5107,9 +5171,12 @@
* before they are split out into multiple emissions of the
* "writable-changed" signal. For most use cases it is more
* appropriate to use the "writable-changed" signal.
+ *
* In the event that the writability change applies only to a single
* key, @key will be set to the #GQuark for that key. In the event
* that the writability change affects the entire settings object,
+ * @key will be 0.
+ *
* The default handler for this signal invokes the "writable-changed"
* and "changed" signals for each affected key. This is done because
* changes in writability might also imply changes in value (if for
@@ -5127,6 +5194,7 @@
* The "writable-changed" signal is emitted when the writability of a
* key has potentially changed. You should call
* g_settings_is_writable() in order to determine the new status.
+ *
* This signal supports detailed connections. You can connect to the
* detailed signal "writable-changed::x" in order to only receive
* callbacks when the writability of "x" changes.
@@ -5229,8 +5297,11 @@
*
* The type of the function that is used to convert from a value stored
* in a #GSettings to a value that is useful to the application.
+ *
* If the value is successfully mapped, the result should be stored at
+ * @result and %TRUE returned. If mapping fails (for example, if @value
* is not in the right format) then %FALSE should be returned.
+ *
* If @value is %NULL then it means that the mapping function is being
* given a "last chance" to successfully return a valid value. %TRUE
* must be returned in this case.
@@ -5250,6 +5321,7 @@
* creation time, if it is left %NULL, no accumulation of callback return
* values is performed. The return value of signal emissions is then the
* value returned by the last callback.
+ *
* should be aborted. Returning %FALSE means to abort the
* current emission and %TRUE is returned for continuation.
*
@@ -5278,7 +5350,9 @@
* A simple function pointer to get invoked when the signal is emitted. This
* allows you to tie a hook to the signal type, so that it will trap all
* emissions of that signal, from any object.
+ *
* You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
+ *
* hook is disconnected (and destroyed).
*
* Returns: whether it wants to stay connected. If it returns %FALSE, the signal
@@ -5336,7 +5410,7 @@
* @signal_flags: The signal flags as passed in to g_signal_new().
* @return_type: The return type for user callbacks.
* @n_params: The number of parameters that user callbacks take.
- * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting>
+ * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> @return_type callback (#gpointer data1, [#param_types param_names,] #gpointer data2); </programlisting>
*
* A structure holding in-depth information for a specific signal. It is
* filled in by the g_signal_query() function.
@@ -5349,6 +5423,8 @@
* @parameter: (allow-none): the parameter to the activation
*
* Indicates that the action was just activated.
+ *
+ * @parameter will always be of the expected type. In the event that
* an incorrect type was given, no signal will be emitted.
*
* Since: 2.28
@@ -5362,12 +5438,16 @@
*
* Indicates that the action just received a request to change its
* state.
+ *
+ * @value will always be of the correct state type. In the event that
* an incorrect type was given, no signal will be emitted.
+ *
* If no handler is connected to this signal then the default
* behaviour is to call g_simple_action_set_state() to set the state
* to the requested value. If you connect a signal handler then no
* default action is taken. If the state should change then you must
* call g_simple_action_set_state() from the handler.
+ *
* <example>
* <title>Example 'change-state' handler</title>
* <programlisting>
@@ -5377,13 +5457,16 @@
* gpointer user_data)
* {
* gint requested;
+ *
* requested = g_variant_get_int32 (value);
+ *
* // Volume only goes from 0 to 10
* if (0 <= requested && requested <= 10)
* g_simple_action_set_state (action, value);
* }
* </programlisting>
* </example>
+ *
* The handler need not set the state to the requested value. It
* could set it to any value at all, or take some other action.
*
@@ -5395,6 +5478,7 @@
* GSimpleAction:enabled:
*
* If @action is currently enabled.
+ *
* If the action is disabled then calls to g_simple_action_activate() and
* g_simple_action_change_state() have no effect.
*
@@ -5617,6 +5701,7 @@
* A protocol identifier is specified when creating a #GSocket, which is a
* family/type specific identifier, where 0 means the default protocol for
* the particular family/type.
+ *
* This enum contains a set of commonly available and used protocols. You
* can also pass any other identifiers handled by the platform in order to
* use protocols not listed here.
@@ -5645,6 +5730,8 @@
* to @service needs to be handled. The handler must initiate the
* handling of @connection, but may not block; in essence,
* asynchronous operations must be used.
+ *
+ * @connection will be unreffed once the signal handler returns,
* so you need to ref it yourself if you are planning to use it.
*
* Returns: %TRUE to stop other handlers from being called
@@ -5700,10 +5787,9 @@
* GSourceCallbackFuncs:
* @ref: Called when a reference is added to the callback object
* @unref: Called when a reference to the callback object is dropped
- * @get: Called to extract the callback function and data from the callback object.
+ * @get: Called to extract the callback function and data from the callback object. The <structname>GSourceCallbackFuncs</structname> struct contains functions for managing callback objects.
+ *
*
- * The <structname>GSourceCallbackFuncs</structname> struct contains
- * functions for managing callback objects.
*/
@@ -5728,22 +5814,25 @@
/**
* GSourceFuncs:
- * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the
+ * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the @timeout_ values returned which were >= 0.
* @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here.
* @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source.
* @finalize: Called when the source is finalized.
*
* The <structname>GSourceFuncs</structname> struct contains a table of
* functions used to handle event sources in a generic manner.
+ *
* For idle sources, the prepare and check functions always return %TRUE
* to indicate that the source is always ready to be processed. The prepare
* function also returns a timeout value of 0 to ensure that the poll() call
* doesn't block (since that would be time wasted which could have been spent
* running the idle function).
+ *
* For timeout sources, the prepare and check functions both return %TRUE
* if the timeout interval has expired. The prepare function also returns
* a timeout value to ensure that the poll() call doesn't block too long
* and miss the next timeout.
+ *
* For file descriptor sources, the prepare function typically returns %FALSE,
* since it must wait until poll() has been called before it knows whether
* any events need to be processed. It sets the returned timeout to -1 to
@@ -5762,12 +5851,15 @@
* is called in the child after GLib has performed all the setup it plans
* to perform but before calling exec(). On POSIX actions taken in this
* function will thus only affect the child, not the parent.
+ *
* Note that POSIX allows only async-signal-safe functions (see signal(7))
* to be called in the child between fork() and exec(), which drastically
* limits the usefulness of child setup functions.
+ *
* Also note that modifying the environment from the child setup function
* may not have the intended effect, since it will get overridden by
* a non-%NULL @env argument to the <literal>g_spawn...</literal> functions.
+ *
* On Windows the function is called in the parent. Its usefulness on
* Windows is thus questionable. In many cases executing the child setup
* function in the parent can have ill effects, and you should be very
@@ -5891,6 +5983,7 @@
* Whether to use the default fallbacks found by shortening the icon name
* at '-' characters. If the "names" array has more than one element,
* ignores any past the first.
+ *
* For example, if the icon name was "gnome-dev-cdrom-audio", the array
* would become
* |[
@@ -5923,6 +6016,7 @@
*
* The ::run signal is emitted in a worker thread in response to an
* incoming connection. This thread is dedicated to handling
+ * @connection and may perform blocking IO. The signal handler need
* not return until the connection is closed.
*
* Returns: %TRUE to stop further signal handlers from being called
@@ -5945,7 +6039,9 @@
* @G_TIME_TYPE_UNIVERSAL: the time is in UTC
*
* Disambiguates a given time in two ways.
+ *
* First, specifies if the given time is in universal or local time.
+ *
* Second, if the time is in local time, specifies if it is local
* standard time or local daylight time. This is important for the case
* where the same local time occurs twice (during daylight savings time
@@ -5965,9 +6061,11 @@
* @monitor: the #GTimeZoneMonitor
*
* Indicates that the local timezone has changed.
+ *
* The g_time_zone_refresh_local() function is called just before this
* signal is emitted, so any new #GTimeZone or #GDateTime instances
* created from signal handlers will be as per the new timezone.
+ *
* Note that this signal is not emitted in response to entering or
* exiting daylight savings time within a given timezone. It's only
* for when the user has changed the timezone to that of a different
@@ -6001,9 +6099,12 @@
/**
* GTlsBackendInterface:
* @g_iface: The parent interface.
+ * @supports_tls: returns whether the backend supports TLS.
+ * @get_default_database: returns a default #GTlsDatabase instance.
* @get_certificate_type: returns the #GTlsCertificate implementation type
* @get_client_connection_type: returns the #GTlsClientConnection implementation type
* @get_server_connection_type: returns the #GTlsServerConnection implementation type
+ * @get_file_database_type: returns the #GTlsFileDatabase implementation type.
*
* Provides an interface for describing TLS-related types.
*
@@ -6117,6 +6218,7 @@
* that the server will accept client certificates signed by. If the
* server requests a client certificate during the handshake, then
* this property will be set after the handshake completes.
+ *
* Each item in the list is a #GByteArray which contains the complete
* subject DN of the certificate authority.
*
@@ -6129,12 +6231,14 @@
*
* A #GSocketConnectable describing the identity of the server that
* is expected on the other end of the connection.
+ *
* If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
* #GTlsClientConnection:validation-flags, this object will be used
* to determine the expected identify of the remote end of the
* connection; if #GTlsClientConnection:server-identity is not set,
* or does not match the identity presented by the server, then the
* %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
+ *
* In addition to its use in verifying the server certificate,
* this is also used to give a hint to the server about what
* certificate we expect, which is useful for servers that serve
@@ -6188,6 +6292,7 @@
* Emitted during the TLS handshake after the peer certificate has
* been received. You can examine @peer_cert's certification path by
* calling g_tls_certificate_get_issuer() on it.
+ *
* For a client-side connection, @peer_cert is the server's
* certificate, and the signal will only be emitted if the
* certificate was not acceptable according to @conn's
@@ -6195,12 +6300,14 @@
* certificate to be accepted despite @errors, return %TRUE from the
* signal handler. Otherwise, if no handler accepts the certificate,
* the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
+ *
* For a server-side connection, @peer_cert is the certificate
* presented by the client, if this was requested via the server's
* #GTlsServerConnection:authentication_mode. On the server side,
* the signal is always emitted when the client presents a
* certificate, and the certificate will only be accepted if a
* handler returns %TRUE.
+ *
* Note that if this signal is emitted as part of asynchronous I/O
* in the main thread, then you should not attempt to interact with
* the user before returning from the signal handler. If you want to
@@ -6211,9 +6318,11 @@
* the user decides to accept the certificate, remember that fact,
* create a new connection, and return %TRUE from the signal handler
* the next time.
+ *
* If you are doing I/O in another thread, you do not
* need to worry about this, and can simply block in the signal
* handler until the UI thread returns an answer.
+ *
* immediately end the signal emission). %FALSE to allow the signal
* emission to continue, which will cause the handshake to fail if
* no one else overrides it.
@@ -6243,12 +6352,35 @@
/**
+ * GTlsConnection:database:
+ *
+ * The certificate database to use when verifying this TLS connection.
+ * If no cerificate database is set, then the default database will be
+ * used. See g_tls_backend_get_default_database().
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GTlsConnection:interaction:
+ *
+ * A #GTlsInteraction object to be used when the connection or certificate
+ * database need to interact with the user. This will be used to prompt the
+ * user for passwords where necessary.
+ *
+ * Since: 2.30
+ */
+
+
+/**
* GTlsConnection:peer-certificate:
*
* The connection's peer's certificate, after the TLS handshake has
* completed and the certificate has been accepted. Note in
* particular that this is not yet set during the emission of
* #GTlsConnection::accept-certificate.
+ *
* (You can watch for a #GObject::notify signal on this property to
* detect when a handshake has occurred.)
*
@@ -6297,7 +6429,38 @@
* verify peer certificates. See
* g_tls_connection_set_use_system_certdb().
*
- * Since: 2.28
+ * Deprecated: 2.30: Use GTlsConnection:database instead
+ */
+
+
+/**
+ * GTlsDatabase:
+ *
+ * Abstract base class for the backend-specific database types.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GTlsDatabaseLookupFlags:
+ * @G_TLS_DATABASE_LOOKUP_NONE: No lookup flags
+ * @G_TLS_DATABASE_LOOKUP_KEYPAIR: Restrict lookup to certificates that have a private key.
+ *
+ * Flags for g_tls_database_lookup_handle(), g_tls_database_lookup_issuer(),
+ * and g_tls_database_lookup_issued().
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GTlsDatabaseVerifyFlags:
+ * @G_TLS_DATABASE_VERIFY_NONE: No verification flags
+ *
+ * Flags for g_tls_database_verify_chain().
+ *
+ * Since: 2.30
*/
@@ -6319,6 +6482,91 @@
/**
+ * GTlsFileDatabase:
+ *
+ * Implemented by a #GTlsDatabase which allows you to load certificates
+ * from a file.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GTlsFileDatabase:anchors:
+ *
+ * The path to a file containing PEM encoded certificate authority
+ * root anchors. The certificates in this file will be treated as
+ * root authorities for the purpose of verifying other certificates
+ * via the g_tls_database_verify_chain() operation.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GTlsFileDatabaseInterface:
+ * @g_iface: The parent interface.
+ *
+ * Provides an interface for #GTlsFileDatabase implementations.
+ */
+
+
+/**
+ * GTlsInteraction:
+ *
+ * An object representing interaction that the TLS connection and database
+ * might have with the user.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GTlsInteractionClass:
+ *
+ * The class for #GTlsInteraction.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GTlsInteractionResult:
+ * @G_TLS_INTERACTION_HANDLED: The interaction completed, and resulting data is available.
+ * @G_TLS_INTERACTION_ABORTED: The user cancelled the interaction, and requested the operation to be aborted.
+ * @G_TLS_INTERACTION_UNHANDLED: The interaction was unhandled (i.e. not implemented).
+ *
+ * #GTlsInteractionResult is returned by various functions in #GTlsInteraction
+ * when finishing an interaction request.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GTlsPassword:
+ *
+ * An abstract interface representing a password used in TLS. Often used in
+ * user interaction such as unlocking a key storage token.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * GTlsPasswordFlags:
+ * @G_TLS_PASSWORD_NONE: No flags
+ * @G_TLS_PASSWORD_RETRY: The password was wrong, and the user should retry.
+ * @G_TLS_PASSWORD_MANY_TRIES: Hint to the user that the password has been wrong many times, and the user may not have many chances left.
+ * @G_TLS_PASSWORD_FINAL_TRY: Hint to the user that this is the last try to get this password right.
+ *
+ * Various flags for the password.
+ *
+ * Since: 2.30
+ */
+
+
+/**
* GTlsRehandshakeMode:
* @G_TLS_REHANDSHAKE_NEVER: Never allow rehandshaking
* @G_TLS_REHANDSHAKE_SAFELY: Allow safe rehandshaking only
@@ -6370,6 +6618,7 @@
*
* The type of functions which are used to translate user-visible
* strings, for <option>--help</option> output.
+ *
* The returned string is owned by GLib and must not be freed.
*
* Returns: a translation of the string for the current locale.
@@ -6401,9 +6650,11 @@
* being freed. You should not call g_type_class_unref() from a
* #GTypeClassCacheFunc function to prevent infinite recursion, use
* g_type_class_unref_uncached() instead.
+ *
* The functions have to check the class id passed in to figure
* whether they actually want to cache the class of this type, since all
* classes are routed through the same #GTypeClassCacheFunc chain.
+ *
* called, %FALSE to continue.
*
* Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
@@ -6601,12 +6852,12 @@
* GTypeValueTable:
* @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]|
* @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]|
- * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
+ * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of @src_value into @dest_value in a way, that even after @src_value has been freed, the contents of @dest_value remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
* @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]|
* @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i
' needs to be used, and for collection of floats 'd'.
- * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_p
ointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour i
s undefined.
+ * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup @value similar to value_init(); e.g. for a string value that does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. @n_collect_values is exactly the string length of @collect_format, and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. @collect_flags is an argument provided as a hint by the caller. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @valu
e lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementatio
n for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, h
owever, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined.
* @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations.
- * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as
NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
+ * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. @n_collect_values equals the string length of @lcopy_format, and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (
!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
*
* The #GTypeValueTable provides the functions required by the #GValue implementation,
* to serve as a container for values of a type.
@@ -6654,10 +6905,12 @@
* @G_UNICODE_BREAK_CLOSE_PARANTHESIS: Closing Parenthesis (CP). Since 2.28
*
* These are the possible line break classifications.
+ *
* The five Hangul types were added in Unicode 4.1, so, has been
* introduced in GLib 2.10. Note that new types may be added in the future.
* Applications should be ready to handle unknown values.
* They may be regarded as %G_UNICODE_BREAK_UNKNOWN.
+ *
* See <ulink url="http://www.unicode.org/unicode/reports/tr14/";>http://www.unicode.org/unicode/reports/tr14/</ulink>.
*/
@@ -6751,11 +7004,11 @@
* @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28
* @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28
*
- * a value never returned from g_unichar_get_script()
* The #GUnicodeScript enumeration identifies different writing
* systems. The values correspond to the names as defined in the
* Unicode standard. The enumeration has been added in GLib 2.14,
* and is interchangeable with #PangoScript.
+ *
* Note that new types may be added in the future. Applications
* should be ready to handle unknown values.
* See <ulink
@@ -6876,6 +7129,7 @@
* GUnixSocketAddress:abstract:
*
* Whether or not this is an abstract address
+ *
* distinguishes between zero-padded and non-zero-padded
* abstract addresses.
*
@@ -6896,6 +7150,7 @@
* socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS
* indicates a socket not bound to any name (eg, a client-side socket,
* or a socket created with socketpair()).
+ *
* For abstract sockets, there are two incompatible ways of naming
* them; the man pages suggest using the entire <literal>struct
* sockaddr_un</literal> as the name, padding the unused parts of the
@@ -6924,6 +7179,7 @@
* These are logical ids for special directories which are defined
* depending on the platform used. You should use g_get_user_special_dir()
* to retrieve the full path associated to the logical id.
+ *
* The #GUserDirectory enumeration can be extended at later date. Not
* every platform has a directory for every logical id in this
* enumeration.
@@ -6936,14 +7192,13 @@
* GValue:
*
* An opaque structure used to hold different types of values.
+ * The data within the structure has protected scope: it is accessible only
* to functions within a #GTypeValueTable structure, or implementations of
* the g_value_*() API. That is, code portions which implement new fundamental
* types.
* #GValue users cannot make any assumptions about how data is stored
* within the 2 element @data union, and the @g_type member should
* only be accessed through the G_VALUE_TYPE() macro.
- *
- * The data within the structure has protected scope: it is accessible only
*/
@@ -6970,6 +7225,7 @@
* GVariantType:
*
* A type in the GVariant type system.
+ *
* Two types may not be compared by value; use g_variant_type_equal() or
* g_variant_type_is_subtype_of(). May be copied using
* g_variant_type_copy() and freed using g_variant_type_free().
@@ -7272,6 +7528,7 @@
* G_BREAKPOINT:
*
* Inserts a breakpoint instruction into the code.
+ *
* On x86 and alpha systems this is implemented as a soft interrupt
* and on other architectures it raises a %SIGTRAP signal.
*/
@@ -7302,6 +7559,8 @@
*
* Check if the closure still needs a marshaller. See g_closure_set_marshal().
*
+ * @closure.
+ *
* Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
*/
@@ -7344,6 +7603,7 @@
* Error domain for errors generated by a remote message bus. Errors
* in this domain will be from the #GDBusError enumeration. See
* #GError for more information on error domains.
+ *
* Note that errors in this error domain is intended only for
* returning errors from a remote message bus process. Errors
* generated locally in-process by e.g. #GDBusConnection is from the
@@ -7423,6 +7683,7 @@
* A convenience macro for dynamic type implementations, which declares a
* class initialization function, an instance initialization function (see
* #GTypeInfo for information about these) and a static variable named
+ * @t_n<!-- -->_parent_class pointing to the parent class. Furthermore,
* it defines a <function>*_get_type()</function> and a static
* <function>*_register_type()</function> function for use in your
* <function>module_init()</function>.
@@ -7442,6 +7703,7 @@
*
* A more general version of G_DEFINE_DYNAMIC_TYPE() which
* allows to specify #GTypeFlags and custom code.
+ *
* |[
* G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
* gtk_gadget,
@@ -7455,18 +7717,22 @@
* static void gtk_gadget_init (GtkGadget *self);
* static void gtk_gadget_class_init (GtkGadgetClass *klass);
* static void gtk_gadget_class_finalize (GtkGadgetClass *klass);
+ *
* static gpointer gtk_gadget_parent_class = NULL;
* static GType gtk_gadget_type_id = 0;
+ *
* static void gtk_gadget_class_intern_init (gpointer klass)
* {
* gtk_gadget_parent_class = g_type_class_peek_parent (klass);
* gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
+ *
* GType
* gtk_gadget_get_type (void)
* {
* return gtk_gadget_type_id;
* }
+ *
* static void
* gtk_gadget_register_type (GTypeModule *type_module)
* {
@@ -7509,6 +7775,7 @@
* A convenience macro for #GTypeInterface definitions, which declares
* a default vtable initialization function and defines a *_get_type()
* function.
+ *
* The macro expects the interface initialization function to have the
* name <literal>t_n ## _default_init</literal>, and the interface
* structure to have the name <literal>TN ## Interface</literal>.
@@ -7586,6 +7853,7 @@
*
* The most general convenience macro for type implementations, on which
* G_DEFINE_TYPE(), etc are based.
+ *
* |[
* G_DEFINE_TYPE_EXTENDED (GtkGadget,
* gtk_gadget,
@@ -7604,6 +7872,7 @@
* gtk_gadget_parent_class = g_type_class_peek_parent (klass);
* gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
+ *
* GType
* gtk_gadget_get_type (void)
* {
@@ -8032,6 +8301,7 @@
* UTF8). This is useful if you want to copy the file to another filesystem that
* might have a different encoding. If the filename is not a valid string in the
* encoding selected for the filesystem it is in then the copy name will not be set.
+ *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
@@ -8045,6 +8315,7 @@
* could be "filename (on hostname)" for a remote file or "filename (in trash)"
* for a file in the trash. This is useful for instance as the window title
* when displaying a directory or for a bookmarks menu.
+ *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
@@ -8067,6 +8338,7 @@
* used when you want to rename the file in the UI. The display name
* might contain information you don't want in the new filename (such as
* "(invalid unicode)" if the filename was in an invalid encoding).
+ *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*/
@@ -8228,6 +8500,7 @@
* A key in the "time" namespace for getting the time the file was last
* changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
* and contains the UNIX time since the file was last changed.
+ *
* This corresponds to the traditional UNIX ctime.
*/
@@ -8248,6 +8521,7 @@
* A key in the "time" namespace for getting the time the file was created.
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
* and contains the UNIX time since the file was created.
+ *
* This corresponds to the NTFS ctime.
*/
@@ -8446,6 +8720,7 @@
* A convenience macro to ease interface addition in the @_C_ section
* of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
* See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
* Note that this macro can only be used together with the G_DEFINE_TYPE_*
* macros, since it depends on variable names from those macros.
*
@@ -8461,6 +8736,7 @@
* A convenience macro to ease interface addition in the @_C_ section
* of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED()
* for an example.
+ *
* Note that this macro can only be used together with the
* G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
* names from that macro.
@@ -8833,6 +9109,7 @@
* @node: a #GNode
*
* Returns %TRUE if a #GNode is a leaf node.
+ *
* (i.e. it has no children)
*
* Returns: %TRUE if the #GNode is a leaf node
@@ -8844,6 +9121,7 @@
* @node: a #GNode
*
* Returns %TRUE if a #GNode is the root of a tree.
+ *
* (i.e. it has no parent or siblings)
*
* Returns: %TRUE if the #GNode is the root of a tree
@@ -8873,6 +9151,7 @@
* @class: a valid #GObjectClass
*
* Return the name of a class structure's type.
+ *
* should not be freed.
*
* Returns: Type name of @class. The string is owned by the type system and
@@ -8914,6 +9193,7 @@
* @object: Object to return the type name for.
*
* Get the name of an object's type.
+ *
* should not be freed.
*
* Returns: Type name of @object. The string is owned by the type system and
@@ -8948,6 +9228,8 @@
* otherwise be left in <literal>argv</literal>. The option must be of type
* %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
* or %G_OPTION_ARG_FILENAME_ARRAY.
+ *
+ *
* Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
* for leftover arguments has the advantage that GOption takes care of
* necessary encoding conversions for strings or filenames.
@@ -9213,6 +9495,7 @@
* G_PARAM_STATIC_STRINGS:
*
* #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
+ *
* Since 2.13.0
*/
@@ -9229,6 +9512,7 @@
* G_PRIORITY_DEFAULT:
*
* Use this for default priority event sources.
+ *
* In GLib this priority is used when adding timeout functions
* with g_timeout_add(). In GDK this priority is used for events
* from the X server.
@@ -9239,6 +9523,7 @@
* G_PRIORITY_DEFAULT_IDLE:
*
* Use this for default priority idle functions.
+ *
* In GLib this priority is used when adding idle functions with
* g_idle_add().
*/
@@ -9248,6 +9533,7 @@
* G_PRIORITY_HIGH:
*
* Use this for high priority event sources.
+ *
* It is not used within GLib or GTK+.
*/
@@ -9256,6 +9542,7 @@
* G_PRIORITY_HIGH_IDLE:
*
* Use this for high priority idle functions.
+ *
* GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
* and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
* done to ensure that any pending resizes are processed before any
@@ -9267,6 +9554,7 @@
* G_PRIORITY_LOW:
*
* Use this for very low priority background tasks.
+ *
* It is not used within GLib or GTK+.
*/
@@ -9296,6 +9584,7 @@
* macro before it can be used. This macro can be used to initialize
* a variable, but it cannot be assigned to a variable. In that case
* you have to use g_queue_init().
+ *
* |[
* GQueue my_queue = G_QUEUE_INIT;
* ]|
@@ -9351,6 +9640,7 @@
* This macro flags signal argument types for which the signal system may
* assume that instances thereof remain persistent across all signal emissions
* they are used in. This is only useful for non ref-counted, value-copy types.
+ *
* To flag a signal argument in this way, add
* <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
* of g_signal_new().
@@ -9430,6 +9720,22 @@
/**
+ * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
+ *
+ * The purpose used to verify the client certificate in a TLS connection.
+ * Used by TLS servers.
+ */
+
+
+/**
+ * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
+ *
+ * The purpose used to verify the server certificate in a TLS connection. This
+ * is the most common purpose in use. Used by TLS clients.
+ */
+
+
+/**
* G_TLS_ERROR:
*
* Error domain for TLS. Errors in this domain will be from the
@@ -9488,6 +9794,7 @@
* Checks that @g_class is a class structure of the type identified by @g_type
* and issues a warning if this is not the case. Returns @g_class casted
* to a pointer to @c_type.
+ *
* This macro should only be used in type implementations.
*/
@@ -9498,6 +9805,8 @@
* @g_type: The type to be checked.
*
* Checks if @g_class is a class structure of the type identified by
+ * @g_type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -9510,6 +9819,7 @@
*
* Checks if @instance is a valid #GTypeInstance structure,
* otherwise issues a warning and returns %FALSE.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -9525,6 +9835,7 @@
* Checks that @instance is an instance of the type identified by @g_type
* and issues a warning if this is not the case. Returns @instance casted
* to a pointer to @c_type.
+ *
* This macro should only be used in type implementations.
*/
@@ -9535,6 +9846,7 @@
* @g_type: The type to be checked
*
* Checks if @instance is an instance of the type identified by @g_type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -9547,6 +9859,7 @@
*
* Checks if @value has been initialized to hold values
* of a value type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -9560,6 +9873,7 @@
*
* Checks if @value has been initialized to hold values
* of type @g_type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -9575,6 +9889,7 @@
* Gets the private class structure for a particular type.
* The private structure must have been registered in the
* get_type() function with g_type_add_class_private().
+ *
* This macro should only be used in type implementations.
*
* Since: 2.24
@@ -9717,6 +10032,7 @@
* @g_class: Location of a valid #GTypeClass structure.
*
* Get the type identifier from a given @class structure.
+ *
* This macro should only be used in type implementations.
*
* Returns: the #GType
@@ -9728,6 +10044,7 @@
* @instance: Location of a valid #GTypeInstance structure.
*
* Get the type identifier from a given @instance structure.
+ *
* This macro should only be used in type implementations.
*
* Returns: the #GType
@@ -9739,6 +10056,7 @@
* @g_iface: Location of a valid #GTypeInterface structure.
*
* Get the type identifier from a given @interface structure.
+ *
* This macro should only be used in type implementations.
*
* Returns: the #GType
@@ -9818,8 +10136,10 @@
*
* Get the class structure of a given @instance, casted
* to a specified ancestor type @g_type of the instance.
+ *
* Note that while calling a GInstanceInitFunc(), the class pointer gets
* modified, so it might not always return the expected pointer.
+ *
* This macro should only be used in type implementations.
*
* Returns: a pointer to the class structure
@@ -9833,6 +10153,7 @@
* @c_type: The C type of the interface structure.
*
* Get the interface structure for interface @g_type of a given @instance.
+ *
* This macro should only be used in type implementations.
*
* Returns: a pointer to the interface structure
@@ -9848,6 +10169,7 @@
* Gets the private structure for a particular type.
* The private structure must have been registered in the
* class_init function with g_type_class_add_private().
+ *
* This macro should only be used in type implementations.
*
* Since: 2.4
@@ -10354,9 +10676,11 @@
* G_TYPE_STRV:
*
* The #GType for a boxed type holding a %NULL-terminated array of strings.
+ *
* The code fragments in the following example show the use of a property of
* type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
* and g_object_get().
+ *
* |[
* g_object_class_install_property (object_class,
* PROP_AUTHORS,
@@ -10365,8 +10689,10 @@
* _("List of authors"),
* G_TYPE_STRV,
* G_PARAM_READWRITE));
+ *
* gchar *authors[] = { "Owen", "Tim", NULL };
* g_object_set (obj, "authors", authors, NULL);
+ *
* gchar *writers[];
* g_object_get (obj, "authors", &writers, NULL);
* /* do something with writers */
@@ -10425,14 +10751,17 @@
* G_TYPE_VARIANT:
*
* The fundamental type corresponding to #GVariant.
+ *
* All floating #GVariant instances passed through the #GType system are
* consumed.
+ *
* Note that callbacks in closures, and signal handlers
* for signals of return type %G_TYPE_VARIANT, must never return floating
* variants.
- * with this fundamental type in 2.26.
*
* Note: GLib 2.24 did include a boxed type with this name. It was replaced
+ * with this fundamental type in 2.26.
+ *
* Since: 2.26
*/
@@ -10716,6 +11045,22 @@
/**
+ * G_VALUE_INIT:
+ *
+ * A #GValue must be initialized before it can be used.
+ * This macro can be used as initializer instead of an explicit
+ * <literal>{ 0 }</literal> when declaring a variable,
+ * but it cannot be assigned to a variable.
+ *
+ * |[
+ * GValue value = G_VALUE_INIT;
+ * ]|
+ *
+ * Since: 2.30
+ */
+
+
+/**
* G_VALUE_NOCOPY_CONTENTS:
*
* If passed to G_VALUE_COLLECT(), allocated data won't be copied
@@ -10751,8 +11096,10 @@
* Converts a string to a const #GVariantType. Depending on the
* current debugging level, this function may perform a runtime check
* to ensure that @string is a valid GVariant type string.
+ *
* It is always a programmer error to use this macro with an invalid
* type string.
+ *
* Since 2.24
*/
@@ -10845,6 +11192,7 @@
* The type of a 32bit signed integer value, that by convention, is used
* as an index into an array of file descriptors that are sent alongside
* a D-Bus message.
+ *
* If you are not interacting with D-Bus, then there is no reason to make
* use of this type.
*/
@@ -10886,6 +11234,7 @@
* The type of a D-Bus object reference. These are strings of a
* specific format used to identify objects at a given destination on
* the bus.
+ *
* If you are not interacting with D-Bus, then there is no reason to make
* use of this type. If you are, then the D-Bus specification contains a
* precise description of valid object paths.
@@ -10904,6 +11253,7 @@
*
* The type of a D-Bus type signature. These are strings of a specific
* format used as type signatures for D-Bus methods and messages.
+ *
* If you are not interacting with D-Bus, then there is no reason to make
* use of this type. If you are, then the D-Bus specification contains a
* precise description of valid signature strings.
@@ -11043,21 +11393,26 @@
* #GIOExtensionPoint provides a mechanism for modules to extend the
* functionality of the library or application that loaded it in an
* organized fashion.
+ *
* An extension point is identified by a name, and it may optionally
* require that any implementation must by of a certain type (or derived
* thereof). Use g_io_extension_point_register() to register an
* extension point, and g_io_extension_point_set_required_type() to
* set a required type.
+ *
* A module can implement an extension point by specifying the #GType
* that implements the functionality. Additionally, each implementation
* of an extension point has a name, and a priority. Use
* g_io_extension_point_implement() to implement an extension point.
+ *
* |[
* GIOExtensionPoint *ep;
+ *
* /* Register an extension point */
* ep = g_io_extension_point_register ("my-extension-point");
* g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
* ]|
+ *
* |[
* /* Implement an extension point */
* G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
@@ -11066,11 +11421,13 @@
* "my-example",
* 10);
* ]|
+ *
* It is up to the code that registered the extension point how
* it uses the implementations that have been associated with it.
* Depending on the use case, it may use all implementations, or
* only the one with the highest priority, or pick a specific
* one by name.
+ *
* To avoid opening all modules just to find out what extension
* points they implement, GIO makes use of a caching mechanism,
* see <link linkend="gio-querymodules">gio-querymodules</link>.
@@ -11085,26 +11442,32 @@
* @short_description: An action
*
* #GAction represents a single named action.
+ *
* The main interface to an action is that it can be activated with
* g_action_activate(). This results in the 'activate' signal being
* emitted. An activation has a #GVariant parameter (which may be
* %NULL). The correct type for the parameter is determined by a static
* parameter type (which is given at construction time).
+ *
* An action may optionally have a state, in which case the state may be
* set with g_action_change_state(). This call takes a #GVariant. The
* correct type for the state is determined by a static state type
* (which is given at construction time).
+ *
* The state may have a hint associated with it, specifying its valid
* range.
+ *
* #GAction is merely the interface to the concept of an action, as
* described above. Various implementations of actions exist, including
* #GSimpleAction and #GtkAction.
+ *
* In all cases, the implementing class is responsible for storing the
* name of the action, the parameter type, the enabled state, the
* optional state type and the state and emitting the appropriate
* signals when these change. The implementor responsible for filtering
* calls to g_action_activate() and g_action_change_state() for type
* safety and for the state being enabled.
+ *
* Probably the only useful thing to do with a #GAction is to put it
* inside of a #GSimpleActionGroup.
*/
@@ -11116,19 +11479,21 @@
* @short_description: A group of actions
*
* #GActionGroup represents a group of actions.
+ *
* Each action in the group has a unique name (which is a string). All
* method calls, except g_action_group_list_actions() take the name of
* an action as an argument.
+ *
* The #GActionGroup API is meant to be the 'public' API to the action
* group. The calls here are exactly the interaction that 'external
+ * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
+ * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
* the action group implementation) are found on subclasses. This is
* why you will find -- for example -- g_action_group_get_action_enabled()
* but not an equivalent <function>set()</function> call.
+ *
* Signals are emitted on the action group in response to state changes
* on individual actions.
- *
- * Forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
- * With actions. 'internal' apis (ie: ones meant only to be accessed by
*/
@@ -11139,6 +11504,7 @@
*
* #GAppInfo and #GAppLaunchContext are used for describing and launching
* applications installed on the system.
+ *
* As of GLib 2.20, URIs will always be converted to POSIX paths
* (using g_file_get_path()) when using g_app_info_launch() even if
* the application requested an URI and not a POSIX path. For example
@@ -11153,6 +11519,7 @@
* <literal>mailto:</literal>, of course cannot be mapped to a POSIX
* path (in gvfs there's no FUSE mount for it); such URIs will be
* passed unmodified to the application.
+ *
* Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
* back to the GIO URI in the #GFile constructors (since gvfs
* implements the #GVfs extension point). As such, if the application
@@ -11161,19 +11528,24 @@
* that the URI passed to e.g. g_file_new_for_commandline_arg() is
* equal to the result of g_file_get_uri(). The following snippet
* illustrates this:
+ *
* <programlisting>
* GFile *f;
* char *uri;
+ *
* file = g_file_new_for_commandline_arg (uri_from_commandline);
+ *
* uri = g_file_get_uri (file);
* strcmp (uri, uri_from_commandline) == 0; // FALSE
* g_free (uri);
+ *
* if (g_file_has_uri_scheme (file, "cdda"))
* {
* // do something special with uri
* }
* g_object_unref (file);
* </programlisting>
+ *
* This code will work when both <literal>cdda://sr0/Track
* 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track
* 1.wav</literal> is passed to the application. It should be noted
@@ -11194,6 +11566,7 @@
* foundation for higher-level application classes such as
* #GtkApplication or #MxApplication. In general, you should not use
* this class outside of a higher level framework.
+ *
* One of the core features that GApplication provides is process
* uniqueness, in the context of a "session". The session concept is
* platform-dependent, but corresponds roughly to a graphical desktop
@@ -11201,16 +11574,20 @@
* are passed through platform communication to the already running
* program. The already running instance of the program is called the
* <firstterm>primary instance</firstterm>.
+ *
* Before using GApplication, you must choose an "application identifier".
* The expected form of an application identifier is very close to that of
* of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface";>DBus bus name</ulink>.
+ * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
* For details on valid application identifiers, see
* g_application_id_is_valid().
+ *
* The application identifier is claimed by the application as a
* well-known bus name on the user's session bus. This means that the
* uniqueness of your application is scoped to the current session. It
* also means that your application may provide additional services
* (through registration of other object paths) at that bus name.
+ *
* The registration of these object paths should be done with the shared
* GDBus session bus. Note that due to the internal architecture of
* GDBus, method calls can be dispatched at any time (even if a main
@@ -11220,14 +11597,17 @@
* (which happens in g_application_register()). Unfortunately, this
* means that you cannot use g_application_get_is_remote() to decide if
* you want to register object paths.
+ *
* GApplication provides convenient life cycle management by maintaining
* a <firstterm>use count</firstterm> for the primary application instance.
* The use count can be changed using g_application_hold() and
* g_application_release(). If it drops to zero, the application exits.
+ *
* GApplication also implements the #GActionGroup interface and lets you
* easily export actions by adding them with g_application_set_action_group().
* When invoking an action by calling g_action_group_activate_action() on
* the application, it is always invoked in the primary instance.
+ *
* There is a number of different entry points into a #GApplication:
* <itemizedlist>
* <listitem>via 'Activate' (i.e. just starting the application)</listitem>
@@ -11237,6 +11617,7 @@
* </itemizedlist>
* The #GApplication::startup signal lets you handle the application
* initialization for all of these in a single place.
+ *
* Regardless of which of these entry points is used to start the application,
* GApplication passes some <firstterm id="platform-data">platform
* data</firstterm> from the launching instance to the primary instance,
@@ -11247,6 +11628,7 @@
* available via g_application_command_line_get_cwd(),
* g_application_command_line_get_environ() and
* g_application_command_line_get_platform_data().
+ *
* As the name indicates, the platform data may vary depending on the
* operating system, but it always includes the current directory (key
* "cwd"), and optionally the environment (ie the set of environment
@@ -11256,10 +11638,12 @@
* can add their own platform data by overriding the @add_platform_data
* virtual function. For instance, #GtkApplication adds startup notification
* data in this way.
+ *
* To parse commandline arguments you may handle the
* #GApplication::command-line signal or override the local_command_line()
* vfunc, to parse them in either the primary instance or the local instance,
* respectively.
+ *
* <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-open.c">
@@ -11267,6 +11651,7 @@
* </xi:include>
* </programlisting>
* </example>
+ *
* <example id="gapplication-example-actions"><title>A GApplication with actions</title>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-actions.c">
@@ -11274,8 +11659,6 @@
* </xi:include>
* </programlisting>
* </example>
- *
- * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
*/
@@ -11288,17 +11671,24 @@
* #GApplicationCommandLine represents a command-line invocation of
* an application. It is created by #GApplication and emitted
* in the #GApplication::command-line signal and virtual function.
+ *
* The class contains the list of arguments that the program was invoked
* with. It is also possible to query if the commandline invocation was
+ * local (ie: the current process is running in direct response to the
+ * invocation) or remote (ie: some other process forwarded the
* commandline to this process).
+ *
* The GApplicationCommandLine object can provide the @argc and @argv
* parameters for use with the #GOptionContext command-line parsing API,
* with the g_application_command_line_get_arguments() function. See
* <xref linkend="gapplication-example-cmdline3"/> for an example.
+ *
* The exit status of the originally-invoked process may be set and
* messages can be printed to stdout or stderr of that process. The
* lifecycle of the originally-invoked process is tied to the lifecycle
+ * of this object (ie: the process exits when the last reference is
* dropped).
+ *
* The main use for #GApplicationCommandline (and the
* #GApplication::command-line signal) is 'Emacs server' like use cases:
* You can set the <envar>EDITOR</envar> environment variable to have
@@ -11307,6 +11697,7 @@
* in the running instance, instead of opening a new one. An important
* aspect of this use case is that the process that gets started by git
* does not return until the editing is done.
+ *
* <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
* <para>
* A simple example where the commandline is completely handled
@@ -11321,6 +11712,7 @@
* </xi:include>
* </programlisting>
* </example>
+ *
* <example id="gapplication-example-cmdline2"><title>Split commandline handling</title>
* <para>
* An example of split commandline handling. Options that start with
@@ -11334,6 +11726,7 @@
* </xi:include>
* </programlisting>
* </example>
+ *
* <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
* <para>
* An example of deferred commandline handling. Here, the commandline is
@@ -11356,10 +11749,6 @@
* </xi:include>
* </programlisting>
* </example>
- *
- * Local (ie: the current process is running in direct response to the
- * Invocation) or remote (ie: some other process forwarded the
- * Of this object (ie: the process exits when the last reference is
*/
@@ -11382,36 +11771,47 @@
* This is the asynchronous version of #GInitable; it behaves the same
* in all ways except that initialization is asynchronous. For more details
* see the descriptions on #GInitable.
+ *
* A class may implement both the #GInitable and #GAsyncInitable interfaces.
+ *
* Users of objects implementing this are not intended to use the interface
* method directly; instead it will be used automatically in various ways.
* For C applications you generally just call g_async_initable_new_async()
* directly, or indirectly via a foo_thing_new_async() wrapper. This will call
* g_async_initable_init_async() under the cover, calling back with %NULL and
* a set %GError on failure.
+ *
* A typical implementation might look something like this:
+ *
* |[
* enum {
* NOT_INITIALIZED,
* INITIALIZING,
* INITIALIZED
* };
+ *
* static void
* _foo_ready_cb (Foo *self)
* {
* GList *l;
+ *
* self->priv->state = INITIALIZED;
+ *
* for (l = self->priv->init_results; l != NULL; l = l->next)
* {
* GSimpleAsyncResult *simple = l->data;
+ *
* if (!self->priv->success)
* g_simple_async_result_set_error (simple, ...);
+ *
* g_simple_async_result_complete (simple);
* g_object_unref (simple);
* }
+ *
* g_list_free (self->priv->init_results);
* self->priv->init_results = NULL;
* }
+ *
* static void
* foo_init_async (GAsyncInitable *initable,
* int io_priority,
@@ -11421,10 +11821,12 @@
* {
* Foo *self = FOO (initable);
* GSimpleAsyncResult *simple;
+ *
* simple = g_simple_async_result_new (G_OBJECT (initable)
* callback,
* user_data,
* foo_init_async);
+ *
* switch (self->priv->state)
* {
* case NOT_INITIALIZED:
@@ -11440,11 +11842,13 @@
* case INITIALIZED:
* if (!self->priv->success)
* g_simple_async_result_set_error (simple, ...);
+ *
* g_simple_async_result_complete_in_idle (simple);
* g_object_unref (simple);
* break;
* }
* }
+ *
* static gboolean
* foo_init_finish (GAsyncInitable *initable,
* GAsyncResult *result,
@@ -11452,16 +11856,20 @@
* {
* g_return_val_if_fail (g_simple_async_result_is_valid (result,
* G_OBJECT (initable), foo_init_async), FALSE);
+ *
* if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
* error))
* return FALSE;
+ *
* return TRUE;
* }
+ *
* static void
* foo_async_initable_iface_init (gpointer g_iface,
* gpointer data)
* {
* GAsyncInitableIface *iface = g_iface;
+ *
* iface->init_async = foo_init_async;
* iface->init_finish = foo_init_finish;
* }
@@ -11476,6 +11884,7 @@
* @see_also: #GSimpleAsyncResult
*
* Provides a base class for implementing asynchronous function results.
+ *
* Asynchronous operations are broken up into two separate operations
* which are chained together by a #GAsyncReadyCallback. To begin
* an asynchronous operation, provide a #GAsyncReadyCallback to the
@@ -11487,6 +11896,7 @@
* the corresponding "_finish()" function, passing the object the
* function was called for, the #GAsyncResult instance, and (optionally)
* an @error to grab any error conditions that may have occurred.
+ *
* The "_finish()" function for an operation takes the generic result
* (of type #GAsyncResult) and returns the specific result that the
* operation in question yields (e.g. a #GFileEnumerator for a
@@ -11498,41 +11908,53 @@
* action at all after the operation completes. Applications may also
* take a reference to the #GAsyncResult and call "_finish()" later;
* however, the "_finish()" function may be called at most once.
+ *
* Example of a typical asynchronous operation flow:
* |[
* void _theoretical_frobnitz_async (Theoretical *t,
* GCancellable *c,
* GAsyncReadyCallback *cb,
* gpointer u);
+ *
* gboolean _theoretical_frobnitz_finish (Theoretical *t,
* GAsyncResult *res,
* GError **e);
+ *
* static void
* frobnitz_result_func (GObject *source_object,
* GAsyncResult *res,
* gpointer user_data)
* {
* gboolean success = FALSE;
+ *
* success = _theoretical_frobnitz_finish (source_object, res, NULL);
+ *
* if (success)
* g_printf ("Hurray!\n");
* else
* g_printf ("Uh oh!\n");
+ *
* /<!-- -->* ... *<!-- -->/
+ *
* }
+ *
* int main (int argc, void *argv[])
* {
* /<!-- -->* ... *<!-- -->/
+ *
* _theoretical_frobnitz_async (theoretical_data,
* NULL,
* frobnitz_result_func,
* NULL);
+ *
* /<!-- -->* ... *<!-- -->/
* }
* ]|
+ *
* The callback for an asynchronous operation is called only once, and is
* always called, even in the case of a cancelled operation. On cancellation
* the result is a %G_IO_ERROR_CANCELLED error.
+ *
* Some asynchronous operations are implemented using synchronous calls.
* These are run in a separate thread, if #GThread has been initialized, but
* otherwise they are sent to the Main Event Loop and processed in an idle
@@ -11549,10 +11971,13 @@
*
* Buffered input stream implements #GFilterInputStream and provides
* for buffered reads.
+ *
* By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
+ *
* To create a buffered input stream, use g_buffered_input_stream_new(),
* or g_buffered_input_stream_new_sized() to specify the buffer's size at
* construction.
+ *
* To get the size of a buffer within a buffered input stream, use
* g_buffered_input_stream_get_buffer_size(). To change the size of a
* buffered input stream's buffer, use
@@ -11569,10 +11994,13 @@
*
* Buffered output stream implements #GFilterOutputStream and provides
* for buffered writes.
+ *
* By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
+ *
* To create a buffered output stream, use g_buffered_output_stream_new(),
* or g_buffered_output_stream_new_sized() to specify the buffer's size
* at construction.
+ *
* To get the size of a buffer within a buffered input stream, use
* g_buffered_output_stream_get_buffer_size(). To change the size of a
* buffered output stream's buffer, use
@@ -11624,10 +12052,11 @@
* #GConverter is implemented by objects that convert
* binary data in various ways. The conversion can be
* stateful and may fail at any place.
+ *
+ * Some example conversions are: character set conversion,
* compression, decompression and regular expression
* replace.
*
- * Some example conversions are: character set conversion,
* Since: 2.24
*/
@@ -11662,20 +12091,25 @@
* The #GCredentials type is a reference-counted wrapper for native
* credentials. This information is typically used for identifying,
* authenticating and authorizing other processes.
+ *
* Some operating systems supports looking up the credentials of the
* remote peer of a communication endpoint - see e.g.
* g_socket_get_credentials().
+ *
* Some operating systems supports securely sending and receiving
* credentials over a Unix Domain Socket, see
* #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
* g_unix_connection_receive_credentials() for details.
+ *
* On Linux, the native credential type is a <type>struct ucred</type>
* - see the
* <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
* man page for details. This corresponds to
* %G_CREDENTIALS_TYPE_LINUX_UCRED.
+ *
* On FreeBSD, the native credential type is a <type>struct cmsgcred</type>.
* This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
+ *
* On OpenBSD, the native credential type is a <type>struct sockpeercred</type>.
* This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
*/
@@ -11725,6 +12159,7 @@
* peers. Simply instantiate a #GDBusAuthObserver and connect to the
* signals you are interested in. Note that new signals may be added
* in the future
+ *
* For example, if you only want to allow D-Bus connections from
* processes owned by the same uid as the server, you would use a
* signal handler like the following:
@@ -11736,6 +12171,7 @@
* gpointer user_data)
* {
* gboolean authorized;
+ *
* authorized = FALSE;
* if (credentials != NULL)
* {
@@ -11745,6 +12181,7 @@
* authorized = TRUE;
* g_object_unref (own_credentials);
* }
+ *
* return authorized;
* }
* </programlisting></example>
@@ -11760,12 +12197,17 @@
* peers such as a message buses. It is a low-level API that offers a
* lot of flexibility. For instance, it lets you establish a connection
* over any transport that can by represented as an #GIOStream.
+ *
* This class is rarely used directly in D-Bus clients. If you are writing
* an D-Bus client, it is often easier to use the g_bus_own_name(),
* g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
+ *
* <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ *
* <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ *
* <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ *
* <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/
@@ -11780,34 +12222,42 @@
* g_dbus_connection_call_sync()) use #GError to represent both D-Bus
* errors (e.g. errors returned from the other peer) and locally
* in-process generated errors.
+ *
* To check if a returned #GError is an error from a remote peer, use
* g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
* use g_dbus_error_get_remote_error(). Before presenting an error,
* always use g_dbus_error_strip_remote_error().
+ *
* In addition, facilities used to return errors to a remote peer also
* use #GError. See g_dbus_method_invocation_return_error() for
* discussion about how the D-Bus error name is set.
+ *
* Applications can associate a #GError error domain with a set of D-Bus errors in order to
* automatically map from D-Bus errors to #GError and back. This
* is typically done in the function returning the #GQuark for the
* error domain:
* <example id="error-registration"><title>Error Registration</title><programlisting>
* /<!-- -->* foo-bar-error.h: *<!-- -->/
+ *
* #define FOO_BAR_ERROR (foo_bar_error_quark ())
* GQuark foo_bar_error_quark (void);
+ *
* typedef enum
* {
* FOO_BAR_ERROR_FAILED,
* FOO_BAR_ERROR_ANOTHER_ERROR,
* FOO_BAR_ERROR_SOME_THIRD_ERROR,
* } FooBarError;
+ *
* /<!-- -->* foo-bar-error.c: *<!-- -->/
+ *
* static const GDBusErrorEntry foo_bar_error_entries[] =
* {
* {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
* {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
* {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
* };
+ *
* GQuark
* foo_bar_error_quark (void)
* {
@@ -11825,6 +12275,7 @@
* If the other peer is using GDBus, the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
* of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
* <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error().
+ *
* Note that errors in the %G_DBUS_ERROR error domain is intended only
* for returning errors from a remote message bus process. Errors
* generated locally in-process by e.g. #GDBusConnection is from the
@@ -11861,6 +12312,7 @@
* Various data structures and convenience routines to parse and
* generate D-Bus introspection XML. Introspection information is
* used when registering objects with g_dbus_connection_register_object().
+ *
* The format of D-Bus introspection XML is specified in the
* <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format";>D-Bus specification</link>.
*/
@@ -11884,6 +12336,7 @@
* Instances of the #GDBusMethodInvocation class are used when
* handling D-Bus method calls. It provides a way to asynchronously
* return results and errors.
+ *
* The normal way to obtain a #GDBusMethodInvocation object is to receive
* it as an argument to the handle_method_call() function in a
* #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
@@ -11897,6 +12350,7 @@
* @include: gio/gio.h
*
* Convenience API for owning bus names.
+ *
* <example id="gdbus-owning-names"><title>Simple application owning a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/
@@ -11908,6 +12362,7 @@
* @include: gio/gio.h
*
* Convenience API for watching bus names.
+ *
* <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/
@@ -11933,6 +12388,7 @@
* client-side implementations of the standardized <ulink
* url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager";>org.freedesktop.DBus.ObjectManager</ulink>
* interface.
+ *
* See #GDBusObjectManagerClient for the client-side implementation
* and #GDBusObjectManagerServer for the service-side implementation.
*/
@@ -11948,11 +12404,13 @@
* code implementing the <ulink
* url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager";>org.freedesktop.DBus.ObjectManager</ulink>
* interface).
+ *
* Once an instance of this type has been created, you can connect to
* the #GDBusObjectManager::object-added and
* #GDBusObjectManager::object-removed signals and inspect the
* #GDBusObjectProxy objects returned by
* g_dbus_object_manager_get_objects().
+ *
* If the name for a #GDBusObjectManagerClient is not owned by anyone at
* object construction time, the default behavior is to request the
* message bus to launch an owner for the name. This behavior can be
@@ -11964,6 +12422,7 @@
* there will be no object proxies
* (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
* the #GDBusObjectManagerClient:name-owner property is %NULL.
+ *
* The owner of the requested name can come and go (for example
* consider a system service being restarted) â #GDBusObjectManagerClient
* handles this case too; simply connect to the #GObject::notify
@@ -11985,6 +12444,7 @@
* #GDBusObjectManagerClient:name-owner will alternate between a name owner
* (e.g. <literal>:1.42</literal>) and %NULL even in the case where
* the name of interest is atomically replaced
+ *
* Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
* instances. All signals (including the
* <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
@@ -11994,6 +12454,7 @@
* including the <emphasis><quote>half the proxy is from the old owner
* and the other half is from the new owner</quote></emphasis> problem
* cannot happen.
+ *
* To avoid having the application connect to signals on the returned
* #GDBusObjectProxy and #GDBusProxy objects, the
* #GDBusObject::interface-added,
@@ -12006,6 +12467,7 @@
* #GDBusObjectManager::interface-removed,
* #GDBusObjectManagerClient::interface-proxy-properties-changed and
* #GDBusObjectManagerClient::interface-proxy-signal.
+ *
* Note that all callbacks and signals are emitted in the
* <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
* that the #GDBusObjectManagerClient object was constructed
@@ -12029,6 +12491,7 @@
* object hierarchy is broadcast using signals. This means that D-Bus
* clients can keep caches up to date by only listening to D-Bus
* signals.
+ *
* See #GDBusObjectManagerClient for the client-side code that is
* intended to be used with #GDBusObjectManagerServer or any D-Bus
* object implementing the org.freedesktop.DBus.ObjectManager
@@ -12058,6 +12521,7 @@
* A #GDBusObjectSkeleton instance is essentially a group of D-Bus
* interfaces. The set of exported interfaces on the object may be
* dynamic and change at runtime.
+ *
* This type is intended to be used with #GDBusObjectManager.
*/
@@ -12070,12 +12534,14 @@
* #GDBusProxy is a base class used for proxies to access a D-Bus
* interface on a remote object. A #GDBusProxy can be constructed for
* both well-known and unique names.
+ *
* By default, #GDBusProxy will cache all properties (and listen to
* changes) of the remote object, and proxy all signals that gets
* emitted. This behaviour can be changed by passing suitable
* #GDBusProxyFlags when the proxy is created. If the proxy is for a
* well-known name, the property cache is flushed when the name owner
* vanishes and reloaded when a name owner appears.
+ *
* If a #GDBusProxy is used for a well-known name, the owner of the
* name is tracked and can be read from
* #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
@@ -12087,6 +12553,7 @@
* then calls will be sent to the well-known name which may result in
* the message bus launching an owner (unless
* %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
+ *
* The generic #GDBusProxy::g-properties-changed and
* #GDBusProxy::g-signal signals are not very convenient to work
* with. Therefore, the recommended way of working with proxies is to
@@ -12095,11 +12562,13 @@
* for how this can easily be done using the
* <command><link linkend="gdbus-codegen">gdbus-codegen</link></command>
* tool.
+ *
* A #GDBusProxy instance can be used from multiple threads but note
* that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
* and #GObject::notify) are emitted in the
* <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
* of the thread where the instance was constructed.
+ *
* <example id="gdbus-wellknown-proxy"><title>GDBusProxy for a well-known-name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/
@@ -12114,8 +12583,10 @@
* peers to use the D-Bus protocol for their own specialized communication.
* A server instance provided in this way will not perform message routing or
* implement the org.freedesktop.DBus interface.
+ *
* To just export an object on a well-known name on a message bus, such as the
* session or system bus, you should instead use g_bus_own_name().
+ *
* <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/
@@ -12138,6 +12609,7 @@
*
* #GDesktopAppInfo is an implementation of #GAppInfo based on
* desktop files.
+ *
* Note that <filename><gio/gdesktopappinfo.h></filename> belongs to
* the UNIX-specific GIO interfaces, thus you have to use the
* <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
@@ -12152,15 +12624,18 @@
* #GDrive - this represent a piece of hardware connected to the machine.
* It's generally only created for removable hardware or hardware with
* removable media.
+ *
* #GDrive is a container class for #GVolume objects that stem from
* the same piece of media. As such, #GDrive abstracts a drive with
* (or without) removable media and provides operations for querying
* whether media is available, determing whether media change is
* automatically detected and ejecting the media.
+ *
* If the #GDrive reports that media isn't automatically detected, one
* can poll for media; typically one should not do this periodically
* as a poll for media operation is potententially expensive and may
* spin up the drive creating noise.
+ *
* #GDrive supports starting and stopping drives with authentication
* support for the former. This can be used to support a diverse set
* of use cases including connecting/disconnecting iSCSI devices,
@@ -12169,6 +12644,7 @@
* semantics and side-effects of starting/stopping a #GDrive may vary
* according to implementation. To choose the correct verbs in e.g. a
* file manager, use g_drive_get_start_stop_type().
+ *
* For porting from GnomeVFS note that there is no equivalent of
* #GDrive in that API.
*/
@@ -12183,6 +12659,7 @@
* #GEmblem is an implementation of #GIcon that supports
* having an emblem, which is an icon with additional properties.
* It can than be added to a #GEmblemedIcon.
+ *
* Currently, only metainformation about the emblem's origin is
* supported. More may be added in the future.
*/
@@ -12197,6 +12674,7 @@
* #GEmblemedIcon is an implementation of #GIcon that supports
* adding an emblem to an icon. Adding multiple emblems to an
* icon is ensured via g_emblemed_icon_add_emblem().
+ *
* Note that #GEmblemedIcon allows no control over the position
* of the emblems. See also #GEmblem for more information.
*/
@@ -12214,14 +12692,18 @@
* #GFile objects do not represent files, merely an identifier for a file. All
* file content I/O is implemented as streaming operations (see #GInputStream and
* #GOutputStream).
+ *
+ * To construct a #GFile, you can use:
* g_file_new_for_path() if you have a path.
* g_file_new_for_uri() if you have a URI.
* g_file_new_for_commandline_arg() for a command line argument.
* g_file_parse_name() from a utf8 string gotten from g_file_get_parse_name().
+ *
* One way to think of a #GFile is as an abstraction of a pathname. For normal
* files the system pathname is what is stored internally, but as #GFile<!-- -->s
* are extensible it could also be something else that corresponds to a pathname
* in a userspace implementation of a filesystem.
+ *
* #GFile<!-- -->s make up hierarchies of directories and files that correspond to the
* files on a filesystem. You can move through the file system with #GFile using
* g_file_get_parent() to get an identifier for the parent directory, g_file_get_child()
@@ -12229,6 +12711,7 @@
* path between two #GFile<!-- -->s. There can be multiple hierarchies, so you may not
* end up at the same root if you repeatedly call g_file_get_parent() on two different
* files.
+ *
* All #GFile<!-- -->s have a basename (get with g_file_get_basename()). These names
* are byte strings that are used to identify the file on the filesystem (relative to
* its parent directory) and there is no guarantees that they have any particular charset
@@ -12238,27 +12721,32 @@
* This is guaranteed to be in utf8 and can be used in a user interface. But always
* store the real basename or the #GFile to use to actually access the file, because
* there is no way to go from a display name to the actual name.
+ *
* Using #GFile as an identifier has the same weaknesses as using a path in that
* there may be multiple aliases for the same file. For instance, hard or
* soft links may cause two different #GFile<!-- -->s to refer to the same file.
+ * Other possible causes for aliases are: case insensitive filesystems, short
* and long names on Fat/NTFS, or bind mounts in Linux. If you want to check if
* two #GFile<!-- -->s point to the same file you can query for the
* %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
* canonicalization of pathnames passed in, so that trivial differences in the
* path string used at creation (duplicated slashes, slash at end of path, "."
* or ".." path segments, etc) does not create different #GFile<!-- -->s.
+ *
* Many #GFile operations have both synchronous and asynchronous versions
* to suit your application. Asynchronous versions of synchronous functions
* simply have _async() appended to their function names. The asynchronous
* I/O functions call a #GAsyncReadyCallback which is then used to finalize
* the operation, producing a GAsyncResult which is then passed to the
* function's matching _finish() operation.
+ *
* Some #GFile operations do not have synchronous analogs, as they may
* take a very long time to finish, and blocking may leave an application
* unusable. Notable cases include:
* g_file_mount_mountable() to mount a mountable file.
* g_file_unmount_mountable_with_operation() to unmount a mountable file.
* g_file_eject_mountable_with_operation() to eject a mountable file.
+ *
* <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
* One notable feature of #GFile<!-- -->s are entity tags, or "etags" for
* short. Entity tags are somewhat like a more abstract version of the
@@ -12267,9 +12755,6 @@
* <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html";>specification</ulink>
* for HTTP Etag headers, which are a very similar concept.
* </para>
- *
- * To construct a #gfile, you can use:
- * Other possible causes for aliases are: case insensitive filesystems, short
*/
@@ -12280,22 +12765,27 @@
* @see_also: #GFile, #GFileInfo
*
* File attributes in GIO consist of a list of key-value pairs.
+ *
* Keys are strings that contain a key namespace and a key name, separated
* by a colon, e.g. "namespace:keyname". Namespaces are included to sort
* key-value pairs by namespaces for relevance. Keys can be retrived
* using wildcards, e.g. "standard::*" will return all of the keys in the
* "standard" namespace.
+ *
* Values are stored within the list in #GFileAttributeValue structures.
* Values can store different types, listed in the enum #GFileAttributeType.
* Upon creation of a #GFileAttributeValue, the type will be set to
* %G_FILE_ATTRIBUTE_TYPE_INVALID.
+ *
* The list of possible attributes for a filesystem (pointed to by a #GFile) is
* availible as a #GFileAttributeInfoList. This list is queryable by key names
* as indicated earlier.
+ *
* Classes that implement #GFileIface will create a #GFileAttributeInfoList and
* install default keys and values for their given file system, architecture,
* and other possible implementation details (e.g., on a UNIX system, a file
* attribute key will be registered for the user id for a given file).
+ *
* <para>
* <table>
* <title>GFileAttributes Default Namespaces</title>
@@ -12335,7 +12825,7 @@
* "user" for getting the user name of the file owner. This information is often mapped from
* some backend specific data such as a unix UID.</entry></row>
* <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes
- * information about file thumbnails and their location within the file system. Exaples of
+ * information about file thumbnails and their location within the file system. Examples of
* keys in this namespace include "path" to get the location of a thumbnail, and "failed"
* to check if thumbnailing of the file failed.</entry></row>
* <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information
@@ -12360,11 +12850,14 @@
* </tgroup>
* </table>
* </para>
+ *
* Please note that these are not all of the possible namespaces.
* More namespaces can be added from GIO modules or by individual applications.
* For more information about writing GIO modules, see #GIOModule.
+ *
* <!-- TODO: Implementation note about using extended attributes on supported
* file systems -->
+ *
* <para><table>
* <title>GFileAttributes Built-in Keys and Value Types</title>
* <tgroup cols='3' align='left'><thead>
@@ -12434,6 +12927,7 @@
* <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row>
* <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row>
* </tbody></tgroup></table></para>
+ *
* Note that there are no predefined keys in the "xattr" and "xattr-sys"
* namespaces. Keys for the "xattr" namespace are constructed by stripping
* away the "user." prefix from the extended user attribute, and prepending
@@ -12453,6 +12947,7 @@
*
* #GFileDescriptorBased is implemented by streams (implementations of
* #GInputStream or #GOutputStream) that are based on file descriptors.
+ *
* Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to
* the UNIX-specific GIO interfaces, thus you have to use the
* <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
@@ -12470,11 +12965,13 @@
* returning a #GFileInfo structure for each file enumerated (e.g.
* g_file_enumerate_children() will return a #GFileEnumerator for each
* of the children within a directory).
+ *
* To get the next file's information from a #GFileEnumerator, use
* g_file_enumerator_next_file() or its asynchronous version,
* g_file_enumerator_next_files_async(). Note that the asynchronous
* version will return a list of #GFileInfo<!---->s, whereas the
* synchronous will only return the next file in the enumerator.
+ *
* To close a #GFileEnumerator, use g_file_enumerator_close(), or
* its asynchronous version, g_file_enumerator_close_async(). Once
* a #GFileEnumerator is closed, no further actions may be performed
@@ -12502,20 +12999,25 @@
* Functionality for manipulating basic metadata for files. #GFileInfo
* implements methods for getting information that all files should
* contain, and allows for manipulation of extended attributes.
+ *
* See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more
* information on how GIO handles file attributes.
+ *
* To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
* async variant). To obtain a #GFileInfo for a file input or output
* stream, use g_file_input_stream_query_info() or
* g_file_output_stream_query_info() (or their async variants).
+ *
* To change the actual attributes of a file, you should then set the
* attribute in the #GFileInfo and call g_file_set_attributes_from_info()
* or g_file_set_attributes_async() on a GFile.
+ *
* However, not all attributes can be changed in the file. For instance,
* the actual size of a file cannot be changed via g_file_info_set_size().
* You may call g_file_query_settable_attributes() and
* g_file_query_writable_namespaces() to discover the settable attributes
* of a particular file at runtime.
+ *
* #GFileAttributeMatcher allows for searching through a #GFileInfo for
* attributes.
*/
@@ -12529,6 +13031,7 @@
*
* GFileInputStream provides input streams that take their
* content from a file.
+ *
* GFileInputStream implements #GSeekable, which allows the input
* stream to jump to arbitrary positions in the file, provided the
* filesystem of the file allows it. To find the position of a file
@@ -12546,17 +13049,21 @@
*
* GFileIOStream provides io streams that both read and write to the same
* file handle.
+ *
* GFileIOStream implements #GSeekable, which allows the io
* stream to jump to arbitrary positions in the file and to truncate
* the file, provided the filesystem of the file supports these
* operations.
+ *
* To find the position of a file io stream, use
* g_seekable_tell().
+ *
* To find out if a file io stream supports seeking, use g_seekable_can_seek().
* To position a file io stream, use g_seekable_seek().
* To find out if a file io stream supports truncating, use
* g_seekable_can_truncate(). To truncate a file io
* stream, use g_seekable_truncate().
+ *
* The default implementation of all the #GFileIOStream operations
* and the implementation of #GSeekable just call into the same operations
* on the output stream.
@@ -12571,9 +13078,11 @@
* @include: gio/gio.h
*
* Monitors a file or directory for changes.
+ *
* To obtain a #GFileMonitor for a file or directory, use
* g_file_monitor(), g_file_monitor_file(), or
* g_file_monitor_directory().
+ *
* To get informed about changes to the file or directory you are
* monitoring, connect to the #GFileMonitor::changed signal. The
* signal will be emitted in the <link
@@ -12604,10 +13113,12 @@
*
* GFileOutputStream provides output streams that write their
* content to a file.
+ *
* GFileOutputStream implements #GSeekable, which allows the output
* stream to jump to arbitrary positions in the file and to truncate
* the file, provided the filesystem of the file supports these
* operations.
+ *
* To find the position of a file output stream, use g_seekable_tell().
* To find out if a file output stream supports seeking, use
* g_seekable_can_seek().To position a file output stream, use
@@ -12649,13 +13160,18 @@
* #GIcon is a very minimal interface for icons. It provides functions
* for checking the equality of two icons, hashing of icons and
* serializing an icon to and from strings.
+ *
* #GIcon does not provide the actual pixmap for the icon as this is out
* of GIO's scope, however implementations of #GIcon may contain the name
* of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
+ *
* To obtain a hash of a #GIcon, see g_icon_hash().
+ *
* To check if two #GIcons are equal, see g_icon_equal().
+ *
* For serializing a #GIcon, use g_icon_to_string() and
* g_icon_new_for_string().
+ *
* If your application or library provides one or more #GIcon
* implementations you need to ensure that each #GType is registered
* with the type system prior to calling g_icon_new_for_string().
@@ -12672,6 +13188,7 @@
* g_resolver_lookup_by_address() or
* g_resolver_lookup_by_address_async() to look up the hostname for a
* #GInetAddress.
+ *
* To actually connect to a remote host, you will need a
* #GInetSocketAddress (which includes a #GInetAddress as well as a
* port number).
@@ -12699,6 +13216,7 @@
* after construction. If g_initable_init() is not called, or if
* it returns an error, all further operations on the object
* should fail, generally with a %G_IO_ERROR_NOT_INITIALIZED error.
+ *
* Users of objects implementing this are not intended to use
* the interface method directly, instead it will be used automatically
* in various ways. For C applications you generally just call
@@ -12706,6 +13224,7 @@
* This will call g_initable_init() under the cover, returning %NULL and
* setting a #GError on failure (at which point the instance is
* unreferenced).
+ *
* For bindings in languages where the native constructor supports
* exceptions the binding could check for objects implemention %GInitable
* during normal construction and automatically initialize them, throwing
@@ -12721,8 +13240,10 @@
* GInputStream has functions to read from a stream (g_input_stream_read()),
* to close a stream (g_input_stream_close()) and to skip some content
* (g_input_stream_skip()).
+ *
* To copy the content of an input stream to an output stream without
* manually handling the reads and writes, use g_output_stream_splice().
+ *
* All of these functions have async variants too.
*/
@@ -12755,6 +13276,7 @@
* Schedules asynchronous I/O operations. #GIOScheduler integrates
* into the main event loop (#GMainLoop) and may use threads if they
* are available.
+ *
* <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm>
* Each I/O operation has a priority, and the scheduler uses the priorities
* to determine the order in which operations are executed. They are
@@ -12776,16 +13298,20 @@
* Generally the two streams acts as separate input and output streams,
* but they share some common resources and state. For instance, for
* seekable streams they may use the same position in both streams.
+ *
* Examples of #GIOStream objects are #GSocketConnection which represents
* a two-way network connection, and #GFileIOStream which represent a
* file handle opened in read-write mode.
+ *
* To do the actual reading and writing you need to get the substreams
* with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
+ *
* The #GIOStream object owns the input and the output streams, not the other
* way around, so keeping the substreams alive will not keep the #GIOStream
* object alive. If the #GIOStream object is freed it will be closed, thus
* closing the substream, so even if the substreams stay alive they will
* always just return a %G_IO_ERROR_CLOSED for all operations.
+ *
* To close a stream use g_io_stream_close() which will close the common
* stream object and also the individual substreams. You can also close
* the substreams themselves. In most cases this only marks the
@@ -12838,10 +13364,12 @@
*
* The #GMount interface represents user-visible mounts. Note, when
* porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
+ *
* #GMount is a "mounted" filesystem that you can access. Mounted is in
* quotes because it's not the same as a unix mount, it might be a gvfs
* mount, but you can still access the files on it if you use GIO. Might or
* might not be related to a volume object.
+ *
* Unmounting a #GMount instance is an asynchronous operation. For
* more information about asynchronous operations, see #GAsyncReady
* and #GSimpleAsyncReady. To unmount a #GMount instance, first call
@@ -12866,9 +13394,11 @@
* mounting files, hard drive partitions or server locations. It can
* also be used to ask the user questions or show a list of applications
* preventing unmount or eject operations from completing.
+ *
* Note that #GMountOperation is used for more than just #GMount
* objects â for example it is also used in g_drive_start() and
* g_drive_stop().
+ *
* Users should instantiate a subclass of this that implements all the
* various callbacks to show the required dialogs, such as
* #GtkMountOperation. If no user interaction is desired (for example
@@ -12885,6 +13415,7 @@
* #GNetworkAddress provides an easy way to resolve a hostname and
* then attempt to connect to that host, handling the possibility of
* multiple IP addresses and multiple address families.
+ *
* See #GSocketConnectable for and example of using the connectable
* interface.
*/
@@ -12900,6 +13431,7 @@
* connect to one of the hosts that implements that service, handling
* service priority/weighting, multiple IP addresses, and multiple
* address families.
+ *
* See #GSrvTarget for more information about SRV records, and see
* #GSocketConnectable for and example of using the connectable
* interface.
@@ -12914,8 +13446,10 @@
* GOutputStream has functions to write to a stream (g_output_stream_write()),
* to close a stream (g_output_stream_close()) and to flush pending writes
* (g_output_stream_flush()).
+ *
* To copy the content of an input stream to an output stream without
* manually handling the reads and writes, use g_output_stream_splice().
+ *
* All of these functions have async variants too.
*/
@@ -12927,11 +13461,14 @@
*
* A #GPermission represents the status of the caller's permission to
* perform a certain action.
+ *
* You can query if the action is currently allowed and if it is
* possible to acquire the permission so that the action will be allowed
* in the future.
+ *
* There is also an API to actually acquire the permission and one to
* release it.
+ *
* As an example, a #GPermission might represent the ability for the
* user to write to a #GSettings object. This #GPermission object could
* then be used to decide if it is appropriate to show a "Click here to
@@ -13013,6 +13550,7 @@
* resolution, for hostnames (g_resolver_lookup_by_address(),
* g_resolver_lookup_by_name() and their async variants) and SRV
* (service) records (g_resolver_lookup_service()).
+ *
* #GNetworkAddress and #GNetworkService provide wrappers around
* #GResolver functionality that also implement #GSocketConnectable,
* making it easy to connect to a remote host/service.
@@ -13036,7 +13574,9 @@
*
* The #GSettings class provides a convenient API for storing and retrieving
* application settings.
+ *
* Reads and writes can be considered to be non-blocking. Reading
+ * settings with #GSettings is typically extremely fast: on
* approximately the same order of magnitude (but slower than) a
* #GHashTable lookup. Writing settings is also extremely fast in terms
* of time to return to your application, but can be extremely expensive
@@ -13051,20 +13591,24 @@
* of preferences widgets. The built-in g_settings_bind() functionality
* is careful not to write settings in response to notify signals as a
* result of modifications that it makes to widgets.
+ *
* When creating a GSettings instance, you have to specify a schema
* that describes the keys in your settings and their types and default
* values, as well as some other information.
+ *
* Normally, a schema has as fixed path that determines where the settings
* are stored in the conceptual global tree of settings. However, schemas
* can also be 'relocatable', i.e. not equipped with a fixed path. This is
* useful e.g. when the schema describes an 'account', and you want to be
* able to store a arbitrary number of accounts.
+ *
* Unlike other configuration systems (like GConf), GSettings does not
* restrict keys to basic types like strings and numbers. GSettings stores
* values as #GVariant, and allows any #GVariantType for keys. Key names
* are restricted to lowercase characters, numbers and '-'. Furthermore,
* the names must begin with a lowercase character, must not end
* with a '-', and must not contain consecutive dashes.
+ *
* Similar to GConf, the default values in GSettings schemas can be
* localized, but the localized values are stored in gettext catalogs
* and looked up with the domain that is specified in the
@@ -13072,12 +13616,15 @@
* <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
* elements and the category that is specified in the l10n attribute of the
* <tag class="starttag">key</tag> element.
+ *
* GSettings uses schemas in a compact binary form that is created
* by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
* utility. The input is a schema description in an XML format that can be
* described by the following DTD:
* |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/gschema.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ *
* glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename>
+ *
* At runtime, schemas are identified by their id (as specified
* in the <tag class="attribute">id</tag> attribute of the
* <tag class="starttag">schema</tag> element). The
@@ -13087,6 +13634,7 @@
* the D-Bus bus name and schema id should match. For schemas which deal
* with settings not associated with one named application, the id should
* not use StudlyCaps, e.g. "org.gnome.font-rendering".
+ *
* In addition to #GVariant types, keys can have types that have enumerated
* types. These can be described by a <tag class="starttag">choice</tag>,
* <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
@@ -13095,10 +13643,12 @@
* g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
* access the numeric values corresponding to the string value of enum
* and flags keys.
+ *
* <example id="schema-default-values"><title>Default values</title>
* <programlisting><![CDATA[
* <schemalist>
* <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
+ *
* <key name="greeting" type="s">
* <default l10n="messages">"Hello, earthlings"</default>
* <summary>A greeting</summary>
@@ -13106,29 +13656,37 @@
* Greeting of the invading martians
* </description>
* </key>
+ *
* <key name="box" type="(ii)">
* <default>(20,30)</default>
* </key>
+ *
* </schema>
* </schemalist>
* ]]></programlisting></example>
+ *
* <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
* <programlisting><![CDATA[
* <schemalist>
+ *
* <enum id="org.gtk.Test.myenum">
* <value nick="first" value="1"/>
* <value nick="second" value="2"/>
* </enum>
+ *
* <flags id="org.gtk.Test.myflags">
* <value nick="flag1" value="1"/>
* <value nick="flag2" value="2"/>
* <value nick="flag3" value="4"/>
* </flags>
+ *
* <schema id="org.gtk.Test">
+ *
* <key name="key-with-range" type="i">
* <range min="1" max="100"/>
* <default>10</default>
* </key>
+ *
* <key name="key-with-choices" type="s">
* <choices>
* <choice value='Elisabeth'/>
@@ -13141,15 +13699,18 @@
* </aliases>
* <default>'Joe'</default>
* </key>
+ *
* <key name='enumerated-key' enum='org.gtk.Test.myenum'>
* <default>'first'</default>
* </key>
+ *
* <key name='flags-key' flags='org.gtk.Test.myflags'>
* <default>["flag1",flag2"]</default>
* </key>
* </schema>
* </schemalist>
* ]]></programlisting></example>
+ *
* <refsect2>
* <title>Vendor overrides</title>
* <para>
@@ -13173,6 +13734,7 @@
* <filename>.gschema.override</filename>
* </para>
* </refsect2>
+ *
* <refsect2>
* <title>Binding</title>
* <para>
@@ -13192,8 +13754,6 @@
* #G_SETTINGS_BIND_NO_SENSITIVITY flag.
* </para>
* </refsect2>
- *
- * Settings with #gsettings is typically extremely fast: on
*/
@@ -13209,16 +13769,20 @@
* an alternative storage backend for #GSettings, you need to implement
* the #GSettingsBackend interface and then make it implement the
* extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
+ *
* The interface defines methods for reading and writing values, a
* method for determining if writing of certain values will fail
* (lockdown) and a change notification mechanism.
+ *
* The semantics of the interface are very precisely defined and
* implementations must carefully adhere to the expectations of
* callers that are documented on each of the interface methods.
+ *
* Some of the GSettingsBackend functions accept or return a #GTree.
* These trees always have strings as keys and #GVariant as values.
* g_settings_backend_create_tree() is a convenience function to create
* suitable trees.
+ *
* <note><para>
* The #GSettingsBackend API is exported to allow third-party
* implementations, but does not carry the same stability guarantees
@@ -13237,6 +13801,7 @@
* A #GSimpleAction is the obvious simple implementation of the #GAction
* interface. This is the easiest way to create an action for purposes of
* adding it to a #GSimpleActionGroup.
+ *
* See also #GtkAction.
*/
@@ -13261,6 +13826,7 @@
* will be all an application needs, and will be used transparently.
* Because of this, #GSimpleAsyncResult is used throughout GIO for
* handling asynchronous functions.
+ *
* GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
* reporting, operation cancellation and the final state of an operation,
* completely transparent to the application. Results can be returned
@@ -13269,15 +13835,18 @@
* of an operation, or a #gssize for operations which return the number
* of bytes modified by the operation; all of the simple return cases
* are covered.
+ *
* Most of the time, an application will not need to know of the details
* of this API; it is handled transparently, and any necessary operations
* are handled by #GAsyncResult's interface. However, if implementing a
* new GIO module, for writing language bindings, or for complex
* applications that need better control of how asynchronous operations
* are completed, it is important to understand this functionality.
+ *
* GSimpleAsyncResults are tagged with the calling function to ensure
* that asynchronous functions and their finishing functions are used
* together correctly.
+ *
* To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
* If the result needs to be created for a #GError, use
* g_simple_async_result_new_from_error() or
@@ -13288,11 +13857,13 @@
* if your application or binding requires passing a variable argument list
* directly), and the error can then be propagated through the use of
* g_simple_async_result_propagate_error().
+ *
* An asynchronous operation can be made to ignore a cancellation event by
* calling g_simple_async_result_set_handle_cancellation() with a
* #GSimpleAsyncResult for the operation and %FALSE. This is useful for
* operations that are dangerous to cancel, such as close (which would
* cause a leak if cancelled before being run).
+ *
* GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
* or it can use #GThread<!-- -->s if available.
* g_simple_async_result_complete() will finish an I/O task directly
@@ -13302,21 +13873,25 @@
* context</link>. g_simple_async_result_run_in_thread() will run the
* job in a separate thread and then deliver the result to the
* thread-default main context.
+ *
* To set the results of an asynchronous function,
* g_simple_async_result_set_op_res_gpointer(),
* g_simple_async_result_set_op_res_gboolean(), and
* g_simple_async_result_set_op_res_gssize()
* are provided, setting the operation's result to a gpointer, gboolean, or
* gssize, respectively.
+ *
* Likewise, to get the result of an asynchronous function,
* g_simple_async_result_get_op_res_gpointer(),
* g_simple_async_result_get_op_res_gboolean(), and
* g_simple_async_result_get_op_res_gssize() are
* provided, getting the operation's result as a gpointer, gboolean, and
* gssize, respectively.
+ *
* For the details of the requirements implementations must respect, see
* #GAsyncResult. A typical implementation of an asynchronous operation
* using GSimpleAsyncResult looks something like this:
+ *
* |[
* static void
* baked_cb (Cake *cake,
@@ -13326,6 +13901,7 @@
* * the GSimpleAsyncResult has to take a reference to it.
* */
* GSimpleAsyncResult *result = user_data;
+ *
* if (cake == NULL)
* g_simple_async_result_set_error (result,
* BAKER_ERRORS,
@@ -13335,6 +13911,8 @@
* g_simple_async_result_set_op_res_gpointer (result,
* g_object_ref (cake),
* g_object_unref);
+ *
+ *
* /* In this example, we assume that baked_cb is called as a callback from
* * the mainloop, so it's safe to complete the operation synchronously here.
* * If, however, _baker_prepare_cake () might call its callback without
@@ -13344,6 +13922,7 @@
* g_simple_async_result_complete (result);
* g_object_unref (result);
* }
+ *
* void
* baker_bake_cake_async (Baker *self,
* guint radius,
@@ -13352,6 +13931,7 @@
* {
* GSimpleAsyncResult *simple;
* Cake *cake;
+ *
* if (radius < 3)
* {
* g_simple_async_report_error_in_idle (G_OBJECT (self),
@@ -13363,11 +13943,13 @@
* radius);
* return;
* }
+ *
* simple = g_simple_async_result_new (G_OBJECT (self),
* callback,
* user_data,
* baker_bake_cake_async);
* cake = _baker_get_cached_cake (self, radius);
+ *
* if (cake != NULL)
* {
* g_simple_async_result_set_op_res_gpointer (simple,
@@ -13381,8 +13963,10 @@
* g_object_unref (cake);
* return;
* }
+ *
* _baker_prepare_cake (self, radius, baked_cb, simple);
* }
+ *
* Cake *
* baker_bake_cake_finish (Baker *self,
* GAsyncResult *result,
@@ -13390,13 +13974,17 @@
* {
* GSimpleAsyncResult *simple;
* Cake *cake;
+ *
* g_return_val_if_fail (g_simple_async_result_is_valid (result,
* G_OBJECT (self),
* baker_bake_cake_async),
* NULL);
+ *
* simple = (GSimpleAsyncResult *) result;
+ *
* if (g_simple_async_result_propagate_error (simple, error))
* return NULL;
+ *
* cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
* return g_object_ref (cake);
* }
@@ -13412,6 +14000,7 @@
* #GSimplePermission is a trivial implementation of #GPermission that
* represents a permission that is either always or never allowed. The
* value is given at constuction and doesn't change.
+ *
* Calling request or release will result in errors.
*/
@@ -13425,16 +14014,19 @@
* A #GSocket is a low-level networking primitive. It is a more or less
* direct mapping of the BSD socket API in a portable GObject based API.
* It supports both the UNIX socket implementations and winsock2 on Windows.
+ *
* #GSocket is the platform independent base upon which the higher level
* network primitives are based. Applications are not typically meant to
* use it directly, but rather through classes like #GSocketClient,
* #GSocketService and #GSocketConnection. However there may be cases where
* direct use of #GSocket is useful.
+ *
* #GSocket implements the #GInitable interface, so if it is manually constructed
* by e.g. g_object_new() you must call g_initable_init() and check the
* results before using the object. This is done automatically in
* g_socket_new() and g_socket_new_from_fd(), so these functions can return
* %NULL.
+ *
* Sockets operate in two general modes, blocking or non-blocking. When
* in blocking mode all operations block until the requested operation
* is finished or there is an error. In non-blocking mode all calls that
@@ -13444,18 +14036,22 @@
* attach it to a #GMainContext to get callbacks when I/O is possible.
* Note that all sockets are always set to non blocking mode in the system, and
* blocking mode is emulated in GSocket.
+ *
* When working in non-blocking mode applications should always be able to
* handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
* function said that I/O was possible. This can easily happen in case
* of a race condition in the application, but it can also happen for other
* reasons. For instance, on Windows a socket is always seen as writable
* until a write returns %G_IO_ERROR_WOULD_BLOCK.
+ *
* #GSocket<!-- -->s can be either connection oriented or datagram based.
* For connection oriented types you must first establish a connection by
* either connecting to an address or accepting a connection from another
* address. For connectionless socket types the target/source address is
* specified or received in each I/O operation.
+ *
* All socket file descriptors are set to be close-on-exec.
+ *
* Note that creating a #GSocket causes the signal %SIGPIPE to be
* ignored for the remainder of the program. If you are writing a
* command-line utility that uses #GSocket, you may need to take into
@@ -13485,9 +14081,11 @@
*
* #GSocketClient is a high-level utility class for connecting to a
* network host using a connection oriented socket type.
+ *
* You create a #GSocketClient object, set any options you want, and then
* call a sync or async connect operation, which returns a #GSocketConnection
* subclass on success.
+ *
* The type of the #GSocketConnection object returned depends on the type of
* the underlying socket that is in use. For instance, for a TCP/IP connection
* it will be a #GTcpConnection.
@@ -13505,6 +14103,7 @@
* g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
* to try out each socket address in turn until one succeeds, as shown
* in the sample code below.
+ *
* |[
* MyConnectionType *
* connect_to_host (const char *hostname,
@@ -13517,18 +14116,22 @@
* GSocketAddressEnumerator *enumerator;
* GSocketAddress *sockaddr;
* GError *conn_error = NULL;
+ *
* addr = g_network_address_new ("www.gnome.org", 80);
* enumerator = g_socket_connectable_enumerate (addr);
* g_object_unref (addr);
+ *
* /<!-- -->* Try each sockaddr until we succeed. Record the first
* * connection error, but not any further ones (since they'll probably
* * be basically the same as the first).
* *<!-- -->/
* while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
* {
+ * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
* g_object_unref (sockaddr);
* }
* g_object_unref (enumerator);
+ *
* if (conn)
* {
* if (conn_error)
@@ -13556,8 +14159,6 @@
* }
* }
* ]|
- *
- * Conn = connect_to_sockaddr (sockaddr, conn_error ? null : &conn_error);
*/
@@ -13570,9 +14171,11 @@
* #GSocketConnection is a #GIOStream for a connected socket. They
* can be created either by #GSocketClient when connecting to a host,
* or by #GSocketListener when accepting a new client.
+ *
* The type of the #GSocketConnection object returned from these calls
* depends on the type of the underlying socket that is in use. For
* instance, for a TCP/IP connection it will be a #GTcpConnection.
+ *
* Choosing what type of object to construct is done with the socket
* connection factory, and it is possible for 3rd parties to register
* custom socket connection types for specific combination of socket
@@ -13591,15 +14194,19 @@
* A #GSocketControlMessage is a special-purpose utility message that
* can be sent to or received from a #GSocket. These types of
* messages are often called "ancillary data".
+ *
* The message can represent some sort of special instruction to or
* information from the socket or can represent a special kind of
* transfer to the peer (for example, sending a file description over
* a UNIX socket).
+ *
* These messages are sent with g_socket_send_message() and received
* with g_socket_receive_message().
+ *
* To extend the set of control message that can be sent, subclass this
* class and override the get_size, get_level, get_type and serialize
* methods.
+ *
* To extend the set of control messages that can be received, subclass
* this class and implement the deserialize method. Also, make sure your
* class is registered with the GType typesystem before calling
@@ -13618,6 +14225,7 @@
* A #GSocketListener is an object that keeps track of a set
* of server sockets and helps you accept sockets from any of the
* socket, either sync or async.
+ *
* If you want to implement a network server, also look at #GSocketService
* and #GThreadedSocketService which are subclass of #GSocketListener
* that makes this even easier.
@@ -13636,18 +14244,22 @@
* is provided to the network or over local sockets. When a new
* connection is made to the service the #GSocketService::incoming
* signal is emitted.
+ *
* A #GSocketService is a subclass of #GSocketListener and you need
* to add the addresses you want to accept connections on with the
* #GSocketListener APIs.
+ *
* There are two options for implementing a network service based on
* #GSocketService. The first is to create the service using
* g_socket_service_new() and to connect to the #GSocketService::incoming
* signal. The second is to subclass #GSocketService and override the
* default signal handler implementation.
+ *
* In either case, the handler must immediately return, or else it
* will block additional incoming connections from being serviced.
* If you are interested in writing connection handlers that contain
* blocking code then see #GThreadedSocketService.
+ *
* The socket service runs on the main loop in the main thread, and is
* not threadsafe in general. However, the calls to start and stop
* the service are threadsafe so these can be used from threads that
@@ -13669,6 +14281,7 @@
* specific server hostname like "xmpp.example.com", an XMPP client
* would look up the "xmpp-client" SRV record for "example.com", and
* then connect to whatever host was pointed to by that record.
+ *
* You can use g_resolver_lookup_service() or
* g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s
* for a given service. However, if you are simply planning to connect
@@ -13733,12 +14346,15 @@
* that handles incoming connections by creating a worker thread and
* dispatching the connection to it by emitting the
* #GThreadedSocketService::run signal in the new thread.
+ *
* The signal handler may perform blocking IO and need not return
* until the connection is closed.
+ *
* The service is implemented using a thread pool, so there is a
* limited amount of threads available to serve incoming requests.
* The service automatically stops the #GSocketService from accepting
* new connections when all threads are busy.
+ *
* As with #GSocketService, you may connect to #GThreadedSocketService::run,
* or subclass and override the default handler.
*/
@@ -13750,15 +14366,16 @@
* @short_description: Monitor the local timezone
*
* #GTimeZoneMonitor is a utility class to monitor the local timezone for
+ * changes (ie: in response to the user manually changing the timezone
* to that of a different locale).
+ *
* You must use this class in order for your program to notice changes
* to the local timezone. It works by monitoring the /etc/localtime
* file. When the timezone is found to have changed,
* g_time_zone_refresh_local() is called and the "changed" signal is
* emitted on the #GTimeZoneMonitor (in that order).
- * Windows support is not presently working.
*
- * Changes (ie: in response to the user manually changing the timezone
+ * Windows support is not presently working.
*/
@@ -13771,6 +14388,7 @@
* #GTlsConnection and related classes provide TLS (Transport Layer
* Security, previously known as SSL, Secure Sockets Layer) support for
* gio-based network streams.
+ *
* In the simplest case, for a client connection, you can just set the
* #GSocketClient:tls flag on a #GSocketClient, and then any
* connections created by that client will have TLS negotiated
@@ -13779,11 +14397,13 @@
* default by setting the #GSocketClient:tls-validation-flags
* property). The returned object will be a #GTcpWrapperConnection,
* which wraps the underlying #GTlsClientConnection.
+ *
* For greater control, you can create your own #GTlsClientConnection,
* wrapping a #GSocketConnection (or an arbitrary #GIOStream with
* pollable input and output streams) and then connect to its signals,
* such as #GTlsConnection::accept-certificate, before starting the
* handshake.
+ *
* Server-side TLS is similar, using #GTlsServerConnection. At the
* moment, there is no support for automatically wrapping server-side
* connections in the way #GSocketClient does for client-side
@@ -13842,6 +14462,63 @@
/**
+ * SECTION:gtlsdatabase
+ * @short_description: TLS database type
+ * @include: gio/gio.h
+ *
+ * #GTlsDatabase is used to lookup certificates and other information
+ * from a certificate or key store. It is an abstract base class which
+ * TLS library specific subtypes override.
+ *
+ * Most common client applications will not directly interact with
+ * #GTlsDatabase. It is used internally by #GTlsConnection.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * SECTION:gtlsfiledatabase
+ * @short_description: TLS file based database type
+ * @include: gio/gio.h
+ *
+ * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
+ * their certificate information from a file. It is in interface which
+ * TLS library specific subtypes implement.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * SECTION:gtlsinteraction
+ * @short_description: Interaction with the user during TLS operations.
+ * @include: gio/gio.h
+ *
+ * #GTlsInteraction provides a mechanism for the TLS connection and database
+ * code to interact with the user. It can be used to ask the user for passwords.
+ *
+ * To use a #GTlsInteraction with a TLS connection use
+ * g_tls_connection_set_interaction().
+ *
+ * Callers should instantiate a subclass of this that implements all the
+ * various callbacks to show the required dialogs, such as
+ * #GtkTlsInteraction. If no interaction is desired, usually %NULL can be
+ * passed, see each method taking a #GTlsInteraction for details.
+ */
+
+
+/**
+ * SECTION:gtlspassword
+ * @title: GTlsPassword
+ * @short_description: TLS Passwords for prompting
+ * @include: gio/gio.h
+ *
+ * Holds a password used in TLS.
+ */
+
+
+/**
* SECTION:gtlsserverconnection
* @short_description: TLS server-side connection
* @include: gio/gio.h
@@ -13862,8 +14539,10 @@
*
* This is the subclass of #GSocketConnection that is created
* for UNIX domain sockets.
+ *
* It contains functions to do some of the UNIX socket specific
* functionality like passing file descriptors.
+ *
* Note that <filename><gio/gunixconnection.h></filename> belongs to
* the UNIX-specific GIO interfaces, thus you have to use the
* <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
@@ -13881,15 +14560,15 @@
*
* This #GSocketControlMessage contains a #GCredentials instance. It
* may be sent using g_socket_send_message() and received using
+ * g_socket_receive_message() over UNIX sockets (ie: sockets in the
* %G_SOCKET_FAMILY_UNIX family).
+ *
* For an easier way to send and receive credentials over
* stream-oriented UNIX sockets, see
* g_unix_connection_send_credentials() and
* g_unix_connection_receive_credentials(). To receive credentials of
* a foreign process connected to a socket, use
* g_socket_get_credentials().
- *
- * G_socket_receive_message() over unix sockets (ie: sockets in the
*/
@@ -13902,9 +14581,11 @@
*
* A #GUnixFDList contains a list of file descriptors. It owns the file
* descriptors that it contains, closing them when finalized.
+ *
* It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
* the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
* and received using g_socket_receive_message().
+ *
* Note that <filename><gio/gunixfdlist.h></filename> belongs to
* the UNIX-specific GIO interfaces, thus you have to use the
* <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
@@ -13920,16 +14601,17 @@
*
* This #GSocketControlMessage contains a #GUnixFDList.
* It may be sent using g_socket_send_message() and received using
+ * g_socket_receive_message() over UNIX sockets (ie: sockets in the
* %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
* between processes by the kernel.
+ *
* For an easier way to send and receive file descriptors over
* stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
* g_unix_connection_receive_fd().
+ *
* Note that <filename><gio/gunixfdmessage.h></filename> belongs to
* the UNIX-specific GIO interfaces, thus you have to use the
* <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
- *
- * G_socket_receive_message() over unix sockets (ie: sockets in the
*/
@@ -13942,6 +14624,7 @@
* #GUnixInputStream implements #GInputStream for reading from a
* UNIX file descriptor, including asynchronous operations. The file
* descriptor must be selectable, so it doesn't work with opened files.
+ *
* Note that <filename><gio/gunixinputstream.h></filename> belongs
* to the UNIX-specific GIO interfaces, thus you have to use the
* <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
@@ -13954,6 +14637,7 @@
* @short_description: UNIX mounts
*
* Routines for managing mounted UNIX mount points and paths.
+ *
* Note that <filename><gio/gunixmounts.h></filename> belongs to the
* UNIX-specific GIO interfaces, thus you have to use the
* <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
@@ -13969,6 +14653,7 @@
* #GUnixOutputStream implements #GOutputStream for writing to a
* UNIX file descriptor, including asynchronous operations. The file
* descriptor must be selectable, so it doesn't work with opened files.
+ *
* Note that <filename><gio/gunixoutputstream.h></filename> belongs
* to the UNIX-specific GIO interfaces, thus you have to use the
* <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
@@ -13981,6 +14666,7 @@
* @include: gio/gunixsocketaddress.h
*
* Support for UNIX-domain (also known as local) sockets.
+ *
* UNIX domain sockets are generally visible in the filesystem.
* However, some systems support abstract socket names which are not
* visible in the filesystem and not affected by the filesystem
@@ -13989,6 +14675,7 @@
* systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
* errors. You can use g_unix_socket_address_abstract_names_supported()
* to see if abstract names are supported.
+ *
* Note that <filename><gio/gunixsocketaddress.h></filename> belongs to
* the UNIX-specific GIO interfaces, thus you have to use the
* <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
@@ -14012,15 +14699,18 @@
* The #GVolume interface represents user-visible objects that can be
* mounted. Note, when porting from GnomeVFS, #GVolume is the moral
* equivalent of #GnomeVFSDrive.
+ *
* Mounting a #GVolume instance is an asynchronous operation. For more
* information about asynchronous operations, see #GAsyncReady and
* #GSimpleAsyncReady. To mount a #GVolume, first call
* g_volume_mount() with (at least) the #GVolume instance, optionally
* a #GMountOperation object and a #GAsyncReadyCallback.
+ *
* Typically, one will only want to pass %NULL for the
* #GMountOperation if automounting all volumes when a desktop session
* starts since it's not desirable to put up a lot of dialogs asking
* for credentials.
+ *
* The callback will be fired when the operation has resolved (either
* with success or failure), and a #GAsyncReady structure will be
* passed to the callback. That callback should then call
@@ -14028,6 +14718,7 @@
* #GAsyncReady data to see if the operation was completed
* successfully. If an @error is present when g_volume_mount_finish()
* is called, then it will be filled with any error information.
+ *
* <para id="volume-identifier">
* It is sometimes necessary to directly access the underlying
* operating system object behind a volume (e.g. for passing a volume
@@ -14036,16 +14727,16 @@
* different kinds of identifiers, such as Hal UDIs, filesystem labels,
* traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
* uuids. GIO uses predefind strings as names for the different kinds
+ * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
* #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
* to obtain an identifier for a volume.
* </para>
+ *
* Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
* when the gvfs hal volume monitor is in use. Other volume monitors
* will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
* identifier, which can be used to obtain a hal device by means of
* libhal_manger_find_device_string_match().
- *
- * Of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
*/
@@ -14058,6 +14749,7 @@
* #GVolumeMonitor is for listing the user interesting devices and volumes
* on the computer. In other words, what a file selector or file manager
* would show in a sidebar.
+ *
* #GVolumeMonitor is not <link
* linkend="g-main-context-push-thread-default">thread-default-context
* aware</link>, and so should not be used other than from the main
@@ -14073,6 +14765,7 @@
*
* #GWin32InputStream implements #GInputStream for reading from a
* Windows file handle.
+ *
* Note that <filename><gio/gwin32inputstream.h></filename> belongs
* to the Windows-specific GIO interfaces, thus you have to use the
* <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
@@ -14087,6 +14780,7 @@
*
* #GWin32OutputStream implements #GOutputStream for writing to a
* Windows file handle.
+ *
* Note that <filename><gio/gwin32outputstream.h></filename> belongs
* to the Windows-specific GIO interfaces, thus you have to use the
* <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
@@ -14116,72 +14810,93 @@
/**
* The string info map is an efficient data structure designed to be:
*
- * used with a small set of items. It is used by GSettings schemas for
- * three purposes:
* 1) Implement <choices> with a list of valid strings
+ *
* 2) Implement <alias> by mapping one string to another
+ *
* 3) Implement enumerated types by mapping strings to integer values
* (and back).
+ *
* The map is made out of an array of uint32s. Each entry in the array
* is an integer value, followed by a specially formatted string value:
+ *
* The string starts with the byte 0xff or 0xfe, followed by the
* content of the string, followed by a nul byte, followed by
* additional nul bytes for padding, followed by a 0xff byte.
+ *
* Padding is added so that the entire formatted string takes up a
* multiple of 4 bytes, and not less than 8 bytes. The requirement
* for a string to take up 8 bytes is so that the scanner doesn't lose
* synch and mistake a string for an integer value.
+ *
* The first byte of the formatted string depends on if the integer is
* an enum value (0xff) or an alias (0xfe). If it is an alias then the
* number refers to the word offset within the info map at which the
* integer corresponding to the "target" value is stored.
+ *
* For example, consider the case of the string info map representing an
* enumerated type of 'foo' (value 1) and 'bar' (value 2) and 'baz'
* (alias for 'bar'). Note that string info maps are always little
* endian.
+ *
* x01 x00 x00 x00 xff 'f' 'o' 'o' x00 x00 x00 xff x02 x00 x00 x00
* xff 'b' 'a' 'r' x00 x00 x00 xff x03 x00 x00 x00 xfe 'b' 'a' 'z'
* x00 x00 x00 xff
+ *
+ *
* The operations that someone may want to perform with the map:
+ *
* - lookup if a string is valid (and not an alias)
* - lookup the integer value for a enum 'nick'
* - lookup the integer value for the target of an alias
* - lookup an alias and convert it to its target string
* - lookup the enum nick for a given value
+ *
* In order to lookup if a string is valid, it is padded on either side
* (as described) and scanned for in the array. For example, you might
* look for "foo":
+ *
* xff 'f' 'o' 'o' x00 x00 x00 xff
+ *
* In order to lookup the integer value for a nick, the string is padded
* on either side and scanned for in the array, as above. Instead of
* merely succeeding, we look at the integer value to the left of the
* match. This is the enum value.
+ *
* In order to lookup an alias and convert it to its target enum value,
* the string is padded on either side (as described, with 0xfe) and
* scanned for. For example, you might look for "baz":
+ *
* xfe 'b' 'a' 'z' x00 x00 x00 xff
+ *
* The integer immediately preceeding the match then contains the offset
* of the integer value of the target. In our example, that's '3'.
* This index is dereferenced to find the enum value of '2'.
+ *
* To convert the alias to its target string, 5 bytes just need to be
* added past the start of the integer value to find the start of the
* string.
+ *
* To lookup the enum nick for a given value, the value is searched for
* in the array. To ensure that the value isn't matching the inside of a
* string, we must check that it is either the first item in the array or
* immediately preceeded by the byte 0xff. It must also be immediately
* followed by the byte 0xff.
+ *
* Because strings always take up a minimum of 2 words, because 0xff or
* 0xfe never appear inside of a utf-8 string and because no two integer
* values ever appear in sequence, the only way we can have the
* sequence:
+ *
* xff __ __ __ __ xff (or 0xfe)
+ *
* is in the event of an integer nested between two strings.
+ *
* For implementation simplicity/efficiency, strings may not be more
- * the value of each choice is set to zero and ignored.
+ * than 65 characters in length (ie: 17 32bit words after padding).
*
- * Than 65 characters in length (ie: 17 32bit words after padding).
* In the event that we are doing <choices> (ie: not an enum type) then
+ * the value of each choice is set to zero and ignored.
*/
@@ -14191,6 +14906,8 @@
* @parameter: (allow-none): the parameter to the activation
*
* Activates the action.
+ *
+ * @parameter must be the correct type of parameter for the action (ie:
* the parameter type given at construction time). If the parameter
* type was %NULL then @parameter must also be %NULL.
*
@@ -14204,11 +14921,14 @@
* @value: the new state
*
* Request for the state of @action to be changed to @value.
+ *
* The action must be stateful and @value must be of the correct type.
* See g_action_get_state_type().
+ *
* This call merely requests a change. The action may refuse to change
* its state or may change its state to something other than @value.
* See g_action_get_state_hint().
+ *
* If the @value GVariant is floating, it is consumed.
*
* Since: 2.30
@@ -14220,6 +14940,7 @@
* @action: a #GAction
*
* Checks if @action is currently enabled.
+ *
* An action must be enabled in order to be activated or in order to
* have its state changed from outside callers.
*
@@ -14244,8 +14965,11 @@
* @action: a #GAction
*
* Queries the type of the parameter that must be given when activating
+ * @action.
+ *
* When activating the action using g_action_activate(), the #GVariant
* given to that function must be of the type returned by this function.
+ *
* In the case that this function returns %NULL, you must not give any
* #GVariant, but %NULL instead.
*
@@ -14259,9 +14983,11 @@
* @action: a #GAction
*
* Queries the current state of @action.
+ *
* If the action is not stateful then %NULL will be returned. If the
* action is stateful then the type of the return value is the type
* given by g_action_get_state_type().
+ *
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
@@ -14275,19 +15001,24 @@
* @action: a #GAction
*
* Requests a hint about the valid range of values for the state of
+ * @action.
+ *
* If %NULL is returned it either means that the action is not stateful
* or that there is no hint about the valid range of values for the
* state of the action.
+ *
* If a #GVariant array is returned then each item in the array is a
+ * possible value for the state. If a #GVariant pair (ie: two-tuple) is
* returned then the tuple specifies the inclusive lower and upper bound
* of valid values for the state.
+ *
* In any case, the information is merely a hint. It may be possible to
* have a state value outside of the hinted range and setting a value
* within the range may fail.
+ *
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Possible value for the state. if a #gvariant pair (ie: two-tuple) is
* Returns: (transfer full): the state range hint
* Since: 2.28
*/
@@ -14298,12 +15029,14 @@
* @action: a #GAction
*
* Queries the type of the state of @action.
+ *
* If the action is stateful (e.g. created with
* g_simple_action_new_stateful()) then this function returns the
* #GVariantType of the state. This is the type of the initial value
* given as the state. All calls to g_action_change_state() must give a
* #GVariant of this type and g_action_get_state() will return a
* #GVariant of the same type.
+ *
* If the action is not stateful (e.g. created with g_simple_action_new())
* then this function will return %NULL. In that case, g_action_get_state()
* will return %NULL and you must not call g_action_change_state().
@@ -14319,6 +15052,7 @@
* @action_name: the name of an action in the group
*
* Emits the #GActionGroup::action-added signal on @action_group.
+ *
* This function should only be called by #GActionGroup implementations.
*
* Since: 2.28
@@ -14332,6 +15066,7 @@
* @enabled: whether or not the action is now enabled
*
* Emits the #GActionGroup::action-enabled-changed signal on @action_group.
+ *
* This function should only be called by #GActionGroup implementations.
*
* Since: 2.28
@@ -14344,6 +15079,7 @@
* @action_name: the name of an action in the group
*
* Emits the #GActionGroup::action-removed signal on @action_group.
+ *
* This function should only be called by #GActionGroup implementations.
*
* Since: 2.28
@@ -14357,6 +15093,7 @@
* @state: the new state of the named action
*
* Emits the #GActionGroup::action-state-changed signal on @action_group.
+ *
* This function should only be called by #GActionGroup implementations.
*
* Since: 2.28
@@ -14370,6 +15107,7 @@
* @parameter: (allow-none): parameters to the activation
*
* Activate the named action within @action_group.
+ *
* If the action is expecting a parameter, then the correct type of
* parameter must be given as @parameter. If the action is expecting no
* parameters then @parameter must be %NULL. See
@@ -14387,11 +15125,14 @@
*
* Request for the state of the named action within @action_group to be
* changed to @value.
+ *
* The action must be stateful and @value must be of the correct type.
* See g_action_group_get_action_state_type().
+ *
* This call merely requests a change. The action may refuse to change
* its state or may change its state to something other than @value.
* See g_action_group_get_action_state_hint().
+ *
* If the @value GVariant is floating, it is consumed.
*
* Since: 2.28
@@ -14404,6 +15145,7 @@
* @action_name: the name of the action to query
*
* Checks if the named action within @action_group is currently enabled.
+ *
* An action must be enabled in order to be activated or in order to
* have its state changed from outside callers.
*
@@ -14419,11 +15161,14 @@
*
* Queries the type of the parameter that must be given when activating
* the named action within @action_group.
+ *
* When activating the action using g_action_group_activate_action(),
* the #GVariant given to that function must be of the type returned
* by this function.
+ *
* In the case that this function returns %NULL, you must not give any
* #GVariant, but %NULL instead.
+ *
* The parameter type of a particular action will never change but it is
* possible for an action to be removed and for a new action to be added
* with the same name but a different parameter type.
@@ -14439,9 +15184,11 @@
* @action_name: the name of the action to query
*
* Queries the current state of the named action within @action_group.
+ *
* If the action is not stateful then %NULL will be returned. If the
* action is stateful then the type of the return value is the type
* given by g_action_group_get_action_state_type().
+ *
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
@@ -14457,19 +15204,23 @@
*
* Requests a hint about the valid range of values for the state of the
* named action within @action_group.
+ *
* If %NULL is returned it either means that the action is not stateful
* or that there is no hint about the valid range of values for the
* state of the action.
+ *
* If a #GVariant array is returned then each item in the array is a
+ * possible value for the state. If a #GVariant pair (ie: two-tuple) is
* returned then the tuple specifies the inclusive lower and upper bound
* of valid values for the state.
+ *
* In any case, the information is merely a hint. It may be possible to
* have a state value outside of the hinted range and setting a value
* within the range may fail.
+ *
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Possible value for the state. if a #gvariant pair (ie: two-tuple) is
* Returns: (transfer full): the state range hint
* Since: 2.28
*/
@@ -14481,14 +15232,18 @@
* @action_name: the name of the action to query
*
* Queries the type of the state of the named action within
+ * @action_group.
+ *
* If the action is stateful then this function returns the
* #GVariantType of the state. All calls to
* g_action_group_change_action_state() must give a #GVariant of this
* type and g_action_group_get_action_state() will return a #GVariant
* of the same type.
+ *
* If the action is not stateful then this function will return %NULL.
* In that case, g_action_group_get_action_state() will return %NULL
* and you must not call g_action_group_change_action_state().
+ *
* The state type of a particular action will never change but it is
* possible for an action to be removed and for a new action to be added
* with the same name but a different state type.
@@ -14515,8 +15270,10 @@
* @action_group: a #GActionGroup
*
* Lists the actions contained within @action_group.
+ *
* The caller is responsible for freeing the list with g_strfreev() when
* it is no longer required.
+ *
* actions in the groupb
*
* Returns: (transfer full): a %NULL-terminated array of the names of the
@@ -14594,6 +15351,7 @@
* @appinfo: a #GAppInfo.
*
* Checks if a supported content type can be removed from an application.
+ *
* content types from a given @appinfo, %FALSE if not.
*
* Returns: %TRUE if it is possible to remove supported
@@ -14618,6 +15376,7 @@
* @appinfo: a #GAppInfo
*
* Tries to delete a #GAppInfo.
+ *
* On some platforms, there may be a difference between user-defined
* #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
* cannot. See g_app_info_can_delete().
@@ -14654,6 +15413,7 @@
*
* Gets a list of all of the applications currently registered
* on this system.
+ *
* For desktop files, this includes applications that have
* <literal>NoDisplay=true</literal> set or are excluded from
* display by means of <literal>OnlyShowIn</literal> or
@@ -14670,6 +15430,7 @@
* @content_type: the content type to find a #GAppInfo for
*
* Gets a list of all #GAppInfos for a given content type.
+ *
* for given @content_type or %NULL on error.
*
* Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
@@ -14682,6 +15443,7 @@
*
* Gets the commandline with which the application will be
* started.
+ *
* or %NULL if this information is not available
*
* Returns: a string containing the @appinfo's commandline,
@@ -14695,6 +15457,7 @@
* @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs
*
* Gets the #GAppInfo that corresponds to a given content type.
+ *
* %NULL on error.
*
* Returns: (transfer full): #GAppInfo for given @content_type or
@@ -14719,6 +15482,7 @@
* @appinfo: a #GAppInfo.
*
* Gets a human-readable description of an installed application.
+ *
* application @appinfo, or %NULL if none.
*
* Returns: a string containing a description of the
@@ -14731,6 +15495,7 @@
*
* Gets the display name of the application. The display name is often more
* descriptive to the user than the name itself.
+ *
* no display name is available.
*
* Returns: the display name of the application for @appinfo, or the name if
@@ -14743,6 +15508,7 @@
* @appinfo: a #GAppInfo
*
* Gets the executable's name for the installed application.
+ *
* binaries name
*
* Returns: a string containing the @appinfo's application
@@ -14756,6 +15522,7 @@
* Gets a list of fallback #GAppInfos for a given content type, i.e.
* those applications which claim to support the given content type
* by MIME type subclassing and not directly.
+ *
* for given @content_type or %NULL on error.
*
* Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
@@ -14781,6 +15548,7 @@
* identifies the application. The exact format of the id is
* platform dependent. For instance, on Unix this is the
* desktop file id from the xdg menu specification.
+ *
* Note that the returned ID may be %NULL, depending on how
* the @appinfo has been constructed.
*
@@ -14808,6 +15576,7 @@
* Note that the first application of the list is the last used one, i.e.
* the last one for which #g_app_info_set_as_last_used_for_type has been
* called.
+ *
* for given @content_type or %NULL on error.
*
* Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
@@ -14826,14 +15595,18 @@
* as arguments, using the optional @launch_context to get information
* about the details of the launcher (like what screen it is on).
* On error, @error will be set accordingly.
+ *
* To launch the application without arguments pass a %NULL @files list.
+ *
* Note that even if the launch is successful the application launched
* can fail to start if it runs into problems during startup. There is
* no way to detect this.
+ *
* Some URIs can be changed when passed through a GFile (for instance
* unsupported uris with strange formats like mailto:), so if you have
* a textual uri you want to pass in as argument, consider using
* g_app_info_launch_uris() instead.
+ *
* On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
* environment variable with the path of the launched desktop file and
* <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
@@ -14873,7 +15646,9 @@
* as arguments, using the optional @launch_context to get information
* about the details of the launcher (like what screen it is on).
* On error, @error will be set accordingly.
+ *
* To launch the application without arguments pass a %NULL @uris list.
+ *
* Note that even if the launch is successful the application launched
* can fail to start if it runs into problems during startup. There is
* no way to detect this.
@@ -15000,9 +15775,11 @@
* Initiates startup notification for the application and returns the
* <envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
* if supported.
+ *
* Startup notification IDs are defined in the <ulink
* url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt";>
* FreeDesktop.Org Startup Notifications standard</ulink>.
+ *
* not supported.
*
* Returns: a startup notification ID for the application, or %NULL if
@@ -15034,8 +15811,10 @@
* @application: a #GApplication
*
* Activates the application.
+ *
* In essence, this results in the #GApplication::activate() signal being
* emitted in the primary instance.
+ *
* The application must be registered before calling this function.
*
* Since: 2.28
@@ -15048,9 +15827,12 @@
* @argc: (out): the length of the arguments array, or %NULL
*
* Gets the list of arguments that was passed on the command line.
+ *
* The strings in the array may contain non-utf8 data.
+ *
* The return value is %NULL-terminated and should be freed using
* g_strfreev().
+ *
* containing the arguments (the argv)
*
* Returns: (array length=argc) (transfer full): the string array
@@ -15064,8 +15846,10 @@
*
* Gets the working directory of the command line invocation.
* The string may contain non-utf8 data.
+ *
* It is possible that the remote application did not send a working
* directory, so this may be %NULL.
+ *
* The return value should not be modified or freed and is valid for as
* long as @cmdline exists.
*
@@ -15082,14 +15866,18 @@
* invocation, as would be returned by g_get_environ(), ie as a
* %NULL-terminated list of strings in the form 'NAME=VALUE'.
* The strings may contain non-utf8 data.
+ *
* The remote application usually does not send an environment. Use
* %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
* set it is possible that the environment is still not available (due
* to invocation messages from other applications).
+ *
* The return value should not be modified or freed and is valid for as
* long as @cmdline exists.
+ *
* See g_application_command_line_getenv() if you are only interested
* in the value of a single environment variable.
+ *
* strings, or %NULL if they were not sent
*
* Returns: (array zero-terminated=1) (transfer none): the environment
@@ -15125,10 +15913,12 @@
* @cmdline: #GApplicationCommandLine
*
* Gets the platform data associated with the invocation of @cmdline.
+ *
* This is a #GVariant dictionary containing information about the
* context in which the invocation occured. It typically contains
* information like the current working directory and the startup
* notification ID.
+ *
* For local invocation, it will be %NULL.
*
* Returns: the platform data, or %NULL
@@ -15144,10 +15934,12 @@
* Gets the value of a particular environment variable of the command
* line invocation, as would be returned by g_getenv(). The strings may
* contain non-utf8 data.
+ *
* The remote application usually does not send an environment. Use
* %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
* set it is possible that the environment is still not available (due
* to invocation messages from other applications).
+ *
* The return value should not be modified or freed and is valid for as
* long as @cmdline exists.
*
@@ -15164,6 +15956,7 @@
*
* Formats a message and prints it using the stdout print handler in the
* invoking process.
+ *
* If @cmdline is a local invocation then this is exactly equivalent to
* g_print(). If @cmdline is remote then this is equivalent to calling
* g_print() in the invoking process.
@@ -15180,6 +15973,7 @@
*
* Formats a message and prints it using the stderr print handler in the
* invoking process.
+ *
* If @cmdline is a local invocation then this is exactly equivalent to
* g_printerr(). If @cmdline is remote then this is equivalent to
* calling g_printerr() in the invoking process.
@@ -15195,23 +15989,26 @@
*
* Sets the exit status that will be used when the invoking process
* exits.
+ *
* The return value of the #GApplication::command-line signal is
* passed to this function when the handler returns. This is the usual
* way of setting the exit status.
+ *
* In the event that you want the remote invocation to continue running
* and want to decide on the exit status in the future, you can use this
* call. For the case of a remote invocation, the remote process will
* typically exit when the last reference is dropped on @cmdline. The
* exit status of the remote process will be equal to the last value
* that was set with this function.
+ *
* In the case that the commandline invocation is local, the situation
* is slightly more complicated. If the commandline invocation results
+ * in the mainloop running (ie: because the use-count of the application
* increased to a non-zero value) then the application is considered to
* have been 'successful' in a certain sense, and the exit status is
* always zero. If the application use count is zero, though, the exit
* status of the local #GApplicationCommandLine is used.
*
- * In the mainloop running (ie: because the use-count of the application
* Since: 2.28
*/
@@ -15233,6 +16030,7 @@
* @returns: the flags for @application
*
* Gets the flags for @application.
+ *
* See #GApplicationFlags.
*
* Since: 2.28
@@ -15244,6 +16042,7 @@
* @application: a #GApplication
*
* Gets the current inactivity timeout for the application.
+ *
* This is the amount of time (in milliseconds) after the last call to
* g_application_release() before the application stops running.
*
@@ -15258,6 +16057,7 @@
* @returns: %TRUE if @application is registered
*
* Checks if @application is registered.
+ *
* An application is registered if g_application_register() has been
* successfully called.
*
@@ -15271,10 +16071,12 @@
* @returns: %TRUE if @application is remote
*
* Checks if @application is remote.
+ *
* If @application is remote then it means that another instance of
* application already exists (the 'primary' instance). Calls to
* perform actions on @application will result in the actions being
* performed by the primary instance.
+ *
* The value of this property cannot be accessed before
* g_application_register() has been called. See
* g_application_get_is_registered().
@@ -15288,9 +16090,11 @@
* @application: a #GApplication
*
* Increases the use count of @application.
+ *
* Use this function to indicate that the application has a reason to
* continue to run. For example, g_application_hold() is called by GTK+
* when a toplevel window is on the screen.
+ *
* To cancel the hold, call g_application_release().
*/
@@ -15301,8 +16105,10 @@
* @returns: %TRUE if @application_id is valid
*
* Checks if @application_id is a valid application identifier.
+ *
* A valid ID is required for calls to g_application_new() and
* g_application_set_application_id().
+ *
* For convenience, the restrictions on application identifiers are
* reproduced here:
* <itemizedlist>
@@ -15322,7 +16128,9 @@
* @returns: a new #GApplication instance
*
* Creates a new #GApplication instance.
+ *
* This function calls g_type_init() for you.
+ *
* The application id must be valid. See g_application_id_is_valid().
*/
@@ -15335,14 +16143,20 @@
* @hint: a hint (or ""), but never %NULL
*
* Opens the given files.
+ *
* In essence, this results in the #GApplication::open signal being emitted
* in the primary instance.
+ *
+ * @n_files must be greater than zero.
+ *
+ * @hint is simply passed through to the ::open signal. It is
* intended to be used by applications that have multiple modes for
+ * opening files (eg: "view" vs "edit", etc). Unless you have a need
* for this functionality, you should use "".
+ *
* The application must be registered before calling this function
* and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
*
- * Opening files (eg: "view" vs "edit", etc). Unless you have a need
* Since: 2.28
*/
@@ -15355,26 +16169,32 @@
* @returns: %TRUE if registration succeeded
*
* Attempts registration of the application.
+ *
* This is the point at which the application discovers if it is the
* primary instance or merely acting as a remote for an already-existing
* primary instance. This is implemented by attempting to acquire the
* application identifier as a unique bus name on the session bus using
* GDBus.
+ *
* Due to the internal architecture of GDBus, method calls can be
* dispatched at any time (even if a main loop is not running). For
* this reason, you must ensure that any object paths that you wish to
* register are registered before calling this function.
+ *
* If the application has already been registered then %TRUE is
* returned with no work performed.
+ *
* The #GApplication::startup signal is emitted if registration succeeds
* and @application is the primary instance.
+ *
* In the event of an error (such as @cancellable being cancelled, or a
* failure to connect to the session bus), %FALSE is returned and @error
* is set appropriately.
+ *
+ * Note: the return value of this function is not an indicator that this
* instance is or is not the primary instance of the application. See
* g_application_get_is_remote() for that.
*
- * Note: the return value of this function is not an indicator that this
* Since: 2.28
*/
@@ -15384,7 +16204,9 @@
* @application: a #GApplication
*
* Decrease the use count of @application.
+ *
* When the use count reaches zero, the application will stop running.
+ *
* Never call this function except to cancel the effect of a previous
* call to g_application_hold().
*/
@@ -15398,11 +16220,13 @@
* @returns: the exit status
*
* Runs the application.
+ *
* This function is intended to be run from main() and its return value
* is intended to be returned by main(). Although you are expected to pass
* the @argc, @argv parameters from main() to this function, it is possible
* to pass %NULL if @argv is not available or commandline handling is not
* required.
+ *
* First, the local_command_line() virtual function is invoked.
* This function always runs on the local instance. It gets passed a pointer
* to a %NULL-terminated copy of @argv and is expected to remove the arguments
@@ -15410,22 +16234,27 @@
* <xref linkend="gapplication-example-cmdline2"/> for an example of
* parsing @argv manually. Alternatively, you may use the #GOptionContext API,
* after setting <literal>argc = g_strv_length (argv);</literal>.
+ *
* The last argument to local_command_line() is a pointer to the @status
* variable which can used to set the exit status that is returned from
* g_application_run().
+ *
* If local_command_line() returns %TRUE, the command line is expected
* to be completely handled, including possibly registering as the primary
* instance, calling g_application_activate() or g_application_open(), etc.
+ *
* If local_command_line() returns %FALSE then the application is registered
* and the #GApplication::command-line signal is emitted in the primary
* instance (which may or may not be this instance). The signal handler
* gets passed a #GApplicationCommandline object that (among other things)
* contains the remaining commandline arguments that have not been handled
* by local_command_line().
+ *
* If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
* flag set then the default implementation of local_command_line()
* always returns %FALSE immediately, resulting in the commandline
* always being handled in the primary instance.
+ *
* Otherwise, the default implementation of local_command_line() tries
* to do a couple of things that are probably reasonable for most
* applications. First, g_application_register() is called to attempt
@@ -15434,25 +16263,29 @@
* g_application_activate() is called. If commandline arguments are
* given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
* are assumed to be filenames and g_application_open() is called.
+ *
* If you need to handle commandline arguments that are not filenames,
* and you don't mind commandline handling to happen in the primary
* instance, you should set %G_APPLICATION_HANDLED_COMMAND_LINE and
* process the commandline arguments in your #GApplication::command-line
* signal handler, either manually or using the #GOptionContext API.
+ *
* If you are interested in doing more complicated local handling of the
* commandline then you should implement your own #GApplication subclass
* and override local_command_line(). In this case, you most likely want
* to return %TRUE from your local_command_line() implementation to
* suppress the default handling. See
* <xref linkend="gapplication-example-cmdline2"/> for an example.
+ *
* If, after the above is done, the use count of the application is zero
* then the exit status is returned immediately. If the use count is
* non-zero then the mainloop is run until the use count falls to zero,
* at which point 0 is returned.
+ *
* If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at
+ * use count of zero is delayed for a while (ie: the instance stays
* around to provide its <emphasis>service</emphasis> to others).
*
- * Use count of zero is delayed for a while (ie: the instance stays
* Since: 2.28
*/
@@ -15463,7 +16296,9 @@
* @action_group: (allow-none): a #GActionGroup, or %NULL
*
* Sets or unsets the group of actions associated with the application.
+ *
* These actions are the actions that can be remotely invoked.
+ *
* It is an error to call this function after the application has been
* registered.
*
@@ -15477,8 +16312,10 @@
* @application_id: the identifier for @application
*
* Sets the unique identifier for @application.
+ *
* The application id can only be modified if @application has not yet
* been registered.
+ *
* The application id must be valid. See g_application_id_is_valid().
*
* Since: 2.28
@@ -15491,8 +16328,10 @@
* @flags: the flags for @application
*
* Sets the flags for @application.
+ *
* The flags can only be modified if @application has not yet been
* registered.
+ *
* See #GApplicationFlags.
*
* Since: 2.28
@@ -15505,8 +16344,10 @@
* @inactivity_timeout: the timeout, in milliseconds
*
* Sets the current inactivity timeout for the application.
+ *
* This is the amount of time (in milliseconds) after the last call to
* g_application_release() before the application stops running.
+ *
* This call has no side effects of its own. The value set here is only
* used for next time g_application_release() drops the use count to
* zero. Any timeouts currently in progress are not impacted.
@@ -15528,29 +16369,34 @@
* interface. This must be done before any real use of the object after
* initial construction. If the object also implements #GInitable you can
* optionally call g_initable_init() instead.
+ *
* When the initialization is finished, @callback will be called. You can
* then call g_async_initable_init_finish() to get the result of the
* initialization.
+ *
* Implementations may also support cancellation. If @cancellable is not
* %NULL, then initialization can be cancelled by triggering the cancellable
* object from another thread. If the operation was cancelled, the error
* %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
* the object doesn't support cancellable initialization, the error
* %G_IO_ERROR_NOT_SUPPORTED will be returned.
+ *
* If this function is not called, or returns with an error, then all
* operations on the object should fail, generally returning the
* error %G_IO_ERROR_NOT_INITIALIZED.
+ *
+ * Implementations of this method must be idempotent: i.e. multiple calls
* to this function with the same argument should return the same results.
* Only the first call initializes the object; further calls return the result
* of the first call. This is so that it's safe to implement the singleton
* pattern in the GObject constructor function.
+ *
* For classes that also support the #GInitable interface, the default
* implementation of this method will run the g_initable_init() function
* in a thread, so if you want to support asynchronous initialization via
* threads, just implement the #GAsyncInitable interface without overriding
* any interface methods.
*
- * Implementations of this method must be idempotent: i.e. multiple calls
* Since: 2.22
*/
@@ -15563,6 +16409,7 @@
*
* Finishes asynchronous initialization and returns the result.
* See g_async_initable_init_async().
+ *
* will return %FALSE and set @error appropriately if present.
*
* Returns: %TRUE if successful. If an error has occurred, this function
@@ -15582,6 +16429,7 @@
*
* Helper function for constructing #GAsyncInitable object. This is
* similar to g_object_new() but also initializes the object asynchronously.
+ *
* When the initialization is finished, @callback will be called. You can
* then call g_async_initable_new_finish() to get the new object and check
* for any errors.
@@ -15598,6 +16446,7 @@
*
* Finishes the async construction for the various g_async_initable_new
* calls, returning the created object or %NULL on error.
+ *
* Free with g_object_unref().
*
* Returns: (transfer full): a newly created #GObject, or %NULL on error.
@@ -15618,6 +16467,7 @@
* Helper function for constructing #GAsyncInitable object. This is
* similar to g_object_new_valist() but also initializes the object
* asynchronously.
+ *
* When the initialization is finished, @callback will be called. You can
* then call g_async_initable_new_finish() to get the new object and check
* for any errors.
@@ -15638,6 +16488,7 @@
*
* Helper function for constructing #GAsyncInitable object. This is
* similar to g_object_newv() but also initializes the object asynchronously.
+ *
* When the initialization is finished, @callback will be called. You can
* then call g_async_initable_new_finish() to get the new object and check
* for any errors.
@@ -15651,6 +16502,7 @@
* @res: a #GAsyncResult
*
* Gets the source object from a #GAsyncResult.
+ *
* or %NULL if there is none.
*
* Returns: (transfer full): a new reference to the source object for the @res,
@@ -15676,22 +16528,29 @@
*
* Tries to read @count bytes from the stream into the buffer.
* Will block during this read.
+ *
* If @count is zero, returns zero and does nothing. A value of @count
* larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+ *
* On success, the number of bytes read into the buffer is returned.
* It is not an error if this is not the same as the requested size, as it
* can happen e.g. near the end of a file. Zero is returned on end of file
* (or if @count is zero), but never otherwise.
+ *
* If @count is -1 then the attempted read size is equal to the number of
* bytes that are required to fill the buffer.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
* operation was partially finished when the operation was cancelled the
* partial result will be returned, without an error.
+ *
* On error -1 is returned and @error is set accordingly.
+ *
* For the asynchronous, non-blocking, version of this function, see
* g_buffered_input_stream_fill_async().
+ *
* or -1 on error.
*
* Returns: the number of bytes read into @stream's buffer, up to @count,
@@ -15708,7 +16567,9 @@
* @user_data: (closure): a #gpointer
*
* Reads data into @stream's buffer asynchronously, up to @count size.
+ * @io_priority can be used to prioritize reads. For the synchronous
* version of this function, see g_buffered_input_stream_fill().
+ *
* If @count is -1 then the attempted read size is equal to the number
* of bytes that are required to fill the buffer.
*/
@@ -15791,6 +16652,7 @@
* Returns the buffer with the currently available bytes. The returned
* buffer must not be modified and will become invalid when reading from
* the stream or filling the buffer.
+ *
* read-only buffer
*
* Returns: (array length=count) (element-type guint8) (transfer none):
@@ -15805,13 +16667,16 @@
*
* Tries to read a single byte from the stream or the buffer. Will block
* during this read.
+ *
* On success, the byte read from the stream is returned. On end of stream
* -1 is returned but it's not an exceptional error and @error is not set.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
* operation was partially finished when the operation was cancelled the
* partial result will be returned, without an error.
+ *
* On error -1 is returned and @error is set accordingly.
*
* Returns: the byte read from the @stream, or -1 on end of stream or error.
@@ -15834,6 +16699,7 @@
* @stream: a #GBufferedOutputStream.
*
* Checks if the buffer automatically grows as data is added.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if the @stream's buffer automatically grows,
@@ -15900,8 +16766,10 @@
* @user_data: The data to pass to @callback.
*
* Asynchronously connects to the message bus specified by @bus_type.
+ *
* When the operation is finished, @callback will be invoked. You can
* then call g_bus_get_finish() to get the result of the operation.
+ *
* This is a asynchronous failable function. See g_bus_get_sync() for
* the synchronous version.
*
@@ -15915,11 +16783,13 @@
* @error: Return location for error or %NULL.
*
* Finishes an operation started with g_bus_get().
+ *
* The returned object is a singleton, that is, shared with other
* callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
* event that you need a private message bus connection, use
* g_dbus_address_get_for_bus_sync() and
* g_dbus_connection_new_for_address().
+ *
* Note that the returned #GDBusConnection object will (usually) have
* the #GDBusConnection:exit-on-close property set to %TRUE.
*
@@ -15938,13 +16808,16 @@
* Note that the returned object may shared with other callers,
* e.g. if two separate parts of a process calls this function with
* the same @bus_type, they will share the same object.
+ *
* This is a synchronous failable function. See g_bus_get() and
* g_bus_get_finish() for the asynchronous version.
+ *
* The returned object is a singleton, that is, shared with other
* callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
* event that you need a private message bus connection, use
* g_dbus_address_get_for_bus_sync() and
* g_dbus_connection_new_for_address().
+ *
* Note that the returned #GDBusConnection object will (usually) have
* the #GDBusConnection:exit-on-close property set to %TRUE.
*
@@ -15965,45 +16838,56 @@
* @user_data_free_func: Function for freeing @user_data or %NULL.
*
* Starts acquiring @name on the bus specified by @bus_type and calls
+ * @name_acquired_handler and @name_lost_handler when the name is
* acquired respectively lost. Callbacks will be invoked in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread you are calling this function from.
+ *
* You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
* callbacks will be invoked after calling this function - there are three
* possible cases:
* <itemizedlist>
* <listitem><para>
+ * @name_lost_handler with a %NULL connection (if a connection to the bus can't be made).
* </para></listitem>
* <listitem><para>
+ * @bus_acquired_handler then @name_lost_handler (if the name can't be obtained)
* </para></listitem>
* <listitem><para>
+ * @bus_acquired_handler then @name_acquired_handler (if the name was obtained).
* </para></listitem>
* </itemizedlist>
* When you are done owning the name, just call g_bus_unown_name()
* with the owner id this function returns.
+ *
* If the name is acquired or lost (for example another application
* could acquire the name if you allow replacement or the application
* currently owning the name exits), the handlers are also invoked. If the
* #GDBusConnection that is used for attempting to own the name
* closes, then @name_lost_handler is invoked since it is no
* longer possible for other processes to access the process.
+ *
* You cannot use g_bus_own_name() several times for the same name (unless
* interleaved with calls to g_bus_unown_name()) - only the first call
* will work.
+ *
* Another guarantee is that invocations of @name_acquired_handler
* and @name_lost_handler are guaranteed to alternate; that
* is, if @name_acquired_handler is invoked then you are
* guaranteed that the next time one of the handlers is invoked, it
* will be @name_lost_handler. The reverse is also true.
+ *
* If you plan on exporting objects (using e.g.
* g_dbus_connection_register_object()), note that it is generally too late
* to export the objects in @name_acquired_handler. Instead, you can do this
* in @bus_acquired_handler since you are guaranteed that this will run
* before @name is requested from the bus.
+ *
* This behavior makes it very simple to write applications that wants
* to own names and export objects, see <xref linkend="gdbus-owning-names"/>.
* Simply register objects to be exported in @bus_acquired_handler and
* unregister the objects (if any) in @name_lost_handler.
+ *
* g_bus_unown_name() to stop owning the name.
*
* Returns: An identifier (never 0) that an be used with
@@ -16023,6 +16907,7 @@
*
* Like g_bus_own_name() but takes a #GDBusConnection instead of a
* #GBusType.
+ *
* g_bus_unown_name() to stop owning the name.
*
* Returns: An identifier (never 0) that an be used with
@@ -16040,6 +16925,7 @@
*
* Version of g_bus_own_name_on_connection() using closures instead of callbacks for
* easier binding in other languages.
+ *
* g_bus_unown_name() to stop owning the name.
*
* Returns: An identifier (never 0) that an be used with
@@ -16059,6 +16945,7 @@
*
* Version of g_bus_own_name() using closures instead of callbacks for
* easier binding in other languages.
+ *
* g_bus_unown_name() to stop owning the name.
*
* Returns: An identifier (never 0) that an be used with
@@ -16098,28 +16985,35 @@
* @user_data_free_func: Function for freeing @user_data or %NULL.
*
* Starts watching @name on the bus specified by @bus_type and calls
+ * @name_appeared_handler and @name_vanished_handler when the name is
* known to have a owner respectively known to lose its
* owner. Callbacks will be invoked in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread you are calling this function from.
+ *
* You are guaranteed that one of the handlers will be invoked after
* calling this function. When you are done watching the name, just
* call g_bus_unwatch_name() with the watcher id this function
* returns.
+ *
* If the name vanishes or appears (for example the application owning
* the name could restart), the handlers are also invoked. If the
* #GDBusConnection that is used for watching the name disconnects, then
+ * @name_vanished_handler is invoked since it is no longer
* possible to access the name.
+ *
* Another guarantee is that invocations of @name_appeared_handler
* and @name_vanished_handler are guaranteed to alternate; that
* is, if @name_appeared_handler is invoked then you are
* guaranteed that the next time one of the handlers is invoked, it
* will be @name_vanished_handler. The reverse is also true.
+ *
* This behavior makes it very simple to write applications that wants
* to take action when a certain name exists, see <xref
* linkend="gdbus-watching-names"/>. Basically, the application
* should create object proxies in @name_appeared_handler and destroy
* them again (if any) in @name_vanished_handler.
+ *
* g_bus_unwatch_name() to stop watching the name.
*
* Returns: An identifier (never 0) that an be used with
@@ -16139,6 +17033,7 @@
*
* Like g_bus_watch_name() but takes a #GDBusConnection instead of a
* #GBusType.
+ *
* g_bus_unwatch_name() to stop watching the name.
*
* Returns: An identifier (never 0) that an be used with
@@ -16156,6 +17051,7 @@
*
* Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
* easier binding in other languages.
+ *
* g_bus_unwatch_name() to stop watching the name.
*
* Returns: An identifier (never 0) that an be used with
@@ -16174,6 +17070,7 @@
*
* Version of g_bus_watch_name() using closures instead of callbacks for
* easier binding in other languages.
+ *
* g_bus_unwatch_name() to stop watching the name.
*
* Returns: An identifier (never 0) that an be used with
@@ -16190,9 +17087,11 @@
* #GCancellable::cancelled signal. (However, see the warning about
* race conditions in the documentation for that signal if you are
* planning to connect to it.)
+ *
* This function is thread-safe. In other words, you can safely call
* it from a thread other than the one running the operation that was
* passed the @cancellable.
+ *
* The convention within gio is that cancelling an asynchronous
* operation causes it to complete asynchronously. That is, if you
* cancel the operation from the same thread in which it is running,
@@ -16211,11 +17110,17 @@
* Convenience function to connect to the #GCancellable::cancelled
* signal. Also handles the race condition that may happen
* if the cancellable is cancelled right before connecting.
+ *
+ * @callback is called at most once, either directly at the
* time of the connect if @cancellable is already cancelled,
* or when @cancellable is cancelled in some thread.
+ *
+ * @data_destroy_func will be called when the handler is
* disconnected, or immediately if the cancellable is already
* cancelled.
+ *
* See #GCancellable::cancelled for details on how to use this.
+ *
* been cancelled.
*
* Returns: The id of the signal handler or 0 if @cancellable has already
@@ -16234,10 +17139,12 @@
* handler has finished. Calling this function from a
* #GCancellable::cancelled signal handler will therefore result in a
* deadlock.
+ *
* This avoids a race condition where a thread cancels at the
* same time as the cancellable operation is finished and the
* signal handler is removed. See #GCancellable::cancelled for
* details on how to use this.
+ *
* If @cancellable is %NULL or @handler_id is %0 this function does
* nothing.
*
@@ -16249,6 +17156,7 @@
* g_cancellable_get_current:
*
* Gets the top cancellable from the stack.
+ *
* if the stack is empty.
*
* Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
@@ -16262,13 +17170,17 @@
* Gets the file descriptor for a cancellable job. This can be used to
* implement cancellable operations on Unix systems. The returned fd will
* turn readable when @cancellable is cancelled.
+ *
* You are not supposed to read from the fd yourself, just check for
* readable status. Reading to unset the readable status is done
* with g_cancellable_reset().
+ *
* After a successful return from this function, you should use
* g_cancellable_release_fd() to free up resources allocated for
* the returned file descriptor.
+ *
* See also g_cancellable_make_pollfd().
+ *
* is not supported, or on errors.
*
* Returns: A valid file descriptor. %-1 if the file descriptor
@@ -16280,6 +17192,7 @@
* @cancellable: a #GCancellable or NULL.
*
* Checks if a cancellable job has been cancelled.
+ *
* FALSE if called with %NULL or if item is not cancelled.
*
* Returns: %TRUE if @cancellable is cancelled,
@@ -16295,16 +17208,21 @@
* to g_poll() and used to poll for cancellation. This is useful both
* for unix systems without a native poll and for portability to
* windows.
+ *
* When this function returns %TRUE, you should use
* g_cancellable_release_fd() to free up resources allocated for the
+ * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
+ *
* If this function returns %FALSE, either no @cancellable was given or
* resource limits prevent this function from allocating the necessary
* structures for polling. (On Linux, you will likely have reached
* the maximum number of file descriptors.) The suggested way to handle
* these cases is to ignore the @cancellable.
+ *
* You are not supposed to read from the fd yourself, just check for
* readable status. Reading to unset the readable status is done
* with g_cancellable_reset().
+ *
* failure to prepare the cancellable.
*
* Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
@@ -16316,9 +17234,11 @@
* g_cancellable_new:
*
* Creates a new #GCancellable object.
+ *
* Applications that want to start one or more operations
* that should be cancellable should create a #GCancellable
* and pass it to the operations.
+ *
* One #GCancellable can be used in multiple consecutive
* operations, but not in multiple concurrent operations.
*
@@ -16341,8 +17261,10 @@
*
* Pushes @cancellable onto the cancellable stack. The current
* cancellable can then be recieved using g_cancellable_get_current().
+ *
* This is useful when implementing cancellable operations in
* code that does not allow you to pass down the cancellable object.
+ *
* This is typically called automatically by e.g. #GFile operations,
* so you rarely have to call this yourself.
*/
@@ -16354,6 +17276,7 @@
*
* Releases a resources previously allocated by g_cancellable_get_fd()
* or g_cancellable_make_pollfd().
+ *
* For compatibility reasons with older releases, calling this function
* is not strictly required, the resources will be automatically freed
* when the @cancellable is finalized. However, the @cancellable will
@@ -16393,6 +17316,7 @@
* calls its callback of type #GCancellableSourceFunc. This is
* primarily useful for attaching to another (non-cancellable) source
* with g_source_add_child_source() to add cancellability to it.
+ *
* For convenience, you can call this with a %NULL #GCancellable,
* in which case the source will never trigger.
*
@@ -16453,6 +17377,7 @@
*
* Checks if a content type can be executable. Note that for instance
* things like text files can be executables (i.e. scripts and batch files).
+ *
* can be executable, %FALSE otherwise.
*
* Returns: %TRUE if the file type corresponds to a type that
@@ -16465,6 +17390,7 @@
* @type2: a content type string
*
* Compares two content types for equality.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if the two strings are identical or equivalent,
@@ -16476,6 +17402,7 @@
* @mime_type: a mime type string
*
* Tries to find a content type based on the mime type name.
+ *
* or %NULL. Free with g_free()
*
* Returns: (allow-none): Newly allocated string with content type
@@ -16488,6 +17415,7 @@
* @type: a content type string
*
* Gets the human readable description of the content type.
+ *
* returned string with g_free()
*
* Returns: a short description of the content type @type. Free the
@@ -16499,6 +17427,7 @@
* @type: a content type string
*
* Gets the icon for a content type.
+ *
* object with g_object_unref()
*
* Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
@@ -16510,6 +17439,7 @@
* @type: a content type string
*
* Gets the mime type for the content type, if one is registered.
+ *
* or %NULL if unknown.
*
* Returns: (allow-none): the registered mime type for the given @type,
@@ -16527,6 +17457,7 @@
* uncertain, @result_uncertain will be set to %TRUE. Either @filename
* or @data may be %NULL, in which case the guess will be based solely
* on the other argument.
+ *
* given data. Free with g_free()
*
* Returns: a string indicating a guessed content type for the
@@ -16540,12 +17471,15 @@
* Tries to guess the type of the tree with root @root, by
* looking at the files it contains. The result is an array
* of content types, with the best guess coming first.
+ *
* The types returned all have the form x-content/foo, e.g.
* x-content/audio-cdda (for audio CDs) or x-content/image-dcf
* (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec";>shared-mime-info</ulink>
* specification for more on x-content types.
+ *
* This function is useful in the implementation of
* g_mount_guess_content_type().
+ *
* array of zero or more content types, or %NULL. Free with g_strfreev()
*
* Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
@@ -16559,6 +17493,7 @@
* @supertype: a content type string
*
* Determines if @type is a subset of @supertype.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if @type is a kind of @supertype,
@@ -16607,12 +17542,15 @@
* multiple times in a loop, and each time it will do some work, i.e.
* producing some output (in @outbuf) or consuming some input (from @inbuf) or
* both. If its not possible to do any work an error is returned.
+ *
* Note that a single call may not consume all input (or any input at all).
* Also a call may produce output even if given no input, due to state stored
* in the converter producing output.
+ *
* If any data was either produced or consumed, and then an error happens, then
* only the successful conversion is reported and the error is returned on the
* next call.
+ *
* A full conversion loop involves calling this method repeatedly, each time
* giving it new input and space output space. When there is no more input
* data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
@@ -16622,17 +17560,21 @@
* may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
* in a decompression converter where the end of data is detectable from the
* data (and there might even be other data after the end of the compressed data).
+ *
* When some data has successfully been converted @bytes_read and is set to
* the number of bytes read from @inbuf, and @bytes_written is set to indicate
* how many bytes was written to @outbuf. If there are more data to output
* or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
* %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
* then %G_CONVERTER_FINISHED is returned.
+ *
* On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
* Some errors need special handling:
+ *
* %G_IO_ERROR_NO_SPACE is returned if there is not enough space
* to write the resulting converted data, the application should
* call the function again with a larger @outbuf to continue.
+ *
* %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
* input to fully determine what the conversion should produce,
* and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
@@ -16640,6 +17582,7 @@
* or when a regexp matches up to the end of the input (and may match
* further input). It may also happen when @inbuf_size is zero and
* there is no more data to produce.
+ *
* When this happens the application should read more input and then
* call the function again. If further input shows that there is no
* more data call the function again with the same data but with
@@ -16647,11 +17590,13 @@
* to finish as e.g. in the regexp match case (or, to fail again with
* %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
* input is actually partial).
+ *
* After g_converter_convert() has returned %G_CONVERTER_FINISHED the
* converter object is in an invalid state where its not allowed
* to call g_converter_convert() anymore. At this time you can only
* free the object or call g_converter_reset() to reset it to the
* initial state.
+ *
* If the flag %G_CONVERTER_FLUSH is set then conversion is modified
* to try to write out all internal state to the output. The application
* has to call the function multiple times with the flag set, and when
@@ -16660,6 +17605,7 @@
* really at the end) is returned instead of %G_CONVERTER_CONVERTED.
* This is somewhat similar to what happens at the end of the input stream,
* but done in the middle of the data.
+ *
* This has different meanings for different conversions. For instance
* in a compression converter it would mean that we flush all the
* compression state into output such that if you uncompress the
@@ -16669,6 +17615,7 @@
* have a match, but there is also a potential longer match. In the
* non-flushed case we would ask for more input, but when flushing we
* treat this as the end of input and do the match.
+ *
* Flushing is not always possible (like if a charset converter flushes
* at a partial multibyte sequence). Converters are supposed to try
* to produce as much output as possible and then return an error
@@ -16741,10 +17688,14 @@
* @native_type: The type of native credentials to get.
*
* Gets a pointer to native credentials of type @native_type from
+ * @credentials.
+ *
* It is a programming error (which will cause an warning to be
* logged) to use this method if there is no #GCredentials support for
* the OS or if @native_type isn't supported by the OS.
+ *
* operation there is no #GCredentials support for the OS or if
+ * @native_type isn't supported by the OS. Do not free the returned
* data, it is owned by @credentials.
*
* Returns: The pointer to native credentials or %NULL if the
@@ -16759,6 +17710,7 @@
*
* Tries to get the UNIX user identifier from @credentials. This
* method is only available on UNIX platforms.
+ *
* This operation can fail if #GCredentials is not supported on the
* OS or if the native credentials type does not contain information
* about the UNIX user.
@@ -16775,8 +17727,10 @@
* @error: Return location for error or %NULL.
*
* Checks if @credentials and @other_credentials is the same user.
+ *
* This operation can fail if #GCredentials is not supported on the
* the OS.
+ *
* user, %FALSE otherwise or if @error is set.
*
* Returns: %TRUE if @credentials and @other_credentials has the same
@@ -16803,6 +17757,7 @@
*
* Copies the native credentials of type @native_type from @native
* into @credentials.
+ *
* It is a programming error (which will cause an warning to be
* logged) to use this method if there is no #GCredentials support for
* the OS or if @native_type isn't supported by the OS.
@@ -16819,6 +17774,7 @@
*
* Tries to set the UNIX user identifier on @credentials. This method
* is only available on UNIX platforms.
+ *
* This operation can fail if #GCredentials is not supported on the
* OS or if the native credentials type does not contain information
* about the UNIX user.
@@ -16878,6 +17834,7 @@
* @error: #GError for error reporting.
*
* Reads an unsigned 8-bit/1-byte value from @stream.
+ *
* if an error occurred.
*
* Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
@@ -16891,8 +17848,10 @@
* @error: #GError for error reporting.
*
* Reads a 16-bit/2-byte value from @stream.
+ *
* In order to get the correct byte order for this read operation,
* see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
+ *
* an error occurred.
*
* Returns: a signed 16-bit/2-byte value read from @stream or %0 if
@@ -16906,11 +17865,14 @@
* @error: #GError for error reporting.
*
* Reads a signed 32-bit/4-byte value from @stream.
+ *
* In order to get the correct byte order for this read operation,
* see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* an error occurred.
*
* Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
@@ -16924,11 +17886,14 @@
* @error: #GError for error reporting.
*
* Reads a 64-bit/8-byte value from @stream.
+ *
* In order to get the correct byte order for this read operation,
* see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* an error occurred.
*
* Returns: a signed 64-bit/8-byte value read from @stream or %0 if
@@ -16945,9 +17910,11 @@
* Reads a line from the data input stream. Note that no encoding
* checks or conversion is performed; the input is not guaranteed to
* be UTF-8, and may in fact have embedded NUL characters.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* NUL terminated byte array with the line that was read in (without
* the newlines). Set @length to a #gsize to get the length of the
* read line. On an error, it will return %NULL and @error will be
@@ -16968,6 +17935,7 @@
*
* The asynchronous version of g_data_input_stream_read_line(). It is
* an error to have two outstanding calls to this function.
+ *
* When the operation is finished, @callback will be called. You
* can then call g_data_input_stream_read_line_finish() to get
* the result of the operation.
@@ -16987,9 +17955,11 @@
* g_data_input_stream_read_line_async(). Note the warning about
* string encoding in g_data_input_stream_read_line() applies here as
* well.
+ *
* NUL-terminated byte array with the line that was read in
* (without the newlines). Set @length to a #gsize to get the
* length of the read line. On an error, it will return %NULL and
+ * @error will be set. If there's no content to read, it will
* still return %NULL, but @error won't be set.
*
* Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
@@ -17006,6 +17976,7 @@
*
* Finish an asynchronous call started by
* g_data_input_stream_read_line_async().
+ *
* (without the newlines). Set @length to a #gsize to get the length
* of the read line. On an error, it will return %NULL and @error
* will be set. For UTF-8 conversion errors, the set error domain is
@@ -17025,9 +17996,11 @@
* @error: #GError for error reporting.
*
* Reads a UTF-8 encoded line from the data input stream.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* line that was read in (without the newlines). Set @length to a
* #gsize to get the length of the read line. On an error, it will
* return %NULL and @error will be set. For UTF-8 conversion errors,
@@ -17046,8 +18019,10 @@
* @error: #GError for error reporting.
*
* Reads an unsigned 16-bit/2-byte value from @stream.
+ *
* In order to get the correct byte order for this read operation,
* see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
+ *
* an error occurred.
*
* Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
@@ -17061,11 +18036,14 @@
* @error: #GError for error reporting.
*
* Reads an unsigned 32-bit/4-byte value from @stream.
+ *
* In order to get the correct byte order for this read operation,
* see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* an error occurred.
*
* Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
@@ -17079,11 +18057,14 @@
* @error: #GError for error reporting.
*
* Reads an unsigned 64-bit/8-byte value from @stream.
+ *
* In order to get the correct byte order for this read operation,
* see g_data_input_stream_get_byte_order().
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* an error occurred.
*
* Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
@@ -17100,13 +18081,16 @@
*
* Reads a string from the data input stream, up to the first
* occurrence of any of the stop characters.
+ *
* Note that, in contrast to g_data_input_stream_read_until_async(),
* this function consumes the stop character that it finds.
+ *
* Don't use this function in new code. Its functionality is
* inconsistent with g_data_input_stream_read_until_async(). Both
* functions will be marked as deprecated in a future release. Use
* g_data_input_stream_read_upto() instead, but note that that function
* does not consume the stop character.
+ *
* before encountering any of the stop characters. Set @length to
* a #gsize to get the length of the string. This function will
* return %NULL on an error.
@@ -17126,12 +18110,15 @@
*
* The asynchronous version of g_data_input_stream_read_until().
* It is an error to have two outstanding calls to this function.
+ *
* Note that, in contrast to g_data_input_stream_read_until(),
* this function does not consume the stop character that it finds. You
* must read it for yourself.
+ *
* When the operation is finished, @callback will be called. You
* can then call g_data_input_stream_read_until_finish() to get
* the result of the operation.
+ *
* Don't use this function in new code. Its functionality is
* inconsistent with g_data_input_stream_read_until(). Both functions
* will be marked as deprecated in a future release. Use
@@ -17150,6 +18137,8 @@
*
* Finish an asynchronous call started by
* g_data_input_stream_read_until_async().
+ *
+ *
* before encountering any of the stop characters. Set @length to
* a #gsize to get the length of the string. This function will
* return %NULL on an error.
@@ -17170,12 +18159,15 @@
*
* Reads a string from the data input stream, up to the first
* occurrence of any of the stop characters.
+ *
* In contrast to g_data_input_stream_read_until(), this function
* does <emphasis>not</emphasis> consume the stop character. You have
* to use g_data_input_stream_read_byte() to get it before calling
* g_data_input_stream_read_upto() again.
+ *
* Note that @stop_chars may contain '\0' if @stop_chars_len is
* specified.
+ *
* before encountering any of the stop characters. Set @length to
* a #gsize to get the length of the string. This function will
* return %NULL on an error
@@ -17197,12 +18189,15 @@
*
* The asynchronous version of g_data_input_stream_read_upto().
* It is an error to have two outstanding calls to this function.
+ *
* In contrast to g_data_input_stream_read_until(), this function
* does <emphasis>not</emphasis> consume the stop character. You have
* to use g_data_input_stream_read_byte() to get it before calling
* g_data_input_stream_read_upto() again.
+ *
* Note that @stop_chars may contain '\0' if @stop_chars_len is
* specified.
+ *
* When the operation is finished, @callback will be called. You
* can then call g_data_input_stream_read_upto_finish() to get
* the result of the operation.
@@ -17220,9 +18215,11 @@
*
* Finish an asynchronous call started by
* g_data_input_stream_read_upto_async().
+ *
* Note that this function does <emphasis>not</emphasis> consume the
* stop character. You have to use g_data_input_stream_read_byte() to
* get it before calling g_data_input_stream_read_upto_async() again.
+ *
* before encountering any of the stop characters. Set @length to
* a #gsize to get the length of the string. This function will
* return %NULL on an error.
@@ -17248,6 +18245,7 @@
* @type: the type of new line return as #GDataStreamNewlineType.
*
* Sets the newline type for the @stream.
+ *
* Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
* chunk ends in "CR" we must read an additional byte to know if this is "CR" or
* "CR LF", and this might block if there is no more data availible.
@@ -17412,9 +18410,11 @@
* Asynchronously connects to an endpoint specified by @address and
* sets up the connection so it is in a state to run the client-side
* of the D-Bus authentication conversation.
+ *
* When the operation is finished, @callback will be invoked. You can
* then call g_dbus_address_get_stream_finish() to get the result of
* the operation.
+ *
* This is an asynchronous failable function. See
* g_dbus_address_get_stream_sync() for the synchronous version.
*
@@ -17445,6 +18445,7 @@
* Synchronously connects to an endpoint specified by @address and
* sets up the connection so it is in a state to run the client-side
* of the D-Bus authentication conversation.
+ *
* This is a synchronous failable function. See
* g_dbus_address_get_stream() for the asynchronous version.
*
@@ -17459,6 +18460,7 @@
* @name: The name of the annotation to look up.
*
* Looks up the value of an annotation.
+ *
* This cost of this function is O(n) in number of annotations.
*
* Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
@@ -17551,17 +18553,20 @@
* than once. Filters added during a filter callback won't be run on
* the message being processed. Filter functions are allowed to modify
* and even drop messages.
+ *
* Note that filters are run in a dedicated message handling thread so
* they can't block and, generally, can't do anything but signal a
* worker thread. Also note that filters are rarely needed - use API
* such as g_dbus_connection_send_message_with_reply(),
* g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
+ *
* If a filter consumes an incoming message the message is not
* dispatched anywhere else - not even the standard dispatch machinery
* (that API such as g_dbus_connection_signal_subscribe() and
* g_dbus_connection_send_message_with_reply() relies on) will see the
* message. Similary, if a filter consumes an outgoing message, the
* message will not be sent to the other peer.
+ *
* g_dbus_connection_remove_filter().
*
* Returns: A filter identifier that can be used with
@@ -17572,7 +18577,7 @@
/**
* g_dbus_connection_call:
* @connection: A #GDBusConnection.
- * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
+ * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection.
* @object_path: Path of remote object.
* @interface_name: D-Bus interface to invoke method on.
* @method_name: The name of the method to invoke.
@@ -17585,14 +18590,19 @@
* @user_data: The data to pass to @callback.
*
* Asynchronously invokes the @method_name method on the
+ * @interface_name D-Bus interface on the remote object at
+ * @object_path owned by @bus_name.
+ *
* If @connection is closed then the operation will fail with
* %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
* fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
* not compatible with the D-Bus protocol, the operation fails with
* %G_IO_ERROR_INVALID_ARGUMENT.
+ *
* If @reply_type is non-%NULL then the reply will be checked for having this type and an
* error will be raised if it does not match. Said another way, if you give a @reply_type
* then any non-%NULL return value will be of this type.
+ *
* If the @parameters #GVariant is floating, it is consumed. This allows
* convenient 'inline' use of g_variant_new(), e.g.:
* |[
@@ -17611,6 +18621,7 @@
* (GAsyncReadyCallback) two_strings_done,
* NULL);
* ]|
+ *
* This is an asynchronous method. When the operation is finished, @callback will be invoked
* in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
* of the thread you are calling this method from. You can then call
@@ -17629,6 +18640,7 @@
* @error: Return location for error or %NULL.
*
* Finishes an operation started with g_dbus_connection_call().
+ *
* return values. Free with g_variant_unref().
*
* Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
@@ -17651,6 +18663,9 @@
* @error: Return location for error or %NULL.
*
* Synchronously invokes the @method_name method on the
+ * @interface_name D-Bus interface on the remote object at
+ * @object_path owned by @bus_name.
+ *
* If @connection is closed then the operation will fail with
* %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
* operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
@@ -17660,6 +18675,7 @@
* this type and an error will be raised if it does not match. Said
* another way, if you give a @reply_type then any non-%NULL return
* value will be of this type.
+ *
* If the @parameters #GVariant is floating, it is consumed.
* This allows convenient 'inline' use of g_variant_new(), e.g.:
* |[
@@ -17677,9 +18693,11 @@
* NULL,
* &error);
* ]|
+ *
* The calling thread is blocked until a reply is received. See
* g_dbus_connection_call() for the asynchronous version of
* this method.
+ *
* return values. Free with g_variant_unref().
*
* Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
@@ -17690,7 +18708,7 @@
/**
* g_dbus_connection_call_with_unix_fd_list:
* @connection: A #GDBusConnection.
- * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
+ * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection.
* @object_path: Path of remote object.
* @interface_name: D-Bus interface to invoke method on.
* @method_name: The name of the method to invoke.
@@ -17704,6 +18722,7 @@
* @user_data: The data to pass to @callback.
*
* Like g_dbus_connection_call() but also takes a #GUnixFDList object.
+ *
* This method is only available on UNIX.
*
* Since: 2.30
@@ -17718,6 +18737,7 @@
* @error: Return location for error or %NULL.
*
* Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
+ *
* return values. Free with g_variant_unref().
*
* Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
@@ -17742,7 +18762,9 @@
* @error: Return location for error or %NULL.
*
* Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
+ *
* This method is only available on UNIX.
+ *
* return values. Free with g_variant_unref().
*
* Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
@@ -17760,17 +18782,22 @@
* Closes @connection. Note that this never causes the process to
* exit (this might only happen if the other end of a shared message
* bus connection disconnects, see #GDBusConnection:exit-on-close).
+ *
* Once the connection is closed, operations such as sending a message
* will return with the error %G_IO_ERROR_CLOSED. Closing a connection
* will not automatically flush the connection so queued messages may
* be lost. Use g_dbus_connection_flush() if you need such guarantees.
+ *
* If @connection is already closed, this method fails with
* %G_IO_ERROR_CLOSED.
+ *
* When @connection has been closed, the #GDBusConnection::closed
* signal is emitted in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread that @connection was constructed in.
+ *
* This is an asynchronous method. When the operation is finished,
+ * @callback will be invoked in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread you are calling this method from. You can
* then call g_dbus_connection_close_finish() to get the result of the
@@ -17821,7 +18848,9 @@
* @error: Return location for error or %NULL.
*
* Emits a signal.
+ *
* If the parameters GVariant is floating, it is consumed.
+ *
* This can only fail if @parameters is not compatible with the D-Bus protocol.
*
* Returns: %TRUE unless @error is set.
@@ -17843,7 +18872,9 @@
* immediately. Without flushing the connection, there is no guarantee
* that the message has been sent to the networking buffers in the OS
* kernel.
+ *
* This is an asynchronous method. When the operation is finished,
+ * @callback will be invoked in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread you are calling this method from. You can
* then call g_dbus_connection_flush_finish() to get the result of the
@@ -17901,6 +18932,7 @@
* Gets whether the process is terminated when @connection is
* closed by the remote peer. See
* #GDBusConnection:exit-on-close for more details.
+ *
* closed by the remote peer.
*
* Returns: Whether the process is terminated when @connection is
@@ -17915,6 +18947,8 @@
* The GUID of the peer performing the role of server when
* authenticating. See #GDBusConnection:guid for more details.
*
+ * @connection.
+ *
* Returns: The GUID. Do not free this string, it is owned by
* Since: 2.26
*/
@@ -17929,9 +18963,11 @@
* (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
* when set up and the client passed credentials as part of the
* authentication process.
+ *
* In a message bus setup, the message bus is always the server and
* each application is a client. So this method will always return
* %NULL for message bus clients.
+ *
* this object, it is owned by @connection.
*
* Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free
@@ -17957,7 +18993,9 @@
* Gets the unique name of @connection as assigned by the message
* bus. This can also be used to figure out if @connection is a
* message bus connection.
+ *
* bus connection. Do not free this string, it is owned by
+ * @connection.
*
* Returns: The unique name or %NULL if @connection is not a message
* Since: 2.26
@@ -17987,13 +19025,17 @@
*
* Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
* with the end represented by @stream.
+ *
* If @stream is a #GSocketConnection, then the corresponding #GSocket
* will be put into non-blocking mode.
+ *
* If @observer is not %NULL it may be used to control the
* authentication process.
+ *
* When the operation is finished, @callback will be invoked. You can
* then call g_dbus_connection_new_finish() to get the result of the
* operation.
+ *
* This is a asynchronous failable constructor. See
* g_dbus_connection_new_sync() for the synchronous
* version.
@@ -18026,16 +19068,20 @@
* Asynchronously connects and sets up a D-Bus client connection for
* exchanging D-Bus messages with an endpoint specified by @address
* which must be in the D-Bus address format.
+ *
* This constructor can only be used to initiate client-side
* connections - use g_dbus_connection_new() if you need to act as the
* server. In particular, @flags cannot contain the
* %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
* %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
+ *
* When the operation is finished, @callback will be invoked. You can
* then call g_dbus_connection_new_finish() to get the result of the
* operation.
+ *
* If @observer is not %NULL it may be used to control the
* authentication process.
+ *
* This is a asynchronous failable constructor. See
* g_dbus_connection_new_for_address_sync() for the synchronous
* version.
@@ -18067,13 +19113,16 @@
* Synchronously connects and sets up a D-Bus client connection for
* exchanging D-Bus messages with an endpoint specified by @address
* which must be in the D-Bus address format.
+ *
* This constructor can only be used to initiate client-side
* connections - use g_dbus_connection_new_sync() if you need to act
* as the server. In particular, @flags cannot contain the
* %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
* %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
+ *
* This is a synchronous failable constructor. See
* g_dbus_connection_new_for_address() for the asynchronous version.
+ *
* If @observer is not %NULL it may be used to control the
* authentication process.
*
@@ -18093,10 +19142,13 @@
*
* Synchronously sets up a D-Bus connection for exchanging D-Bus messages
* with the end represented by @stream.
+ *
* If @stream is a #GSocketConnection, then the corresponding #GSocket
* will be put into non-blocking mode.
+ *
* If @observer is not %NULL it may be used to control the
* authentication process.
+ *
* This is a synchronous failable constructor. See
* g_dbus_connection_new() for the asynchronous version.
*
@@ -18111,39 +19163,49 @@
* @object_path: The object path to register at.
* @interface_info: Introspection data for the interface.
* @vtable: (allow-none): A #GDBusInterfaceVTable to call into or %NULL.
- * @user_data: Data to pass to functions in @vtable.
+ * @user_data: (allow-none): Data to pass to functions in @vtable.
* @user_data_free_func: Function to call when the object path is unregistered.
* @error: Return location for error or %NULL.
*
* Registers callbacks for exported objects at @object_path with the
* D-Bus interface that is described in @interface_info.
+ *
* Calls to functions in @vtable (and @user_data_free_func) will
* happen in the <link linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread you are calling this method from.
+ *
* Note that all #GVariant values passed to functions in @vtable will match
* the signature given in @interface_info - if a remote caller passes
* incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal>
* is returned to the remote caller.
+ *
* Additionally, if the remote caller attempts to invoke methods or
* access properties not mentioned in @interface_info the
* <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp.
* <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors
* are returned to the caller.
+ *
* It is considered a programming error if the
* #GDBusInterfaceGetPropertyFunc function in @vtable returns a
* #GVariant of incorrect type.
+ *
* If an existing callback is already registered at @object_path and
+ * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
+ *
* GDBus automatically implements the standard D-Bus interfaces
* org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
* and org.freedesktop.Peer, so you don't have to implement those for
* the objects you export. You <emphasis>can</emphasis> implement
* org.freedesktop.DBus.Properties yourself, e.g. to handle getting
* and setting of properties asynchronously.
+ *
* Note that the reference count on @interface_info will be
* incremented by 1 (unless allocated statically, e.g. if the
* reference count is -1, see g_dbus_interface_info_ref()) for as long
* as the object is exported. Also note that @vtable will be copied.
+ *
* See <xref linkend="gdbus-server"/> for an example of how to use this method.
+ *
* that can be used with g_dbus_connection_unregister_object() .
*
* Returns: 0 if @error is set, otherwise a registration id (never 0)
@@ -18162,21 +19224,27 @@
* @error: Return location for error or %NULL.
*
* Registers a whole subtree of <quote>dynamic</quote> objects.
+ *
* The @enumerate and @introspection functions in @vtable are used to
* convey, to remote callers, what nodes exist in the subtree rooted
* by @object_path.
+ *
* When handling remote calls into any node in the subtree, first the
+ * @enumerate function is used to check if the node exists. If the node exists
* or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
* the @introspection function is used to check if the node supports the
* requested method. If so, the @dispatch function is used to determine
* where to dispatch the call. The collected #GDBusInterfaceVTable and
* #gpointer will be used to call into the interface vtable for processing
* the request.
+ *
* All calls into user-provided code will be invoked in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread you are calling this method from.
+ *
* If an existing subtree is already registered at @object_path or
* then @error is set to #G_IO_ERROR_EXISTS.
+ *
* Note that it is valid to register regular objects (using
* g_dbus_connection_register_object()) in a subtree registered with
* g_dbus_connection_register_subtree() - if so, the subtree handler
@@ -18184,9 +19252,12 @@
* handler is to consider it a <quote>fallback handler</quote>
* for object paths not registered via g_dbus_connection_register_object()
* or other bindings.
+ *
* Note that @vtable will be copied so you cannot change it after
* registration.
+ *
* See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method.
+ *
* that can be used with g_dbus_connection_unregister_subtree() .
*
* Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
@@ -18214,20 +19285,25 @@
* @error: Return location for error or %NULL.
*
* Asynchronously sends @message to the peer represented by @connection.
+ *
* Unless @flags contain the
* %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
* will be assigned by @connection and set on @message via
* g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
* serial number used will be written to this location prior to
* submitting the message to the underlying transport.
+ *
* If @connection is closed then the operation will fail with
* %G_IO_ERROR_CLOSED. If @message is not well-formed,
* the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ *
* See <xref linkend="gdbus-server"/> and <xref
* linkend="gdbus-unix-fd-client"/> for an example of how to use this
* low-level API to send and receive UNIX file descriptors.
+ *
* Note that @message must be unlocked, unless @flags contain the
* %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+ *
* transmission, %FALSE if @error is set.
*
* Returns: %TRUE if the message was well-formed and queued for
@@ -18247,23 +19323,28 @@
* @user_data: The data to pass to @callback.
*
* Asynchronously sends @message to the peer represented by @connection.
+ *
* Unless @flags contain the
* %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
* will be assigned by @connection and set on @message via
* g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
* serial number used will be written to this location prior to
* submitting the message to the underlying transport.
+ *
* If @connection is closed then the operation will fail with
* %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
* fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
* the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ *
* This is an asynchronous method. When the operation is finished, @callback will be invoked
* in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
* of the thread you are calling this method from. You can then call
* g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
* See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
+ *
* Note that @message must be unlocked, unless @flags contain the
* %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+ *
* See <xref linkend="gdbus-server"/> and <xref
* linkend="gdbus-unix-fd-client"/> for an example of how to use this
* low-level API to send and receive UNIX file descriptors.
@@ -18279,10 +19360,12 @@
* @error: Return location for error or %NULL.
*
* Finishes an operation started with g_dbus_connection_send_message_with_reply().
+ *
* Note that @error is only set if a local in-process error
* occured. That is to say that the returned #GDBusMessage object may
* be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
* g_dbus_message_to_gerror() to transcode this to a #GError.
+ *
* See <xref linkend="gdbus-server"/> and <xref
* linkend="gdbus-unix-fd-client"/> for an example of how to use this
* low-level API to send and receive UNIX file descriptors.
@@ -18306,23 +19389,28 @@
* and blocks the calling thread until a reply is received or the
* timeout is reached. See g_dbus_connection_send_message_with_reply()
* for the asynchronous version of this method.
+ *
* Unless @flags contain the
* %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
* will be assigned by @connection and set on @message via
* g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
* serial number used will be written to this location prior to
* submitting the message to the underlying transport.
+ *
* If @connection is closed then the operation will fail with
* %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
* fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
* the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ *
* Note that @error is only set if a local in-process error
* occured. That is to say that the returned #GDBusMessage object may
* be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
* g_dbus_message_to_gerror() to transcode this to a #GError.
+ *
* See <xref linkend="gdbus-server"/> and <xref
* linkend="gdbus-unix-fd-client"/> for an example of how to use this
* low-level API to send and receive UNIX file descriptors.
+ *
* Note that @message must be unlocked, unless @flags contain the
* %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
*
@@ -18339,6 +19427,7 @@
* Sets whether the process should be terminated when @connection is
* closed by the remote peer. See #GDBusConnection:exit-on-close for
* more details.
+ *
* Note that this function should be used with care. Most modern UNIX
* desktops tie the notion of a user session the session bus, and expect
* all of a users applications to quit when their bus connection goes away.
@@ -18361,15 +19450,17 @@
* @flags: Flags describing how to subscribe to the signal (currently unused).
* @callback: Callback to invoke when there is a signal matching the requested data.
* @user_data: User data to pass to @callback.
- * @user_data_free_func: Function to free @user_data with when subscription is removed or %NULL.
+ * @user_data_free_func: (allow-none): Function to free @user_data with when subscription is removed or %NULL.
*
* Subscribes to signals on @connection and invokes @callback with a
* whenever the signal is received. Note that @callback
* will be invoked in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread you are calling this method from.
+ *
* If @connection is not a message bus connection, @sender must be
* %NULL.
+ *
* If @sender is a well-known name note that @callback is invoked with
* the unique name for the owner of @sender, not the well-known name
* as one would expect. This is because the message bus rewrites the
@@ -18437,10 +19528,12 @@
* Creates a D-Bus error name to use for @error. If @error matches
* a registered error (cf. g_dbus_error_register_error()), the corresponding
* D-Bus error name will be returned.
+ *
* Otherwise the a name of the form
* <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal>
* will be used. This allows other GDBus applications to map the error
* on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
+ *
* This function is typically only used in object mappings to put a
* #GError on the wire. Regular applications should not use it.
*
@@ -18454,6 +19547,7 @@
* @error: A #GError.
*
* Gets the D-Bus error name used for @error, if any.
+ *
* This function is guaranteed to return a D-Bus error name for all
* #GError<!-- -->s returned from functions handling remote method
* calls (e.g. g_dbus_connection_call_finish()) unless
@@ -18470,6 +19564,7 @@
*
* Checks if @error represents an error received via D-Bus from a remote peer. If so,
* use g_dbus_error_get_remote_error() to get the name of the error.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if @error represents an error from a remote peer,
@@ -18483,22 +19578,28 @@
* @dbus_error_message: D-Bus error message.
*
* Creates a #GError based on the contents of @dbus_error_name and
+ * @dbus_error_message.
+ *
* Errors registered with g_dbus_error_register_error() will be looked
* up using @dbus_error_name and if a match is found, the error domain
* and code is used. Applications can use g_dbus_error_get_remote_error()
* to recover @dbus_error_name.
+ *
* If a match against a registered error is not found and the D-Bus
* error name is in a form as returned by g_dbus_error_encode_gerror()
* the error domain and code encoded in the name is used to
* create the #GError. Also, @dbus_error_name is added to the error message
* such that it can be recovered with g_dbus_error_get_remote_error().
+ *
* Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
* in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
* added to the error message such that it can be recovered with
* g_dbus_error_get_remote_error().
+ *
* In all three cases, @dbus_error_name can always be recovered from the
* returned #GError using the g_dbus_error_get_remote_error() function
* (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
+ *
* This function is typically only used in object mappings to prepare
* #GError instances for applications. Regular applications should not use
* it.
@@ -18516,8 +19617,10 @@
*
* Creates an association to map between @dbus_error_name and
* #GError<!-- -->s specified by @error_domain and @error_code.
+ *
* This is typically done in the routine that returns the #GQuark for
* an error domain.
+ *
* exists.
*
* Returns: %TRUE if the association was created, %FALSE if it already
@@ -18576,6 +19679,7 @@
* the D-Bus error name and strips it if found. If stripped, the
* message field in @error will correspond exactly to what was
* received on the wire.
+ *
* This is typically used when presenting errors to the end user.
*
* Returns: %TRUE if information was stripped, %FALSE otherwise.
@@ -18601,6 +19705,7 @@
*
* Generate a D-Bus GUID that can be used with
* e.g. g_dbus_connection_new().
+ *
* See the D-Bus specification regarding what strings are valid D-Bus
* GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
*
@@ -18615,6 +19720,7 @@
* @type: A #GVariantType.
*
* Converts a #GValue to a #GVariant of the type indicated by the @type parameter.
+ *
* The conversion is using the following rules:
* <table frame='all'>
* <title>#GValue / #GVariant conversion rules</title>
@@ -18673,13 +19779,17 @@
* is <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>. It will
* also fail for any #GType (including e.g. #G_TYPE_OBJECT and
* #G_TYPE_BOXED derived-types) not in the table above.
+ *
* Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
* %NULL, the <emphasis>empty</emphasis> #GVariant instance (never
* %NULL) for @type is returned (e.g. 0 for scalar types, the empty
* string for string types, <literal>'/'</literal> for object path
* types, the empty array for any array type and so on).
+ *
* See the g_dbus_gvariant_to_gvalue() function for how to convert a
* #GVariant to a #GValue.
+ *
+ * @type holding the data from @gvalue or %NULL in case of
* failure. Free with g_variant_unref().
*
* Returns: A #GVariant (never floating) of #GVariantType
@@ -18693,9 +19803,12 @@
* @out_gvalue: Return location pointing to a zero-filled (uninitialized) #GValue.
*
* Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
+ *
* The rules specified in the g_dbus_gvalue_to_gvariant() function are
* used - this function is essentially its reverse form.
+ *
* The conversion never fails - a valid #GValue is always returned in
+ * @out_gvalue.
*
* Since: 2.30
*/
@@ -18718,6 +19831,7 @@
* @interface_: An exported D-Bus interface.
*
* Gets the #GDBusObject that @interface_ belongs to, if any.
+ *
* reference belongs to @interface_ and should not be freed.
*
* Returns: (transfer none): A #GDBusObject or %NULL. The returned
@@ -18733,8 +19847,10 @@
* g_dbus_interface_info_lookup_method(),
* g_dbus_interface_info_lookup_signal() and
* g_dbus_interface_info_lookup_property().
+ *
* If this has already been called with @info, the existing cache is
* used and its use count is increased.
+ *
* Note that @info cannot be modified until
* g_dbus_interface_info_cache_release() is called.
*
@@ -18758,9 +19874,10 @@
* g_dbus_interface_info_generate_xml:
* @info: A #GDBusNodeInfo
* @indent: Indentation level.
- * @string_builder: A #GString to to append XML data to.
+ * @string_builder: (out): A #GString to to append XML data to.
*
* Appends an XML representation of @info (and its children) to @string_builder.
+ *
* This function is typically used for generating introspection XML
* documents at run-time for handling the
* <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>
@@ -18776,6 +19893,7 @@
* @name: A D-Bus method name (typically in CamelCase)
*
* Looks up information about a method.
+ *
* This cost of this function is O(n) in number of methods unless
* g_dbus_interface_info_cache_build() has been used on @info.
*
@@ -18790,6 +19908,7 @@
* @name: A D-Bus property name (typically in CamelCase).
*
* Looks up information about a property.
+ *
* This cost of this function is O(n) in number of properties unless
* g_dbus_interface_info_cache_build() has been used on @info.
*
@@ -18804,6 +19923,7 @@
* @name: A D-Bus signal name (typically in CamelCase)
*
* Looks up information about a signal.
+ *
* This cost of this function is O(n) in number of signals unless
* g_dbus_interface_info_cache_build() has been used on @info.
*
@@ -18842,6 +19962,7 @@
* @object: A #GDBusObject or %NULL.
*
* Sets the #GDBusObject for @interface_ to @object.
+ *
* Note that @interface_ will hold a weak reference to @object.
*
* Since: 2.30
@@ -18856,8 +19977,11 @@
* @error: Return location for error or %NULL.
*
* Exports @interface_ at @object_path on @connection.
+ *
* Use g_dbus_interface_skeleton_unexport() to unexport the object.
*
+ * @error set.
+ *
* Returns: %TRUE if the interface was exported, other %FALSE with
* Since: 2.30
*/
@@ -18869,6 +19993,7 @@
*
* If @interface_ has outstanding changes, request for these changes to be
* emitted immediately.
+ *
* For example, an exported D-Bus interface may queue up property
* changes and emit the
* <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
@@ -18884,6 +20009,7 @@
* @interface_: A #GDBusInterfaceSkeleton.
*
* Gets the connection that @interface_ is exported on, if any.
+ *
* not exported anywhere. Do not free, the object belongs to @interface_.
*
* Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
@@ -18920,6 +20046,7 @@
* @interface_: A #GDBusInterfaceSkeleton.
*
* Gets the object path that @interface_ is exported on, if any.
+ *
* anywhere. Do not free, the string belongs to @interface_.
*
* Returns: A string owned by @interface_ or %NULL if @interface_ is not exported
@@ -18943,6 +20070,7 @@
* @interface_: A #GDBusInterfaceSkeleton.
*
* Gets the interface vtable for the D-Bus interface implemented by
+ * @interface_. The returned function pointers should expect @interface_
* itself to be passed as @user_data.
*
* Returns: A #GDBusInterfaceVTable (never %NULL).
@@ -18977,6 +20105,7 @@
* @string: A string.
*
* Checks if @string is a D-Bus address.
+ *
* This doesn't check if @string is actually supported by #GDBusServer
* or #GDBusConnection - use g_dbus_is_supported_address() to do more
* checks.
@@ -18991,6 +20120,7 @@
* @string: The string to check.
*
* Checks if @string is a D-Bus GUID.
+ *
* See the D-Bus specification regarding what strings are valid D-Bus
* GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
*
@@ -19040,6 +20170,7 @@
* Like g_dbus_is_address() but also checks if the library suppors the
* transports in @string and that key/value pairs for each transport
* are valid.
+ *
* supported by this library, %FALSE if @error is set.
*
* Returns: %TRUE if @string is a valid D-Bus address that is
@@ -19066,6 +20197,8 @@
*
* Utility function to calculate how many bytes are needed to
* completely deserialize the D-Bus message stored at @blob.
+ *
+ * @blob contains invalid data or not enough data is available to
* determine the size).
*
* Returns: Number of bytes needed or -1 if @error is set (e.g. if
@@ -19081,8 +20214,10 @@
* Copies @message. The copy is a deep copy and the returned
* #GDBusMessage is completely identical except that it is guaranteed
* to not be locked.
+ *
* This operation can fail if e.g. @message contains file descriptors
* and the per-process or system-wide open files limit is reached.
+ *
* Free with g_object_unref().
*
* Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
@@ -19096,6 +20231,8 @@
*
* Convenience to get the first item in the body of @message.
*
+ * @message is not a string.
+ *
* Returns: The string item or %NULL if the first item in the body of
* Since: 2.26
*/
@@ -19161,6 +20298,7 @@
* @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
*
* Gets a header field on @message.
+ *
* otherwise. Do not free, it is owned by @message.
*
* Returns: A #GVariant with the value if the header was found, %NULL
@@ -19173,6 +20311,7 @@
* @message: A #GDBusMessage.
*
* Gets an array of all header fields on @message that are set.
+ *
* %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a
* #guchar. Free with g_free().
*
@@ -19298,7 +20437,9 @@
* @message: A #GDBusMessage.
*
* Gets the UNIX file descriptors associated with @message, if any.
+ *
* This method is only available on UNIX.
+ *
* associated. Do not free, this object is owned by @message.
*
* Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
@@ -19336,6 +20477,7 @@
* Creates a new #GDBusMessage from the data stored at @blob. The byte
* order that the message was in can be retrieved using
* g_dbus_message_get_byte_order().
+ *
* g_object_unref().
*
* Returns: A new #GDBusMessage or %NULL if @error is set. Free with
@@ -19428,34 +20570,39 @@
* @indent: Indentation level.
*
* Produces a human-readable multi-line description of @message.
+ *
* The contents of the description has no ABI guarantees, the contents
* and formatting is subject to change at any time. Typical output
* looks something like this:
* <programlisting>
+ * Flags: none
+ * Version: 0
+ * Serial: 4
* Headers:
* path -> objectpath '/org/gtk/GDBus/TestObject'
* interface -> 'org.gtk.GDBus.TestInterface'
* member -> 'GimmeStdout'
* destination -> ':1.146'
+ * Body: ()
* UNIX File Descriptors:
* (none)
* </programlisting>
* or
* <programlisting>
+ * Flags: no-reply-expected
+ * Version: 0
+ * Serial: 477
* Headers:
* reply-serial -> uint32 4
* destination -> ':1.159'
* sender -> ':1.146'
* num-unix-fds -> uint32 1
+ * Body: ()
* UNIX File Descriptors:
+ * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
* </programlisting>
*
* Type: method-return
- * Flags: no-reply-expected
- * Version: 0
- * Serial: 477
- * Body: ()
- * Fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
* Returns: A string that should be freed with g_free().
* Since: 2.26
*/
@@ -19469,6 +20616,7 @@
* Sets the body @message. As a side-effect the
* %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
* type string of @body (or cleared if @body is %NULL).
+ *
* If @body is floating, @message assumes ownership of @body.
*
* Since: 2.26
@@ -19524,6 +20672,7 @@
* @value: A #GVariant to set the header field or %NULL to clear the header field.
*
* Sets a header field on @message.
+ *
* If @value is floating, @message assumes ownership of @value.
*
* Since: 2.26
@@ -19637,6 +20786,8 @@
* Sets the UNIX file descriptors associated with @message. As a
* side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
* field is set to the number of fds in @fd_list (or cleared if
+ * @fd_list is %NULL).
+ *
* This method is only available on UNIX.
*
* Since: 2.26
@@ -19652,6 +20803,7 @@
*
* Serializes @message to a blob. The byte order returned by
* g_dbus_message_get_byte_order() will be used.
+ *
* generated by @message or %NULL if @error is set. Free with g_free().
*
* Returns: A pointer to a valid binary D-Bus message of @out_size bytes
@@ -19666,6 +20818,7 @@
*
* If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
* nothing and returns %FALSE.
+ *
* Otherwise this method encodes the error in @message as a #GError
* using g_dbus_error_set_dbus_error() using the information in the
* %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
@@ -19730,6 +20883,7 @@
* you need to use low-level protocol features, such as UNIX file
* descriptor passing, that cannot be properly expressed in the
* #GVariant API.
+ *
* See <xref linkend="gdbus-server"/> and <xref
* linkend="gdbus-unix-fd-client"/> for an example of how to use this
* low-level API to send and receive UNIX file descriptors.
@@ -19813,6 +20967,7 @@
* @error_message: A valid D-Bus error message.
*
* Finishes handling a D-Bus method call by returning an error.
+ *
* This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.26
@@ -19828,6 +20983,7 @@
* @...: Parameters for @format.
*
* Finishes handling a D-Bus method call by returning an error.
+ *
* See g_dbus_error_encode_gerror() for details about what error name
* will be returned on the wire. In a nutshell, if the given error is
* registered using g_dbus_error_register_error() the name given
@@ -19835,9 +20991,11 @@
* <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is
* used. This provides transparent mapping of #GError between
* applications using GDBus.
+ *
* If you are writing an application intended to be portable,
* <emphasis>always</emphasis> register errors with g_dbus_error_register_error()
* or use g_dbus_method_invocation_return_dbus_error().
+ *
* This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.26
@@ -19852,6 +21010,7 @@
* @message: The error message.
*
* Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
+ *
* This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.26
@@ -19868,6 +21027,7 @@
*
* Like g_dbus_method_invocation_return_error() but intended for
* language bindings.
+ *
* This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.26
@@ -19881,6 +21041,7 @@
*
* Like g_dbus_method_invocation_return_error() but takes a #GError
* instead of the error domain, error code and message.
+ *
* This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.26
@@ -19894,7 +21055,9 @@
*
* Finishes handling a D-Bus method call by returning @parameters.
* If the @parameters GVariant is floating, it is consumed.
+ *
* It is an error if @parameters is not of the right format.
+ *
* This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.26
@@ -19908,7 +21071,9 @@
* @fd_list: (allow-none): A #GUnixFDList or %NULL.
*
* Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
+ *
* This method is only available on UNIX.
+ *
* This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.30
@@ -19922,6 +21087,7 @@
*
* Like g_dbus_method_invocation_return_gerror() but takes ownership
* of @error so the caller does not need to free it.
+ *
* This method will free @invocation, you cannot use it afterwards.
*
* Since: 2.30
@@ -19932,9 +21098,10 @@
* g_dbus_node_info_generate_xml:
* @info: A #GDBusNodeInfo.
* @indent: Indentation level.
- * @string_builder: A #GString to to append XML data to.
+ * @string_builder: (out): A #GString to to append XML data to.
*
* Appends an XML representation of @info (and its children) to @string_builder.
+ *
* This function is typically used for generating introspection XML documents at run-time for
* handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.
*
@@ -19948,9 +21115,10 @@
* @name: A D-Bus interface name.
*
* Looks up information about an interface.
+ *
* This cost of this function is O(n) in number of interfaces.
*
- * Returns: A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
+ * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
* Since: 2.26
*/
@@ -19961,6 +21129,7 @@
* @error: Return location for error.
*
* Parses @xml_data and returns a #GDBusNodeInfo representing the data.
+ *
* with g_dbus_node_info_unref().
*
* Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
@@ -19998,6 +21167,8 @@
* @interface_name: A D-Bus interface name.
*
* Gets the D-Bus interface with name @interface_name associated with
+ * @object, if any.
+ *
* #GDBusInterface that must be freed with g_object_unref().
*
* Returns: (transfer full): %NULL if not found, otherwise a
@@ -20010,6 +21181,7 @@
* @object: A #GDBusObject.
*
* Gets the D-Bus interfaces associated with @object.
+ *
* The returned list must be freed by g_list_free() after each element has been freed
* with g_object_unref().
*
@@ -20034,6 +21206,7 @@
* @manager: A #GDBusObjectManagerClient
*
* Gets the #GDBusConnection used by @manager.
+ *
* the object belongs to @manager.
*
* Returns: (transfer none): A #GDBusConnection object. Do not free,
@@ -20046,6 +21219,7 @@
* @manager: A #GDBusObjectManagerClient
*
* Gets the flags that @manager was constructed with.
+ *
* enumeration.
*
* Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
@@ -20058,6 +21232,7 @@
* @manager: A #GDBusObjectManagerClient
*
* Gets the name that @manager is for.
+ *
* belongs to @manager.
*
* Returns: A unique or well-known name. Do not free, the string
@@ -20073,6 +21248,7 @@
* no-one currently owns that name. You can connect to the
* #GObject::notify signal to track changes to the
* #GDBusObjectManagerClient:name-owner property.
+ *
* g_free().
*
* Returns: The name owner or %NULL if no name owner exists. Free with
@@ -20094,6 +21270,7 @@
* @user_data: The data to pass to @callback.
*
* Asynchronously creates a new #GDBusObjectManagerClient object.
+ *
* This is an asynchronous failable constructor. When the result is
* ready, @callback will be invoked in the
* <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
@@ -20111,6 +21288,7 @@
* @error: Return location for error or %NULL.
*
* Finishes an operation started with g_dbus_object_manager_client_new().
+ *
* #GDBusObjectManagerClient object or %NULL if @error is set. Free
* with g_object_unref().
*
@@ -20134,6 +21312,7 @@
*
* Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
* #GDBusConnection.
+ *
* This is an asynchronous failable constructor. When the result is
* ready, @callback will be invoked in the
* <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
@@ -20151,6 +21330,7 @@
* @error: Return location for error or %NULL.
*
* Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
+ *
* #GDBusObjectManagerClient object or %NULL if @error is set. Free
* with g_object_unref().
*
@@ -20173,9 +21353,11 @@
*
* Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
* of a #GDBusConnection.
+ *
* This is a synchronous failable constructor - the calling thread is
* blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
* for the asynchronous version.
+ *
* #GDBusObjectManagerClient object or %NULL if @error is set. Free
* with g_object_unref().
*
@@ -20197,9 +21379,11 @@
* @error: Return location for error or %NULL.
*
* Creates a new #GDBusObjectManagerClient object.
+ *
* This is a synchronous failable constructor - the calling thread is
* blocked until a reply is received. See g_dbus_object_manager_client_new()
* for the asynchronous version.
+ *
* #GDBusObjectManagerClient object or %NULL if @error is set. Free
* with g_object_unref().
*
@@ -20216,6 +21400,7 @@
*
* Gets the interface proxy for @interface_name at @object_path, if
* any.
+ *
* with g_object_unref().
*
* Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
@@ -20229,6 +21414,7 @@
* @object_path: Object path to lookup.
*
* Gets the #GDBusObjectProxy at @object_path, if any.
+ *
* g_object_unref().
*
* Returns: (transfer full): A #GDBusObject or %NULL. Free with
@@ -20252,6 +21438,7 @@
* @manager: A #GDBusObjectManager.
*
* Gets all #GDBusObject objects known to @manager.
+ *
* #GDBusObject objects. The returned list should be freed with
* g_list_free() after each element has been freed with
* g_object_unref().
@@ -20267,10 +21454,13 @@
* @object: A #GDBusObjectSkeleton.
*
* Exports @object on @manager.
+ *
* If there is already a #GDBusObject exported at the object path,
* then the old object is removed.
+ *
* The object path for @object must be in the hierarchy rooted by the
* object path for @manager.
+ *
* Note that @manager will take a reference on @object for as long as
* it is exported.
*
@@ -20285,6 +21475,7 @@
*
* Like g_dbus_object_manager_server_export() but appends a string of
* the form <literal>_N</literal> (with N being a natural number) to
+ * @object<!-- -->'s object path if an object with the given path
* already exists. As such, the #GDBusObjectProxy:object-path property
* of @object may be modified.
*
@@ -20297,6 +21488,8 @@
* @manager: A #GDBusObjectManagerServer
*
* Gets the #GDBusConnection used by @manager.
+ *
+ * @manager isn't exported on a connection. The returned object should
* be freed with g_object_unref().
*
* Returns: (transfer full): A #GDBusConnection object or %NULL if
@@ -20309,6 +21502,7 @@
* @object_path: The object path to export the manager object at.
*
* Creates a new #GDBusObjectManagerServer object.
+ *
* The returned server isn't yet exported on any connection. To do so,
* use g_dbus_object_manager_server_set_connection(). Normally you
* want to export all of your objects before doing so to avoid <ulink
@@ -20326,6 +21520,7 @@
* @connection: (allow-none): A #GDBusConnection or %NULL.
*
* Exports all objects managed by @manager on @connection. If
+ * @connection is %NULL, stops exporting objects.
*/
@@ -20336,6 +21531,7 @@
*
* If @manager has an object at @path, removes the object. Otherwise
* does nothing.
+ *
* Note that @object_path must be in the hierarchy rooted by the
* object path for @manager.
*
@@ -20349,6 +21545,7 @@
* @proxy: a #GDBusObjectProxy
*
* Gets the connection that @proxy is for.
+ *
* object is owned by @proxy.
*
* Returns: (transfer none): A #GDBusConnection. Do not free, the
@@ -20375,8 +21572,10 @@
* @interface_: A #GDBusInterfaceSkeleton.
*
* Adds @interface_ to @object.
+ *
* If @object already contains a #GDBusInterfaceSkeleton with the same
* interface name, it is removed before @interface_ is added.
+ *
* Note that @object takes its own reference on @interface_ and holds
* it until removed.
*
@@ -20424,6 +21623,7 @@
* @interface_name: A D-Bus interface name.
*
* Removes the #GDBusInterface with @interface_name from @object.
+ *
* If no D-Bus interface of the given interface exists, this function
* does nothing.
*
@@ -20478,14 +21678,18 @@
* @user_data: The data to pass to @callback.
*
* Asynchronously invokes the @method_name method on @proxy.
+ *
* If @method_name contains any dots, then @name is split into interface and
* method name parts. This allows using @proxy for invoking methods on
* other interfaces.
+ *
* If the #GDBusConnection associated with @proxy is closed then
* the operation will fail with %G_IO_ERROR_CLOSED. If
+ * @cancellable is canceled, the operation will fail with
* %G_IO_ERROR_CANCELLED. If @parameters contains a value not
* compatible with the D-Bus protocol, the operation fails with
* %G_IO_ERROR_INVALID_ARGUMENT.
+ *
* If the @parameters #GVariant is floating, it is consumed. This allows
* convenient 'inline' use of g_variant_new(), e.g.:
* |[
@@ -20500,7 +21704,9 @@
* (GAsyncReadyCallback) two_strings_done,
* &data);
* ]|
+ *
* This is an asynchronous method. When the operation is finished,
+ * @callback will be invoked in the
* <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
* of the thread you are calling this method from.
* You can then call g_dbus_proxy_call_finish() to get the result of
@@ -20518,6 +21724,7 @@
* @error: Return location for error or %NULL.
*
* Finishes an operation started with g_dbus_proxy_call().
+ *
* return values. Free with g_variant_unref().
*
* Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
@@ -20536,14 +21743,18 @@
* @error: Return location for error or %NULL.
*
* Synchronously invokes the @method_name method on @proxy.
+ *
* If @method_name contains any dots, then @name is split into interface and
* method name parts. This allows using @proxy for invoking methods on
* other interfaces.
+ *
* If the #GDBusConnection associated with @proxy is disconnected then
* the operation will fail with %G_IO_ERROR_CLOSED. If
+ * @cancellable is canceled, the operation will fail with
* %G_IO_ERROR_CANCELLED. If @parameters contains a value not
* compatible with the D-Bus protocol, the operation fails with
* %G_IO_ERROR_INVALID_ARGUMENT.
+ *
* If the @parameters #GVariant is floating, it is consumed. This allows
* convenient 'inline' use of g_variant_new(), e.g.:
* |[
@@ -20557,9 +21768,11 @@
* NULL,
* &error);
* ]|
+ *
* The calling thread is blocked until a reply is received. See
* g_dbus_proxy_call() for the asynchronous version of this
* method.
+ *
* return values. Free with g_variant_unref().
*
* Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
@@ -20580,6 +21793,7 @@
* @user_data: The data to pass to @callback.
*
* Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
+ *
* This method is only available on UNIX.
*
* Since: 2.30
@@ -20594,6 +21808,7 @@
* @error: Return location for error or %NULL.
*
* Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
+ *
* return values. Free with g_variant_unref().
*
* Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
@@ -20614,7 +21829,9 @@
* @error: Return location for error or %NULL.
*
* Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
+ *
* This method is only available on UNIX.
+ *
* return values. Free with g_variant_unref().
*
* Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
@@ -20629,9 +21846,11 @@
*
* Looks up the value for a property from the cache. This call does no
* blocking IO.
+ *
* If @proxy has an expected interface (see
* #GDBusProxy:g-interface-info), then @property_name (for existence)
* is checked against it.
+ *
* for @property_name or %NULL if the value is not in the cache. The
* returned reference must be freed with g_variant_unref().
*
@@ -20645,9 +21864,11 @@
* @proxy: A #GDBusProxy.
*
* Gets the names of all cached properties on @proxy.
- * no cached properties. Free the returned array with g_strfreev().
*
- * Returns: A %NULL-terminated array of strings or %NULL if @proxy has
+ * @proxy has no cached properties. Free the returned array with
+ * g_strfreev().
+ *
+ * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
* Since: 2.26
*/
@@ -20670,6 +21891,7 @@
* Gets the timeout to use if -1 (specifying default timeout) is
* passed as @timeout_msec in the g_dbus_proxy_call() and
* g_dbus_proxy_call_sync() functions.
+ *
* See the #GDBusProxy:g-default-timeout property for more details.
*
* Returns: Timeout to use for @proxy.
@@ -20694,7 +21916,9 @@
*
* Returns the #GDBusInterfaceInfo, if any, specifying the minimal
* interface that @proxy conforms to.
+ *
* See the #GDBusProxy:g-interface-info property for more details.
+ *
* object, it is owned by @proxy.
*
* Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
@@ -20767,17 +21991,22 @@
* %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
* the #GDBusProxy::g-properties-changed signal to get notified about
* property changes.
+ *
* If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
* match rules for signals. Connect to the #GDBusProxy::g-signal signal
* to handle signals from the remote object.
+ *
* If @name is a well-known name and the
* %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name
* owner currently exists, the message bus will be requested to launch
* a name owner for the name.
+ *
* This is a failable asynchronous constructor - when the proxy is
* ready, @callback will be invoked and you can use
* g_dbus_proxy_new_finish() to get the result.
+ *
* See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
+ *
* See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
*
* Since: 2.26
@@ -20809,6 +22038,7 @@
* @user_data: User data to pass to @callback.
*
* Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
+ *
* See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
*
* Since: 2.26
@@ -20839,6 +22069,7 @@
* @error: Return location for error or %NULL.
*
* Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
+ *
* See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
*
* Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
@@ -20861,15 +22092,19 @@
* at @object_path owned by @name at @connection and synchronously
* loads D-Bus properties unless the
* %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
+ *
* If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
* match rules for signals. Connect to the #GDBusProxy::g-signal signal
* to handle signals from the remote object.
+ *
* If @name is a well-known name and the
* %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name
* owner currently exists, the message bus will be requested to launch
* a name owner for the name.
+ *
* This is a synchronous failable constructor. See g_dbus_proxy_new()
* and g_dbus_proxy_new_finish() for the asynchronous version.
+ *
* See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
*
* Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
@@ -20885,11 +22120,14 @@
*
* If @value is not %NULL, sets the cached value for the property with
* name @property_name to the value in @value.
+ *
* If @value is %NULL, then the cached value is removed from the
* property cache.
+ *
* If @proxy has an expected interface (see
* #GDBusProxy:g-interface-info), then @property_name (for existence)
* and @value (for the type) is checked against it.
+ *
* If the @value #GVariant is floating, it is consumed. This allows
* convenient 'inline' use of g_variant_new(), e.g.
* |[
@@ -20899,12 +22137,14 @@
* "A String",
* 42));
* ]|
+ *
* Normally you will not need to use this method since @proxy is
* tracking changes using the
* <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
* D-Bus signal. However, for performance reasons an object may decide
* to not use this signal for some properties and instead use a
* proprietary out-of-band mechanism to transmit changes.
+ *
* As a concrete example, consider an object with a property
* <literal>ChatroomParticipants</literal> which is an array of
* strings. Instead of transmitting the same (long) array every time
@@ -20925,6 +22165,7 @@
* Sets the timeout to use if -1 (specifying default timeout) is
* passed as @timeout_msec in the g_dbus_proxy_call() and
* g_dbus_proxy_call_sync() functions.
+ *
* See the #GDBusProxy:g-default-timeout property for more details.
*
* Since: 2.26
@@ -20941,6 +22182,7 @@
* signature of the message isn't what's expected, the given #GError
* is set. Signals that have a type signature mismatch are simply
* dropped.
+ *
* See the #GDBusProxy:g-interface-info property for more details.
*
* Since: 2.26
@@ -20953,6 +22195,7 @@
*
* Gets a D-Bus address string that can be used by clients to connect
* to @server.
+ *
* by @server.
*
* Returns: A D-Bus address string. Do not free, the string is owned
@@ -21003,16 +22246,23 @@
* @error: Return location for server or %NULL.
*
* Creates a new D-Bus server that listens on the first address in
+ * @address that works.
+ *
* Once constructed, you can use g_dbus_server_get_client_address() to
* get a D-Bus address string that clients can use to connect.
+ *
* Connect to the #GDBusServer::new-connection signal to handle
* incoming connections.
+ *
* The returned #GDBusServer isn't active - you have to start it with
* g_dbus_server_start().
+ *
* See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can
* be used.
+ *
* This is a synchronous failable constructor. See
* g_dbus_server_new() for the asynchronous version.
+ *
* g_object_unref().
*
* Returns: A #GDBusServer or %NULL if @error is set. Free with
@@ -21069,6 +22319,7 @@
* @info: a #GDesktopAppInfo
*
* Gets the categories from the desktop file.
+ *
* i.e. no attempt is made to split it by ';' or validate it.
*
* Returns: The unparsed Categories key from the desktop file;
@@ -21123,6 +22374,29 @@
/**
+ * g_desktop_app_info_get_show_in:
+ * @info: a #GDesktopAppInfo
+ * @desktop_env: a string specifying a desktop name
+ *
+ * Checks if the application info should be shown in menus that list available
+ * applications for a specific name of the desktop, based on the
+ * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys.
+ *
+ * If @desktop_env is %NULL, then the name of the desktop set with
+ * g_desktop_app_info_set_desktop_env() is used.
+ *
+ * Note that g_app_info_should_show() for @info will include this check (with
+ * %NULL for @desktop_env) as well as additional checks.
+ *
+ * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE
+ * otherwise.
+ *
+ * Returns: %TRUE if the @info should be shown in @desktop_env according to the
+ * Since: 2.30
+ */
+
+
+/**
* g_desktop_app_info_launch_uris_as_manager:
* @appinfo: a #GDesktopAppInfo
* @uris: (element-type utf8): List of URIs
@@ -21138,11 +22412,15 @@
* but is intended primarily for operating system components that
* launch applications. Ordinary applications should use
* g_app_info_launch_uris().
+ *
* In contrast to g_app_info_launch_uris(), all processes created will
* always be run directly as children as if by the UNIX fork()/exec()
* calls.
+ *
* This guarantee allows additional control over the exact environment
* of the child processes, which is provided via a setup function
+ * @setup, as well as the process identifier of each child process via
+ * @pid_callback. See g_spawn_async() for more information about the
* semantics of the @setup function.
*
* Returns: %TRUE on successful launch, %FALSE otherwise.
@@ -21157,6 +22435,7 @@
* Gets the default application for launching applications
* using this URI scheme for a particular GDesktopAppInfoLookup
* implementation.
+ *
* The GDesktopAppInfoLookup interface and this function is used
* to implement g_app_info_get_default_for_uri_scheme() backends
* in a GIO module. There is no reason for applications to use it
@@ -21172,6 +22451,7 @@
* @desktop_id: the desktop file id
*
* Creates a new #GDesktopAppInfo based on a desktop file id.
+ *
* A desktop file id is the basename of the desktop file, including the
* .desktop extension. GIO is looking for a desktop file with this name
* in the <filename>applications</filename> subdirectories of the XDG data
@@ -21212,9 +22492,11 @@
* @desktop_env: a string specifying what desktop this is
*
* Sets the name of the desktop that the application is running in.
- * This is used by g_app_info_should_show() to evaluate the
+ * This is used by g_app_info_should_show() and
+ * g_desktop_app_info_get_show_in() to evaluate the
* <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal>
* desktop entry fields.
+ *
* The <ulink url="http://standards.freedesktop.org/menu-spec/latest/";>Desktop
* Menu specification</ulink> recognizes the following:
* <simplelist>
@@ -21224,6 +22506,7 @@
* <member>XFCE</member>
* <member>Old</member>
* </simplelist>
+ *
* Should be called only once; subsequent calls are ignored.
*/
@@ -21243,6 +22526,7 @@
* @drive: a #GDrive.
*
* Checks if a drive can be polled for media changes.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if the @drive can be polled for media changes,
@@ -21291,6 +22575,7 @@
* @user_data: user data to pass to @callback
*
* Asynchronously ejects a drive.
+ *
* When the operation is finished, @callback will be called.
* You can then call g_drive_eject_finish() to obtain the
* result of the operation.
@@ -21306,6 +22591,7 @@
* @error: a #GError, or %NULL
*
* Finishes ejecting a drive.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if the drive has been ejected successfully,
@@ -21337,6 +22623,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes ejecting a drive. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
* Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
* Since: 2.22
@@ -21350,6 +22637,7 @@
* Gets the kinds of identifiers that @drive has.
* Use g_drive_get_identifer() to obtain the identifiers
* themselves.
+ *
* array of strings containing kinds of identifiers. Use g_strfreev()
* to free.
*
@@ -21362,6 +22650,7 @@
* @drive: a #GDrive.
*
* Gets the icon for @drive.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): #GIcon for the @drive.
@@ -21374,6 +22663,7 @@
* @kind: the kind of identifier to return
*
* Gets the identifier of the given kind for @drive.
+ *
* requested identfier, or %NULL if the #GDrive
* doesn't have this kind of identifier.
*
@@ -21386,6 +22676,7 @@
* @drive: a #GDrive.
*
* Gets the name of @drive.
+ *
* string should be freed when no longer needed.
*
* Returns: a string containing @drive's name. The returned
@@ -21408,6 +22699,7 @@
* @drive: a #GDrive.
*
* Get a list of mountable volumes for @drive.
+ *
* The returned list should be freed with g_list_free(), after
* its elements have been unreffed with g_object_unref().
*
@@ -21442,6 +22734,7 @@
* @drive: a #GDrive.
*
* Checks if @drive is capabable of automatically detecting media changes.
+ *
* media changes, %FALSE otherwise.
*
* Returns: %TRUE if the @drive is capabable of automatically detecting
@@ -21466,6 +22759,7 @@
* @user_data: user data to pass to @callback
*
* Asynchronously polls @drive to see if media has been inserted or removed.
+ *
* When the operation is finished, @callback will be called.
* You can then call g_drive_poll_for_media_finish() to obtain the
* result of the operation.
@@ -21479,6 +22773,7 @@
* @error: a #GError, or %NULL
*
* Finishes an operation started with g_drive_poll_for_media() on a drive.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if the drive has been poll_for_mediaed successfully,
@@ -21495,6 +22790,7 @@
* @user_data: user data to pass to @callback
*
* Asynchronously starts a drive.
+ *
* When the operation is finished, @callback will be called.
* You can then call g_drive_start_finish() to obtain the
* result of the operation.
@@ -21510,6 +22806,7 @@
* @error: a #GError, or %NULL
*
* Finishes starting a drive.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if the drive has been started successfully,
@@ -21527,6 +22824,7 @@
* @user_data: user data to pass to @callback
*
* Asynchronously stops a drive.
+ *
* When the operation is finished, @callback will be called.
* You can then call g_drive_stop_finish() to obtain the
* result of the operation.
@@ -21542,6 +22840,7 @@
* @error: a #GError, or %NULL
*
* Finishes stopping a drive.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if the drive has been stopped successfully,
@@ -21554,6 +22853,7 @@
* @emblem: a #GEmblem from which the icon should be extracted.
*
* Gives back the icon from @emblem.
+ *
* the emblem and should not be modified or freed.
*
* Returns: (transfer none): a #GIcon. The returned object belongs to
@@ -21621,6 +22921,7 @@
* @emblemed: a #GEmblemedIcon
*
* Gets the list of emblems for the @icon.
+ *
* #GEmblem <!-- -->s that is owned by @emblemed
*
* Returns: (element-type Gio.Emblem) (transfer none): a #GList of
@@ -21660,18 +22961,22 @@
*
* Gets an output stream for appending data to the file. If
* the file doesn't already exist it is created.
+ *
* By default files created are generally readable by everyone,
* but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
* will be made readable only to the current user, to the level that
* is supported on the target filesystem.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* Some file systems don't allow all file names, and may
* return an %G_IO_ERROR_INVALID_FILENAME error.
* If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be
* returned. Other errors are possible too, and depend on what kind of
* filesystem the file is on.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
@@ -21688,8 +22993,10 @@
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously opens @file for appending.
+ *
* For more details, see g_file_append_to() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_append_to_finish() to get the result of the operation.
*/
@@ -21703,6 +23010,7 @@
*
* Finishes an asynchronous file append operation started with
* g_file_append_to_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a valid #GFileOutputStream or %NULL on error.
@@ -21737,6 +23045,7 @@
* @name: the name of the attribute to lookup.
*
* Gets the file attribute with the name @name from @list.
+ *
* attribute isn't found.
*
* Returns: a #GFileAttributeInfo for the @name, or %NULL if an
@@ -21780,9 +23089,11 @@
* This will always return %TRUE if a wildcard character is in use (e.g. if
* matcher was created with "standard::*" and @ns is "standard", or if matcher was created
* using "*" and namespace is anything.)
+ *
+ * TODO: this is awkwardly worded.
+ *
* in the given @ns, %FALSE otherwise.
*
- * Todo: this is awkwardly worded.
* Returns: %TRUE if the matcher matches all of the entries
*/
@@ -21792,6 +23103,7 @@
* @matcher: a #GFileAttributeMatcher.
*
* Gets the next matched attribute from a #GFileAttributeMatcher.
+ *
* no more attribute exist.
*
* Returns: a string containing the next attribute or %NULL if
@@ -21832,11 +23144,13 @@
* counted structures, and are created with a reference count of 1. If
* the number of references falls to 0, the #GFileAttributeMatcher is
* automatically destroyed.
+ *
* The @attribute string should be formatted with specific keys separated
* from namespaces with a double colon. Several "namespace::key" strings may be
* concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
* The wildcard "*" may be used to match all keys and namespaces, or
* "namespace::*" will match all keys in a given namespace.
+ *
* Examples of strings to use:
* <table>
* <title>File Attribute Matcher strings and results</title>
@@ -21885,28 +23199,38 @@
*
* Copies the file @source to the location specified by @destination.
* Can not handle recursive copies of directories.
+ *
* If the flag #G_FILE_COPY_OVERWRITE is specified an already
* existing @destination file is overwritten.
+ *
* If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
* will be copied as symlinks, otherwise the target of the
+ * @source symlink will be copied.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If @progress_callback is not %NULL, then the operation can be monitored by
* setting this to a #GFileProgressCallback function. @progress_callback_data
* will be passed to this function. It is guaranteed that this callback will
* be called after all data has been transferred with the total number of bytes
* copied during the operation.
+ *
* If the @source file does not exist then the G_IO_ERROR_NOT_FOUND
* error is returned, independent on the status of the @destination.
+ *
* If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the
* error G_IO_ERROR_EXISTS is returned.
+ *
* If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY
* error is returned. If trying to overwrite a directory with a directory the
* G_IO_ERROR_WOULD_MERGE error is returned.
+ *
* If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is
* specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error
* is returned.
+ *
* If you are interested in copying the #GFile object itself (not the on-disk
* file), see g_file_dup().
*
@@ -21928,9 +23252,11 @@
*
* Copies the file @source to the location specified by @destination
* asynchronously. For details of the behaviour, see g_file_copy().
+ *
* If @progress_callback is not %NULL, then that function that will be called
* just like in g_file_copy(), however the callback will run in the main loop,
* not in the thread that is doing the I/O operation.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_copy_finish() to get the result of the operation.
*/
@@ -21945,6 +23271,7 @@
* @error: a #GError, %NULL to ignore.
*
* Copies the file attributes from @source to @destination.
+ *
* Normally only a subset of the file attributes are copied,
* those that are copies in a normal file copy operation
* (which for instance does not include e.g. owner). However
@@ -21978,13 +23305,16 @@
*
* Creates a new file and returns an output stream for writing to it.
* The file must not already exist.
+ *
* By default files created are generally readable by everyone,
* but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
* will be made readable only to the current user, to the level that
* is supported on the target filesystem.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If a file or directory with this name already exists the G_IO_ERROR_EXISTS
* error will be returned.
* Some file systems don't allow all file names, and may
@@ -21992,6 +23322,7 @@
* is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned.
* Other errors are possible too, and depend on what kind of
* filesystem the file is on.
+ *
* %NULL on error.
* Free the returned object with g_object_unref().
*
@@ -22010,8 +23341,10 @@
*
* Asynchronously creates a new file and returns an output stream for writing to it.
* The file must not already exist.
+ *
* For more details, see g_file_create() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_create_finish() to get the result of the operation.
*/
@@ -22025,6 +23358,7 @@
*
* Finishes an asynchronous file create operation started with
* g_file_create_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileOutputStream or %NULL on error.
@@ -22040,21 +23374,26 @@
*
* Creates a new file and returns a stream for reading and writing to it.
* The file must not already exist.
+ *
* By default files created are generally readable by everyone,
* but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
* will be made readable only to the current user, to the level that
* is supported on the target filesystem.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If a file or directory with this name already exists the %G_IO_ERROR_EXISTS
* error will be returned. Some file systems don't allow all file names,
* and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name
* is too long, %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors
* are possible too, and depend on what kind of filesystem the file is on.
+ *
* Note that in many non-local file cases read and write streams are not
* supported, so make sure you really need to do read and write streaming,
* rather than just opening for reading or writing.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error.
@@ -22073,8 +23412,10 @@
*
* Asynchronously creates a new file and returns a stream for reading and
* writing to it. The file must not already exist.
+ *
* For more details, see g_file_create_readwrite() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then
* call g_file_create_readwrite_finish() to get the result of the operation.
*
@@ -22090,6 +23431,7 @@
*
* Finishes an asynchronous file create operation started with
* g_file_create_readwrite_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileIOStream or %NULL on error.
@@ -22105,6 +23447,7 @@
*
* Deletes a file. If the @file is a directory, it will only be deleted if it
* is empty.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -22132,6 +23475,7 @@
* Duplicates a #GFile handle. This operation does not duplicate
* the actual file or directory represented by the #GFile; see
* g_file_copy() if attempting to copy a file.
+ *
* This call does no blocking i/o.
*
* Returns: (transfer full): a new #GFile that is a duplicate of the given #GFile.
@@ -22148,7 +23492,9 @@
*
* Starts an asynchronous eject on a mountable.
* When this operation has completed, @callback will be called with
+ * @user_user data, and the operation can be finalized with
* g_file_eject_mountable_finish().
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -22165,6 +23511,7 @@
*
* Finishes an asynchronous eject operation started by
* g_file_eject_mountable().
+ *
* otherwise.
*
* Returns: %TRUE if the @file was ejected successfully. %FALSE
@@ -22183,7 +23530,9 @@
*
* Starts an asynchronous eject on a mountable.
* When this operation has completed, @callback will be called with
+ * @user_user data, and the operation can be finalized with
* g_file_eject_mountable_with_operation_finish().
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -22200,6 +23549,7 @@
*
* Finishes an asynchronous eject operation started by
* g_file_eject_mountable_with_operation().
+ *
* otherwise.
*
* Returns: %TRUE if the @file was ejected successfully. %FALSE
@@ -22218,6 +23568,7 @@
* Gets the requested information about the files in a directory. The result
* is a #GFileEnumerator object that will give out #GFileInfo objects for
* all the files in the directory.
+ *
* The @attributes value is a string that specifies the file attributes that
* should be gathered. It is not an error if it's not possible to read a particular
* requested attribute from a file - it just won't be set. @attributes should
@@ -22225,12 +23576,15 @@
* means all attributes, and a wildcard like "standard::*" means all attributes in the standard
* namespace. An example attribute query be "standard::*,owner::user".
* The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
* If the file is not a directory, the G_FILE_ERROR_NOTDIR error will be returned.
* Other errors are possible too.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error.
@@ -22250,8 +23604,10 @@
* Asynchronously gets the requested information about the files in a directory. The result
* is a #GFileEnumerator object that will give out #GFileInfo objects for
* all the files in the directory.
+ *
* For more details, see g_file_enumerate_children() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_enumerate_children_finish() to get the result of the operation.
*/
@@ -22265,6 +23621,7 @@
*
* Finishes an async enumerate children operation.
* See g_file_enumerate_children_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred.
@@ -22279,6 +23636,7 @@
*
* Releases all resources used by this enumerator, making the
* enumerator return %G_IO_ERROR_CLOSED on all calls.
+ *
* This will be automatically called when the last reference
* is dropped, but you might want to call this function to make
* sure resources are released as early as possible.
@@ -22296,6 +23654,7 @@
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously closes the file enumerator.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
@@ -22310,6 +23669,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes closing a file enumerator, started from g_file_enumerator_close_async().
+ *
* If the file enumerator was already closed when g_file_enumerator_close_async()
* was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
* return %FALSE. If the file enumerator had pending operation when the close
@@ -22364,9 +23724,11 @@
* Will block until the information is available. The #GFileInfo
* returned from this function will contain attributes that match the
* attribute string that was passed when the #GFileEnumerator was created.
+ *
* On error, returns %NULL and sets @error to the error. If the
* enumerator is at the end, %NULL will be returned and @error will
* be unset.
+ *
* Free the returned object with g_object_unref() when no longer needed.
*
* Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
@@ -22385,13 +23747,16 @@
* Request information for a number of files from the enumerator asynchronously.
* When all i/o for the operation is finished the @callback will be called with
* the requested information.
+ *
* The callback can be called with less than @num_files files in case of error
* or at the end of the enumerator. In case of a partial error the callback will
* be called with any succeeding items and no error, and on the next request the
* error will be reported. If a request is cancelled the callback will be called
* with %G_IO_ERROR_CANCELLED.
+ *
* During an async request no other sync and async calls are allowed, and will
* result in %G_IO_ERROR_PENDING errors.
+ *
* Any outstanding i/o request with higher priority (lower numerical value) will
* be executed before an outstanding request with lower priority. Default
* priority is %G_PRIORITY_DEFAULT.
@@ -22405,6 +23770,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
+ *
* g_list_free() and unref the infos with g_object_unref() when you're
* done with them.
*
@@ -22430,7 +23796,9 @@
* #GFile<!-- -->s that differ can still refer to the same
* file on the filesystem due to various forms of filename
* aliasing.
+ *
* This call does no blocking i/o.
+ *
* %FALSE if either is not a #GFile.
*
* Returns: %TRUE if @file1 and @file2 are equal.
@@ -22444,12 +23812,15 @@
* @error: a #GError.
*
* Gets a #GMount for the #GFile.
+ *
* If the #GFileIface for @file does not have a mount (e.g. possibly a
* remote share), @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL
* will be returned.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GMount where the @file is located or %NULL on error.
@@ -22465,8 +23836,10 @@
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously gets the mount for the file.
+ *
* For more details, see g_file_find_enclosing_mount() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_find_enclosing_mount_finish() to get the result of the operation.
*/
@@ -22480,6 +23853,7 @@
*
* Finishes an asynchronous find mount request.
* See g_file_find_enclosing_mount_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): #GMount for given @file or %NULL on error.
@@ -22491,15 +23865,19 @@
* @file: input #GFile.
*
* Gets the base name (the last component of the path) for a given #GFile.
+ *
* If called for the top level of a system (such as the filesystem root
* or a uri like sftp://host/) it will return a single directory separator
* (and on Windows, possibly a drive letter).
+ *
* The base name is a byte string (*not* UTF-8). It has no defined encoding
* or rules other than it may not contain zero bytes. If you want to use
* filenames in a user interface you should use the display name that you
* can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
* attribute with g_file_query_info().
+ *
* This call does no blocking i/o.
+ *
* if given #GFile is invalid. The returned string should be
* freed with g_free() when no longer needed.
*
@@ -22513,10 +23891,13 @@
* @name: string containing the child's basename.
*
* Gets a child of @file with basename equal to @name.
+ *
* Note that the file with that specific name might not exist, but
* you can still have a #GFile that points to it. You can use this
* for instance to create that file.
+ *
* This call does no blocking i/o.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFile to a child specified by @name.
@@ -22534,7 +23915,9 @@
* set. This is very useful when constructing a GFile for a new file
* and the user entered the filename in the user interface, for instance
* when you select a directory and type a filename in the file selector.
+ *
* This call does no blocking i/o.
+ *
* %NULL if the display name couldn't be converted.
* Free the returned object with g_object_unref().
*
@@ -22549,7 +23932,9 @@
* Gets the parent directory for the @file.
* If the @file represents the root directory of the
* file system, then %NULL will be returned.
+ *
* This call does no blocking i/o.
+ *
* #GFile or %NULL if there is no parent.
* Free the returned object with g_object_unref().
*
@@ -22565,13 +23950,17 @@
* A parse name is a UTF-8 string that describes the
* file such that one can get the #GFile back using
* g_file_parse_name().
+ *
* This is generally used to show the #GFile as a nice
* full-pathname kind of string in a user interface,
* like in a location entry.
+ *
* For local files with names that can safely be converted
* to UTF8 the pathname is used, otherwise the IRI is used
* (a form of URI that allows UTF8 characters unescaped).
+ *
* This call does no blocking i/o.
+ *
* string should be freed with g_free() when no longer needed.
*
* Returns: a string containing the #GFile's parse name. The returned
@@ -22583,7 +23972,9 @@
* @file: input #GFile.
*
* Gets the local pathname for #GFile, if one exists.
+ *
* This call does no blocking i/o.
+ *
* no such path exists. The returned string should be
* freed with g_free() when no longer needed.
*
@@ -22597,7 +23988,9 @@
* @descendant: input #GFile.
*
* Gets the path for @descendant relative to @parent.
+ *
* This call does no blocking i/o.
+ *
* to @parent, or %NULL if @descendant doesn't have @parent as prefix.
* The returned string should be freed with g_free() when no longer needed.
*
@@ -22610,7 +24003,9 @@
* @file: input #GFile.
*
* Gets the URI for the @file.
+ *
* This call does no blocking i/o.
+ *
* The returned string should be freed with g_free() when no longer needed.
*
* Returns: a string containing the #GFile's URI.
@@ -22627,7 +24022,9 @@
* URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
* </programlisting>
* Common schemes include "file", "http", "ftp", etc.
+ *
* This call does no blocking i/o.
+ *
* #GFile. The returned string should be freed with g_free()
* when no longer needed.
*
@@ -22641,9 +24038,11 @@
* @parent: the parent to check for, or %NULL
*
* Checks if @file has a parent, and optionally, if it is @parent.
+ *
* If @parent is %NULL then this function returns %TRUE if @file has any
* parent at all. If @parent is non-%NULL then %TRUE is only returned
* if @file is a child of @parent.
+ *
* case that @parent is %NULL).
*
* Returns: %TRUE if @file is a child of @parent (or any parent in the
@@ -22660,10 +24059,12 @@
* if the names of inital elements of @file<!-- -->s pathname match @prefix.
* Only full pathname elements are matched, so a path like /foo is not
* considered a prefix of /foobar, only of /foo/bar.
+ *
* This call does no i/o, as it works purely on names. As such it can
* sometimes return %FALSE even if @file is inside a @prefix (from a
* filesystem point of view), because the prefix of @file is an alias
* of @prefix.
+ *
* %FALSE otherwise.
*
* Virtual: prefix_matches
@@ -22677,7 +24078,9 @@
* @uri_scheme: a string containing a URI scheme.
*
* Checks to see if a #GFile has a given URI scheme.
+ *
* This call does no blocking i/o.
+ *
* given URI scheme, %FALSE if URI scheme is %NULL,
* not supported, or #GFile is invalid.
*
@@ -22690,7 +24093,9 @@
* @file: #gconstpointer to a #GFile.
*
* Creates a hash value for a #GFile.
+ *
* This call does no blocking i/o.
+ *
* integer that can be used as hash value for the #GFile.
* This function is intended for easily hashing a #GFile to
* add to a #GHashTable or similar data structure.
@@ -22755,6 +24160,7 @@
* Gets the value of a attribute, formated as a string.
* This escapes things as needed to make the string valid
* utf8.
+ *
* When you're done with the string it must be freed with g_free().
*
* Returns: a UTF-8 string associated with the given @attribute.
@@ -22780,6 +24186,7 @@
*
* Gets the value of a byte string attribute. If the attribute does
* not contain a byte string, %NULL will be returned.
+ *
* %NULL otherwise.
*
* Returns: the contents of the @attribute value as a byte string, or
@@ -22795,6 +24202,7 @@
* @status: (out) (allow-none): return location for the attribute status, or %NULL
*
* Gets the attribute type, value and status for an attribute key.
+ *
* %FALSE otherwise.
*
* Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
@@ -22834,6 +24242,7 @@
*
* Gets the value of a #GObject attribute. If the attribute does
* not contain a #GObject, %NULL will be returned.
+ *
* %NULL otherwise.
*
* Returns: (transfer none): a #GObject associated with the given @attribute, or
@@ -22846,6 +24255,7 @@
* @attribute: a file attribute key
*
* Gets the attribute status for an attribute key.
+ *
* %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
*
* Returns: a #GFileAttributeStatus for the given @attribute, or
@@ -22859,6 +24269,7 @@
*
* Gets the value of a string attribute. If the attribute does
* not contain a string, %NULL will be returned.
+ *
* %NULL otherwise.
*
* Returns: the contents of the @attribute value as a UTF-8 string, or
@@ -22872,6 +24283,7 @@
*
* Gets the value of a stringv attribute. If the attribute does
* not contain a stringv, %NULL will be returned.
+ *
* %NULL otherwise. Do not free. These returned strings are UTF-8.
*
* Returns: (transfer none): the contents of the @attribute value as a stringv, or
@@ -22885,6 +24297,7 @@
* @attribute: a file attribute key.
*
* Gets the attribute type for an attribute key.
+ *
* %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
*
* Returns: a #GFileAttributeType for the given @attribute, or
@@ -23066,6 +24479,7 @@
* @attribute: a file attribute key.
*
* Checks if a file info structure has an attribute named @attribute.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if @Ginfo has an attribute named @attribute,
@@ -23079,6 +24493,7 @@
*
* Checks if a file info structure has an attribute in the
* specified @name_space.
+ *
* %FALSE otherwise.
*
* Returns: %TRUE if @Ginfo has an attribute in @name_space,
@@ -23092,6 +24507,7 @@
* @name_space: a file attribute key's namespace.
*
* Lists the file info structure's attributes.
+ *
* possible attribute types for the given @name_space, or
* %NULL on error.
*
@@ -23201,6 +24617,7 @@
* Sets the attribute status for an attribute key. This is only
* needed by external code that implement g_file_set_attributes_from_info()
* or similar functions.
+ *
* The attribute must exist in @info for this to work. Otherwise %FALSE
* is returned and @info is unchanged.
*
@@ -23414,8 +24831,10 @@
* When the operation is finished @callback will be called.
* You can then call g_file_input_stream_query_info_finish()
* to get the result of the operation.
+ *
* For the synchronous version of this function,
* see g_file_input_stream_query_info().
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be set
@@ -23460,11 +24879,13 @@
* While the stream is blocked, the stream will set the pending flag
* internally, and any other operations on the stream will fail with
* %G_IO_ERROR_PENDING.
+ *
* Can fail if the stream was already closed (with @error being set to
* %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
* set to %G_IO_ERROR_PENDING), or if querying info is not supported for
* the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
* all cases of failure, %NULL will be returned.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
@@ -23485,7 +24906,9 @@
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously queries the @stream for a #GFileInfo. When completed,
+ * @callback will be called with a #GAsyncResult which can be used to
* finish the operation with g_file_io_stream_query_info_finish().
+ *
* For the synchronous version of this function, see
* g_file_io_stream_query_info().
*
@@ -23512,13 +24935,16 @@
* @file: input #GFile.
*
* Checks to see if a file is native to the platform.
+ *
* A native file s one expressed in the platform-native filename format,
* e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
* as it might be on a locally mounted remote filesystem.
+ *
* On some systems non-native files may be available using
* the native filesystem via a userspace filesystem (FUSE), in
* these cases this call will return %FALSE, but g_file_get_path()
* will still return a native path.
+ *
* This call does no blocking i/o.
*
* Returns: %TRUE if file is native.
@@ -23538,9 +24964,11 @@
* zero-terminated, but this is not included in the resultant @length.
* The returned @content should be freed with g_free() when no longer
* needed.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* %FALSE if there were errors.
*
* Returns: %TRUE if the @file's contents were successfully loaded.
@@ -23555,12 +24983,15 @@
* @user_data: the data to pass to callback function
*
* Starts an asynchronous load of the @file's contents.
+ *
* For more details, see g_file_load_contents() which is
* the synchronous version of this call.
+ *
* When the load operation has completed, @callback will be called
* with @user data. To finish the operation, call
* g_file_load_contents_finish() with the #GAsyncResult returned by
* the @callback.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -23581,6 +25012,7 @@
* size of the @contents string. The @content should be freed with
* g_free() when no longer needed. If @etag_out is present, it will be
* set to the new entity tag for the @file.
+ *
* present, it will be set appropriately.
*
* Returns: %TRUE if the load was successful. If %FALSE and @error is
@@ -23599,8 +25031,10 @@
* used to stop reading from the file when appropriate, else this function
* will behave exactly as g_file_load_contents_async(). This operation
* can be finished by g_file_load_partial_contents_finish().
+ *
* Users of this function should be aware that @user_data is passed to
* both the @read_more_callback and the @callback.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -23621,6 +25055,7 @@
* zero-terminated, but this is not included in the resultant @length.
* The returned @content should be freed with g_free() when no longer
* needed.
+ *
* present, it will be set appropriately.
*
* Returns: %TRUE if the load was successful. If %FALSE and @error is
@@ -23637,10 +25072,13 @@
* the immediate parent directory of the path or URI given by the #GFile. To
* recursively create directories, see g_file_make_directory_with_parents().
* This function will fail if the parent directory does not exist, setting
+ * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support creating
* directories, this function will fail, setting @error to
* %G_IO_ERROR_NOT_SUPPORTED.
+ *
* For a local #GFile the newly created directory will have the default
* (current) ownership and permissions of the current process.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -23658,11 +25096,14 @@
* Creates a directory and any parent directories that may not exist similar to
* 'mkdir -p'. If the file system does not support creating directories, this
* function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED.
+ *
* For a local #GFile the newly created directories will have the default
* (current) ownership and permissions of the current process.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* otherwise.
*
* Returns: %TRUE if all directories have been successfully created, %FALSE
@@ -23678,6 +25119,8 @@
* @error: a #GError.
*
* Creates a symbolic link named @file which contains the string
+ * @symlink_value.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -23695,9 +25138,11 @@
*
* Obtains a file or directory monitor for the given file, depending
* on the type of the file.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
@@ -23724,9 +25169,11 @@
*
* Obtains a directory monitor for the given file.
* This may fail if directory monitoring is not supported.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* Free the returned object with g_object_unref().
*
* Virtual: monitor_dir
@@ -23744,6 +25191,7 @@
* Emits the #GFileMonitor::changed signal if a change
* has taken place. Should be called from file monitor
* implementations only.
+ *
* The signal will be emitted from an idle handler (in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* context</link>).
@@ -23759,9 +25207,11 @@
*
* Obtains a file monitor for the given file. If no file notification
* mechanism exists, then regular polling of the file is used.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
@@ -23798,8 +25248,11 @@
* @user_data: the data to pass to callback function
*
* Starts a @mount_operation, mounting the volume that contains the file @location.
+ *
* When this operation has completed, @callback will be called with
+ * @user_user data, and the operation can be finalized with
* g_file_mount_enclosing_volume_finish().
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -23813,6 +25266,7 @@
* @error: a #GError, or %NULL
*
* Finishes a mount operation started by g_file_mount_enclosing_volume().
+ *
* has occurred, this function will return %FALSE and set @error
* appropriately if present.
*
@@ -23832,9 +25286,11 @@
* Mounts a file of type G_FILE_TYPE_MOUNTABLE.
* Using @mount_operation, you can request callbacks when, for instance,
* passwords are needed during authentication.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_mount_mountable_finish() to get the result of the operation.
*/
@@ -23847,8 +25303,10 @@
* @error: a #GError, or %NULL
*
* Finishes a mount operation. See g_file_mount_mountable() for details.
+ *
* Finish an asynchronous mount operation that was started
* with g_file_mount_mountable().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFile or %NULL on error.
@@ -23869,25 +25327,34 @@
* If native move operations are supported then this is used, otherwise a copy + delete
* fallback is used. The native implementation may support moving directories (for instance
* on moves inside the same filesystem), but the fallback code does not.
+ *
* If the flag #G_FILE_COPY_OVERWRITE is specified an already
* existing @destination file is overwritten.
+ *
* If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
* will be copied as symlinks, otherwise the target of the
+ * @source symlink will be copied.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If @progress_callback is not %NULL, then the operation can be monitored by
* setting this to a #GFileProgressCallback function. @progress_callback_data
* will be passed to this function. It is guaranteed that this callback will
* be called after all data has been transferred with the total number of bytes
* copied during the operation.
+ *
* If the @source file does not exist then the G_IO_ERROR_NOT_FOUND
* error is returned, independent on the status of the @destination.
+ *
* If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the
* error G_IO_ERROR_EXISTS is returned.
+ *
* If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY
* error is returned. If trying to overwrite a directory with a directory the
* G_IO_ERROR_WOULD_MERGE error is returned.
+ *
* If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is
* specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error
* may be returned (if the native move operation isn't available).
@@ -23901,6 +25368,7 @@
* @arg: a command line string.
*
* Creates a #GFile with the given argument from the command line. The value of
+ * @arg can be either a URI, an absolute path or a relative path resolved
* relative to the current working directory.
* This operation never fails, but the returned object might not support any
* I/O operation if @arg points to a malformed path.
@@ -23942,15 +25410,18 @@
*
* Opens an existing file for reading and writing. The result is
* a #GFileIOStream that can be used to read and write the contents of the file.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
* If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned.
* Other errors are possible too, and depend on what kind of filesystem the file is on.
* Note that in many non-local file cases read and write streams are not supported,
* so make sure you really need to do read and write streaming, rather than
* just opening for reading or writing.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): #GFileIOStream or %NULL on error.
@@ -23967,8 +25438,10 @@
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously opens @file for reading and writing.
+ *
* For more details, see g_file_open_readwrite() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_open_readwrite_finish() to get the result of the operation.
*
@@ -23984,6 +25457,7 @@
*
* Finishes an asynchronous file read operation started with
* g_file_open_readwrite_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileIOStream or %NULL on error.
@@ -24016,11 +25490,13 @@
* While the stream is blocked, the stream will set the pending flag
* internally, and any other operations on the stream will fail with
* %G_IO_ERROR_PENDING.
+ *
* Can fail if the stream was already closed (with @error being set to
* %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
* set to %G_IO_ERROR_PENDING), or if querying info is not supported for
* the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
* all cases of failure, %NULL will be returned.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
@@ -24040,7 +25516,9 @@
* @user_data: the data to pass to callback function
*
* Asynchronously queries the @stream for a #GFileInfo. When completed,
+ * @callback will be called with a #GAsyncResult which can be used to
* finish the operation with g_file_output_stream_query_info_finish().
+ *
* For the synchronous version of this function, see
* g_file_output_stream_query_info().
*/
@@ -24079,9 +25557,11 @@
* @user_data: the data to pass to callback function
*
* Polls a file of type G_FILE_TYPE_MOUNTABLE.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_mount_mountable_finish() to get the result of the operation.
*
@@ -24096,8 +25576,10 @@
* @error: a #GError, or %NULL
*
* Finishes a poll operation. See g_file_poll_mountable() for details.
+ *
* Finish an asynchronous poll operation that was polled
* with g_file_poll_mountable().
+ *
* otherwise.
*
* Returns: %TRUE if the operation finished successfully. %FALSE
@@ -24113,9 +25595,11 @@
*
* Returns the #GAppInfo that is registered as the default
* application to handle the file specified by @file.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* When you are done with it, release it with g_object_unref()
*
* Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors.
@@ -24129,24 +25613,27 @@
*
* Utility function to check if a particular file exists. This is
* implemented using g_file_query_info() and as such does blocking I/O.
+ *
* Note that in many cases it is racy to first check for file existence
* and then execute something based on the outcome of that, because the
* file might have been created or removed in between the operations. The
* general approach to handling that is to not check, but just do the
* operation and handle the errors as they come.
+ *
* As an example of race-free checking, take the case of reading a file, and
+ * if it doesn't exist, creating it. There are two racy versions: read it, and
+ * on error create it; and: check if it exists, if not create it. These
* can both result in two processes creating the file (with perhaps a partially
* written file as the result). The correct approach is to always try to create
* the file with g_file_create() which will either atomically create the file
* or fail with a G_IO_ERROR_EXISTS error.
+ *
* However, in many cases an existence check is useful in a user
* interface, for instance to make a menu item sensitive/insensitive, so that
* you don't have to fool users that something is possible and then just show
* and error dialog. If you do this, you should make sure to also handle the
* errors that can happen due to races when you execute the operation.
*
- * If it doesn't exist, creating it. there are two racy versions: read it, and
- * On error create it; and: check if it exists, if not create it. These
* Returns: %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled).
*/
@@ -24159,8 +25646,10 @@
*
* Utility function to inspect the #GFileType of a file. This is
* implemented using g_file_query_info() and as such does blocking I/O.
+ *
* The primary use case of this method is to check if a file is a regular file,
* directory, or symlink.
+ *
* does not exist
*
* Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file
@@ -24179,20 +25668,24 @@
* about the filesystem the @file is on, rather than the file itself.
* For instance the amount of space available and the type of
* the filesystem.
+ *
* The @attributes value is a string that specifies the file attributes that
* should be gathered. It is not an error if it's not possible to read a particular
* requested attribute from a file - it just won't be set. @attributes should
* be a comma-separated list of attributes or attribute wildcards. The wildcard "*"
- * means all attributes, and a wildcard like "fs:*" means all attributes in the fs
- * namespace. The standard namespace for filesystem attributes is "fs".
+ * means all attributes, and a wildcard like "filesystem::*" means all attributes in the
+ * filesystem namespace. The standard namespace for filesystem attributes is "filesystem".
* Common attributes of interest are #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE
* (the total size of the filesystem in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of
* bytes available), and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
* Other errors are possible too, and depend on what kind of filesystem the file is on.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
@@ -24212,8 +25705,10 @@
* that the specified @file is on. The result is a #GFileInfo object
* that contains key-value attributes (such as type or size for the
* file).
+ *
* For more details, see g_file_query_filesystem_info() which is the
* synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can
* then call g_file_query_info_finish() to get the result of the
* operation.
@@ -24228,6 +25723,7 @@
*
* Finishes an asynchronous filesystem info query. See
* g_file_query_filesystem_info_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): #GFileInfo for given @file or %NULL on error.
@@ -24245,6 +25741,7 @@
* Gets the requested information about specified @file. The result
* is a #GFileInfo object that contains key-value attributes (such as
* the type or size of the file).
+ *
* The @attributes value is a string that specifies the file attributes that
* should be gathered. It is not an error if it's not possible to read a particular
* requested attribute from a file - it just won't be set. @attributes should
@@ -24252,17 +25749,21 @@
* means all attributes, and a wildcard like "standard::*" means all attributes in the standard
* namespace. An example attribute query be "standard::*,owner::user".
* The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* For symlinks, normally the information about the target of the
* symlink is returned, rather than information about the symlink itself.
* However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in @flags the
* information about the symlink itself will be returned. Also, for symlinks
* that point to non-existing files the information about the symlink itself
* will be returned.
+ *
* If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
* Other errors are possible too, and depend on what kind of filesystem the file is on.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error.
@@ -24282,8 +25783,10 @@
* Asynchronously gets the requested information about specified @file. The result
* is a #GFileInfo object that contains key-value attributes (such as type or size
* for the file).
+ *
* For more details, see g_file_query_info() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_query_info_finish() to get the result of the operation.
*/
@@ -24297,6 +25800,7 @@
*
* Finishes an asynchronous file info query.
* See g_file_query_info_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): #GFileInfo for given @file or %NULL on error.
@@ -24310,13 +25814,16 @@
* @error: a #GError, or %NULL
*
* Obtain the list of settable attributes for the file.
+ *
* Returns the type and full attribute name of all the attributes
* that can be set on this file. This doesn't mean setting it will always
* succeed though, you might get an access failure, or some specific
* file may not support a specific attribute.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* When you are done with it, release it with g_file_attribute_info_list_unref()
*
* Returns: a #GFileAttributeInfoList describing the settable attributes.
@@ -24332,9 +25839,11 @@
* Obtain the list of attribute namespaces where new attributes
* can be created by a user. An example of this is extended
* attributes (in the "xattr" namespace).
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* When you are done with it, release it with g_file_attribute_info_list_unref()
*
* Returns: a #GFileAttributeInfoList describing the writable namespaces.
@@ -24349,12 +25858,15 @@
*
* Opens a file for reading. The result is a #GFileInputStream that
* can be used to read the contents of the file.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
* If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned.
* Other errors are possible too, and depend on what kind of filesystem the file is on.
+ *
* Free the returned object with g_object_unref().
*
* Virtual: read_fn
@@ -24371,8 +25883,10 @@
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously opens @file for reading.
+ *
* For more details, see g_file_read() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_read_finish() to get the result of the operation.
*/
@@ -24386,6 +25900,7 @@
*
* Finishes an asynchronous file read operation started with
* g_file_read_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileInputStream or %NULL on error.
@@ -24404,18 +25919,22 @@
* Returns an output stream for overwriting the file, possibly
* creating a backup copy of the file first. If the file doesn't exist,
* it will be created.
+ *
* This will try to replace the file in the safest way possible so
* that any errors during the writing will not affect an already
* existing copy of the file. For instance, for local files it
* may write to a temporary file and then atomically rename over
* the destination when the stream is closed.
+ *
* By default files created are generally readable by everyone,
* but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
* will be made readable only to the current user, to the level that
* is supported on the target filesystem.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If you pass in a non-#NULL @etag value, then this value is
* compared to the current entity tag of the file, and if they differ
* an G_IO_ERROR_WRONG_ETAG error is returned. This generally means
@@ -24424,9 +25943,12 @@
* finished writing and closed the #GFileOutputStream. When you load
* a new file you can use g_file_input_stream_query_info() to get
* the etag of the file.
+ *
* If @make_backup is %TRUE, this function will attempt to make a backup
* of the current file before overwriting it. If this fails a G_IO_ERROR_CANT_CREATE_BACKUP
* error will be returned. If you want to replace anyway, try again with
+ * @make_backup set to %FALSE.
+ *
* If the file is a directory the G_IO_ERROR_IS_DIRECTORY error will be returned,
* and if the file is some other form of non-regular file then a
* G_IO_ERROR_NOT_REGULAR_FILE error will be returned.
@@ -24435,6 +25957,7 @@
* is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned.
* Other errors are possible too, and depend on what kind of
* filesystem the file is on.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileOutputStream or %NULL on error.
@@ -24454,8 +25977,10 @@
*
* Asynchronously overwrites the file, replacing the contents, possibly
* creating a backup copy of the file first.
+ *
* For more details, see g_file_replace() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_replace_finish() to get the result of the operation.
*/
@@ -24476,12 +26001,16 @@
* Replaces the contents of @file with @contents of @length bytes.
* If @etag is specified (not %NULL) any existing file must have that etag, or
* the error %G_IO_ERROR_WRONG_ETAG will be returned.
+ *
* If @make_backup is %TRUE, this function will attempt to make a backup of @file.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* The returned @new_etag can be used to verify that the file hasn't changed the
* next time it is saved over.
+ *
* has occurred, this function will return %FALSE and set @error
* appropriately if present.
*
@@ -24502,12 +26031,17 @@
* @user_data: the data to pass to callback function
*
* Starts an asynchronous replacement of @file with the given
+ * @contents of @length bytes. @etag will replace the document's
* current entity tag.
+ *
* When this operation has completed, @callback will be called with
+ * @user_user data, and the operation can be finalized with
* g_file_replace_contents_finish().
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* If @make_backup is %TRUE, this function will attempt to
* make a backup of @file.
*/
@@ -24536,6 +26070,7 @@
*
* Finishes an asynchronous file replace operation started with
* g_file_replace_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
@@ -24554,11 +26089,14 @@
* Returns an output stream for overwriting the file in readwrite mode,
* possibly creating a backup copy of the file first. If the file doesn't
* exist, it will be created.
+ *
* For details about the behaviour, see g_file_replace() which does the same
* thing but returns an output stream only.
+ *
* Note that in many non-local file cases read and write streams are not
* supported, so make sure you really need to do read and write streaming,
* rather than just opening for reading or writing.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileIOStream or %NULL on error.
@@ -24579,8 +26117,10 @@
*
* Asynchronously overwrites the file in read-write mode, replacing the
* contents, possibly creating a backup copy of the file first.
+ *
* For more details, see g_file_replace_readwrite() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then
* call g_file_replace_readwrite_finish() to get the result of the operation.
*
@@ -24596,6 +26136,7 @@
*
* Finishes an asynchronous file replace operation started with
* g_file_replace_readwrite_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFileIOStream, or %NULL on error.
@@ -24609,7 +26150,9 @@
* @relative_path: a given relative path string.
*
* Resolves a relative path for @file to an absolute path.
+ *
* This call does no blocking i/o.
+ *
* is %NULL or if @file is invalid.
* Free the returned object with g_object_unref().
*
@@ -24628,8 +26171,10 @@
* @error: a #GError, or %NULL
*
* Sets an attribute in the file with attribute name @attribute to @value.
+ *
* Some attributes can be unset by setting @attribute to
* %G_FILE_ATTRIBUTE_TYPE_INVALID and @value to %NULL.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -24650,9 +26195,11 @@
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
* If @attribute is of a different type, this operation will fail,
* returning %FALSE.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* in the @file, %FALSE otherwise.
*
* Returns: %TRUE if the @attribute was successfully set to @value
@@ -24670,9 +26217,11 @@
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
* If @attribute is of a different type, this operation will fail.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* in the @file, %FALSE otherwise.
*
* Returns: %TRUE if the @attribute was successfully set to @value
@@ -24690,6 +26239,7 @@
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
* If @attribute is of a different type, this operation will fail.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -24709,6 +26259,7 @@
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
* If @attribute is of a different type, this operation will fail.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -24728,9 +26279,11 @@
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
* If @attribute is of a different type, this operation will fail.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* in the @file, %FALSE otherwise.
*
* Returns: %TRUE if the @attribute was successfully set to @value
@@ -24748,9 +26301,11 @@
*
* Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
* If @attribute is of a different type, this operation will fail.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* in the @file, %FALSE otherwise.
*
* Returns: %TRUE if the @attribute was successfully set to @value
@@ -24768,8 +26323,10 @@
* @user_data: (closure): a #gpointer.
*
* Asynchronously sets the attributes of @file with @info.
+ *
* For more details, see g_file_set_attributes_from_info() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_set_attributes_finish() to get the result of the operation.
*/
@@ -24798,11 +26355,13 @@
*
* Tries to set all attributes in the #GFileInfo on the target values,
* not stopping on the first error.
+ *
* If there is any error during this operation then @error will be set to
* the first error. Error on particular fields are flagged by setting
* the "status" field in the attribute value to
* %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect
* further errors.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -24819,15 +26378,20 @@
* @error: a #GError, or %NULL
*
* Renames @file to the specified display name.
+ *
* The display name is converted from UTF8 to the correct encoding for the target
* filesystem if possible and the @file is renamed to this.
+ *
* If you want to implement a rename operation in the user interface the edit name
* (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename
* widget, and then the result after editing should be passed to g_file_set_display_name().
+ *
* On success the resulting converted filename is returned.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* if there was an error.
* Free the returned object with g_object_unref().
*
@@ -24845,8 +26409,10 @@
* @user_data: (closure): the data to pass to callback function
*
* Asynchronously sets the display name for a given #GFile.
+ *
* For more details, see g_file_set_display_name() which is
* the synchronous version of this call.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_set_display_name_finish() to get the result of the operation.
*/
@@ -24860,6 +26426,7 @@
*
* Finishes setting a display name started with
* g_file_set_display_name_async().
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFile or %NULL on error.
@@ -24878,9 +26445,11 @@
* Starts a file of type G_FILE_TYPE_MOUNTABLE.
* Using @start_operation, you can request callbacks when, for instance,
* passwords are needed during authentication.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_mount_mountable_finish() to get the result of the operation.
*
@@ -24895,8 +26464,10 @@
* @error: a #GError, or %NULL
*
* Finishes a start operation. See g_file_start_mountable() for details.
+ *
* Finish an asynchronous start operation that was started
* with g_file_start_mountable().
+ *
* otherwise.
*
* Returns: %TRUE if the operation finished successfully. %FALSE
@@ -24914,9 +26485,11 @@
* @user_data: the data to pass to callback function
*
* Stops a file of type G_FILE_TYPE_MOUNTABLE.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_stop_mountable_finish() to get the result of the operation.
*
@@ -24931,8 +26504,10 @@
* @error: a #GError, or %NULL
*
* Finishes an stop operation, see g_file_stop_mountable() for details.
+ *
* Finish an asynchronous stop operation that was started
* with g_file_stop_mountable().
+ *
* otherwise.
*
* Returns: %TRUE if the operation finished successfully. %FALSE
@@ -24965,6 +26540,8 @@
* deleting it, but the user can recover it before emptying the trashcan.
* Not all file systems support trashing, so this call can return the
* %G_IO_ERROR_NOT_SUPPORTED error.
+ *
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -24982,9 +26559,11 @@
* @user_data: (closure): the data to pass to callback function
*
* Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_unmount_mountable_finish() to get the result of the operation.
*
@@ -24999,8 +26578,10 @@
* @error: a #GError, or %NULL
*
* Finishes an unmount operation, see g_file_unmount_mountable() for details.
+ *
* Finish an asynchronous unmount operation that was started
* with g_file_unmount_mountable().
+ *
* otherwise.
*
* Returns: %TRUE if the operation finished successfully. %FALSE
@@ -25018,9 +26599,11 @@
* @user_data: (closure): the data to pass to callback function
*
* Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* When the operation is finished, @callback will be called. You can then call
* g_file_unmount_mountable_finish() to get the result of the operation.
*
@@ -25035,8 +26618,10 @@
* @error: a #GError, or %NULL
*
* Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details.
+ *
* Finish an asynchronous unmount operation that was started
* with g_file_unmount_mountable_with_operation().
+ *
* otherwise.
*
* Returns: %TRUE if the operation finished successfully. %FALSE
@@ -25050,6 +26635,7 @@
* @initial_text: text to be completed.
*
* Obtains a completion for @initial_text from @completer.
+ *
* This string is not owned by GIO, so remember to g_free() it
* when finished.
*
@@ -25063,6 +26649,7 @@
* @initial_text: text to be completed.
*
* Gets an array of completion strings for a given initial text.
+ *
* This array must be freed by g_strfreev() when finished.
*
* Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text.
@@ -25182,6 +26769,7 @@
* @icon: #gconstpointer to an icon object.
*
* Gets a hash for an icon.
+ *
* use in a #GHashTable or similar data structure.
*
* Virtual: hash
@@ -25195,9 +26783,12 @@
* @error: Return location for error.
*
* Generate a #GIcon instance from @str. This function can fail if
+ * @str is not valid - see g_icon_to_string() for discussion.
+ *
* If your application or library provides one or more #GIcon
* implementations you need to ensure that each #GType is registered
* with the type system prior to calling g_icon_new_for_string().
+ *
* interface or %NULL if @error is set.
*
* Returns: (transfer full): An object implementing the #GIcon
@@ -25213,8 +26804,10 @@
* serialization such as when passing @icon to a different process or
* saving it to persistent storage. Use g_icon_new_for_string() to
* get @icon back from the returned string.
+ *
* The encoding of the returned string is proprietary to #GIcon except
* in the following two cases
+ *
* <itemizedlist>
* <listitem><para>
* If @icon is a #GFileIcon, the returned string is a native path
@@ -25228,6 +26821,7 @@
* simply the name (such as <literal>network-server</literal>).
* </para></listitem>
* </itemizedlist>
+ *
* be serialized. Use g_free() to free.
*
* Virtual: to_tokens
@@ -25392,6 +26986,7 @@
*
* Creates a #GInetAddress for the "any" address (unassigned/"don't
* care") for @family.
+ *
* for @family.
*
* Returns: a new #GInetAddress corresponding to the "any" address
@@ -25405,6 +27000,7 @@
* @family: the address family of @bytes
*
* Creates a new #GInetAddress from the given @family and @bytes.
+ * @bytes should be 4 bytes for %G_INET_ADDRESS_IPV4 and 16 bytes for
* %G_INET_ADDRESS_IPV6.
*
* Returns: a new #GInetAddress corresponding to @family and @bytes.
@@ -25418,6 +27014,8 @@
*
* Parses @string as an IP address and creates a new #GInetAddress.
*
+ * @string could not be parsed.
+ *
* Returns: a new #GInetAddress corresponding to @string, or %NULL if
* Since: 2.22
*/
@@ -25428,6 +27026,7 @@
* @family: the address family
*
* Creates a #GInetAddress for the loopback address for @family.
+ *
* for @family.
*
* Returns: a new #GInetAddress corresponding to the loopback address
@@ -25440,6 +27039,7 @@
* @address: a #GInetAddress
*
* Gets the raw binary address data from @address.
+ *
* which should not be modified, stored, or freed. The size of this
* array can be gotten with g_inet_address_get_native_size().
*
@@ -25453,6 +27053,7 @@
* @address: a #GInetAddress
*
* Converts @address to string form.
+ *
* freed after use.
*
* Returns: a representation of @address as a string, which should be
@@ -25465,6 +27066,7 @@
* @address: a #GInetSocketAddress
*
* Gets @address's #GInetAddress.
+ *
* g_object_ref()'d if it will be stored
*
* Returns: (transfer none): the #GInetAddress for @address, which must be
@@ -25503,20 +27105,24 @@
*
* Initializes the object implementing the interface. This must be
* done before any real use of the object after initial construction.
+ *
* Implementations may also support cancellation. If @cancellable is not %NULL,
* then initialization can be cancelled by triggering the cancellable object
* from another thread. If the operation was cancelled, the error
* %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
* the object doesn't support cancellable initialization the error
* %G_IO_ERROR_NOT_SUPPORTED will be returned.
+ *
* If this function is not called, or returns with an error then all
* operations on the object should fail, generally returning the
* error %G_IO_ERROR_NOT_INITIALIZED.
+ *
* Implementations of this method must be idempotent, i.e. multiple calls
* to this function with the same argument should return the same results.
* Only the first call initializes the object, further calls return the result
* of the first call. This is so that its safe to implement the singleton
* pattern in the GObject constructor function.
+ *
* return %FALSE and set @error appropriately if present.
*
* Returns: %TRUE if successful. If an error has occurred, this function will
@@ -25590,18 +27196,23 @@
* @error: location to store the error occuring, or %NULL to ignore
*
* Closes the stream, releasing resources related to it.
+ *
* Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
* Closing a stream multiple times will not return an error.
+ *
* Streams will be automatically closed when the last reference
* is dropped, but you might want to call this function to make sure
* resources are released as early as possible.
+ *
* Some streams might keep the backing store of the stream (e.g. a file descriptor)
* open after the stream is closed. See the documentation for the individual
* stream for details.
+ *
* On failure the first error that happened will be reported, but the close
* operation will finish as much as possible. A stream that failed to
* close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
* is important to check and report the error to the user.
+ *
* If @cancellable is not NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -25624,7 +27235,9 @@
* When the operation is finished @callback will be called.
* You can then call g_input_stream_close_finish() to get the result of the
* operation.
+ *
* For behaviour details see g_input_stream_close().
+ *
* The asyncronous methods have a default fallback that uses threads to implement
* asynchronicity, so they are optional for inheriting classes. However, if you
* override one you must override all.
@@ -25672,17 +27285,22 @@
* @error: location to store the error occuring, or %NULL to ignore
*
* Tries to read @count bytes from the stream into the buffer starting at
+ * @buffer. Will block during this read.
+ *
* If count is zero returns zero and does nothing. A value of @count
* larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+ *
* On success, the number of bytes read into the buffer is returned.
* It is not an error if this is not the same as the requested size, as it
* can happen e.g. near the end of a file. Zero is returned on end of file
* (or if @count is zero), but never otherwise.
+ *
* If @cancellable is not NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an
* operation was partially finished when the operation was cancelled the
* partial result will be returned, without an error.
+ *
* On error -1 is returned and @error is set accordingly.
*
* Returns: Number of bytes read, or -1 on error
@@ -25699,11 +27317,15 @@
* @error: location to store the error occuring, or %NULL to ignore
*
* Tries to read @count bytes from the stream into the buffer starting at
+ * @buffer. Will block during this read.
+ *
* This function is similar to g_input_stream_read(), except it tries to
* read as many bytes as requested, only stopping on an error or end of stream.
+ *
* On a successful read of @count bytes, or if we reached the end of the
* stream, %TRUE is returned, and @bytes_read is set to the number of bytes
* read into @buffer.
+ *
* If there is an error during the operation %FALSE is returned and @error
* is set to indicate the error status, @bytes_read is updated to contain
* the number of bytes read into @buffer before the error occurred.
@@ -25726,17 +27348,22 @@
* starting at @buffer. When the operation is finished @callback will be called.
* You can then call g_input_stream_read_finish() to get the result of the
* operation.
+ *
* During an async request no other sync and async calls are allowed on @stream, and will
* result in %G_IO_ERROR_PENDING errors.
+ *
* A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+ *
* On success, the number of bytes read into the buffer will be passed to the
* callback. It is not an error if this is not the same as the requested size, as it
* can happen e.g. near the end of a file, but generally we try to read
* as many bytes as requested. Zero is returned on end of file
* (or if @count is zero), but never otherwise.
+ *
* Any outstanding i/o request with higher priority (lower numerical value) will
* be executed before an outstanding request with lower priority. Default
* priority is %G_PRIORITY_DEFAULT.
+ *
* The asyncronous methods have a default fallback that uses threads to implement
* asynchronicity, so they are optional for inheriting classes. However, if you
* override one you must override all.
@@ -25762,6 +27389,7 @@
*
* Sets @stream to have actions pending. If the pending flag is
* already set or @stream is closed, it will return %FALSE and set
+ * @error.
*
* Returns: %TRUE if pending was previously unset and is now set.
*/
@@ -25775,11 +27403,14 @@
* @error: location to store the error occuring, or %NULL to ignore
*
* Tries to skip @count bytes from the stream. Will block during the operation.
+ *
* This is identical to g_input_stream_read(), from a behaviour standpoint,
* but the bytes that are skipped are not returned to the user. Some
* streams have an implementation that is more efficient than reading the data.
+ *
* This function is optional for inherited classes, as the default implementation
* emulates it using read.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
@@ -25803,17 +27434,22 @@
* When the operation is finished @callback will be called.
* You can then call g_input_stream_skip_finish() to get the result
* of the operation.
+ *
* During an async request no other sync and async calls are allowed,
* and will result in %G_IO_ERROR_PENDING errors.
+ *
* A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+ *
* On success, the number of bytes skipped will be passed to the callback.
* It is not an error if this is not the same as the requested size, as it
* can happen e.g. near the end of a file, but generally we try to skip
* as many bytes as requested. Zero is returned on end of file
* (or if @count is zero), but never otherwise.
+ *
* Any outstanding i/o request with higher priority (lower numerical value)
* will be executed before an outstanding request with lower priority.
* Default priority is %G_PRIORITY_DEFAULT.
+ *
* The asynchronous methods have a default fallback that uses threads to
* implement asynchronicity, so they are optional for inheriting classes.
* However, if you override one, you must override all.
@@ -25869,6 +27505,7 @@
* @extension: a #GIOExtension
*
* Gets the name under which @extension was registered.
+ *
* Note that the same type may be registered as extension
* for multiple extension points, under different names.
*
@@ -25902,6 +27539,7 @@
* @name: the name of the extension to get
*
* Finds a #GIOExtension for an extension point by name.
+ *
* given name, or %NULL if there is no extension with that name
*
* Returns: (transfer none): the #GIOExtension for @extension_point that has the
@@ -25914,6 +27552,7 @@
*
* Gets a list of all extensions that implement this extension point.
* The list is sorted by priority, beginning with the highest priority.
+ *
* #GIOExtension<!-- -->s. The list is owned by GIO and should not be
* modified.
*
@@ -25926,6 +27565,7 @@
* @extension_point: a #GIOExtensionPoint
*
* Gets the required type for @extension_point.
+ *
* or #G_TYPE_INVALID if the extension point has no required type
*
* Returns: the #GType that all implementations must have,
@@ -25940,6 +27580,8 @@
* @priority: the priority for the extension
*
* Registers @type as extension for the extension point with name
+ * @extension_point_name.
+ *
* If @type has already been registered as an extension for this
* extension point, the existing #GIOExtension object is returned.
*
@@ -25952,6 +27594,7 @@
* @name: the name of the extension point
*
* Looks up an existing extension point.
+ *
* registered extension point with the given name
*
* Returns: the #GIOExtensionPoint, or %NULL if there is no
@@ -25963,6 +27606,7 @@
* @name: The name of the extension point
*
* Registers an extension point.
+ *
* and should not be freed
*
* Returns: the new #GIOExtensionPoint. This object is owned by GIO
@@ -26006,6 +27650,7 @@
*
* Creates a new GIOModule that will load the specific
* shared library when in use.
+ *
* or %NULL on error.
*
* Returns: a #GIOModule from given @filename,
@@ -26016,22 +27661,28 @@
* g_io_module_query:
*
* Optional API for GIO modules to implement.
+ *
* Should return a list of all the extension points that may be
* implemented in this module.
+ *
* This method will not be called in normal use, however it may be
* called when probing existing modules and recording which extension
* points that this modle is used for. This means we won't have to
* load and initialze this module unless its needed.
+ *
* If this function is not implemented by the module the module will
* always be loaded, initialized and then unloaded on application startup
* so that it can register its extension points during init.
+ *
* Note that a module need not actually implement all the extension points
* that g_io_module_query returns, since the exact list of extension may
* depend on runtime issues. However all extension points actually implemented
* must be returned by g_io_module_query() (if defined).
+ *
* When installing a module that implements g_io_module_query you must
* run gio-querymodules in order to build the cache files required for
* lazy loading.
+ *
* extension points of the module. The array must be suitable for
* freeing with g_strfreev().
*
@@ -26055,9 +27706,11 @@
* @dirname: pathname for a directory containing modules to load.
*
* Loads all the modules in the specified directory.
+ *
* If don't require all modules to be initialized (and thus registering
* all gtypes) then you can use g_io_modules_scan_all_in_directory()
* which allows delayed/lazy loading of modules.
+ *
* from the directory,
* All the modules are loaded into memory, if you want to
* unload them (enabling on-demand loading) you must call
@@ -26074,11 +27727,13 @@
*
* Scans all the modules in the specified directory, ensuring that
* any extension point implemented by a module is registered.
+ *
* This may not actually load and initialize all the types in each
* module, some modules may be lazily loaded and initialized when
* an extension point it implementes is used with e.g.
* g_io_extension_point_get_extensions() or
* g_io_extension_point_get_extension_by_name().
+ *
* If you need to guarantee that all types are loaded in all the modules,
* use g_io_modules_load_all_in_directory().
*
@@ -26090,6 +27745,7 @@
* g_io_scheduler_cancel_all_jobs:
*
* Cancels all cancellable I/O jobs.
+ *
* A job is cancellable if a #GCancellable was passed into
* g_io_scheduler_push_job().
*/
@@ -26121,8 +27777,10 @@
* the thread that the job was started from. The callback will be run
* when the main loop is available, but at that time the I/O job might
* have finished. The return value from the callback is ignored.
+ *
* Note that if you are passing the @user_data from g_io_scheduler_push_job()
* on to this function you have to ensure that it is not freed before
+ * @func is called, either by passing %NULL as @notify to
* g_io_scheduler_push_job() or by using refcounting for @user_data.
*/
@@ -26136,7 +27794,10 @@
* @cancellable: optional #GCancellable object, %NULL to ignore.
*
* Schedules the I/O job to run.
+ *
+ * @notify will be called on @user_data after @job_func has returned,
* regardless whether the job was cancelled or has run to completion.
+ *
* If @cancellable is not %NULL, it can be used to cancel the I/O job
* by calling g_cancellable_cancel() or by calling
* g_io_scheduler_cancel_all_jobs().
@@ -26162,27 +27823,34 @@
* Closes the stream, releasing resources related to it. This will also
* closes the individual input and output streams, if they are not already
* closed.
+ *
* Once the stream is closed, all other operations will return
* %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
* return an error.
+ *
* Closing a stream will automatically flush any outstanding buffers
* in the stream.
+ *
* Streams will be automatically closed when the last reference
* is dropped, but you might want to call this function to make sure
* resources are released as early as possible.
+ *
* Some streams might keep the backing store of the stream (e.g. a file
* descriptor) open after the stream is closed. See the documentation for
* the individual stream for details.
+ *
* On failure the first error that happened will be reported, but the
* close operation will finish as much as possible. A stream that failed
* to close will still return %G_IO_ERROR_CLOSED for all operations.
* Still, it is important to check and report the error to the user,
* otherwise there might be a loss of data as all data might not be written.
+ *
* If @cancellable is not NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
* Cancelling a close will still leave the stream closed, but some streams
* can use a faster close that doesn't block to e.g. check errors.
+ *
* The default implementation of this method just calls close on the
* individual input/output streams.
*
@@ -26203,7 +27871,9 @@
* related to it. When the operation is finished @callback will be
* called. You can then call g_io_stream_close_finish() to get
* the result of the operation.
+ *
* For behaviour details see g_io_stream_close().
+ *
* The asynchronous methods have a default fallback that uses threads
* to implement asynchronicity, so they are optional for inheriting
* classes. However, if you override one you must override all.
@@ -26231,6 +27901,7 @@
*
* Gets the input stream for this object. This is used
* for reading.
+ *
* Do not free.
*
* Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
@@ -26244,6 +27915,7 @@
*
* Gets the output stream for this object. This is used for
* writing.
+ *
* Do not free.
*
* Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
@@ -26280,6 +27952,7 @@
*
* Sets @stream to have actions pending. If the pending flag is
* already set or @stream is closed, it will return %FALSE and set
+ * @error.
*
* Returns: %TRUE if pending was previously unset and is now set.
* Since: 2.22
@@ -26297,6 +27970,9 @@
* @user_data: (closure): user data passed to @callback.
*
* Asyncronously splice the output stream of @stream1 to the input stream of
+ * @stream2, and splice the output stream of @stream2 to the input stream of
+ * @stream1.
+ *
* When the operation is finished @callback will be called.
* You can then call g_io_stream_splice_finish() to get the
* result of the operation.
@@ -26321,44 +27997,53 @@
* g_keyfile_settings_backend_new:
* @filename: the filename of the keyfile
* @root_path: the path under which all settings keys appear
- * @root_group: (allow-none): the group name corresponding to
+ * @root_group: (allow-none): the group name corresponding to @root_path, or %NULL
* @returns: (transfer full): a keyfile-backed #GSettingsBackend
*
* Creates a keyfile-backed #GSettingsBackend.
+ *
* The filename of the keyfile to use is given by @filename.
+ *
* All settings read to or written from the backend must fall under the
* path given in @root_path (which must start and end with a slash and
* not contain two consecutive slashes). @root_path may be "/".
+ *
* If @root_group is non-%NULL then it specifies the name of the keyfile
* group used for keys that are written directly below @root_path. For
* example, if @root_path is "/apps/example/" and @root_group is
* "toplevel", then settings the key "/apps/example/enabled" to a value
* of %TRUE will cause the following to appear in the keyfile:
+ *
* |[
* [toplevel]
* enabled=true
* ]|
+ *
* If @root_group is %NULL then it is not permitted to store keys
* directly below the @root_path.
+ *
+ * For keys not stored directly below @root_path (ie: in a sub-path),
* the name of the subpath (with the final slash stripped) is used as
* the name of the keyfile group. To continue the example, if
* "/apps/example/profiles/default/font-size" were set to
* 12 then the following would appear in the keyfile:
+ *
* |[
* [profiles/default]
* font-size=12
* ]|
+ *
* The backend will refuse writes (and return writability as being
* %FALSE) for keys outside of @root_path and, in the event that
+ * @root_group is %NULL, also for keys directly under @root_path.
* Writes will also be refused if the backend detects that it has the
+ * inability to rewrite the keyfile (ie: the containing directory is not
* writable).
+ *
* There is no checking done for your key namespace clashing with the
* syntax of the key file format. For example, if you have '[' or ']'
* characters in your path names or '=' in your key names you may be in
* trouble.
- *
- * For keys not stored directly below @root_path (ie: in a sub-path),
- * Inability to rewrite the keyfile (ie: the containing directory is not
*/
@@ -26462,8 +28147,10 @@
* Checks if any events are pending for the default #GMainContext
* (i.e. ready to be processed).
*
- * Returns: %TRUE if any events are pending.
+ *
* Deprected: 2.2: Use g_main_context_pending() instead.
+ *
+ * Returns: %TRUE if any events are pending.
*/
@@ -26536,6 +28223,7 @@
* @ostream: a #GMemoryOutputStream
*
* Gets any loaded data from the @ostream.
+ *
* Note that the returned pointer may become invalid on the next
* write or truncate operation on the stream.
*
@@ -26565,8 +28253,10 @@
* growable (no realloc was passed to g_memory_output_stream_new()) then
* this is the maximum size of the stream and further writes
* will return %G_IO_ERROR_NO_SPACE.
+ *
* Note that for growable streams the returned size may become invalid on
* the next write or truncate operation on the stream.
+ *
* If you want the number of bytes currently written to the stream, use
* g_memory_output_stream_get_data_size().
*
@@ -26582,15 +28272,19 @@
* @destroy_function: a function to be called on @data when the stream is finalized, or %NULL
*
* Creates a new #GMemoryOutputStream.
+ *
* If @data is non-%NULL, the stream will use that for its internal storage.
* If @realloc_fn is non-%NULL, it will be used for resizing the internal
* storage when necessary. To construct a fixed-size output stream,
* pass %NULL as @realloc_fn.
+ *
* |[
* /* a stream that can grow */
* stream = g_memory_output_stream_new (NULL, 0, realloc, free);
+ *
* /* another stream that can grow */
* stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
+ *
* /* a fixed-size stream */
* data = malloc (200);
* stream3 = g_memory_output_stream_new (data, 200, NULL, free);
@@ -26609,6 +28303,8 @@
* freed using the free function set in @ostream's
* #GMemoryOutputStream:destroy-function property.
*
+ * @ostream must be closed before calling this function.
+ *
* Returns: (transfer full): the stream's data
* Since: 2.26
*/
@@ -26618,6 +28314,7 @@
* g_memory_settings_backend_new:
*
* Creates a memory-backed #GSettingsBackend.
+ *
* This backend allows changes to settings, but does not write them
* to any backing storage, so the next time you run your application,
* the memory backend will start out with the default values again.
@@ -26670,6 +28367,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes ejecting a mount. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
* Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
* Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
@@ -26700,6 +28398,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes ejecting a mount. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
* Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
* Since: 2.22
@@ -26711,7 +28410,9 @@
* @mount: a #GMount.
*
* Gets the default location of @mount. The default location of the given
+ * @mount is a path that reflects the main entry point for the user (e.g.
* the home directory, or the root of the volume).
+ *
* The returned object should be unreffed with
* g_object_unref() when no longer needed.
*
@@ -26724,8 +28425,10 @@
* @mount: a #GMount.
*
* Gets the drive for the @mount.
+ *
* This is a convenience method for getting the #GVolume and then
* using that object to get the #GDrive.
+ *
* The returned object should be unreffed with
* g_object_unref() when no longer needed.
*
@@ -26738,6 +28441,7 @@
* @mount: a #GMount.
*
* Gets the icon for @mount.
+ *
* The returned object should be unreffed with
* g_object_unref() when no longer needed.
*
@@ -26750,6 +28454,7 @@
* @mount: a #GMount.
*
* Gets the name of @mount.
+ *
* The returned string should be freed with g_free()
* when no longer needed.
*
@@ -26762,6 +28467,7 @@
* @mount: a #GMount.
*
* Gets the root directory on @mount.
+ *
* The returned object should be unreffed with
* g_object_unref() when no longer needed.
*
@@ -26777,6 +28483,7 @@
* the file system UUID for the mount in question and should be
* considered an opaque string. Returns %NULL if there is no UUID
* available.
+ *
* The returned string should be freed with g_free()
* when no longer needed.
*
@@ -26789,6 +28496,7 @@
* @mount: a #GMount.
*
* Gets the volume for the @mount.
+ *
* The returned object should be unreffed with
* g_object_unref() when no longer needed.
*
@@ -26809,9 +28517,11 @@
* prefixed with "x-content/"), e.g. x-content/image-dcf for camera
* memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec";>shared-mime-info</ulink>
* specification for more on x-content types.
+ *
* This is an asynchronous operation (see
* g_mount_guess_content_type_sync() for the synchronous version), and
* is finished by calling g_mount_guess_content_type_finish() with the
+ * @mount and #GAsyncResult data returned in the @callback.
*
* Since: 2.18
*/
@@ -26828,6 +28538,7 @@
* %FALSE will be returned. In particular, you may get an
* %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
* guessing.
+ *
* Caller should free this array with g_strfreev() when done with it.
*
* Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
@@ -26847,8 +28558,10 @@
* prefixed with "x-content/"), e.g. x-content/image-dcf for camera
* memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec";>shared-mime-info</ulink>
* specification for more on x-content types.
+ *
* This is an synchronous operation and as such may block doing IO;
* see g_mount_guess_content_type() for the asynchronous version.
+ *
* Caller should free this array with g_strfreev() when done with it.
*
* Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
@@ -26862,9 +28575,11 @@
*
* Determines if @mount is shadowed. Applications or libraries should
* avoid displaying @mount in the user interface if it is shadowed.
+ *
* A mount is said to be shadowed if there exists one or more user
* visible objects (currently #GMount objects) with a root that is
* inside the root of @mount.
+ *
* One application of shadow mounts is when exposing a single file
* system that is used to address several logical volumes. In this
* situation, a #GVolumeMonitor implementation would create two
@@ -26877,6 +28592,7 @@
* #GVolumeMonitor implementation would create two #GMount objects
* (each with their root matching the corresponding volume activation
* root) that would shadow the original mount.
+ *
* The proxy monitor in GVfs 2.26 and later, automatically creates and
* manage shadow mounts (and shadows the underlying mount) if the
* activation root on a #GVolume is set.
@@ -26902,6 +28618,7 @@
* @op: a #GMountOperation.
*
* Gets a choice from the mount operation.
+ *
* the choice's list, or %0.
*
* Returns: an integer containing an index of the user's choice from
@@ -27032,6 +28749,7 @@
* Remounts a mount. This is an asynchronous operation, and is
* finished by calling g_mount_remount_finish() with the @mount
* and #GAsyncResults data returned in the @callback.
+ *
* Remounting is useful when some setting affecting the operation
* of the volume has been changed, as these may need a remount to
* take affect. While this is semantically equivalent with unmounting
@@ -27047,6 +28765,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes remounting a mount. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
* Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
*/
@@ -27058,6 +28777,7 @@
*
* Increments the shadow count on @mount. Usually used by
* #GVolumeMonitor implementations when creating a shadow mount for
+ * @mount, see g_mount_is_shadowed() for more information. The caller
* will need to emit the #GMount::changed signal on @mount manually.
*
* Since: 2.20
@@ -27087,6 +28807,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes unmounting a mount. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
* Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
* Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
@@ -27117,6 +28838,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes unmounting a mount. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
* Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
* Since: 2.22
@@ -27129,6 +28851,7 @@
*
* Decrements the shadow count on @mount. Usually used by
* #GVolumeMonitor implementations when destroying a shadow mount for
+ * @mount, see g_mount_is_shadowed() for more information. The caller
* will need to emit the #GMount::changed signal on @mount manually.
*
* Since: 2.20
@@ -27175,6 +28898,7 @@
* @port: the port
*
* Creates a new #GSocketConnectable for connecting to the given
+ * @hostname and @port.
*
* Returns: (transfer full): the new #GNetworkAddress
* Since: 2.22
@@ -27188,14 +28912,19 @@
* @error: a pointer to a #GError, or %NULL
*
* Creates a new #GSocketConnectable for connecting to the given
+ * @hostname and @port. May fail and return %NULL in case
* parsing @host_and_port fails.
+ *
+ * @host_and_port may be in any of a number of recognised formats; an IPv6
* address, an IPv4 address, or a domain name (in which case a DNS
* lookup is performed). Quoting with [] is supported for all address
* types. A port override may be specified in the usual way with a
* colon. Ports may be given as decimal numbers or symbolic names (in
* which case an /etc/services lookup is performed).
+ *
* If no port is specified in @host_and_port then @default_port will be
* used as the port number to connect to.
+ *
* In general, @host_and_port is expected to be provided by the user
* (allowing them to give the hostname, and a port overide if necessary)
* and @default_port is expected to be provided by the application.
@@ -27212,6 +28941,8 @@
* @error: a pointer to a #GError, or %NULL
*
* Creates a new #GSocketConnectable for connecting to the given
+ * @uri. May fail and return %NULL in case parsing @uri fails.
+ *
* Using this rather than g_network_address_new() or
* g_network_address_parse_host() allows #GSocketClient to determine
* when to use application-specific proxy protocols.
@@ -27274,6 +29005,7 @@
* @domain: the DNS domain to look up the service in
*
* Creates a new #GNetworkService representing the given @service,
+ * @protocol, and @domain. This will initially be unresolved; use the
* #GSocketConnectable interface to resolve it.
*
* Returns: (transfer full): a new #GNetworkService
@@ -27302,6 +29034,7 @@
* The returned pointer is cast to a pointer to the given type.
* If @n_structs is 0 it returns %NULL.
* Care is taken to avoid overflow when calculating the size of the allocated block.
+ *
* Since the returned pointer is already casted to the right type,
* it is normally unnecessary to cast it explicitly, and doing
* so might hide memory allocation errors.
@@ -27319,6 +29052,7 @@
* The returned pointer is cast to a pointer to the given type.
* If @n_structs is 0 it returns %NULL.
* Care is taken to avoid overflow when calculating the size of the allocated block.
+ *
* Since the returned pointer is already casted to the right type,
* it is normally unnecessary to cast it explicitly, and doing
* so might hide memory allocation errors.
@@ -27365,6 +29099,7 @@
* @node: a #GNode
*
* Gets the first child of a #GNode.
+ *
* or has no children
*
* Returns: the first child of @node, or %NULL if @node is %NULL
@@ -27400,6 +29135,7 @@
* @node: a #GNode
*
* Gets the next sibling of a #GNode.
+ *
* or %NULL
*
* Returns: the next sibling of @node, or %NULL if @node is the last node
@@ -27422,6 +29158,7 @@
* @node: a #GNode
*
* Gets the previous sibling of a #GNode.
+ *
* node or %NULL
*
* Returns: the previous sibling of @node, or %NULL if @node is the first
@@ -27432,6 +29169,7 @@
* g_null_settings_backend_new:
*
* Creates a readonly #GSettingsBackend.
+ *
* This backend does not allow changes to settings, so all settings
* will always have their default values.
*
@@ -27455,21 +29193,27 @@
* @error: location to store the error occuring, or %NULL to ignore
*
* Closes the stream, releasing resources related to it.
+ *
* Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
* Closing a stream multiple times will not return an error.
+ *
* Closing a stream will automatically flush any outstanding buffers in the
* stream.
+ *
* Streams will be automatically closed when the last reference
* is dropped, but you might want to call this function to make sure
* resources are released as early as possible.
+ *
* Some streams might keep the backing store of the stream (e.g. a file descriptor)
* open after the stream is closed. See the documentation for the individual
* stream for details.
+ *
* On failure the first error that happened will be reported, but the close
* operation will finish as much as possible. A stream that failed to
* close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
* is important to check and report the error to the user, otherwise
* there might be a loss of data as all data might not be written.
+ *
* If @cancellable is not NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -27494,7 +29238,9 @@
* related to it. When the operation is finished @callback will be
* called. You can then call g_output_stream_close_finish() to get
* the result of the operation.
+ *
* For behaviour details see g_output_stream_close().
+ *
* The asyncronous methods have a default fallback that uses threads
* to implement asynchronicity, so they are optional for inheriting
* classes. However, if you override one you must override all.
@@ -27521,7 +29267,9 @@
*
* Flushed any outstanding buffers in the stream. Will block during
* the operation. Closing the stream will implicitly cause a flush.
+ *
* This function is optional for inherited classes.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -27540,6 +29288,7 @@
*
* Flushes a stream asynchronously.
* For behaviour details see g_output_stream_flush().
+ *
* When the operation is finished @callback will be
* called. You can then call g_output_stream_flush_finish() to get the
* result of the operation.
@@ -27599,6 +29348,7 @@
*
* Sets @stream to have actions pending. If the pending flag is
* already set or @stream is closed, it will return %FALSE and set
+ * @error.
*
* Returns: %TRUE if pending was previously unset and is now set.
*/
@@ -27613,6 +29363,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Splices an input stream into an output stream.
+ *
* -1 if an error occurred. Note that if the number of bytes
* spliced is greater than %G_MAXSSIZE, then that will be
* returned, and there is no way to determine the actual number
@@ -27636,6 +29387,7 @@
* When the operation is finished @callback will be called.
* You can then call g_output_stream_splice_finish() to get the
* result of the operation.
+ *
* For the synchronous, blocking version of this function, see
* g_output_stream_splice().
*/
@@ -27648,6 +29400,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes an asynchronous stream splice operation.
+ *
* number of bytes spliced is greater than %G_MAXSSIZE, then that
* will be returned, and there is no way to determine the actual
* number of bytes spliced.
@@ -27666,18 +29419,23 @@
*
* Tries to write @count bytes from @buffer into the stream. Will block
* during the operation.
+ *
* If count is 0, returns 0 and does nothing. A value of @count
* larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
+ *
* On success, the number of bytes written to the stream is returned.
* It is not an error if this is not the same as the requested size, as it
* can happen e.g. on a partial I/O error, or if there is not enough
* storage in the stream. All writes block until at least one byte
* is written or an error occurs; 0 is never returned (unless
+ * @count is 0).
+ *
* If @cancellable is not NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
* operation was partially finished when the operation was cancelled the
* partial result will be returned, without an error.
+ *
* On error -1 is returned and @error is set accordingly.
*
* Returns: Number of bytes written, or -1 on error
@@ -27695,10 +29453,13 @@
*
* Tries to write @count bytes from @buffer into the stream. Will block
* during the operation.
+ *
* This function is similar to g_output_stream_write(), except it tries to
* write as many bytes as requested, only stopping on an error.
+ *
* On a successful write of @count bytes, %TRUE is returned, and @bytes_written
* is set to @count.
+ *
* If there is an error during the operation FALSE is returned and @error
* is set to indicate the error status, @bytes_written is updated to contain
* the number of bytes written into the stream before the error occurred.
@@ -27721,22 +29482,30 @@
* the stream. When the operation is finished @callback will be called.
* You can then call g_output_stream_write_finish() to get the result of the
* operation.
+ *
* During an async request no other sync and async calls are allowed,
* and will result in %G_IO_ERROR_PENDING errors.
+ *
* A value of @count larger than %G_MAXSSIZE will cause a
* %G_IO_ERROR_INVALID_ARGUMENT error.
+ *
* On success, the number of bytes written will be passed to the
+ * @callback. It is not an error if this is not the same as the
* requested size, as it can happen e.g. on a partial I/O error,
* but generally we try to write as many bytes as requested.
+ *
* You are guaranteed that this method will never fail with
* %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
* method will just wait until this changes.
+ *
* Any outstanding I/O request with higher priority (lower numerical
* value) will be executed before an outstanding request with lower
* priority. Default priority is %G_PRIORITY_DEFAULT.
+ *
* The asyncronous methods have a default fallback that uses threads
* to implement asynchronicity, so they are optional for inheriting
* classes. However, if you override one you must override all.
+ *
* For the synchronous, blocking version of this function, see
* g_output_stream_write().
*/
@@ -27762,13 +29531,17 @@
* @returns: %TRUE if the permission was successfully acquired
*
* Attempts to acquire the permission represented by @permission.
+ *
* The precise method by which this happens depends on the permission
* and the underlying authentication mechanism. A simple example is
* that a dialog may appear asking the user to enter their password.
+ *
* You should check with g_permission_get_can_acquire() before calling
* this function.
+ *
* If the permission is acquired then %TRUE is returned. Otherwise,
* %FALSE is returned and @error is set appropriately.
+ *
* This call is blocking, likely for a very long time (in the case that
* user interaction is required). See g_permission_acquire_async() for
* the non-blocking version.
@@ -27785,6 +29558,7 @@
* @user_data: the user data to pass to @callback
*
* Attempts to acquire the permission represented by @permission.
+ *
* This is the first half of the asynchronous version of
* g_permission_acquire().
*
@@ -27801,6 +29575,7 @@
*
* Collects the result of attempting to acquire the permission
* represented by @permission.
+ *
* This is the second half of the asynchronous version of
* g_permission_acquire().
*
@@ -27815,6 +29590,7 @@
*
* Gets the value of the 'allowed' property. This property is %TRUE if
* the caller currently has permission to perform the action that
+ * @permission represents the permission to perform.
*
* Since: 2.26
*/
@@ -27856,6 +29632,7 @@
* This function is called by the #GPermission implementation to update
* the properties of the permission. You should never call this
* function except from a #GPermission implementation.
+ *
* GObject notify signals are generated, as appropriate.
*
* Since: 2.26
@@ -27870,13 +29647,17 @@
* @returns: %TRUE if the permission was successfully released
*
* Attempts to release the permission represented by @permission.
+ *
* The precise method by which this happens depends on the permission
* and the underlying authentication mechanism. In most cases the
* permission will be dropped immediately without further action.
+ *
* You should check with g_permission_get_can_release() before calling
* this function.
+ *
* If the permission is released then %TRUE is returned. Otherwise,
* %FALSE is returned and @error is set appropriately.
+ *
* This call is blocking, likely for a very long time (in the case that
* user interaction is required). See g_permission_release_async() for
* the non-blocking version.
@@ -27893,6 +29674,7 @@
* @user_data: the user data to pass to @callback
*
* Attempts to release the permission represented by @permission.
+ *
* This is the first half of the asynchronous version of
* g_permission_release().
*
@@ -27909,6 +29691,7 @@
*
* Collects the result of attempting to release the permission
* represented by @permission.
+ *
* This is the second half of the asynchronous version of
* g_permission_release().
*
@@ -27934,6 +29717,7 @@
* #GPollableInputStream but have only certain instances of that class
* be pollable. If this method returns %FALSE, then the behavior of
* other #GPollableInputStream methods is undefined.
+ *
* For any given stream, the value returned by this method is constant;
* a stream cannot switch from pollable to non-pollable or vice versa.
*
@@ -27948,7 +29732,9 @@
* @cancellable: (allow-none): a #GCancellable, or %NULL
*
* Creates a #GSource that triggers when @stream can be read, or
+ * @cancellable is triggered or an error occurs. The callback on the
* source is of the #GPollableSourceFunc type.
+ *
* As with g_pollable_input_stream_is_readable(), it is possible that
* the stream may not actually be readable even after the source
* triggers, so you should use g_pollable_input_stream_read_nonblocking()
@@ -27964,12 +29750,14 @@
* @stream: a #GPollableInputStream.
*
* Checks if @stream can be read.
+ *
* Note that some stream types may not be able to implement this 100%
* reliably, and it is possible that a call to g_input_stream_read()
* after this returns %TRUE would still block. To guarantee
* non-blocking behavior, you should always use
* g_pollable_input_stream_read_nonblocking(), which will return a
* %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
+ *
* has occurred on @stream, this will result in
* g_pollable_input_stream_is_readable() returning %TRUE, and the
* next attempt to read will return the error.
@@ -27992,11 +29780,13 @@
* this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
* use g_pollable_input_stream_create_source() to create a #GSource
* that will be triggered when @stream is readable.
+ *
* Note that since this method never blocks, you cannot actually
* use @cancellable to cancel it. However, it will return an error
* if @cancellable has already been cancelled when you call, which
* may happen if you call this method after a source triggers due
* to having been cancelled.
+ *
* %G_IO_ERROR_WOULD_BLOCK).
*
* Virtual: read_nonblocking
@@ -28012,6 +29802,7 @@
* #GPollableOutputStream but have only certain instances of that
* class be pollable. If this method returns %FALSE, then the behavior
* of other #GPollableOutputStream methods is undefined.
+ *
* For any given stream, the value returned by this method is constant;
* a stream cannot switch from pollable to non-pollable or vice versa.
*
@@ -28026,7 +29817,9 @@
* @cancellable: (allow-none): a #GCancellable, or %NULL
*
* Creates a #GSource that triggers when @stream can be written, or
+ * @cancellable is triggered or an error occurs. The callback on the
* source is of the #GPollableSourceFunc type.
+ *
* As with g_pollable_output_stream_is_writable(), it is possible that
* the stream may not actually be writable even after the source
* triggers, so you should use g_pollable_output_stream_write_nonblocking()
@@ -28042,12 +29835,14 @@
* @stream: a #GPollableOutputStream.
*
* Checks if @stream can be written.
+ *
* Note that some stream types may not be able to implement this 100%
* reliably, and it is possible that a call to g_output_stream_write()
* after this returns %TRUE would still block. To guarantee
* non-blocking behavior, you should always use
* g_pollable_output_stream_write_nonblocking(), which will return a
* %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
+ *
* has occurred on @stream, this will result in
* g_pollable_output_stream_is_writable() returning %TRUE, and the
* next attempt to write will return the error.
@@ -28070,11 +29865,13 @@
* this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
* use g_pollable_output_stream_create_source() to create a #GSource
* that will be triggered when @stream is writable.
+ *
* Note that since this method never blocks, you cannot actually
* use @cancellable to cancel it. However, it will return an error
* if @cancellable has already been cancelled when you call, which
* may happen if you call this method after a source triggers due
* to having been cancelled.
+ *
* %G_IO_ERROR_WOULD_BLOCK).
*
* Virtual: write_nonblocking
@@ -28182,6 +29979,7 @@
* #GSocketConnection that is connected to the proxy server), this
* does the necessary handshake to connect to @proxy_address, and if
* required, wraps the #GIOStream to handle proxy payload.
+ *
* be the same as @connection, in which case a reference
* will be added.
*
@@ -28224,6 +30022,7 @@
*
* Lookup "gio-proxy" extension point for a proxy implementation that supports
* specified protocol.
+ *
* is not supported.
*
* Returns: (transfer full): return a #GProxy or NULL if protocol
@@ -28266,14 +30065,17 @@
* form <literal><protocol>://[user[:password] ]host:port</literal>
* or <literal>direct://</literal>, where <protocol> could be
* http, rtsp, socks or other proxying protocol.
+ *
* If you don't know what network protocol is being used on the
* socket, you should use <literal>none</literal> as the URI protocol.
* In this case, the resolver might still return a generic proxy type
* (such as SOCKS), but would not return protocol-specific proxy types
* (such as http).
+ *
* <literal>direct://</literal> is used when no proxy is needed.
* Direct connection should not be attempted unless it is part of the
* returned array of proxies.
+ *
* NULL-terminated array of proxy URIs. Must be freed
* with g_strfreev().
*
@@ -28306,6 +30108,7 @@
* Call this function to obtain the array of proxy URIs when
* g_proxy_resolver_lookup_async() is complete. See
* g_proxy_resolver_lookup() for more details.
+ *
* NULL-terminated array of proxy URIs. Must be freed
* with g_strfreev().
*
@@ -28338,6 +30141,7 @@
* @n_structs: the number of elements to allocate
*
* Reallocates the memory pointed to by @mem, so that it now has space for
+ * @n_structs elements of type @struct_type. It returns the new address of
* the memory, which may have been moved.
* Care is taken to avoid overflow when calculating the size of the allocated block.
*
@@ -28403,11 +30207,14 @@
*
* Synchronously reverse-resolves @address to determine its
* associated hostname.
+ *
* If the DNS resolution fails, @error (if non-%NULL) will be set to
* a value from #GResolverError.
+ *
* If @cancellable is non-%NULL, it can be used to cancel the
* operation, in which case @error (if non-%NULL) will be set to
* %G_IO_ERROR_CANCELLED.
+ *
* form), or %NULL on error.
*
* Returns: a hostname (either ASCII-only, or in ASCII-encoded
@@ -28439,8 +30246,11 @@
*
* Retrieves the result of a previous call to
* g_resolver_lookup_by_address_async().
+ *
* If the DNS resolution failed, @error (if non-%NULL) will be set to
* a value from #GResolverError. If the operation was cancelled,
+ * @error will be set to %G_IO_ERROR_CANCELLED.
+ *
* form), or %NULL on error.
*
* Returns: a hostname (either ASCII-only, or in ASCII-encoded
@@ -28459,20 +30269,26 @@
* address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
* the textual form of an IP address (in which case this just becomes
* a wrapper around g_inet_address_new_from_string()).
+ *
* On success, g_resolver_lookup_by_name() will return a #GList of
* #GInetAddress, sorted in order of preference and guaranteed to not
* contain duplicates. That is, if using the result to connect to
+ * @hostname, you should attempt to connect to the first address
* first, then the second if the first fails, etc. If you are using
* the result to listen on a socket, it is appropriate to add each
* result using e.g. g_socket_listener_add_address().
+ *
* If the DNS resolution fails, @error (if non-%NULL) will be set to a
* value from #GResolverError.
+ *
* If @cancellable is non-%NULL, it can be used to cancel the
* operation, in which case @error (if non-%NULL) will be set to
* %G_IO_ERROR_CANCELLED.
+ *
* If you are planning to connect to a socket on the resolved IP
* address, it may be easier to create a #GNetworkAddress and use its
* #GSocketConnectable interface.
+ *
* of #GInetAddress, or %NULL on error. You
* must unref each of the addresses and free the list when you are
* done with it. (You can use g_resolver_free_addresses() to do this.)
@@ -28507,8 +30323,11 @@
*
* Retrieves the result of a call to
* g_resolver_lookup_by_name_async().
+ *
* If the DNS resolution failed, @error (if non-%NULL) will be set to
* a value from #GResolverError. If the operation was cancelled,
+ * @error will be set to %G_IO_ERROR_CANCELLED.
+ *
* of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
* for more details.
*
@@ -28527,20 +30346,28 @@
* @error: return location for a #GError, or %NULL
*
* Synchronously performs a DNS SRV lookup for the given @service and
+ * @protocol in the given @domain and returns an array of #GSrvTarget.
+ * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
+ * @service and @protocol arguments <emphasis>do not</emphasis>
* include the leading underscore that appears in the actual DNS
* entry.
+ *
* On success, g_resolver_lookup_service() will return a #GList of
* #GSrvTarget, sorted in order of preference. (That is, you should
* attempt to connect to the first target first, then the second if
* the first fails, etc.)
+ *
* If the DNS resolution fails, @error (if non-%NULL) will be set to
* a value from #GResolverError.
+ *
* If @cancellable is non-%NULL, it can be used to cancel the
* operation, in which case @error (if non-%NULL) will be set to
* %G_IO_ERROR_CANCELLED.
+ *
* If you are planning to connect to the service, it is usually easier
* to create a #GNetworkService and use its #GSocketConnectable
* interface.
+ *
* or %NULL on error. You must free each of the targets and the list when you are
* done with it. (You can use g_resolver_free_targets() to do this.)
*
@@ -28560,6 +30387,8 @@
* @user_data: (closure): data for @callback
*
* Begins asynchronously performing a DNS SRV lookup for the given
+ * @service and @protocol in the given @domain, and eventually calls
+ * @callback, which must call g_resolver_lookup_service_finish() to
* get the final result. See g_resolver_lookup_service() for more
* details.
*
@@ -28575,8 +30404,11 @@
*
* Retrieves the result of a previous call to
* g_resolver_lookup_service_async().
+ *
* If the DNS resolution failed, @error (if non-%NULL) will be set to
* a value from #GResolverError. If the operation was cancelled,
+ * @error will be set to %G_IO_ERROR_CANCELLED.
+ *
* or %NULL on error. See g_resolver_lookup_service() for more details.
*
* Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
@@ -28589,7 +30421,9 @@
* @resolver: the new default #GResolver
*
* Sets @resolver to be the application's default resolver (reffing
+ * @resolver, and unreffing the previous default resolver, if any).
* Future calls to g_resolver_get_default() will return this resolver.
+ *
* This can be used if an application wants to perform any sort of DNS
* caching or "pinning"; it can implement its own #GResolver that
* calls the original default resolver for DNS operations, and
@@ -28629,9 +30463,11 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Seeks in the stream by the given @offset, modified by @type.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ *
* has occurred, this function will return %FALSE and set @error
* appropriately if present.
*
@@ -28657,11 +30493,13 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Truncates a stream with a given #offset.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
* operation was partially finished when the operation was cancelled the
* partial result will be returned, without an error.
+ *
* has occurred, this function will return %FALSE and set @error
* appropriately if present.
*
@@ -28690,17 +30528,22 @@
* Signals that a single key has possibly changed. Backend
* implementations should call this if a key has possibly changed its
* value.
+ *
+ * @key must be a valid key (ie starting with a slash, not containing
* '//', and not ending with a slash).
+ *
* The implementation must call this function during any call to
* g_settings_backend_write(), before the call returns (except in the
* case that no keys are actually changed and it cares to detect this
* fact). It may not rely on the existence of a mainloop for
* dispatching the signal later.
+ *
* The implementation may call this function at any other time it likes
* in response to other events (such as changes occuring outside of the
* program). These calls may originate from a mainloop or may originate
* in response to any other action (including from calls to
* g_settings_backend_write()).
+ *
* In the case that this call is in response to a call to
* g_settings_backend_write() then @origin_tag must be set to the same
* value that was passed to that call.
@@ -28716,6 +30559,7 @@
* @origin_tag: the origin tag
*
* This call is a convenience wrapper. It gets the list of changes from
+ * @tree, computes the longest common prefix and calls
* g_settings_backend_changed().
*
* Since: 2.26
@@ -28732,8 +30576,10 @@
* Calculate the longest common prefix of all keys in a tree and write
* out an array of the key names relative to that prefix and,
* optionally, the value to store at each of those keys.
+ *
* You must free the value returned in @path, @keys and @values using
* g_free(). You should not attempt to free or unref the contents of
+ * @keys or @values.
*
* Since: 2.26
*/
@@ -28746,6 +30592,7 @@
* Returns the default #GSettingsBackend. It is possible to override
* the default by setting the <envar>GSETTINGS_BACKEND</envar>
* environment variable to the name of a settings backend.
+ *
* The user gets a reference to the backend.
*
* Since: 2.28
@@ -28762,20 +30609,25 @@
* Signals that a list of keys have possibly changed. Backend
* implementations should call this if keys have possibly changed their
* values.
+ *
+ * @path must be a valid path (ie starting and ending with a slash and
* not containing '//'). Each string in @items must form a valid key
+ * name when @path is prefixed to it (ie: each item must not start or
* end with '/' and must not contain '//').
+ *
* The meaning of this signal is that any of the key names resulting
* from the contatenation of @path with each item in @items may have
* changed.
+ *
* The same rules for when notifications must occur apply as per
* g_settings_backend_changed(). These two calls can be used
* interchangeably if exactly one item has changed (although in that
* case g_settings_backend_changed() is definitely preferred).
+ *
* For efficiency reasons, the implementation should strive for @path to
+ * be as long as possible (ie: the longest common prefix of all of the
* keys that were changed) but this is not strictly required.
*
- * Name when @path is prefixed to it (ie: each item must not start or
- * Be as long as possible (ie: the longest common prefix of all of the
* Since: 2.26
*/
@@ -28789,20 +30641,25 @@
* Signals that all keys below a given path may have possibly changed.
* Backend implementations should call this if an entire path of keys
* have possibly changed their values.
+ *
+ * @path must be a valid path (ie starting and ending with a slash and
* not containing '//').
+ *
* The meaning of this signal is that any of the key which has a name
* starting with @path may have changed.
+ *
* The same rules for when notifications must occur apply as per
* g_settings_backend_changed(). This call might be an appropriate
* reasponse to a 'reset' call but implementations are also free to
* explicitly list the keys that were affected by that call if they can
* easily do so.
+ *
* For efficiency reasons, the implementation should strive for @path to
+ * be as long as possible (ie: the longest common prefix of all of the
* keys that were changed) but this is not strictly required. As an
* example, if this function is called with the path of "/" then every
* single key in the application will be notified of a possible change.
*
- * Be as long as possible (ie: the longest common prefix of all of the
* Since: 2.26
*/
@@ -28814,6 +30671,7 @@
*
* Signals that the writability of all keys below a given path may have
* changed.
+ *
* Since GSettings performs no locking operations for itself, this call
* will always be made in response to external events.
*
@@ -28827,6 +30685,7 @@
* @key: the name of the key
*
* Signals that the writability of a single key has possibly changed.
+ *
* Since GSettings performs no locking operations for itself, this call
* will always be made in response to external events.
*
@@ -28844,16 +30703,20 @@
*
* Create a binding between the @key in the @settings object
* and the property @property of @object.
+ *
* The binding uses the default GIO mapping functions to map
* between the settings and property values. These functions
* handle booleans, numeric types and string types in a
* straightforward way. Use g_settings_bind_with_mapping() if
* you need a custom mapping, or map between types that are not
* supported by the default mapping functions.
+ *
* Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
* function also establishes a binding between the writability of
+ * @key and the "sensitive" property of @object (if @object has
* a boolean property by that name). See g_settings_bind_writable()
* for more details about writable bindings.
+ *
* Note that the lifecycle of the binding is tied to the object,
* and that you can have only one binding per object property.
* If you bind the same property twice on the same object, the second
@@ -28877,8 +30740,10 @@
*
* Create a binding between the @key in the @settings object
* and the property @property of @object.
+ *
* The binding uses the provided mapping functions to map between
* settings and property values.
+ *
* Note that the lifecycle of the binding is tied to the object,
* and that you can have only one binding per object property.
* If you bind the same property twice on the same object, the second
@@ -28897,15 +30762,19 @@
* @inverted: whether to 'invert' the value
*
* Create a binding between the writability of @key in the
+ * @settings object and the property @property of @object.
* The property must be boolean; "sensitive" or "visible"
* properties of widgets are the most likely candidates.
+ *
* Writable bindings are always uni-directional; changes of the
* writability of the setting will be propagated to the object
* property, not the other way.
+ *
* When the @inverted argument is %TRUE, the binding inverts the
* value as it passes from the setting to the object, i.e. @property
* will be set to %TRUE if the key is <emphasis>not</emphasis>
* writable.
+ *
* Note that the lifecycle of the binding is tied to the object,
* and that you can have only one binding per object property.
* If you bind the same property twice on the same object, the second
@@ -28935,8 +30804,10 @@
* @...: arguments as per @format
*
* Gets the value that is stored at @key in @settings.
+ *
* A convenience function that combines g_settings_get_value() with
* g_variant_get().
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings or for the #GVariantType of @format to mismatch
* the type given in the schema.
@@ -28952,7 +30823,9 @@
* @returns: a boolean
*
* Gets the value that is stored at @key in @settings.
+ *
* A convenience variant of g_settings_get() for booleans.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a boolean type in the schema for @settings.
*
@@ -28969,6 +30842,7 @@
* Creates a 'child' settings object which has a base path of
* <replaceable>base-path</replaceable>/@name, where
* <replaceable>base-path</replaceable> is the base path of @settings.
+ *
* The schema for the child settings object must have been declared
* in the schema of @settings using a <tag class="starttag">child</tag> element.
*
@@ -28983,7 +30857,9 @@
* @returns: a double
*
* Gets the value that is stored at @key in @settings.
+ *
* A convenience variant of g_settings_get() for doubles.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a 'double' type in the schema for @settings.
*
@@ -28999,10 +30875,13 @@
*
* Gets the value that is stored in @settings for @key and converts it
* to the enum value that it represents.
+ *
* In order to use this function the type of the value must be a string
* and it must be marked in the schema file as an enumerated type.
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings or is not marked as an enumerated type.
+ *
* If the value stored in the configuration database is not a valid
* value for the enumerated type then this function will return the
* default value.
@@ -29019,10 +30898,13 @@
*
* Gets the value that is stored in @settings for @key and converts it
* to the flags value that it represents.
+ *
* In order to use this function the type of the value must be an array
* of strings and it must be marked in the schema file as an flags type.
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings or is not marked as a flags type.
+ *
* If the value stored in the configuration database is not a valid
* value for the flags type then this function will return the default
* value.
@@ -29050,7 +30932,9 @@
* @returns: an integer
*
* Gets the value that is stored at @key in @settings.
+ *
* A convenience variant of g_settings_get() for 32-bit integers.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a int32 type in the schema for @settings.
*
@@ -29068,26 +30952,30 @@
*
* Gets the value that is stored at @key in @settings, subject to
* application-level validation/mapping.
+ *
* You should use this function when the application needs to perform
* some processing on the value of the key (for example, parsing). The
+ * @mapping function performs that processing. If the function
* indicates that the processing was unsuccessful (due to a parse error,
* for example) then the mapping is tried again with another value.
* This allows a robust 'fall back to defaults' behaviour to be
* implemented somewhat automatically.
+ *
* The first value that is tried is the user's setting for the key. If
* the mapping function fails to map this value, other values may be
* tried in an unspecified order (system or site defaults, translated
* schema default values, untranslated schema default values, etc).
+ *
* If the mapping function fails for all possible values, one additional
+ * attempt is made: the mapping function is called with a %NULL value.
* If the mapping function still indicates failure at this point then
* the application will be aborted.
+ *
* The result parameter for the @mapping function is pointed to a
* #gpointer which is initially set to %NULL. The same pointer is given
* to each invocation of @mapping. The final value of that #gpointer is
* what is returned by this function. %NULL is valid; it is returned
* just as any other value would be.
- *
- * Attempt is made: the mapping function is called with a %NULL value.
*/
@@ -29098,18 +30986,23 @@
* @returns: a #GVariant describing the range
*
* Queries the range of a key.
+ *
* This function will return a #GVariant that fully describes the range
* of values that are valid for @key.
+ *
* The type of #GVariant returned is <literal>(sv)</literal>. The
* string describes the type of range restriction in effect. The type
* and meaning of the value contained in the variant depends on the
* string.
+ *
* If the string is <literal>'type'</literal> then the variant contains
* an empty array. The element type of that empty array is the expected
* type of value and all values of that type are valid.
+ *
* If the string is <literal>'enum'</literal> then the variant contains
* an array enumerating the possible values. Each item in the array is
* a possible valid value and no other values are valid.
+ *
* If the string is <literal>'flags'</literal> then the variant contains
* an array. Each item in the array is a value that may appear zero or
* one times in an array to be used as the value for this key. For
@@ -29118,16 +31011,20 @@
* <literal>[]</literal>, <literal>['x']</literal>,
* <literal>['y']</literal>, <literal>['x', 'y']</literal> and
* <literal>['y', 'x']</literal>.
+ *
* Finally, if the string is <literal>'range'</literal> then the variant
* contains a pair of like-typed values -- the minimum and maximum
* permissible values for this key.
+ *
* This information should not be used by normal programs. It is
* considered to be a hint for introspection purposes. Normal programs
* should already know what is permitted by their own schema. The
* format may change in any way in the future -- but particularly, new
* forms may be added to the possibilities described above.
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings.
+ *
* You should free the returned value with g_variant_unref() when it is
* no longer needed.
*
@@ -29142,7 +31039,9 @@
* @returns: a newly-allocated string
*
* Gets the value that is stored at @key in @settings.
+ *
* A convenience variant of g_settings_get() for strings.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a string type in the schema for @settings.
*
@@ -29157,6 +31056,7 @@
* @returns: (array zero-terminated=1) (transfer full): a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings.
*
* A convenience variant of g_settings_get() for string arrays.
+ *
* It is a programmer error to give a @key that isn't specified as
* having an array of strings type in the schema for @settings.
*
@@ -29171,8 +31071,10 @@
* @returns: an unsigned integer
*
* Gets the value that is stored at @key in @settings.
+ *
* A convenience variant of g_settings_get() for 32-bit unsigned
* integers.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a uint32 type in the schema for @settings.
*
@@ -29187,6 +31089,7 @@
* @returns: a new #GVariant
*
* Gets the value that is stored in @settings for @key.
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings.
*
@@ -29212,21 +31115,24 @@
* @returns: (transfer full) (element-type utf8): a list of the children on @settings
*
* Gets the list of children on @settings.
+ *
* The list is exactly the list of strings for which it is not an error
* to call g_settings_get_child().
+ *
* For GSettings objects that are lists, this value can change at any
* time and you should connect to the "children-changed" signal to watch
+ * for those changes. Note that there is a race condition here: you may
* request a child after listing it only for it to have been destroyed
* in the meantime. For this reason, g_settings_get_child() may return
* %NULL even for a child that was listed by this function.
+ *
* For GSettings objects that are not lists, you should probably not be
* calling this function from "normal" code (since you should already
* know what children are in your schema). This function may still be
* useful there for introspection reasons, however.
+ *
* You should free the return value with g_strfreev() when you are done
* with it.
- *
- * For those changes. note that there is a race condition here: you may
*/
@@ -29236,9 +31142,11 @@
* @returns: (transfer full) (element-type utf8): a list of the keys on @settings
*
* Introspects the list of keys on @settings.
+ *
* You should probably not be calling this function from "normal" code
* (since you should already know what keys are in your schema). This
* function is intended for introspection reasons.
+ *
* You should free the return value with g_strfreev() when you are done
* with it.
*/
@@ -29251,9 +31159,11 @@
* system. These are schemas that do not provide their own path. It is
* usual to instantiate these schemas directly, but if you want to you
* can use g_settings_new_with_path() to specify the path.
+ *
* The output of this function, tTaken together with the output of
* g_settings_list_schemas() represents the complete list of all
* installed schemas.
+ *
* #GSettings schemas that are available. The list must not be
* modified or freed.
*
@@ -29268,13 +31178,15 @@
* Gets a list of the #GSettings schemas installed on the system. The
* returned list is exactly the list of schemas for which you may call
* g_settings_new() without adverse effects.
+ *
* This function does not list the schemas that do not provide their own
+ * paths (ie: schemas for which you must use
* g_settings_new_with_path()). See
* g_settings_list_relocatable_schemas() for that.
+ *
* schemas that are available. The list must not be modified or
* freed.
*
- * Paths (ie: schemas for which you must use
* Returns: (element-type utf8) (transfer none): a list of #GSettings
* Since: 2.26
*/
@@ -29286,6 +31198,7 @@
* @returns: a new #GSettings object
*
* Creates a new #GSettings object with a given schema.
+ *
* Signals on the newly created #GSettings object will be dispatched
* via the thread-default #GMainContext in effect at the time of the
* call to g_settings_new(). The new #GSettings will hold a reference
@@ -29302,6 +31215,7 @@
* @returns: a new #GSettings object
*
* Creates a new #GSettings object with a given schema and backend.
+ *
* Creating a #GSettings object with a different backend allows accessing
* settings from a database other than the usual one. For example, it may make
* sense to pass a backend corresponding to the "defaults" settings database on
@@ -29321,6 +31235,7 @@
*
* Creates a new #GSettings object with a given schema, backend and
* path.
+ *
* This is a mix of g_settings_new_with_backend() and
* g_settings_new_with_path().
*
@@ -29335,9 +31250,11 @@
* @returns: a new #GSettings object
*
* Creates a new #GSettings object with a given schema and path.
+ *
* You only need to do this if you want to directly create a settings
* object with a schema that doesn't have a specified path of its own.
* That's quite rare.
+ *
* It is a programmer error to call this function for a schema that
* has an explicitly specified path.
*
@@ -29354,9 +31271,11 @@
*
* Checks if the given @value is of the correct type and within the
* permitted range for @key.
+ *
* This API is not intended to be used by normal programs -- they should
* already know what is permitted by their own schemas. This API is
* meant to be used by programs such as editors or commandline tools.
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings.
*
@@ -29370,6 +31289,7 @@
* @key: the name of a key
*
* Resets @key to its default value.
+ *
* This call resets the key, as much as possible, to its default value.
* That might the value specified in the schema or the one set by the
* administrator.
@@ -29384,6 +31304,7 @@
* does nothing unless @settings is in 'delay-apply' mode; see
* g_settings_delay(). In the normal case settings are always applied
* immediately.
+ *
* Change notifications will be emitted for affected keys.
*/
@@ -29397,8 +31318,10 @@
* @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
*
* Sets @key in @settings to @value.
+ *
* A convenience function that combines g_settings_set_value() with
* g_variant_new().
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings or for the #GVariantType of @format to mismatch
* the type given in the schema.
@@ -29415,7 +31338,9 @@
* @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
*
* Sets @key in @settings to @value.
+ *
* A convenience variant of g_settings_set() for booleans.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a boolean type in the schema for @settings.
*
@@ -29431,7 +31356,9 @@
* @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
*
* Sets @key in @settings to @value.
+ *
* A convenience variant of g_settings_set() for doubles.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a 'double' type in the schema for @settings.
*
@@ -29448,10 +31375,14 @@
*
* Looks up the enumerated type nick for @value and writes it to @key,
* within @settings.
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings or is not marked as an enumerated type, or for
+ * @value not to be a valid value for the named type.
+ *
* After performing the write, accessing @key directly with
* g_settings_get_string() will return the 'nick' associated with
+ * @value.
*/
@@ -29464,9 +31395,12 @@
*
* Looks up the flags type nicks for the bits specified by @value, puts
* them in an array of strings and writes the array to @key, withing
+ * @settings.
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings or is not marked as a flags type, or for @value
* to contain any bits that are not value for the named type.
+ *
* After performing the write, accessing @key directly with
* g_settings_get_strv() will return an array of 'nicks'; one for each
* bit in @value.
@@ -29481,7 +31415,9 @@
* @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
*
* Sets @key in @settings to @value.
+ *
* A convenience variant of g_settings_set() for 32-bit integers.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a int32 type in the schema for @settings.
*
@@ -29497,7 +31433,9 @@
* @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
*
* Sets @key in @settings to @value.
+ *
* A convenience variant of g_settings_set() for strings.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a string type in the schema for @settings.
*
@@ -29513,7 +31451,10 @@
* @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
*
* Sets @key in @settings to @value.
+ *
* A convenience variant of g_settings_set() for string arrays. If
+ * @value is %NULL, then @key is set to be the empty array.
+ *
* It is a programmer error to give a @key that isn't specified as
* having an array of strings type in the schema for @settings.
*
@@ -29529,8 +31470,10 @@
* @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
*
* Sets @key in @settings to @value.
+ *
* A convenience variant of g_settings_set() for 32-bit unsigned
* integers.
+ *
* It is a programmer error to give a @key that isn't specified as
* having a uint32 type in the schema for @settings.
*
@@ -29546,9 +31489,11 @@
* @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
*
* Sets @key in @settings to @value.
+ *
* It is a programmer error to give a @key that isn't contained in the
* schema for @settings or for @value to have the incorrect type, per
* the schema.
+ *
* If @value is floating then this function consumes the reference.
*
* Since: 2.26
@@ -29560,9 +31505,11 @@
*
* Ensures that all pending operations for the given are complete for
* the default backend.
+ *
* Writes made to a #GSettings are handled asynchronously. For this
* reason, it is very unlikely that the changes have it to disk by the
* time g_settings_set() returns.
+ *
* This call will block until all of the writes have made it to the
* backend. Since the mainloop is not running, no change notifications
* will be dispatched during this call (but some may be queued by the
@@ -29576,6 +31523,7 @@
* @property: the property whose binding is removed
*
* Removes an existing binding for @property on @object.
+ *
* Note that bindings are automatically removed when the
* object is finalized, so it is rarely necessary to call this
* function.
@@ -29592,6 +31540,7 @@
* @data: data to pass to @c_handler calls.
*
* Connects a #GCallback function to a signal for a particular object.
+ *
* The handler will be called before the default handler of the signal.
*
* Returns: the handler id
@@ -29606,6 +31555,7 @@
* @data: data to pass to @c_handler calls.
*
* Connects a #GCallback function to a signal for a particular object.
+ *
* The handler will be called after the default handler of the signal.
*
* Returns: the handler id
@@ -29620,6 +31570,7 @@
* @data: data to pass to @c_handler calls.
*
* Connects a #GCallback function to a signal for a particular object.
+ *
* The instance on which the signal is emitted and @data will be swapped when
* calling the handler.
*
@@ -29672,7 +31623,9 @@
*
* A convenience function for creating multiple #GSimpleAction instances
* and adding them to the action group.
+ *
* Each action is constructed as per one #GActionEntry.
+ *
* <example>
* <title>Using g_simple_action_group_add_entries()</title>
* <programlisting>
@@ -29683,6 +31636,7 @@
* {
* exit (0);
* }
+ *
* static void
* activate_print_string (GSimpleAction *simple,
* GVariant *parameter,
@@ -29690,6 +31644,7 @@
* {
* g_print ("%s\n", g_variant_get_string (parameter, NULL));
* }
+ *
* static GActionGroup *
* create_action_group (void)
* {
@@ -29698,8 +31653,10 @@
* { "print-string", activate_print_string, "s" }
* };
* GSimpleActionGroup *group;
+ *
* group = g_simple_action_group_new ();
* g_simple_action_group_add_entries (group, entries, G_N_ELEMENTS (entries), NULL);
+ *
* return G_ACTION_GROUP (group);
* }
* </programlisting>
@@ -29715,7 +31672,10 @@
* @action: a #GAction
*
* Adds an action to the action group.
+ *
* If the action group already contains an action with the same name as
+ * @action then the old action is dropped from the group.
+ *
* The action group takes its own reference on @action.
*
* Since: 2.28
@@ -29728,6 +31688,7 @@
* @action_name: the name of an action
*
* Looks up the action with the name @action_name in the group.
+ *
* If no such action exists, returns %NULL.
*
* Returns: (transfer none): a #GAction, or %NULL
@@ -29751,6 +31712,7 @@
* @action_name: the name of the action
*
* Removes the named action from the action group.
+ *
* If no action of this name is in the group then nothing happens.
*
* Since: 2.28
@@ -29763,6 +31725,7 @@
* @parameter_type: (allow-none): the type of parameter to the activate function
*
* Creates a new action.
+ *
* The created action is stateless. See g_simple_action_new_stateful().
*
* Returns: a new #GSimpleAction
@@ -29777,7 +31740,10 @@
* @state: the initial state of the action
*
* Creates a new stateful action.
+ *
+ * @state is the initial state of the action. All future state values
* must have the same #GVariantType as the initial state.
+ *
* If the @state GVariant is floating, it is consumed.
*
* Returns: a new #GSimpleAction
@@ -29791,8 +31757,10 @@
* @enabled: whether the action is enabled
*
* Sets the action as enabled or not.
+ *
* An action must be enabled in order to be activated or in order to
* have its state changed from outside callers.
+ *
* This should only be called by the implementor of the action. Users
* of the action should not attempt to modify its enabled flag.
*
@@ -29806,7 +31774,9 @@
* @value: the new #GVariant for the state
*
* Sets the state of the action.
+ *
* This directly updates the 'state' property to the given value.
+ *
* This should only be called by the implementor of the action. Users
* of the action should not attempt to directly modify the 'state'
* property. Instead, they should call g_action_change_state() to
@@ -29868,6 +31838,7 @@
* the thread where the asynchronous result was to be delivered, as it
* invokes the callback directly. If you are in a different thread use
* g_simple_async_result_complete_in_idle().
+ *
* Calling this function takes a reference to @simple for as long as
* is needed to complete the call.
*/
@@ -29880,6 +31851,7 @@
* Completes an asynchronous function in an idle handler in the <link
* linkend="g-main-context-push-thread-default">thread-default main
* loop</link> of the thread that @simple was initially created in.
+ *
* Calling this function takes a reference to @simple for as long as
* is needed to complete the call.
*/
@@ -29890,6 +31862,7 @@
* @simple: a #GSimpleAsyncResult.
*
* Gets the operation result boolean from within the asynchronous result.
+ *
* if the operation's result was %FALSE.
*
* Returns: %TRUE if the operation's result was %TRUE, %FALSE
@@ -29934,12 +31907,14 @@
*
* Ensures that the data passed to the _finish function of an async
* operation is consistent. Three checks are performed.
+ *
* First, @result is checked to ensure that it is really a
* #GSimpleAsyncResult. Second, @source is checked to ensure that it
* matches the source object of @result. Third, @source_tag is
* checked to ensure that it is either %NULL (as it is when the result was
* created by g_simple_async_report_error_in_idle() or
* g_simple_async_report_gerror_in_idle()) or equal to the
+ * @source_tag argument given to g_simple_async_result_new() (which, by
* convention, is a pointer to the _async function corresponding to the
* _finish function from which this function is called).
*
@@ -30027,6 +32002,7 @@
* Runs the asynchronous job in a separate thread and then calls
* g_simple_async_result_complete_in_idle() on @simple to return
* the result to the appropriate main loop.
+ *
* Calling this function takes a reference to @simple for as long as
* is needed to run the job and report its completion.
*/
@@ -30137,11 +32113,14 @@
* Accept incoming connections on a connection-based socket. This removes
* the first outstanding connection request from the listening socket and
* creates a #GSocket object for it.
+ *
* The @socket must be bound to a local address with g_socket_bind() and
* must be listening for incoming connections (g_socket_listen()).
+ *
* If there are no outstanding connections then the operation will block
* or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
* To be notified of an incoming connection, wait for the %G_IO_IN condition.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a new #GSocket, or %NULL on error.
@@ -30160,6 +32139,7 @@
* to do a DNS lookup before it can return an address.) Use
* g_socket_address_enumerator_next_async() if you need to avoid
* blocking.
+ *
* If @enumerator is expected to yield addresses, but for some reason
* is unable to (eg, because of a DNS error), then the first call to
* g_socket_address_enumerator_next() will return an appropriate error
@@ -30167,6 +32147,7 @@
* g_socket_address_enumerator_next() succeeds, then any further
* internal errors (other than @cancellable being triggered) will be
* ignored.
+ *
* error (in which case * error will be set) or if there are no
* more addresses.
*
@@ -30197,6 +32178,7 @@
* g_socket_address_enumerator_next_async(). See
* g_socket_address_enumerator_next() for more information about
* error handling.
+ *
* error (in which case * error will be set) or if there are no
* more addresses.
*
@@ -30223,6 +32205,8 @@
* You can use this to allocate memory to pass to
* g_socket_address_to_native().
*
+ * @address represents
+ *
* Returns: the size of the native <type>struct sockaddr</type> that
* Since: 2.22
*/
@@ -30235,6 +32219,7 @@
*
* Creates a #GSocketAddress subclass corresponding to the native
* <type>struct sockaddr</type> @native.
+ *
* otherwise %NULL.
*
* Returns: a new #GSocketAddress if @native could successfully be converted,
@@ -30252,6 +32237,7 @@
* Converts a #GSocketAddress to a native <type>struct
* sockaddr</type>, which can be passed to low-level functions like
* connect() or bind().
+ *
* If not enough space is availible, a %G_IO_ERROR_NO_SPACE error is
* returned. If the address type is not known on the system
* then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
@@ -30271,10 +32257,13 @@
* When a socket is created it is attached to an address family, but it
* doesn't have an address in this family. g_socket_bind() assigns the
* address (sometimes called name) of the socket.
+ *
* It is generally required to bind to a local address before you can
* receive connections. (See g_socket_listen() and g_socket_accept() ).
* In certain situations, you may also want to bind a socket that will be
* used to initiate connections, though this is not normally required.
+ *
+ * @allow_reuse should be %TRUE for server sockets (sockets that you will
* eventually call g_socket_accept() on), and %FALSE for client sockets.
* (Specifically, if it is %TRUE, then g_socket_bind() will set the
* %SO_REUSEADDR flag on the socket, allowing it to bind @address even if
@@ -30316,6 +32305,7 @@
* #GSocketConnection, and seeing if it's a #GProxyAddress of the
* appropriate type, to determine whether or not it needs to handle
* the proxy handshaking itself.
+ *
* This should be used for proxy protocols that are dialects of
* another protocol such as HTTP proxy. It also allows cohabitation of
* proxy protocols that are reused between protocols. A good example
@@ -30332,16 +32322,21 @@
* @error: #GError for error reporting, or %NULL to ignore.
*
* Tries to resolve the @connectable and make a network connection to it.
+ *
* Upon a successful connection, a new #GSocketConnection is constructed
* and returned. The caller owns this new object and must drop their
* reference to it when finished with it.
+ *
* The type of the #GSocketConnection object returned depends on the type of
* the underlying socket that is used. For instance, for a TCP/IP connection
* it will be a #GTcpConnection.
+ *
* The socket created will be the same family as the address that the
+ * @connectable resolves to, unless family is set with g_socket_client_set_family()
* or indirectly via g_socket_client_set_local_address(). The socket type
* defaults to %G_SOCKET_TYPE_STREAM but can be set with
* g_socket_client_set_socket_type().
+ *
* If a local address is specified with g_socket_client_set_local_address() the
* socket will be bound to this address before connecting.
*
@@ -30359,6 +32354,7 @@
* @user_data: (closure): user data for the callback
*
* This is the asynchronous version of g_socket_client_connect().
+ *
* When the operation is finished @callback will be
* called. You can then call g_socket_client_connect_finish() to get
* the result of the operation.
@@ -30389,23 +32385,32 @@
* @error: a pointer to a #GError, or %NULL
*
* This is a helper function for g_socket_client_connect().
+ *
* Attempts to create a TCP connection to the named host.
+ *
+ * @host_and_port may be in any of a number of recognized formats; an IPv6
* address, an IPv4 address, or a domain name (in which case a DNS
* lookup is performed). Quoting with [] is supported for all address
* types. A port override may be specified in the usual way with a
* colon. Ports may be given as decimal numbers or symbolic names (in
* which case an /etc/services lookup is performed).
+ *
* If no port override is given in @host_and_port then @default_port will be
* used as the port number to connect to.
+ *
* In general, @host_and_port is expected to be provided by the user (allowing
* them to give the hostname, and a port override if necessary) and
+ * @default_port is expected to be provided by the application.
+ *
* In the case that an IP address is given, a single connection
* attempt is made. In the case that a name is given, multiple
* connection attempts may be made, in turn and according to the
* number of address records in DNS, until a connection succeeds.
+ *
* Upon a successful connection, a new #GSocketConnection is constructed
* and returned. The caller owns this new object and must drop their
* reference to it when finished with it.
+ *
* In the event of any failure (DNS error, service not found, no hosts
* connectable) %NULL is returned and @error (if non-%NULL) is set
* accordingly.
@@ -30425,6 +32430,7 @@
* @user_data: (closure): user data for the callback
*
* This is the asynchronous version of g_socket_client_connect_to_host().
+ *
* When the operation is finished @callback will be
* called. You can then call g_socket_client_connect_to_host_finish() to get
* the result of the operation.
@@ -30456,13 +32462,16 @@
* @returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
*
* Attempts to create a TCP connection to a service.
+ *
* This call looks up the SRV record for @service at @domain for the
* "tcp" protocol. It then attempts to connect, in turn, to each of
* the hosts providing the service until either a connection succeeds
* or there are no hosts remaining.
+ *
* Upon a successful connection, a new #GSocketConnection is constructed
* and returned. The caller owns this new object and must drop their
* reference to it when finished with it.
+ *
* In the event of any failure (DNS error, service not found, no hosts
* connectable) %NULL is returned and @error (if non-%NULL) is set
* accordingly.
@@ -30507,17 +32516,23 @@
* @error: a pointer to a #GError, or %NULL
*
* This is a helper function for g_socket_client_connect().
+ *
* Attempts to create a TCP connection with a network URI.
+ *
+ * @uri may be any valid URI containing an "authority" (hostname/port)
* component. If a port is not specified in the URI, @default_port
* will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
* (#GSocketClient does not know to automatically assume TLS for
* certain URI schemes.)
+ *
* Using this rather than g_socket_client_connect() or
* g_socket_client_connect_to_host() allows #GSocketClient to
* determine when to use application-specific proxy protocols.
+ *
* Upon a successful connection, a new #GSocketConnection is constructed
* and returned. The caller owns this new object and must drop their
* reference to it when finished with it.
+ *
* In the event of any failure (DNS error, service not found, no hosts
* connectable) %NULL is returned and @error (if non-%NULL) is set
* accordingly.
@@ -30537,6 +32552,7 @@
* @user_data: (closure): user data for the callback
*
* This is the asynchronous version of g_socket_client_connect_to_uri().
+ *
* When the operation is finished @callback will be
* called. You can then call g_socket_client_connect_to_uri_finish() to get
* the result of the operation.
@@ -30574,6 +32590,7 @@
* @client: a #GSocketClient.
*
* Gets the socket family of the socket client.
+ *
* See g_socket_client_set_family() for details.
*
* Returns: a #GSocketFamily
@@ -30586,6 +32603,7 @@
* @client: a #GSocketClient.
*
* Gets the local address of the socket client.
+ *
* See g_socket_client_set_local_address() for details.
*
* Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
@@ -30598,6 +32616,7 @@
* @client: a #GSocketClient
*
* Gets the protocol name type of the socket client.
+ *
* See g_socket_client_set_protocol() for details.
*
* Returns: a #GSocketProtocol
@@ -30610,6 +32629,7 @@
* @client: a #GSocketClient.
*
* Gets the socket type of the socket client.
+ *
* See g_socket_client_set_socket_type() for details.
*
* Returns: a #GSocketFamily
@@ -30622,6 +32642,7 @@
* @client: a #GSocketClient
*
* Gets the I/O timeout time for sockets created by @client.
+ *
* See g_socket_client_set_timeout() for details.
*
* Returns: the timeout in seconds
@@ -30646,6 +32667,7 @@
* @client: a #GSocketClient.
*
* Gets the TLS validation flags used creating TLS connections via
+ * @client.
*
* Returns: the TLS validation flags
* Since: 2.28
@@ -30656,6 +32678,7 @@
* g_socket_client_new:
*
* Creates a new #GSocketClient with the default options.
+ *
* Free the returned object with g_object_unref().
*
* Returns: a #GSocketClient.
@@ -30686,6 +32709,7 @@
* If this is set to something other than %G_SOCKET_FAMILY_INVALID
* then the sockets created by this object will be of the specified
* family.
+ *
* This might be useful for instance if you want to force the local
* connection to be an ipv4 socket, even though the address might
* be an ipv6 mapped to ipv4 address.
@@ -30702,6 +32726,7 @@
* Sets the local address of the socket client.
* The sockets created by this object will bound to the
* specified address (if not %NULL) before connecting.
+ *
* This is useful if you want to ensure that the local
* side of the connection is on a specific port, or on
* a specific interface.
@@ -30718,6 +32743,7 @@
* Sets the protocol of the socket client.
* The sockets created by this object will use of the specified
* protocol.
+ *
* If @protocol is %0 that means to use the default
* protocol for the socket family and type.
*
@@ -30733,6 +32759,7 @@
* Sets the socket type of the socket client.
* The sockets created by this object will be of the specified
* type.
+ *
* It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
* as GSocketClient is used for connection oriented services.
*
@@ -30747,6 +32774,7 @@
*
* Sets the I/O timeout for sockets created by @client. @timeout is a
* time in seconds, or 0 for no timeout (the default).
+ *
* The timeout value affects the initial connection attempt as well,
* so setting this may cause calls to g_socket_client_connect(), etc,
* to fail with %G_IO_ERROR_TIMED_OUT.
@@ -30763,6 +32791,7 @@
* Sets whether @client creates TLS (aka SSL) connections. If @tls is
* %TRUE, @client will wrap its connections in a #GTlsClientConnection
* and perform a TLS handshake when connecting.
+ *
* Note that since #GSocketClient must return a #GSocketConnection,
* but #GTlsClientConnection is not a #GSocketConnection, this
* actually wraps the resulting #GTlsClientConnection in a
@@ -30792,15 +32821,19 @@
* @error: #GError for error reporting, or %NULL to ignore.
*
* Closes the socket, shutting down any active connection.
+ *
* Closing a socket does not wait for all outstanding I/O operations
* to finish, so the caller should not rely on them to be guaranteed
* to complete even if the close returns with no error.
+ *
* Once the socket is closed, all other operations will return
* %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
* return an error.
+ *
* Sockets will be automatically closed when the last reference
* is dropped, but you might want to call this function to make sure
* resources are released as early as possible.
+ *
* Beware that due to the way that TCP works, it is possible for
* recently-sent data to be lost if either you close a socket while the
* %G_IO_IN condition is set, or else if the remote connection tries to
@@ -30831,6 +32864,7 @@
* The operations specified in @condition are checked for and masked
* against the currently-satisfied conditions on @socket. The result
* is returned.
+ *
* Note that on Windows, it is possible for an operation to return
* %G_IO_ERROR_WOULD_BLOCK even immediately after
* g_socket_condition_check() has claimed that the socket is ready for
@@ -30838,8 +32872,10 @@
* writing to the socket if it succeeds, it is generally better to
* simply try writing to the socket right away, and try again later if
* the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
+ *
* It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
* these conditions will always be set in the output if they are true.
+ *
* This call never blocks.
*
* Returns: the @GIOCondition mask of the current state
@@ -30856,6 +32892,7 @@
*
* Waits for @condition to become true on @socket. When the condition
* is met, %TRUE is returned.
+ *
* If @cancellable is cancelled before the condition is met, or if the
* socket has a timeout set and it is reached before the condition is
* met, then %FALSE is returned and @error, if non-%NULL, is set to
@@ -30875,17 +32912,20 @@
* @error: #GError for error reporting, or %NULL to ignore.
*
* Connect the socket to the specified remote address.
+ *
* For connection oriented socket this generally means we attempt to make
* a connection to the @address. For a connection-less socket it sets
* the default address for g_socket_send() and discards all incoming datagrams
* from other sources.
+ *
* Generally connection oriented sockets can only connect once, but
* connection-less sockets can connect multiple times to change the
* default address.
+ *
* If the connect call needs to do network I/O it will block, unless
* non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
* and the user can be notified of the connection finishing by waiting
- * for the G_IO_OUT condition. The result of the connection can then be
+ * for the G_IO_OUT condition. The result of the connection must then be
* checked with g_socket_check_connect_result().
*
* Returns: %TRUE if connected, %FALSE on error.
@@ -30911,6 +32951,7 @@
* Creates a #GSocketAddressEnumerator for @connectable that will
* return #GProxyAddress<!-- -->es for addresses that you must connect
* to via a proxy.
+ *
* If @connectable does not implement
* g_socket_connectable_proxy_enumerate(), this will fall back to
* calling g_socket_connectable_enumerate().
@@ -30925,6 +32966,7 @@
* @socket: a #GSocket
*
* Creates a #GSocketConnection subclass of the right type for
+ * @socket.
*
* Returns: (transfer full): a #GSocketConnection
* Since: 2.22
@@ -30939,6 +32981,7 @@
*
* Looks up the #GType to be used when creating socket connections on
* sockets with the specified @family, @type and @protocol_id.
+ *
* If no type is registered, the #GSocketConnection base type is returned.
*
* Returns: a #GType
@@ -30955,6 +32998,7 @@
*
* Looks up the #GType to be used when creating socket connections on
* sockets with the specified @family, @type and @protocol.
+ *
* If no type is registered, the #GSocketConnection base type is returned.
*
* Since: 2.22
@@ -30967,6 +33011,7 @@
* @error: #GError for error reporting, or %NULL to ignore.
*
* Try to get the local address of a socket connection.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GSocketAddress or %NULL on error.
@@ -30980,6 +33025,7 @@
* @error: #GError for error reporting, or %NULL to ignore.
*
* Try to get the remote address of a socket connection.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GSocketAddress or %NULL on error.
@@ -31008,8 +33054,10 @@
* @data: (array length=size) (element-type guint8): pointer to the message data
*
* Tries to deserialize a socket control message of a given
+ * @level and @type. This will ask all known (to GType) subclasses
* of #GSocketControlMessage if they can understand this kind
* of message and if so deserialize it into a #GSocketControlMessage.
+ *
* If there is no implementation for this kind of control message, %NULL
* will be returned.
*
@@ -31061,6 +33109,8 @@
*
* Converts the data in the message to bytes placed in the
* message.
+ *
+ * @data is guaranteed to have enough space to fit the size
* returned by g_socket_control_message_get_size() on this
* object.
*
@@ -31076,13 +33126,18 @@
*
* Creates a %GSource that can be attached to a %GMainContext to monitor
* for the availibility of the specified @condition on the socket.
+ *
* The callback on the source is of the #GSocketSourceFunc type.
+ *
* It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
* these conditions will always be reported output if they are true.
+ *
+ * @cancellable if not %NULL can be used to cancel the source, which will
* cause the source to trigger, reporting the current condition (which
* is likely 0 unless cancellation happened at the same time as a
* condition change). You can check for this in the callback using
* g_cancellable_is_cancelled().
+ *
* If @socket has a timeout set, and it is reached before @condition
* occurs, the source will then trigger anyway, reporting %G_IO_IN or
* %G_IO_OUT depending on @condition. However, @socket will have been
@@ -31114,13 +33169,16 @@
* Returns the credentials of the foreign process connected to this
* socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
* sockets).
+ *
* If this operation isn't supported on the OS, the method fails with
* the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
* by reading the %SO_PEERCRED option on the underlying socket.
+ *
* Other ways to obtain credentials from a foreign peer includes the
* #GUnixCredentialsMessage type and
* g_unix_connection_send_credentials() /
* g_unix_connection_receive_credentials() functions.
+ *
* that must be freed with g_object_unref().
*
* Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object
@@ -31186,6 +33244,7 @@
* Try to get the local address of a bound socket. This is only
* useful if the socket has been bound to a local address,
* either explicitly or implicitly when connecting.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GSocketAddress or %NULL on error.
@@ -31212,6 +33271,7 @@
*
* Try to get the remove address of a connected socket. This is only
* useful for connection oriented sockets that have been connected.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GSocketAddress or %NULL on error.
@@ -31272,8 +33332,10 @@
*
* Marks the socket as a server socket, i.e. a socket that is used
* to accept incoming requests using g_socket_accept().
+ *
* Before calling this the socket must be bound to a local address using
* g_socket_bind().
+ *
* To set the maximum amount of outstanding clients, use
* g_socket_set_listen_backlog().
*
@@ -31292,9 +33354,11 @@
* Blocks waiting for a client to connect to any of the sockets added
* to the listener. Returns a #GSocketConnection for the socket that was
* accepted.
+ *
* If @source_object is not %NULL it will be filled out with the source
* object specified when the corresponding socket or address was added
* to the listener.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -31312,6 +33376,7 @@
* @user_data: (closure): user data for the callback
*
* This is the asynchronous version of g_socket_listener_accept().
+ *
* When the operation is finished @callback will be
* called. You can then call g_socket_listener_accept_socket()
* to get the result of the operation.
@@ -31343,12 +33408,15 @@
*
* Blocks waiting for a client to connect to any of the sockets added
* to the listener. Returns the #GSocket that was accepted.
+ *
* If you want to accept the high-level #GSocketConnection, not a #GSocket,
* which is often the case, then you should use g_socket_listener_accept()
* instead.
+ *
* If @source_object is not %NULL it will be filled out with the source
* object specified when the corresponding socket or address was added
* to the listener.
+ *
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -31366,6 +33434,7 @@
* @user_data: (closure): user data for the callback
*
* This is the asynchronous version of g_socket_listener_accept_socket().
+ *
* When the operation is finished @callback will be
* called. You can then call g_socket_listener_accept_socket_finish()
* to get the result of the operation.
@@ -31401,19 +33470,23 @@
* Creates a socket of type @type and protocol @protocol, binds
* it to @address and adds it to the set of sockets we're accepting
* sockets from.
+ *
* Note that adding an IPv6 address, depending on the platform,
* may or may not result in a listener that also accepts IPv4
* connections. For more deterministic behavior, see
* g_socket_listener_add_inet_port().
+ *
+ * @source_object will be passed out in the various calls
* to accept to identify this particular source, which is
* useful if you're listening on multiple addresses and do
* different things depending on what address is connected to.
+ *
* If successful and @effective_address is non-%NULL then it will
* be set to the address that the binding actually occurred at. This
* is helpful for determining the port number that was used for when
+ * requesting a binding to port 0 (ie: "any port"). This address, if
* requested, belongs to the caller and must be freed.
*
- * Requesting a binding to port 0 (ie: "any port"). This address, if
* Returns: %TRUE on success, %FALSE on error.
* Since: 2.22
*/
@@ -31427,8 +33500,11 @@
*
* Listens for TCP connections on any available port number for both
* IPv6 and IPv4 (if each is available).
+ *
* This is useful if you need to have a socket for incoming connections
* but don't care about the specific port number.
+ *
+ * @source_object will be passed out in the various calls
* to accept to identify this particular source, which is
* useful if you're listening on multiple addresses and do
* different things depending on what address is connected to.
@@ -31448,6 +33524,8 @@
* Helper function for g_socket_listener_add_address() that
* creates a TCP/IP socket listening on IPv4 and IPv6 (if
* supported) on the specified port on all interfaces.
+ *
+ * @source_object will be passed out in the various calls
* to accept to identify this particular source, which is
* useful if you're listening on multiple addresses and do
* different things depending on what address is connected to.
@@ -31467,6 +33545,8 @@
* Adds @socket to the set of sockets that we try to accept
* new clients from. The socket must be bound to a local
* address and listened to.
+ *
+ * @source_object will be passed out in the various calls
* to accept to identify this particular source, which is
* useful if you're listening on multiple addresses and do
* different things depending on what address is connected to.
@@ -31504,6 +33584,7 @@
* @listen_backlog: an integer
*
* Sets the listen backlog on the sockets in the listener.
+ *
* See g_socket_set_listen_backlog() for details
*
* Since: 2.22
@@ -31520,14 +33601,17 @@
* Creates a new #GSocket with the defined family, type and protocol.
* If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
* for the family and type is used.
+ *
* The @protocol is a family and type specific int that specifies what
* kind of protocol to use. #GSocketProtocol lists several common ones.
* Many families only support one protocol, and use 0 for this, others
* support several and using 0 means to use the default protocol for
* the family and type.
+ *
* The protocol id is passed directly to the operating
* system, so you can use protocols not listed in #GSocketProtocol if you
* know the protocol number used for it.
+ *
* Free the returned object with g_object_unref().
*
* Returns: a #GSocket or %NULL on error.
@@ -31542,10 +33626,12 @@
*
* Creates a new #GSocket from a native file descriptor
* or winsock SOCKET handle.
+ *
* This reads all the settings from the file descriptor so that
* all properties should work. Note that the file descriptor
* will be set to non-blocking mode, independent on the blocking
* mode of the #GSocket.
+ *
* Free the returned object with g_object_unref().
*
* Returns: a #GSocket or %NULL on error.
@@ -31564,22 +33650,27 @@
* Receive data (up to @size bytes) from a socket. This is mainly used by
* connection-oriented sockets; it is identical to g_socket_receive_from()
* with @address set to %NULL.
+ *
* For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
* g_socket_receive() will always read either 0 or 1 complete messages from
* the socket. If the received message is too large to fit in @buffer, then
* the data beyond @size bytes will be discarded, without any explicit
* indication that this has occurred.
+ *
* For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
* number of bytes, up to @size. If more than @size bytes have been
* received, the additional data will be returned in future calls to
* g_socket_receive().
+ *
* If the socket is in blocking mode the call will block until there
* is some data to receive, the connection is closed, or there is an
* error. If there is no data available and the socket is in
* non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
* returned. To be notified when data is available, wait for the
* %G_IO_IN condition.
+ *
* On error -1 is returned and @error is set accordingly.
+ *
* the peer, or -1 on error
*
* Returns: Number of bytes read, or 0 if the connection was closed by
@@ -31597,9 +33688,13 @@
* @error: #GError for error reporting, or %NULL to ignore.
*
* Receive data (up to @size bytes) from a socket.
+ *
* If @address is non-%NULL then @address will be set equal to the
* source address of the received packet.
+ * @address is owned by the caller.
+ *
* See g_socket_receive() for additional information.
+ *
* the peer, or -1 on error
*
* Returns: Number of bytes read, or 0 if the connection was closed by
@@ -31622,15 +33717,23 @@
* Receive data from a socket. This is the most complicated and
* fully-featured version of this call. For easier use, see
* g_socket_receive() and g_socket_receive_from().
+ *
* If @address is non-%NULL then @address will be set equal to the
* source address of the received packet.
+ * @address is owned by the caller.
+ *
+ * @vector must point to an array of #GInputVector structs and
+ * @num_vectors must be the length of this array. These structs
* describe the buffers that received data will be scattered into.
* If @num_vectors is -1, then @vectors is assumed to be terminated
* by a #GInputVector with a %NULL buffer pointer.
+ *
* As a special case, if @num_vectors is 0 (in which case, @vectors
* may of course be %NULL), then a single byte is received and
* discarded. This is to facilitate the common practice of sending a
* single '\0' byte for the purposes of transferring ancillary data.
+ *
+ * @messages, if non-%NULL, will be set to point to a newly-allocated
* array of #GSocketControlMessage instances or %NULL if no such
* messages was received. These correspond to the control messages
* received from the kernel, one #GSocketControlMessage per message
@@ -31638,12 +33741,20 @@
* by the caller using g_free() after calling g_object_unref() on each
* element. If @messages is %NULL, any control messages received will
* be discarded.
+ *
+ * @num_messages, if non-%NULL, will be set to the number of control
* messages received.
+ *
* If both @messages and @num_messages are non-%NULL, then
+ * @num_messages gives the number of #GSocketControlMessage instances
+ * in @messages (ie: not including the %NULL terminator).
+ *
+ * @flags is an in/out parameter. The commonly available arguments
* for this are available in the #GSocketMsgFlags enum, but the
* values there are the same as the system values, and the flags
* are passed in as-is, so you can pass in system-specific flags too
* (and g_socket_receive_message() may pass system-specific flags out).
+ *
* As with g_socket_receive(), data may be discarded if @socket is
* %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
* provide enough buffer space to read a complete message. You can pass
@@ -31651,16 +33762,18 @@
* removing it from the receive queue, but there is no portable way to find
* out the length of the message other than by reading it into a
* sufficiently-large buffer.
+ *
* If the socket is in blocking mode the call will block until there
* is some data to receive, the connection is closed, or there is an
* error. If there is no data available and the socket is in
* non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
* returned. To be notified when data is available, wait for the
* %G_IO_IN condition.
+ *
* On error -1 is returned and @error is set accordingly.
+ *
* the peer, or -1 on error
*
- * In @messages (ie: not including the %NULL terminator).
* Returns: Number of bytes read, or 0 if the connection was closed by
* Since: 2.22
*/
@@ -31678,6 +33791,7 @@
* This behaves exactly the same as g_socket_receive(), except that
* the choice of blocking or non-blocking behavior is determined by
* the @blocking argument rather than by @socket's properties.
+ *
* the peer, or -1 on error
*
* Returns: Number of bytes read, or 0 if the connection was closed by
@@ -31696,6 +33810,7 @@
* Tries to send @size bytes from @buffer on the socket. This is
* mainly used by connection-oriented sockets; it is identical to
* g_socket_send_to() with @address set to %NULL.
+ *
* If the socket is in blocking mode the call will block until there is
* space for the data in the socket queue. If there is no space available
* and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
@@ -31704,7 +33819,9 @@
* %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
* notified of a %G_IO_OUT condition. (On Windows in particular, this is
* very common due to the way the underlying APIs work.)
+ *
* On error -1 is returned and @error is set accordingly.
+ *
* on error
*
* Returns: Number of bytes written (which may be less than @size), or -1
@@ -31727,21 +33844,30 @@
* Send data to @address on @socket. This is the most complicated and
* fully-featured version of this call. For easier use, see
* g_socket_send() and g_socket_send_to().
+ *
* If @address is %NULL then the message is sent to the default receiver
* (set by g_socket_connect()).
+ *
+ * @vectors must point to an array of #GOutputVector structs and
+ * @num_vectors must be the length of this array. (If @num_vectors is -1,
* then @vectors is assumed to be terminated by a #GOutputVector with a
* %NULL buffer pointer.) The #GOutputVector structs describe the buffers
* that the sent data will be gathered from. Using multiple
* #GOutputVector<!-- -->s is more memory-efficient than manually copying
* data from multiple sources into a single buffer, and more
* network-efficient than making multiple calls to g_socket_send().
+ *
+ * @messages, if non-%NULL, is taken to point to an array of @num_messages
* #GSocketControlMessage instances. These correspond to the control
* messages to be sent on the socket.
* If @num_messages is -1 then @messages is treated as a %NULL-terminated
* array.
+ *
+ * @flags modify how the message is sent. The commonly available arguments
* for this are available in the #GSocketMsgFlags enum, but the
* values there are the same as the system values, and the flags
* are passed in as-is, so you can pass in system-specific flags too.
+ *
* If the socket is in blocking mode the call will block until there is
* space for the data in the socket queue. If there is no space available
* and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
@@ -31750,7 +33876,9 @@
* %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
* notified of a %G_IO_OUT condition. (On Windows in particular, this is
* very common due to the way the underlying APIs work.)
+ *
* On error -1 is returned and @error is set accordingly.
+ *
* on error
*
* Returns: Number of bytes written (which may be less than @size), or -1
@@ -31770,7 +33898,9 @@
* Tries to send @size bytes from @buffer to @address. If @address is
* %NULL then the message is sent to the default receiver (set by
* g_socket_connect()).
+ *
* See g_socket_send() for additional information.
+ *
* on error
*
* Returns: Number of bytes written (which may be less than @size), or -1
@@ -31790,6 +33920,7 @@
* This behaves exactly the same as g_socket_send(), except that
* the choice of blocking or non-blocking behavior is determined by
* the @blocking argument rather than by @socket's properties.
+ *
* on error
*
* Returns: Number of bytes written (which may be less than @size), or -1
@@ -31829,6 +33960,7 @@
*
* Starts the service, i.e. start accepting connections
* from the added sockets when the mainloop runs.
+ *
* This call is threadsafe, so it may be called from a thread
* handling an incoming client request.
*
@@ -31842,6 +33974,7 @@
*
* Stops the service, i.e. stops accepting connections
* from the added sockets when the mainloop runs.
+ *
* This call is threadsafe, so it may be called from a thread
* handling an incoming client request.
*
@@ -31858,6 +33991,7 @@
* all operations block until they succeed or there is an error. In
* non-blocking mode all functions return results immediately or
* with a %G_IO_ERROR_WOULD_BLOCK error.
+ *
* All sockets are created in blocking mode. However, note that the
* platform level socket is always non-blocking, and blocking mode
* is a GSocket level feature.
@@ -31877,8 +34011,10 @@
* time passes with no data being exchanged. If the system is unable to
* verify the presence of the remote endpoint, it will automatically close
* the connection.
+ *
* This option is only functional on certain kinds of sockets. (Notably,
* %G_SOCKET_PROTOCOL_TCP sockets.)
+ *
* The exact time between pings is system- and protocol-dependent, but will
* normally be at least two hours. Most commonly, you would set this flag
* on a server socket if you want to allow clients to remain idle for long
@@ -31898,6 +34034,7 @@
* when listening on this socket. If more clients than this are
* connecting to the socket and the application is not handling them
* on time then the new connections will be refused.
+ *
* Note that this must be called before g_socket_listen() and has no
* effect if called after that.
*
@@ -31912,17 +34049,22 @@
*
* Sets the time in seconds after which I/O operations on @socket will
* time out if they have not yet completed.
+ *
* On a blocking socket, this means that any blocking #GSocket
* operation will time out after @timeout seconds of inactivity,
* returning %G_IO_ERROR_TIMED_OUT.
+ *
* On a non-blocking socket, calls to g_socket_condition_wait() will
* also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
* created with g_socket_create_source() will trigger after
+ * @timeout seconds of inactivity, with the requested condition
* set, at which point calling g_socket_receive(), g_socket_send(),
* g_socket_check_connect_result(), etc, will fail with
* %G_IO_ERROR_TIMED_OUT.
+ *
* If @timeout is 0 (the default), operations will never time out
* on their own.
+ *
* Note that if an I/O operation is interrupted by a signal, this may
* cause the timeout to be reset.
*
@@ -31938,11 +34080,15 @@
* @error: #GError for error reporting, or %NULL to ignore.
*
* Shut down part of a full-duplex connection.
+ *
* If @shutdown_read is %TRUE then the recieving side of the connection
* is shut down, and further reading is disallowed.
+ *
* If @shutdown_write is %TRUE then the sending side of the connection
* is shut down, and further writing is disallowed.
+ *
* It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
+ *
* One example where this is used is graceful disconnect for TCP connections
* where you close the sending side, then wait for the other side to close
* the connection, thus ensuring that the other side saw all sent data.
@@ -31957,10 +34103,12 @@
* @socket: a #GSocket
*
* Checks if a socket is capable of speaking IPv4.
+ *
* IPv4 sockets are capable of speaking IPv4. On some operating systems
* and under some combinations of circumstances IPv6 sockets are also
* capable of speaking IPv4. See RFC 3493 section 3.7 for more
* information.
+ *
* No other types of sockets are currently considered as being capable
* of speaking IPv4.
*
@@ -32060,6 +34208,7 @@
* @weight: the target's weight
*
* Creates a new #GSrvTarget with the given parameters.
+ *
* You should not need to use this; normally #GSrvTarget<!-- -->s are
* created by #GResolver.
*
@@ -32088,6 +34237,7 @@
* This enabled graceful disconnects on close. A graceful disconnect
* means that we signal the receiving end that the connection is terminated
* and wait for it to close the connection before closing the connection.
+ *
* A graceful disconnect means that we can be sure that we successfully sent
* all the outstanding data to the other end, or get an error reported.
* However, it also means we have to wait for all the data to reach the
@@ -32126,6 +34276,7 @@
* @iconname: name of icon to append to list of icons from within @icon.
*
* Append a name to the list of icons from within @icon.
+ *
* <note><para>
* Note that doing so invalidates the hash computed by prior calls
* to g_icon_hash().
@@ -32170,6 +34321,7 @@
*
* Creates a new themed icon for @iconname, and all the names
* that can be created by shortening @iconname at '-' characters.
+ *
* In the following example, @icon1 and @icon2 are equivalent:
* |[
* const char *names[] = {
@@ -32178,6 +34330,7 @@
* "gnome-dev",
* "gnome"
* };
+ *
* icon1 = g_themed_icon_new_from_names (names, 4);
* icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
* ]|
@@ -32192,6 +34345,7 @@
* @iconname: name of icon to prepend to list of icons from within @icon.
*
* Prepend a name to the list of icons from within @icon.
+ *
* <note><para>
* Note that doing so invalidates the hash computed by prior calls
* to g_icon_hash().
@@ -32218,15 +34372,17 @@
*
* Gets the singleton instance of the #GTimeZoneMonitor class, creating
* it if required.
+ *
* You should call g_object_unref() on the result when you no longer
* need it. Be aware, though, that this will not destroy the instance,
* so if you connected to the changed signal, you are required to
* disconnect from it for yourself.
+ *
* There is only one instance of #GTimeZoneMonitor and it dispatches its
* signals via the default #GMainContext. There is no way to create an
* instance that will dispatch signals using a different context.
*
- * Returns: a reference to the #GTimeZoneMonitor.
+ * Returns: (transfer full): a reference to the #GTimeZoneMonitor.
*/
@@ -32235,6 +34391,7 @@
* @backend: the #GTlsBackend
*
* Gets the #GType of @backend's #GTlsCertificate implementation.
+ *
* implementation.
*
* Returns: the #GType of @backend's #GTlsCertificate
@@ -32247,6 +34404,7 @@
* @backend: the #GTlsBackend
*
* Gets the #GType of @backend's #GTlsClientConnection implementation.
+ *
* implementation.
*
* Returns: the #GType of @backend's #GTlsClientConnection
@@ -32265,10 +34423,35 @@
/**
+ * g_tls_backend_get_default_database:
+ * @backend: the #GTlsBackend
+ *
+ * Gets the default #GTlsDatabase used to verify TLS connections.
+ *
+ * unreffed when done.
+ *
+ * Returns: (transfer full): the default database, which should be
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_backend_get_file_database_type:
+ * @backend: the #GTlsBackend
+ *
+ * Gets the #GTyep of @backend's #GTlsFileDatabase implementation.
+ *
+ * Returns: the #GType of backend's #GTlsFileDatabase implementation.
+ * Since: 2.30
+ */
+
+
+/**
* g_tls_backend_get_server_connection_type:
* @backend: the #GTlsBackend
*
* Gets the #GType of @backend's #GTlsServerConnection implementation.
+ *
* implementation.
*
* Returns: the #GType of @backend's #GTlsServerConnection
@@ -32293,6 +34476,7 @@
* @cert: a #GTlsCertificate
*
* Gets the #GTlsCertificate representing @cert's issuer, if known
+ *
* or %NULL if @cert is self-signed or signed with an unknown
* certificate.
*
@@ -32311,6 +34495,7 @@
* return %NULL and set @error. If @file does not contain any
* PEM-encoded certificates, this will return an empty list and not
* set @error.
+ *
* #GList containing #GTlsCertificate objects. You must free the list
* and its contents when you are done with it.
*
@@ -32325,6 +34510,7 @@
* @error: #GError for error reporting, or %NULL to ignore.
*
* Creates a #GTlsCertificate from the PEM-encoded data in @file. If
+ * @file cannot be read or parsed, the function will return %NULL and
* set @error. Otherwise, this behaves like g_tls_certificate_new().
*
* Returns: the new certificate, or %NULL on error
@@ -32357,6 +34543,7 @@
* Creates a new #GTlsCertificate from the PEM-encoded data in @data.
* If @data includes both a certificate and a private key, then the
* returned certificate will include the private key data as well.
+ *
* If @data includes multiple certificates, only the first one will be
* parsed.
*
@@ -32376,14 +34563,18 @@
* certificate outside the context of making a connection, or to
* check a certificate against a CA that is not part of the system
* CA database.
+ *
* If @identity is not %NULL, @cert's name(s) will be compared against
* it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
* value if it does not match. If @identity is %NULL, that bit will
* never be set in the return value.
+ *
* If @trusted_ca is not %NULL, then @cert (or one of the certificates
* in its chain) must be signed by it, or else
* %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
+ * @trusted_ca is %NULL, that bit will never be set in the return
* value.
+ *
* (All other #GTlsCertificateFlags values will always be set or unset
* as appropriate.)
*
@@ -32400,8 +34591,10 @@
* that the server will accept certificates from. This will be set
* during the TLS handshake if the server requests a certificate.
* Otherwise, it will be %NULL.
+ *
* Each item in the list is a #GByteArray which contains the complete
* subject DN of the certificate authority.
+ *
* CA DNs. You should unref each element with g_byte_array_unref() and then
* the free the list with g_list_free().
*
@@ -32415,6 +34608,7 @@
* @conn: the #GTlsClientConnection
*
* Gets @conn's expected server identity
+ *
* expected server identity, or %NULL if the expected identity is not
* known.
*
@@ -32457,7 +34651,7 @@
* must have pollable input and output streams) which is assumed to
* communicate with the server identified by @server_identity.
*
- * Returns: the new #GTlsClientConnection, or %NULL on error
+ * Returns: (transfer full): the new #GTlsClientConnection, or %NULL on error
* Since: 2.28
*/
@@ -32512,6 +34706,7 @@
*
* Used by #GTlsConnection implementations to emit the
* #GTlsConnection::accept-certificate signal.
+ *
* %TRUE to accept @peer_cert
*
* Returns: %TRUE if one of the signal handlers has returned
@@ -32532,6 +34727,31 @@
/**
+ * g_tls_connection_get_database:
+ * @conn: a #GTlsConnection
+ *
+ * Gets the certificate database that @conn uses to verify
+ * peer certificates. See g_tls_connection_set_database().
+ *
+ * Returns: (transfer none): the certificate database that @conn uses or %NULL
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_connection_get_interaction:
+ * @conn: a connection
+ *
+ * Get the object that will be used to interact with the user. It will be used
+ * for things like prompting the user for passwords. If %NULL is returned, then
+ * no user interaction will occur for this connection.
+ *
+ * Returns: (transfer none): The interaction object.
+ * Since: 2.30
+ */
+
+
+/**
* g_tls_connection_get_peer_certificate:
* @conn: a #GTlsConnection
*
@@ -32576,6 +34796,7 @@
* Tests whether or not @conn expects a proper TLS close notification
* when the connection is closed. See
* g_tls_connection_set_require_close_notify() for details.
+ *
* notification.
*
* Returns: %TRUE if @conn requires a proper TLS close
@@ -32591,7 +34812,7 @@
* peer certificates. See g_tls_connection_set_use_system_certdb().
*
* Returns: whether @conn uses the system certificate database
- * Since: 2.28
+ * Deprecated: 2.30: Use g_tls_connection_get_database() instead
*/
@@ -32602,6 +34823,7 @@
* @error: a #GError, or %NULL
*
* Attempts a TLS handshake on @conn.
+ *
* On the client side, it is never necessary to call this method;
* although the connection needs to perform a handshake after
* connecting (or after sending a "STARTTLS"-type command) and may
@@ -32613,11 +34835,13 @@
* just immediately trying to write to @conn's output stream, in which
* case if it fails, it may not be possible to tell if it failed
* before or after completing the handshake).
+ *
* Likewise, on the server side, although a handshake is necessary at
* the beginning of the communication, you do not need to call this
* function explicitly unless you want clearer error reporting.
* However, you may call g_tls_connection_handshake() later on to
* renegotiate parameters (encryption methods, etc) with the client.
+ *
* #GTlsConnection::accept_certificate may be emitted during the
* handshake.
*
@@ -32649,6 +34873,7 @@
*
* Finish an asynchronous TLS handshake operation. See
* g_tls_connection_handshake() for more information.
+ *
* case @error will be set.
*
* Returns: %TRUE on success, %FALSE on failure, in which
@@ -32665,6 +34890,7 @@
* during the TLS handshake. For a #GTlsServerConnection, it is
* mandatory to set this, and that will normally be done at construct
* time.
+ *
* For a #GTlsClientConnection, this is optional. If a handshake fails
* with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
* requires a certificate, and if you try connecting again, you should
@@ -32672,6 +34898,7 @@
* g_tls_client_connection_get_accepted_cas() on the failed connection
* to get a list of Certificate Authorities that the server will
* accept certificates from.
+ *
* (It is also possible that a server will allow the connection with
* or without a certificate; in that case, if you don't provide a
* certificate, you can tell that the server requested one by the fact
@@ -32683,21 +34910,58 @@
/**
+ * g_tls_connection_set_database:
+ * @conn: a #GTlsConnection
+ * @database: a #GTlsDatabase
+ *
+ * Sets the certificate database that is used to verify peer certificates.
+ * This is set to the default database by default. See
+ * g_tls_backend_get_default_database(). If set to %NULL, then
+ * peer certificate validation will always set the
+ * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
+ * #GTlsConnection::accept-certificate will always be emitted on
+ * client-side connections, unless that bit is not set in
+ * #GTlsClientConnection:validation-flags).
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_connection_set_interaction:
+ * @conn: a connection
+ * @interaction: (allow-none): an interaction object, or %NULL
+ *
+ * Set the object that will be used to interact with the user. It will be used
+ * for things like prompting the user for passwords.
+ *
+ * The @interaction argument will normally be a derived subclass of
+ * #GTlsInteraction. %NULL can also be provided if no user interaction
+ * should occur for this connection.
+ *
+ * Since: 2.30
+ */
+
+
+/**
* g_tls_connection_set_rehandshake_mode:
* @conn: a #GTlsConnection
* @mode: the rehandshaking mode
*
* Sets how @conn behaves with respect to rehandshaking requests.
+ *
* %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
* rehandshake after the initial handshake is complete. (For a client,
* this means it will refuse rehandshake requests from the server, and
* for a server, this means it will close the connection with an error
* if the client attempts to rehandshake.)
+ *
* %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
* rehandshake only if the other end of the connection supports the
* TLS <literal>renegotiation_info</literal> extension. This is the
* default behavior, but means that rehandshaking will not work
* against older implementations that do not support that extension.
+ *
* %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
* rehandshaking even without the
* <literal>renegotiation_info</literal> extension. On the server side
@@ -32721,6 +34985,7 @@
* %G_TLS_ERROR_EOF error if the connection is closed without proper
* notification (since this may indicate a network error, or
* man-in-the-middle attack).
+ *
* In some protocols, the application will know whether or not the
* connection was closed cleanly based on application-level data
* (because the application-level data includes a length field, or is
@@ -32732,6 +34997,7 @@
* will show up as a 0-length read, as in a non-TLS
* #GSocketConnection, and it is up to the application to check that
* the data has been fully received.
+ *
* Note that this only affects the behavior when the peer closes the
* connection; when the application calls g_io_stream_close() itself
* on @conn, this will send a close notification regardless of the
@@ -32756,7 +35022,284 @@
* client-side connections, unless that bit is not set in
* #GTlsClientConnection:validation-flags).
*
- * Since: 2.28
+ * Deprecated: 2.30: Use g_tls_connection_set_database() instead
+ */
+
+
+/**
+ * g_tls_database_create_certificate_handle:
+ * @self: a #GTlsDatabase
+ * @certificate: certificate for which to create a handle.
+ *
+ * Create a handle string for the certificate. The database will only be able
+ * to create a handle for certificates that originate from the database. In
+ * cases where the database cannot create a handle for a certificate, %NULL
+ * will be returned.
+ *
+ * This handle should be stable across various instances of the application,
+ * and between applications. If a certificate is modified in the database,
+ * then it is not guaranteed that this handle will continue to point to it.
+ *
+ * Returns: (allow-none): a newly allocated string containing the handle.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_lookup_certificate_for_handle:
+ * @self: a #GTlsDatabase
+ * @handle: a certificate handle
+ * @interaction: (allow-none): used to interact with the user if necessary
+ * @flags: Flags which affect the lookup.
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: (allow-none): a #GError, or %NULL
+ *
+ * Lookup a certificate by its handle.
+ *
+ * The handle should have been created by calling g_tls_database_create_handle()
+ * on a #GTlsDatabase object of the same TLS backend. The handle is designed
+ * to remain valid across instantiations of the database.
+ *
+ * If the handle is no longer valid, or does not point to a certificate in
+ * this database, then %NULL will be returned.
+ *
+ * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
+ * the lookup operation asynchronously.
+ *
+ * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
+ *
+ * Returns: (transfer full) (allow-none): a newly allocated
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_lookup_certificate_for_handle_async:
+ * @self: a #GTlsDatabase
+ * @handle: a certificate handle
+ * @interaction: (allow-none): used to interact with the user if necessary
+ * @flags: Flags which affect the lookup.
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: callback to call when the operation completes
+ * @user_data: the data to pass to the callback function
+ *
+ * Asynchronously lookup a certificate by its handle in the database. See
+ * g_tls_database_lookup_handle() for more information.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_lookup_certificate_for_handle_finish:
+ * @self: a #GTlsDatabase
+ * @result: a #GAsyncResult.
+ * @error: a #GError pointer, or %NULL
+ *
+ * Finish an asynchronous lookup of a certificate by its handle. See
+ * g_tls_database_lookup_handle() for more information.
+ *
+ * If the handle is no longer valid, or does not point to a certificate in
+ * this database, then %NULL will be returned.
+ *
+ * Use g_object_unref() to release the certificate.
+ *
+ * Returns: (transfer full): a newly allocated #GTlsCertificate object.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_lookup_certificate_issuer:
+ * @self: a #GTlsDatabase
+ * @certificate: a #GTlsCertificate
+ * @interaction: (allow-none): used to interact with the user if necessary
+ * @flags: flags which affect the lookup operation
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: (allow-none): a #GError, or %NULL
+ *
+ * Lookup the issuer of @certificate in the database.
+ *
+ * The %issuer property
+ * of @certificate is not modified, and the two certificates are not hooked
+ * into a chain.
+ *
+ * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
+ * the lookup operation asynchronously.
+ *
+ * or %NULL. Use g_object_unref() to release the certificate.
+ *
+ * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_lookup_certificate_issuer_async:
+ * @self: a #GTlsDatabase
+ * @certificate: a #GTlsCertificate
+ * @interaction: (allow-none): used to interact with the user if necessary
+ * @flags: flags which affect the lookup operation
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: callback to call when the operation completes
+ * @user_data: the data to pass to the callback function
+ *
+ * Asynchronously lookup the issuer of @certificate in the database. See
+ * g_tls_database_lookup_certificate_issuer() for more information.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_lookup_certificate_issuer_finish:
+ * @self: a #GTlsDatabase
+ * @result: a #GAsyncResult.
+ * @error: a #GError pointer, or %NULL
+ *
+ * Finish an asynchronous lookup issuer operation. See
+ * g_tls_database_lookup_certificate_issuer() for more information.
+ *
+ * or %NULL. Use g_object_unref() to release the certificate.
+ *
+ * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_lookup_certificates_issued_by:
+ * @self: a #GTlsDatabase
+ * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
+ * @interaction: (allow-none): used to interact with the user if necessary
+ * @flags: Flags which affect the lookup operation.
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: (allow-none): a #GError, or %NULL
+ *
+ * Lookup certificates issued by this issuer in the database.
+ *
+ * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
+ * the lookup operation asynchronously.
+ *
+ * Use g_object_unref() on each certificate, and g_list_free() on the release the list.
+ *
+ * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_lookup_certificates_issued_by_async:
+ * @self: a #GTlsDatabase
+ * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
+ * @interaction: (allow-none): used to interact with the user if necessary
+ * @flags: Flags which affect the lookup operation.
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: callback to call when the operation completes
+ * @user_data: the data to pass to the callback function
+ *
+ * Asynchronously lookup certificates issued by this issuer in the database. See
+ * g_tls_database_lookup_certificates_issued_by() for more information.
+ *
+ * The database may choose to hold a reference to the issuer byte array for the duration
+ * of of this asynchronous operation. The byte array should not be modified during
+ * this time.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_lookup_certificates_issued_by_finish:
+ * @self: a #GTlsDatabase
+ * @result: a #GAsyncResult.
+ * @error: a #GError pointer, or %NULL
+ *
+ * Finish an asynchronous lookup of certificates. See
+ * g_tls_database_lookup_certificates_issued_by() for more information.
+ *
+ * Use g_object_unref() on each certificate, and g_list_free() on the release the list.
+ *
+ * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_verify_chain:
+ * @self: a #GTlsDatabase
+ * @chain: a #GTlsCertificate chain
+ * @purpose: the purpose that this certificate chain will be used for.
+ * @identity: (allow-none): the expected peer identity
+ * @interaction: (allow-none): used to interact with the user if necessary
+ * @flags: additional verify flags
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @error: (allow-none): a #GError, or %NULL
+ *
+ * Verify's a certificate chain after looking up and adding any missing
+ * certificates to the chain.
+ *
+ * @chain is a chain of #GTlsCertificate objects each pointing to the next
+ * certificate in the chain by its %issuer property. The chain may initially
+ * consist of one or more certificates. After the verification process is
+ * complete, @chain may be modified by adding missing certificates, or removing
+ * extra certificates. If a certificate anchor was found, then it is added to
+ * the @chain.
+ *
+ * @purpose describes the purpose (or usage) for which the certificate
+ * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
+ * which means that the certificate is being used to authenticate a server
+ * (and we are acting as the client).
+ *
+ * The @identity is used to check for pinned certificates (trust exceptions)
+ * in the database. These will override the normal verification process on a
+ * host by host basis.
+ *
+ * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
+ * used.
+ *
+ * This function can block, use g_tls_database_verify_chain_async() to perform
+ * the verification operation asynchronously.
+ *
+ * result of verification.
+ *
+ * Returns: the appropriate #GTlsCertificateFlags which represents the
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_verify_chain_async:
+ * @self: a #GTlsDatabase
+ * @chain: a #GTlsCertificate chain
+ * @purpose: the purpose that this certificate chain will be used for.
+ * @identity: (allow-none): the expected peer identity
+ * @interaction: (allow-none): used to interact with the user if necessary
+ * @flags: additional verify flags
+ * @cancellable: (allow-none): a #GCancellable, or %NULL
+ * @callback: callback to call when the operation completes
+ * @user_data: the data to pass to the callback function
+ *
+ * Asynchronously verify's a certificate chain after looking up and adding
+ * any missing certificates to the chain. See g_tls_database_verify_chain()
+ * for more information.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_database_verify_chain_finish:
+ * @self: a #GTlsDatabase
+ * @result: a #GAsyncResult.
+ * @error: a #GError pointer, or %NULL
+ *
+ * Finish an asynchronous verify chain operation. See
+ * g_tls_database_verify_chain() for more information. *
+ * result of verification.
+ *
+ * Returns: the appropriate #GTlsCertificateFlags which represents the
+ * Since: 2.30
*/
@@ -32771,6 +35314,210 @@
/**
+ * g_tls_file_database_new:
+ * @anchors: filename of anchor certificate authorities.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Creates a new #GTlsFileDatabase which uses anchor certificate authorities
+ * in @anchors to verify certificate chains.
+ *
+ * The certificates in @anchors must be PEM encoded.
+ *
+ * Returns: (transfer full): the new #GTlsFileDatabase, or %NULL on error
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_interaction_ask_password:
+ * @interaction: a #GTlsInteraction object
+ * @password: a #GTlsPassword object
+ *
+ * This function is normally called by #GTlsConnection or #GTlsDatabase to
+ * ask the user for a password.
+ *
+ * Derived subclasses usually implement a password prompt, although they may
+ * also choose to provide a password from elsewhere. The @password value will
+ * be filled in and then @callback will be called. Alternatively the user may
+ * abort this password request, which will usually abort the TLS connection.
+ *
+ * Returns: The status of the ask password interaction.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_interaction_ask_password_async:
+ * @interaction: a #GTlsInteraction object
+ * @password: a #GTlsPassword object
+ * @callback: will be called when the interaction completes
+ * @user_data: (allow-none): data to pass to the @callback
+ *
+ * This function is normally called by #GTlsConnection or #GTlsDatabase to
+ * ask the user for a password.
+ *
+ * Derived subclasses usually implement a password prompt, although they may
+ * also choose to provide a password from elsewhere. The @password value will
+ * be filled in and then @callback will be called. Alternatively the user may
+ * abort this password request, which will usually abort the TLS connection.
+ *
+ * The @callback will be invoked on thread-default main context of the thread
+ * that called this function. The @callback should call
+ * g_tls_interaction_ask_password_finish() to get the status of the user
+ * interaction.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_interaction_ask_password_finish:
+ * @interaction: a #GTlsInteraction object
+ * @result: the result passed to the callback
+ *
+ * Complete an ask password user interaction request. This should be once
+ * the g_tls_interaction_ask_password() completion callback is called.
+ *
+ * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
+ * to g_tls_interaction_ask_password() will have its password filled in.
+ *
+ * Returns: The status of the ask password interaction.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_password_get_description:
+ * @password: a #GTlsPassword object
+ *
+ * Get a description string about what the password will be used for.
+ *
+ * Returns: The description of the password.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_password_get_flags:
+ * @password: a #GTlsPassword object
+ *
+ * Get flags about the password.
+ *
+ * Returns: The flags about the password.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_password_get_value:
+ * @password: a #GTlsPassword object
+ * @length: (allow-none): location to place the length of the password.
+ *
+ * Get the password value. If @length is not %NULL then it will be filled
+ * in with the length of the password value.
+ *
+ * Returns: The password value owned by the password object.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_password_get_warning:
+ * @password: a #GTlsPassword object
+ *
+ * Get a user readable translated warning. Usually this warning is a
+ * representation of the password flags returned from
+ * g_tls_password_get_flags().
+ *
+ * Returns: The warning.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_password_new:
+ * @flags: the password flags
+ * @description: description of what the password is for
+ *
+ * Create a new #GTlsPassword object.
+ *
+ * Returns: (transfer full): The newly allocated password object
+ */
+
+
+/**
+ * g_tls_password_set_description:
+ * @password: a #GTlsPassword object
+ * @description: The description of the password
+ *
+ * Set a description string about what the password will be used for.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_password_set_flags:
+ * @password: a #GTlsPassword object
+ * @flags: The flags about the password
+ *
+ * Set flags about the password.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_password_set_value:
+ * @password: a #GTlsPassword object
+ * @value: the new password value
+ * @length: the length of the password, or -1
+ *
+ * Set the value for this password. The @value will be copied by the password
+ * object.
+ *
+ * Specify the @length, for a non-null-terminated password. Pass -1 as
+ * @length if using a null-terminated password, and @length will be calculated
+ * automatically.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_password_set_value_full:
+ * @password: a #GTlsPassword object
+ * @value: the value for the password
+ * @length: the length of the password, or -1
+ * @destroy: (allow-none): a function to use to free the password.
+ *
+ * Provide the value for this password.
+ *
+ * The @value will be owned by the password object, and later freed using
+ * the @destroy function callback.
+ *
+ * Specify the @length, for a non-null-terminated password. Pass -1 as
+ * @length if using a null-terminated password, and @length will be calculated
+ * automatically.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_tls_password_set_warning:
+ * @password: a #GTlsPassword object
+ * @warning: The user readable warning
+ *
+ * Set a user readable translated warning. Usually this warning is a
+ * representation of the password flags returned from
+ * g_tls_password_get_flags().
+ *
+ * Since: 2.30
+ */
+
+
+/**
* g_tls_server_connection_new:
* @base_io_stream: the #GIOStream to wrap
* @certificate: (allow-none): the default server certificate, or %NULL
@@ -32779,7 +35526,7 @@
* Creates a new #GTlsServerConnection wrapping @base_io_stream (which
* must have pollable input and output streams).
*
- * Returns: the new #GTlsServerConnection, or %NULL on error
+ * Returns: (transfer full): the new #GTlsServerConnection, or %NULL on error
* Since: 2.28
*/
@@ -32841,11 +35588,14 @@
* Receives credentials from the sending end of the connection. The
* sending end has to call g_unix_connection_send_credentials() (or
* similar) for this to work.
+ *
* As well as reading the credentials this also reads (and discards) a
* single byte from the stream, as this is required for credentials
* passing to work on some implementations.
+ *
* Other ways to exchange credentials with a foreign peer includes the
* #GUnixCredentialsMessage type and g_socket_get_credentials() function.
+ *
* g_object_unref()), %NULL if @error is set.
*
* Returns: (transfer full): Received credentials on success (free with
@@ -32862,6 +35612,7 @@
* Receives a file descriptor from the sending end of the connection.
* The sending end has to call g_unix_connection_send_fd() for this
* to work.
+ *
* As well as reading the fd this also reads a single byte from the
* stream, as this is required for fd passing to work on some
* implementations.
@@ -32881,9 +35632,11 @@
* of the connection. The receiving end has to call
* g_unix_connection_receive_credentials() (or similar) to accept the
* credentials.
+ *
* As well as sending the credentials this also writes a single NUL
* byte to the stream, as this is required for credentials passing to
* work on some implementations.
+ *
* Other ways to exchange credentials with a foreign peer includes the
* #GUnixCredentialsMessage type and g_socket_get_credentials() function.
*
@@ -32902,6 +35655,7 @@
* Passes a file descriptor to the receiving side of the
* connection. The receiving end has to call g_unix_connection_receive_fd()
* to accept the file descriptor.
+ *
* As well as sending the fd this also writes a single byte to the
* stream, as this is required for fd passing to work on some
* implementations.
@@ -32960,14 +35714,18 @@
* @error: a #GError pointer
*
* Adds a file descriptor to @list.
+ *
* The file descriptor is duplicated using dup(). You keep your copy
* of the descriptor and the copy contained in @list will be closed
* when @list is finalized.
+ *
* A possible cause of failure is exceeding the per-process or
* system-wide file descriptor limit.
+ *
* The index of the file descriptor in the list is returned. If you use
* this index with g_unix_fd_list_get() then you will receive back a
* duplicated copy of the same file descriptor.
+ *
* (and @error is set)
*
* Returns: the index of the appended fd in case of success, else -1
@@ -32982,11 +35740,15 @@
* @error: a #GError pointer
*
* Gets a file descriptor out of @list.
+ *
+ * @index_ specifies the index of the file descriptor to get. It is a
* programmer error for @index_ to be out of range; see
* g_unix_fd_list_get_length().
+ *
* The file descriptor is duplicated using dup() and set as
* close-on-exec before being returned. You must call close() on it
* when you are done.
+ *
* A possible cause of failure is exceeding the per-process or
* system-wide file descriptor limit.
*
@@ -32999,9 +35761,9 @@
* g_unix_fd_list_get_length:
* @list: a #GUnixFDList
*
+ * Gets the length of @list (ie: the number of file descriptors
* contained within).
*
- * Gets the length of @list (ie: the number of file descriptors
* Returns: the length of @list
* Since: 2.24
*/
@@ -33023,9 +35785,12 @@
* @n_fds: the length of #fds, or -1
*
* Creates a new #GUnixFDList containing the file descriptors given in
+ * @fds. The file descriptors become the property of the new list and
* may no longer be used by the caller. The array itself is owned by
* the caller.
+ *
* Each file descriptor in the array should be set to close-on-exec.
+ *
* If @n_fds is -1 then @fds must be terminated with -1.
*
* Returns: a new #GUnixFDList
@@ -33040,14 +35805,18 @@
*
* Returns the array of file descriptors that is contained in this
* object.
+ *
* After this call, the descriptors remain the property of @list. The
* caller must not close them and must not free the array. The array is
* valid only until @list is changed in any way.
+ *
* If @length is non-%NULL then it is set to the number of file
* descriptors in the returned array. The returned array is also
* terminated with -1.
+ *
* This function never returns %NULL. In case there are no file
* descriptors contained in @list, an empty array is returned.
+ *
* descriptors
*
* Returns: (array length=length) (transfer none): an array of file
@@ -33062,17 +35831,23 @@
*
* Returns the array of file descriptors that is contained in this
* object.
+ *
* After this call, the descriptors are no longer contained in
+ * @list. Further calls will return an empty list (unless more
* descriptors have been added).
+ *
* The return result of this function must be freed with g_free().
* The caller is also responsible for closing all of the file
* descriptors. The file descriptors in the array are set to
* close-on-exec.
+ *
* If @length is non-%NULL then it is set to the number of file
* descriptors in the returned array. The returned array is also
* terminated with -1.
+ *
* This function never returns %NULL. In case there are no file
* descriptors contained in @list, an empty array is returned.
+ *
* descriptors
*
* Returns: (array length=length) (transfer full): an array of file
@@ -33087,9 +35862,11 @@
* @error: a #GError pointer
*
* Adds a file descriptor to @message.
+ *
* The file descriptor is duplicated using dup(). You keep your copy
* of the descriptor and the copy contained in @message will be closed
* when @message is finalized.
+ *
* A possible cause of failure is exceeding the per-process or
* system-wide file descriptor limit.
*
@@ -33140,16 +35917,22 @@
*
* Returns the array of file descriptors that is contained in this
* object.
+ *
* After this call, the descriptors are no longer contained in
+ * @message. Further calls will return an empty list (unless more
* descriptors have been added).
+ *
* The return result of this function must be freed with g_free().
* The caller is also responsible for closing all of the file
* descriptors.
+ *
* If @length is non-%NULL then it is set to the number of file
* descriptors in the returned array. The returned array is also
* terminated with -1.
+ *
* This function never returns %NULL. In case there are no file
* descriptors contained in @message, an empty array is returned.
+ *
* descriptors
*
* Returns: (array length=length) (transfer full): an array of file
@@ -33186,6 +35969,7 @@
* @close_fd: %TRUE to close the file descriptor when done
*
* Creates a new #GUnixInputStream for the given @fd.
+ *
* If @close_fd is %TRUE, the file descriptor will be closed
* when the stream is closed.
*
@@ -33213,6 +35997,7 @@
* OS. This is primarily used for hiding mountable and mounted volumes
* that only are used in the OS and has little to no relevance to the
* casual user.
+ *
* of the OS.
*
* Returns: %TRUE if @mount_path is considered an implementation detail
@@ -33238,6 +36023,7 @@
* @mount2: second #GUnixMountEntry to compare.
*
* Compares two unix mounts.
+ *
* or less than @mount2, respectively.
*
* Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
@@ -33308,6 +36094,7 @@
*
* Guesses the name of a Unix mount.
* The result is a translated string.
+ *
* be freed with g_free()
*
* Returns: A newly allocated string that must
@@ -33374,6 +36161,7 @@
* @mount2: a #GUnixMount.
*
* Compares two unix mount points.
+ *
* or less than @mount2, respectively.
*
* Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
@@ -33444,6 +36232,7 @@
*
* Guesses the name of a Unix mount point.
* The result is a translated string.
+ *
* be freed with g_free()
*
* Returns: A newly allocated string that must
@@ -33498,6 +36287,7 @@
* If @time_read is set, it will be filled with the mount timestamp,
* allowing for checking if the mounts have changed with
* g_unix_mount_points_changed_since().
+ *
* a #GList of the UNIX mountpoints.
*
* Returns: (element-type GUnixMountPoint) (transfer full):
@@ -33522,6 +36312,7 @@
* If @time_read is set, it will be filled with the mount
* timestamp, allowing for checking if the mounts have changed
* with g_unix_mounts_changed_since().
+ *
* a #GList of the UNIX mounts.
*
* Returns: (element-type GUnixMountEntry) (transfer full):
@@ -33557,6 +36348,7 @@
* @close_fd: %TRUE to close the file descriptor when done
*
* Creates a new #GUnixOutputStream for the given @fd.
+ *
* If @close_fd, is %TRUE, the file descriptor will be closed when
* the output stream is destroyed.
*
@@ -33614,6 +36406,7 @@
* @address: a #GInetSocketAddress
*
* Gets @address's path, or for abstract sockets the "name".
+ *
* Guaranteed to be zero-terminated, but an abstract socket
* may contain embedded zeros, and thus you should use
* g_unix_socket_address_get_path_len() to get the true length
@@ -33629,6 +36422,7 @@
* @address: a #GInetSocketAddress
*
* Gets the length of @address's path.
+ *
* For details, see g_unix_socket_address_get_path().
*
* Returns: the length of the path
@@ -33641,6 +36435,7 @@
* @path: the socket path
*
* Creates a new #GUnixSocketAddress for @path.
+ *
* To create abstract socket addresses, on systems that support that,
* use g_unix_socket_address_new_abstract().
*
@@ -33669,8 +36464,10 @@
* @type: a #GUnixSocketAddressType
*
* Creates a new #GUnixSocketAddress of type @type with name @path.
+ *
* If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
* calling g_unix_socket_address_new().
+ *
* If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
* bytes of @path will be copied to the socket's path, and only those
* bytes will be considered part of the name. (If @path_len is -1,
@@ -33678,13 +36475,17 @@
* was "test", then calling g_socket_address_get_native_size() on the
* returned socket would return 7 (2 bytes of overhead, 1 byte for the
* abstract-socket indicator byte, and 4 bytes for the name "test").
+ *
* If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then
+ * @path_len bytes of @path will be copied to the socket's path, the
* rest of the path will be padded with 0 bytes, and the entire
* zero-padded buffer will be considered the name. (As above, if
+ * @path_len is -1, then @path is assumed to be NUL-terminated.) In
* this case, g_socket_address_get_native_size() will always return
* the full size of a <literal>struct sockaddr_un</literal>, although
* g_unix_socket_address_get_path_len() will still return just the
* length of @path.
+ *
* %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over
* %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course,
* when connecting to a server created by another process, you must
@@ -33724,6 +36525,7 @@
* @path: a string containing a VFS path.
*
* Gets a #GFile for @path.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFile.
@@ -33736,9 +36538,11 @@
* @uri: a string containing a URI
*
* Gets a #GFile for @uri.
+ *
* This operation never fails, but the returned object
* might not support any I/O operation if the URI
* is malformed or if the URI scheme is not supported.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFile.
@@ -33759,6 +36563,7 @@
* @vfs: a #GVfs.
*
* Gets a list of URI schemes supported by @vfs.
+ *
* The returned array belongs to GIO and must
* not be freed or modified.
*
@@ -33784,6 +36589,7 @@
* This operation never fails, but the returned object might
* not support any I/O operations if the @parse_name cannot
* be parsed by the #GVfs module.
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GFile for the given @parse_name.
@@ -33833,6 +36639,7 @@
* @error: a #GError location to store an error, or %NULL to ignore
*
* Finishes ejecting a volume. If any errors occured during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
* Returns: %TRUE, %FALSE if operation failed.
* Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
@@ -33863,6 +36670,7 @@
* @error: a #GError location to store the error occuring, or %NULL to ignore.
*
* Finishes ejecting a volume. If any errors occurred during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
*
* Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise.
* Since: 2.22
@@ -33876,6 +36684,7 @@
* Gets the kinds of <link linkend="volume-identifier">identifiers</link>
* that @volume has. Use g_volume_get_identifer() to obtain
* the identifiers themselves.
+ *
* of strings containing kinds of identifiers. Use g_strfreev() to free.
*
* Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
@@ -33892,22 +36701,29 @@
* #GMount object obtained from g_volume_get_mount() will always
* either be equal or a prefix of what this function returns. In
* other words, in code
+ *
* <programlisting>
* GMount *mount;
* GFile *mount_root
* GFile *volume_activation_root;
+ *
* mount = g_volume_get_mount (volume); /* mounted, so never NULL */
* mount_root = g_mount_get_root (mount);
* volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */
* </programlisting>
+ *
* then the expression
+ *
* <programlisting>
* (g_file_has_prefix (volume_activation_root, mount_root) ||
* </programlisting>
+ *
* will always be %TRUE.
+ *
* Activation roots are typically used in #GVolumeMonitor
* implementations to find the underlying mount to shadow, see
* g_mount_is_shadowed() for more details.
+ *
* g_object_unref() to free.
*
* Returns: (transfer full): the activation root of @volume or %NULL. Use
@@ -33920,6 +36736,7 @@
* @volume: a #GVolume.
*
* Gets the drive for the @volume.
+ *
* The returned object should be unreffed with g_object_unref()
* when no longer needed.
*
@@ -33932,6 +36749,7 @@
* @volume: a #GVolume.
*
* Gets the icon for @volume.
+ *
* The returned object should be unreffed with g_object_unref()
* when no longer needed.
*
@@ -33947,6 +36765,7 @@
* Gets the identifier of the given kind for @volume.
* See the <link linkend="volume-identifier">introduction</link>
* for more information about volume identifiers.
+ *
* requested identfier, or %NULL if the #GVolume
* doesn't have this kind of identifier
*
@@ -33959,6 +36778,7 @@
* @volume: a #GVolume.
*
* Gets the mount for the @volume.
+ *
* The returned object should be unreffed with g_object_unref()
* when no longer needed.
*
@@ -33971,6 +36791,7 @@
* @volume: a #GVolume.
*
* Gets the name of @volume.
+ *
* be freed with g_free() when no longer needed.
*
* Returns: the name for the given @volume. The returned string should
@@ -33985,6 +36806,7 @@
* the file system UUID for the volume in question and should be
* considered an opaque string. Returns %NULL if there is no UUID
* available.
+ *
* The returned string should be freed with g_free()
* when no longer needed.
*
@@ -34000,26 +36822,33 @@
* implementation when a new #GMount object is created that is not
* associated with a #GVolume object. It must be called just before
* emitting the @mount_added signal.
+ *
* If the return value is not %NULL, the caller must associate the
* returned #GVolume object with the #GMount. This involves returning
* it in its g_mount_get_volume() implementation. The caller must
* also listen for the "removed" signal on the returned object
* and give up its reference when handling that signal
+ *
* Similary, if implementing g_volume_monitor_adopt_orphan_mount(),
* the implementor must take a reference to @mount and return it in
* its g_volume_get_mount() implemented. Also, the implementor must
* listen for the "unmounted" signal on @mount and give up its
* reference upon handling that signal.
+ *
* There are two main use cases for this function.
+ *
* One is when implementing a user space file system driver that reads
* blocks of a block device that is already represented by the native
* volume monitor (for example a CD Audio file system driver). Such
* a driver will generate its own #GMount object that needs to be
* assoicated with the #GVolume object that represents the volume.
+ *
* The other is for implementing a #GVolumeMonitor whose sole purpose
* is to return #GVolume objects representing entries in the users
* "favorite servers" list or similar.
+ *
* if no wants to adopt the #GMount.
+ *
* implementations should instead create shadow mounts with the URI of
* the mount they intend to adopt. See the proxy volume monitor in
* gvfs for an example of this. Also see g_mount_is_shadowed(),
@@ -34034,6 +36863,7 @@
* g_volume_monitor_get:
*
* Gets the volume monitor used by gio.
+ *
* g_object_unref() when done with it.
*
* Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call
@@ -34045,6 +36875,7 @@
* @volume_monitor: a #GVolumeMonitor.
*
* Gets a list of drives connected to the system.
+ *
* The returned list should be freed with g_list_free(), after
* its elements have been unreffed with g_object_unref().
*
@@ -34058,6 +36889,7 @@
* @uuid: the UUID to look for
*
* Finds a #GMount object by its UUID (see g_mount_get_uuid())
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GMount or %NULL if no such mount is available.
@@ -34069,6 +36901,7 @@
* @volume_monitor: a #GVolumeMonitor.
*
* Gets a list of the mounts on the system.
+ *
* The returned list should be freed with g_list_free(), after
* its elements have been unreffed with g_object_unref().
*
@@ -34082,6 +36915,7 @@
* @uuid: the UUID to look for
*
* Finds a #GVolume object by its UUID (see g_volume_get_uuid())
+ *
* Free the returned object with g_object_unref().
*
* Returns: (transfer full): a #GVolume or %NULL if no such volume is available.
@@ -34093,6 +36927,7 @@
* @volume_monitor: a #GVolumeMonitor.
*
* Gets a list of the volumes on the system.
+ *
* The returned list should be freed with g_list_free(), after
* its elements have been unreffed with g_object_unref().
*
@@ -34124,6 +36959,8 @@
* @error: a #GError location to store an error, or %NULL to ignore
*
* Finishes mounting a volume. If any errors occured during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
+ *
* If the mount operation succeeded, g_volume_get_mount() on @volume
* is guaranteed to return the mount right after calling this
* function; there's no need to listen for the 'mount-added' signal on
@@ -34191,8 +37028,10 @@
* @close_fd: %TRUE to close the handle when done
*
* Creates a new #GWin32InputStream for the given @fd.
+ *
* If @close_handle is %TRUE, the handle will be closed
* when the stream is closed.
+ *
* Note that "handle" here means a Win32 HANDLE, not a "file descriptor"
* as used in the Windows C libraries.
*
@@ -34241,6 +37080,7 @@
* @close_handle: %TRUE to close the handle when done
*
* Creates a new #GWin32OutputStream for the given @handle.
+ *
* If @close_handle, is %TRUE, the handle will be closed when the
* output stream is destroyed.
*
@@ -34293,10 +37133,11 @@
* #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
* it will be used to set the file name and modification time in
* the GZIP header of the compressed data.
+ *
+ * Note: it is an error to call this function while a compression is in
* progress; it may only be called immediately after creation of @compressor,
* or after resetting it with g_converter_reset().
*
- * Note: it is an error to call this function while a compression is in
* Since: 2.26
*/
@@ -34343,7 +37184,9 @@
* are listed in an order so that default applications are listed before
* non-default ones, and handlers for inherited mimetypes are listed
* after the base ones.
+ *
* Optionally doesn't list the desktop ids given in the @except
+ *
* to handle @mime_type.
*
* Returns: a #GList containing the desktop ids which claim
@@ -34355,11 +37198,14 @@
*
* A type which can hold any UTF-32 or UCS-4 character code,
* also known as a Unicode code point.
+ *
* If you want to produce the UTF-8 representation of a #gunichar,
* use g_ucs4_to_utf8(). See also g_utf8_to_ucs4() for the reverse
* process.
+ *
* To print/scan values of this type as integer, use
* %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
+ *
* The notation to express a Unicode code point in running text is
* as a hexadecimal number with four to six digits and uppercase
* letters, prefixed by the string "U+". Leading zeros are omitted,
@@ -34367,6 +37213,7 @@
* For example, "U+0041 LATIN CAPITAL LETTER A". To print a code point
* in the U+-notation, use the format string "U+%04"G_GINT32_FORMAT"X".
* To scan, use the format string "U+%06"G_GINT32_FORMAT"X".
+ *
* |[
* gunichar c;
* sscanf ("U+0041", "U+%06"G_GINT32_FORMAT"X", &c)
@@ -34384,8 +37231,10 @@
* the BMP as pairs of 16bit numbers. Surrogate pairs cannot be stored
* in a single gunichar2 field, but all GLib functions accepting gunichar2
* arrays will correctly interpret surrogate pairs.</footnote>.
+ *
* To print/scan values of this type to/from text you need to convert
* to/from UTF-8, using g_utf16_to_utf8()/g_utf8_to_utf16().
+ *
* To print/scan values of this type as integer, use
* %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
*/
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 01bdea6..dba09c2 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -74,6 +74,7 @@
*
* Flags to be passed to g_object_bind_property() or
* g_object_bind_property_full().
+ *
* This enumeration can be extended at later date.
*
* Since: 2.26
@@ -90,6 +91,7 @@
* A function to be called to transform the source property of @source
* from @source_value into the target property of @target
* using @target_value.
+ *
* otherwise
*
* Returns: %TRUE if the transformation was successful, and %FALSE
@@ -232,6 +234,7 @@
*
* The hashing algorithm to be used by #GChecksum when performing the
* digest of some data.
+ *
* Note that the #GChecksumType enumeration may be extended at a later
* date to include new hashing algorithm types.
*
@@ -302,6 +305,7 @@
* is performed for class initialization of derived types as well.
* An example may help to correspond the intend of the different class
* initializers:
+ *
* |[
* typedef struct {
* GObjectClass parent_class;
@@ -323,6 +327,7 @@
* {
* class->static_integer = 42;
* }
+ *
* typedef struct {
* TypeAClass parent_class;
* gfloat static_float;
@@ -471,6 +476,7 @@
* condition to be false. If other threads change the state of this
* condition they signal the #GCond, and that causes the waiting
* threads to be woken up.
+ *
* <example>
* <title>
* Using GCond to block a thread until a condition is satisfied
@@ -479,6 +485,7 @@
* GCond* data_cond = NULL; /<!-- -->* Must be initialized somewhere *<!-- -->/
* GMutex* data_mutex = NULL; /<!-- -->* Must be initialized somewhere *<!-- -->/
* gpointer current_data = NULL;
+ *
* void
* push_data (gpointer data)
* {
@@ -487,36 +494,42 @@
* g_cond_signal (data_cond);
* g_mutex_unlock (data_mutex);
* }
+ *
* gpointer
* pop_data (void)
* {
* gpointer data;
+ *
* g_mutex_lock (data_mutex);
* while (!current_data)
* g_cond_wait (data_cond, data_mutex);
* data = current_data;
* current_data = NULL;
* g_mutex_unlock (data_mutex);
+ *
* return data;
* }
* </programlisting>
* </example>
+ *
* Whenever a thread calls <function>pop_data()</function> now, it will
* wait until current_data is non-%NULL, i.e. until some other thread
* has called <function>push_data()</function>.
+ *
* <note><para>It is important to use the g_cond_wait() and
* g_cond_timed_wait() functions only inside a loop which checks for the
* condition to be true. It is not guaranteed that the waiting thread
* will find the condition fulfilled after it wakes up, even if the
+ * signaling thread left the condition in that state: another thread may
* have altered the condition before the waiting thread got the chance
* to be woken up, even if the condition itself is protected by a
* #GMutex, like above.</para></note>
+ *
* A #GCond should only be accessed via the following functions.
+ *
* <note><para>All of the <function>g_cond_*</function> functions are
* actually macros. Apart from taking their addresses, you can however
* use them as if they were functions.</para></note>
- *
- * Signaling thread left the condition in that state: another thread may
*/
@@ -742,10 +755,12 @@
*
* Specifies the type of the hash function which is passed to
* g_hash_table_new() when a #GHashTable is created.
+ *
* The function is passed a key and should return a #guint hash value.
* The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
* hash functions which can be used when the key is a #gpointer, #gint,
* and #gchar* respectively.
+ *
* <!-- FIXME: Need more here. --> The hash values should be evenly
* distributed over a fairly large range? The modulus is taken with the
* hash table size (a prime number) to find the 'bucket' to place each
@@ -774,6 +789,17 @@
/**
+ * GHmac:
+ *
+ * An opaque structure representing a HMAC operation.
+ * To create a new GHmac, use g_hmac_new(). To free
+ * a GHmac, use g_hmac_unref().
+ *
+ * Since: 2.30
+ */
+
+
+/**
* GIOChannel:
*
* A data structure representing an IO Channel. The fields should be
@@ -962,6 +988,7 @@
*
* Checks the version of the GLib library that is being compiled
* against.
+ *
* <example>
* <title>Checking the version of the GLib library</title>
* <programlisting>
@@ -969,7 +996,9 @@
* g_error ("GLib version 1.2.0 or above is needed");
* </programlisting>
* </example>
+ *
* See glib_check_version() for a runtime check.
+ *
* is the same as or newer than the passed-in version.
*
* Returns: %TRUE if the version of the GLib header files
@@ -980,6 +1009,7 @@
* GLIB_MAJOR_VERSION:
*
* The major version number of the GLib library.
+ *
* Like #glib_major_version, but from the headers used at
* application compile time, rather than from the library
* linked against at application run time.
@@ -990,6 +1020,7 @@
* GLIB_MICRO_VERSION:
*
* The micro version number of the GLib library.
+ *
* Like #gtk_micro_version, but from the headers used at
* application compile time, rather than from the library
* linked against at application run time.
@@ -1000,6 +1031,7 @@
* GLIB_MINOR_VERSION:
*
* The minor version number of the GLib library.
+ *
* Like #gtk_minor_version, but from the headers used at
* application compile time, rather than from the library
* linked against at application run time.
@@ -1044,6 +1076,7 @@
* A mixed enumerated type and flags field. You must specify one type
* (string, strdup, boolean, tristate). Additionally, you may optionally
* bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL.
+ *
* It is likely that this enum will be extended in the future to
* support other types.
*/
@@ -1068,6 +1101,7 @@
*
* A parse context is used to parse a stream of bytes that
* you expect to contain marked-up text.
+ *
* See g_markup_parse_context_new(), #GMarkupParser, and so
* on for more details.
*/
@@ -1131,6 +1165,7 @@
* The #GMutex struct is an opaque data structure to represent a mutex
* (mutual exclusion). It can be used to protect data against shared
* access. Take for example the following function:
+ *
* <example>
* <title>A function which will not work in a threaded environment</title>
* <programlisting>
@@ -1138,17 +1173,21 @@
* give_me_next_number (void)
* {
* static int current_number = 0;
+ *
* /<!-- -->* now do a very complicated calculation to calculate the new
* * number, this might for example be a random number generator
* *<!-- -->/
* current_number = calc_next_number (current_number);
+ *
* return current_number;
* }
* </programlisting>
* </example>
+ *
* It is easy to see that this won't work in a multi-threaded
* application. There current_number must be protected against shared
* access. A first naive implementation would be:
+ *
* <example>
* <title>The wrong way to write a thread-safe function</title>
* <programlisting>
@@ -1158,22 +1197,28 @@
* static int current_number = 0;
* int ret_val;
* static GMutex * mutex = NULL;
+ *
* if (!mutex) mutex = g_mutex_new (<!-- -->);
+ *
* g_mutex_lock (mutex);
* ret_val = current_number = calc_next_number (current_number);
* g_mutex_unlock (mutex);
+ *
* return ret_val;
* }
* </programlisting>
* </example>
+ *
* This looks like it would work, but there is a race condition while
* constructing the mutex and this code cannot work reliable. Please do
* not use such constructs in your own programs! One working solution
* is:
+ *
* <example>
* <title>A correct thread-safe function</title>
* <programlisting>
* static GMutex *give_me_next_number_mutex = NULL;
+ *
* /<!-- -->* this function must be called before any call to
* * give_me_next_number(<!-- -->)
* *
@@ -1185,24 +1230,31 @@
* g_assert (give_me_next_number_mutex == NULL);
* give_me_next_number_mutex = g_mutex_new (<!-- -->);
* }
+ *
* int
* give_me_next_number (void)
* {
* static int current_number = 0;
* int ret_val;
+ *
* g_mutex_lock (give_me_next_number_mutex);
* ret_val = current_number = calc_next_number (current_number);
* g_mutex_unlock (give_me_next_number_mutex);
+ *
* return ret_val;
* }
* </programlisting>
* </example>
+ *
* #GStaticMutex provides a simpler and safer way of doing this.
+ *
* If you want to use a mutex, and your code should also work without
* calling g_thread_init() first, then you cannot use a #GMutex, as
* g_mutex_new() requires that the thread system be initialized. Use a
* #GStaticMutex instead.
+ *
* A #GMutex should only be accessed via the following functions.
+ *
* <note><para>All of the <function>g_mutex_*</function> functions are
* actually macros. Apart from taking their addresses, you can however
* use them as if they were functions.</para></note>
@@ -1276,7 +1328,7 @@
/**
* GObjectClass:
* @g_type_class: the parent class
- * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons.
+ * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the @constructor of the parent class. Overriding @constructor should be rarely needed, e.g. to handle construct properties, or to implement singletons.
* @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system.
* @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties.
* @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class.
@@ -1286,16 +1338,19 @@
* @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation.
*
* The class structure for the <structname>GObject</structname> type.
+ *
* <example>
* <title>Implementing singletons using a constructor</title>
* <programlisting>
* static MySingleton *the_singleton = NULL;
+ *
* static GObject*
* my_singleton_constructor (GType type,
* guint n_construct_params,
* GObjectConstructParam *construct_params)
* {
* GObject *object;
+ *
* if (!the_singleton)
* {
* object = G_OBJECT_CLASS (parent_class)->constructor (type,
@@ -1305,6 +1360,7 @@
* }
* else
* object = g_object_ref (G_OBJECT (the_singleton));
+ *
* return object;
* }
* </programlisting></example>
@@ -1394,8 +1450,7 @@
* options expect to find. If an option expects an extra argument, it
* can be specified in several ways; with a short option:
* <option>-x arg</option>, with a long option: <option>--name arg</option>
- *
- * Or combined in a single argument: <option>--name=arg</option>.
+ * or combined in a single argument: <option>--name=arg</option>.
*/
@@ -1408,6 +1463,7 @@
*
* The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
* options.
+ *
* occurred, in which case @error should be set with g_set_error()
*
* Returns: %TRUE if the option was successfully parsed, %FALSE if an error
@@ -1479,6 +1535,7 @@
*
* A <structname>GOptionGroup</structname> struct defines the options in a single
* group. The struct has only private fields and should not be directly accessed.
+ *
* All options in a group share the same translation function. Libraries which
* need to parse commandline options are expected to provide a function for
* getting a <structname>GOptionGroup</structname> holding their options, which
@@ -1494,6 +1551,7 @@
* @error: A return location for error details
*
* The type of function that can be called before and after parsing.
+ *
* occurred, in which case @error should be set with g_set_error()
*
* Returns: %TRUE if the function completed successfully, %FALSE if an error
@@ -1839,6 +1897,7 @@
* GPid:
*
* A type which is used to hold a process identification.
+ *
* On UNIX, processes are identified by a process id (an integer),
* while Windows uses process handles (which are pointers).
*/
@@ -1862,6 +1921,7 @@
*
* Specifies the type of function passed to g_main_context_set_poll_func().
* The semantics of the function should match those of the poll() system call.
+ *
* reported, or -1 if an error occurred.
*
* Returns: the number of #GPollFD elements which have events or errors
@@ -1883,6 +1943,7 @@
* <note><para>
* #GStaticPrivate is a better choice for most uses.
* </para></note>
+ *
* The #GPrivate struct is an opaque data structure to represent a
* thread private data key. Threads can thereby obtain and set a
* pointer which is private to the current thread. Take our
@@ -1890,33 +1951,41 @@
* above. Suppose we don't want <literal>current_number</literal> to be
* shared between the threads, but instead to be private to each thread.
* This can be done as follows:
+ *
* <example>
* <title>Using GPrivate for per-thread data</title>
* <programlisting>
* GPrivate* current_number_key = NULL; /<!-- -->* Must be initialized somewhere
* with g_private_new (g_free); *<!-- -->/
+ *
* int
* give_me_next_number (void)
* {
* int *current_number = g_private_get (current_number_key);
+ *
* if (!current_number)
* {
* current_number = g_new (int, 1);
* *current_number = 0;
* g_private_set (current_number_key, current_number);
* }
+ *
* *current_number = calc_next_number (*current_number);
+ *
* return *current_number;
* }
* </programlisting>
* </example>
+ *
* Here the pointer belonging to the key
* <literal>current_number_key</literal> is read. If it is %NULL, it has
* not been set yet. Then get memory for an integer value, assign this
* memory to the pointer and write the pointer back. Now we have an
* integer value that is private to the current thread.
+ *
* The #GPrivate struct should only be accessed via the following
* functions.
+ *
* <note><para>All of the <function>g_private_*</function> functions are
* actually macros. Apart from taking their addresses, you can however
* use them as if they were functions.</para></note>
@@ -1978,8 +2047,7 @@
* @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
* @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set.
* @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern.
- * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes.
- * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
+ * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
* @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches.
* @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched.
* @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
@@ -2052,6 +2120,7 @@
* Specifies the type of the function passed to g_regex_replace_eval().
* It is called for each occurance of the pattern in the string passed
* to g_regex_replace_eval(), and it should append the replacement to
+ * @result.
*
* Returns: %FALSE to continue the replacement process, %TRUE to stop it
* Since: 2.14
@@ -2127,7 +2196,7 @@
* @a: a #GSequenceIter
* @b: a #GSequenceIter
* @data: user data
- * @Returns: zero if the iterators are equal, a negative value if @a comes before @b, and a positive value if @b comes before
+ * @Returns: zero if the iterators are equal, a negative value if @a comes before @b, and a positive value if @b comes before @a.
*
* A #GSequenceIterCompareFunc is a function used to compare iterators.
* It must return zero if the iterators compare equal, a negative value
@@ -2158,6 +2227,7 @@
* creation time, if it is left %NULL, no accumulation of callback return
* values is performed. The return value of signal emissions is then the
* value returned by the last callback.
+ *
* should be aborted. Returning %FALSE means to abort the
* current emission and %TRUE is returned for continuation.
*
@@ -2186,7 +2256,9 @@
* A simple function pointer to get invoked when the signal is emitted. This
* allows you to tie a hook to the signal type, so that it will trap all
* emissions of that signal, from any object.
+ *
* You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
+ *
* hook is disconnected (and destroyed).
*
* Returns: whether it wants to stay connected. If it returns %FALSE, the signal
@@ -2244,7 +2316,7 @@
* @signal_flags: The signal flags as passed in to g_signal_new().
* @return_type: The return type for user callbacks.
* @n_params: The number of parameters that user callbacks take.
- * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting>
+ * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> @return_type callback (#gpointer data1, [#param_types param_names,] #gpointer data2); </programlisting>
*
* A structure holding in-depth information for a specific signal. It is
* filled in by the g_signal_query() function.
@@ -2263,10 +2335,9 @@
* GSourceCallbackFuncs:
* @ref: Called when a reference is added to the callback object
* @unref: Called when a reference to the callback object is dropped
- * @get: Called to extract the callback function and data from the callback object.
+ * @get: Called to extract the callback function and data from the callback object. The <structname>GSourceCallbackFuncs</structname> struct contains functions for managing callback objects.
+ *
*
- * The <structname>GSourceCallbackFuncs</structname> struct contains
- * functions for managing callback objects.
*/
@@ -2291,22 +2362,25 @@
/**
* GSourceFuncs:
- * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the
+ * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the @timeout_ values returned which were >= 0.
* @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here.
* @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source.
* @finalize: Called when the source is finalized.
*
* The <structname>GSourceFuncs</structname> struct contains a table of
* functions used to handle event sources in a generic manner.
+ *
* For idle sources, the prepare and check functions always return %TRUE
* to indicate that the source is always ready to be processed. The prepare
* function also returns a timeout value of 0 to ensure that the poll() call
* doesn't block (since that would be time wasted which could have been spent
* running the idle function).
+ *
* For timeout sources, the prepare and check functions both return %TRUE
* if the timeout interval has expired. The prepare function also returns
* a timeout value to ensure that the poll() call doesn't block too long
* and miss the next timeout.
+ *
* For file descriptor sources, the prepare function typically returns %FALSE,
* since it must wait until poll() has been called before it knows whether
* any events need to be processed. It sets the returned timeout to -1 to
@@ -2325,12 +2399,15 @@
* is called in the child after GLib has performed all the setup it plans
* to perform but before calling exec(). On POSIX actions taken in this
* function will thus only affect the child, not the parent.
+ *
* Note that POSIX allows only async-signal-safe functions (see signal(7))
* to be called in the child between fork() and exec(), which drastically
* limits the usefulness of child setup functions.
+ *
* Also note that modifying the environment from the child setup function
* may not have the intended effect, since it will get overridden by
* a non-%NULL @env argument to the <literal>g_spawn...</literal> functions.
+ *
* On Windows the function is called in the parent. Its usefulness on
* Windows is thus questionable. In many cases executing the child setup
* function in the parent can have ill effects, and you should be very
@@ -2385,6 +2462,7 @@
*
* A type corresponding to the appropriate struct type for the stat
* system call, depending on the platform and/or compiler being used.
+ *
* See g_stat() for more information.
*/
@@ -2397,6 +2475,7 @@
* but can be defined at compile-time. Here is a shorter, easier and
* safer version of our <function>give_me_next_number()</function>
* example:
+ *
* <example>
* <title>
* Using <structname>GStaticMutex</structname>
@@ -2409,13 +2488,16 @@
* static int current_number = 0;
* int ret_val;
* static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
+ *
* g_static_mutex_lock (&mutex);
* ret_val = current_number = calc_next_number (current_number);
* g_static_mutex_unlock (&mutex);
+ *
* return ret_val;
* }
* </programlisting>
* </example>
+ *
* Sometimes you would like to dynamically create a mutex. If you don't
* want to require prior calling to g_thread_init(), because your code
* should also be usable in non-threaded programs, you are not able to
@@ -2424,14 +2506,17 @@
* It must be initialized with g_static_mutex_init() before using it
* and freed with with g_static_mutex_free() when not needed anymore to
* free up any allocated resources.
+ *
* Even though #GStaticMutex is not opaque, it should only be used with
* the following functions, as it is defined differently on different
* platforms.
+ *
* All of the <function>g_static_mutex_*</function> functions apart
* from <function>g_static_mutex_get_mutex</function> can also be used
* even if g_thread_init() has not yet been called. Then they do
* nothing, apart from <function>g_static_mutex_trylock</function>,
* which does nothing but returning %TRUE.
+ *
* <note><para>All of the <function>g_static_mutex_*</function>
* functions are actually macros. Apart from taking their addresses, you
* can however use them as if they were functions.</para></note>
@@ -2447,6 +2532,7 @@
* similar to the difference between #GMutex and #GStaticMutex. Now
* look at our <function>give_me_next_number()</function> example with
* #GStaticPrivate:
+ *
* <example>
* <title>Using GStaticPrivate for per-thread data</title>
* <programlisting>
@@ -2455,13 +2541,16 @@
* {
* static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
* int *current_number = g_static_private_get (&current_number_key);
+ *
* if (!current_number)
* {
* current_number = g_new (int,1);
* *current_number = 0;
* g_static_private_set (&current_number_key, current_number, g_free);
* }
+ *
* *current_number = calc_next_number (*current_number);
+ *
* return *current_number;
* }
* </programlisting>
@@ -2478,36 +2567,46 @@
* desirable that several readers can read at once, whereas of course
* only one writer may write at a time. Take a look at the following
* example:
+ *
* <example>
* <title>An array with access functions</title>
* <programlisting>
* GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;
* GPtrArray *array;
+ *
* gpointer
* my_array_get (guint index)
* {
* gpointer retval = NULL;
+ *
* if (!array)
* return NULL;
+ *
* g_static_rw_lock_reader_lock (&rwlock);
* if (index < array->len)
* retval = g_ptr_array_index (array, index);
* g_static_rw_lock_reader_unlock (&rwlock);
+ *
* return retval;
* }
+ *
* void
* my_array_set (guint index, gpointer data)
* {
* g_static_rw_lock_writer_lock (&rwlock);
+ *
* if (!array)
* array = g_ptr_array_new (<!-- -->);
+ *
* if (index >= array->len)
* g_ptr_array_set_size (array, index+1);
* g_ptr_array_index (array, index) = data;
+ *
* g_static_rw_lock_writer_unlock (&rwlock);
* }
* </programlisting>
* </example>
+ *
* This example shows an array which can be accessed by many readers
* (the <function>my_array_get()</function> function) simultaneously,
* whereas the writers (the <function>my_array_set()</function>
@@ -2515,18 +2614,22 @@
* currently access the array. This is because of the potentially
* dangerous resizing of the array. Using these functions is fully
* multi-thread safe now.
+ *
* Most of the time, writers should have precedence over readers. That
* means, for this implementation, that as soon as a writer wants to
* lock the data, no other reader is allowed to lock the data, whereas,
* of course, the readers that already have locked the data are allowed
* to finish their operation. As soon as the last reader unlocks the
* data, the writer will lock it.
+ *
* Even though #GStaticRWLock is not opaque, it should only be used
* with the following functions.
+ *
* All of the <function>g_static_rw_lock_*</function> functions can be
* used even if g_thread_init() has not been called. Then they do
* nothing, apart from <function>g_static_rw_lock_*_trylock</function>,
* which does nothing but returning %TRUE.
+ *
* <note><para>A read-write lock has a higher overhead than a mutex. For
* example, both g_static_rw_lock_reader_lock() and
* g_static_rw_lock_reader_unlock() have to lock and unlock a
@@ -2545,18 +2648,19 @@
* A #GStaticRecMutex works like a #GStaticMutex, but it can be locked
* multiple times by one thread. If you enter it n times, you have to
* unlock it n times again to let other threads lock it. An exception
+ * is the function g_static_rec_mutex_unlock_full(): that allows you to
* unlock a #GStaticRecMutex completely returning the depth, (i.e. the
* number of times this mutex was locked). The depth can later be used
* to restore the state of the #GStaticRecMutex by calling
* g_static_rec_mutex_lock_full().
+ *
* Even though #GStaticRecMutex is not opaque, it should only be used
* with the following functions.
+ *
* All of the <function>g_static_rec_mutex_*</function> functions can
* be used even if g_thread_init() has not been called. Then they do
* nothing, apart from <function>g_static_rec_mutex_trylock</function>,
* which does nothing but returning %TRUE.
- *
- * Is the function g_static_rec_mutex_unlock_full(): that allows you to
*/
@@ -2604,7 +2708,11 @@
* The type used for functions that operate on test fixtures. This is
* used for the fixture setup and teardown functions as well as for the
* testcases themselves.
+ *
+ * @user_data is a pointer to the data that was given when registering
* the test case.
+ *
+ * @fixture will be a pointer to the area of memory allocated by the
* test framework, of the size requested. If the requested size was
* zero then @fixture will be equal to @user_data.
*
@@ -2641,6 +2749,7 @@
* The #GThread struct represents a running thread. It has three public
* read-only members, but the underlying struct is bigger, so you must
* not copy this struct.
+ *
* <note><para>Resources for a joinable thread are not fully released
* until g_thread_join() is called for that thread.</para></note>
*/
@@ -2693,6 +2802,7 @@
* g_* prepended counterparts (described in this document). For
* example, if you call g_mutex_new() then mutex_new() from the table
* provided to g_thread_init() will be called.
+ *
* <note><para>Do not use this struct unless you know what you are
* doing.</para></note>
*/
@@ -2718,6 +2828,7 @@
* @G_THREAD_PRIORITY_URGENT: the highest priority
*
* Specifies the priority of a thread.
+ *
* <note><para>It is not guaranteed that threads with different priorities
* really behave accordingly. On some systems (e.g. Linux) there are no
* thread priorities. On other systems (e.g. Solaris) there doesn't
@@ -2742,7 +2853,9 @@
* @G_TIME_TYPE_UNIVERSAL: the time is in UTC
*
* Disambiguates a given time in two ways.
+ *
* First, specifies if the given time is in universal or local time.
+ *
* Second, if the time is in local time, specifies if it is local
* standard time or local daylight time. This is important for the case
* where the same local time occurs twice (during daylight savings time
@@ -2785,6 +2898,7 @@
*
* The type of functions which are used to translate user-visible
* strings, for <option>--help</option> output.
+ *
* The returned string is owned by GLib and must not be freed.
*
* Returns: a translation of the string for the current locale.
@@ -2877,9 +2991,11 @@
* being freed. You should not call g_type_class_unref() from a
* #GTypeClassCacheFunc function to prevent infinite recursion, use
* g_type_class_unref_uncached() instead.
+ *
* The functions have to check the class id passed in to figure
* whether they actually want to cache the class of this type, since all
* classes are routed through the same #GTypeClassCacheFunc chain.
+ *
* called, %FALSE to continue.
*
* Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
@@ -3077,12 +3193,12 @@
* GTypeValueTable:
* @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]|
* @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]|
- * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
+ * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of @src_value into @dest_value in a way, that even after @src_value has been freed, the contents of @dest_value remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
* @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]|
* @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i
' needs to be used, and for collection of floats 'd'.
- * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_p
ointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour i
s undefined.
+ * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup @value similar to value_init(); e.g. for a string value that does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. @n_collect_values is exactly the string length of @collect_format, and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. @collect_flags is an argument provided as a hint by the caller. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @valu
e lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementatio
n for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, h
owever, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined.
* @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations.
- * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as
NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
+ * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. @n_collect_values equals the string length of @lcopy_format, and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (
!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
*
* The #GTypeValueTable provides the functions required by the #GValue implementation,
* to serve as a container for values of a type.
@@ -3130,10 +3246,12 @@
* @G_UNICODE_BREAK_CLOSE_PARANTHESIS: Closing Parenthesis (CP). Since 2.28
*
* These are the possible line break classifications.
+ *
* The five Hangul types were added in Unicode 4.1, so, has been
* introduced in GLib 2.10. Note that new types may be added in the future.
* Applications should be ready to handle unknown values.
* They may be regarded as %G_UNICODE_BREAK_UNKNOWN.
+ *
* See <ulink url="http://www.unicode.org/unicode/reports/tr14/";>http://www.unicode.org/unicode/reports/tr14/</ulink>.
*/
@@ -3227,11 +3345,11 @@
* @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28
* @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28
*
- * a value never returned from g_unichar_get_script()
* The #GUnicodeScript enumeration identifies different writing
* systems. The values correspond to the names as defined in the
* Unicode standard. The enumeration has been added in GLib 2.14,
* and is interchangeable with #PangoScript.
+ *
* Note that new types may be added in the future. Applications
* should be ready to handle unknown values.
* See <ulink
@@ -3294,6 +3412,7 @@
* These are logical ids for special directories which are defined
* depending on the platform used. You should use g_get_user_special_dir()
* to retrieve the full path associated to the logical id.
+ *
* The #GUserDirectory enumeration can be extended at later date. Not
* every platform has a directory for every logical id in this
* enumeration.
@@ -3306,14 +3425,13 @@
* GValue:
*
* An opaque structure used to hold different types of values.
+ * The data within the structure has protected scope: it is accessible only
* to functions within a #GTypeValueTable structure, or implementations of
* the g_value_*() API. That is, code portions which implement new fundamental
* types.
* #GValue users cannot make any assumptions about how data is stored
* within the 2 element @data union, and the @g_type member should
* only be accessed through the G_VALUE_TYPE() macro.
- *
- * The data within the structure has protected scope: it is accessible only
*/
@@ -3350,8 +3468,10 @@
* GVariantBuilder:
*
* A utility type for constructing container-type #GVariant instances.
+ *
* This is an opaque structure and may only be accessed using the
* following functions.
+ *
* #GVariantBuilder is not threadsafe in any way. Do not attempt to
* access it from more than one thread.
*/
@@ -3421,6 +3541,7 @@
* GVariantType:
*
* A type in the GVariant type system.
+ *
* Two types may not be compared by value; use g_variant_type_equal() or
* g_variant_type_is_subtype_of(). May be copied using
* g_variant_type_copy() and freed using g_variant_type_free().
@@ -3479,6 +3600,7 @@
* G_BREAKPOINT:
*
* Inserts a breakpoint instruction into the code.
+ *
* On x86 and alpha systems this is implemented as a soft interrupt
* and on other architectures it raises a %SIGTRAP signal.
*/
@@ -3509,6 +3631,8 @@
*
* Check if the closure still needs a marshaller. See g_closure_set_marshal().
*
+ * @closure.
+ *
* Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
*/
@@ -3615,6 +3739,7 @@
* A convenience macro for dynamic type implementations, which declares a
* class initialization function, an instance initialization function (see
* #GTypeInfo for information about these) and a static variable named
+ * @t_n<!-- -->_parent_class pointing to the parent class. Furthermore,
* it defines a <function>*_get_type()</function> and a static
* <function>*_register_type()</function> function for use in your
* <function>module_init()</function>.
@@ -3634,6 +3759,7 @@
*
* A more general version of G_DEFINE_DYNAMIC_TYPE() which
* allows to specify #GTypeFlags and custom code.
+ *
* |[
* G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
* gtk_gadget,
@@ -3647,18 +3773,22 @@
* static void gtk_gadget_init (GtkGadget *self);
* static void gtk_gadget_class_init (GtkGadgetClass *klass);
* static void gtk_gadget_class_finalize (GtkGadgetClass *klass);
+ *
* static gpointer gtk_gadget_parent_class = NULL;
* static GType gtk_gadget_type_id = 0;
+ *
* static void gtk_gadget_class_intern_init (gpointer klass)
* {
* gtk_gadget_parent_class = g_type_class_peek_parent (klass);
* gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
+ *
* GType
* gtk_gadget_get_type (void)
* {
* return gtk_gadget_type_id;
* }
+ *
* static void
* gtk_gadget_register_type (GTypeModule *type_module)
* {
@@ -3701,6 +3831,7 @@
* A convenience macro for #GTypeInterface definitions, which declares
* a default vtable initialization function and defines a *_get_type()
* function.
+ *
* The macro expects the interface initialization function to have the
* name <literal>t_n ## _default_init</literal>, and the interface
* structure to have the name <literal>TN ## Interface</literal>.
@@ -3778,6 +3909,7 @@
*
* The most general convenience macro for type implementations, on which
* G_DEFINE_TYPE(), etc are based.
+ *
* |[
* G_DEFINE_TYPE_EXTENDED (GtkGadget,
* gtk_gadget,
@@ -3796,6 +3928,7 @@
* gtk_gadget_parent_class = g_type_class_peek_parent (klass);
* gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
+ *
* GType
* gtk_gadget_get_type (void)
* {
@@ -3909,6 +4042,7 @@
* A convenience macro to ease interface addition in the @_C_ section
* of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
* See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
* Note that this macro can only be used together with the G_DEFINE_TYPE_*
* macros, since it depends on variable names from those macros.
*
@@ -3924,6 +4058,7 @@
* A convenience macro to ease interface addition in the @_C_ section
* of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED()
* for an example.
+ *
* Note that this macro can only be used together with the
* G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
* names from that macro.
@@ -4307,18 +4442,22 @@
* of the variable you intent to protect with the lock. Look at our
* <function>give_me_next_number()</function> example using the
* %G_LOCK_* macros:
+ *
* <example>
* <title>Using the %G_LOCK_* convenience macros</title>
* <programlisting>
* G_LOCK_DEFINE (current_number);
+ *
* int
* give_me_next_number (void)
* {
* static int current_number = 0;
* int ret_val;
+ *
* G_LOCK (current_number);
* ret_val = current_number = calc_next_number (current_number);
* G_UNLOCK (current_number);
+ *
* return ret_val;
* }
* </programlisting>
@@ -4357,6 +4496,7 @@
* @node: a #GNode
*
* Returns %TRUE if a #GNode is a leaf node.
+ *
* (i.e. it has no children)
*
* Returns: %TRUE if the #GNode is a leaf node
@@ -4368,6 +4508,7 @@
* @node: a #GNode
*
* Returns %TRUE if a #GNode is the root of a tree.
+ *
* (i.e. it has no parent or siblings)
*
* Returns: %TRUE if the #GNode is the root of a tree
@@ -4397,6 +4538,7 @@
* @class: a valid #GObjectClass
*
* Return the name of a class structure's type.
+ *
* should not be freed.
*
* Returns: Type name of @class. The string is owned by the type system and
@@ -4438,6 +4580,7 @@
* @object: Object to return the type name for.
*
* Get the name of an object's type.
+ *
* should not be freed.
*
* Returns: Type name of @object. The string is owned by the type system and
@@ -4459,6 +4602,7 @@
* G_ONCE_INIT:
*
* A #GOnce must be initialized with this macro before it can be used.
+ *
* <informalexample>
* <programlisting>
* GOnce my_once = G_ONCE_INIT;
@@ -4486,6 +4630,8 @@
* otherwise be left in <literal>argv</literal>. The option must be of type
* %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
* or %G_OPTION_ARG_FILENAME_ARRAY.
+ *
+ *
* Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
* for leftover arguments has the advantage that GOption takes care of
* necessary encoding conversions for strings or filenames.
@@ -4751,6 +4897,7 @@
* G_PARAM_STATIC_STRINGS:
*
* #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
+ *
* Since 2.13.0
*/
@@ -4767,6 +4914,7 @@
* G_PRIORITY_DEFAULT:
*
* Use this for default priority event sources.
+ *
* In GLib this priority is used when adding timeout functions
* with g_timeout_add(). In GDK this priority is used for events
* from the X server.
@@ -4777,6 +4925,7 @@
* G_PRIORITY_DEFAULT_IDLE:
*
* Use this for default priority idle functions.
+ *
* In GLib this priority is used when adding idle functions with
* g_idle_add().
*/
@@ -4786,6 +4935,7 @@
* G_PRIORITY_HIGH:
*
* Use this for high priority event sources.
+ *
* It is not used within GLib or GTK+.
*/
@@ -4794,6 +4944,7 @@
* G_PRIORITY_HIGH_IDLE:
*
* Use this for high priority idle functions.
+ *
* GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
* and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
* done to ensure that any pending resizes are processed before any
@@ -4805,6 +4956,7 @@
* G_PRIORITY_LOW:
*
* Use this for very low priority background tasks.
+ *
* It is not used within GLib or GTK+.
*/
@@ -4816,6 +4968,7 @@
* macro before it can be used. This macro can be used to initialize
* a variable, but it cannot be assigned to a variable. In that case
* you have to use g_queue_init().
+ *
* |[
* GQueue my_queue = G_QUEUE_INIT;
* ]|
@@ -4864,6 +5017,7 @@
* This macro flags signal argument types for which the signal system may
* assume that instances thereof remain persistent across all signal emissions
* they are used in. This is only useful for non ref-counted, value-copy types.
+ *
* To flag a signal argument in this way, add
* <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
* of g_signal_new().
@@ -4896,6 +5050,7 @@
* be used. This macro can used be to initialize a variable, but it
* cannot be assigned to a variable. In that case you have to use
* g_static_mutex_init().
+ *
* <informalexample>
* <programlisting>
* GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
@@ -4909,6 +5064,7 @@
*
* Every #GStaticPrivate must be initialized with this macro, before it
* can be used.
+ *
* <informalexample>
* <programlisting>
* GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
@@ -4924,6 +5080,7 @@
* be used. This macro can used be to initialize a variable, but it
* cannot be assigned to a variable. In that case you have to use
* g_static_rec_mutex_init().
+ *
* <informalexample>
* <programlisting>
* GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
@@ -4938,6 +5095,7 @@
* be used. This macro can used be to initialize a variable, but it
* cannot be assigned to a variable. In that case you have to use
* g_static_rw_lock_init().
+ *
* <informalexample>
* <programlisting>
* GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;
@@ -5086,6 +5244,7 @@
* Checks that @g_class is a class structure of the type identified by @g_type
* and issues a warning if this is not the case. Returns @g_class casted
* to a pointer to @c_type.
+ *
* This macro should only be used in type implementations.
*/
@@ -5096,6 +5255,8 @@
* @g_type: The type to be checked.
*
* Checks if @g_class is a class structure of the type identified by
+ * @g_type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -5108,6 +5269,7 @@
*
* Checks if @instance is a valid #GTypeInstance structure,
* otherwise issues a warning and returns %FALSE.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -5123,6 +5285,7 @@
* Checks that @instance is an instance of the type identified by @g_type
* and issues a warning if this is not the case. Returns @instance casted
* to a pointer to @c_type.
+ *
* This macro should only be used in type implementations.
*/
@@ -5133,6 +5296,7 @@
* @g_type: The type to be checked
*
* Checks if @instance is an instance of the type identified by @g_type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -5145,6 +5309,7 @@
*
* Checks if @value has been initialized to hold values
* of a value type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -5158,6 +5323,7 @@
*
* Checks if @value has been initialized to hold values
* of type @g_type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -5173,6 +5339,7 @@
* Gets the private class structure for a particular type.
* The private structure must have been registered in the
* get_type() function with g_type_add_class_private().
+ *
* This macro should only be used in type implementations.
*
* Since: 2.24
@@ -5252,6 +5419,7 @@
* @g_class: Location of a valid #GTypeClass structure.
*
* Get the type identifier from a given @class structure.
+ *
* This macro should only be used in type implementations.
*
* Returns: the #GType
@@ -5263,6 +5431,7 @@
* @instance: Location of a valid #GTypeInstance structure.
*
* Get the type identifier from a given @instance structure.
+ *
* This macro should only be used in type implementations.
*
* Returns: the #GType
@@ -5274,6 +5443,7 @@
* @g_iface: Location of a valid #GTypeInterface structure.
*
* Get the type identifier from a given @interface structure.
+ *
* This macro should only be used in type implementations.
*
* Returns: the #GType
@@ -5353,8 +5523,10 @@
*
* Get the class structure of a given @instance, casted
* to a specified ancestor type @g_type of the instance.
+ *
* Note that while calling a GInstanceInitFunc(), the class pointer gets
* modified, so it might not always return the expected pointer.
+ *
* This macro should only be used in type implementations.
*
* Returns: a pointer to the class structure
@@ -5368,6 +5540,7 @@
* @c_type: The C type of the interface structure.
*
* Get the interface structure for interface @g_type of a given @instance.
+ *
* This macro should only be used in type implementations.
*
* Returns: a pointer to the interface structure
@@ -5383,6 +5556,7 @@
* Gets the private structure for a particular type.
* The private structure must have been registered in the
* class_init function with g_type_class_add_private().
+ *
* This macro should only be used in type implementations.
*
* Since: 2.4
@@ -5889,9 +6063,11 @@
* G_TYPE_STRV:
*
* The #GType for a boxed type holding a %NULL-terminated array of strings.
+ *
* The code fragments in the following example show the use of a property of
* type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
* and g_object_get().
+ *
* |[
* g_object_class_install_property (object_class,
* PROP_AUTHORS,
@@ -5900,8 +6076,10 @@
* _("List of authors"),
* G_TYPE_STRV,
* G_PARAM_READWRITE));
+ *
* gchar *authors[] = { "Owen", "Tim", NULL };
* g_object_set (obj, "authors", authors, NULL);
+ *
* gchar *writers[];
* g_object_get (obj, "authors", &writers, NULL);
* /* do something with writers */
@@ -5960,14 +6138,17 @@
* G_TYPE_VARIANT:
*
* The fundamental type corresponding to #GVariant.
+ *
* All floating #GVariant instances passed through the #GType system are
* consumed.
+ *
* Note that callbacks in closures, and signal handlers
* for signals of return type %G_TYPE_VARIANT, must never return floating
* variants.
- * with this fundamental type in 2.26.
*
* Note: GLib 2.24 did include a boxed type with this name. It was replaced
+ * with this fundamental type in 2.26.
+ *
* Since: 2.26
*/
@@ -6007,6 +6188,7 @@
* ensure that %errno is relevant. The code for all #G_UNIX_ERROR is
* always %0, and the error message is always generated via
* g_strerror().
+ *
* It is expected that most code will not look at %errno from these
* APIs. Important cases where one would want to differentiate between
* errors are already covered by existing cross-platform GLib API,
@@ -6276,6 +6458,22 @@
/**
+ * G_VALUE_INIT:
+ *
+ * A #GValue must be initialized before it can be used.
+ * This macro can be used as initializer instead of an explicit
+ * <literal>{ 0 }</literal> when declaring a variable,
+ * but it cannot be assigned to a variable.
+ *
+ * |[
+ * GValue value = G_VALUE_INIT;
+ * ]|
+ *
+ * Since: 2.30
+ */
+
+
+/**
* G_VALUE_NOCOPY_CONTENTS:
*
* If passed to G_VALUE_COLLECT(), allocated data won't be copied
@@ -6320,8 +6518,10 @@
* Converts a string to a const #GVariantType. Depending on the
* current debugging level, this function may perform a runtime check
* to ensure that @string is a valid GVariant type string.
+ *
* It is always a programmer error to use this macro with an invalid
* type string.
+ *
* Since 2.24
*/
@@ -6414,6 +6614,7 @@
* The type of a 32bit signed integer value, that by convention, is used
* as an index into an array of file descriptors that are sent alongside
* a D-Bus message.
+ *
* If you are not interacting with D-Bus, then there is no reason to make
* use of this type.
*/
@@ -6455,6 +6656,7 @@
* The type of a D-Bus object reference. These are strings of a
* specific format used to identify objects at a given destination on
* the bus.
+ *
* If you are not interacting with D-Bus, then there is no reason to make
* use of this type. If you are, then the D-Bus specification contains a
* precise description of valid object paths.
@@ -6473,6 +6675,7 @@
*
* The type of a D-Bus type signature. These are strings of a specific
* format used as type signatures for D-Bus methods and messages.
+ *
* If you are not interacting with D-Bus, then there is no reason to make
* use of this type. If you are, then the D-Bus specification contains a
* precise description of valid signature strings.
@@ -6572,16 +6775,23 @@
*
* Arrays are similar to standard C arrays, except that they grow
* automatically as elements are added.
+ *
* Array elements can be of any size (though all elements of one array
* are the same size), and the array can be automatically cleared to
* '0's and zero-terminated.
+ *
* To create a new array use g_array_new().
+ *
* To add elements to an array, use g_array_append_val(),
* g_array_append_vals(), g_array_prepend_val(), and
* g_array_prepend_vals().
+ *
* To access an element of an array, use g_array_index().
+ *
* To set the size of an array, use g_array_set_size().
+ *
* To free an array, use g_array_free().
+ *
* <example>
* <title>Using a #GArray to store #gint values</title>
* <programlisting>
@@ -6594,12 +6804,11 @@
* g_array_append_val (garray, i);
* for (i = 0; i < 10000; i++)
* if (g_array_index (garray, gint, i) != i)
+ * g_print ("ERROR: got %d instead of %d\n",
* g_array_index (garray, gint, i), i);
* g_array_free (garray, TRUE);
* </programlisting>
* </example>
- *
- * G_print ("error: got %d instead of %d\n",
*/
@@ -6610,19 +6819,26 @@
*
* #GByteArray is based on #GArray, to provide arrays of bytes which
* grow automatically as elements are added.
+ *
* To create a new #GByteArray use g_byte_array_new().
+ *
* To add elements to a #GByteArray, use g_byte_array_append(), and
* g_byte_array_prepend().
+ *
* To set the size of a #GByteArray, use g_byte_array_set_size().
+ *
* To free a #GByteArray, use g_byte_array_free().
+ *
* <example>
* <title>Using a #GByteArray</title>
* <programlisting>
* GByteArray *gbarray;
* gint i;
+ *
* gbarray = g_byte_array_new (<!-- -->);
* for (i = 0; i < 10000; i++)
* g_byte_array_append (gbarray, (guint8*) "abcd", 4);
+ *
* for (i = 0; i < 10000; i++)
* {
* g_assert (gbarray->data[4*i] == 'a');
@@ -6630,6 +6846,7 @@
* g_assert (gbarray->data[4*i+2] == 'c');
* g_assert (gbarray->data[4*i+3] == 'd');
* }
+ *
* g_byte_array_free (gbarray, TRUE);
* </programlisting>
* </example>
@@ -6643,34 +6860,44 @@
*
* Pointer Arrays are similar to Arrays but are used only for storing
* pointers.
+ *
* <note><para>If you remove elements from the array, elements at the
* end of the array are moved into the space previously occupied by the
* removed element. This means that you should not rely on the index of
* particular elements remaining the same. You should also be careful
* when deleting elements while iterating over the array.</para></note>
+ *
* To create a pointer array, use g_ptr_array_new().
+ *
* To add elements to a pointer array, use g_ptr_array_add().
+ *
* To remove elements from a pointer array, use g_ptr_array_remove(),
* g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
+ *
* To access an element of a pointer array, use g_ptr_array_index().
+ *
* To set the size of a pointer array, use g_ptr_array_set_size().
+ *
* To free a pointer array, use g_ptr_array_free().
+ *
* <example>
* <title>Using a #GPtrArray</title>
* <programlisting>
* GPtrArray *gparray;
* gchar *string1 = "one", *string2 = "two", *string3 = "three";
+ *
* gparray = g_ptr_array_new (<!-- -->);
* g_ptr_array_add (gparray, (gpointer) string1);
* g_ptr_array_add (gparray, (gpointer) string2);
* g_ptr_array_add (gparray, (gpointer) string3);
+ *
* if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
+ * g_print ("ERROR: got %p instead of %p\n",
* g_ptr_array_index (gparray, 0), string1);
+ *
* g_ptr_array_free (gparray, TRUE);
* </programlisting>
* </example>
- *
- * G_print ("error: got %p instead of %p\n",
*/
@@ -6684,11 +6911,13 @@
* passing. These messages only make sense asynchronously for
* multi-threaded applications though, as a synchronous operation could
* as well be done in the same thread.
+ *
* Asynchronous queues are an exception from most other GLib data
* structures, as they can be used simultaneously from multiple threads
* without explicit locking and they bring their own builtin reference
* counting. This is because the nature of an asynchronous queue is that
* it will always be used by at least 2 concurrent threads.
+ *
* For using an asynchronous queue you first have to create one with
* g_async_queue_new(). A newly-created queue will get the reference
* count 1. Whenever another thread is creating a new reference of (that
@@ -6697,8 +6926,10 @@
* the reference count has to be decreased (using g_async_queue_unref()).
* After that the queue might no longer exist so you must not access
* it after that point.
+ *
* A thread, which wants to send a message to that queue simply calls
* g_async_queue_push() to push the message to the queue.
+ *
* A thread, which is expecting messages from an asynchronous queue
* simply calls g_async_queue_pop() for that queue. If no message is
* available in the queue at that point, the thread is now put to sleep
@@ -6706,6 +6937,7 @@
* and returned. The functions g_async_queue_try_pop() and
* g_async_queue_timed_pop() can be used to only check for the presence
* of messages or to only wait a certain time for messages respectively.
+ *
* For almost every function there exist two variants, one that locks
* the queue and one that doesn't. That way you can hold the queue lock
* (acquire it with g_async_queue_lock() and release it with
@@ -6725,27 +6957,33 @@
*
* The following is a collection of compiler macros to provide atomic
* access to integer and pointer-sized values.
+ *
* The macros that have 'int' in the name will operate on pointers to
* #gint and #guint. The macros with 'pointer' in the name will operate
* on pointers to any pointer-sized value, including #gsize. There is
* no support for 64bit operations on platforms with 32bit pointers
* because it is not generally possible to perform these operations
* atomically.
+ *
* The get, set and exchange operations for integers and pointers
* nominally operate on #gint and #gpointer, respectively. Of the
* arithmetic operations, the 'add' operation operates on (and returns)
* signed integer values (#gint and #gssize) and the 'and', 'or', and
* 'xor' operations operate on (and return) unsigned integer values
* (#guint and #gsize).
+ *
* All of the operations act as a full compiler and (where appropriate)
* hardware memory barrier. Acquire and release or producer and
* consumer barrier semantics are not available through this API.
+ *
* On GCC, these macros are implemented using GCC intrinsic operations.
* On non-GCC compilers they will evaluate to function calls to
* functions implemented by GLib.
+ *
* If GLib itself was compiled with GCC then these functions will again
* be implemented by the GCC intrinsics. On Windows without GCC, the
* interlocked API is used to implement the functions.
+ *
* With non-GCC compilers on non-Windows systems, the functions are
* currently incapable of implementing true atomic operations --
* instead, they fallback to holding a global lock while performing the
@@ -6753,10 +6991,12 @@
* process, but not between separate processes. For this reason, one
* should exercise caution when attempting to use these options on
* shared memory regions.
+ *
* It is very important that all accesses to a particular integer or
* pointer be performed using only this API and that different sizes of
* operation are not mixed or used on overlapping memory regions. Never
* read or assign directly from or to a value -- always use this API.
+ *
* For simple reference counting purposes you should use
* g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that
* fall outside of simple reference counting patterns are prone to
@@ -6780,11 +7020,13 @@
* 1421</ulink> or <ulink url="http://www.ietf.org/rfc/rfc2045.txt";>RFC
* 2045</ulink>. Base64 is most commonly used as a MIME transfer encoding
* for email.
+ *
* GLib supports incremental encoding using g_base64_encode_step() and
* g_base64_encode_close(). Incremental decoding can be done with
* g_base64_decode_step(). To encode or decode data in one go, use
* g_base64_encode() or g_base64_decode(). To avoid memory allocation when
* decoding, you can use g_base64_decode_inplace().
+ *
* Support for Base64 encoding has been added in GLib 2.12.
*/
@@ -6801,7 +7043,9 @@
* using the
* <ulink url="http://www.gnome.org/~ebassi/bookmark-spec";>Desktop Bookmark
* Specification</ulink>.
+ *
* The syntax of the bookmark files is described in detail inside the Desktop
+ * Bookmark Specification, here is a quick summary: bookmark files use a
* sub-class of the <ulink url="">XML Bookmark Exchange Language</ulink>
* specification, consisting of valid UTF-8 encoded XML, under the
* <literal>xbel</literal> root element; each bookmark is stored inside a
@@ -6817,17 +7061,18 @@
* registered; the URI and MIME type of an icon, to be used when displaying
* the bookmark inside a GUI.
* |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../glib/tests/bookmarks.xbel"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ *
* A bookmark file might contain more than one bookmark; each bookmark
* is accessed through its URI.
+ *
* The important caveat of bookmark files is that when you add a new
* bookmark you must also add the application that is registering it, using
* g_bookmark_file_add_application() or g_bookmark_file_set_app_info().
* If a bookmark has no applications then it won't be dumped when creating
* the on disk representation, using g_bookmark_file_to_data() or
* g_bookmark_file_to_file().
- * The #GBookmarkFile parser was added in GLib 2.12.
*
- * Bookmark specification, here is a quick summary: bookmark files use a
+ * The #GBookmarkFile parser was added in GLib 2.12.
*/
@@ -6838,10 +7083,12 @@
*
* A #GCache allows sharing of complex data structures, in order to
* save system resources.
+ *
* GTK+ uses caches for #GtkStyles and #GdkGCs. These consume a lot of
* resources, so a #GCache is used to see if a #GtkStyle or #GdkGC with
* the required properties already exists. If it does, then the
* existing object is used instead of creating a new one.
+ *
* #GCache uses keys and values. A #GCache key describes the properties
* of a particular resource. A #GCache value is the actual resource.
*/
@@ -6856,6 +7103,7 @@
* for a sequence of arbitrary bytes, using various hashing algorithms
* like MD5, SHA-1 and SHA-256. Checksums are commonly used in various
* environments and specifications.
+ *
* GLib supports incremental checksums using the GChecksum data
* structure, by calling g_checksum_update() as long as there's data
* available and then using g_checksum_get_string() or
@@ -6864,6 +7112,7 @@
* compute the checksum for binary blobs and NUL-terminated strings in
* one go, use the convenience functions g_compute_checksum_for_data()
* and g_compute_checksum_for_string(), respectively.
+ *
* Support for checksums has been added in GLib 2.16
*/
@@ -6876,18 +7125,21 @@
* #GCompletion provides support for automatic completion of a string
* using any group of target strings. It is typically used for file
* name completion as is common in many UNIX shells.
+ *
* A #GCompletion is created using g_completion_new(). Target items are
* added and removed with g_completion_add_items(),
* g_completion_remove_items() and g_completion_clear_items(). A
* completion attempt is requested with g_completion_complete() or
* g_completion_complete_utf8(). When no longer needed, the
* #GCompletion is freed with g_completion_free().
+ *
* Items in the completion can be simple strings (e.g. filenames), or
* pointers to arbitrary data structures. If data structures are used
* you must provide a #GCompletionFunc in g_completion_new(), which
* retrieves the item's string from the data structure. You can change
* the way in which strings are compared by setting a different
* #GCompletionStrncmpFunc in g_completion_set_compare().
+ *
* GCompletion has been marked as deprecated, since this API is rarely
* used and not very actively maintained.
*/
@@ -6901,23 +7153,30 @@
* The g_convert() family of function wraps the functionality of iconv(). In
* addition to pure character set conversions, GLib has functions to deal
* with the extra complications of encodings for file names.
+ *
* <refsect2 id="file-name-encodings">
* <title>File Name Encodings</title>
* <para>
* Historically, Unix has not had a defined encoding for file
+ * names: a file name is valid as long as it does not have path
* separators in it ("/"). However, displaying file names may
+ * require conversion: from the character set in which they were
* created, to the character set in which the application
* operates. Consider the Spanish file name
* "<filename>Presentación.sxi</filename>". If the
* application which created it uses ISO-8859-1 for its encoding,
* </para>
* <programlisting id="filename-iso8859-1">
+ * Character: P r e s e n t a c i ó n . s x i
+ * Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
* </programlisting>
* <para>
* However, if the application use UTF-8, the actual file name on
* disk would look like this:
* </para>
* <programlisting id="filename-utf-8">
+ * Character: P r e s e n t a c i ó n . s x i
+ * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
* </programlisting>
* <para>
* Glib uses UTF-8 for its strings, and GUI toolkits like GTK+
@@ -6926,6 +7185,7 @@
* and you wish to display the file name to the user, you
* <emphasis>will</emphasis> need to convert it into UTF-8. The
* opposite case is when the user types the name of a file he
+ * wishes to save: the toolkit will give you that string in
* UTF-8 encoding, and you will need to convert it to the
* character set used for file names before you can create the
* file with open(2) or fopen(3).
@@ -6933,6 +7193,7 @@
* <para>
* By default, Glib assumes that file names on disk are in UTF-8
* encoding. This is a valid assumption for file systems which
+ * were created relatively recently: most applications use UTF-8
* encoding for their strings, and that is also what they use for
* the file names they create. However, older file systems may
* still contain file names created in "older" encodings, such as
@@ -7003,13 +7264,6 @@
* </orderedlist>
* </refsect3>
* </refsect2>
- *
- * Names: a file name is valid as long as it does not have path
- * Require conversion: from the character set in which they were
- * Character: P r e s e n t a c i ó n . s x i
- * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
- * Wishes to save: the toolkit will give you that string in
- * Were created relatively recently: most applications use UTF-8
*/
@@ -7021,20 +7275,28 @@
* Keyed data lists provide lists of arbitrary data elements which can
* be accessed either with a string or with a #GQuark corresponding to
* the string.
+ *
* The #GQuark methods are quicker, since the strings have to be
* converted to #GQuarks anyway.
+ *
* Data lists are used for associating arbitrary data with #GObjects,
* using g_object_set_data() and related functions.
+ *
* To create a datalist, use g_datalist_init().
+ *
* To add data elements to a datalist use g_datalist_id_set_data(),
* g_datalist_id_set_data_full(), g_datalist_set_data() and
* g_datalist_set_data_full().
+ *
* To get data elements from a datalist use g_datalist_id_get_data()
* and g_datalist_get_data().
+ *
* To iterate over all data elements in a datalist use
* g_datalist_foreach() (not thread-safe).
+ *
* To remove data elements from a datalist use
* g_datalist_id_remove_data() and g_datalist_remove_data().
+ *
* To remove all data elements from a datalist, use g_datalist_clear().
*/
@@ -7049,6 +7311,7 @@
* structure returned from an external library. Since you cannot modify
* the structure, you use its location in memory as the key into a
* dataset, where you can associate any number of data elements with it.
+ *
* There are two forms of most of the dataset functions. The first form
* uses strings to identify the data elements associated with a
* location. The second form uses #GQuark identifiers, which are
@@ -7056,17 +7319,23 @@
* g_quark_from_static_string(). The second form is quicker, since it
* does not require looking up the string in the hash table of #GQuark
* identifiers.
+ *
* There is no function to create a dataset. It is automatically
* created as soon as you add elements to it.
+ *
* To add data elements to a dataset use g_dataset_id_set_data(),
* g_dataset_id_set_data_full(), g_dataset_set_data() and
* g_dataset_set_data_full().
+ *
* To get data elements from a dataset use g_dataset_id_get_data() and
* g_dataset_get_data().
+ *
* To iterate over all data elements in a dataset use
* g_dataset_foreach() (not thread-safe).
+ *
* To remove data elements from a dataset use
* g_dataset_id_remove_data() and g_dataset_remove_data().
+ *
* To destroy a dataset, use g_dataset_destroy().
*/
@@ -7083,20 +7352,24 @@
* microseconds and the time can range (proleptically) from 0001-01-01
* 00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX
* time in the sense that it is oblivious to leap seconds.
+ *
* #GDateTime is an immutable object; once it has been created it cannot
* be modified further. All modifiers will create a new #GDateTime.
* Nearly all such functions can fail due to the date or time going out
* of range, in which case %NULL will be returned.
+ *
* #GDateTime is reference counted: the reference count is increased by calling
* g_date_time_ref() and decreased by calling g_date_time_unref(). When the
* reference count drops to 0, the resources allocated by the #GDateTime
* structure are released.
+ *
* Many parts of the API may produce non-obvious results. As an
* example, adding two months to January 31st will yield March 31st
* whereas adding one month and then one month again will yield either
* March 28th or March 29th. Also note that adding 24 hours is not
* always the same as adding one day (since days containing daylight
* savings time transitions are either 23 or 25 hours in length).
+ *
* #GDateTime is available since GLib 2.26.
*/
@@ -7113,18 +7386,23 @@
* object) and a <emphasis>set of rules.</emphasis> If you use #GError
* incorrectly, then your code will not properly interoperate with other
* code that uses #GError, and users of your API will probably get confused.
+ *
+ * First and foremost: <emphasis>#GError should only be used to report
* recoverable runtime errors, never to report programming
* errors.</emphasis> If the programmer has screwed up, then you should
* use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some
* similar facility. (Incidentally, remember that the g_error() function
* should <emphasis>only</emphasis> be used for programming errors, it
* should not be used to print any error reportable via #GError.)
+ *
* Examples of recoverable runtime errors are "file not found" or
* "failed to parse input." Examples of programming errors are "NULL
* passed to strcmp()" or "attempted to free the same pointer twice."
+ * These two kinds of errors are fundamentally different: runtime errors
* should be handled or reported to the user, programming errors should
* be eliminated by fixing the bug in the program. This is why most
* functions in GLib and GTK+ do not use the #GError facility.
+ *
* Functions that can fail take a return location for a #GError as their
* last argument. For example:
* |[
@@ -7145,6 +7423,7 @@
* {
* /* Report error to user, and free error */
* g_assert (contents == NULL);
+ * fprintf (stderr, "Unable to read file: %s\n", err->message);
* g_error_free (err);
* }
* else
@@ -7157,6 +7436,7 @@
* <emphasis>reliable</emphasis> indicator of whether
* g_file_get_contents() failed. Additionally, g_file_get_contents()
* returns a boolean which indicates whether it was successful.
+ *
* Because g_file_get_contents() returns %FALSE on failure, if you
* are only interested in whether it failed and don't need to display
* an error message, you can pass %NULL for the <literal>error</literal>
@@ -7167,10 +7447,13 @@
* else
* /* error */ ;
* ]|
+ *
+ * The #GError object contains three fields: <literal>domain</literal>
* indicates the module the error-reporting function is located in,
* <literal>code</literal> indicates the specific error that occurred,
* and <literal>message</literal> is a user-readable error message with
* as many details as possible. Several functions are provided to deal
+ * with an error received from a called function: g_error_matches()
* returns %TRUE if the error matches a given domain and code,
* g_propagate_error() copies an error into an error location (so the
* calling function will receive it), and g_clear_error() clears an
@@ -7180,6 +7463,7 @@
* context known only to the calling function (the file being opened,
* or whatever -- though in the g_file_get_contents() case,
* <literal>error->message</literal> already contains a filename).
+ *
* When implementing a function that can report errors, the basic
* tool is g_set_error(). Typically, if a fatal error occurs you
* want to g_set_error(), then return immediately. g_set_error()
@@ -7190,7 +7474,9 @@
* foo_open_file (GError **error)
* {
* gint fd;
+ *
* fd = open ("file.txt", O_RDONLY);
+ *
* if (fd < 0)
* {
* g_set_error (error,
@@ -7204,6 +7490,7 @@
* return fd;
* }
* ]|
+ *
* Things are somewhat more complicated if you yourself call another
* function that can report a #GError. If the sub-function indicates
* fatal errors in some way other than reporting a #GError, such as
@@ -7213,16 +7500,19 @@
* my_function_that_can_fail (GError **err)
* {
* g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+ *
* if (!sub_function_that_can_fail (err))
* {
* /* assert that error was set by the sub-function */
* g_assert (err == NULL || *err != NULL);
* return FALSE;
* }
+ *
* /* otherwise continue, no error occurred */
* g_assert (err == NULL || *err == NULL);
* }
* ]|
+ *
* If the sub-function does not indicate errors other than by
* reporting a #GError, you need to create a temporary #GError
* since the passed-in one may be %NULL. g_propagate_error() is
@@ -7232,9 +7522,12 @@
* my_function_that_can_fail (GError **err)
* {
* GError *tmp_error;
+ *
* g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+ *
* tmp_error = NULL;
* sub_function_that_can_fail (&tmp_error);
+ *
* if (tmp_error != NULL)
* {
* /* store tmp_error in err, if err != NULL,
@@ -7243,19 +7536,24 @@
* g_propagate_error (err, tmp_error);
* return FALSE;
* }
+ *
* /* otherwise continue, no error occurred */
* }
* ]|
+ *
* Error pileups are always a bug. For example, this code is incorrect:
* |[
* gboolean
* my_function_that_can_fail (GError **err)
* {
* GError *tmp_error;
+ *
* g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+ *
* tmp_error = NULL;
* sub_function_that_can_fail (&tmp_error);
* other_function_that_can_fail (&tmp_error);
+ *
* if (tmp_error != NULL)
* {
* g_propagate_error (err, tmp_error);
@@ -7265,6 +7563,7 @@
* ]|
* <literal>tmp_error</literal> should be checked immediately after
* sub_function_that_can_fail(), and either cleared or propagated
+ * upward. The rule is: <emphasis>after each error, you must either
* handle the error, or return it to the calling function</emphasis>.
* Note that passing %NULL for the error location is the equivalent
* of handling an error by always doing nothing about it. So the
@@ -7275,10 +7574,14 @@
* my_function_that_can_fail (GError **err)
* {
* GError *tmp_error;
+ *
* g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+ *
* sub_function_that_can_fail (NULL); /* ignore errors */
+ *
* tmp_error = NULL;
* other_function_that_can_fail (&tmp_error);
+ *
* if (tmp_error != NULL)
* {
* g_propagate_error (err, tmp_error);
@@ -7286,11 +7589,13 @@
* }
* }
* ]|
+ *
* Note that passing %NULL for the error location
* <emphasis>ignores</emphasis> errors; it's equivalent to
* <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal>
* in C++. It does <emphasis>not</emphasis> mean to leave errors
* unhandled; it means to handle them by doing nothing.
+ *
* Error domains and codes are conventionally named as follows:
* <itemizedlist>
* <listitem><para>
@@ -7299,6 +7604,7 @@
* for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
* |[
* #define G_SPAWN_ERROR g_spawn_error_quark ()
+ *
* GQuark
* g_spawn_error_quark (void)
* {
@@ -7328,6 +7634,7 @@
* for example %G_SPAWN_ERROR_FAILED or %G_THREAD_ERROR_FAILED.
* </para></listitem>
* </itemizedlist>
+ *
* Summary of rules for use of #GError:
* <itemizedlist>
* <listitem><para>
@@ -7389,13 +7696,6 @@
* <literal>g_return_if_fail (error == NULL || *error == NULL);</literal>).
* </para></listitem>
* </itemizedlist>
- *
- * First and foremost: <emphasis>#GError should only be used to report
- * These two kinds of errors are fundamentally different: runtime errors
- * Fprintf (stderr, "unable to read file: %s\n", err->message);
- * The #gerror object contains three fields: <literal>domain</literal>
- * With an error received from a called function: g_error_matches()
- * Upward. the rule is: <emphasis>after each error, you must either
*/
@@ -7406,6 +7706,7 @@
* Functions for manipulating internet hostnames; in particular, for
* converting between Unicode and ASCII-encoded forms of
* Internationalized Domain Names (IDNs).
+ *
* The <ulink
* url="http://www.ietf.org/rfc/rfc3490.txt";>Internationalized Domain
* Names for Applications (IDNA)</ulink> standards allow for the use
@@ -7426,6 +7727,7 @@
* The <function>g_regex_*()</function> functions implement regular
* expression pattern matching using syntax and semantics similar to
* Perl regular expression.
+ *
* Some functions accept a @start_position argument, setting it differs
* from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL
* in the case of a pattern that begins with any kind of lookbehind assertion.
@@ -7435,8 +7737,10 @@
* from the fourth byte, namely "issipi", it does not match, because "\B" is
* always false at the start of the subject, which is deemed to be a word
* boundary. However, if the entire string is passed , but with
+ * @start_position set to 4, it finds the second occurrence of "iss" because
* it is able to look behind the starting point to discover that it is
* preceded by a letter.
+ *
* Note that, unless you set the #G_REGEX_RAW flag, all the strings passed
* to these functions must be encoded in UTF-8. The lengths and the positions
* inside the strings are in bytes and not in characters, so, for instance,
@@ -7444,6 +7748,7 @@
* single character. If you set #G_REGEX_RAW the strings can be non-valid
* UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
* bytes and two characters long.
+ *
* When matching a pattern, "\n" matches only against a "\n" character in
* the string, and "\r" matches only a "\r" character. To match any newline
* sequence use "\R". This particular group matches either the two-character
@@ -7451,6 +7756,7 @@
* U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
* CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
* separator, U+2028), or PS (paragraph separator, U+2029).
+ *
* The behaviour of the dot, circumflex, and dollar metacharacters are
* affected by newline characters, the default is to recognize any newline
* character (the same characters recognized by "\R"). This can be changed
@@ -7461,10 +7767,12 @@
* relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an
* unescaped "#" outside a character class is encountered. This indicates
* a comment that lasts until after the next newline.
+ *
* Creating and manipulating the same #GRegex structure from different
* threads is not a problem as #GRegex does not modify its internal
* state between creation and destruction, on the other hand #GMatchInfo
* is not threadsafe.
+ *
* The regular expressions low-level functionalities are obtained through
* the excellent <ulink url="http://www.pcre.org/";>PCRE</ulink> library
* written by Philip Hazel.
@@ -7481,6 +7789,7 @@
* functions is designed for programs which explicitly target UNIX,
* or are using it to build higher level abstractions which would be
* conditionally compiled if the platform matches G_OS_UNIX.
+ *
* To use these functions, you must explicitly include the
* "glib-unix.h" header.
*/
@@ -7507,30 +7816,38 @@
* information about the type of that value. The range of possible
* values is determined by the type. The type system used by #GVariant
* is #GVariantType.
+ *
* #GVariant instances always have a type and a value (which are given
* at construction time). The type and value of a #GVariant instance
* can never change other than by the #GVariant itself being
* destroyed. A #GVariant cannot contain a pointer.
+ *
* #GVariant is reference counted using g_variant_ref() and
* g_variant_unref(). #GVariant also has floating reference counts --
* see g_variant_ref_sink().
+ *
* #GVariant is completely threadsafe. A #GVariant instance can be
* concurrently accessed in any way from any number of threads without
* problems.
+ *
* #GVariant is heavily optimised for dealing with data in serialised
* form. It works particularly well with data located in memory-mapped
* files. It can perform nearly all deserialisation operations in a
* small constant time, usually touching only a single memory page.
* Serialised #GVariant data can also be sent over the network.
+ *
* #GVariant is largely compatible with D-Bus. Almost all types of
* #GVariant instances can be sent over D-Bus. See #GVariantType for
* exceptions.
+ *
* For convenience to C programmers, #GVariant features powerful
* varargs-based value construction and destruction. This feature is
* designed to be embedded in other libraries.
+ *
* There is a Python-inspired text language for describing #GVariant
* values. #GVariant includes a printer for this language and a parser
* with type inferencing.
+ *
* <refsect2>
* <title>Memory Use</title>
* <para>
@@ -7541,6 +7858,7 @@
* </para>
* <para>
* The memory allocated by #GVariant can be grouped into 4 broad
+ * purposes: memory for serialised data, memory for the type
* information cache, buffer management memory and memory for the
* #GVariant structure itself.
* </para>
@@ -7566,6 +7884,7 @@
* <para>
* Arrays use the amount of space required to store each of their
* members, concatenated. Additionally, if the items stored in an
+ * array are not of a fixed-size (ie: strings, other arrays, etc)
* then an additional framing offset is stored for each item. The
* size of this offset is either 1, 2 or 4 bytes depending on the
* overall size of the container. Additionally, extra padding bytes
@@ -7630,7 +7949,9 @@
* <para>
* Aside from the type information structures stored in read-only
* memory, there are two forms of type information. One is used for
+ * container types where there is a single element type: arrays and
* maybe types. The other is used for container types where there
+ * are multiple element types: tuples and dictionary entries.
* </para>
* <para>
* Array type info structures are 6 * sizeof (void *), plus the
@@ -7699,6 +8020,7 @@
* <para>
* If calls are made to start accessing the other values then
* #GVariant instances will exist for those values only for as long
+ * as they are in use (ie: until you call g_variant_unref()). The
* type information is shared. The serialised data and the buffer
* management structure for that serialised data is shared by the
* child.
@@ -7721,12 +8043,6 @@
* </para>
* </refsect3>
* </refsect2>
- *
- * Purposes: memory for serialised data, memory for the type
- * Array are not of a fixed-size (ie: strings, other arrays, etc)
- * Container types where there is a single element type: arrays and
- * Are multiple element types: tuples and dictionary entries.
- * As they are in use (ie: until you call g_variant_unref()). The
*/
@@ -7742,11 +8058,13 @@
* url='http://dbus.freedesktop.org/doc/dbus-specification.html'>DBus
* specification</ulink>, therefore, provides a significant amount of
* information that is useful when working with GVariant.
+ *
* The first major change with respect to the D-Bus type system is the
* introduction of maybe (or "nullable") types. Any type in GVariant can be
* converted to a maybe type, in which case, "nothing" (or "null") becomes a
* valid value. Maybe types have been added by introducing the
* character "<literal>m</literal>" to type strings.
+ *
* The second major change is that the GVariant type system supports the
* concept of "indefinite types" -- types that are less specific than
* the normal types found in D-Bus. For example, it is possible to speak
@@ -7755,11 +8073,14 @@
* strings". Indefinite types have been added by introducing the
* characters "<literal>*</literal>", "<literal>?</literal>" and
* "<literal>r</literal>" to type strings.
+ *
* Finally, all arbitrary restrictions relating to the complexity of
* types are lifted along with the restriction that dictionary entries
* may only appear nested inside of arrays.
+ *
* Just as in D-Bus, GVariant types are described with strings ("type
* strings"). Subject to the differences mentioned above, these strings
+ * are of the same form as those found in DBus. Note, however: D-Bus
* always works in terms of messages and therefore individual type
* strings appear nowhere in its interface. Instead, "signatures"
* are a concatenation of the strings of the type of each argument in a
@@ -7768,6 +8089,7 @@
* that a D-Bus signature string is generally not a valid GVariant type
* string -- except in the case that it is the signature of a message
* containing exactly one argument.
+ *
* An indefinite type is similar in spirit to what may be called an
* abstract type in other type systems. No value can exist that has an
* indefinite type as its type, but values can exist that have types
@@ -7779,6 +8101,7 @@
* which certainly matches the type of "an array of no particular type",
* since "array of integers" is a subtype of "array of no particular
* type".
+ *
* This is similar to how instances of abstract classes may not
* directly exist in other type systems, but instances of their
* non-abstract subtypes may. For example, in GTK, no object that has
@@ -7786,7 +8109,9 @@
* but a #GtkWindow can certainly be instantiated, and you would say
* that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
* #GtkBin).
+ *
* A detailed description of GVariant type strings is given here:
+ *
* <refsect2 id='gvariant-typestrings'>
* <title>GVariant Type Strings</title>
* <para>
@@ -8171,8 +8496,31 @@
* "<literal>{**}</literal>" is not a valid type string.
* </para>
* </refsect2>
+ */
+
+
+/**
+ * SECTION:gwakeup
+ * @title: GWakeup
+ * @short_description: portable cross-thread event signal mechanism
+ *
+ * #GWakeup is a simple and portable way of signaling events between
+ * different threads in a way that integrates nicely with g_poll().
+ * GLib uses it internally for cross-thread signalling in the
+ * implementation of #GMainContext and #GCancellable.
+ *
+ * You first create a #GWakeup with g_wakeup_new() and initialise a
+ * #GPollFD from it using g_wakeup_get_pollfd(). Polling on the created
+ * #GPollFD will block until g_wakeup_signal() is called, at which point
+ * it will immediately return. Future attempts to poll will continue to
+ * return until g_wakeup_acknowledge() is called. g_wakeup_free() is
+ * used to free a #GWakeup.
+ *
+ * On sufficiently modern Linux, this is implemented using eventfd. On
+ * Windows it is implemented using an event handle. On other systems it
+ * is implemented with a pair of pipes.
*
- * Are of the same form as those found in dbus. note, however: D-Bus
+ * Since: 2.30
*/
@@ -8184,34 +8532,45 @@
* A #GHashTable provides associations between keys and values which is
* optimized so that given a key, the associated value can be found
* very quickly.
+ *
* Note that neither keys nor values are copied when inserted into the
* #GHashTable, so they must exist for the lifetime of the #GHashTable.
* This means that the use of static strings is OK, but temporary
* strings (i.e. those created in buffers and those returned by GTK+
* widgets) should be copied with g_strdup() before being inserted.
+ *
* If keys or values are dynamically allocated, you must be careful to
* ensure that they are freed when they are removed from the
* #GHashTable, and also when they are overwritten by new insertions
* into the #GHashTable. It is also not advisable to mix static strings
* and dynamically-allocated strings in a #GHashTable, because it then
* becomes difficult to determine whether the string should be freed.
+ *
* To create a #GHashTable, use g_hash_table_new().
+ *
* To insert a key and value into a #GHashTable, use
* g_hash_table_insert().
+ *
* To lookup a value corresponding to a given key, use
* g_hash_table_lookup() and g_hash_table_lookup_extended().
+ *
* g_hash_table_lookup_extended() can also be used to simply
* check if a key is present in the hash table.
+ *
* To remove a key and value, use g_hash_table_remove().
+ *
* To call a function for each key and value pair use
* g_hash_table_foreach() or use a iterator to iterate over the
* key/value pairs in the hash table, see #GHashTableIter.
+ *
* To destroy a #GHashTable use g_hash_table_destroy().
+ *
* <example>
* <title>Using a GHashTable as a set</title>
* <para>
* A common use-case for hash tables is to store information about
* a set of keys, without associating any particular value with each
+ * key. GHashTable optimizes one way of doing so: If you store only
* key-value pairs where key == value, then GHashTable does not
* allocate memory to store the values, which can be a considerable
* space saving, if your set is large.
@@ -8222,20 +8581,23 @@
* GEqualFunc equal_func,
* GDestroyNotify destroy)
* {
- * return g_hash_table_new_full (hash_func, equal_func, destroy);
+ * return g_hash_table_new_full (hash_func, equal_func, destroy, NULL);
* }
+ *
* void
* set_insert (GHashTable *set,
* gpointer element)
* {
* g_hash_table_insert (set, element, element);
* }
+ *
* gboolean
* set_contains (GHashTable *set,
* gpointer element)
* {
* return g_hash_table_lookup_extended (set, element, NULL, NULL);
* }
+ *
* gboolean
* set_remove (GHashTable *set,
* gpointer element)
@@ -8244,8 +8606,24 @@
* }
* </programlisting>
* </example>
+ */
+
+
+/**
+ * SECTION:hmac
+ * @title: Secure HMAC Digests
+ * @short_description: Computes the HMAC for data
+ *
+ * HMACs should be used when producing a cookie or hash based on data
+ * and a key. Simple mechanisms for using SHA1 and other algorithms to
+ * digest a key and data together are vulnerable to various security
+ * issues. <ulink url="http://en.wikipedia.org/wiki/HMAC";>HMAC</ulink>
+ * uses algorithms like SHA1 in a secure way to produce a digest of a
+ * key and data.
+ *
+ * Both the key and data are arbitrary byte arrays of bytes or characters.
*
- * Key. ghashtable optimizes one way of doing so: If you store only
+ * Support for HMAC Digests has been added in GLib 2.30.
*/
@@ -8260,19 +8638,23 @@
* into the <link linkend="glib-The-Main-Event-Loop">main event
* loop</link>. Currently full support is available on UNIX platforms,
* support for Windows is only partially complete.
+ *
* To create a new #GIOChannel on UNIX systems use
* g_io_channel_unix_new(). This works for plain file descriptors,
* pipes and sockets. Alternatively, a channel can be created for a
* file in a system independent manner using g_io_channel_new_file().
+ *
* Once a #GIOChannel has been created, it can be used in a generic
* manner with the functions g_io_channel_read_chars(),
* g_io_channel_write_chars(), g_io_channel_seek_position(), and
* g_io_channel_shutdown().
+ *
* To add a #GIOChannel to the <link
* linkend="glib-The-Main-Event-Loop">main event loop</link> use
* g_io_add_watch() or g_io_add_watch_full(). Here you specify which
* events you are interested in on the #GIOChannel, and provide a
* function to be called whenever these events occur.
+ *
* #GIOChannel instances are created with an initial reference count of
* 1. g_io_channel_ref() and g_io_channel_unref() can be used to
* increment or decrement the reference count respectively. When the
@@ -8280,6 +8662,7 @@
* isn't closed automatically, unless it was created using
* g_io_channel_new_file().) Using g_io_add_watch() or
* g_io_add_watch_full() increments a channel's reference count.
+ *
* The new functions g_io_channel_read_chars(),
* g_io_channel_read_line(), g_io_channel_read_line_string(),
* g_io_channel_read_to_end(), g_io_channel_write_chars(),
@@ -8296,32 +8679,43 @@
*
* The #GList structure and its associated functions provide a standard
* doubly-linked list data structure.
+ *
* Each element in the list contains a piece of data, together with
* pointers which link to the previous and next elements in the list.
* Using these pointers it is possible to move through the list in both
* directions (unlike the <link
* linkend="glib-Singly-Linked-Lists">Singly-Linked Lists</link> which
* only allows movement through the list in the forward direction).
+ *
* The data contained in each element can be either integer values, by
* using one of the <link linkend="glib-Type-Conversion-Macros">Type
* Conversion Macros</link>, or simply pointers to any type of data.
+ *
* List elements are allocated from the <link
* linkend="glib-Memory-Slices">slice allocator</link>, which is more
* efficient than allocating elements individually.
+ *
* Note that most of the #GList functions expect to be passed a pointer
* to the first element in the list. The functions which insert
* elements return the new start of the list, which may have changed.
+ *
* There is no function to create a #GList. %NULL is considered to be
* the empty list so you simply set a #GList* to %NULL.
+ *
* To add elements, use g_list_append(), g_list_prepend(),
* g_list_insert() and g_list_insert_sorted().
+ *
* To remove elements, use g_list_remove().
+ *
* To find elements in the list use g_list_first(), g_list_last(),
* g_list_next(), g_list_previous(), g_list_nth(), g_list_nth_data(),
* g_list_find() and g_list_find_custom().
+ *
* To find the index of an element use g_list_position() and
* g_list_index().
+ *
* To call a function for each element in the list use g_list_foreach().
+ *
* To free the entire list, use g_list_free().
*/
@@ -8333,33 +8727,44 @@
*
* The #GSList structure and its associated functions provide a
* standard singly-linked list data structure.
+ *
* Each element in the list contains a piece of data, together with a
* pointer which links to the next element in the list. Using this
* pointer it is possible to move through the list in one direction
* only (unlike the <link
* linkend="glib-Doubly-Linked-Lists">Doubly-Linked Lists</link> which
* allow movement in both directions).
+ *
* The data contained in each element can be either integer values, by
* using one of the <link linkend="glib-Type-Conversion-Macros">Type
* Conversion Macros</link>, or simply pointers to any type of data.
+ *
* List elements are allocated from the <link
* linkend="glib-Memory-Slices">slice allocator</link>, which is more
* efficient than allocating elements individually.
+ *
* Note that most of the #GSList functions expect to be passed a
* pointer to the first element in the list. The functions which insert
* elements return the new start of the list, which may have changed.
+ *
* There is no function to create a #GSList. %NULL is considered to be
* the empty list so you simply set a #GSList* to %NULL.
+ *
* To add elements, use g_slist_append(), g_slist_prepend(),
* g_slist_insert() and g_slist_insert_sorted().
+ *
* To remove elements, use g_slist_remove().
+ *
* To find elements in the list use g_slist_last(), g_slist_next(),
* g_slist_nth(), g_slist_nth_data(), g_slist_find() and
* g_slist_find_custom().
+ *
* To find the index of an element use g_slist_position() and
* g_slist_index().
+ *
* To call a function for each element in the list use
* g_slist_foreach().
+ *
* To free the entire list, use g_slist_free().
*/
@@ -8374,29 +8779,36 @@
* different types of sources such as file descriptors (plain files,
* pipes or sockets) and timeouts. New types of event sources can also
* be added using g_source_attach().
+ *
* To allow multiple independent sets of sources to be handled in
* different threads, each source is associated with a #GMainContext.
* A GMainContext can only be running in a single thread, but
* sources can be added to it and removed from it from other threads.
+ *
* Each event source is assigned a priority. The default priority,
* #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
* Values greater than 0 denote lower priorities. Events from high priority
* sources are always processed before events from lower priority sources.
+ *
* Idle functions can also be added, and assigned a priority. These will
* be run whenever no events with a higher priority are ready to be processed.
+ *
* The #GMainLoop data type represents a main event loop. A GMainLoop is
* created with g_main_loop_new(). After adding the initial event sources,
* g_main_loop_run() is called. This continuously checks for new events from
* each of the event sources and dispatches them. Finally, the processing of
* an event from one of the sources leads to a call to g_main_loop_quit() to
* exit the main loop, and g_main_loop_run() returns.
+ *
* It is possible to create new instances of #GMainLoop recursively.
* This is often used in GTK+ applications when showing modal dialog
* boxes. Note that event sources are associated with a particular
* #GMainContext, and will be checked and dispatched for all main
* loops associated with that GMainContext.
+ *
* GTK+ contains wrappers of some of these functions, e.g. gtk_main(),
* gtk_main_quit() and gtk_events_pending().
+ *
* <refsect2><title>Creating new source types</title>
* <para>One of the unusual features of the #GMainLoop functionality
* is that new types of event source can be created and used in
@@ -8449,6 +8861,7 @@
* Full-scale XML parsers should be able to parse the subset used by
* GMarkup, so you can easily migrate to full-scale XML at a later
* time if the need arises.
+ *
* GMarkup is not guaranteed to signal an error on all invalid XML;
* the parser may accept documents that an XML parser would not.
* However, XML documents which are not well-formed<footnote
@@ -8456,6 +8869,7 @@
* valid. See the <ulink url="http://www.w3.org/TR/REC-xml/";>XML
* specification</ulink> for definitions of these terms.</footnote>
* are not considered valid GMarkup documents.
+ *
* Simplifications to XML include:
* <itemizedlist>
* <listitem>Only UTF-8 encoding is allowed</listitem>
@@ -8464,6 +8878,7 @@
* are "passed through" but are not interpreted in any way</listitem>
* <listitem>No DTD or validation.</listitem>
* </itemizedlist>
+ *
* The markup format does support:
* <itemizedlist>
* <listitem>Elements</listitem>
@@ -8483,10 +8898,12 @@
* @Title: Memory Allocation
*
* These functions provide support for allocating and freeing memory.
+ *
* <note>
* If any call to allocate memory fails, the application is terminated.
* This also means that there is no need to check if the call succeeded.
* </note>
+ *
* <note>
* It's important to match g_malloc() with g_free(), plain malloc() with free(),
* and (if you're using C++) new with delete and new[] with delete[]. Otherwise
@@ -8511,6 +8928,7 @@
* allocator</link>, which has been added in 2.10. All internal uses of
* memory chunks in GLib have been converted to the
* <literal>g_slice</literal> API.
+ *
* There are two types of memory chunks, #G_ALLOC_ONLY, and
* #G_ALLOC_AND_FREE. <itemizedlist> <listitem><para> #G_ALLOC_ONLY
* chunks only allow allocation of atoms. The atoms can never be freed
@@ -8520,27 +8938,36 @@
* that the memory chunk has to keep track of which atoms have been
* freed. This results in more memory being used and a slight
* degradation in performance. </para></listitem> </itemizedlist>
+ *
* To create a memory chunk use g_mem_chunk_new() or the convenience
* macro g_mem_chunk_create().
+ *
* To allocate a new atom use g_mem_chunk_alloc(),
* g_mem_chunk_alloc0(), or the convenience macros g_chunk_new() or
* g_chunk_new0().
+ *
* To free an atom use g_mem_chunk_free(), or the convenience macro
* g_chunk_free(). (Atoms can only be freed if the memory chunk is
* created with the type set to #G_ALLOC_AND_FREE.)
+ *
* To free any blocks of memory which are no longer being used, use
* g_mem_chunk_clean(). To clean all memory chunks, use g_blow_chunks().
+ *
* To reset the memory chunk, freeing all of the atoms, use
* g_mem_chunk_reset().
+ *
* To destroy a memory chunk, use g_mem_chunk_destroy().
+ *
* To help debug memory chunks, use g_mem_chunk_info() and
* g_mem_chunk_print().
+ *
* <example>
* <title>Using a #GMemChunk</title>
* <programlisting>
* GMemChunk *mem_chunk;
* gchar *mem[10000];
* gint i;
+ *
* /<!-- -->* Create a GMemChunk with atoms 50 bytes long, and memory
* blocks holding 100 bytes. Note that this means that only 2 atoms
* fit into each memory block and so isn't very efficient. *<!-- -->/
@@ -8563,6 +8990,7 @@
* g_mem_chunk_destroy (mem_chunk);
* </programlisting>
* </example>
+ *
* <example>
* <title>Using a #GMemChunk with data structures</title>
* <programlisting>
@@ -8578,6 +9006,8 @@
* array->data = NULL;
* array->len = 0;
* array->alloc = 0;
+ * array->zero_terminated = (zero_terminated ? 1 : 0);
+ * array->clear = (clear ? 1 : 0);
* array->elt_size = elt_size;
* /<!-- -->* We can free the element, so it can be reused. *<!-- -->/
* g_chunk_free (array, array_mem_chunk);
@@ -8585,9 +9015,6 @@
* g_mem_chunk_destroy (array_mem_chunk);
* </programlisting>
* </example>
- *
- * Array->zero_terminated = (zero_terminated ? 1 : 0);
- * Array->clear = (clear ? 1 : 0);
*/
@@ -8608,7 +9035,9 @@
* The GOption commandline parser is intended to be a simpler replacement
* for the popt library. It supports short and long commandline options,
* as shown in the following example:
+ *
* <literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal>
+ *
* The example demonstrates a number of features of the GOption
* commandline parser
* <itemizedlist><listitem><para>
@@ -8629,6 +9058,7 @@
* any remaining arguments (even those starting with a dash) are returned
* to the application as rest arguments.
* </para></listitem></itemizedlist>
+ *
* Another important feature of GOption is that it can automatically
* generate nicely formatted help output. Unless it is explicitly turned
* off with g_option_context_set_help_enabled(), GOption will recognize
@@ -8638,13 +9068,16 @@
* (where <replaceable>groupname</replaceable> is the name of a
* #GOptionGroup) and write a text similar to the one shown in the
* following example to stdout.
+ *
* <informalexample><screen>
* Usage:
* testtreemodel [OPTION...] - test tree model performance
+ *
* Help Options:
* -h, --help Show help options
* --help-all Show all help options
* --help-gtk Show GTK+ Options
+ *
* Application Options:
* -r, --repeats=N Average over N repetitions
* -m, --max-size=M Test up to 2^M items
@@ -8653,24 +9086,29 @@
* -b, --beep Beep when done
* --rand Randomize the data
* </screen></informalexample>
+ *
* GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to
* incorporate options from multiple sources. The intended use for this is
* to let applications collect option groups from the libraries it uses,
* add them to their #GOptionContext, and parse all options by a single call
* to g_option_context_parse(). See gtk_get_option_group() for an example.
+ *
* If an option is declared to be of type string or filename, GOption takes
* care of converting it to the right encoding; strings are returned in
* UTF-8, filenames are returned in the GLib filename encoding. Note that
* this only works if setlocale() has been called before
* g_option_context_parse().
+ *
* Here is a complete example of setting up GOption to parse the example
* commandline above and produce the example help output.
+ *
* <informalexample><programlisting>
* static gint repeats = 2;
* static gint max_size = 8;
* static gboolean verbose = FALSE;
* static gboolean beep = FALSE;
* static gboolean rand = FALSE;
+ *
* static GOptionEntry entries[] =
* {
* { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
@@ -8680,23 +9118,26 @@
* { "rand", 0, 0, G_OPTION_ARG_NONE, &rand, "Randomize the data", NULL },
* { NULL }
* };
+ *
* int
* main (int argc, char *argv[])
* {
* GError *error = NULL;
* GOptionContext *context;
+ *
* context = g_option_context_new ("- test tree model performance");
* g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
* g_option_context_add_group (context, gtk_get_option_group (TRUE));
* if (!g_option_context_parse (context, &argc, &argv, &error))
* {
+ * g_print ("option parsing failed: %s\n", error->message);
* exit (1);
* }
+ *
* /* ... */
+ *
* }
* </programlisting></informalexample>
- *
- * G_print ("option parsing failed: %s\n", error->message);
*/
@@ -8707,19 +9148,20 @@
*
* The <function>g_pattern_match*</function> functions match a string
* against a pattern containing '*' and '?' wildcards with similar
+ * semantics as the standard glob() function: '*' matches an arbitrary,
* possibly empty, string, '?' matches an arbitrary character.
+ *
* Note that in contrast to glob(), the '/' character
* <emphasis>can</emphasis> be matched by the wildcards, there are no
* '[...]' character ranges and '*' and '?' can
* <emphasis>not</emphasis> be escaped to include them literally in a
* pattern.
+ *
* When multiple strings must be matched against the same pattern, it
* is better to compile the pattern to a #GPatternSpec using
* g_pattern_spec_new() and use g_pattern_match_string() instead of
* g_pattern_match_simple(). This avoids the overhead of repeated
* pattern compilation.
- *
- * Semantics as the standard glob() function: '*' matches an arbitrary,
*/
@@ -8731,15 +9173,20 @@
* Quarks are associations between strings and integer identifiers.
* Given either the string or the #GQuark identifier it is possible to
* retrieve the other.
+ *
* Quarks are used for both <link
* linkend="glib-Datasets">Datasets</link> and <link
* linkend="glib-Keyed-Data-Lists">Keyed Data Lists</link>.
+ *
* To create a new quark from a string, use g_quark_from_string() or
* g_quark_from_static_string().
+ *
* To find the string corresponding to a given #GQuark, use
* g_quark_to_string().
+ *
* To find the #GQuark corresponding to a given string, use
* g_quark_try_string().
+ *
* Another use for the string pool maintained for the quark functions
* is string interning, using g_intern_string() or
* g_intern_static_string(). An interned string is a canonical
@@ -8757,15 +9204,21 @@
* The #GQueue structure and its associated functions provide a standard
* queue data structure. Internally, GQueue uses the same data structure
* as #GList to store elements.
+ *
* The data contained in each element can be either integer values, by
* using one of the <link linkend="glib-Type-Conversion-Macros">Type
* Conversion Macros</link>, or simply pointers to any type of data.
+ *
* To create a new GQueue, use g_queue_new().
+ *
* To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or
* g_queue_init().
+ *
* To add elements, use g_queue_push_head(), g_queue_push_head_link(),
* g_queue_push_tail() and g_queue_push_tail_link().
+ *
* To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
+ *
* To free the entire queue, use g_queue_free().
*/
@@ -8781,6 +9234,7 @@
* Nishimura. Further information can be found at
* <ulink url="http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html";>
* http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html</ulink>.
+ *
* If you just need a random number, you simply call the
* <function>g_random_*</function> functions, which will create a
* globally used #GRand and use the according
@@ -8791,10 +9245,12 @@
* with a certain seed will produce exactly the same series of random
* numbers on all platforms. This can thus be used as a seed for e.g.
* games.
+ *
* The <function>g_rand*_range</function> functions will return high
* quality equally distributed random numbers, whereas for example the
* <literal>(g_random_int()%max)</literal> approach often
* doesn't yield equally distributed numbers.
+ *
* GLib changed the seeding algorithm for the pseudo-random number
* generator Mersenne Twister, as used by
* <structname>GRand</structname> and <structname>GRandom</structname>.
@@ -8802,6 +9258,7 @@
* pseudo-random streams. Also the pseudo-random integers generated by
* <function>g_rand*_int_range()</function> will have a slightly better
* equal distribution with the new version of GLib.
+ *
* The original seeding and generation algorithms, as found in GLib
* 2.0.x, can be used instead of the new ones by setting the
* environment variable <envar>G_RANDOM_VERSION</envar> to the value of
@@ -8820,26 +9277,37 @@
* a number of records, called tuples. Each record contains a number of
* fields. Records are not ordered, so it is not possible to find the
* record at a particular index.
+ *
* Note that #GRelation tables are currently limited to 2 fields.
+ *
* To create a GRelation, use g_relation_new().
+ *
* To specify which fields should be indexed, use g_relation_index().
* Note that this must be called before any tuples are added to the
* #GRelation.
+ *
* To add records to a #GRelation use g_relation_insert().
+ *
* To determine if a given record appears in a #GRelation, use
* g_relation_exists(). Note that fields are compared directly, so
* pointers must point to the exact same position (i.e. different
* copies of the same string will not match.)
+ *
* To count the number of records which have a particular value in a
* given field, use g_relation_count().
+ *
* To get all the records which have a particular value in a given
* field, use g_relation_select(). To access fields of the resulting
* records, use g_tuples_index(). To free the resulting records use
* g_tuples_destroy().
+ *
* To delete all records which have a particular value in a given
* field, use g_relation_delete().
+ *
* To destroy the #GRelation, use g_relation_destroy().
+ *
* To help debug #GRelation objects, use g_relation_print().
+ *
* GRelation has been marked as deprecated, since this API has never
* been fully implemented, is not very actively maintained and rarely
* used.
@@ -8858,6 +9326,7 @@
* values, by using of the <link
* linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
* or simply pointers to any type of data.
+ *
* A #GSequence is accessed through <firstterm>iterators</firstterm>,
* represented by a #GSequenceIter. An iterator represents a position
* between two elements of the sequence. For example, the
@@ -8866,15 +9335,18 @@
* <firstterm>end</firstterm> iterator represents the gap immediately
* after the last element. In an empty sequence, the begin and end
* iterators are the same.
+ *
* Some methods on #GSequence operate on ranges of items. For example
* g_sequence_foreach_range() will call a user-specified function on
* each element with the given range. The range is delimited by the
* gaps represented by the passed-in iterators, so if you pass in the
* begin and end iterators, the range in question is the entire
* sequence.
+ *
* The function g_sequence_get() is used with an iterator to access the
* element immediately following the gap that the iterator represents.
* The iterator is said to <firstterm>point</firstterm> to that element.
+ *
* Iterators are stable across most operations on a #GSequence. For
* example an iterator pointing to some element of a sequence will
* continue to point to that element even after the sequence is sorted.
@@ -8912,16 +9384,22 @@
* allocated in blocks, and as strings are added to the #GStringChunk
* they are copied into the next free position in a block. When a block
* is full a new block is allocated.
+ *
* When storing a large number of strings, string chunks are more
* efficient than using g_strdup() since fewer calls to malloc() are
* needed, and less memory is wasted in memory allocation overheads.
+ *
* By adding strings with g_string_chunk_insert_const() it is also
* possible to remove duplicates.
+ *
* To create a new #GStringChunk use g_string_chunk_new().
+ *
* To add strings to a #GStringChunk use g_string_chunk_insert().
+ *
* To add strings to a #GStringChunk, but without duplicating strings
* which are already in the #GStringChunk, use
* g_string_chunk_insert_const().
+ *
* To free the entire #GStringChunk use g_string_chunk_free(). It is
* not possible to free individual strings.
*/
@@ -8939,18 +9417,23 @@
* too high. In such cases reusing already started threads seems like a
* good idea. And it indeed is, but implementing this can be tedious
* and error-prone.
+ *
* Therefore GLib provides thread pools for your convenience. An added
* advantage is, that the threads can be shared between the different
* subsystems of your program, when they are using GLib.
+ *
* To create a new thread pool, you use g_thread_pool_new(). It is
* destroyed by g_thread_pool_free().
+ *
* If you want to execute a certain task within a thread pool, you call
* g_thread_pool_push().
+ *
* To get the current number of running threads you call
* g_thread_pool_get_num_threads(). To get the number of still
* unprocessed tasks you call g_thread_pool_unprocessed(). To control
* the maximal number of threads for a thread pool, you use
* g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads().
+ *
* Finally you can control the number of unused threads, that are kept
* alive by GLib for future use. The current number can be fetched with
* g_thread_pool_get_num_unused_threads(). The maximal number can be
@@ -8975,6 +9458,7 @@
* assumptions on the order of execution of code running in different
* threads can be made, unless order is explicitly forced by the
* programmer through synchronization primitives.
+ *
* The aim of the thread related functions in GLib is to provide a
* portable means for writing multi-threaded software. There are
* primitives for mutexes to protect the access to portions of memory
@@ -8987,23 +9471,27 @@
* initialization (#GOnce, g_once_init_enter()). Last but definitely
* not least there are primitives to portably create and manage
* threads (#GThread).
+ *
* The threading system is initialized with g_thread_init(), which
* takes an optional custom thread implementation or %NULL for the
* default implementation. If you want to call g_thread_init() with a
* non-%NULL argument this must be done before executing any other GLib
* functions (except g_mem_set_vtable()). This is a requirement even if
* no threads are in fact ever created by the process.
+ *
* Calling g_thread_init() with a %NULL argument is somewhat more
* relaxed. You may call any other glib functions in the main thread
* before g_thread_init() as long as g_thread_init() is not called from
* a glib callback, or with any locks held. However, many libraries
* above glib does not support late initialization of threads, so doing
* this should be avoided if possible.
+ *
* Please note that since version 2.24 the GObject initialization
* function g_type_init() initializes threads (with a %NULL argument),
* so most applications, including those using Gtk+ will run with
* threads enabled. If you want a special thread implementation, make
* sure you call g_thread_init() before g_type_init() is called.
+ *
* After calling g_thread_init(), GLib is completely thread safe (all
* global data is automatically locked), but individual data structure
* instances are not automatically locked for performance reasons. So,
@@ -9012,6 +9500,7 @@
* are #GMainLoop and #GAsyncQueue, which <emphasis>are</emphasis>
* threadsafe and need no further application-level locking to be
* accessed from multiple threads.
+ *
* To help debugging problems in multithreaded applications, GLib
* supports error-checking mutexes that will give you helpful error
* messages on common problems. To use error-checking mutexes, define
@@ -9039,21 +9528,24 @@
*
* #GTimeZone is a structure that represents a time zone, at no
* particular point in time. It is refcounted and immutable.
+ *
* A time zone contains a number of intervals. Each interval has
* an abbreviation to describe it, an offet to UTC and a flag indicating
* if the daylight savings time is in effect during that interval. A
* time zone always has at least one interval -- interval 0.
+ *
* Every UTC time is contained within exactly one interval, but a given
* local time may be contained within zero, one or two intervals (due to
* incontinuities associated with daylight savings time).
+ *
+ * An interval may refer to a specific period of time (eg: the duration
* of daylight savings time during 2010) or it may refer to many periods
+ * of time that share the same properties (eg: all periods of daylight
* savings time). It is also possible (usually for political reasons)
* that some properties (like the abbreviation) change between intervals
* without other properties changing.
- * #GTimeZone is available since GLib 2.26.
*
- * An interval may refer to a specific period of time (eg: the duration
- * Of time that share the same properties (eg: all periods of daylight
+ * #GTimeZone is available since GLib 2.26.
*/
@@ -9065,15 +9557,22 @@
* The #GTree structure and its associated functions provide a sorted
* collection of key/value pairs optimized for searching and traversing
* in order.
+ *
* To create a new #GTree use g_tree_new().
+ *
* To insert a key/value pair into a #GTree use g_tree_insert().
+ *
* To lookup the value corresponding to a given key, use
* g_tree_lookup() and g_tree_lookup_extended().
+ *
* To find out the number of nodes in a #GTree, use g_tree_nnodes(). To
* get the height of a #GTree, use g_tree_height().
+ *
* To traverse a #GTree, calling a function for each node visited in
* the traversal, use g_tree_foreach().
+ *
* To remove a key/value pair use g_tree_remove().
+ *
* To destroy a #GTree, use g_tree_destroy().
*/
@@ -9085,23 +9584,31 @@
*
* The #GNode struct and its associated functions provide a N-ary tree
* data structure, where nodes in the tree can contain arbitrary data.
+ *
* To create a new tree use g_node_new().
+ *
* To insert a node into a tree use g_node_insert(),
* g_node_insert_before(), g_node_append() and g_node_prepend().
+ *
* To create a new node and insert it into a tree use
* g_node_insert_data(), g_node_insert_data_before(),
* g_node_append_data() and g_node_prepend_data().
+ *
* To reverse the children of a node use g_node_reverse_children().
+ *
* To find a node use g_node_get_root(), g_node_find(),
* g_node_find_child(), g_node_child_index(), g_node_child_position(),
* g_node_first_child(), g_node_last_child(), g_node_nth_child(),
* g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling()
* or g_node_last_sibling().
+ *
* To get information about a node or tree use G_NODE_IS_LEAF(),
* G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(),
* g_node_n_children(), g_node_is_ancestor() or g_node_max_height().
+ *
* To traverse a tree, calling a function for each node visited in the
* traversal, use g_node_traverse() or g_node_children_foreach().
+ *
* To remove a node or subtree from a tree use g_node_unlink() or
* g_node_destroy().
*/
@@ -9120,6 +9627,7 @@
* functions, functions to perform normalization, case conversion and
* collation on UTF-8 strings and finally functions to convert between
* the UTF-8, UTF-16 and UCS-4 encodings of Unicode.
+ *
* The implementations of the Unicode functions in GLib are based
* on the Unicode Character Data tables, which are available from
* <ulink url="http://www.unicode.org/";>www.unicode.org</ulink>.
@@ -9146,6 +9654,7 @@
* @Short_description: functions to output messages and help debug applications
*
* These functions provide support for outputting messages.
+ *
* The <function>g_return</function> family of macros (g_return_if_fail(),
* g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached())
* should only be used for programming errors, a typical use case is
@@ -9176,13 +9685,16 @@
* A wrapper for the POSIX access() function. This function is used to
* test a pathname for one or several of read, write or execute
* permissions, or just existence.
+ *
* On Windows, the file protection mechanism is not at all POSIX-like,
* and the underlying function in the C library only checks the
* FAT-style READONLY attribute, and does not look at the ACL of a
* file at all. This function is this in practise almost useless on
* Windows. Software that needs to handle file permissions on Windows
* more exactly should use the Win32 API.
+ *
* See your C library manual for more details about access().
+ *
* object that has all the tested permissions, or -1 otherwise or on
* error.
*
@@ -9236,9 +9748,9 @@
* @allocator: a #GAllocator.
*
* Frees all of the memory allocated by the #GAllocator.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -9249,9 +9761,9 @@
* @Returns: a new #GAllocator.
*
* Creates a new #GAllocator.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -9263,6 +9775,7 @@
*
* Adds the value on to the end of the array. The array will grow in
* size automatically if necessary.
+ *
* <note><para>g_array_append_val() is a macro which uses a reference
* to the value parameter @v. This means that you cannot use it with
* literal values such as "27". You must use variables.</para></note>
@@ -9293,6 +9806,7 @@
* underlying array for use elsewhere. If the reference count of @array
* is greater than one, the #GArray wrapper is preserved but the size
* of @array will be set to zero.
+ *
* <note><para>If array elements contain dynamically-allocated memory,
* they should be freed separately.</para></note>
*/
@@ -9318,6 +9832,7 @@
*
* Returns the element of a #GArray at the given index. The return
* value is cast to the given type.
+ *
* <example>
* <title>Getting a pointer to an element in a #GArray</title>
* <programlisting>
@@ -9338,6 +9853,7 @@
* @Returns: the #GArray.
*
* Inserts an element into an array at the given index.
+ *
* <note><para>g_array_insert_val() is a macro which uses a reference
* to the value parameter @v. This means that you cannot use it with
* literal values such as "27". You must use variables.</para></note>
@@ -9375,9 +9891,11 @@
*
* Adds the value on to the start of the array. The array will grow in
* size automatically if necessary.
+ *
* This operation is slower than g_array_append_val() since the
* existing elements in the array have to be moved to make space for
* the new element.
+ *
* <note><para>g_array_prepend_val() is a macro which uses a reference
* to the value parameter @v. This means that you cannot use it with
* literal values such as "27". You must use variables.</para></note>
@@ -9392,6 +9910,7 @@
* @Returns: the #GArray.
*
* Adds @len elements onto the start of the array.
+ *
* This operation is slower than g_array_append_vals() since the
* existing elements in the array have to be moved to make space for
* the new elements.
@@ -9483,6 +10002,7 @@
* comparison function (returns less than zero for first arg is less
* than second arg, zero for equal, greater zero if first arg is
* greater than second arg).
+ *
* If two array elements compare equal, their order in the sorted array
* is undefined. If you want equal elements to keep their order – i.e.
* you want a stable sort – you can write a comparison function that,
@@ -9523,6 +10043,7 @@
* digit. Differs from g_unichar_digit_value() because it takes
* a char, so there's no worry about sign extension if characters
* are signed.
+ *
* g_ascii_isdigit()), its numeric value. Otherwise, -1.
*
* Returns: If @c is a decimal digit (according to
@@ -9537,6 +10058,7 @@
*
* Converts a #gdouble to a string, using the '.' as
* decimal point.
+ *
* This functions generates enough precision that converting
* the string back using g_ascii_strtod() gives the same machine-number
* (on machines with IEEE compatible 64bit doubles). It is
@@ -9558,6 +10080,7 @@
* decimal point. To format the number you pass in
* a printf()-style format string. Allowed conversion
* specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
+ *
* If you just want to want to serialize the value into a
* string, use g_ascii_dtostr().
*
@@ -9571,9 +10094,11 @@
* @s2: string to compare with @s1.
*
* Compare two strings, ignoring the case of ASCII characters.
+ *
* Unlike the BSD strcasecmp() function, this only recognizes standard
* ASCII letters and ignores the locale, treating all non-ASCII
* bytes as if they are not letters.
+ *
* This function should be used only on strings that are known to be
* in encodings where the bytes corresponding to ASCII letters always
* represent themselves. This includes UTF-8 and the ISO-8859-*
@@ -9581,6 +10106,7 @@
* Windows Codepage 932, where the trailing bytes of double-byte
* characters include all ASCII letters. If you compare two CP932
* strings using this function, you will get false matches.
+ *
* or a positive value if @s1 > @s2.
*
* Returns: 0 if the strings match, a negative value if @s1 < @s2,
@@ -9593,6 +10119,7 @@
* @len: length of @str in bytes, or -1 if @str is nul-terminated.
*
* Converts all upper case ASCII letters to lower case ASCII letters.
+ *
* characters in @str converted to lower case, with
* semantics that exactly match g_ascii_tolower(). (Note
* that this is unlike the old g_strdown(), which modified
@@ -9610,14 +10137,17 @@
*
* Compare @s1 and @s2, ignoring the case of ASCII characters and any
* characters after the first @n in each string.
+ *
* Unlike the BSD strcasecmp() function, this only recognizes standard
* ASCII letters and ignores the locale, treating all non-ASCII
* characters as if they are not letters.
+ *
+ * The same warning as in g_ascii_strcasecmp() applies: Use this
* function only on strings known to be in encodings where bytes
* corresponding to ASCII letters always represent themselves.
+ *
* or a positive value if @s1 > @s2.
*
- * The same warning as in g_ascii_strcasecmp() applies: Use this
* Returns: 0 if the strings match, a negative value if @s1 < @s2,
*/
@@ -9628,21 +10158,26 @@
* @endptr: if non-%NULL, it returns the character after the last character used in the conversion.
*
* Converts a string to a #gdouble value.
+ *
* This function behaves like the standard strtod() function
* does in the C locale. It does this without actually changing
* the current locale, since that would not be thread-safe.
* A limitation of the implementation is that this function
* will still accept localized versions of infinities and NANs.
+ *
* This function is typically used when reading configuration
* files or other non-user input that should be locale independent.
* To handle input from the user you should normally use the
* locale-sensitive system strtod() function.
+ *
* To convert from a #gdouble to a string in a locale-insensitive
* way, use g_ascii_dtostr().
+ *
* If the correct value would cause overflow, plus or minus %HUGE_VAL
* is returned (according to the sign of the value), and %ERANGE is
* stored in %errno. If the correct value would cause underflow,
* zero is returned and %ERANGE is stored in %errno.
+ *
* This function resets %errno before calling strtod() so that
* you can reliably detect overflow and underflow.
*
@@ -9661,14 +10196,17 @@
* does in the C locale. It does this without actually
* changing the current locale, since that would not be
* thread-safe.
+ *
* This function is typically used when reading configuration
* files or other non-user input that should be locale independent.
* To handle input from the user you should normally use the
* locale-sensitive system strtoll() function.
+ *
* If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
* is returned, and %ERANGE is stored in %errno. If the base is
* outside the valid range, zero is returned, and %EINVAL is stored
* in %errno. If the string conversion fails, zero is returned, and
+ * @endptr returns @nptr (if @endptr is non-%NULL).
*
* Returns: the #gint64 value or zero on error.
* Since: 2.12
@@ -9686,14 +10224,17 @@
* does in the C locale. It does this without actually
* changing the current locale, since that would not be
* thread-safe.
+ *
* This function is typically used when reading configuration
* files or other non-user input that should be locale independent.
* To handle input from the user you should normally use the
* locale-sensitive system strtoull() function.
+ *
* If the correct value would cause overflow, %G_MAXUINT64
* is returned, and %ERANGE is stored in %errno. If the base is
* outside the valid range, zero is returned, and %EINVAL is stored
* in %errno. If the string conversion fails, zero is returned, and
+ * @endptr returns @nptr (if @endptr is non-%NULL).
*
* Returns: the #guint64 value or zero on error.
* Since: 2.2
@@ -9706,6 +10247,7 @@
* @len: length of @str in bytes, or -1 if @str is nul-terminated.
*
* Converts all lower case ASCII letters to upper case ASCII letters.
+ *
* characters in @str converted to upper case, with
* semantics that exactly match g_ascii_toupper(). (Note
* that this is unlike the old g_strup(), which modified
@@ -9720,6 +10262,7 @@
* @c: any character.
*
* Convert a character to ASCII lower case.
+ *
* Unlike the standard C library tolower() function, this only
* recognizes standard ASCII letters and ignores the locale, returning
* all non-ASCII characters unchanged, even if they are lower case
@@ -9727,7 +10270,9 @@
* library function, this takes and returns a char, not an int, so
* don't call it on %EOF but no need to worry about casting to #guchar
* before passing a possibly non-ASCII character in.
+ *
* If @c is not an ASCII upper case letter,
+ * @c is returned unchanged.
*
* Returns: the result of converting @c to lower case.
*/
@@ -9738,6 +10283,7 @@
* @c: any character.
*
* Convert a character to ASCII upper case.
+ *
* Unlike the standard C library toupper() function, this only
* recognizes standard ASCII letters and ignores the locale, returning
* all non-ASCII characters unchanged, even if they are upper case
@@ -9745,7 +10291,9 @@
* library function, this takes and returns a char, not an int, so
* don't call it on %EOF but no need to worry about casting to #guchar
* before passing a possibly non-ASCII character in.
+ *
* If @c is not an ASCII lower case letter,
+ * @c is returned unchanged.
*
* Returns: the result of converting @c to upper case.
*/
@@ -9759,6 +10307,7 @@
* digit. Differs from g_unichar_xdigit_value() because it takes
* a char, so there's no worry about sign extension if characters
* are signed.
+ *
* g_ascii_isxdigit()), its numeric value. Otherwise, -1.
*
* Returns: If @c is a hex digit (according to
@@ -9771,6 +10320,7 @@
*
* Returns the length of the queue, negative values mean waiting
* threads, positive values mean available entries in the
+ * @queue. Actually this function returns the number of data items in
* the queue minus the number of waiting threads. Thus a return value
* of 0 could mean 'n' entries in the queue and 'n' thread waiting.
* That can happen due to locking of the queue or due to
@@ -9786,6 +10336,7 @@
*
* Returns the length of the queue, negative values mean waiting
* threads, positive values mean available entries in the
+ * @queue. Actually this function returns the number of data items in
* the queue minus the number of waiting threads. Thus a return value
* of 0 could mean 'n' entries in the queue and 'n' thread waiting.
* That can happen due to locking of the queue or due to
@@ -9802,6 +10353,7 @@
*
* Acquires the @queue's lock. After that you can only call the
* <function>g_async_queue_*_unlocked()</function> function variants on that
+ * @queue. Otherwise it will deadlock.
*/
@@ -9868,10 +10420,13 @@
*
* Inserts @data into @queue using @func to determine the new
* position.
+ *
* This function requires that the @queue is sorted before pushing on
* new elements.
+ *
* This function will lock @queue before it sorts the queue and unlock
* it when it is finished.
+ *
* For an example of @func see g_async_queue_sort().
*
* Since: 2.10
@@ -9887,9 +10442,12 @@
*
* Inserts @data into @queue using @func to determine the new
* position.
+ *
* This function requires that the @queue is sorted before pushing on
* new elements.
+ *
* This function is called while holding the @queue's lock.
+ *
* For an example of @func see g_async_queue_sort().
*
* Since: 2.10
@@ -9923,6 +10481,7 @@
* @Deprecated: Since 2.8, reference counting is done atomically
*
* Increases the reference count of the asynchronous @queue by 1.
+ *
* so g_async_queue_ref() can be used regardless of the @queue's
* lock.
*/
@@ -9935,18 +10494,22 @@
* @user_data: user data passed to @func
*
* Sorts @queue using @func.
+ *
* This function will lock @queue before it sorts the queue and unlock
* it when it is finished.
+ *
* If you were sorting a list of priority numbers to make sure the
* lowest priority would be at the top of the queue, you could use:
* |[
* gint32 id1;
* gint32 id2;
+ *
* id1 = GPOINTER_TO_INT (element1);
* id2 = GPOINTER_TO_INT (element2);
+ *
+ * return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
* ]|
*
- * Return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
* Since: 2.10
*/
@@ -9958,6 +10521,7 @@
* @user_data: user data passed to @func
*
* Sorts @queue using @func.
+ *
* This function is called while holding the @queue's lock.
*
* Since: 2.10
@@ -9971,8 +10535,10 @@
*
* Pops data from the @queue. If no data is received before @end_time,
* %NULL is returned.
+ *
* To easily calculate @end_time a combination of g_get_current_time()
* and g_time_val_add() can be used.
+ *
* received before @end_time.
*
* Returns: data from the queue or %NULL, when no data is
@@ -9986,8 +10552,11 @@
*
* Pops data from the @queue. If no data is received before @end_time,
* %NULL is returned. This function must be called while holding the
+ * @queue's lock.
+ *
* To easily calculate @end_time a combination of g_get_current_time()
* and g_time_val_add() can be used.
+ *
* received before @end_time.
*
* Returns: data from the queue or %NULL, when no data is
@@ -10000,6 +10569,7 @@
*
* Tries to pop data from the @queue. If no data is available, %NULL is
* returned.
+ *
* available immediately.
*
* Returns: data from the queue or %NULL, when no data is
@@ -10013,6 +10583,7 @@
* Tries to pop data from the @queue. If no data is available, %NULL is
* returned. This function must be called while holding the @queue's
* lock.
+ *
* available immediately.
*
* Returns: data from the queue or %NULL, when no data is
@@ -10034,6 +10605,7 @@
* Decreases the reference count of the asynchronous @queue by 1. If
* the reference count went to 0, the @queue will be destroyed and the
* memory allocated will be freed. So you are not allowed to use the
+ * @queue afterwards, as it might have disappeared. You do not need to
* hold the lock to call this function.
*/
@@ -10045,7 +10617,9 @@
*
* Decreases the reference count of the asynchronous @queue by 1 and
* releases the lock. This function must be called while holding the
+ * @queue's lock. If the reference count went to 0, the @queue will be
* destroyed and the memory allocated will be freed.
+ *
* so g_async_queue_unref() can be used regardless of the @queue's
* lock.
*/
@@ -10056,6 +10630,7 @@
* @func: (scope async): the function to call on normal program termination.
*
* Specifies a function to be called at normal program termination.
+ *
* Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor
* macro that maps to a call to the atexit() function in the C
* library. This means that in case the code that calls g_atexit(),
@@ -10064,18 +10639,23 @@
* than that the function is called when the GLib DLL is detached,
* which happened earlier when g_atexit() was a function in the GLib
* DLL.
+ *
* The behaviour of atexit() in the context of dynamically loaded
* modules is not formally specified and varies wildly.
+ *
* On POSIX systems, calling g_atexit() (or atexit()) in a dynamically
* loaded module which is unloaded before the program terminates might
* well cause a crash at program exit.
+ *
* Some POSIX systems implement atexit() like Windows, and have each
* dynamically loaded module maintain an own atexit chain that is
* called when the module is unloaded.
+ *
* On other POSIX systems, before a dynamically loaded module is
* unloaded, the registered atexit functions (if any) residing in that
* module are called, regardless where the code that registered them
* resided. This is presumably the most robust approach.
+ *
* As can be seen from the above, for portability it's best to avoid
* calling g_atexit() (or atexit()) except in the main executable of a
* program.
@@ -10088,9 +10668,12 @@
* @val: the value to add
*
* Atomically adds @val to the value of @atomic.
+ *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; * atomic += @val; return tmp; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
+ *
* Before version 2.30, this function did not return a value
* (but g_atomic_int_exchange_and_add() did, and had the same meaning).
*
@@ -10106,7 +10689,9 @@
*
* Performs an atomic bitwise 'and' of the value of @atomic and @val,
* storing the result back in @atomic.
+ *
* This call acts as a full compiler and hardware memory barrier.
+ *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; * atomic &= @val; return tmp; }</literal>
*
@@ -10123,9 +10708,12 @@
*
* Compares @atomic to @oldval and, if equal, sets it to @newval.
* If @atomic was not equal to @oldval then no change occurs.
+ *
* This compare and exchange is done atomically.
+ *
* Think of this operation as an atomic version of
* <literal>{ if (* atomic == @oldval) { * atomic = @newval; return TRUE; } else return FALSE; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Returns: %TRUE if the exchange took place
@@ -10138,8 +10726,10 @@
* @atomic: a pointer to a #gint or #guint
*
* Decrements the value of @atomic by 1.
+ *
* Think of this operation as an atomic version of
* <literal>{ * atomic -= 1; return (* atomic == 0); }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Returns: %TRUE if the resultant value is zero
@@ -10167,6 +10757,7 @@
* @atomic: a pointer to a #gint or #guint
*
* Gets the current value of @atomic.
+ *
* This call acts as a full compiler and hardware
* memory barrier (before the get).
*
@@ -10180,8 +10771,10 @@
* @atomic: a pointer to a #gint or #guint
*
* Increments the value of @atomic by 1.
+ *
* Think of this operation as an atomic version of
* <literal>{ * atomic += 1; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Since: 2.4
@@ -10195,8 +10788,10 @@
*
* Performs an atomic bitwise 'or' of the value of @atomic and @val,
* storing the result back in @atomic.
+ *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; * atomic |= @val; return tmp; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Returns: the value of @atomic before the operation, unsigned
@@ -10210,6 +10805,7 @@
* @newval: a new value to store
*
* Sets the value of @atomic to @newval.
+ *
* This call acts as a full compiler and hardware
* memory barrier (after the set).
*
@@ -10224,8 +10820,10 @@
*
* Performs an atomic bitwise 'xor' of the value of @atomic and @val,
* storing the result back in @atomic.
+ *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; * atomic ^= @val; return tmp; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Returns: the value of @atomic before the operation, unsigned
@@ -10239,8 +10837,10 @@
* @val: the value to add
*
* Atomically adds @val to the value of @atomic.
+ *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; * atomic += @val; return tmp; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Returns: the value of @atomic before the add, signed
@@ -10255,8 +10855,10 @@
*
* Performs an atomic bitwise 'and' of the value of @atomic and @val,
* storing the result back in @atomic.
+ *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; * atomic &= @val; return tmp; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Returns: the value of @atomic before the operation, unsigned
@@ -10272,9 +10874,12 @@
*
* Compares @atomic to @oldval and, if equal, sets it to @newval.
* If @atomic was not equal to @oldval then no change occurs.
+ *
* This compare and exchange is done atomically.
+ *
* Think of this operation as an atomic version of
* <literal>{ if (* atomic == @oldval) { * atomic = @newval; return TRUE; } else return FALSE; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Returns: %TRUE if the exchange took place
@@ -10287,6 +10892,7 @@
* @atomic: a pointer to a #gpointer-sized value
*
* Gets the current value of @atomic.
+ *
* This call acts as a full compiler and hardware
* memory barrier (before the get).
*
@@ -10302,8 +10908,10 @@
*
* Performs an atomic bitwise 'or' of the value of @atomic and @val,
* storing the result back in @atomic.
+ *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; * atomic |= @val; return tmp; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Returns: the value of @atomic before the operation, unsigned
@@ -10317,6 +10925,7 @@
* @newval: a new value to store
*
* Sets the value of @atomic to @newval.
+ *
* This call acts as a full compiler and hardware
* memory barrier (after the set).
*
@@ -10331,8 +10940,10 @@
*
* Performs an atomic bitwise 'xor' of the value of @atomic and @val,
* storing the result back in @atomic.
+ *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; * atomic ^= @val; return tmp; }</literal>
+ *
* This call acts as a full compiler and hardware memory barrier.
*
* Returns: the value of @atomic before the operation, unsigned
@@ -10346,6 +10957,7 @@
* @out_len: (out): The length of the decoded data is written here
*
* Decode a sequence of Base-64 encoded text into binary data
+ *
* newly allocated buffer containing the binary data
* that @text represents. The returned buffer must
* be freed with g_free().
@@ -10362,6 +10974,7 @@
*
* Decode a sequence of Base-64 encoded text into binary data
* by overwriting the input data.
+ *
* is the same as the input @text.
*
* Returns: (transfer none): The binary data that @text responds. This pointer
@@ -10380,11 +10993,12 @@
* Incrementally decode a sequence of binary data from its Base-64 stringified
* representation. By calling this function multiple times you can convert
* data in chunks to avoid having to have the full encoded data in memory.
+ *
* The output buffer must be large enough to fit all the data that will
* be written to it. Since base64 encodes 3 bytes in 4 chars you need
+ * at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
* state).
*
- * At least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
* Returns: The number of bytes of output that was written
* Since: 2.12
*/
@@ -10397,6 +11011,7 @@
*
* Encode a sequence of binary data into its Base-64 stringified
* representation.
+ *
* encoded string representing @data. The returned string must
* be freed with g_free().
*
@@ -10413,6 +11028,7 @@
* @save: (inout): Saved state from g_base64_encode_step()
*
* Flush the status from a sequence of calls to g_base64_encode_step().
+ *
* The output buffer must be large enough to fit all the data that will
* be written to it. It will need up to 4 bytes, or up to 5 bytes if
* line-breaking is enabled.
@@ -10434,16 +11050,20 @@
* Incrementally encode a sequence of binary data into its Base-64 stringified
* representation. By calling this function multiple times you can convert
* data in chunks to avoid having to have the full encoded data in memory.
+ *
* When all of the data has been converted you must call
* g_base64_encode_close() to flush the saved state.
+ *
* The output buffer must be large enough to fit all the data that will
* be written to it. Due to the way base64 encodes you will need
+ * at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
* non-zero state). If you enable line-breaking you will need at least:
* ((@len / 3 + 1) * 4 + 4) / 72 + 1 bytes of extra space.
+ *
+ * @break_lines is typically used when putting base64-encoded data in emails.
* It breaks the lines at 72 columns instead of putting all of the text on
* the same line. This avoids problems with long lines in the email system.
*
- * At least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
* Returns: The number of bytes of output that was written
* Since: 2.12
*/
@@ -10455,11 +11075,13 @@
*
* Gets the name of the file without any leading directory components.
* It returns a pointer into the given file name string.
+ *
+ *
+ * Deprecated:2.2: Use g_path_get_basename() instead, but notice that
* g_path_get_basename() allocates new memory for the returned string, unlike
* this function which returns a pointer into the argument.
*
* Returns: the name of the file without any leading directory components.
- * Deprecated:2.2: Use g_path_get_basename() instead, but notice that
*/
@@ -10471,11 +11093,15 @@
* Sets the indicated @lock_bit in @address. If the bit is already
* set, this call will block until g_bit_unlock() unsets the
* corresponding bit.
+ *
* Attempting to lock on two different bits within the same integer is
* not supported and will very probably cause deadlocks.
+ *
* The value of the bit that is set is (1u << @bit). If @bit is not
* between 0 and 31 then the result is undefined.
+ *
* This function accesses @address atomically. All other accesses to
+ * @address must be atomic in order for this function to work
* reliably.
*
* Since: 2.24
@@ -10530,11 +11156,15 @@
*
* Sets the indicated @lock_bit in @address, returning %TRUE if
* successful. If the bit is already set, returns %FALSE immediately.
+ *
* Attempting to lock on two different bits within the same integer is
* not supported.
+ *
* The value of the bit that is set is (1u << @bit). If @bit is not
* between 0 and 31 then the result is undefined.
+ *
* This function accesses @address atomically. All other accesses to
+ * @address must be atomic in order for this function to work
* reliably.
*
* Since: 2.24
@@ -10549,7 +11179,9 @@
* Clears the indicated @lock_bit in @address. If another thread is
* currently blocked in g_bit_lock() on this same bit then it will be
* woken up.
+ *
* This function accesses @address atomically. All other accesses to
+ * @address must be atomic in order for this function to work
* reliably.
*
* Since: 2.24
@@ -10560,9 +11192,9 @@
* g_blow_chunks:
*
* Calls g_mem_chunk_clean() on all #GMemChunk objects.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -10575,19 +11207,25 @@
*
* Adds the application with @name and @exec to the list of
* applications that have registered a bookmark for @uri into
+ * @bookmark.
+ *
* Every bookmark inside a #GBookmarkFile must have at least an
* application registered. Each application must provide a name, a
* command line useful for launching the bookmark, the number of times
* the bookmark has been registered by the application and the last
* time the application registered this bookmark.
+ *
* If @name is %NULL, the name of the application will be the
* same returned by g_get_application_name(); if @exec is %NULL, the
* command line will be a composition of the program name as
* returned by g_get_prgname() and the "%u" modifier, which will be
* expanded to the bookmark's URI.
+ *
* This function will automatically take care of updating the
* registrations count and timestamping in case an application
* with the same @name had already registered a bookmark for
+ * @uri inside @bookmark.
+ *
* If no bookmark for @uri is found, one is created.
*
* Since: 2.12
@@ -10602,6 +11240,7 @@
*
* Adds @group to the list of groups to which the bookmark for @uri
* belongs to.
+ *
* If no bookmark for @uri is found then it is created.
*
* Since: 2.12
@@ -10625,7 +11264,9 @@
* @error: return location for a #GError, or %NULL
*
* Gets the time the bookmark for @uri was added to @bookmark
+ *
* In the event the URI cannot be found, -1 is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
* Returns: a timestamp
* Since: 2.12
@@ -10643,9 +11284,13 @@
* @error: return location for a #GError, or %NULL
*
* Gets the registration informations of @app_name for the bookmark for
+ * @uri. See g_bookmark_file_set_app_info() for more informations about
* the returned data.
+ *
* The string returned in @app_exec must be freed.
+ *
* In the event the URI cannot be found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
* event that no application with name @app_name has registered a bookmark
* for @uri, %FALSE is returned and error is set to
* #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting
@@ -10666,7 +11311,10 @@
*
* Retrieves the names of the applications that have registered the
* bookmark for @uri.
+ *
* In the event the URI cannot be found, %NULL is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+ *
* Use g_strfreev() to free it.
*
* Returns: a newly allocated %NULL-terminated array of strings.
@@ -10681,7 +11329,10 @@
* @error: return location for a #GError, or %NULL
*
* Retrieves the description of the bookmark for @uri.
+ *
* In the event the URI cannot be found, %NULL is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+ *
* URI cannot be found.
*
* Returns: a newly allocated string or %NULL if the specified
@@ -10697,9 +11348,13 @@
* @error: return location for a #GError, or %NULL
*
* Retrieves the list of group names of the bookmark for @uri.
+ *
* In the event the URI cannot be found, %NULL is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+ *
* The returned array is %NULL terminated, so @length may optionally
* be %NULL.
+ *
* Use g_strfreev() to free it.
*
* Returns: a newly allocated %NULL-terminated array of group names.
@@ -10716,7 +11371,10 @@
* @error: return location for a #GError or %NULL
*
* Gets the icon of the bookmark for @uri.
+ *
* In the event the URI cannot be found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+ *
* You should free the returned strings.
*
* Returns: %TRUE if the icon for the bookmark for the URI was found.
@@ -10731,8 +11389,11 @@
* @error: return location for a #GError, or %NULL
*
* Gets whether the private flag of the bookmark for @uri is set.
+ *
* In the event the URI cannot be found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
* event that the private flag cannot be found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
*
* Returns: %TRUE if the private flag is set, %FALSE otherwise.
* Since: 2.12
@@ -10746,8 +11407,12 @@
* @error: return location for a #GError, or %NULL
*
* Retrieves the MIME type of the resource pointed by @uri.
+ *
* In the event the URI cannot be found, %NULL is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
* event that the MIME type cannot be found, %NULL is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
+ *
* URI cannot be found.
*
* Returns: a newly allocated string or %NULL if the specified
@@ -10762,7 +11427,9 @@
* @error: return location for a #GError, or %NULL
*
* Gets the time when the bookmark for @uri was last modified.
+ *
* In the event the URI cannot be found, -1 is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
* Returns: a timestamp
* Since: 2.12
@@ -10787,8 +11454,12 @@
* @error: return location for a #GError, or %NULL
*
* Returns the title of the bookmark for @uri.
+ *
* If @uri is %NULL, the title of @bookmark is returned.
+ *
* In the event the URI cannot be found, %NULL is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
+ *
* URI cannot be found.
*
* Returns: a newly allocated string or %NULL if the specified
@@ -10804,6 +11475,7 @@
* Returns all URIs of the bookmarks in the bookmark file @bookmark.
* The array of returned URIs will be %NULL-terminated, so @length may
* optionally be %NULL.
+ *
* Use g_strfreev() to free it.
*
* Returns: a newly allocated %NULL-terminated array of strings.
@@ -10818,7 +11490,9 @@
* @error: return location for a #GError, or %NULL
*
* Gets the time the bookmark for @uri was last visited.
+ *
* In the event the URI cannot be found, -1 is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
* Returns: a timestamp.
* Since: 2.12
@@ -10834,7 +11508,9 @@
*
* Checks whether the bookmark for @uri inside @bookmark has been
* registered by application @name.
+ *
* In the event the URI cannot be found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
* Returns: %TRUE if the application @name was found
* Since: 2.12
@@ -10850,7 +11526,9 @@
*
* Checks whether @group appears in the list of groups to which
* the bookmark for @uri belongs to.
+ *
* In the event the URI cannot be found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
* Returns: %TRUE if @group was found.
* Since: 2.12
@@ -10895,6 +11573,7 @@
* This function looks for a desktop bookmark file named @file in the
* paths returned from g_get_user_data_dir() and g_get_system_data_dirs(),
* loads the file into @bookmark and returns the file's full path in
+ * @full_path. If the file could not be loaded then an %error is
* set to either a #GFileError or #GBookmarkFileError.
*
* Returns: %TRUE if a key file could be loaded, %FALSE othewise
@@ -10927,7 +11606,9 @@
* Changes the URI of a bookmark item from @old_uri to @new_uri. Any
* existing bookmark for @new_uri will be overwritten. If @new_uri is
* %NULL, then the bookmark is removed.
+ *
* In the event the URI cannot be found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
* Returns: %TRUE if the URI was successfully changed
* Since: 2.12
@@ -10938,6 +11619,7 @@
* g_bookmark_file_new:
*
* Creates a new empty #GBookmarkFile object.
+ *
* Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data()
* or g_bookmark_file_load_from_data_dirs() to read an existing bookmark
* file.
@@ -10956,7 +11638,9 @@
*
* Removes application registered with @name from the list of applications
* that have registered a bookmark for @uri inside @bookmark.
+ *
* In the event the URI cannot be found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
* In the event that no application with name @app_name has registered
* a bookmark for @uri, %FALSE is returned and error is set to
* #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.
@@ -10975,8 +11659,11 @@
*
* Removes @group from the list of groups to which the bookmark
* for @uri belongs to.
+ *
* In the event the URI cannot be found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
* In the event no group was defined, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
*
* Returns: %TRUE if @group was successfully removed.
* Since: 2.12
@@ -11003,6 +11690,7 @@
* @added: a timestamp or -1 to use the current time
*
* Sets the time the bookmark for @uri was added into @bookmark.
+ *
* If no bookmark for @uri is found then it is created.
*
* Since: 2.12
@@ -11022,23 +11710,32 @@
*
* Sets the meta-data of application @name inside the list of
* applications that have registered a bookmark for @uri inside
+ * @bookmark.
+ *
* You should rarely use this function; use g_bookmark_file_add_application()
* and g_bookmark_file_remove_application() instead.
+ *
+ * @name can be any UTF-8 encoded string used to identify an
* application.
* be expanded as the local file name retrieved from the bookmark's
* URI; "%u", which will be expanded as the bookmark's URI.
* The expansion is done automatically when retrieving the stored
* command line using the g_bookmark_file_get_app_info() function.
+ * @count is the number of times the application has registered the
* bookmark; if is < 0, the current registration count will be increased
* by one, if is 0, the application with @name will be removed from
* the list of registered applications.
+ * @stamp is the Unix time of the last registration; if it is -1, the
* current time will be used.
+ *
* If you try to remove an application by setting its registration count to
* zero, and no bookmark for @uri is found, %FALSE is returned and
+ * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly,
* in the event that no application @name has registered a bookmark
* for @uri, %FALSE is returned and error is set to
* #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark
* for @uri is found, one is created.
+ *
* changed.
*
* Returns: %TRUE if the application's meta-data was successfully
@@ -11053,7 +11750,9 @@
* @description: a string
*
* Sets @description as the description of the bookmark for @uri.
+ *
* If @uri is %NULL, the description of @bookmark is set.
+ *
* If a bookmark for @uri cannot be found then it is created.
*
* Since: 2.12
@@ -11069,6 +11768,7 @@
*
* Sets a list of group names for the item with URI @uri. Each previously
* set group name list is removed.
+ *
* If @uri cannot be found then an item for it is created.
*
* Since: 2.12
@@ -11085,6 +11785,7 @@
* Sets the icon for the bookmark for @uri. If @href is %NULL, unsets
* the currently set icon. @href can either be a full URL for the icon
* file or the icon name following the Icon Naming specification.
+ *
* If no bookmark for @uri is found one is created.
*
* Since: 2.12
@@ -11098,6 +11799,7 @@
* @is_private: %TRUE if the bookmark should be marked as private
*
* Sets the private flag of the bookmark for @uri.
+ *
* If a bookmark for @uri cannot be found then it is created.
*
* Since: 2.12
@@ -11111,6 +11813,7 @@
* @mime_type: a MIME type
*
* Sets @mime_type as the MIME type of the bookmark for @uri.
+ *
* If a bookmark for @uri cannot be found then it is created.
*
* Since: 2.12
@@ -11124,7 +11827,9 @@
* @modified: a timestamp or -1 to use the current time
*
* Sets the last time the bookmark for @uri was last modified.
+ *
* If no bookmark for @uri is found then it is created.
+ *
* The "modified" time should only be set when the bookmark's meta-data
* was actually changed. Every function of #GBookmarkFile that
* modifies a bookmark also changes the modification time, except for
@@ -11142,7 +11847,9 @@
*
* Sets @title as the title of the bookmark for @uri inside the
* bookmark file @bookmark.
+ *
* If @uri is %NULL, the title of @bookmark is set.
+ *
* If a bookmark for @uri cannot be found then it is created.
*
* Since: 2.12
@@ -11156,7 +11863,9 @@
* @visited: a timestamp or -1 to use the current time
*
* Sets the time the bookmark for @uri was last visited.
+ *
* If no bookmark for @uri is found then it is created.
+ *
* The "visited" time should only be set if the bookmark was launched,
* either using the command line retrieved by g_bookmark_file_get_app_info()
* or by the default application for the bookmark's MIME type, retrieved
@@ -11174,6 +11883,7 @@
* @error: return location for a #GError, or %NULL
*
* This function outputs @bookmark as a string.
+ *
* the contents of the #GBookmarkFile
*
* Returns: a newly allocated string holding
@@ -11202,14 +11912,17 @@
*
* Creates a filename from a series of elements using the correct
* separator for filenames.
+ *
* On Unix, this function behaves identically to <literal>g_build_path
* (G_DIR_SEPARATOR_S, first_element, ....)</literal>.
+ *
* On Windows, it takes into account that either the backslash
* (<literal>\</literal> or slash (<literal>/</literal>) can be used
* as separator in filenames, but otherwise behaves as on Unix. When
* file pathname separators need to be inserted, the one that last
* previously occurred in the parameters (reading from left to right)
* is used.
+ *
* No attempt is made to force the resulting filename to be an absolute
* path. If the first element is a relative path, the result will
* be a relative path.
@@ -11242,20 +11955,25 @@
* any trailing occurrences of separator in the first element, or
* leading occurrences of separator in the second element are removed
* and exactly one copy of the separator is inserted.
+ *
* Empty elements are ignored.
+ *
* The number of leading copies of the separator on the result is
* the same as the number of leading copies of the separator on
* the first non-empty element.
+ *
* The number of trailing copies of the separator on the result is
* the same as the number of trailing copies of the separator on
* the last non-empty element. (Determination of the number of
* trailing copies is done without stripping leading copies, so
* if the separator is <literal>ABA</literal>, <literal>ABABA</literal>
* has 1 trailing copy.)
+ *
* However, if there is only a single non-empty element, and there
* are no characters in that element not part of the leading or
* trailing separators, then the result is exactly the original value
* of that element.
+ *
* Other than for determination of the number of leading and trailing
* copies of the separator, elements consisting only of copies
* of the separator are ignored.
@@ -11298,6 +12016,7 @@
*
* Frees the memory allocated by the #GByteArray. If @free_segment is
* %TRUE it frees the actual byte data. If the reference count of
+ * @array is greater than one, the #GByteArray wrapper is preserved but
* the size of @array will be set to zero.
*/
@@ -11403,6 +12122,7 @@
* qsort()-style comparison function (returns less than zero for first
* arg is less than second arg, zero for equal, greater than zero if
* first arg is greater than second arg).
+ *
* If two array elements compare equal, their order in the sorted array
* is undefined. If you want equal elements to keep their order – i.e.
* you want a stable sort – you can write a comparison function that,
@@ -11440,6 +12160,7 @@
* @cache: a #GCache.
*
* Frees the memory allocated for the #GCache.
+ *
* Note that it does not destroy the keys and values which were
* contained in the #GCache.
*/
@@ -11469,6 +12190,7 @@
* @user_data: user data to pass to the function.
*
* Calls the given function for each of the keys in the #GCache.
+ *
* NOTE @func is passed three parameters, the value and key of a cache
* entry and the @user_data. The order of value and key is different
* from the order in which g_hash_table_foreach() passes key-value
@@ -11498,6 +12220,7 @@
*
* Decreases the reference count of the given value. If it drops to 0
* then the value and its corresponding key are destroyed, using the
+ * @value_destroy_func and @key_destroy_func passed to g_cache_new().
*/
@@ -11508,10 +12231,10 @@
* @user_data: user data to pass to the function.
*
* Calls the given function for each of the values in the #GCache.
- * data structures to @func; use g_cache_key_foreach()
- * instead
*
* Deprecated:2.10: The reason is that it passes pointers to internal
+ * data structures to @func; use g_cache_key_foreach()
+ * instead
*/
@@ -11521,6 +12244,7 @@
*
* A wrapper for the POSIX chdir() function. The function changes the
* current directory of the process to @path.
+ *
* See your C library manual for more details about chdir().
*
* Returns: 0 on success, -1 if an error occurred.
@@ -11535,6 +12259,7 @@
* Copies a #GChecksum. If @checksum has been closed, by calling
* g_checksum_get_string() or g_checksum_get_digest(), the copied
* checksum will be closed as well.
+ *
* when finished using it.
*
* Returns: the copy of the passed #GChecksum. Use g_checksum_free()
@@ -11554,16 +12279,17 @@
/**
* g_checksum_get_digest:
- * @checksum: a #GChecksum
+ * @hmac: a #GHmac
* @buffer: output buffer
- * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest.
+ * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest
*
- * Gets the digest from @checksum as a raw binary vector and places it
+ * Gets the digest from @checksum as a raw binary array and places it
* into @buffer. The size of the digest depends on the type of checksum.
- * Once this function has been called, the #GChecksum is closed and can
+ *
+ * Once this function has been called, the #GHmac is closed and can
* no longer be updated with g_checksum_update().
*
- * Since: 2.16
+ * Since: 2.30
*/
@@ -11572,9 +12298,12 @@
* @checksum: a #GChecksum
*
* Gets the digest as an hexadecimal string.
+ *
* Once this function has been called the #GChecksum can no longer be
* updated with g_checksum_update().
+ *
* The hexadecimal characters will be lower case.
+ *
* returned string is owned by the checksum and should not be modified
* or freed.
*
@@ -11591,6 +12320,7 @@
* If the @checksum_type is not known, %NULL is returned.
* A #GChecksum can be used to compute the checksum, or digest, of an
* arbitrary binary blob, using different hashing algorithms.
+ *
* A #GChecksum works by feeding a binary blob through g_checksum_update()
* until there is data to be checked; the digest can then be extracted
* using g_checksum_get_string(), which will return the checksum as a
@@ -11599,6 +12329,7 @@
* g_checksum_get_digest() have been called on a #GChecksum, the checksum
* will be closed and it won't be possible to call g_checksum_update()
* on it anymore.
+ *
* Use g_checksum_free() to free the memory allocated by it.
*
* Returns: the newly created #GChecksum, or %NULL.
@@ -11621,6 +12352,7 @@
* @checksum_type: a #GChecksumType
*
* Gets the length in bytes of digests of type @checksum_type
+ *
* not supported.
*
* Returns: the checksum length, or -1 if @checksum_type is
@@ -11650,14 +12382,18 @@
*
* Sets a function to be called when the child indicated by @pid
* exits, at a default priority, #G_PRIORITY_DEFAULT.
+ *
* If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
* you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
* the spawn function for the child watching to work.
+ *
* Note that on platforms where #GPid must be explicitly closed
* (see g_spawn_close_pid()) @pid must not be closed while the
* source is still active. Typically, you will want to call
* g_spawn_close_pid() in the callback function for the source.
+ *
* GLib supports only a single callback per process id.
+ *
* This internally creates a main loop source using
* g_child_watch_source_new() and attaches it to the main loop context
* using g_source_attach(). You can do these steps manually if you
@@ -11678,14 +12414,18 @@
*
* Sets a function to be called when the child indicated by @pid
* exits, at the priority @priority.
+ *
* If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
* you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
* the spawn function for the child watching to work.
+ *
* Note that on platforms where #GPid must be explicitly closed
* (see g_spawn_close_pid()) @pid must not be closed while the
* source is still active. Typically, you will want to call
* g_spawn_close_pid() in the callback function for the source.
+ *
* GLib supports only a single callback per process id.
+ *
* This internally creates a main loop source using
* g_child_watch_source_new() and attaches it to the main loop context
* using g_source_attach(). You can do these steps manually if you
@@ -11702,16 +12442,20 @@
* @pid: process to watch. On POSIX the pid of a child process. On Windows a handle for a process (which doesn't have to be a child).
*
* Creates a new child_watch source.
+ *
* The source will not initially be associated with any #GMainContext
* and must be added to one with g_source_attach() before it will be
* executed.
+ *
* Note that child watch sources can only be used in conjunction with
* <literal>g_spawn...</literal> when the %G_SPAWN_DO_NOT_REAP_CHILD
* flag is used.
+ *
* Note that on platforms where #GPid must be explicitly closed
* (see g_spawn_close_pid()) @pid must not be closed while the
* source is still active. Typically, you will want to call
* g_spawn_close_pid() in the callback function for the source.
+ *
* Note further that using g_child_watch_source_new() is not
* compatible with calling <literal>waitpid(-1)</literal> in
* the application. Calling waitpid() for individual pids will
@@ -11729,11 +12473,13 @@
*
* A wrapper for the POSIX chmod() function. The chmod() function is
* used to set the permissions of a file system object.
+ *
* On Windows the file protection mechanism is not at all POSIX-like,
* and the underlying chmod() function in the C library just sets or
* clears the FAT-style READONLY attribute. It does not touch any
* ACL. Software that needs to manage file permissions on Windows
* exactly should use the Win32 API.
+ *
* See your C library manual for more details about chmod().
*
* Returns: zero if the operation succeeded, -1 on error.
@@ -11759,7 +12505,7 @@
* g_chunk_new:
* @type: the type of the #GMemChunk atoms, typically a structure name.
* @chunk: a #GMemChunk.
- * @Returns: a pointer to the allocated atom, cast to a pointer to
+ * @Returns: a pointer to the allocated atom, cast to a pointer to @type.
*
* A convenience macro to allocate an atom of memory from a #GMemChunk.
* It calls g_mem_chunk_alloc() and casts the returned atom to a
@@ -11773,7 +12519,7 @@
* g_chunk_new0:
* @type: the type of the #GMemChunk atoms, typically a structure name.
* @chunk: a #GMemChunk.
- * @Returns: a pointer to the allocated atom, cast to a pointer to
+ * @Returns: a pointer to the allocated atom, cast to a pointer to @type.
*
* A convenience macro to allocate an atom of memory from a #GMemChunk.
* It calls g_mem_chunk_alloc0() and casts the returned atom to a
@@ -11837,8 +12583,10 @@
* In contrast to g_completion_complete(), this function returns the largest common
* prefix that is a valid UTF-8 string, omitting a possible common partial
* character.
+ *
* You should use this function instead of g_completion_complete() if your
* items are UTF-8 strings.
+ *
* not be changed.
*
* Returns: (element-type utf8) (transfer none): the list of items whose strings begin with @prefix. This should
@@ -11898,7 +12646,9 @@
* Computes the checksum for a binary @data of @length. This is a
* convenience wrapper for g_checksum_new(), g_checksum_get_string()
* and g_checksum_free().
+ *
* The hexadecimal string returned will be in lower case.
+ *
* The returned string should be freed with g_free() when done using it.
*
* Returns: the digest of the binary data as a string in hexadecimal.
@@ -11913,7 +12663,9 @@
* @length: the length of the string, or -1 if the string is null-terminated.
*
* Computes the checksum of a string.
+ *
* The hexadecimal string returned will be in lower case.
+ *
* should be freed with g_free() when done using it.
*
* Returns: the checksum as a hexadecimal string. The returned string
@@ -11922,12 +12674,54 @@
/**
+ * g_compute_hmac_for_data:
+ * @digest_type: a #GChecksumType to use for the HMAC
+ * @key: (array length=key_len): the key to use in the HMAC
+ * @key_len: the length of the key
+ * @data: binary blob to compute the HMAC of
+ * @length: length of @data
+ *
+ * Computes the HMAC for a binary @data of @length. This is a
+ * convenience wrapper for g_hmac_new(), g_hmac_get_string()
+ * and g_hmac_unref().
+ *
+ * The hexadecimal string returned will be in lower case.
+ *
+ * The returned string should be freed with g_free() when done using it.
+ *
+ * Returns: the HMAC of the binary data as a string in hexadecimal.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_compute_hmac_for_string:
+ * @digest_type: a #GChecksumType to use for the HMAC
+ * @key: (array length=key_len): the key to use in the HMAC
+ * @key_len: the length of the key
+ * @str: the string to compute the HMAC for
+ * @length: the length of the string, or -1 if the string is nul-terminated
+ *
+ * Computes the HMAC for a string.
+ *
+ * The hexadecimal string returned will be in lower case.
+ *
+ * The returned string should be freed with g_free()
+ * when done using it.
+ *
+ * Returns: the HMAC as a hexadecimal string.
+ * Since: 2.30
+ */
+
+
+/**
* g_cond_broadcast:
* @cond: a #GCond.
*
* If threads are waiting for @cond, all of them are woken up. It is
* good practice to lock the same mutex as the waiting threads, while
* calling this function, though not required.
+ *
* This function can be used even if g_thread_init() has not yet been
* called, and, in that case, will do nothing.
*/
@@ -11957,6 +12751,7 @@
* If threads are waiting for @cond, exactly one of them is woken up.
* It is good practice to hold the same lock as the waiting thread
* while calling this function, though not required.
+ *
* This function can be used even if g_thread_init() has not yet been
* called, and, in that case, will do nothing.
*/
@@ -11972,9 +12767,12 @@
* Waits until this thread is woken up on @cond, but not longer than
* until the time specified by @abs_time. The @mutex is unlocked before
* falling asleep and locked again before resuming.
+ *
* If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait().
+ *
* This function can be used even if g_thread_init() has not yet been
* called, and, in that case, will immediately return %TRUE.
+ *
* To easily calculate @abs_time a combination of g_get_current_time()
* and g_time_val_add() can be used.
*/
@@ -11987,6 +12785,7 @@
*
* Waits until this thread is woken up on @cond. The @mutex is unlocked
* before falling asleep and locked again before resuming.
+ *
* This function can be used even if g_thread_init() has not yet been
* called, and, in that case, will immediately return.
*/
@@ -11998,22 +12797,15 @@
* @len: the length of the string, or -1 if the string is nul-terminated<footnote id="nul-unsafe">
* @to_codeset: name of character set into which to convert @str
* @from_codeset: character set of @str.
- * @bytes_read: (out): location to store the number of bytes in the
- * @bytes_written: (out): the number of bytes stored in the output buffer (not
- * @error: location to store the error occuring, or %NULL to ignore
- *
- * input string that were successfully converted, or %NULL.
- * Even if the conversion was successful, this may be
- * less than @len if there were partial characters
- * at the end of the input. If the error
- * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
- * stored will the byte offset after the last valid
- * input sequence.
- * including the terminating nul).
- * errors. Any of the errors in #GConvertError may occur.
+ * @bytes_read: (out): location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence.
+ * @bytes_written: (out): the number of bytes stored in the output buffer (not including the terminating nul).
+ * @error: location to store the error occuring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur.
+ *
* Converts a string from one character set to another.
+ *
* Note that you should use g_iconv() for streaming
* conversions<footnoteref linkend="streaming-state"/>.
+ *
* nul-terminated string, which must be freed with
* g_free(). Otherwise %NULL and @error will be set.
*
@@ -12028,16 +12820,10 @@
* @to_codeset: name of character set into which to convert @str
* @from_codeset: character set of @str.
* @fallback: UTF-8 string to use in place of character not present in the target encoding. (The string must be representable in the target encoding).
- * @bytes_read: location to store the number of bytes in the
- * @bytes_written: the number of bytes stored in the output buffer (not
- * @error: location to store the error occuring, or %NULL to ignore
- *
- * input string that were successfully converted, or %NULL.
- * Even if the conversion was successful, this may be
- * less than @len if there were partial characters
- * at the end of the input.
- * including the terminating nul).
- * errors. Any of the errors in #GConvertError may occur.
+ * @bytes_read: location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input.
+ * @bytes_written: the number of bytes stored in the output buffer (not including the terminating nul).
+ * @error: location to store the error occuring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur.
+ *
* Converts a string from one character set to another, possibly
* including fallback sequences for characters not representable
* in the output. Note that it is not guaranteed that the specification
@@ -12045,8 +12831,10 @@
* systems may do an approximate conversion from @from_codeset
* to @to_codeset in their iconv() functions,
* in which case GLib will simply return that approximate conversion.
+ *
* Note that you should use g_iconv() for streaming
* conversions<footnoteref linkend="streaming-state"/>.
+ *
* nul-terminated string, which must be freed with
* g_free(). Otherwise %NULL and @error will be set.
*
@@ -12064,6 +12852,7 @@
* @error: location to store the error occuring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur.
*
* Converts a string from one character set to another.
+ *
* Note that you should use g_iconv() for streaming
* conversions<footnote id="streaming-state">
* <para>
@@ -12078,6 +12867,7 @@
* character.)
* </para>
* </footnote>.
+ *
* nul-terminated string, which must be freed with
* g_free(). Otherwise %NULL and @error will be set.
*
@@ -12099,13 +12889,16 @@
* different, see MSDN documentation for CreateFile(). The Win32 API
* uses file handles, which are more randomish integers, not small
* integers like file descriptors.
+ *
* Because file descriptors are specific to the C library on Windows,
* the file descriptor returned by this function makes sense only to
* functions in the same C library. Thus if the GLib-using code uses a
* different C library than GLib does, the file descriptor returned by
* this function cannot be passed to C library functions like write()
* or read().
+ *
* See your C library manual for more details about creat().
+ *
* return value can be used exactly like the return value from creat().
*
* Returns: a new file descriptor, or -1 if an error occurred. The
@@ -12456,6 +13249,7 @@
* Sets the value of a date to the date corresponding to a time
* specified as a time_t. The time to date conversion is done using
* the user's current timezone.
+ *
* To set the value of a date to the current day, you could write:
* |[
* g_date_set_time_t (date, time (NULL));
@@ -12471,7 +13265,9 @@
* @timeval: #GTimeVal value to set
*
* Sets the value of a date from a #GTimeVal value. Note that the
+ * @tv_usec member is ignored, because #GDate can't make use of the
* additional precision.
+ *
* The time to date conversion is done using the user's current timezone.
*
* Since: 2.10
@@ -12484,6 +13280,7 @@
* @timespan: a #GTimeSpan
*
* Creates a copy of @datetime and adds the specified timespan to the copy.
+ *
* g_date_time_unref().
*
* Returns: the newly created #GDateTime which should be freed with
@@ -12498,6 +13295,7 @@
*
* Creates a copy of @datetime and adds the specified number of days to the
* copy.
+ *
* g_date_time_unref().
*
* Returns: the newly created #GDateTime which should be freed with
@@ -12517,6 +13315,7 @@
*
* Creates a new #GDateTime adding the specified values to the current date and
* time in @datetime.
+ *
* g_date_time_unref().
*
* Returns: the newly created #GDateTime that should be freed with
@@ -12530,6 +13329,7 @@
* @hours: the number of hours to add
*
* Creates a copy of @datetime and adds the specified number of hours
+ *
* g_date_time_unref().
*
* Returns: the newly created #GDateTime which should be freed with
@@ -12543,6 +13343,7 @@
* @minutes: the number of minutes to add
*
* Creates a copy of @datetime adding the specified number of minutes.
+ *
* g_date_time_unref().
*
* Returns: the newly created #GDateTime which should be freed with
@@ -12557,6 +13358,7 @@
*
* Creates a copy of @datetime and adds the specified number of months to the
* copy.
+ *
* g_date_time_unref().
*
* Returns: the newly created #GDateTime which should be freed with
@@ -12570,6 +13372,7 @@
* @seconds: the number of seconds to add
*
* Creates a copy of @datetime and adds the specified number of seconds.
+ *
* g_date_time_unref().
*
* Returns: the newly created #GDateTime which should be freed with
@@ -12584,6 +13387,7 @@
*
* Creates a copy of @datetime and adds the specified number of weeks to the
* copy.
+ *
* g_date_time_unref().
*
* Returns: the newly created #GDateTime which should be freed with
@@ -12598,6 +13402,7 @@
*
* Creates a copy of @datetime and adds the specified number of years to the
* copy.
+ *
* g_date_time_unref().
*
* Returns: the newly created #GDateTime which should be freed with
@@ -12612,6 +13417,7 @@
*
* A comparison function for #GDateTimes that is suitable
* as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
+ *
* than @dt2.
*
* Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater
@@ -12627,6 +13433,7 @@
* Calculates the difference in time between @end and @begin. The
* #GTimeSpan that is returned is effectively @end - @begin (ie:
* positive if the first simparameter is larger).
+ *
* span expressed in microseconds.
*
* Returns: the difference between the two #GDateTime, as a time
@@ -12640,6 +13447,7 @@
* @dt2: a #GDateTime
*
* Checks to see if @dt1 and @dt2 are equal.
+ *
* Equal here means that they represent the same moment after converting
* them to the same time zone.
*
@@ -12654,12 +13462,15 @@
* @format: a valid UTF-8 string, containing the format for the #GDateTime
*
* Creates a newly allocated string representing the requested @format.
+ *
* The format strings understood by this function are a subset of the
* strftime() format language. In contrast to strftime(), this function
* always produces a UTF-8 string, regardless of the current locale.
* Note that the rendering of many formats is locale-dependent and may
* not match the strftime() output exactly.
+ *
* The following format specifiers are supported:
+ *
* <variablelist>
* <varlistentry><term>
* <literal>%%a</literal>:
@@ -12756,6 +13567,7 @@
* <varlistentry><term>
* <literal>%%P</literal>:
* </term><listitem><simpara>
+ * like %%p but lowercase: "am" or "pm" or a corresponding string for
* the current locale
* </simpara></listitem></varlistentry>
* <varlistentry><term>
@@ -12832,6 +13644,7 @@
* a literal <literal>%%</literal> character
* </simpara></listitem></varlistentry>
* </variablelist>
+ *
* Some conversion specifications can be modified by preceding the
* conversion specifier by one or more modifier characters. The
* following modifiers are supported for many of the numeric
@@ -12866,10 +13679,10 @@
* </listitem>
* </varlistentry>
* </variablelist>
+ *
* or %NULL in the case that there was an error. The string
* should be freed with g_free().
*
- * Like %%p but lowercase: "am" or "pm" or a corresponding string for
* Returns: a newly allocated string formatted to the requested format
* Since: 2.26
*/
@@ -12985,9 +13798,11 @@
*
* Determines the time zone abbreviation to be used at the time and in
* the time zone of @datetime.
+ *
* For example, in Toronto this is currently "EST" during the winter
* months and "EDT" during the summer months when daylight savings
* time is in effect.
+ *
* string is owned by the #GDateTime and it should not be
* modified or freed
*
@@ -13002,12 +13817,15 @@
*
* Determines the offset to UTC in effect at the time and in the time
* zone of @datetime.
+ *
* The offset is the number of microseconds that you add to UTC time to
+ * arrive at local time for the time zone (ie: negative numbers for time
* zones west of GMT, positive numbers for east).
+ *
* If @datetime represents UTC time, then the offset is always zero.
+ *
* get the local time
*
- * Arrive at local time for the time zone (ie: negative numbers for time
* Returns: the number of microseconds that should be added to UTC to
* Since: 2.26
*/
@@ -13018,26 +13836,34 @@
* @datetime: a #GDateTime
*
* Returns the ISO 8601 week-numbering year in which the week containing
+ * @datetime falls.
+ *
* This function, taken together with g_date_time_get_week_of_year() and
* g_date_time_get_day_of_week() can be used to determine the full ISO
* week date on which @datetime falls.
+ *
* This is usually equal to the normal Gregorian year (as returned by
* g_date_time_get_year()), except as detailed below:
+ *
* For Thursday, the week-numbering year is always equal to the usual
* calendar year. For other days, the number is such that every day
* within a complete week (Monday to Sunday) is contained within the
* same week-numbering year.
+ *
* For Monday, Tuesday and Wednesday occuring near the end of the year,
* this may mean that the week-numbering year is one greater than the
* calendar year (so that these days have the same week-numbering year
* as the Thursday occuring early in the next year).
+ *
* For Friday, Saturaday and Sunday occuring near the start of the year,
* this may mean that the week-numbering year is one less than the
* calendar year (so that these days have the same week-numbering year
* as the Thursday occuring late in the previous year).
+ *
* An equivalent description is that the week-numbering year is equal to
* the calendar year containing the majority of the days in the current
* week (Monday to Sunday).
+ *
* Note that January 1 0001 in the proleptic Gregorian calendar is a
* Monday, so this function never returns 0.
*
@@ -13054,9 +13880,11 @@
* The ISO 8601 week number is the same for every day of the week (from
* Moday through Sunday). That can produce some unusual results
* (described below).
+ *
* The first week of the year is week 1. This is the week that contains
* the first Thursday of the year. Equivalently, this is the first week
* that has more than 4 of its days falling within the calendar year.
+ *
* The value 0 is never returned by this function. Days contained
* within a year but occuring before the first ISO 8601 week of that
* year are considered as being contained in the last week of the
@@ -13128,21 +13956,30 @@
*
* Creates a new #GDateTime corresponding to the given date and time in
* the time zone @tz.
+ *
* The @year must be between 1 and 9999, @month between 1 and 12 and @day
* between 1 and 28, 29, 30 or 31 depending on the month and the year.
+ *
+ * @hour must be between 0 and 23 and @minute must be between 0 and 59.
+ *
+ * @seconds must be at least 0.0 and must be strictly less than 60.0.
* It will be rounded down to the nearest microsecond.
+ *
* If the given time is not representable in the given time zone (for
* example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
* time) then the time will be rounded up to the nearest existing time
* (in this case, 03:00). If this matters to you then you should verify
* the return value for containing the same as the numbers you gave.
+ *
* In the case that the given time is ambiguous in the given time zone
* (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
* savings time) then the time falling within standard (ie:
* non-daylight) time is taken.
+ *
* It not considered a programmer error for the values to this function
* to be out of range, but in the case that they are, the function will
* return %NULL.
+ *
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
@@ -13157,11 +13994,14 @@
*
* Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
* local time zone.
+ *
* The time contained in a #GTimeVal is always stored in the form of
* seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
* local time offset.
+ *
* This call can fail (returning %NULL) if @tv represents a time outside
* of the supported range of #GDateTime.
+ *
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
@@ -13175,10 +14015,13 @@
* @tv: a #GTimeVal
*
* Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC.
+ *
* The time contained in a #GTimeVal is always stored in the form of
* seconds elapsed since 1970-01-01 00:00:00 UTC.
+ *
* This call can fail (returning %NULL) if @tv represents a time outside
* of the supported range of #GDateTime.
+ *
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
@@ -13193,10 +14036,13 @@
*
* Creates a #GDateTime corresponding to the given Unix time @t in the
* local time zone.
+ *
* Unix time is the number of seconds that have elapsed since 1970-01-01
* 00:00:00 UTC, regardless of the local time offset.
+ *
* This call can fail (returning %NULL) if @t represents a time outside
* of the supported range of #GDateTime.
+ *
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
@@ -13210,10 +14056,13 @@
* @t: the Unix time
*
* Creates a #GDateTime corresponding to the given Unix time @t in UTC.
+ *
* Unix time is the number of seconds that have elapsed since 1970-01-01
* 00:00:00 UTC.
+ *
* This call can fail (returning %NULL) if @t represents a time outside
* of the supported range of #GDateTime.
+ *
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
@@ -13233,6 +14082,7 @@
*
* Creates a new #GDateTime corresponding to the given date and time in
* the local time zone.
+ *
* This call is equivalent to calling g_date_time_new() with the time
* zone returned by g_time_zone_new_local().
*
@@ -13248,9 +14098,11 @@
* Creates a #GDateTime corresponding to this exact instant in the given
* time zone @tz. The time is as accurate as the system allows, to a
* maximum accuracy of 1 microsecond.
+ *
* This function will always succeed unless the system clock is set to
* truly insane values (or unless GLib is still being used after the
* year 9999).
+ *
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
@@ -13264,6 +14116,7 @@
*
* Creates a #GDateTime corresponding to this exact instant in the local
* time zone.
+ *
* This is equivalent to calling g_date_time_new_now() with the time
* zone returned by g_time_zone_new_local().
*
@@ -13276,6 +14129,7 @@
* g_date_time_new_now_utc:
*
* Creates a #GDateTime corresponding to this exact instant in UTC.
+ *
* This is equivalent to calling g_date_time_new_now() with the time
* zone returned by g_time_zone_new_utc().
*
@@ -13295,6 +14149,7 @@
*
* Creates a new #GDateTime corresponding to the given date and time in
* UTC.
+ *
* This call is equivalent to calling g_date_time_new() with the time
* zone returned by g_time_zone_new_utc().
*
@@ -13319,6 +14174,8 @@
* @datetime: a #GDateTime
*
* Creates a new #GDateTime corresponding to the same instant in time as
+ * @datetime, but in the local time zone.
+ *
* This call is equivalent to calling g_date_time_to_timezone() with the
* time zone returned by g_time_zone_new_local().
*
@@ -13333,16 +14190,19 @@
* @tv: a #GTimeVal to modify
*
* Stores the instant in time that @datetime represents into @tv.
+ *
* The time contained in a #GTimeVal is always stored in the form of
* seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
* zone associated with @datetime.
+ *
+ * On systems where 'long' is 32bit (ie: all 32bit systems and all
* Windows systems), a #GTimeVal is incapable of storing the entire
* range of values that #GDateTime is capable of expressing. On those
* systems, this function returns %FALSE to indicate that the time is
* out of range.
+ *
* On systems where 'long' is 64bit, this function never fails.
*
- * On systems where 'long' is 32bit (ie: all 32bit systems and all
* Returns: %TRUE if successful, else %FALSE
* Since: 2.26
*/
@@ -13354,9 +14214,12 @@
* @tz: the new #GTimeZone
*
* Create a new #GDateTime corresponding to the same instant in time as
+ * @datetime, but in the time zone @tz.
+ *
* This call can fail in the case that the time goes out of bounds. For
* example, converting 0001-01-01 00:00:00 UTC to a time zone west of
* Greenwich will fail (due to the year 0 being out of range).
+ *
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
@@ -13371,6 +14234,7 @@
*
* Gives the Unix time corresponding to @datetime, rounding down to the
* nearest second.
+ *
* Unix time is the number of seconds that have elapsed since 1970-01-01
* 00:00:00 UTC, regardless of the time zone associated with @datetime.
*
@@ -13384,6 +14248,8 @@
* @datetime: a #GDateTime
*
* Creates a new #GDateTime corresponding to the same instant in time as
+ * @datetime, but in UTC.
+ *
* This call is equivalent to calling g_date_time_to_timezone() with the
* time zone returned by g_time_zone_new_utc().
*
@@ -13397,7 +14263,9 @@
* @datetime: a #GDateTime
*
* Atomically decrements the reference count of @datetime by one.
+ *
* When the reference count reaches zero, the resources allocated by
+ * @datetime are freed
*
* Since: 2.26
*/
@@ -13427,6 +14295,7 @@
* This function is a wrapper of dgettext() which does not translate
* the message if the default domain as set with textdomain() has no
* translations for the current locale.
+ *
* The advantage of using this function over dgettext() proper is that
* libraries using this function (like GTK+) will not use translations
* if the application using the library does not have translations for
@@ -13435,6 +14304,7 @@
* feature to work, the call to textdomain() and setlocale() should
* precede any g_dgettext() invocations. For GTK+, it means calling
* textdomain() before gtk_init or its variants.
+ *
* This function disables translations if and only if upon its first
* call all the following conditions hold:
* <itemizedlist>
@@ -13445,9 +14315,11 @@
* <listitem>current locale is not "C" or any English locales (those
* starting with "en_")</listitem>
* </itemizedlist>
+ *
* Note that this behavior may not be desired for example if an application
* has its untranslated messages in a language other than English. In those
* cases the application should call textdomain() after initializing GTK+.
+ *
* Applications should normally not use this function directly,
* but use the _() macro for translations.
*
@@ -13465,6 +14337,33 @@
/**
+ * g_dir_make_tmp:
+ * @tmpl: Template for directory name, as in g_mkdtemp(), basename only, or %NULL, to a default template
+ * @name_used: location to store actual name used, or %NULL
+ * @error: return location for a #GError
+ *
+ * Creates a subdirectory in the preferred directory for temporary
+ * files (as returned by g_get_tmp_dir()).
+ *
+ * @tmpl should be a string in the GLib file name encoding containing
+ * a sequence of six 'X' characters, as the parameter to g_mkstemp().
+ * However, unlike these functions, the template should only be a
+ * basename, no directory components are allowed. If template is
+ * %NULL, a default template is used.
+ *
+ * Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not
+ * modified, and might thus be a read-only literal string.
+ *
+ * with g_free() when not needed any longer and is is in the GLib
+ * file name encoding. In case of errors, %NULL is returned
+ * and @error will be set.
+ *
+ * Returns: The actual name used. This string should be freed
+ * Since: 2.30
+ */
+
+
+/**
* g_dir_open:
* @path: the path to the directory you are interested in. On Unix in the on-disk encoding. On Windows in UTF-8
* @flags: Currently must be set to 0. Reserved for future use.
@@ -13473,6 +14372,7 @@
* Opens a directory for reading. The names of the files in the
* directory can then be retrieved using g_dir_read_name(). Note
* that the ordering is not defined.
+ *
* If non-%NULL, you must free the result with g_dir_close()
* when you are finished with it.
*
@@ -13488,10 +14388,13 @@
* The order of entries returned from this function is not defined,
* and may vary by file system or other operating-system dependent
* factors.
+ *
* On Unix, the '.' and '..' entries are omitted, and the returned
* name is in the on-disk encoding.
+ *
* On Windows, as is true of all GLib functions which operate on
* filenames, the returned name is in UTF-8.
+ *
* more entries. The return value is owned by GLib and
* must not be modified or freed.
*
@@ -13556,6 +14459,7 @@
* This function is a wrapper of dngettext() which does not translate
* the message if the default domain as set with textdomain() has no
* translations for the current locale.
+ *
* See g_dgettext() for details of how this differs from dngettext()
* proper.
*
@@ -13605,8 +14509,10 @@
* If 0 is passed as @msgidoffset, this function will fall back to
* trying to use the deprecated convention of using "|" as a separation
* character.
+ *
* This uses g_dgettext() internally. See that functions for differences
* with dgettext() proper.
+ *
* Applications should normally not use this function directly,
* but use the C_() macro for translations with context.
*
@@ -13625,8 +14531,10 @@
* a disambiguating message context. GNU gettext uses the
* '\004' character to separate the message context and
* message id in @msgctxtid.
+ *
* This uses g_dgettext() internally. See that functions for differences
* with dgettext() proper.
+ *
* This function differs from C_() in that it is not a macro and
* thus you may use non-string-literals as context and msgid arguments.
*
@@ -13689,6 +14597,7 @@
*
* Creates a new #GError; unlike g_error_new(), @message is
* not a printf()-style format string. Use this function if
+ * @message contains text you don't have control over,
* that could include printf() escape sequences.
*
* Returns: a new #GError
@@ -13718,6 +14627,7 @@
* For example, if you pass in %EEXIST this function returns
* #G_FILE_ERROR_EXIST. Unlike @errno values, you can portably
* assume that all #GFileError values will exist.
+ *
* Normally a #GFileError value goes into a #GError returned
* from a function that manipulates files. So you would use
* g_file_error_from_errno() when constructing a #GError.
@@ -13735,12 +14645,14 @@
*
* Reads an entire file into allocated memory, with good error
* checking.
+ *
* If the call was successful, it returns %TRUE and sets @contents to the file
* contents and @length to the length of the file contents in bytes. The string
* stored in @contents will be nul-terminated, so for text files you can pass
* %NULL for the @length argument. If the call was not successful, it returns
* %FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error
* codes are those in the #GFileError enumeration. In the error case,
+ * @contents is set to %NULL and @length is set to zero.
*
* Returns: %TRUE on success, %FALSE if an error occurred
*/
@@ -13754,20 +14666,26 @@
*
* Opens a file for writing in the preferred directory for temporary
* files (as returned by g_get_tmp_dir()).
+ *
+ * @tmpl should be a string in the GLib file name encoding containing
* a sequence of six 'X' characters, as the parameter to g_mkstemp().
* However, unlike these functions, the template should only be a
* basename, no directory components are allowed. If template is
* %NULL, a default template is used.
- * Note that in contrast to g_mkstemp() (and mkstemp())
- * The actual name used is returned in @name_used if non-%NULL. This
- * string should be freed with g_free() when not needed any longer.
- * The returned name is in the GLib file name encoding.
- * the file opened for reading and writing. The file is opened in binary
- * mode on platforms where there is a difference. The file handle should be
- * closed with close(). In case of errors, -1 is returned
- * and @error will be set.
*
- * Returns: A file handle (as from open()) to
+ * Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not
+ * modified, and might thus be a read-only literal string.
+ *
+ * Upon success, and if @name_used is non-%NULL, the actual name used
+ * is returned in @name_used. This string should be freed with g_free()
+ * when not needed any longer. The returned name is in the GLib file
+ * name encoding.
+ *
+ * reading and writing. The file is opened in binary mode on platforms
+ * where there is a difference. The file handle should be closed with
+ * close(). In case of errors, -1 is returned and @error will be set.
+ *
+ * Returns: A file handle (as from open()) to the file opened for
*/
@@ -13779,6 +14697,7 @@
* Reads the contents of the symbolic link @filename like the POSIX
* readlink() function. The returned string is in the encoding used
* for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
+ *
* or %NULL if an error occurred.
*
* Returns: A newly-allocated string with the contents of the symbolic link,
@@ -13795,6 +14714,7 @@
*
* Writes all of @contents to a file named @filename, with good error checking.
* If a file called @filename already exists it will be overwritten.
+ *
* This write is atomic in the sense that it is first written to a temporary
* file which is then renamed to the final name. Notes:
* <itemizedlist>
@@ -13812,11 +14732,14 @@
* <listitem>
* On Windows there is no way to remove a file that is open to some
* process, or mapped into memory. Thus, this function will fail if
+ * @filename already exists and is open.
* </listitem>
* </itemizedlist>
+ *
* If the call was sucessful, it returns %TRUE. If the call was not successful,
* it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR.
* Possible error codes are those in the #GFileError enumeration.
+ *
* Note that the name for the temporary file is constructed by appending up
* to 7 characters to @filename.
*
@@ -13836,11 +14759,14 @@
* the check whether it's a directory doesn't matter since the existence
* test is %TRUE. With the current set of available tests, there's no point
* passing in more than one test at a time.
+ *
* Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links,
* so for a symbolic link to a regular file g_file_test() will return
* %TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR.
+ *
* Note, that for a dangling symbolic link g_file_test() will return
* %TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags.
+ *
* You should never use g_file_test() to test whether it is safe
* to perform an operation, because there is always the possibility
* of the condition changing before you actually perform the operation.
@@ -13855,12 +14781,14 @@
* /* write to fd */
* }
* ]|
+ *
* Another thing to note is that %G_FILE_TEST_EXISTS and
* %G_FILE_TEST_IS_EXECUTABLE are implemented using the access()
* system call. This usually doesn't matter, but if your program
* is setuid or setgid it means that these tests will give you
* the answer for the real user ID and group ID, rather than the
* effective user ID and group ID.
+ *
* On Windows, there are no symlinks, so testing for
* %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
* %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
@@ -13879,15 +14807,19 @@
* to be valid UTF-8. The display name might not be identical to the filename,
* for instance there might be problems converting it to UTF-8, and some files
* can be translated in the display.
+ *
* If GLib cannot make sense of the encoding of @filename, as a last resort it
* replaces unknown characters with U+FFFD, the Unicode replacement character.
* You can search the result for the UTF-8 encoding of this character (which is
* "\357\277\275" in octal notation) to find out if @filename was in an invalid
* encoding.
+ *
* You must pass the whole absolute pathname to this functions so that
* translation of well known locations can be done.
+ *
* This function is preferred over g_filename_display_name() if you know the
* whole path, as it allows translation.
+ *
* a rendition of the basename of the filename in valid UTF-8
*
* Returns: a newly allocated string containing
@@ -13904,14 +14836,17 @@
* and use the return value of this function only for display purposes.
* Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL
* even if the filename actually isn't in the GLib file name encoding.
+ *
* If GLib cannot make sense of the encoding of @filename, as a last resort it
* replaces unknown characters with U+FFFD, the Unicode replacement character.
* You can search the result for the UTF-8 encoding of this character (which is
* "\357\277\275" in octal notation) to find out if @filename was in an invalid
* encoding.
+ *
* If you know the whole pathname of the file you should use
* g_filename_display_basename(), since that allows location-based
* translation of filenames.
+ *
* a rendition of the filename in valid UTF-8
*
* Returns: a newly allocated string containing
@@ -13927,6 +14862,7 @@
*
* Converts an escaped ASCII-encoded URI to a local filename in the
* encoding used for filenames.
+ *
* filename, or %NULL on an error.
*
* Returns: a newly-allocated string holding the resulting
@@ -13958,6 +14894,7 @@
*
* Converts an absolute filename to an escaped ASCII-encoded URI, with the path
* component following Section 3.3. of RFC 2396.
+ *
* URI, or %NULL on an error.
*
* Returns: a newly-allocated string holding the resulting
@@ -13989,9 +14926,12 @@
* same way that execvp() would locate it. Returns an allocated string
* with the absolute path name, or %NULL if the program is not found in
* the path. If @program is already an absolute path, returns a copy of
+ * @program if @program exists and is executable, and %NULL otherwise.
+ *
* On Windows, if @program does not have a file type suffix, tries
* with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
* the <envar>PATHEXT</envar> environment variable.
+ *
* On Windows, it looks for the file in the same way as CreateProcess()
* would. This means first in the directory where the executing
* program was loaded from, then in the current directory, then in the
@@ -14011,6 +14951,7 @@
*
* A wrapper for the stdio fopen() function. The fopen() function
* opens a file and associates a new stream with it.
+ *
* Because file descriptors are specific to the C library on Windows,
* and a file descriptor is partof the <type>FILE</type> struct, the
* <type>FILE</type> pointer returned by this function makes sense
@@ -14018,7 +14959,9 @@
* code uses a different C library than GLib does, the
* <type>FILE</type> pointer returned by this function cannot be
* passed to C library functions like fprintf() or fread().
+ *
* See your C library manual for more details about fopen().
+ *
* opened, or %NULL if an error occurred
*
* Returns: A <type>FILE</type> pointer if the file was successfully
@@ -14034,10 +14977,14 @@
* string. Sizes are rounded to the nearest size prefix (kB, MB, GB)
* and are displayed rounded to the nearest tenth. E.g. the file size
* 3292528 bytes will be converted into the string "3.2 MB".
+ *
* The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
+ *
* This string should be freed with g_free() when not needed any longer.
+ *
* See g_format_size_full() for more options about how the size might be
* formatted.
+ *
* file size.
*
* Returns: a newly-allocated formatted string containing a human readable
@@ -14053,14 +15000,18 @@
* Sizes are rounded to the nearest size prefix (KB, MB, GB) and are displayed
* rounded to the nearest tenth. E.g. the file size 3292528 bytes will be
* converted into the string "3.1 MB".
+ *
* The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).
+ *
* This string should be freed with g_free() when not needed any longer.
+ *
* file size.
+ *
+ * Deprecated:2.30: This function is broken due to its use of SI
* suffixes to denote IEC units. Use g_format_size()
* instead.
*
* Returns: a newly-allocated formatted string containing a human readable
- * Deprecated:2.30: This function is broken due to its use of SI
* Since: 2.16
*/
@@ -14071,8 +15022,10 @@
* @flags: #GFormatSizeFlags to modify the output
*
* Formats a size.
+ *
* This function is similar to g_format_size() but allows for flags that
* modify the output. See #GFormatSizeFlags.
+ *
* readable file size.
*
* Returns: a newly-allocated formatted string containing a human
@@ -14111,7 +15064,9 @@
*
* A wrapper for the POSIX freopen() function. The freopen() function
* opens a file and associates it with an existing stream.
+ *
* See your C library manual for more details about freopen().
+ *
* opened, or %NULL if an error occurred.
*
* Returns: A <type>FILE</type> pointer if the file was successfully
@@ -14144,13 +15099,16 @@
* g_convert(), to convert from the current locale's encoding to some
* other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8()
* are nice shortcuts, though.)
+ *
* On Windows the character set returned by this function is the
* so-called system default ANSI code-page. That is the character set
* used by the "narrow" versions of C library and Win32 functions that
* handle file names. It might be different from the character set
* used by the C library's current locale.
+ *
* The return value is %TRUE if the locale's encoding is UTF-8, in that
* case you can perhaps avoid calling g_convert().
+ *
* The string returned in @charset is not allocated, and should not be
* freed.
*
@@ -14162,6 +15120,7 @@
* g_get_codeset:
*
* Get the codeset for the current locale.
+ *
* of the codeset. This string must be freed with g_free().
*
* Returns: a newly allocated string containing the name
@@ -14184,6 +15143,7 @@
* @result: #GTimeVal structure in which to store current time.
*
* Equivalent to the UNIX gettimeofday() function, but portable.
+ *
* You may find g_get_real_time() to be more convenient.
*/
@@ -14194,8 +15154,10 @@
* Gets the list of environment variables for the current process. The
* list is %NULL terminated and each item in the list is of the form
* 'NAME=VALUE'.
+ *
* This is equivalent to direct access to the 'environ' global variable,
* except portable.
+ *
* The return value is freshly allocated and it should be freed with
* g_strfreev() when it is no longer needed.
*
@@ -14212,11 +15174,13 @@
* The first character set from the @charsets is the filename encoding, the
* subsequent character sets are used when trying to generate a displayable
* representation of a filename, see g_filename_display_name().
+ *
* On Unix, the character sets are determined by consulting the
* environment variables <envar>G_FILENAME_ENCODING</envar> and
* <envar>G_BROKEN_FILENAMES</envar>. On Windows, the character set
* used in the GLib API is always UTF-8 and said environment variables
* have no effect.
+ *
* <envar>G_FILENAME_ENCODING</envar> may be set to a comma-separated list
* of character set names. The special token "@locale" is taken to
* mean the character set for the <link linkend="setlocale">current
@@ -14225,7 +15189,9 @@
* locale is taken as the filename encoding. If neither environment variable
* is set, UTF-8 is taken as the filename encoding, but the character
* set of the current locale is also put in the list of encodings.
+ *
* The returned @charsets belong to GLib and must not be freed.
+ *
* Note that on Unix, regardless of the locale character set or
* <envar>G_FILENAME_ENCODING</envar> value, the actual file names present
* on a system might be in any random encoding or just gibberish.
@@ -14240,9 +15206,11 @@
*
* Gets the current user's home directory as defined in the
* password database.
+ *
* Note that in contrast to traditional UNIX tools, this function
* prefers <filename>passwd</filename> entries over the <envar>HOME</envar>
* environment variable.
+ *
* One of the reasons for this decision is that applications in many
* cases need special handling to deal with the case where
* <envar>HOME</envar> is
@@ -14270,6 +15238,7 @@
* g_get_host_name:
*
* Return a name for the machine.
+ *
* The returned name is not necessarily a fully-qualified domain name,
* or even present in DNS or some other name service at all. It need
* not even be unique on your local network or site, but usually it
@@ -14293,11 +15262,14 @@
* e.g. construct locale-dependent filenames or search paths. The returned
* list is sorted from most desirable to least desirable and always contains
* the default locale "C".
+ *
* For example, if LANGUAGE=de:en_US, then the returned list is
* "de", "en_US", "en", "C".
+ *
* This function consults the environment variables <envar>LANGUAGE</envar>,
* <envar>LC_ALL</envar>, <envar>LC_MESSAGES</envar> and <envar>LANG</envar>
* to find the list of locales specified by the user.
+ *
* that must not be modified or freed.
*
* Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib
@@ -14313,10 +15285,13 @@
* e.g. construct locale-dependent filenames or search paths. The returned
* list is sorted from most desirable to least desirable.
* This function handles territory, charset and extra locale modifiers.
+ *
* For example, if @locale is "fr_BE", then the returned list
* is "fr_BE", "fr".
+ *
* If you need the list of variants for the <emphasis>current locale</emphasis>,
* use g_get_language_names().
+ *
* allocated array of newly allocated strings with the locale variants. Free with
* g_strfreev().
*
@@ -14329,10 +15304,12 @@
* g_get_monotonic_time:
*
* Queries the system monotonic time, if available.
+ *
* On POSIX systems with clock_gettime() and %CLOCK_MONOTONIC this call
* is a very shallow wrapper for that. Otherwise, we make a best effort
* that probably involves returning the wall clock time (with at least
* microsecond accuracy, subject to the limitations of the OS kernel).
+ *
* Note that, on Windows, "limitations of the OS kernel" is a rather
* substantial statement. Depending on the configuration of the system,
* the wall clock time is updated as infrequently as 64 times a second
@@ -14351,6 +15328,7 @@
* (If you are using GDK or GTK+ the program name is set in gdk_init(),
* which is called by gtk_init(). The program name is found by taking
* the last component of <literal>argv[0]</literal>.)
+ *
* to GLib and must not be modified or freed.
*
* Returns: the name of the program. The returned string belongs
@@ -14374,9 +15352,11 @@
* g_get_real_time:
*
* Queries the system wall-clock time.
+ *
* This call is functionally equivalent to g_get_current_time() except
* that the return value is often more convenient than dealing with a
* #GTimeVal.
+ *
* You should only use this call if you are actually interested in the real
* wall-clock time. g_get_monotonic_time() is probably more useful for
* measuring intervals.
@@ -14391,16 +15371,19 @@
*
* Returns an ordered list of base directories in which to access
* system-wide configuration information.
+ *
* On UNIX platforms this is determined using the mechanisms described in
* the <ulink url="http://www.freedesktop.org/Standards/basedir-spec";>
* XDG Base Directory Specification</ulink>.
* In this case the list of directories retrieved will be XDG_CONFIG_DIRS.
+ *
* On Windows is the directory that contains application data for all users.
* A typical path is C:\Documents and Settings\All Users\Application Data.
* This folder is used for application data that is not user specific.
* For example, an application can store a spell-check dictionary, a database
* of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
* This information will not roam and is available to anyone using the computer.
+ *
* not be modified or freed.
*
* Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
@@ -14413,27 +15396,34 @@
*
* Returns an ordered list of base directories in which to access
* system-wide application data.
+ *
* On UNIX platforms this is determined using the mechanisms described in
* the <ulink url="http://www.freedesktop.org/Standards/basedir-spec";>
* XDG Base Directory Specification</ulink>
* In this case the list of directories retrieved will be XDG_DATA_DIRS.
+ *
* On Windows the first elements in the list are the Application Data
* and Documents folders for All Users. (These can be determined only
* on Windows 2000 or later and are not present in the list on other
* Windows versions.) See documentation for CSIDL_COMMON_APPDATA and
* CSIDL_COMMON_DOCUMENTS.
+ *
* Then follows the "share" subfolder in the installation folder for
* the package containing the DLL that calls this function, if it can
* be determined.
+ *
* Finally the list contains the "share" subfolder in the installation
* folder for GLib, and in the installation folder for the package the
* application's .exe file belongs to.
+ *
* The installation folders above are determined by looking up the
* folder where the module (DLL or EXE) in question is located. If the
* folder's name is "bin", its parent is used, otherwise the folder
* itself.
+ *
* Note that on Windows the returned list can vary depending on where
* this function is called.
+ *
* not be modified or freed.
*
* Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
@@ -14460,14 +15450,17 @@
*
* Returns a base directory in which to store non-essential, cached
* data specific to particular user.
+ *
* On UNIX platforms this is determined using the mechanisms described in
* the <ulink url="http://www.freedesktop.org/Standards/basedir-spec";>
* XDG Base Directory Specification</ulink>.
* In this case the directory retrieved will be XDG_CACHE_HOME.
+ *
* On Windows is the directory that serves as a common repository for
* temporary Internet files. A typical path is
* C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
* See documentation for CSIDL_INTERNET_CACHE.
+ *
* or freed.
*
* Returns: a string owned by GLib that must not be modified
@@ -14480,14 +15473,17 @@
*
* Returns a base directory in which to store user-specific application
* configuration information such as user preferences and settings.
+ *
* On UNIX platforms this is determined using the mechanisms described in
* the <ulink url="http://www.freedesktop.org/Standards/basedir-spec";>
* XDG Base Directory Specification</ulink>.
* In this case the directory retrieved will be XDG_CONFIG_HOME.
+ *
* On Windows this is the folder to use for local (as opposed to
* roaming) application data. See documentation for
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_data_dir() returns.
+ *
* or freed.
*
* Returns: a string owned by GLib that must not be modified
@@ -14500,14 +15496,17 @@
*
* Returns a base directory in which to access application data such
* as icons that is customized for a particular user.
+ *
* On UNIX platforms this is determined using the mechanisms described in
* the <ulink url="http://www.freedesktop.org/Standards/basedir-spec";>
* XDG Base Directory Specification</ulink>.
* In this case the directory retrieved will be XDG_DATA_HOME.
+ *
* On Windows this is the folder to use for local (as opposed to
* roaming) application data. See documentation for
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_config_dir() returns.
+ *
* or freed.
*
* Returns: a string owned by GLib that must not be modified
@@ -14532,12 +15531,14 @@
*
* Returns a directory that is unique to the current user on the local
* system.
+ *
* On UNIX platforms this is determined using the mechanisms described in
* the <ulink url="http://www.freedesktop.org/Standards/basedir-spec";>
* XDG Base Directory Specification</ulink>. This is the directory
* specified in the <envar>XDG_RUNTIME_DIR</envar> environment variable.
* In the case that this variable is not set, GLib will issue a warning
* message to stderr and return the value of g_get_user_cache_dir().
+ *
* On Windows this is the folder to use for local (as opposed to
* roaming) application data. See documentation for
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
@@ -14553,13 +15554,16 @@
* @directory: the logical id of special directory
*
* Returns the full path of a special directory using its logical id.
+ *
* On Unix this is done using the XDG special user directories.
* For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP
* falls back to <filename>$HOME/Desktop</filename> when XDG special
* user directories have not been set up.
+ *
* Depending on the platform, the user might be able to change the path
* of the special directory without requiring the session to restart; GLib
* will not reflect any change once the special directories are loaded.
+ *
* if the logical id was not found. The returned string is owned by
* GLib and should not be modified or freed.
*
@@ -14578,6 +15582,7 @@
* and encoding. On Windows, it is in UTF-8. On Windows, in case the
* environment variable's value contains references to other
* environment variables, they are expanded.
+ *
* the environment variable is not found. The returned string may be
* overwritten by the next call to g_getenv(), g_setenv() or
* g_unsetenv().
@@ -14606,8 +15611,10 @@
* @user_data: user data to pass to the function.
*
* Calls the given function for key/value pairs in the #GHashTable until
+ * @predicate returns %TRUE. The function is passed the key and value of
* each pair, and the given @user_data parameter. The hash table may not
* be modified while iterating over it (you can't add/remove items).
+ *
* Note, that hash tables are really only optimized for forward lookups,
* i.e. g_hash_table_lookup().
* So code that frequently issues g_hash_table_find() or
@@ -14616,6 +15623,7 @@
* data structures for reverse lookups (keep in mind that an O(n) find/foreach
* operation issued for all n values in a hash table ends up needing O(n*n)
* operations).
+ *
* for which @predicate evaluates to %TRUE. If no pair with the
* requested property is found, %NULL is returned.
*
@@ -14636,6 +15644,7 @@
* be modified while iterating over it (you can't add/remove
* items). To remove all items matching a predicate, use
* g_hash_table_foreach_remove().
+ *
* See g_hash_table_find() for performance caveats for linear
* order searches in contrast to g_hash_table_lookup().
*/
@@ -14652,6 +15661,7 @@
* #GHashTable. If you supplied key or value destroy functions when creating
* the #GHashTable, they are used to free the memory allocated for the removed
* keys and values.
+ *
* See #GHashTableIter for an alternative way to loop over the
* key/value pairs in the hash table.
*
@@ -14668,6 +15678,7 @@
* Calls the given function for each key/value pair in the #GHashTable.
* If the function returns %TRUE, then the key/value pair is removed from the
* #GHashTable, but no key or value destroy functions are called.
+ *
* See #GHashTableIter for an alternative way to loop over the
* key/value pairs in the hash table.
*
@@ -14690,6 +15701,7 @@
*
* Retrieves every key inside @hash_table. The returned data is valid
* until @hash_table is modified.
+ *
* table. The content of the list is owned by the hash table and
* should not be modified or freed. Use g_list_free() when done
* using the list.
@@ -14705,6 +15717,7 @@
*
* Retrieves every value inside @hash_table. The returned data is
* valid until @hash_table is modified.
+ *
* table. The content of the list is owned by the hash table and
* should not be modified or freed. Use g_list_free() when done
* using the list.
@@ -14721,6 +15734,7 @@
* @value: the value to associate with the key.
*
* Inserts a new key and value into a #GHashTable.
+ *
* If the key already exists in the #GHashTable its current value is replaced
* with the new value. If you supplied a @value_destroy_func when creating the
* #GHashTable, the old value is freed using that function. If you supplied
@@ -14746,10 +15760,12 @@
* @hash_table: a #GHashTable.
*
* Initializes a key/value pair iterator and associates it with
+ * @hash_table. Modifying the hash table after calling this function
* invalidates the returned iterator.
* |[
* GHashTableIter iter;
* gpointer key, value;
+ *
* g_hash_table_iter_init (&iter, hash_table);
* while (g_hash_table_iter_next (&iter, &key, &value))
* {
@@ -14769,6 +15785,7 @@
*
* Advances @iter and retrieves the key and/or value that are now
* pointed to as a result of this advancement. If %FALSE is returned,
+ * @key and @value are not set, and the iterator becomes invalid.
*
* Returns: %FALSE if the end of the #GHashTable has been reached.
* Since: 2.16
@@ -14783,6 +15800,7 @@
* from its associated #GHashTable. Can only be called after
* g_hash_table_iter_next() returned %TRUE, and cannot be called more
* than once for the same key/value pair.
+ *
* If the #GHashTable was created using g_hash_table_new_full(), the
* key and value are freed using the supplied destroy functions, otherwise
* you have to make sure that any dynamically allocated values are freed
@@ -14800,6 +15818,7 @@
* Replaces the value currently pointed to by the iterator
* from its associated #GHashTable. Can only be called after
* g_hash_table_iter_next() returned %TRUE.
+ *
* If you supplied a @value_destroy_func when creating the #GHashTable,
* the old value is freed using that function.
*
@@ -14846,6 +15865,7 @@
* associated value and a #gboolean which is %TRUE if the key was found. This
* is useful if you need to free the memory allocated for the original key,
* for example before calling g_hash_table_remove().
+ *
* You can actually pass %NULL for @lookup_key to test
* whether the %NULL key exists, provided the hash and equal functions
* of @hash_table are %NULL-safe.
@@ -14898,6 +15918,7 @@
* @key: the key to remove.
*
* Removes a key and its associated value from a #GHashTable.
+ *
* If the #GHashTable was created using g_hash_table_new_full(), the
* key and value are freed using the supplied destroy functions, otherwise
* you have to make sure that any dynamically allocated values are freed
@@ -14912,6 +15933,7 @@
* @hash_table: a #GHashTable
*
* Removes all keys and their associated values from a #GHashTable.
+ *
* If the #GHashTable was created using g_hash_table_new_full(), the keys
* and values are freed using the supplied destroy functions, otherwise you
* have to make sure that any dynamically allocated values are freed
@@ -14930,6 +15952,7 @@
* Inserts a new key and value into a #GHashTable similar to
* g_hash_table_insert(). The difference is that if the key already exists
* in the #GHashTable, it gets replaced by the new key. If you supplied a
+ * @value_destroy_func when creating the #GHashTable, the old value is freed
* using that function. If you supplied a @key_destroy_func when creating the
* #GHashTable, the old key is freed using that function.
*/
@@ -14991,60 +16014,169 @@
/**
- * g_hostname_is_ascii_encoded:
- * @hostname: a hostname
+ * g_hmac_copy:
+ * @hmac: the #GHmac to copy
*
- * Tests if @hostname contains segments with an ASCII-compatible
- * encoding of an Internationalized Domain Name. If this returns
- * %TRUE, you should decode the hostname with g_hostname_to_unicode()
- * before displaying it to the user.
- * Note that a hostname might contain a mix of encoded and unencoded
- * segments, and so it is possible for g_hostname_is_non_ascii() and
- * g_hostname_is_ascii_encoded() to both return %TRUE for a name.
- * segments.
+ * Copies a #GHmac. If @hmac has been closed, by calling
+ * g_hmac_get_string() or g_hmac_get_digest(), the copied
+ * HMAC will be closed as well.
*
- * Returns: %TRUE if @hostname contains any ASCII-encoded
- * Since: 2.22
+ * when finished using it.
+ *
+ * Returns: the copy of the passed #GHmac. Use g_hmac_unref()
+ * Since: 2.30
*/
/**
- * g_hostname_is_ip_address:
- * @hostname: a hostname (or IP address in string form)
+ * g_hmac_get_string:
+ * @hmac: a #GHmac
*
- * Tests if @hostname is the string form of an IPv4 or IPv6 address.
- * (Eg, "192.168.0.1".)
+ * Gets the HMAC as an hexadecimal string.
*
- * Returns: %TRUE if @hostname is an IP address
- * Since: 2.22
+ * Once this function has been called the #GHmac can no longer be
+ * updated with g_hmac_update().
+ *
+ * The hexadecimal characters will be lower case.
+ *
+ * returned string is owned by the HMAC and should not be modified
+ * or freed.
+ *
+ * Returns: the hexadecimal representation of the HMAC. The
+ * Since: 2.30
*/
/**
- * g_hostname_is_non_ascii:
- * @hostname: a hostname
+ * g_hmac_new:
+ * @digest_type: the desired type of digest
+ * @key: (array length=key_len): the key for the HMAC
+ * @key_len: the length of the keys
*
- * Tests if @hostname contains Unicode characters. If this returns
- * %TRUE, you need to encode the hostname with g_hostname_to_ascii()
- * before using it in non-IDN-aware contexts.
- * Note that a hostname might contain a mix of encoded and unencoded
- * segments, and so it is possible for g_hostname_is_non_ascii() and
- * g_hostname_is_ascii_encoded() to both return %TRUE for a name.
+ * Creates a new #GHmac, using the digest algorithm @digest_type.
+ * If the @digest_type is not known, %NULL is returned.
+ * A #GHmac can be used to compute the HMAC of a key and an
+ * arbitrary binary blob, using different hashing algorithms.
*
- * Returns: %TRUE if @hostname contains any non-ASCII characters
- * Since: 2.22
+ * A #GHmac works by feeding a binary blob through g_hmac_update()
+ * until the data is complete; the digest can then be extracted
+ * using g_hmac_get_string(), which will return the checksum as a
+ * hexadecimal string; or g_hmac_get_digest(), which will return a
+ * array of raw bytes. Once either g_hmac_get_string() or
+ * g_hmac_get_digest() have been called on a #GHmac, the HMAC
+ * will be closed and it won't be possible to call g_hmac_update()
+ * on it anymore.
+ *
+ * Use g_hmac_unref() to free the memory allocated by it.
+ *
+ * Returns: the newly created #GHmac, or %NULL.
+ * Since: 2.30
*/
/**
- * g_hostname_to_ascii:
- * @hostname: a valid UTF-8 or ASCII hostname
+ * g_hmac_ref:
+ * @hmac: a valid #GHmac
*
- * Converts @hostname to its canonical ASCII form; an ASCII-only
- * string containing no uppercase letters and not ending with a
- * trailing dot.
+ * Atomically increments the reference count of @hmac by one.
*
- * Returns: an ASCII hostname, which must be freed, or %NULL if
+ * This function is MT-safe and may be called from any thread.
+ *
+ * Returns: the passed in #GHmac.
+ * Since: 2.30
+ */
+
+
+/**
+ * g_hmac_unref:
+ * @hmac: a #GHmac
+ *
+ * Atomically decrements the reference count of @hmac by one.
+ *
+ * If the reference count drops to 0, all keys and values will be
+ * destroyed, and all memory allocated by the hash table is released.
+ * This function is MT-safe and may be called from any thread.
+ * Frees the memory allocated for @hmac.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_hmac_update:
+ * @hmac: a #GHmac
+ * @data: (array length=length): buffer used to compute the checksum
+ * @length: size of the buffer, or -1 if it is a nul-terminated string
+ *
+ * Feeds @data into an existing #GHmac.
+ *
+ * The HMAC must still be open, that is g_hmac_get_string() or
+ * g_hmac_get_digest() must not have been called on @hmac.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_hostname_is_ascii_encoded:
+ * @hostname: a hostname
+ *
+ * Tests if @hostname contains segments with an ASCII-compatible
+ * encoding of an Internationalized Domain Name. If this returns
+ * %TRUE, you should decode the hostname with g_hostname_to_unicode()
+ * before displaying it to the user.
+ *
+ * Note that a hostname might contain a mix of encoded and unencoded
+ * segments, and so it is possible for g_hostname_is_non_ascii() and
+ * g_hostname_is_ascii_encoded() to both return %TRUE for a name.
+ *
+ * segments.
+ *
+ * Returns: %TRUE if @hostname contains any ASCII-encoded
+ * Since: 2.22
+ */
+
+
+/**
+ * g_hostname_is_ip_address:
+ * @hostname: a hostname (or IP address in string form)
+ *
+ * Tests if @hostname is the string form of an IPv4 or IPv6 address.
+ * (Eg, "192.168.0.1".)
+ *
+ * Returns: %TRUE if @hostname is an IP address
+ * Since: 2.22
+ */
+
+
+/**
+ * g_hostname_is_non_ascii:
+ * @hostname: a hostname
+ *
+ * Tests if @hostname contains Unicode characters. If this returns
+ * %TRUE, you need to encode the hostname with g_hostname_to_ascii()
+ * before using it in non-IDN-aware contexts.
+ *
+ * Note that a hostname might contain a mix of encoded and unencoded
+ * segments, and so it is possible for g_hostname_is_non_ascii() and
+ * g_hostname_is_ascii_encoded() to both return %TRUE for a name.
+ *
+ * Returns: %TRUE if @hostname contains any non-ASCII characters
+ * Since: 2.22
+ */
+
+
+/**
+ * g_hostname_to_ascii:
+ * @hostname: a valid UTF-8 or ASCII hostname
+ *
+ * Converts @hostname to its canonical ASCII form; an ASCII-only
+ * string containing no uppercase letters and not ending with a
+ * trailing dot.
+ *
+ * @hostname is in some way invalid.
+ *
+ * Returns: an ASCII hostname, which must be freed, or %NULL if
* Since: 2.22
*/
@@ -15057,9 +16189,12 @@
* string in Unicode normalization form C, containing no uppercase
* letters, no forbidden characters, and no ASCII-encoded segments,
* and not ending with a trailing dot.
+ *
* Of course if @hostname is not an internationalized hostname, then
* the canonical presentation form will be entirely ASCII.
*
+ * @hostname is in some way invalid.
+ *
* Returns: a UTF-8 hostname, which must be freed, or %NULL if
* Since: 2.22
*/
@@ -15076,6 +16211,7 @@
* Same as the standard UNIX routine iconv(), but
* may be implemented via libiconv on UNIX flavors that lack
* a native implementation.
+ *
* GLib provides g_convert() and g_locale_to_utf8() which are likely
* more convenient than the raw iconv wrappers.
*
@@ -15092,6 +16228,7 @@
* a native implementation. Should be called to clean up
* the conversion descriptor from g_iconv_open() when
* you are done converting things.
+ *
* GLib provides g_convert() and g_locale_to_utf8() which are likely
* more convenient than the raw iconv wrappers.
*
@@ -15107,8 +16244,10 @@
* Same as the standard UNIX routine iconv_open(), but
* may be implemented via libiconv on UNIX flavors that lack
* a native implementation.
+ *
* GLib provides g_convert() and g_locale_to_utf8() which are likely
* more convenient than the raw iconv wrappers.
+ *
* opening the converter failed.
*
* Returns: a "conversion descriptor", or (GIConv)-1 if
@@ -15125,6 +16264,7 @@
* default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function
* returns %FALSE it is automatically removed from the list of event
* sources and will not be called again.
+ *
* This internally creates a main loop source using g_idle_source_new()
* and attaches it to the main loop context using g_source_attach().
* You can do these steps manually if you need greater control.
@@ -15143,6 +16283,7 @@
* Adds a function to be called whenever there are no higher priority
* events pending. If the function returns %FALSE it is automatically
* removed from the list of event sources and will not be called again.
+ *
* This internally creates a main loop source using g_idle_source_new()
* and attaches it to the main loop context using g_source_attach().
* You can do these steps manually if you need greater control.
@@ -15166,6 +16307,7 @@
* g_idle_source_new:
*
* Creates a new idle source.
+ *
* The source will not initially be associated with any #GMainContext
* and must be added to one with g_source_attach() before it will be
* executed. Note that the default priority for idle sources is
@@ -15281,6 +16423,7 @@
*
* Adds the #GIOChannel into the default main loop context
* with the given priority.
+ *
* This internally creates a main loop source using g_io_create_watch()
* and attaches it to the main loop context with g_source_attach().
* You can do these steps manually if you need greater control.
@@ -15307,6 +16450,7 @@
* @en: an <literal>errno</literal> error number, e.g. %EINVAL
*
* Converts an <literal>errno</literal> error number to a #GIOChannelError.
+ *
* %G_IO_CHANNEL_ERROR_INVAL.
*
* Returns: a #GIOChannelError error number, e.g.
@@ -15328,6 +16472,7 @@
* @error: location to store an error of type #GIOChannelError
*
* Flushes the write buffer for the GIOChannel.
+ *
* #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or
* #G_IO_STATUS_ERROR.
*
@@ -15375,6 +16520,7 @@
* will be closed when @channel receives its final unref and is
* destroyed. The default value of this is %TRUE for channels created
* by g_io_channel_new_file (), and %FALSE for all other channels.
+ *
* the GIOChannel data structure.
*
* Returns: Whether the channel will be closed on the final unref of
@@ -15388,6 +16534,7 @@
* Gets the encoding for the input/output of the channel.
* The internal encoding is always UTF-8. The encoding %NULL
* makes the channel safe for binary data.
+ *
* owned by GLib and must not be freed.
*
* Returns: A string containing the encoding, this string is
@@ -15400,6 +16547,7 @@
*
* Gets the current flags for a #GIOChannel, including read-only
* flags such as %G_IO_FLAG_IS_READABLE.
+ *
* The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITEABLE
* are cached for internal use by the channel when it is created.
* If they should change at some later point (e.g. partial shutdown
@@ -15419,6 +16567,7 @@
* This returns the string that #GIOChannel uses to determine
* where in the file a line break occurs. A value of %NULL
* indicates autodetection.
+ *
* is owned by GLib and must not be freed.
*
* Returns: The line termination string. This value
@@ -15430,6 +16579,7 @@
* @channel: a #GIOChannel
*
* Initializes a #GIOChannel struct.
+ *
* This is called by each of the above functions when creating a
* #GIOChannel, and so is not often needed by the application
* programmer (unless you are creating a new type of #GIOChannel).
@@ -15461,8 +16611,10 @@
*
* Reads data from a #GIOChannel.
*
- * Returns: %G_IO_ERROR_NONE if the operation was successful.
+ *
* Deprecated:2.2: Use g_io_channel_read_chars() instead.
+ *
+ * Returns: %G_IO_ERROR_NONE if the operation was successful.
*/
@@ -15490,6 +16642,7 @@
*
* Reads a line, including the terminating character(s),
* from a #GIOChannel into a newly-allocated string.
+ * @str_return will contain allocated memory if the return
* is %G_IO_STATUS_NORMAL.
*
* Returns: the status of the operation.
@@ -15517,6 +16670,7 @@
* @error: location to return an error of type #GConvertError or #GIOChannelError
*
* Reads all the remaining data from the file.
+ *
* This function never returns %G_IO_STATUS_EOF.
*
* Returns: %G_IO_STATUS_NORMAL on success.
@@ -15555,8 +16709,10 @@
* Sets the current position in the #GIOChannel, similar to the standard
* library function fseek().
*
- * Returns: %G_IO_ERROR_NONE if the operation was successful.
+ *
* Deprecated:2.2: Use g_io_channel_seek_position() instead.
+ *
+ * Returns: %G_IO_ERROR_NONE if the operation was successful.
*/
@@ -15589,6 +16745,7 @@
*
* The buffering state can only be set if the channel's encoding
* is %NULL. For any other encoding, the channel must be buffered.
+ *
* A buffered channel can only be set unbuffered if the channel's
* internal buffers have been flushed. Newly created channels or
* channels which have returned %G_IO_STATUS_EOF
@@ -15599,9 +16756,11 @@
* and an offset of zero. Note that this means that socket-based
* channels cannot be set unbuffered once they have had data
* read from them.
+ *
* On unbuffered channels, it is safe to mix read and write
* calls from the new and old APIs, if this is necessary for
* maintaining old code.
+ *
* The default state of the channel is buffered.
*/
@@ -15625,7 +16784,9 @@
* Sets the encoding for the input/output of the channel.
* The internal encoding is always UTF-8. The default encoding
* for the external file is UTF-8.
+ *
* The encoding %NULL is safe to use with binary data.
+ *
* The encoding can only be set if one of the following conditions
* is true:
* <itemizedlist>
@@ -15711,6 +16872,7 @@
* @Returns: the file descriptor of the #GIOChannel.
*
* Returns the file descriptor of the #GIOChannel.
+ *
* On Windows this function returns the file descriptor or socket of
* the #GIOChannel.
*/
@@ -15723,14 +16885,18 @@
*
* Creates a new #GIOChannel given a file descriptor. On UNIX systems
* this works for plain files, pipes, and sockets.
+ *
* The returned #GIOChannel has a reference count of 1.
+ *
* The default encoding for #GIOChannel is UTF-8. If your application
* is reading output from a command using via pipe, you may need to set
* the encoding to the encoding of the current locale (see
* g_get_charset()) with the g_io_channel_set_encoding() function.
+ *
* If you want to read raw binary data without interpretation, then
* call the g_io_channel_set_encoding() function with %NULL for the
* encoding argument.
+ *
* This function is available in GLib on Windows, too, but you should
* avoid using it on Windows. The domain of file descriptors and
* sockets overlap. There is no way for GLib to know which one you mean
@@ -15755,6 +16921,7 @@
*
* Creates a new #GIOChannel given a file descriptor on Windows. This
* works for file descriptors from the C runtime.
+ *
* This function works for file descriptors as returned by the open(),
* creat(), pipe() and fileno() calls in the Microsoft C runtime. In
* order to meaningfully use this function your code should use the
@@ -15764,6 +16931,7 @@
* version that supported using msvcrt.dll as the C runtime was version
* 6. The GNU compiler and toolchain for Windows, also known as Mingw,
* fully supports msvcrt.dll.
+ *
* If you have created a #GIOChannel for a file descriptor and started
* watching (polling) it, you shouldn't call read() on the file
* descriptor. This is because adding polling for a file descriptor is
@@ -15771,6 +16939,7 @@
* blocked in a read() from the file descriptor most of the time. All
* reads from the file descriptor should be done by this internal GLib
* thread. Your code should call only g_io_channel_read().
+ *
* This function is available only in GLib on Windows.
*/
@@ -15781,6 +16950,7 @@
* @Returns: a new #GIOChannel.
*
* Creates a new #GIOChannel given a window handle on Windows.
+ *
* This function creates a #GIOChannel that can be used to poll for
* Windows messages for the window in question.
*/
@@ -15792,8 +16962,10 @@
* @Returns: a new #GIOChannel
*
* Creates a new #GIOChannel given a socket on Windows.
+ *
* This function works for sockets created by Winsock. It's available
* only in GLib on Windows.
+ *
* Polling a #GSource created to watch a channel for a socket puts the
* socket in non-blocking mode. This is a side-effect of the
* implementation and unavoidable.
@@ -15809,8 +16981,10 @@
*
* Writes data to a #GIOChannel.
*
- * Returns: %G_IO_ERROR_NONE if the operation was successful.
+ *
* Deprecated:2.2: Use g_io_channel_write_chars() instead.
+ *
+ * Returns: %G_IO_ERROR_NONE if the operation was successful.
*/
@@ -15823,6 +16997,7 @@
* @error: a location to return an error of type #GConvertError or #GIOChannelError
*
* Replacement for g_io_channel_write() with the new API.
+ *
* On seekable channels with encodings other than %NULL or UTF-8, generic
* mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
* may only be made on a channel from which data has been read in the
@@ -15853,9 +17028,11 @@
* Creates a #GSource that's dispatched when @condition is met for the
* given @channel. For example, if condition is #G_IO_IN, the source will
* be dispatched when there's data available for reading.
+ *
* g_io_add_watch() is a simpler interface to this same functionality, for
* the case where you want to add the source to the default main loop context
* at the default priority.
+ *
* On Windows, polling a #GSource created to watch a channel for a socket
* puts the socket in non-blocking mode. This is a side-effect of the
* implementation and unavoidable.
@@ -15883,10 +17060,12 @@
*
* Returns the value associated with @key under @group_name as a
* boolean.
+ *
* If @key cannot be found then %FALSE is returned and @error is set
* to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
* associated with @key cannot be interpreted as a boolean then %FALSE
* is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
+ *
* or %FALSE if the key was not found or could not be parsed.
*
* Returns: the value associated with the key as a boolean,
@@ -15904,10 +17083,12 @@
*
* Returns the values associated with @key under @group_name as
* booleans.
+ *
* If @key cannot be found then %NULL is returned and @error is set to
* #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
* with @key cannot be interpreted as booleans then %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
+ *
* the values associated with the key as a list of booleans, or %NULL if the
* key was not found or could not be parsed. The returned list of booleans
* should be freed with g_free() when no longer needed.
@@ -15926,6 +17107,8 @@
*
* Retrieves a comment above @key from @group_name.
* If @key is %NULL then @comment will be read from above
+ * @group_name. If both @key and @group_name are %NULL, then
+ * @comment will be read from above the first group in the file.
*
* Returns: a comment that should be freed with g_free()
* Since: 2.6
@@ -15941,10 +17124,12 @@
*
* Returns the value associated with @key under @group_name as a
* double. If @group_name is %NULL, the start_group is used.
+ *
* If @key cannot be found then 0.0 is returned and @error is set to
* #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
* with @key cannot be interpreted as a double then 0.0 is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
+ *
* 0.0 if the key was not found or could not be parsed.
*
* Returns: the value associated with the key as a double, or
@@ -15962,10 +17147,12 @@
*
* Returns the values associated with @key under @group_name as
* doubles.
+ *
* If @key cannot be found then %NULL is returned and @error is set to
* #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
* with @key cannot be interpreted as doubles then %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
+ *
* the values associated with the key as a list of doubles, or %NULL if the
* key was not found or could not be parsed. The returned list of doubles
* should be freed with g_free() when no longer needed.
@@ -15982,6 +17169,8 @@
*
* Returns all groups in the key file loaded with @key_file.
* The array of returned groups will be %NULL-terminated, so
+ * @length may optionally be %NULL.
+ *
* Use g_strfreev() to free it.
*
* Returns: a newly-allocated %NULL-terminated array of strings.
@@ -15999,6 +17188,7 @@
* Returns the value associated with @key under @group_name as a signed
* 64-bit integer. This is similar to g_key_file_get_integer() but can return
* 64-bit results without truncation.
+ *
* 0 if the key was not found or could not be parsed.
*
* Returns: the value associated with the key as a signed 64-bit integer, or
@@ -16015,10 +17205,12 @@
*
* Returns the value associated with @key under @group_name as an
* integer.
+ *
* If @key cannot be found then 0 is returned and @error is set to
* #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
* with @key cannot be interpreted as an integer then 0 is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
+ *
* 0 if the key was not found or could not be parsed.
*
* Returns: the value associated with the key as an integer, or
@@ -16036,10 +17228,12 @@
*
* Returns the values associated with @key under @group_name as
* integers.
+ *
* If @key cannot be found then %NULL is returned and @error is set to
* #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
* with @key cannot be interpreted as integers then %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
+ *
* the values associated with the key as a list of integers, or %NULL if
* the key was not found or could not be parsed. The returned list of
* integers should be freed with g_free() when no longer needed.
@@ -16061,6 +17255,7 @@
* optionally be %NULL. In the event that the @group_name cannot
* be found, %NULL is returned and @error is set to
* #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
+ *
* Use g_strfreev() to free it.
*
* Returns: a newly-allocated %NULL-terminated array of strings.
@@ -16079,10 +17274,12 @@
* Returns the value associated with @key under @group_name
* translated in the given @locale if available. If @locale is
* %NULL then the current locale is assumed.
+ *
* If @key cannot be found then %NULL is returned and @error is set
* to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
* with @key cannot be interpreted or no suitable translation can
* be found then the untranslated value is returned.
+ *
* key cannot be found.
*
* Returns: a newly allocated string or %NULL if the specified
@@ -16108,6 +17305,7 @@
* can be found then the untranslated values are returned. The
* returned array is %NULL-terminated, so @length may optionally
* be %NULL.
+ *
* or %NULL if the key isn't found. The string array should be freed
* with g_strfreev().
*
@@ -16137,9 +17335,12 @@
* Returns the string value associated with @key under @group_name.
* Unlike g_key_file_get_value(), this function handles escape sequences
* like \s.
+ *
* In the event the key cannot be found, %NULL is returned and
+ * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
* event that the @group_name cannot be found, %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
+ *
* key cannot be found.
*
* Returns: a newly allocated string or %NULL if the specified
@@ -16156,9 +17357,12 @@
* @error: return location for a #GError, or %NULL
*
* Returns the values associated with @key under @group_name.
+ *
* In the event the key cannot be found, %NULL is returned and
+ * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
* event that the @group_name cannot be found, %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
+ *
* a %NULL-terminated string array or %NULL if the specified
* key cannot be found. The array should be freed with g_strfreev().
*
@@ -16177,6 +17381,7 @@
* Returns the value associated with @key under @group_name as an unsigned
* 64-bit integer. This is similar to g_key_file_get_integer() but can return
* large positive results without truncation.
+ *
* or 0 if the key was not found or could not be parsed.
*
* Returns: the value associated with the key as an unsigned 64-bit integer,
@@ -16193,9 +17398,13 @@
*
* Returns the raw value associated with @key under @group_name.
* Use g_key_file_get_string() to retrieve an unescaped UTF-8 string.
+ *
* In the event the key cannot be found, %NULL is returned and
+ * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
* event that the @group_name cannot be found, %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
+ *
+ *
* key cannot be found.
*
* Returns: a newly allocated string or %NULL if the specified
@@ -16209,6 +17418,7 @@
* @group_name: a group name
*
* Looks whether the key file has the group @group_name.
+ *
* otherwise.
*
* Returns: %TRUE if @group_name is a part of @key_file, %FALSE
@@ -16224,12 +17434,16 @@
* @error: return location for a #GError
*
* Looks whether the key file has the key @key in the group
+ * @group_name.
+ *
* <note>This function does not follow the rules for #GError strictly;
* the return value both carries meaning and signals an error. To use
* this function, you must pass a #GError pointer in @error, and check
* whether it is not %NULL to see if an error occurred.</note>
+ *
* Language bindings should use g_key_file_get_value() to test whether
* or not a key exists.
+ *
* otherwise.
*
* Returns: %TRUE if @key is a part of @group_name, %FALSE
@@ -16264,6 +17478,7 @@
* This function looks for a key file named @file in the paths
* returned from g_get_user_data_dir() and g_get_system_data_dirs(),
* loads the file into @key_file and returns the file's full path in
+ * @full_path. If the file could not be loaded then an %error is
* set to either a #GFileError or #GKeyFileError.
*
* Returns: %TRUE if a key file could be loaded, %FALSE othewise
@@ -16436,6 +17651,7 @@
* @length: number of double values in @list
*
* Associates a list of double values with @key under
+ * @group_name. If @key cannot be found then it is created.
*
* Since: 2.12
*/
@@ -16522,6 +17738,7 @@
* @length: the length of @list
*
* Associates a list of string values for @key and @locale under
+ * @group_name. If the translation for @key cannot be found then
* it is created.
*
* Since: 2.6
@@ -16583,6 +17800,7 @@
* @value: a string
*
* Associates a new value with @key under @group_name.
+ *
* If @key cannot be found then it is created. If @group_name cannot
* be found then it is created. To set an UTF-8 string which may contain
* characters that need escaping (such as newlines or spaces), use
@@ -16599,8 +17817,10 @@
* @error: return location for a #GError, or %NULL
*
* This function outputs @key_file as a string.
+ *
* Note that this function never reports an error,
* so it is safe to pass %NULL as @error.
+ *
* the contents of the #GKeyFile
*
* Returns: a newly allocated string holding
@@ -16624,22 +17844,27 @@
* @data: the data for the new element
*
* Adds a new element on to the end of the list.
+ *
* <note><para>
* The return value is the new start of the list, which
* may have changed, so make sure you store the new value.
* </para></note>
+ *
* <note><para>
* Note that g_list_append() has to traverse the entire list
* to find the end, which is inefficient when adding multiple
* elements. A common idiom to avoid the inefficiency is to prepend
* the elements and reverse the list when all elements have been added.
* </para></note>
+ *
* |[
* /* Notice that these are initialized to the empty list. */
* GList *list = NULL, *number_list = NULL;
+ *
* /* This is a list of strings. */
* list = g_list_append (list, "first");
* list = g_list_append (list, "second");
+ *
* /* This is a list of integers. */
* number_list = g_list_append (number_list, GINT_TO_POINTER (27));
* number_list = g_list_append (number_list, GINT_TO_POINTER (14));
@@ -16667,6 +17892,7 @@
* @list: a #GList
*
* Copies a #GList.
+ *
* <note><para>
* Note that this is a "shallow" copy. If the list elements
* consist of pointers to data, the pointers are copied but
@@ -16697,6 +17923,7 @@
*
* Finds the element in a #GList which
* contains the given data.
+ *
* or %NULL if it is not found
*
* Returns: the found #GList element,
@@ -16725,6 +17952,7 @@
* @list: a #GList
*
* Gets the first element in a #GList.
+ *
* or %NULL if the #GList has no elements
*
* Returns: the first element in the #GList,
@@ -16747,6 +17975,7 @@
*
* Frees all of the memory used by a #GList.
* The freed elements are returned to the slice allocator.
+ *
* <note><para>
* If list elements contain dynamically-allocated memory,
* you should either use g_list_free_full() or free them manually
@@ -16790,6 +18019,7 @@
*
* Gets the position of the element containing
* the given data (starting from 0).
+ *
* or -1 if the data is not found
*
* Returns: the index of the element containing the data,
@@ -16853,6 +18083,7 @@
* @list: a #GList
*
* Gets the last element in a #GList.
+ *
* or %NULL if the #GList has no elements
*
* Returns: the last element in the #GList,
@@ -16864,6 +18095,7 @@
* @list: a #GList
*
* Gets the number of elements in a #GList.
+ *
* <note><para>
* This function iterates over the whole list to
* count its elements.
@@ -16888,6 +18120,7 @@
* @n: the position of the element, counting from 0
*
* Gets the element at the given position in a #GList.
+ *
* the end of the #GList
*
* Returns: the element, or %NULL if the position is off
@@ -16900,6 +18133,7 @@
* @n: the position of the element
*
* Gets the data of the element at the given position.
+ *
* is off the end of the #GList
*
* Returns: the element's data, or %NULL if the position
@@ -16912,6 +18146,7 @@
* @n: the position of the element, counting from 0
*
* Gets the element @n places before @list.
+ *
* off the end of the #GList
*
* Returns: the element, or %NULL if the position is
@@ -16923,12 +18158,13 @@
*
* Restores the previous #GAllocator, used when allocating #GList
* elements.
+ *
* Note that this function is not available if GLib has been compiled
* with <option>--disable-mem-pools</option>
- * to the <link linkend="glib-Memory-Slices">slice
- * allocator</link>
*
* Deprecated:2.10: It does nothing, since #GList has been converted
+ * to the <link linkend="glib-Memory-Slices">slice
+ * allocator</link>
*/
@@ -16939,6 +18175,7 @@
*
* Gets the position of the given element
* in the #GList (starting from 0).
+ *
* or -1 if the element is not found
*
* Returns: the position of the element in the #GList,
@@ -16951,10 +18188,12 @@
* @data: the data for the new element
*
* Adds a new element on to the start of the list.
+ *
* <note><para>
* The return value is the new start of the list, which
* may have changed, so make sure you store the new value.
* </para></note>
+ *
* |[
* /* Notice that it is initialized to the empty list. */
* GList *list = NULL;
@@ -16981,12 +18220,13 @@
*
* Sets the allocator to use to allocate #GList elements. Use
* g_list_pop_allocator() to restore the previous allocator.
+ *
* Note that this function is not available if GLib has been compiled
* with <option>--disable-mem-pools</option>
- * to the <link linkend="glib-Memory-Slices">slice
- * allocator</link>
*
* Deprecated:2.10: It does nothing, since #GList has been converted
+ * to the <link linkend="glib-Memory-Slices">slice
+ * allocator</link>
*/
@@ -17069,7 +18309,9 @@
* g_listenv:
*
* Gets the names of all variables set in the environment.
+ *
* with g_strfreev().
+ *
* Programs that want to be portable to Windows should typically use
* this function and g_getenv() instead of using the environ array
* from the C library directly. On Windows, the strings in the environ
@@ -17126,7 +18368,9 @@
* information about the symbolic link itself and not the file that it
* refers to. If the system does not support symbolic links g_lstat()
* is identical to g_stat().
+ *
* See your C library manual for more details about lstat().
+ *
* occurred
*
* Returns: 0 if the information was successfully retrieved, -1 if an error
@@ -17141,14 +18385,16 @@
* Tries to become the owner of the specified context.
* If some other thread is the owner of the context,
* returns %FALSE immediately. Ownership is properly
+ * recursive: the owner can require ownership again
* and will release ownership when g_main_context_release()
* is called as many times as g_main_context_acquire().
+ *
* You must be the owner of a context before you
* can call g_main_context_prepare(), g_main_context_query(),
* g_main_context_check(), g_main_context_dispatch().
+ *
* this thread is now the owner of @context.
*
- * Recursive: the owner can require ownership again
* Returns: %TRUE if the operation succeeded, and
*/
@@ -17256,6 +18502,7 @@
* programs applications may sometimes want to temporarily push a
* non-default context, so it is not safe to assume that this will
* always return %NULL if threads are not initialized.)
+ *
* thread-default context is the global default context.
*
* Returns: the thread-default #GMainContext, or %NULL if the
@@ -17271,17 +18518,22 @@
*
* Invokes a function in such a way that @context is owned during the
* invocation of @function.
+ *
* If @context is %NULL then the global default main context â as
* returned by g_main_context_default() â is used.
+ *
* If @context is owned by the current thread, @function is called
* directly. Otherwise, if @context is the thread-default main context
* of the current thread and g_main_context_acquire() succeeds, then
+ * @function is called and g_main_context_release() is called
* afterwards.
+ *
* In any other case, an idle source is created to call @function and
* that source is attached to @context (presumably to be run in another
* thread). The idle source is attached with #G_PRIORITY_DEFAULT
* priority. If you want a different priority, use
* g_main_context_invoke_full().
+ *
* Note that, as with normal idle functions, @function should probably
* return %FALSE. If it returns %TRUE, it will be continuously run in a
* loop (and may prevent this call from returning).
@@ -17300,9 +18552,12 @@
*
* Invokes a function in such a way that @context is owned during the
* invocation of @function.
+ *
* This function is the same as g_main_context_invoke() except that it
* lets you specify the priority incase @function ends up being
* scheduled as an idle and also lets you give a #GDestroyNotify for @data.
+ *
+ * @notify should not assume that it is called from any particular
* thread or with any particular context acquired.
*
* Since: 2.28
@@ -17336,6 +18591,7 @@
* sources are not waited to become ready, only those highest priority
* events sources will be dispatched (if any), that are ready at this
* given moment without further waiting.
+ *
* Note that even when @may_block is %TRUE, it is still possible for
* g_main_context_iteration() to return %FALSE, since the the wait may
* be interrupted for other reasons than an event source becoming ready.
@@ -17381,6 +18637,7 @@
*
* Prepares to poll sources within a main loop. The resulting information
* for polling is determined by calling g_main_context_query ().
+ *
* prior to polling.
*
* Returns: %TRUE if some source is ready to be dispatched
@@ -17401,6 +18658,7 @@
* g_main_context_get_thread_default(), <emphasis>not</emphasis> the
* one returned by g_main_context_default(), so it does not affect the
* context used by functions like g_idle_add().
+ *
* Normally you would call this function shortly after creating a new
* thread, passing it a #GMainContext which will be run by a
* #GMainLoop in that thread, to set a new default context for all
@@ -17414,6 +18672,7 @@
* g_main_context_pop_thread_default() pair, but it is up to you to
* ensure that no other asynchronous operations accidentally get
* started while the non-default context is active.
+ *
* Beware that libraries that predate this function may not correctly
* handle being used from a thread with a thread-default context. Eg,
* see g_file_supports_thread_contexts().
@@ -17431,6 +18690,7 @@
* @n_fds: length of @fds.
*
* Determines information necessary to poll this main loop.
+ *
* or, if more than @n_fds records need to be stored, the number
* of records that need to be stored.
*
@@ -17477,6 +18737,7 @@
* will be used instead of the poll() system call
* (or GLib's replacement function, which is used where
* poll() isn't available).
+ *
* This function could possibly be used to integrate the GLib event
* loop with an external event loop.
*/
@@ -17502,6 +18763,7 @@
* is the owner, atomically drop @mutex and wait on @cond until
* that owner releases ownership or until @cond is signaled, then
* try again (once) to become the owner.
+ *
* this thread is now the owner of @context.
*
* Returns: %TRUE if the operation succeeded, and
@@ -17537,10 +18799,13 @@
* (or g_main_loop_run(), etc.) it returns 1. When called from within
* a callback to a recursive call to g_main_context_iteration(),
* it returns 2. And so forth.
+ *
* This function is useful in a situation like the following:
* Imagine an extremely simple "garbage collected" system.
+ *
* |[
* static GList *free_list;
+ *
* gpointer
* allocate_memory (gsize size)
* {
@@ -17548,6 +18813,7 @@
* free_list = g_list_prepend (free_list, result);
* return result;
* }
+ *
* void
* free_allocated_memory (void)
* {
@@ -17557,19 +18823,23 @@
* g_list_free (free_list);
* free_list = NULL;
* }
+ *
* [...]
+ *
* while (TRUE);
* {
* g_main_context_iteration (NULL, TRUE);
* free_allocated_memory();
* }
* ]|
+ *
* This works from an application, however, if you want to do the same
* thing from a library, it gets more difficult, since you no longer
* control the main loop. You might think you can simply use an idle
* function to make the call to free_allocated_memory(), but that
* doesn't work, since the idle function could be called from a
* recursive callback. This can be fixed by using g_main_depth()
+ *
* |[
* gpointer
* allocate_memory (gsize size)
@@ -17580,10 +18850,12 @@
* free_list = g_list_prepend (free_list, block);
* return block->mem;
* }
+ *
* void
* free_allocated_memory (void)
* {
* GList *l;
+ *
* int depth = g_main_depth ();
* for (l = free_list; l; );
* {
@@ -17595,10 +18867,12 @@
* g_free (block);
* free_list = g_list_delete_link (free_list, l);
* }
+ *
* l = next;
* }
* }
* ]|
+ *
* There is a temptation to use g_main_depth() to solve
* problems with reentrancy. For instance, while waiting for data
* to be received from the network in response to a menu item,
@@ -17610,6 +18884,7 @@
* these checks all over your code, since there are doubtless many,
* many things that the user could do. Instead, you can use the
* following techniques:
+ *
* <orderedlist>
* <listitem>
* <para>
@@ -17701,6 +18976,7 @@
*
* Stops a #GMainLoop from running. Any calls to g_main_loop_run()
* for the loop will return.
+ *
* Note that sources that have already been dispatched when
* g_main_loop_quit() is called will still be executed.
*/
@@ -17753,8 +19029,10 @@
* Checks if any events are pending for the default #GMainContext
* (i.e. ready to be processed).
*
- * Returns: %TRUE if any events are pending.
+ *
* Deprected: 2.2: Use g_main_context_pending() instead.
+ *
+ * Returns: %TRUE if any events are pending.
*/
@@ -17845,8 +19123,9 @@
* This call existed before #GMappedFile had refcounting and is currently
* exactly the same as g_mapped_file_unref().
*
- * Since: 2.8
* Deprecated:2.22: Use g_mapped_file_unref() instead.
+ *
+ * Since: 2.8
*/
@@ -17855,8 +19134,10 @@
* @file: a #GMappedFile
*
* Returns the contents of a #GMappedFile.
+ *
* Note that the contents may not be zero-terminated,
* even if the #GMappedFile is backed by a text file.
+ *
* If the file is empty then %NULL is returned.
*
* Returns: the contents of @file, or %NULL.
@@ -17882,14 +19163,17 @@
* @error: return location for a #GError, or %NULL
*
* Maps a file into memory. On UNIX, this is using the mmap() function.
+ *
* If @writable is %TRUE, the mapped buffer may be modified, otherwise
* it is an error to modify the mapped buffer. Modifications to the buffer
* are not visible to other processes mapping the same file, and are not
* written back to the file.
+ *
* Note that modifications of the underlying file might affect the contents
* of the #GMappedFile. Therefore, mapping should only be used if the file
* will not be modified, or if all modifications of the file are done
* atomically (e.g. using g_file_set_contents()).
+ *
* with g_mapped_file_unref(), or %NULL if the mapping failed.
*
* Returns: a newly allocated #GMappedFile which must be unref'd
@@ -17915,7 +19199,9 @@
*
* Decrements the reference count of @file by one. If the reference count
* drops to 0, unmaps the buffer of @file and frees it.
+ *
* It is safe to call this function from any thread.
+ *
* Since 2.22
*/
@@ -17933,21 +19219,28 @@
* Collects the attributes of the element from the data passed to the
* #GMarkupParser start_element function, dealing with common error
* conditions and supporting boolean values.
+ *
* This utility function is not required to write a parser but can save
* a lot of typing.
+ *
* The @element_name, @attribute_names, @attribute_values and @error
* parameters passed to the start_element callback should be passed
* unmodified to this function.
+ *
* Following these arguments is a list of "supported" attributes to collect.
* It is an error to specify multiple attributes with the same name. If any
* attribute not in the list appears in the @attribute_names array then an
* unknown attribute error will result.
+ *
* The #GMarkupCollectType field allows specifying the type of collection
* to perform and if a given attribute must appear or is optional.
+ *
* The attribute name is simply the name of the attribute to collect.
+ *
* The pointer should be of the appropriate type (see the descriptions
* under #GMarkupCollectType) and may be %NULL in case a particular
* attribute is to be allowed but ignored.
+ *
* This function deals with issuing errors for missing attributes
* (of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes
* (of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate
@@ -17970,9 +19263,11 @@
* Less than, greater than, ampersand, etc. are replaced with the
* corresponding entities. This function would typically be used
* when writing out a file to be parsed with the markup parser.
+ *
* Note that this function doesn't protect whitespace and line endings
* from being processed according to the XML rules for normalization
* of line endings and attribute values.
+ *
* Note also that this function will produce character references in
* the range of &#x1; ... &#x1f; for all control sequences
* except for tabstop, newline and carriage return. The character
@@ -17990,6 +19285,7 @@
*
* Signals to the #GMarkupParseContext that all data has been
* fed into the parse context with g_markup_parse_context_parse().
+ *
* This function reports an error if the document isn't complete,
* for example if elements are still open.
*
@@ -18002,6 +19298,7 @@
* @context: a #GMarkupParseContext
*
* Frees a #GMarkupParseContext.
+ *
* This function can't be called from inside one of the
* #GMarkupParser functions or while a subparser is pushed.
*/
@@ -18012,6 +19309,7 @@
* @context: a #GMarkupParseContext
*
* Retrieves the name of the currently open element.
+ *
* If called from the start_element or end_element handlers this will
* give the element_name as passed to those functions. For the parent
* elements, see g_markup_parse_context_get_element_stack().
@@ -18026,10 +19324,12 @@
* @context: a #GMarkupParseContext
*
* Retrieves the element stack from the internal state of the parser.
+ *
* The returned #GSList is a list of strings where the first item is
* the currently open tag (as would be returned by
* g_markup_parse_context_get_element()) and the next item is its
* immediate parent.
+ *
* This function is intended to be used in the start_element and
* end_element handlers where g_markup_parse_context_get_element()
* would merely return the name of the element that is being
@@ -18058,9 +19358,11 @@
* @context: a #GMarkupParseContext
*
* Returns the user_data associated with @context.
+ *
* This will either be the user_data that was provided to
* g_markup_parse_context_new() or to the most recent call
* of g_markup_parse_context_push().
+ *
* the markup context and will be freed when
* g_markup_parse_context_free() is called.
*
@@ -18094,6 +19396,7 @@
* @error: return location for a #GError
*
* Feed some data to the #GMarkupParseContext.
+ *
* The data need not be valid UTF-8; an error will be signaled if
* it's invalid. The data need not be an entire document; you can
* feed a document into the parser incrementally, via multiple calls
@@ -18112,11 +19415,14 @@
* @context: a #GMarkupParseContext
*
* Completes the process of a temporary sub-parser redirection.
+ *
* This function exists to collect the user_data allocated by a
* matching call to g_markup_parse_context_push(). It must be called
* in the end_element handler corresponding to the start_element
* handler during which g_markup_parse_context_push() was called.
* You must not call this function from the error callback -- the
+ * @user_data is provided directly to the callback in that case.
+ *
* This function is not intended to be directly called by users
* interested in invoking subparsers. Instead, it is intended to
* be used by the subparsers themselves to implement a higher-level
@@ -18134,15 +19440,18 @@
* @user_data: user data to pass to #GMarkupParser functions
*
* Temporarily redirects markup data to a sub-parser.
+ *
* This function may only be called from the start_element handler of
* a #GMarkupParser. It must be matched with a corresponding call to
* g_markup_parse_context_pop() in the matching end_element handler
* (except in the case that the parser aborts due to an error).
+ *
* All tags, text and other data between the matching tags is
* redirected to the subparser given by @parser. @user_data is used
* as the user_data for that parser. @user_data is also passed to the
* error callback in the event that an error occurs. This includes
* errors that occur in subparsers of the subparser.
+ *
* The end tag matching the start tag for which this call was made is
* handled by the previous parser (which is given its own user_data)
* which is why g_markup_parse_context_pop() is provided to allow "one
@@ -18151,17 +19460,21 @@
* the error callback of the subparser and g_markup_parse_context_pop()
* should not be called. In either case, if @user_data was allocated
* then it ought to be freed from both of these locations.
+ *
* This function is not intended to be directly called by users
* interested in invoking subparsers. Instead, it is intended to be
* used by the subparsers themselves to implement a higher-level
* interface.
+ *
* As an example, see the following implementation of a simple
* parser that counts the number of tags encountered.
+ *
* |[
* typedef struct
* {
* gint tag_count;
* } CounterData;
+ *
* static void
* counter_start_element (GMarkupParseContext *context,
* const gchar *element_name,
@@ -18171,16 +19484,20 @@
* GError **error)
* {
* CounterData *data = user_data;
+ *
* data->tag_count++;
* }
+ *
* static void
* counter_error (GMarkupParseContext *context,
* GError *error,
* gpointer user_data)
* {
* CounterData *data = user_data;
+ *
* g_slice_free (CounterData, data);
* }
+ *
* static GMarkupParser counter_subparser =
* {
* counter_start_element,
@@ -18190,38 +19507,49 @@
* counter_error
* };
* ]|
+ *
* In order to allow this parser to be easily used as a subparser, the
* following interface is provided:
+ *
* |[
* void
* start_counting (GMarkupParseContext *context)
* {
* CounterData *data = g_slice_new (CounterData);
+ *
* data->tag_count = 0;
* g_markup_parse_context_push (context, &counter_subparser, data);
* }
+ *
* gint
* end_counting (GMarkupParseContext *context)
* {
* CounterData *data = g_markup_parse_context_pop (context);
* int result;
+ *
* result = data->tag_count;
* g_slice_free (CounterData, data);
+ *
* return result;
* }
* ]|
+ *
* The subparser would then be used as follows:
+ *
* |[
* static void start_element (context, element_name, ...)
* {
* if (strcmp (element_name, "count-these") == 0)
* start_counting (context);
+ *
* /* else, handle other tags... */
* }
+ *
* static void end_element (context, element_name, ...)
* {
* if (strcmp (element_name, "count-these") == 0)
* g_print ("Counted %d tags\n", end_counting (context));
+ *
* /* else, handle other tags... */
* }
* ]|
@@ -18241,6 +19569,7 @@
* want to insert literal strings into XML-style markup
* output, without having to worry that the strings
* might themselves contain markup.
+ *
* |[
* const char *store = "Fortnum & Mason";
* const char *item = "Tea";
@@ -18252,6 +19581,7 @@
* "</purchase>",
* store, item);
* ]|
+ *
* operation. Free with g_free().
*
* Returns: newly allocated result from formatting
@@ -18267,6 +19597,7 @@
* Formats the data in @args according to @format, escaping
* all string and character arguments in the fashion
* of g_markup_escape_text(). See g_markup_printf_escaped().
+ *
* operation. Free with g_free().
*
* Returns: newly allocated result from formatting
@@ -18284,10 +19615,14 @@
* references and escape sequences expanded. References refer to the last
* match done with @string against @regex and have the same syntax used by
* g_regex_replace().
+ *
* The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was
* passed to g_regex_new().
+ *
* The backreferences are extracted from the string passed to the match
* function, so you cannot call this function after freeing the string.
+ *
+ * @match_info may be %NULL in which case @string_to_expand must not
* contain references. For instance "foo\n" does not refer to an actual
* pattern and '\n' merely will be replaced with \n character,
* while to expand "\0" (whole match) one needs the result of a match.
@@ -18307,16 +19642,20 @@
* Retrieves the text matching the @match_num<!-- -->'th capturing
* parentheses. 0 is the full text of the match, 1 is the first paren
* set, 2 the second, and so on.
+ *
* If @match_num is a valid sub pattern but it didn't match anything
* (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
* string is returned.
+ *
* If the match was obtained using the DFA algorithm, that is using
* g_regex_match_all() or g_regex_match_all_full(), the retrieved
* string is not that of a set of parentheses but that of a matched
* substring. Substrings are matched in reverse order of length, so
* 0 is the longest match.
+ *
* The string is fetched from the string passed to the match function,
* so you cannot call this function after freeing the string.
+ *
* occurred. You have to free the string yourself
*
* Returns: (allow-none): The matched substring, or %NULL if an error
@@ -18332,15 +19671,19 @@
* and stores them in an array of gchar pointers. The first element in
* the returned array is the match number 0, i.e. the entire matched
* text.
+ *
* If a sub pattern didn't match anything (e.g. sub pattern 1, matching
* "b" against "(a)?b") then an empty string is inserted.
+ *
* If the last match was obtained using the DFA algorithm, that is using
* g_regex_match_all() or g_regex_match_all_full(), the retrieved
* strings are not that matched by sets of parentheses but that of the
* matched substring. Substrings are matched in reverse order of length,
* so the first one is the longest match.
+ *
* The strings are fetched from the string passed to the match function,
* so you cannot call this function after freeing the string.
+ *
* It must be freed using g_strfreev(). If the previous match failed
* %NULL is returned
*
@@ -18355,11 +19698,14 @@
* @name: name of the subexpression
*
* Retrieves the text matching the capturing parentheses named @name.
+ *
* If @name is a valid sub pattern name but it didn't match anything
* (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
* then an empty string is returned.
+ *
* The string is fetched from the string passed to the match function,
* so you cannot call this function after freeing the string.
+ *
* occurred. You have to free the string yourself
*
* Returns: (allow-none): The matched substring, or %NULL if an error
@@ -18375,9 +19721,11 @@
* @end_pos: (out) (allow-none): pointer to location where to store the end position, or %NULL
*
* Retrieves the position in bytes of the capturing parentheses named @name.
+ *
* If @name is a valid sub pattern name but it didn't match anything
* (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
* then @start_pos and @end_pos are set to -1 and %TRUE is returned.
+ *
* If the position cannot be fetched, @start_pos and @end_pos
* are left unchanged.
*
@@ -18396,14 +19744,17 @@
* Retrieves the position in bytes of the @match_num<!-- -->'th capturing
* parentheses. 0 is the full text of the match, 1 is the first
* paren set, 2 the second, and so on.
+ *
* If @match_num is a valid sub pattern but it didn't match anything
* (e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos
* and @end_pos are set to -1 and %TRUE is returned.
+ *
* If the match was obtained using the DFA algorithm, that is using
* g_regex_match_all() or g_regex_match_all_full(), the retrieved
* position is not that of a set of parentheses but that of a matched
* substring. Substrings are matched in reverse order of length, so
* 0 is the longest match.
+ *
* the position cannot be fetched, @start_pos and @end_pos are left
* unchanged
*
@@ -18430,6 +19781,7 @@
* Retrieves the number of matched substrings (including substring 0,
* that is the whole matched text), so 1 is returned if the pattern
* has no substrings in it and 0 is returned if the match failed.
+ *
* If the last match was obtained using the DFA algorithm, that is
* using g_regex_match_all() or g_regex_match_all_full(), the retrieved
* count is not that of the number of capturing parentheses but that of
@@ -18474,6 +19826,7 @@
* it goes, but is too short to match the entire pattern, %FALSE is
* returned. There are circumstances where it might be helpful to
* distinguish this case from other cases in which there is no match.
+ *
* Consider, for example, an application where a human is required to
* type in data for a field with specific formatting requirements. An
* example might be a date in the form ddmmmyy, defined by the pattern
@@ -18481,13 +19834,16 @@
* If the application sees the userâs keystrokes one by one, and can
* check that what has been typed so far is potentially valid, it is
* able to raise an error as soon as a mistake is made.
+ *
* GRegex supports the concept of partial matching by means of the
* #G_REGEX_MATCH_PARTIAL flag. When this is set the return code for
* g_regex_match() or g_regex_match_full() is, as usual, %TRUE
* for a complete match, %FALSE otherwise. But, when these functions
* return %FALSE, you can check if the match was partial calling
* g_match_info_is_partial_match().
+ *
* When using partial matching you cannot use g_match_info_fetch*().
+ *
* Because of the way certain internal optimizations are implemented
* the partial matching algorithm cannot be used with all patterns.
* So repeated single characters such as "a{2,4}" and repeated single
@@ -18509,6 +19865,7 @@
* @match_info: a #GMatchInfo structure
*
* Returns whether the previous match operation succeeded.
+ *
* %FALSE otherwise
*
* Returns: %TRUE if the previous match operation succeeded,
@@ -18523,6 +19880,8 @@
*
* Scans for the next match using the same parameters of the previous
* call to g_regex_match_full() or g_regex_match() that returned
+ * @match_info.
+ *
* The match is done on the string passed to the match function, so you
* cannot free it before calling this function.
*
@@ -18581,9 +19940,9 @@
* @mem_chunk: a #GMemChunk.
*
* Frees any blocks in a #GMemChunk which are no longer being used.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -18599,9 +19958,9 @@
* name. The atom size is determined using
* <function>sizeof()</function>, and the area size is calculated by
* multiplying the @pre_alloc parameter with the atom size.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -18610,9 +19969,9 @@
* @mem_chunk: a #GMemChunk.
*
* Frees all of the memory allocated for a #GMemChunk.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -18636,9 +19995,9 @@
* in use. It outputs the number of #GMemChunk objects currently
* allocated, and calls g_mem_chunk_print() to output information on
* each one.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -18651,9 +20010,9 @@
* @Returns: the new #GMemChunk.
*
* Creates a new #GMemChunk.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -18664,9 +20023,9 @@
* Outputs debugging information for a #GMemChunk. It outputs the name
* of the #GMemChunk (set with g_mem_chunk_new()), the number of bytes
* used, and the number of blocks of memory allocated.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -18676,9 +20035,9 @@
*
* Resets a GMemChunk to its initial state. It frees all of the
* currently allocated blocks of memory.
- * allocator</link> instead
*
* Deprecated:2.10: Use the <link linkend="glib-Memory-Slices">slice
+ * allocator</link> instead
*/
@@ -18698,6 +20057,7 @@
* malloc() can be used interchangeable with memory allocated using g_malloc().
* This function is useful for avoiding an extra copy of allocated memory returned
* by a non-GLib-based API.
+ *
* A different allocator can be set using g_mem_set_vtable().
*
* Returns: if %TRUE, malloc() and g_malloc() can be mixed.
@@ -18708,11 +20068,13 @@
* g_mem_profile:
*
* Outputs a summary of memory usage.
+ *
* It outputs the frequency of allocations of different sizes,
* the total number of bytes which have been allocated,
* the total number of bytes which have been freed,
* and the difference between the previous two values, i.e. the number of bytes
* still in use.
+ *
* Note that this function will not output anything unless you have
* previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
*/
@@ -18728,6 +20090,7 @@
* provide malloc(), realloc(), and free() functions; GLib can provide default
* implementations of the others. The malloc() and realloc() implementations
* should return %NULL on failure, GLib will handle error-checking for you.
+ * @vtable is copied, so need not persist after this function has been called.
*/
@@ -18738,6 +20101,7 @@
*
* Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
* from @mem. If @mem is %NULL it returns %NULL.
+ *
* is %NULL.
*
* Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
@@ -18752,6 +20116,7 @@
*
* Copies a block of memory @len bytes long, from @src to @dest.
* The source and destination areas may overlap.
+ *
* In order to use this function, you must include
* <filename>string.h</filename> yourself, because this macro will
* typically simply resolve to memmove() and GLib does not include
@@ -18767,7 +20132,9 @@
* A wrapper for the POSIX mkdir() function. The mkdir() function
* attempts to create a directory with the given name and permissions.
* The mode argument is ignored on Windows.
+ *
* See your C library manual for more details about mkdir().
+ *
* occurred
*
* Returns: 0 if the directory was successfully created, -1 if an error
@@ -18782,6 +20149,7 @@
*
* Create a directory if it doesn't already exist. Create intermediate
* parent directories as needed, too.
+ *
* created. Returns -1 if an error occurred, with errno set.
*
* Returns: 0 if the directory already exists, or was successfully
@@ -18790,22 +20158,70 @@
/**
+ * g_mkdtemp:
+ * @tmpl: template directory name
+ *
+ * Creates a temporary directory. See the mkdtemp() documentation
+ * on most UNIX-like systems.
+ *
+ * The parameter is a string that should follow the rules for
+ * mkdtemp() templates, i.e. contain the string "XXXXXX".
+ * g_mkdtemp() is slightly more flexible than mkdtemp() in that the
+ * sequence does not have to occur at the very end of the template
+ * and you can pass a @mode and additional @flags. The X string will
+ * be modified to form the name of a directory that didn't exist.
+ * The string should be in the GLib file name encoding. Most importantly,
+ * on Windows it should be in UTF-8.
+ *
+ * to hold the directory name. In case of errors, NULL is returned.
+ *
+ * Returns: A pointer to @tmpl, which has been modified
+ * Since: 2.26
+ */
+
+
+/**
+ * g_mkdtemp_full:
+ * @tmpl: template directory name
+ * @mode: permissions to create the temporary directory with
+ *
+ * Creates a temporary directory. See the mkdtemp() documentation
+ * on most UNIX-like systems.
+ *
+ * The parameter is a string that should follow the rules for
+ * mkdtemp() templates, i.e. contain the string "XXXXXX".
+ * g_mkdtemp() is slightly more flexible than mkdtemp() in that the
+ * sequence does not have to occur at the very end of the template
+ * and you can pass a @mode. The X string will be modified to form
+ * the name of a directory that didn't exist. The string should be
+ * in the GLib file name encoding. Most importantly, on Windows it
+ * should be in UTF-8.
+ *
+ * to hold the directory name. In case of errors, %NULL is returned.
+ *
+ * Returns: A pointer to @tmpl, which has been modified
+ * Since: 2.26
+ */
+
+
+/**
* g_mkstemp:
* @tmpl: template filename
*
* Opens a temporary file. See the mkstemp() documentation
* on most UNIX-like systems.
+ *
* The parameter is a string that should follow the rules for
* mkstemp() templates, i.e. contain the string "XXXXXX".
- * g_mkstemp() is slightly more flexible than mkstemp()
- * in that the sequence does not have to occur at the very end of the
- * template. The X string will
- * be modified to form the name of a file that didn't exist.
- * The string should be in the GLib file name encoding. Most importantly,
- * on Windows it should be in UTF-8.
- * opened for reading and writing. The file is opened in binary mode
- * on platforms where there is a difference. The file handle should be
- * closed with close(). In case of errors, -1 is returned.
+ * g_mkstemp() is slightly more flexible than mkstemp() in that the
+ * sequence does not have to occur at the very end of the template.
+ * The X string will be modified to form the name of a file that
+ * didn't exist. The string should be in the GLib file name encoding.
+ * Most importantly, on Windows it should be in UTF-8.
+ *
+ * opened for reading and writing. The file is opened in binary
+ * mode on platforms where there is a difference. The file handle
+ * should be closed with close(). In case of errors, -1 is returned.
*
* Returns: A file handle (as from open()) to the file
*/
@@ -18815,10 +20231,11 @@
* g_mkstemp_full:
* @tmpl: template filename
* @flags: flags to pass to an open() call in addition to O_EXCL and O_CREAT, which are passed automatically
- * @mode: permissios to create the temporary file with
+ * @mode: permissions to create the temporary file with
*
* Opens a temporary file. See the mkstemp() documentation
* on most UNIX-like systems.
+ *
* The parameter is a string that should follow the rules for
* mkstemp() templates, i.e. contain the string "XXXXXX".
* g_mkstemp_full() is slightly more flexible than mkstemp()
@@ -18827,6 +20244,7 @@
* string will be modified to form the name of a file that didn't exist.
* The string should be in the GLib file name encoding. Most importantly,
* on Windows it should be in UTF-8.
+ *
* opened for reading and writing. The file handle should be
* closed with close(). In case of errors, -1 is returned.
*
@@ -18840,6 +20258,7 @@
* @mutex: a #GMutex.
*
* Destroys @mutex.
+ *
* <note><para>Calling g_mutex_free() on a locked mutex may result in
* undefined behaviour.</para></note>
*/
@@ -18852,8 +20271,10 @@
* Locks @mutex. If @mutex is already locked by another thread, the
* current thread will block until @mutex is unlocked by the other
* thread.
+ *
* This function can be used even if g_thread_init() has not yet been
* called, and, in that case, will do nothing.
+ *
* <note><para>#GMutex is neither guaranteed to be recursive nor to be
* non-recursive, i.e. a thread could deadlock while calling
* g_mutex_lock(), if it already has locked @mutex. Use
@@ -18866,6 +20287,7 @@
* @Returns: a new #GMutex.
*
* Creates a new #GMutex.
+ *
* <note><para>This function will abort if g_thread_init() has not been
* called yet.</para></note>
*/
@@ -18879,11 +20301,14 @@
* Tries to lock @mutex. If @mutex is already locked by another thread,
* it immediately returns %FALSE. Otherwise it locks @mutex and returns
* %TRUE.
+ *
* This function can be used even if g_thread_init() has not yet been
* called, and, in that case, will immediately return %TRUE.
+ *
* <note><para>#GMutex is neither guaranteed to be recursive nor to be
* non-recursive, i.e. the return value of g_mutex_trylock() could be
* both %FALSE or %TRUE, if the current thread already has locked
+ * @mutex. Use #GStaticRecMutex, if you need recursive
* mutexes.</para></note>
*/
@@ -18894,6 +20319,7 @@
*
* Unlocks @mutex. If another thread is blocked in a g_mutex_lock()
* call for @mutex, it will be woken and can lock @mutex itself.
+ *
* This function can be used even if g_thread_init() has not yet been
* called, and, in that case, will do nothing.
*/
@@ -18908,6 +20334,7 @@
* The returned pointer is cast to a pointer to the given type.
* If @n_structs is 0 it returns %NULL.
* Care is taken to avoid overflow when calculating the size of the allocated block.
+ *
* Since the returned pointer is already casted to the right type,
* it is normally unnecessary to cast it explicitly, and doing
* so might hide memory allocation errors.
@@ -18925,6 +20352,7 @@
* The returned pointer is cast to a pointer to the given type.
* If @n_structs is 0 it returns %NULL.
* Care is taken to avoid overflow when calculating the size of the allocated block.
+ *
* Since the returned pointer is already casted to the right type,
* it is normally unnecessary to cast it explicitly, and doing
* so might hide memory allocation errors.
@@ -18974,6 +20402,8 @@
* Gets the position of the first child of a #GNode
* which contains the given data.
*
+ * @data, or -1 if the data is not found
+ *
* Returns: the index of the child of @node which contains
*/
@@ -18984,6 +20414,7 @@
* @child: a child of @node
*
* Gets the position of a #GNode with respect to its siblings.
+ * @child must be a child of @node. The first child is numbered 0,
* the second 1, and so on.
*
* Returns: the position of @child with respect to its siblings
@@ -19031,6 +20462,7 @@
* @node: a #GNode
*
* Gets the depth of a #GNode.
+ *
* If @node is %NULL the depth is 0. The root node has a depth of 1.
* For the children of the root node the depth is 2. And so on.
*
@@ -19077,6 +20509,7 @@
* @node: a #GNode
*
* Gets the first child of a #GNode.
+ *
* or has no children
*
* Returns: the first child of @node, or %NULL if @node is %NULL
@@ -19204,6 +20637,7 @@
*
* Gets the maximum height of all branches beneath a #GNode.
* This is the maximum distance from the #GNode to all leaf nodes.
+ *
* If @root is %NULL, 0 is returned. If @root has no children,
* 1 is returned. If @root has children, 2 is returned. And so on.
*
@@ -19248,6 +20682,7 @@
* @node: a #GNode
*
* Gets the next sibling of a #GNode.
+ *
* or %NULL
*
* Returns: the next sibling of @node, or %NULL if @node is the last node
@@ -19272,12 +20707,13 @@
*
* Restores the previous #GAllocator, used when allocating #GNode
* elements.
+ *
* Note that this function is not available if GLib has been compiled
* with <option>--disable-mem-pools</option>
- * the <link linkend="glib-Memory-Slices">slice
- * allocator</link>
*
* Deprecated:2.10: It does nothing, since #GNode has been converted to
+ * the <link linkend="glib-Memory-Slices">slice
+ * allocator</link>
*/
@@ -19308,6 +20744,7 @@
* @node: a #GNode
*
* Gets the previous sibling of a #GNode.
+ *
* node or %NULL
*
* Returns: the previous sibling of @node, or %NULL if @node is the first
@@ -19320,12 +20757,13 @@
*
* Sets the allocator to use to allocate #GNode elements. Use
* g_node_pop_allocator() to restore the previous allocator.
+ *
* Note that this function is not available if GLib has been compiled
* with <option>--disable-mem-pools</option>
- * the <link linkend="glib-Memory-Slices">slice
- * allocator</link>
*
* Deprecated:2.10: It does nothing, since #GNode has been converted to
+ * the <link linkend="glib-Memory-Slices">slice
+ * allocator</link>
*/
@@ -19378,8 +20816,10 @@
* This function is intended to be used for debugging use only.
* The following example shows how it can be used together with
* the g_log() functions.
+ *
* |[
* #include <glib.h>
+ *
* static void
* log_handler (const gchar *log_domain,
* GLogLevelFlags log_level,
@@ -19387,8 +20827,10 @@
* gpointer user_data)
* {
* g_log_default_handler (log_domain, log_level, message, user_data);
+ *
* g_on_error_query (MY_PROGRAM_NAME);
* }
+ *
* int
* main (int argc, char *argv[])
* {
@@ -19400,12 +20842,16 @@
* NULL);
* /* ... */
* ]|
+ *
* If [E]xit is selected, the application terminates with a call
* to <literal>_exit(0)</literal>.
+ *
* If [S]tack trace is selected, g_on_error_stack_trace() is called.
* This invokes <command>gdb</command>, which attaches to the current
* process and shows a stack trace. The prompt is then shown again.
+ *
* If [P]roceed is selected, the function returns.
+ *
* This function may cause different actions on non-UNIX platforms.
*/
@@ -19417,6 +20863,7 @@
* Invokes <command>gdb</command>, which attaches to the current
* process and shows a stack trace. Called by g_on_error_query()
* when the [S]tack trace option is selected.
+ *
* This function may cause different actions on non-UNIX platforms.
*/
@@ -19432,17 +20879,23 @@
* calls to g_once() with the same #GOnce struct do not call @func
* again, but return the stored result of the first call. On return
* from g_once(), the status of @once will be %G_ONCE_STATUS_READY.
+ *
* For example, a mutex or a thread-specific data key must be created
* exactly once. In a threaded environment, calling g_once() ensures
* that the initialization is serialized across multiple threads.
+ *
* <note><para>Calling g_once() recursively on the same #GOnce struct in
+ * @func will lead to a deadlock.</para></note>
+ *
* <informalexample>
* <programlisting>
* gpointer
* get_debug_flags (void)
* {
* static GOnce my_once = G_ONCE_INIT;
+ *
* g_once (&my_once, parse_debug_flags, NULL);
+ *
* return my_once.retval;
* }
* </programlisting>
@@ -19466,14 +20919,18 @@
* during a program's life time, and that concurrent threads are
* blocked until initialization completed. To be used in constructs
* like this:
+ *
* <informalexample>
* <programlisting>
* static gsize initialization_value = 0;
+ *
* if (g_once_init_enter (&initialization_value))
* {
* gsize setup_value = 42; /<!-- -->* initialization code here *<!-- -->/
+ *
* g_once_init_leave (&initialization_value, setup_value);
* }
+ *
* /<!-- -->* use initialization_value here *<!-- -->/
* </programlisting>
* </informalexample>
@@ -19505,19 +20962,23 @@
*
* A wrapper for the POSIX open() function. The open() function is
* used to convert a pathname into a file descriptor.
+ *
* On POSIX systems file descriptors are implemented by the operating
* system. On Windows, it's the C library that implements open() and
* file descriptors. The actual Win32 API for opening files is quite
* different, see MSDN documentation for CreateFile(). The Win32 API
* uses file handles, which are more randomish integers, not small
* integers like file descriptors.
+ *
* Because file descriptors are specific to the C library on Windows,
* the file descriptor returned by this function makes sense only to
* functions in the same C library. Thus if the GLib-using code uses a
* different C library than GLib does, the file descriptor returned by
* this function cannot be passed to C library functions like write()
* or read().
+ *
* See your C library manual for more details about open().
+ *
* return value can be used exactly like the return value from open().
*
* Returns: a new file descriptor, or -1 if an error occurred. The
@@ -19559,6 +21020,7 @@
*
* Frees context and all the groups which have been
* added to it.
+ *
* Please note that parsed arguments need to be freed separately (see
* #GOptionEntry).
*
@@ -19625,6 +21087,7 @@
* @context: a #GOptionContext
*
* Returns a pointer to the main group of @context.
+ *
* have a main group. Note that group belongs to @context and should
* not be modified or freed.
*
@@ -19649,6 +21112,7 @@
* @parameter_string: a string which is displayed in the first line of <option>--help</option> output, after the usage summary <literal><replaceable>programname</replaceable> [OPTION...]</literal>
*
* Creates a new option context.
+ *
* The @parameter_string can serve multiple purposes. It can be used
* to add descriptions for "rest" arguments, which are not parsed by
* the #GOptionContext, typically something like "FILES" or
@@ -19656,14 +21120,17 @@
* collecting "rest" arguments, GLib handles this automatically by
* using the @arg_description of the corresponding #GOptionEntry in
* the usage summary.
+ *
* Another usage is to give a short summary of the program
* functionality, like " - frob the strings", which will be displayed
* in the same line as the usage. For a longer description of the
* program functionality that should be displayed as a paragraph
* below the usage line, use g_option_context_set_summary().
+ *
* Note that the @parameter_string is translated using the
* function set with g_option_context_set_translate_func(), so
* it should normally be passed untranslated.
+ *
* freed with g_option_context_free() after use.
*
* Returns: a newly created #GOptionContext, which must be
@@ -19682,20 +21149,25 @@
* which have been added to @context. A side-effect of
* calling this function is that g_set_prgname() will be
* called.
+ *
* If the parsing is successful, any parsed arguments are
* removed from the array and @argc and @argv are updated
* accordingly. A '--' option is stripped from @argv
* unless there are unparsed options before and after it,
* or some of the options after it start with '-'. In case
* of an error, @argc and @argv are left unmodified.
+ *
* If automatic <option>--help</option> support is enabled
* (see g_option_context_set_help_enabled()), and the
+ * @argv array contains one of the recognized help options,
* this function will produce help output to stdout and
* call <literal>exit (0)</literal>.
+ *
* Note that function depends on the
* <link linkend="setlocale">current locale</link> for
* automatic character set conversion of string and filename
* arguments.
+ *
* %FALSE if an error occurred
*
* Returns: %TRUE if the parsing was successful,
@@ -19711,6 +21183,7 @@
* Adds a string to be displayed in <option>--help</option> output
* after the list of options. This text often includes a bug reporting
* address.
+ *
* Note that the summary is translated (see
* g_option_context_set_translate_func()).
*
@@ -19742,6 +21215,7 @@
* Sets whether to ignore unknown options or not. If an argument is
* ignored, it is left in the @argv array after parsing. By default,
* g_option_context_parse() treats unknown options as error.
+ *
* This setting does not affect non-option arguments (i.e. arguments
* which don't start with a dash). But note that GOption cannot reliably
* determine whether a non-option belongs to a preceding unknown option.
@@ -19772,6 +21246,7 @@
* Adds a string to be displayed in <option>--help</option> output
* before the list of options. This is typically a summary of the
* program functionality.
+ *
* Note that the summary is translated (see
* g_option_context_set_translate_func() and
* g_option_context_set_translation_domain()).
@@ -19790,10 +21265,12 @@
* Sets the function which is used to translate the contexts
* user-visible strings, for <option>--help</option> output.
* If @func is %NULL, strings are not translated.
+ *
* Note that option groups have their own translation functions,
* this function only affects the @parameter_string (see g_option_context_new()),
* the summary (see g_option_context_set_summary()) and the description
* (see g_option_context_set_description()).
+ *
* If you are using gettext(), you only need to set the translation
* domain, see g_option_context_set_translation_domain().
*
@@ -19844,6 +21321,7 @@
* @destroy: a function that will be called to free @user_data, or %NULL
*
* Creates a new #GOptionGroup.
+ *
* to a #GOptionContext or freed with g_option_group_free().
*
* Returns: a newly created option group. It should be added
@@ -19858,6 +21336,7 @@
*
* Associates a function with @group which will be called
* from g_option_context_parse() when an error occurs.
+ *
* Note that the user data to be passed to @error_func can be
* specified when constructing the group with g_option_group_new().
*
@@ -19874,7 +21353,9 @@
* Associates two functions with @group which will be called
* from g_option_context_parse() before the first option is parsed
* and after the last option has been parsed, respectively.
+ *
* Note that the user data to be passed to @pre_parse_func and
+ * @post_parse_func can be specified when constructing the group
* with g_option_group_new().
*
* Since: 2.6
@@ -19892,6 +21373,7 @@
* strings, for <option>--help</option> output. Different
* groups can use different #GTranslateFunc<!-- -->s. If @func
* is %NULL, strings are not translated.
+ *
* If you are using gettext(), you only need to set the translation
* domain, see g_option_group_set_translation_domain().
*
@@ -19921,6 +21403,7 @@
* into a %guint containing bit flags. This is used
* within GDK and GTK+ to parse the debug options passed on the
* command line or through environment variables.
+ *
* If @string is equal to "all", all flags are set. If @string
* is equal to "help", all the available keys in @keys are printed
* out to standard error.
@@ -19935,7 +21418,10 @@
*
* Gets the last component of the filename. If @file_name ends with a
* directory separator it gets the component before the last slash. If
+ * @file_name consists only of directory separators (and on Windows,
* possibly a drive letter), a single separator is returned. If
+ * @file_name is empty, it gets ".".
+ *
* the filename.
*
* Returns: a newly allocated string containing the last component of
@@ -19960,8 +21446,10 @@
*
* Returns %TRUE if the given @file_name is an absolute file name.
* Note that this is a somewhat vague concept on Windows.
+ *
* On POSIX systems, an absolute file name is well-defined. It always
* starts from the single root directory. For example "/usr/local".
+ *
* On Windows, the concepts of current drive and drive-specific
* current directory introduce vagueness. This function interprets as
* an absolute file name one that either begins with a directory
@@ -19969,9 +21457,11 @@
* for example "C:\Windows". The first case also includes UNC paths
* such as "\\myserver\docs\foo". In all cases, either slashes or
* backslashes are accepted.
+ *
* Note that a file name relative to the current drive root does not
* truly specify a file uniquely over time and across processes, as
* the current drive is a per-process value and can be changed.
+ *
* File names relative the current directory on some specific drive,
* such as "D:foo/bar", are not interpreted as absolute by this
* function, but they obviously are not relative to the normal current
@@ -20009,11 +21499,13 @@
* version of the string to be matched is not at hand, as
* g_pattern_match() will only construct it if the compiled pattern
* requires reverse matches.
+ *
* Note that, if the user code will (possibly) match a string against a
* multitude of patterns containing wildcards, chances are high that
* some patterns will require a reversed string. In this case, it's
* more efficient to provide the reversed string to avoid multiple
* constructions thereof in the various calls to g_pattern_match().
+ *
* Note also that the reverse of a UTF-8 encoded string can in general
* <emphasis>not</emphasis> be obtained by g_strreverse(). This works
* only if the string doesn't contain any multibyte characters. GLib
@@ -20082,6 +21574,7 @@
*
* This is equivalent to g_bit_lock, but working on pointers (or other
* pointer-sized values).
+ *
* For portability reasons, you may only lock on the bottom 32 bits of
* the pointer.
*
@@ -20097,6 +21590,7 @@
*
* This is equivalent to g_bit_trylock, but working on pointers (or
* other pointer-sized values).
+ *
* For portability reasons, you may only lock on the bottom 32 bits of
* the pointer.
*
@@ -20111,6 +21605,7 @@
*
* This is equivalent to g_bit_unlock, but working on pointers (or other
* pointer-sized values).
+ *
* For portability reasons, you may only lock on the bottom 32 bits of
* the pointer.
*
@@ -20129,16 +21624,19 @@
* This is used internally by #GMainContext, but it can be called
* directly if you need to block until a file descriptor is ready, but
* don't want to run the full main loop.
+ *
* Each element of @fds is a #GPollFD describing a single file
* descriptor to poll. The %fd field indicates the file descriptor,
* and the %events field indicates the events to poll for. On return,
* the %revents fields will be filled with the events that actually
* occurred.
+ *
* On POSIX systems, the file descriptors in @fds can be any sort of
* file descriptor, but the situation is much more complicated on
* Windows. If you need to use g_poll() in code that has to run on
* Windows, the easiest solution is to construct all of your
* #GPollFD<!-- -->s with g_io_channel_win32_make_pollfd().
+ *
* were filled in, or 0 if the operation timed out, or -1 on error or
* if the call was interrupted.
*
@@ -20157,12 +21655,13 @@
* Formats a string according to @format and
* prefix it to an existing error message. If
* nothing.
+ *
+ * If * err is %NULL (ie: an error variable is
* present but there is no error condition) then
* also do nothing. Whether or not it makes
* sense to take advantage of this feature is up
* to you.
*
- * If * err is %null (ie: an error variable is
* Since: 2.16
*/
@@ -20174,6 +21673,7 @@
*
* Outputs a formatted message via the print handler.
* The default print handler simply outputs the message to stdout.
+ *
* g_print() should not be used from within libraries for debugging
* messages, since it may be redirected by applications to special
* purpose message windows or even files. Instead, libraries should
@@ -20189,6 +21689,7 @@
*
* Outputs a formatted message via the error message handler.
* The default handler simply outputs the message to stderr.
+ *
* g_printerr() should not be used from within libraries.
* Instead g_log() should be used, or the convenience functions
* g_message(), g_warning() and g_error().
@@ -20216,6 +21717,7 @@
* Returns the pointer keyed to @private_key for the current thread. If
* g_private_set() hasn't been called for the current @private_key and
* thread yet, this pointer will be %NULL.
+ *
* This function can be used even if g_thread_init() has not yet been
* called, and, in that case, will return the value of @private_key
* casted to #gpointer. Note however, that private data set
@@ -20237,13 +21739,17 @@
* corresponding pointer keyed to this instance of #GPrivate is
* non-%NULL, the destructor is called with this pointer as the
* argument.
+ *
* <note><para>
* #GStaticPrivate is a better choice for most uses.
* </para></note>
+ *
* <note><para>@destructor is used quite differently from @notify in
* g_static_private_set().</para></note>
+ *
* <note><para>A #GPrivate cannot be freed. Reuse it instead, if you
* can, to avoid shortage, or use #GStaticPrivate.</para></note>
+ *
* <note><para>This function will abort if g_thread_init() has not been
* called yet.</para></note>
*/
@@ -20255,6 +21761,7 @@
* @data: the new pointer.
*
* Sets the pointer keyed to @private_key for the current thread.
+ *
* This function can be used even if g_thread_init() has not yet been
* called, and, in that case, will set @private_key to @data casted to
* #GPrivate*. See g_private_get() for resulting caveats.
@@ -20321,6 +21828,7 @@
* underlying array for use elsewhere. If the reference count of @array
* is greater than one, the #GPtrArray wrapper is preserved but the
* size of @array will be set to zero.
+ *
* <note><para>If array contents point to dynamically-allocated
* memory, they should be freed separately if @free_seg is %TRUE and no
* #GDestroyNotify function has been set for @array.</para></note>
@@ -20399,6 +21907,7 @@
* array. The following elements are moved down one place. If @array
* has a non-%NULL #GDestroyNotify function it is called for the
* removed element.
+ *
* It returns %TRUE if the pointer was removed, or %FALSE if the
* pointer was not found.
*/
@@ -20415,6 +21924,7 @@
* so this function does not preserve the order of the array. But it is
* faster than g_ptr_array_remove(). If @array has a non-%NULL
* #GDestroyNotify function it is called for the removed element.
+ *
* It returns %TRUE if the pointer was removed, or %FALSE if the
* pointer was not found.
*/
@@ -20508,11 +22018,13 @@
* comparison function (returns less than zero for first arg is less
* than second arg, zero for equal, greater than zero if irst arg is
* greater than second arg).
+ *
* If two array elements compare equal, their order in the sorted array
* is undefined. If you want equal elements to keep their order – i.e.
* you want a stable sort – you can write a comparison function that,
* if two elements would otherwise compare equal, compares them by
* their addresses.
+ *
* <note><para>The comparison function for g_ptr_array_sort() doesn't
* take the pointers from the array as arguments, it takes pointers to
* the pointers in the array.</para></note>
@@ -20527,6 +22039,7 @@
*
* Like g_ptr_array_sort(), but the comparison function has an extra
* user data argument.
+ *
* <note><para>The comparison function for g_ptr_array_sort_with_data()
* doesn't take the pointers from the array as arguments, it takes
* pointers to the pointers in the array.</para></note>
@@ -20567,6 +22080,7 @@
* Gets the #GQuark identifying the given (static) string. If the
* string does not currently have an associated #GQuark, a new #GQuark
* is created, linked to the given string.
+ *
* Note that this function is identical to g_quark_from_string() except
* that if a new #GQuark is created the string itself is used rather
* than a copy. This saves memory, but can only be used if the string
@@ -20605,6 +22119,7 @@
*
* Gets the #GQuark associated with the given string, or 0 if string is
* %NULL or it has no associated #GQuark.
+ *
* If you want the GQuark to be created if it doesn't already exist,
* use g_quark_from_string() or g_quark_from_static_string().
*/
@@ -20641,6 +22156,8 @@
*
* Removes @link_ from @queue and frees it.
*
+ * @link_ must be part of @queue.
+ *
* Since: 2.4
*/
@@ -20692,6 +22209,7 @@
* @queue: a #GQueue.
*
* Frees the memory allocated for the #GQueue. Only call this function if
+ * @queue was created with g_queue_new(). If queue elements contain
* dynamically-allocated memory, they should be freed first.
*/
@@ -20740,6 +22258,8 @@
*
* Inserts @data into @queue after @sibling
*
+ * @sibling must be part of @queue
+ *
* Since: 2.4
*/
@@ -20752,6 +22272,8 @@
*
* Inserts @data into @queue before @sibling.
*
+ * @sibling must be part of @queue.
+ *
* Since: 2.4
*/
@@ -20785,6 +22307,7 @@
* @link_: A #GList link
*
* Returns the position of @link_ in @queue.
+ *
* not part of @queue
*
* Returns: The position of @link_, or -1 if the link is
@@ -20806,6 +22329,7 @@
* @queue: a #GQueue.
*
* Returns the first element of the queue.
+ *
* is empty.
*
* Returns: the data of the first element in the queue, or %NULL if the queue
@@ -20829,6 +22353,7 @@
* @n: the position of the element.
*
* Returns the @n'th element of @queue.
+ *
* off the end of @queue.
*
* Returns: The data for the @n'th element of @queue, or %NULL if @n is
@@ -20842,6 +22367,7 @@
* @n: the position of the link
*
* Returns the link at the given position
+ *
* end of the list
*
* Returns: The link at the @n'th position, or %NULL if @n is off the
@@ -20854,6 +22380,7 @@
* @queue: a #GQueue.
*
* Returns the last element of the queue.
+ *
* is empty.
*
* Returns: the data of the last element in the queue, or %NULL if the queue
@@ -20876,6 +22403,7 @@
* @queue: a #GQueue.
*
* Removes the first element of the queue.
+ *
* is empty.
*
* Returns: the data of the first element in the queue, or %NULL if the queue
@@ -20887,6 +22415,7 @@
* @queue: a #GQueue.
*
* Removes the first element of the queue.
+ *
* is empty.
*
* Returns: the #GList element at the head of the queue, or %NULL if the queue
@@ -20922,6 +22451,7 @@
* @queue: a #GQueue.
*
* Removes the last element of the queue.
+ *
* is empty.
*
* Returns: the data of the last element in the queue, or %NULL if the queue
@@ -20933,6 +22463,7 @@
* @queue: a #GQueue.
*
* Removes the last element of the queue.
+ *
* is empty.
*
* Returns: the #GList element at the tail of the queue, or %NULL if the queue
@@ -20972,7 +22503,7 @@
/**
* g_queue_push_nth_link:
* @queue: a #GQueue
- * @n: the position to insert the link. If this is negative or larger than the number of elements in @queue, the link is added to the end of
+ * @n: the position to insert the link. If this is negative or larger than the number of elements in @queue, the link is added to the end of @queue.
* @link_: the link to add to @queue
*
* Inserts @link into @queue at the given position.
@@ -21053,6 +22584,8 @@
* Unlinks @link_ so that it will no longer be part of @queue. The link is
* not freed.
*
+ * @link_ must be part of @queue,
+ *
* Since: 2.4
*/
@@ -21259,6 +22792,7 @@
* @n_bytes: new size of the memory in bytes
*
* Reallocates the memory pointed to by @mem, so that it now has space for
+ * @n_bytes bytes of memory. It returns the new address of the memory, which may
* have been moved. @mem may be %NULL, in which case it's considered to
* have zero-length. @n_bytes may be 0, in which case %NULL will be returned
* and @mem will be freed unless it is %NULL.
@@ -21290,6 +22824,7 @@
* Checks whether @replacement is a valid replacement string
* (see g_regex_replace()), i.e. that all escape sequences in
* it are valid.
+ *
* If @has_references is not %NULL then @replacement is checked
* for pattern references. For instance, replacement text 'foo\n'
* does not contain references and may be evaluated without information
@@ -21308,6 +22843,7 @@
*
* Escapes the nul characters in @string to "\x00". It can be used
* to compile a regex with embedded nul characters.
+ *
* For completeness, @length can be -1 for a nul-terminated string.
* In this case the output string will be of course equal to @string.
*
@@ -21324,6 +22860,8 @@
* Escapes the special characters used for regular expressions
* in @string, for instance "a.b*c" becomes "a\.b\*c". This
* function is useful to dynamically generate regular expressions.
+ *
+ * @string can contain nul characters that are replaced with "\0",
* in this case remember to specify the correct length of @string
* in @length.
*
@@ -21396,6 +22934,7 @@
* @name: name of the subexpression
*
* Retrieves the number of the subexpression named @name.
+ *
* does not exists
*
* Returns: The number of the subexpression or -1 if @name
@@ -21414,12 +22953,15 @@
* The @match_options are combined with the match options specified
* when the @regex structure was created, letting you have more
* flexibility in reusing #GRegex structures.
+ *
* A #GMatchInfo structure, used to get information on the match,
* is stored in @match_info if not %NULL. Note that if @match_info
* is not %NULL then it is created even if the function returns %FALSE,
* i.e. you must free it regardless if regular expression actually matched.
+ *
* To retrieve all the non-overlapping matches of the pattern in
* string you can use g_match_info_next().
+ *
* |[
* static void
* print_uppercase_words (const gchar *string)
@@ -21433,6 +22975,7 @@
* while (g_match_info_matches (match_info))
* {
* gchar *word = g_match_info_fetch (match_info, 0);
+ * g_print ("Found: %s\n", word);
* g_free (word);
* g_match_info_next (match_info, NULL);
* }
@@ -21440,10 +22983,11 @@
* g_regex_unref (regex);
* }
* ]|
+ *
+ * @string is not copied and is used in #GMatchInfo internally. If
* you use any #GMatchInfo method (except g_match_info_free()) after
* freeing or modifying @string then the behaviour is undefined.
*
- * G_print ("found: %s\n", word);
* Returns: %TRUE is the string matched, %FALSE otherwise
* Since: 2.14
*/
@@ -21460,11 +23004,14 @@
* the longest match in the string is retrieved. This function uses
* a different algorithm so it can retrieve all the possible matches.
* For more documentation see g_regex_match_all_full().
+ *
* A #GMatchInfo structure, used to get information on the match, is
* stored in @match_info if not %NULL. Note that if @match_info is
* not %NULL then it is created even if the function returns %FALSE,
* i.e. you must free it regardless if regular expression actually
* matched.
+ *
+ * @string is not copied and is used in #GMatchInfo internally. If
* you use any #GMatchInfo method (except g_match_info_free()) after
* freeing or modifying @string then the behaviour is undefined.
*
@@ -21488,31 +23035,38 @@
* to obtain all the available matches. For instance matching
* "<a> <b> <c>" against the pattern "<.*>"
* you get "<a> <b> <c>".
+ *
* This function uses a different algorithm (called DFA, i.e. deterministic
* finite automaton), so it can retrieve all the possible matches, all
* starting at the same point in the string. For instance matching
* "<a> <b> <c>" against the pattern "<.*>"
+ * you would obtain three matches: "<a> <b> <c>",
* "<a> <b>" and "<a>".
+ *
* The number of matched strings is retrieved using
* g_match_info_get_match_count(). To obtain the matched strings and
* their position you can use, respectively, g_match_info_fetch() and
* g_match_info_fetch_pos(). Note that the strings are returned in
* reverse order of length; that is, the longest matching string is
* given first.
+ *
* Note that the DFA algorithm is slower than the standard one and it
* is not able to capture substrings, so backreferences do not work.
+ *
* Setting @start_position differs from just passing over a shortened
* string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
* that begins with any kind of lookbehind assertion, such as "\b".
+ *
* A #GMatchInfo structure, used to get information on the match, is
* stored in @match_info if not %NULL. Note that if @match_info is
* not %NULL then it is created even if the function returns %FALSE,
* i.e. you must free it regardless if regular expression actually
* matched.
+ *
+ * @string is not copied and is used in #GMatchInfo internally. If
* you use any #GMatchInfo method (except g_match_info_free()) after
* freeing or modifying @string then the behaviour is undefined.
*
- * You would obtain three matches: "<a> <b> <c>",
* Returns: %TRUE is the string matched, %FALSE otherwise
* Since: 2.14
*/
@@ -21532,18 +23086,24 @@
* The @match_options are combined with the match options specified
* when the @regex structure was created, letting you have more
* flexibility in reusing #GRegex structures.
+ *
* Setting @start_position differs from just passing over a shortened
* string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
* that begins with any kind of lookbehind assertion, such as "\b".
+ *
* A #GMatchInfo structure, used to get information on the match, is
* stored in @match_info if not %NULL. Note that if @match_info is
* not %NULL then it is created even if the function returns %FALSE,
* i.e. you must free it regardless if regular expression actually
* matched.
+ *
+ * @string is not copied and is used in #GMatchInfo internally. If
* you use any #GMatchInfo method (except g_match_info_free()) after
* freeing or modifying @string then the behaviour is undefined.
+ *
* To retrieve all the non-overlapping matches of the pattern in
* string you can use g_match_info_next().
+ *
* |[
* static void
* print_uppercase_words (const gchar *string)
@@ -21558,6 +23118,7 @@
* while (g_match_info_matches (match_info))
* {
* gchar *word = g_match_info_fetch (match_info, 0);
+ * g_print ("Found: %s\n", word);
* g_free (word);
* g_match_info_next (match_info, &error);
* }
@@ -21565,13 +23126,12 @@
* g_regex_unref (regex);
* if (error != NULL)
* {
+ * g_printerr ("Error while matching: %s\n", error->message);
* g_error_free (error);
* }
* }
* ]|
*
- * G_print ("found: %s\n", word);
- * G_printerr ("error while matching: %s\n", error->message);
* Returns: %TRUE is the string matched, %FALSE otherwise
* Since: 2.14
*/
@@ -21585,10 +23145,12 @@
* @match_options: match options, or 0
*
* Scans for a match in @string for @pattern.
+ *
* This function is equivalent to g_regex_match() but it does not
* require to compile the pattern with g_regex_new(), avoiding some
* lines of code when you need just to do a match without extracting
* substrings, capture counts, and so on.
+ *
* If this function is to be called on the same @pattern more than
* once, it's more efficient to compile the pattern once with
* g_regex_new() and then use g_regex_match().
@@ -21607,6 +23169,7 @@
*
* Compiles the regular expression to an internal form, and does
* the initial setup of the #GRegex structure.
+ *
* are done with it
*
* Returns: a #GRegex structure. Call g_regex_unref() when you
@@ -21643,6 +23206,7 @@
* complete match, but '\0' followed by a number is the octal representation
* of a character. To include a literal '\' in the replacement, write '\\'.
* There are also escapes that changes the case of the following text:
+ *
* <variablelist>
* <varlistentry><term>\l</term>
* <listitem>
@@ -21670,10 +23234,13 @@
* </listitem>
* </varlistentry>
* </variablelist>
+ *
* If you do not need to use backreferences use g_regex_replace_literal().
+ *
* The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was
* passed to g_regex_new(). If you want to use not UTF-8 encoded stings
* you can use g_regex_replace_literal().
+ *
* Setting @start_position differs from just passing over a shortened
* string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that
* begins with any kind of lookbehind assertion, such as "\b".
@@ -21695,9 +23262,12 @@
* @error: location to store the error occuring, or %NULL to ignore errors
*
* Replaces occurrences of the pattern in regex with the output of
+ * @eval for that occurrence.
+ *
* Setting @start_position differs from just passing over a shortened
* string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
* that begins with any kind of lookbehind assertion, such as "\b".
+ *
* The following example uses g_regex_replace_eval() to replace multiple
* strings at once:
* |[
@@ -21708,24 +23278,32 @@
* {
* gchar *match;
* gchar *r;
+ *
* match = g_match_info_fetch (info, 0);
* r = g_hash_table_lookup ((GHashTable *)data, match);
* g_string_append (res, r);
* g_free (match);
+ *
* return FALSE;
* }
+ *
* /* ... */
+ *
* GRegex *reg;
* GHashTable *h;
* gchar *res;
+ *
* h = g_hash_table_new (g_str_hash, g_str_equal);
+ *
* g_hash_table_insert (h, "1", "ONE");
* g_hash_table_insert (h, "2", "TWO");
* g_hash_table_insert (h, "3", "THREE");
* g_hash_table_insert (h, "4", "FOUR");
+ *
* reg = g_regex_new ("1|2|3|4", 0, 0, NULL);
* res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
* g_hash_table_destroy (h);
+ *
* /* ... */
* ]|
*
@@ -21747,6 +23325,7 @@
* Replaces all occurrences of the pattern in @regex with the
* replacement text. @replacement is replaced literally, to
* include backreferences use g_regex_replace().
+ *
* Setting @start_position differs from just passing over a
* shortened string and setting #G_REGEX_MATCH_NOTBOL in the
* case of a pattern that begins with any kind of lookbehind
@@ -21768,12 +23347,14 @@
* of the substrings will also be returned. If the pattern does not match
* anywhere in the string, then the whole string is returned as the first
* token.
+ *
* As a special case, the result of splitting the empty string "" is an
* empty vector, not a vector containing a single string. The reason for
* this special case is that being able to represent a empty vector is
* typically more useful than consistent handling of empty elements. If
* you do need to represent empty elements, you'll need to check for the
* empty string before calling this function.
+ *
* A pattern that can match empty strings splits @string into separate
* characters wherever it matches the empty string between characters.
* For example splitting "ab c" using as a separator "\s*", you will get
@@ -21799,16 +23380,19 @@
* of the substrings will also be returned. If the pattern does not match
* anywhere in the string, then the whole string is returned as the first
* token.
+ *
* As a special case, the result of splitting the empty string "" is an
* empty vector, not a vector containing a single string. The reason for
* this special case is that being able to represent a empty vector is
* typically more useful than consistent handling of empty elements. If
* you do need to represent empty elements, you'll need to check for the
* empty string before calling this function.
+ *
* A pattern that can match empty strings splits @string into separate
* characters wherever it matches the empty string between characters.
* For example splitting "ab c" using as a separator "\s*", you will get
* "a", "b" and "c".
+ *
* Setting @start_position differs from just passing over a shortened
* string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
* that begins with any kind of lookbehind assertion, such as "\b".
@@ -21830,13 +23414,16 @@
* then the text for each of the substrings will also be returned.
* If the pattern does not match anywhere in the string, then the
* whole string is returned as the first token.
+ *
* This function is equivalent to g_regex_split() but it does
* not require to compile the pattern with g_regex_new(), avoiding
* some lines of code when you need just to do a split without
* extracting substrings, capture counts, and so on.
+ *
* If this function is to be called on the same @pattern more than
* once, it's more efficient to compile the pattern once with
* g_regex_new() and then use g_regex_split().
+ *
* As a special case, the result of splitting the empty string ""
* is an empty vector, not a vector containing a single string.
* The reason for this special case is that being able to represent
@@ -21844,6 +23431,7 @@
* of empty elements. If you do need to represent empty elements,
* you'll need to check for the empty string before calling this
* function.
+ *
* A pattern that can match empty strings splits @string into
* separate characters wherever it matches the empty string between
* characters. For example splitting "ab c" using as a separator
@@ -21988,6 +23576,7 @@
* Resets the cache used for g_get_user_special_dir(), so
* that the latest on-disk version is used. Call this only
* if you just changed the data on disk yourself.
+ *
* Due to threadsafety issues this may cause leaking of strings
* that were previously returned from g_get_user_special_dir()
* that can't be freed. We ensure to only leak the data for
@@ -22003,6 +23592,7 @@
*
* A wrapper for the POSIX remove() function. The remove() function
* deletes a name from the filesystem.
+ *
* See your C library manual for more details about how remove() works
* on your system. On Unix, remove() removes also directories, as it
* calls unlink() for files and rmdir() for directories. On Windows,
@@ -22011,10 +23601,12 @@
* thus works for both files and directories. Note however, that on
* Windows, it is in general not possible to remove a file that is
* open to some process, or mapped into memory.
+ *
* If this function fails on Windows you can't infer too much from the
* errno value. rmdir() is tried regardless of what caused remove() to
* fail. Any errno value set by remove() will be overwritten by that
* set by rmdir().
+ *
* occurred
*
* Returns: 0 if the file was successfully removed, -1 if an error
@@ -22029,6 +23621,7 @@
*
* A wrapper for the POSIX rename() function. The rename() function
* renames a file, moving it between directories if required.
+ *
* See your C library manual for more details about how rename() works
* on your system. It is not possible in general on Windows to rename
* a file that is open to some process.
@@ -22045,6 +23638,7 @@
* @n_structs: the number of elements to allocate
*
* Reallocates the memory pointed to by @mem, so that it now has space for
+ * @n_structs elements of type @struct_type. It returns the new address of
* the memory, which may have been moved.
* Care is taken to avoid overflow when calculating the size of the allocated block.
*
@@ -22058,8 +23652,10 @@
*
* A wrapper for the POSIX rmdir() function. The rmdir() function
* deletes a directory from the filesystem.
+ *
* See your C library manual for more details about how rmdir() works
* on your system.
+ *
* occurred
*
* Returns: 0 if the directory was successfully removed, -1 if an error
@@ -22100,6 +23696,7 @@
* @user_data: user data passed to @func
*
* Calls @func for each item in the range (@begin, @end) passing
+ * @user_data to the function.
*
* Since: 2.14
*/
@@ -22111,6 +23708,7 @@
*
* Frees the memory allocated for @seq. If @seq has a data destroy
* function associated with it, that function is called on all items in
+ * @seq.
*
* Since: 2.14
*/
@@ -22195,6 +23793,8 @@
* Inserts @data into @sequence using @func to determine the new
* position. The sequence must already be sorted according to @cmp_func;
* otherwise the new position of @data is undefined.
+ *
+ * @cmp_func is called with two items of the @seq and @user_data.
* It should return 0 if the items are equal, a negative value
* if the first item comes before the second, and a positive value
* if the second item comes before the first.
@@ -22214,9 +23814,12 @@
* Like g_sequence_insert_sorted(), but uses
* a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
* the compare function.
+ *
+ * @iter_cmp is called with two iterators pointing into @seq.
* It should return 0 if the iterators are equal, a negative
* value if the first iterator comes before the second, and a
* positive value if the second iterator comes before the first.
+ *
* It is called with two iterators pointing into @seq. It should
* return 0 if the iterators are equal, a negative value if the
* first iterator comes before the second, and a positive value
@@ -22234,7 +23837,9 @@
*
* Returns a negative number if @a comes before @b, 0 if they are equal,
* and a positive number if @a comes after @b.
+ *
* The @a and @b iterators must point into the same sequence.
+ *
* equal, and a positive number if @a comes after @b.
*
* Returns: A negative number if @a comes before @b, 0 if they are
@@ -22306,6 +23911,7 @@
* @iter: a #GSequenceIter
*
* Returns an iterator pointing to the next position after @iter. If
+ * @iter is the end iterator, the end iterator is returned.
*
* Returns: a #GSequenceIter pointing to the next position after @iter.
* Since: 2.14
@@ -22317,6 +23923,9 @@
* @iter: a #GSequenceIter
*
* Returns an iterator pointing to the previous position before @iter. If
+ * @iter is the begin iterator, the begin iterator is returned.
+ *
+ * @iter.
*
* Returns: a #GSequenceIter pointing to the previous position before
* Since: 2.14
@@ -22335,9 +23944,12 @@
* item is equal, it is not guaranteed that it is the first which is
* returned. In that case, you can use g_sequence_iter_next() and
* g_sequence_iter_prev() to get others.
+ *
+ * @cmp_func is called with two items of the @seq and @user_data.
* It should return 0 if the items are equal, a negative value if
* the first item comes before the second, and a positive value if
* the second item comes before the first.
+ *
* first item found equal to @data according to @cmp_func and @cmp_data.
*
* Returns: an #GSequenceIter pointing to the position of the
@@ -22354,9 +23966,12 @@
*
* Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc
* instead of a #GCompareDataFunc as the compare function.
+ *
+ * @iter_cmp is called with two iterators pointing into @seq.
* It should return 0 if the iterators are equal, a negative value
* if the first iterator comes before the second, and a positive
* value if the second iterator comes before the first.
+ *
* the first item found equal to @data according to @cmp_func
* and @cmp_data.
*
@@ -22389,6 +24004,7 @@
* The @begin and @end iters must point into the same sequence. It is
* allowed for @dest to point to a different sequence than the one pointed
* into by @begin and @end.
+ *
* If @dest is NULL, the range indicated by @begin and @end is
* removed from the sequence. If @dest iter points to a place within
* the (@begin, @end) range, the range does not move.
@@ -22430,7 +24046,10 @@
* Finds an iterator somewhere in the range (@begin, @end). This
* iterator will be close to the middle of the range, but is not
* guaranteed to be <emphasis>exactly</emphasis> in the middle.
+ *
* The @begin and @end iterators must both point to the same sequence and
+ * @begin must come before or be equal to @end in the sequence.
+ *
* (@begin, @end) range.
*
* Returns: A #GSequenceIter pointing somewhere in the
@@ -22444,6 +24063,7 @@
*
* Removes the item pointed to by @iter. It is an error to pass the
* end iterator to this function.
+ *
* If the sequnce has a data destroy function associated with it, this
* function is called on the data for the removed item.
*
@@ -22457,6 +24077,7 @@
* @end: a #GSequenceIter
*
* Removes all items in the (@begin, @end) range.
+ *
* If the sequence has a data destroy function associated with it, this
* function is called on the data for the removed items.
*
@@ -22473,11 +24094,15 @@
*
* Returns an iterator pointing to the position where @data would
* be inserted according to @cmp_func and @cmp_data.
+ *
+ * @cmp_func is called with two items of the @seq and @user_data.
* It should return 0 if the items are equal, a negative value if
* the first item comes before the second, and a positive value if
* the second item comes before the first.
+ *
* If you are simply searching for an existing element of the sequence,
* consider using g_sequence_lookup().
+ *
* would have been inserted according to @cmp_func and @cmp_data.
*
* Returns: an #GSequenceIter pointing to the position where @data
@@ -22494,11 +24119,15 @@
*
* Like g_sequence_search(), but uses a #GSequenceIterCompareFunc
* instead of a #GCompareDataFunc as the compare function.
+ *
+ * @iter_cmp is called with two iterators pointing into @seq.
* It should return 0 if the iterators are equal, a negative value
* if the first iterator comes before the second, and a positive
* value if the second iterator comes before the first.
+ *
* If you are simply searching for an existing element of the sequence,
* consider using g_sequence_lookup_iter().
+ *
* where @data would have been inserted according to @iter_cmp
* and @cmp_data.
*
@@ -22527,6 +24156,8 @@
* @cmp_data: user data passed to @cmp_func
*
* Sorts @seq using @cmp_func.
+ *
+ * @cmp_func is passed two items of @seq and should
* return 0 if they are equal, a negative value if the
* first comes before the second, and a positive value
* if the second comes before the first.
@@ -22545,6 +24176,8 @@
* function should be called for items in a sequence already sorted according
* to @cmp_func whenever some aspect of an item changes so that @cmp_func
* may return different values for that item.
+ *
+ * @cmp_func is called with two items of the @seq and @user_data.
* It should return 0 if the items are equal, a negative value if
* the first item comes before the second, and a positive value if
* the second item comes before the first.
@@ -22562,6 +24195,8 @@
* Like g_sequence_sort_changed(), but uses
* a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
* the compare function.
+ *
+ * @iter_cmp is called with two iterators pointing into @seq. It should
* return 0 if the iterators are equal, a negative value if the first
* iterator comes before the second, and a positive value if the second
* iterator comes before the first.
@@ -22578,6 +24213,8 @@
*
* Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead
* of a GCompareDataFunc as the compare function
+ *
+ * @cmp_func is called with two iterators pointing into @seq. It should
* return 0 if the iterators are equal, a negative value if the first
* iterator comes before the second, and a positive value if the second
* iterator comes before the first.
@@ -22607,8 +24244,10 @@
* Contrast with g_set_prgname(), which sets a non-localized name.
* g_set_prgname() will be called automatically by gtk_init(),
* but g_set_application_name() will not.
+ *
* Note that for thread safety reasons, this function can only
* be called once.
+ *
* The application name will be used in contexts such as error messages,
* or when displaying an application's name in the task list.
*
@@ -22661,6 +24300,7 @@
* @func: the new print handler
*
* Sets the print handler.
+ *
* Any messages passed to g_print() will be output via
* the new handler. The default handler simply outputs
* the message to stdout. By providing your own handler
@@ -22676,6 +24316,7 @@
* @func: the new error message handler
*
* Sets the handler for printing error messages.
+ *
* Any messages passed to g_printerr() will be output via
* the new handler. The default handler simply outputs the
* message to stderr. By providing your own handler you can
@@ -22696,6 +24337,7 @@
* should be in the GLib file name encoding. On UNIX, this means that
* they can be any sequence of bytes. On Windows, they should be in
* UTF-8.
+ *
* Note that on some systems, when variables are overwritten, the memory
* used for the previous variables and its value isn't reclaimed.
*
@@ -22759,6 +24401,7 @@
* double quotes are handled, as are escapes including escaped
* newlines. The return value must be freed with g_free(). Possible
* errors are in the #G_SHELL_ERROR domain.
+ *
* Shell quoting rules are a bit strange. Single quotes preserve the
* literal string exactly. escape sequences are not allowed; not even
* \' - if you want a ' in the quoted text, you have to do something
@@ -22778,6 +24421,7 @@
* @data: data to pass to @c_handler calls.
*
* Connects a #GCallback function to a signal for a particular object.
+ *
* The handler will be called before the default handler of the signal.
*
* Returns: the handler id
@@ -22792,6 +24436,7 @@
* @data: data to pass to @c_handler calls.
*
* Connects a #GCallback function to a signal for a particular object.
+ *
* The handler will be called after the default handler of the signal.
*
* Returns: the handler id
@@ -22806,6 +24451,7 @@
* @data: data to pass to @c_handler calls.
*
* Connects a #GCallback function to a signal for a particular object.
+ *
* The instance on which the signal is emitted and @data will be swapped when
* calling the handler.
*
@@ -22865,22 +24511,27 @@
* @data: the data for the new element
*
* Adds a new element on to the end of the list.
+ *
* <note><para>
* The return value is the new start of the list, which may
* have changed, so make sure you store the new value.
* </para></note>
+ *
* <note><para>
* Note that g_slist_append() has to traverse the entire list
* to find the end, which is inefficient when adding multiple
* elements. A common idiom to avoid the inefficiency is to prepend
* the elements and reverse the list when all elements have been added.
* </para></note>
+ *
* |[
* /* Notice that these are initialized to the empty list. */
* GSList *list = NULL, *number_list = NULL;
+ *
* /* This is a list of strings. */
* list = g_slist_append (list, "first");
* list = g_slist_append (list, "second");
+ *
* /* This is a list of integers. */
* number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
* number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
@@ -22908,6 +24559,7 @@
* @list: a #GSList
*
* Copies a #GSList.
+ *
* <note><para>
* Note that this is a "shallow" copy. If the list elements
* consist of pointers to data, the pointers are copied but
@@ -22938,6 +24590,7 @@
*
* Finds the element in a #GSList which
* contains the given data.
+ *
* or %NULL if it is not found
*
* Returns: the found #GSList element,
@@ -22977,6 +24630,7 @@
*
* Frees all of the memory used by a #GSList.
* The freed elements are returned to the slice allocator.
+ *
* <note><para>
* If list elements contain dynamically-allocated memory,
* you should either use g_slist_free_full() or free them manually
@@ -23008,8 +24662,8 @@
* @list: a pointer to a #GSList
* @free_func: the function to be called to free each element's data
*
- * Convenience method, which frees all the memory used by a #GSList,
- * and calls the specified destroy function on every element's data.
+ * Convenience method, which frees all the memory used by a #GSList, and
+ * calls the specified destroy function on every element's data.
*
* Since: 2.28
*/
@@ -23022,6 +24676,7 @@
*
* Gets the position of the element containing
* the given data (starting from 0).
+ *
* or -1 if the data is not found
*
* Returns: the index of the element containing the data,
@@ -23085,9 +24740,11 @@
* @list: a #GSList
*
* Gets the last element in a #GSList.
+ *
* <note><para>
* This function iterates over the whole list.
* </para></note>
+ *
* or %NULL if the #GSList has no elements
*
* Returns: the last element in the #GSList,
@@ -23099,6 +24756,7 @@
* @list: a #GSList
*
* Gets the number of elements in a #GSList.
+ *
* <note><para>
* This function iterates over the whole list to
* count its elements.
@@ -23123,6 +24781,7 @@
* @n: the position of the element, counting from 0
*
* Gets the element at the given position in a #GSList.
+ *
* the end of the #GSList
*
* Returns: the element, or %NULL if the position is off
@@ -23135,6 +24794,7 @@
* @n: the position of the element
*
* Gets the data of the element at the given position.
+ *
* is off the end of the #GSList
*
* Returns: the element's data, or %NULL if the position
@@ -23146,8 +24806,10 @@
*
* Restores the previous #GAllocator, used when allocating #GSList
* elements.
+ *
* Note that this function is not available if GLib has been compiled
* with <option>--disable-mem-pools</option>
+ *
* to the <link linkend="glib-Memory-Slices">slice
* allocator</link>
*
@@ -23162,6 +24824,7 @@
*
* Gets the position of the given element
* in the #GSList (starting from 0).
+ *
* or -1 if the element is not found
*
* Returns: the position of the element in the #GSList,
@@ -23174,10 +24837,12 @@
* @data: the data for the new element
*
* Adds a new element on to the start of the list.
+ *
* <note><para>
* The return value is the new start of the list, which
* may have changed, so make sure you store the new value.
* </para></note>
+ *
* |[
* /* Notice that it is initialized to the empty list. */
* GSList *list = NULL;
@@ -23195,8 +24860,10 @@
*
* Sets the allocator to use to allocate #GSList elements. Use
* g_slist_pop_allocator() to restore the previous allocator.
+ *
* Note that this function is not available if GLib has been compiled
* with <option>--disable-mem-pools</option>
+ *
* to the <link linkend="glib-Memory-Slices">slice
* allocator</link>
*
@@ -23288,16 +24955,21 @@
* A safer form of the standard sprintf() function. The output is guaranteed
* to not exceed @n characters (including the terminating nul character), so
* it is easy to ensure that a buffer overflow cannot occur.
+ *
* See also g_strdup_printf().
+ *
* In versions of GLib prior to 1.2.3, this function may return -1 if the
* output was truncated, and the truncated string may not be nul-terminated.
* In versions prior to 1.3.12, this function returns the length of the output
* string.
+ *
* The return value of g_snprintf() conforms to the snprintf()
* function as standardized in ISO C99. Note that this is different from
* traditional snprintf(), which returns the length of the output string.
+ *
* The format string may contain positional parameters, as specified in
* the Single Unix Specification.
+ *
* was large enough.
*
* Returns: the number of bytes which would be produced if the buffer
@@ -23313,10 +24985,14 @@
* with the same priority, when @child_source is triggered, it will
* cause @source to dispatch (in addition to calling its own
* callback), and when @source is destroyed, it will destroy
+ * @child_source as well. (@source will also still be dispatched if
* its own prepare/check functions indicate that it is ready.)
+ *
* If you don't need @child_source to do anything on its own when it
* triggers, you can call g_source_set_dummy_callback() on it to set a
* callback that does nothing (except return %TRUE if appropriate).
+ *
+ * @source will hold a reference on @child_source while @child_source
* is attached to it.
*
* Since: 2.28
@@ -23342,6 +25018,7 @@
*
* Adds a #GSource to a @context so that it will be executed within
* that context. Remove it by calling g_source_destroy().
+ *
* #GMainContext.
*
* Returns: the ID (greater than 0) for the source within the
@@ -23375,6 +25052,7 @@
*
* Gets the #GMainContext with which the source is associated.
* Calling this function on a destroyed source is an error.
+ *
* or %NULL if the context has not yet been added
* to a source.
*
@@ -23441,6 +25119,7 @@
* calling this function over calling g_get_monotonic_time() directly is
* that when checking multiple sources, GLib can cache a single value
* instead of having to repeatedly get the system monotonic time.
+ *
* The time here is the system monotonic time, if available, or some
* other reasonable alternative otherwise. See g_get_monotonic_time().
*
@@ -23454,50 +25133,62 @@
* @source: a #GSource
*
* Returns whether @source has been destroyed.
+ *
* This is important when you operate upon your objects
* from within idle handlers, but may have freed the object
* before the dispatch of your idle handler.
+ *
* |[
* static gboolean
* idle_callback (gpointer data)
* {
* SomeWidget *self = data;
+ *
* GDK_THREADS_ENTER (<!-- -->);
* /<!-- -->* do stuff with self *<!-- -->/
* self->idle_id = 0;
* GDK_THREADS_LEAVE (<!-- -->);
+ *
* return FALSE;
* }
+ *
* static void
* some_widget_do_stuff_later (SomeWidget *self)
* {
* self->idle_id = g_idle_add (idle_callback, self);
* }
+ *
* static void
* some_widget_finalize (GObject *object)
* {
* SomeWidget *self = SOME_WIDGET (object);
+ *
* if (self->idle_id)
* g_source_remove (self->idle_id);
+ *
* G_OBJECT_CLASS (parent_class)->finalize (object);
* }
* ]|
+ *
* This will fail in a multi-threaded application if the
* widget is destroyed before the idle handler fires due
* to the use after free in the callback. A solution, to
* this particular problem, is to check to if the source
* has already been destroy within the callback.
+ *
* |[
* static gboolean
* idle_callback (gpointer data)
* {
* SomeWidget *self = data;
+ *
* GDK_THREADS_ENTER ();
* if (!g_source_is_destroyed (g_main_current_source ()))
* {
* /<!-- -->* do stuff with self *<!-- -->/
* }
* GDK_THREADS_LEAVE ();
+ *
* return FALSE;
* }
* ]|
@@ -23516,6 +25207,7 @@
* allow creating structures derived from #GSource that contain
* additional data. The size passed in must be at least
* <literal>sizeof (GSource)</literal>.
+ *
* The source will not initially be associated with any #GMainContext
* and must be added to one with g_source_attach() before it will be
* executed.
@@ -23544,6 +25236,7 @@
* functions g_source_attach(), g_idle_add(), g_idle_add_full(),
* g_timeout_add(), g_timeout_add_full(), g_child_watch_add(),
* g_child_watch_add_full(), g_io_add_watch(), and g_io_add_watch_full().
+ *
* See also g_source_destroy(). You must use g_source_destroy() for sources
* added to a non-default main context.
*
@@ -23604,9 +25297,11 @@
*
* Sets the callback function for a source. The callback for a source is
* called from the source's dispatch function.
+ *
* The exact type of @func depends on the type of source; ie. you
* should not count on @func being called with @data as its first
* parameter.
+ *
* Typically, you won't use this function. Instead use functions specific
* to the type of source you are using.
*/
@@ -23622,6 +25317,7 @@
* "object". This is used internally. Note that calling
* g_source_set_callback_indirect() assumes
* an initial reference count on @callback_data, and thus
+ * @callback_funcs->unref will eventually be called once more
* than @callback_funcs->ref.
*/
@@ -23657,9 +25353,11 @@
*
* Sets a name for the source, used in debugging and profiling.
* The name defaults to #NULL.
+ *
* The source name should describe in a human-readable way
* what the source does. For example, "X11 event queue"
* or "GTK+ repaint idle handler" or whatever it is.
+ *
* It is permitted to call this function multiple times, but is not
* recommended due to the potential performance impact. For example,
* one could change the name in the "check" function of a #GSourceFuncs
@@ -23675,6 +25373,7 @@
* @name: debug name for the source
*
* Sets the name of a source using its ID.
+ *
* This is a convenience utility to set source names from the return
* value of g_idle_add(), g_timeout_add(), etc.
*
@@ -23711,8 +25410,10 @@
* Gets the smallest prime number from a built-in array of primes which
* is larger than @num. This is used within GLib to calculate the optimum
* size of a #GHashTable.
+ *
* The built-in array of primes ranges from 11 to 13845163 such that
* each prime is approximately 1.5-2 times the previous prime.
+ *
* which is larger than @num
*
* Returns: the smallest prime number from a built-in array of primes
@@ -23732,14 +25433,17 @@
*
* See g_spawn_async_with_pipes() for a full description; this function
* simply calls the g_spawn_async_with_pipes() without any pipes.
+ *
* You should call g_spawn_close_pid() on the returned child process
* reference when you don't need it any more.
+ *
* <note><para>
* If you are writing a GTK+ application, and the program you
* are spawning is a graphical application, too, then you may
* want to use gdk_spawn_on_screen() instead to ensure that
* the spawned program opens its windows on the right screen.
* </para></note>
+ *
* <note><para> Note that the returned @child_pid on Windows is a
* handle to the child process and not its identifier. Process handles
* and process identifiers are different concepts on Windows.
@@ -23771,6 +25475,7 @@
* course the name of the program to execute. By default, the name of
* the program must be a full path; the <envar>PATH</envar> shell variable
* will only be searched if you pass the %G_SPAWN_SEARCH_PATH flag.
+ *
* On Windows, note that all the string or string vector arguments to
* this function and the other g_spawn*() functions are in UTF-8, the
* GLib file name encoding. Unicode characters that are not part of
@@ -23779,6 +25484,7 @@
* to retrieve its command line. For C programs built with Microsoft's
* tools it is enough to make the program have a wmain() instead of
* main(). wmain() has a wide character argument vector as parameter.
+ *
* At least currently, mingw doesn't support wmain(), so if you use
* mingw to develop the spawned program, it will have to call the
* undocumented function __wgetmainargs() to get the wide character
@@ -23787,6 +25493,7 @@
* for that function. Alternatively, you can retrieve the Win32 system
* level wide character command line passed to the spawned program
* using the GetCommandLineW() function.
+ *
* On Windows the low-level child process creation API
* <function>CreateProcess()</function> doesn't use argument vectors,
* but a command line. The C runtime library's
@@ -23803,20 +25510,28 @@
* g_spawn_async_with_pipes() will do quoting and escaping on argument
* vector elements that need it before calling the C runtime
* spawn() function.
+ *
* The returned @child_pid on Windows is a handle to the child
* process, not its identifier. Process handles and process
* identifiers are different concepts on Windows.
+ *
+ * @envp is a %NULL-terminated array of strings, where each string
* has the form <literal>KEY=VALUE</literal>. This will become
* the child's environment. If @envp is %NULL, the child inherits its
* parent's environment.
+ *
+ * @flags should be the bitwise OR of any flags you want to affect the
* function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that
* the child will not automatically be reaped; you must use a
* #GChildWatch source to be notified about the death of the child
* process. Eventually you must call g_spawn_close_pid() on the
+ * @child_pid, in order to free resources which may be associated
* with the child process. (On Unix, using a #GChildWatch source is
* equivalent to calling waitpid() or handling the %SIGCHLD signal
* manually. On Windows, calling g_spawn_close_pid() is equivalent
* to calling CloseHandle() on the process handle returned in
+ * @child_pid).
+ *
* %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file
* descriptors will be inherited by the child; otherwise all
* descriptors except stdin/stdout/stderr will be closed before
@@ -23837,6 +25552,8 @@
* actual argument vector to pass to the file. Normally
* g_spawn_async_with_pipes() uses @argv[0] as the file to execute, and
* passes all of @argv to the child.
+ *
+ * @child_setup and @user_data are a function and user data. On POSIX
* platforms, the function is called in the child after GLib has
* performed all the setup it plans to perform (including creating
* pipes, closing file descriptors, etc.) but before calling
@@ -23844,10 +25561,12 @@
* before calling exec() in the child. Obviously
* actions taken in this function will only affect the child, not the
* parent.
+ *
* On Windows, there is no separate fork() and exec()
* functionality. Child processes are created and run with a single
* API call, CreateProcess(). There is no sensible thing @child_setup
* could be used for on Windows so it is ignored and not called.
+ *
* If non-%NULL, @child_pid will on Unix be filled with the child's
* process ID. You can use the process ID to send signals to the
* child, or to use g_child_watch_add() (or waitpid()) if you specified the
@@ -23858,29 +25577,38 @@
* with the <function>WaitFor*()</function> functions, or examine its
* exit code with GetExitCodeProcess(). You should close the handle
* with CloseHandle() or g_spawn_close_pid() when you no longer need it.
+ *
* If non-%NULL, the @standard_input, @standard_output, @standard_error
* locations will be filled with file descriptors for writing to the child's
* standard input or reading from its standard output or standard error.
* The caller of g_spawn_async_with_pipes() must close these file descriptors
* when they are no longer in use. If these parameters are %NULL, the corresponding
* pipe won't be created.
+ *
* If @standard_input is NULL, the child's standard input is attached to
* /dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
+ *
* If @standard_error is NULL, the child's standard error goes to the same
* location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL
* is set.
+ *
* If @standard_output is NULL, the child's standard output goes to the same
* location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL
* is set.
+ *
+ * @error can be %NULL to ignore errors, or non-%NULL to report errors.
* If an error is set, the function returns %FALSE. Errors
* are reported even if they occur in the child (for example if the
* executable in <literal>argv[0]</literal> is not found). Typically
* the <literal>message</literal> field of returned errors should be displayed
* to users. Possible errors are those from the #G_SPAWN_ERROR domain.
+ *
* If an error occurs, @child_pid, @standard_input, @standard_output,
* and @standard_error will not be filled with valid values.
+ *
* If @child_pid is not %NULL and an error does not occur then the returned
* process reference must be closed using g_spawn_close_pid().
+ *
* <note><para>
* If you are writing a GTK+ application, and the program you
* are spawning is a graphical application, too, then you may
@@ -23915,6 +25643,7 @@
* that %G_SPAWN_SEARCH_PATH can have security implications, so
* consider using g_spawn_async() directly if appropriate. Possible
* errors are those from g_shell_parse_argv() and g_spawn_async().
+ *
* The same concerns on Windows apply as for g_spawn_command_line_sync().
*
* Returns: %TRUE on success, %FALSE if error is set.
@@ -23937,9 +25666,11 @@
* implications, so consider using g_spawn_sync() directly if
* appropriate. Possible errors are those from g_spawn_sync() and those
* from g_shell_parse_argv().
+ *
* If @exit_status is non-%NULL, the exit status of the child is stored there as
* it would be returned by waitpid(); standard UNIX macros such as WIFEXITED()
* and WEXITSTATUS() must be used to evaluate the exit status.
+ *
* On Windows, please note the implications of g_shell_parse_argv()
* parsing @command_line. Parsing is done according to Unix shell rules, not
* Windows command interpreter rules.
@@ -23978,6 +25709,8 @@
* Note that this function call waitpid() even if @exit_status is %NULL, and
* does not accept the %G_SPAWN_DO_NOT_REAP_CHILD flag.
* If an error occurs, no data is returned in @standard_output,
+ * @standard_error, or @exit_status.
+ *
* This function calls g_spawn_async_with_pipes() internally; see that
* function for full details on the other parameters and details on
* how these functions work on Windows.
@@ -23994,8 +25727,10 @@
*
* An implementation of the standard sprintf() function which supports
* positional parameters, as specified in the Single Unix Specification.
+ *
* Note that it is usually better to use g_snprintf(), to avoid the
* risk of buffer overflow.
+ *
* See also g_strdup_printf().
*
* Returns: the number of bytes printed.
@@ -24013,11 +25748,13 @@
* the C library checks only the FAT-style READONLY attribute and does
* not look at the ACL at all. Thus on Windows the protection bits in
* the st_mode field are a fabrication of little use.
+ *
* On Windows the Microsoft C libraries have several variants of the
* <structname>stat</structname> struct and stat() function with names
* like "_stat", "_stat32", "_stat32i64" and "_stat64i32". The one
* used here is for 32-bit code the one with 32-bit size and time
* fields, specifically called "_stat32".
+ *
* In Microsoft's compiler, by default "struct stat" means one with
* 64-bit time fields while in MinGW "struct stat" is the legacy one
* with 32-bit fields. To hopefully clear up this messs, the gstdio.h
@@ -24025,7 +25762,9 @@
* depending on the platform and/or compiler being used. On POSIX it
* is just "struct stat", but note that even on POSIX platforms,
* "stat" might be a macro.
+ *
* See your C library manual for more details about stat().
+ *
* occurred
*
* Returns: 0 if the information was successfully retrieved, -1 if an error
@@ -24038,10 +25777,12 @@
* @mutex: a #GStaticMutex to be freed.
*
* Releases all resources allocated to @mutex.
+ *
* You don't have to call this functions for a #GStaticMutex with an
* unbounded lifetime, i.e. objects declared 'static', but if you have
* a #GStaticMutex as a member of a structure and the structure is
* freed, you should also free the #GStaticMutex.
+ *
* <note><para>Calling g_static_mutex_free() on a locked mutex may
* result in undefined behaviour.</para></note>
*/
@@ -24097,6 +25838,7 @@
* @private_key: a #GStaticPrivate to be freed.
*
* Releases all resources allocated to @private_key.
+ *
* You don't have to call this functions for a #GStaticPrivate with an
* unbounded lifetime, i.e. objects declared 'static', but if you have
* a #GStaticPrivate as a member of a structure and the structure is
@@ -24110,6 +25852,7 @@
* @Returns: the corresponding pointer.
*
* Works like g_private_get() only for a #GStaticPrivate.
+ *
* This function works even if g_thread_init() has not yet been called.
*/
@@ -24133,10 +25876,12 @@
* the function @notify to be called with that pointer (%NULL or
* non-%NULL), whenever the pointer is set again or whenever the
* current thread ends.
+ *
* This function works even if g_thread_init() has not yet been called.
* If g_thread_init() is called later, the @data keyed to @private_key
* will be inherited only by the main thread, i.e. the one that called
* g_thread_init().
+ *
* <note><para>@notify is used quite differently from @destructor in
* g_private_new().</para></note>
*/
@@ -24147,6 +25892,7 @@
* @mutex: a #GStaticRecMutex to be freed.
*
* Releases all resources allocated to a #GStaticRecMutex.
+ *
* You don't have to call this functions for a #GStaticRecMutex with an
* unbounded lifetime, i.e. objects declared 'static', but if you have
* a #GStaticRecMutex as a member of a structure and the structure is
@@ -24217,6 +25963,7 @@
* Completely unlocks @mutex. If another thread is blocked in a
* g_static_rec_mutex_lock() call for @mutex, it will be woken and can
* lock @mutex itself. This function returns the number of times that
+ * @mutex has been locked by the current thread. To restore the state
* before the call to g_static_rec_mutex_unlock_full() you can call
* g_static_rec_mutex_lock_full() with the depth returned by this
* function.
@@ -24228,6 +25975,7 @@
* @lock: a #GStaticRWLock to be freed.
*
* Releases all resources allocated to @lock.
+ *
* You don't have to call this functions for a #GStaticRWLock with an
* unbounded lifetime, i.e. objects declared 'static', but if you have
* a #GStaticRWLock as a member of a structure, and the structure is
@@ -24253,8 +26001,10 @@
* reading of a #GStaticRWLock at the same time. If @lock is already
* locked for writing by another thread or if another thread is already
* waiting to lock @lock for writing, this function will block until
+ * @lock is unlocked by the other writing thread and no other writing
* threads want to lock @lock. This lock has to be unlocked by
* g_static_rw_lock_reader_unlock().
+ *
* #GStaticRWLock is not recursive. It might seem to be possible to
* recursively lock for reading, but that can result in a deadlock, due
* to writer preference.
@@ -24269,6 +26019,7 @@
* Tries to lock @lock for reading. If @lock is already locked for
* writing by another thread or if another thread is already waiting to
* lock @lock for writing, immediately returns %FALSE. Otherwise locks
+ * @lock for reading and returns %TRUE. This lock has to be unlocked by
* g_static_rw_lock_reader_unlock().
*/
@@ -24292,6 +26043,7 @@
* completely unlocked and then lock @lock for writing. While this
* functions waits to lock @lock, no other thread can lock @lock for
* reading. When @lock is locked for writing, no other thread can lock
+ * @lock (neither for reading nor writing). This lock has to be
* unlocked by g_static_rw_lock_writer_unlock().
*/
@@ -24342,6 +26094,8 @@
*
* Compares two strings for byte-by-byte equality and returns %TRUE
* if they are equal. It can be passed to g_hash_table_new() as the
+ * @key_equal_func parameter, when using strings as keys in a #GHashTable.
+ *
* Note that this function is primarily meant as a hash table comparison
* function. For a general-purpose, %NULL-safe string comparison function,
* see g_strcmp0().
@@ -24379,14 +26133,16 @@
* @v: a string key
*
* Converts a string to a hash value.
+ *
* This function implements the widely used "djb" hash apparently posted
* by Daniel Bernstein to comp.lang.c some time ago. The 32 bit
* unsigned hash value starts at 5381 and for each byte 'c' in the
+ * string, is updated: <literal>hash = hash * 33 + c</literal>. This
* function uses the signed value of each byte.
+ *
* It can be passed to g_hash_table_new() as the @hash_func parameter,
* when using strings as keys in a #GHashTable.
*
- * String, is updated: <literal>hash = hash * 33 + c</literal>. This
* Returns: a hash value corresponding to the key
*/
@@ -24398,11 +26154,13 @@
*
* A case-insensitive string comparison, corresponding to the standard
* strcasecmp() function on platforms which support it.
+ *
* or a positive value if @s1 > @s2.
+ *
+ * Deprecated:2.2: See g_strncasecmp() for a discussion of why this function
* is deprecated and how to replace it.
*
* Returns: 0 if the strings match, a negative value if @s1 < @s2,
- * Deprecated:2.2: See g_strncasecmp() for a discussion of why this function
*/
@@ -24427,9 +26185,11 @@
*
* Concatenates all of the given strings into one long string.
* The returned string should be freed with g_free() when no longer needed.
+ *
* Note that this function is usually not the right function to use to
* assemble a translated message from pieces, since proper translation
* often requires the pieces to be reordered.
+ *
* <warning><para>The variable argument list <emphasis>must</emphasis> end
* with %NULL. If you forget the %NULL, g_strconcat() will start appending
* random memory junk to your string.</para></warning>
@@ -24443,11 +26203,13 @@
* @string: the string to convert.
*
* Converts a string to lower case.
+ *
+ *
+ * Deprecated:2.2: This function is totally broken for the reasons discussed
* in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
* instead.
*
* Returns: the string
- * Deprecated:2.2: This function is totally broken for the reasons discussed
*/
@@ -24486,6 +26248,7 @@
* calculates the maximum space required and allocates memory to hold
* the result. The returned string should be freed with g_free() when
* no longer needed.
+ *
* See also g_vasprintf(), which offers the same functionality, but
* additionally returns the length of the allocated string.
*
@@ -24514,6 +26277,7 @@
* "no such process". You should use this function in preference to
* strerror(), because it returns a string in UTF-8 encoding, and since
* not all platforms support the strerror() function.
+ *
* is unknown, it returns "unknown error (<code>)". The string
* can only be used until the next call to g_strerror()
*
@@ -24523,10 +26287,9 @@
/**
* g_strfreev:
- * @str_array: a %NULL-terminated array of strings to free.
+ * @str_array: a %NULL-terminated array of strings to free. Frees a %NULL-terminated array of strings, and the array itself. If called on a %NULL value, g_strfreev() simply returns.
+ *
*
- * Frees a %NULL-terminated array of strings, and the array itself.
- * If called on a %NULL value, g_strfreev() simply returns.
*/
@@ -24563,6 +26326,7 @@
* Appends @len bytes of @val to @string. Because @len is
* provided, @val may contain embedded nuls and need not
* be nul-terminated.
+ *
* Since this function does not stop at nul bytes, it is
* the caller's responsibility to ensure that @val has at
* least @len addressable bytes.
@@ -24630,6 +26394,7 @@
* @string: a GString
*
* Converts all upper case ASCII letters to lower case ASCII letters.
+ *
* characters converted to lower case in place, with
* semantics that exactly match g_ascii_tolower().
*
@@ -24642,6 +26407,7 @@
* @string: a GString
*
* Converts all lower case ASCII letters to upper case ASCII letters.
+ *
* characters converted to upper case in place, with
* semantics that exactly match g_ascii_toupper().
*
@@ -24695,11 +26461,13 @@
* in the #GStringChunk. The characters in the string
* can be changed, if necessary, though you should not
* change anything after the end of the string.
+ *
* Unlike g_string_chunk_insert_const(), this function
* does not check for duplicates. Also strings added
* with g_string_chunk_insert() will not be searched
* by g_string_chunk_insert_const() when looking for
* duplicates.
+ *
* the #GStringChunk
*
* Returns: a pointer to the copy of @string within
@@ -24714,14 +26482,17 @@
* Adds a copy of @string to the #GStringChunk, unless the same
* string has already been added to the #GStringChunk with
* g_string_chunk_insert_const().
+ *
* This function is useful if you need to copy a large number
* of strings but do not want to waste space storing duplicates.
* But you must remember that there may be several pointers to
* the same string, and so any changes made to the strings
* should be done very carefully.
+ *
* Note that g_string_chunk_insert_const() will not return a
* pointer to a string added with g_string_chunk_insert(), even
* if they do match.
+ *
* within the #GStringChunk
*
* Returns: a pointer to the new or existing copy of @string
@@ -24736,9 +26507,11 @@
*
* Adds a copy of the first @len bytes of @string to the #GStringChunk.
* The copy is nul-terminated.
+ *
* Since this function does not stop at nul bytes, it is the caller's
* responsibility to ensure that @string has at least @len addressable
* bytes.
+ *
* The characters in the returned string can be changed, if necessary,
* though you should not change anything after the end of the string.
*
@@ -24762,11 +26535,13 @@
* @string: a #GString
*
* Converts a #GString to lowercase.
+ *
+ *
+ * Deprecated:2.2: This function uses the locale-specific
* tolower() function, which is almost never the right thing.
* Use g_string_ascii_down() or g_utf8_strdown() instead.
*
* Returns: the #GString.
- * Deprecated:2.2: This function uses the locale-specific
*/
@@ -24777,6 +26552,7 @@
*
* Compares two strings for equality, returning %TRUE if they are equal.
* For use with #GHashTable.
+ *
* same bytes
*
* Returns: %TRUE if they strings are the same length and contain the
@@ -24805,6 +26581,7 @@
* If @free_segment is %TRUE it also frees the character data. If
* it's %FALSE, the caller gains ownership of the buffer and must
* free it after use with g_free().
+ *
* (i.e. %NULL if @free_segment is %TRUE)
*
* Returns: the character data of @string
@@ -24857,6 +26634,7 @@
* Because @len is provided, @val may contain embedded
* nuls and need not be nul-terminated. If @pos is -1,
* bytes are inserted at the end of the string.
+ *
* Since this function does not stop at nul bytes, it is
* the caller's responsibility to ensure that @val has at
* least @len addressable bytes.
@@ -24896,6 +26674,7 @@
* Creates a new #GString with @len bytes of the @init buffer.
* Because a length is provided, @init need not be nul-terminated,
* and can contain embedded nul bytes.
+ *
* Since this function does not stop at nul bytes, it is the caller's
* responsibility to ensure that @init has at least @len addressable
* bytes.
@@ -24965,8 +26744,10 @@
* Prepends @len bytes of @val to @string.
* Because @len is provided, @val may contain
* embedded nuls and need not be nul-terminated.
+ *
* Since this function does not stop at nul bytes,
* it is the caller's responsibility to ensure that
+ * @val has at least @len addressable bytes.
*
* Returns: @string
*/
@@ -25072,11 +26853,13 @@
* @string: a #GString
*
* Converts a #GString to uppercase.
+ *
+ *
+ * Deprecated:2.2: This function uses the locale-specific
* toupper() function, which is almost never the right thing.
* Use g_string_ascii_up() or g_utf8_strup() instead.
*
* Returns: @string
- * Deprecated:2.2: This function uses the locale-specific
*/
@@ -25100,6 +26883,7 @@
* @msgval: another string
*
* An auxiliary function for gettext() support (see Q_()).
+ *
* a '|' character, in which case a pointer to the substring of msgid after
* the first '|' character is returned.
*
@@ -25116,6 +26900,7 @@
* Joins a number of strings together to form one long string, with the
* optional @separator inserted between each of them. The returned string
* should be freed with g_free().
+ *
* together, with @separator between them
*
* Returns: a newly-allocated string containing all of the strings joined
@@ -25130,6 +26915,7 @@
* Joins a number of strings together to form one long string, with the
* optional @separator inserted between each of them. The returned string
* should be freed with g_free().
+ *
* together, with @separator between them
*
* Returns: a newly-allocated string containing all of the strings joined
@@ -25146,14 +26932,17 @@
* and emulates it otherwise. Appends nul-terminated @src string to @dest,
* guaranteeing nul-termination for @dest. The total size of @dest won't
* exceed @dest_size.
+ *
* At most dest_size - 1 characters will be copied.
* Unlike strncat, dest_size is the full size of dest, not the space left over.
* This function does NOT allocate memory.
* This always NUL terminates (unless siz == 0 or there were no NUL characters
* in the dest_size characters of dest to start with).
+ *
* <note><para>Caveat: this is supposedly a more secure alternative to
* strcat() or strncat(), but for real security g_strconcat() is harder
* to mess up.</para></note>
+ *
* (original dest)) + strlen (src), so if retval >= dest_size,
* truncation occurred.
*
@@ -25170,11 +26959,14 @@
* Portability wrapper that calls strlcpy() on systems which have it,
* and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
* guaranteed to be nul-terminated; @src must be nul-terminated;
+ * @dest_size is the buffer size, not the number of chars to copy.
+ *
* At most dest_size - 1 characters will be copied. Always nul-terminates
* (unless dest_size == 0). This function does <emphasis>not</emphasis>
* allocate memory. Unlike strncpy(), this function doesn't pad dest (so
* it's often faster). It returns the size of the attempted result,
* strlen (src), so if @retval >= @dest_size, truncation occurred.
+ *
* <note><para>Caveat: strlcpy() is supposedly more secure than
* strcpy() or strncpy(), but if you really want to avoid screwups,
* g_strdup() is an even better idea.</para></note>
@@ -25193,7 +26985,10 @@
* strncasecmp() function on platforms which support it.
* It is similar to g_strcasecmp() except it only compares the first @n
* characters of the strings.
+ *
* or a positive value if @s1 > @s2.
+ *
+ * Deprecated:2.2: The problem with g_strncasecmp() is that it does the
* comparison by calling toupper()/tolower(). These functions are
* locale-specific and operate on single bytes. However, it is impossible
* to handle things correctly from an I18N standpoint by operating on
@@ -25202,12 +26997,12 @@
* locale-sensitive, and it's broken if your string is localized, since
* it doesn't work on many encodings at all, including UTF-8, EUC-JP,
* etc.
+ *
+ * There are therefore two replacement functions: g_ascii_strncasecmp(),
* which only works on ASCII and is not locale-sensitive, and
* g_utf8_casefold(), which is good for case-insensitive sorting of UTF-8.
*
* Returns: 0 if the strings match, a negative value if @s1 < @s2,
- * Deprecated:2.2: The problem with g_strncasecmp() is that it does the
- * There are therefore two replacement functions: g_ascii_strncasecmp(),
*/
@@ -25221,10 +27016,12 @@
* If @str is less than @n bytes long the buffer is padded with nuls.
* If @str is %NULL it returns %NULL.
* The returned value should be freed when no longer needed.
+ *
* <note><para>
* To copy a number of characters from a UTF-8 encoded string, use
* g_utf8_strncpy() instead.
* </para></note>
+ *
* of @str, nul-terminated
*
* Returns: a newly-allocated buffer containing the first @n bytes
@@ -25250,6 +27047,7 @@
* Reverses all of the bytes in a string. For example,
* <literal>g_strreverse ("abcdef")</literal> will result
* in "fedcba".
+ *
* Note that g_strreverse() doesn't work on UTF-8 strings
* containing multibyte characters. For that purpose, use
* g_utf8_strreverse().
@@ -25265,6 +27063,7 @@
*
* Searches the string @haystack for the last occurrence
* of the string @needle.
+ *
* %NULL if not found.
*
* Returns: a pointer to the found occurrence, or
@@ -25280,6 +27079,7 @@
* Searches the string @haystack for the last occurrence
* of the string @needle, limiting the length of the search
* to @haystack_len.
+ *
* %NULL if not found.
*
* Returns: a pointer to the found occurrence, or
@@ -25294,6 +27094,7 @@
* You should use this function in preference to strsignal(), because it
* returns a string in UTF-8 encoding, and since not all platforms support
* the strsignal() function.
+ *
* it returns "unknown signal (<signum>)". The string can only be
* used until the next call to g_strsignal()
*
@@ -25304,17 +27105,20 @@
/**
* g_strsplit:
* @string: a string to split.
- * @delimiter: a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings, unless
+ * @delimiter: a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings, unless @max_tokens is reached.
* @max_tokens: the maximum number of pieces to split @string into. If this is less than 1, the string is split completely.
*
* Splits a string into a maximum of @max_tokens pieces, using the given
+ * @delimiter. If @max_tokens is reached, the remainder of @string is appended
* to the last token.
+ *
* As a special case, the result of splitting the empty string "" is an empty
* vector, not a vector containing a single string. The reason for this
* special case is that being able to represent a empty vector is typically
* more useful than consistent handling of empty elements. If you do need
* to represent empty elements, you'll need to check for the empty string
* before calling g_strsplit().
+ *
* g_strfreev() to free it.
*
* Returns: a newly-allocated %NULL-terminated array of strings. Use
@@ -25331,19 +27135,24 @@
* in @delimiter. A token is the (possibly empty) longest string that does not
* contain any of the characters in @delimiters. If @max_tokens is reached, the
* remainder is appended to the last token.
+ *
* For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
* %NULL-terminated vector containing the three strings "abc", "def",
* and "ghi".
+ *
* The result if g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated
* vector containing the four strings "", "def", "ghi", and "".
+ *
* As a special case, the result of splitting the empty string "" is an empty
* vector, not a vector containing a single string. The reason for this
* special case is that being able to represent a empty vector is typically
* more useful than consistent handling of empty elements. If you do need
* to represent empty elements, you'll need to check for the empty string
* before calling g_strsplit_set().
+ *
* Note that this function works on bytes not characters, so it can't be used
* to delimit UTF-8 strings for anything but ASCII characters.
+ *
* g_strfreev() to free it.
*
* Returns: a newly-allocated %NULL-terminated array of strings. Use
@@ -25360,6 +27169,7 @@
* Searches the string @haystack for the first occurrence
* of the string @needle, limiting the length of the search
* to @haystack_len.
+ *
* %NULL if not found.
*
* Returns: a pointer to the found occurrence, or
@@ -25375,6 +27185,7 @@
* It calls the standard strtod() function to handle the conversion, but
* if the string is not completely converted it attempts the conversion
* again with g_ascii_strtod(), and returns the best match.
+ *
* This function should seldomly be used. The normal situation when reading
* numbers not for human consumption is to use g_ascii_strtod(). Only when
* you know that you must expect both locale formatted and C formatted numbers
@@ -25391,10 +27202,12 @@
* @string: the string to convert.
*
* Converts a string to upper case.
+ *
+ *
+ * Deprecated:2.2: This function is totally broken for the reasons discussed
* in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
*
* Returns: the string
- * Deprecated:2.2: This function is totally broken for the reasons discussed
*/
@@ -25478,6 +27291,7 @@
* @uri_pattern: the base pattern for bug URIs
*
* Specify the base URI for bug reports.
+ *
* The base URI is used to construct bug report messages for
* g_test_message() when g_test_bug() is called.
* Calling this function outside of a test case sets the
@@ -25509,10 +27323,12 @@
* function data_test() is called. Once the test run completed, the
* fixture structure is torn down by calling data_teardown() and
* after that the memory is released.
+ *
* Splitting up a test run into fixture setup, test function and
* fixture teardown is most usful if the same fixture is used for
* multiple tests. In this cases, g_test_create_case() will be
* called with the same fixture, but varying @test_name and
+ * @data_test arguments.
*
* Returns: a newly allocated #GTestCase.
* Since: 2.16
@@ -25536,12 +27352,15 @@
* Indicates that a test failed. This function can be called
* multiple times from the same test. You can use this function
* if your test failed in a recoverable way.
+ *
* Do not use this function if the failure of a test could cause
* other tests to malfunction.
+ *
* Calling this function will not stop the test from running, you
* need to return from the test function yourself. So you can
* produce additional diagnostic messages or even continue running
* the test.
+ *
* If not called from inside a test, this function does nothing.
*
* Since: 2.30
@@ -25687,14 +27506,17 @@
* Installs a non-error fatal log handler which can be
* used to decide whether log messages which are counted
* as fatal abort the program.
+ *
* The use case here is that you are running a test case
* that depends on particular libraries or circumstances
* and cannot prevent certain known critical or warning
* messages. So you install a handler that compares the
* domain and message to precisely not abort in such a case.
+ *
* Note that the handler is reset at the beginning of
* any test case, so you have to set it inside each test
* function which needs the special behavior.
+ *
* This handler has no effect on g_error messages.
*
* Since: 2.22
@@ -25800,9 +27622,11 @@
* g_test_rand_int:
*
* Get a reproducible random integer number.
+ *
* The random numbers generated by the g_test_rand_*() family of functions
* change with every new test program start, unless the --seed option is
* given when starting test programs.
+ *
* For individual test cases however, the random number generator is
* reseeded, to avoid dependencies between tests and to make --seed
* effective for all test cases.
@@ -25917,17 +27741,22 @@
* Fork the current test program to execute a test case that might
* not return or that might abort. The forked test case is aborted
* and considered failing if its run time exceeds @usec_timeout.
+ *
* The forking behavior can be configured with the #GTestTrapFlags flags.
+ *
* In the following example, the test code forks, the forked child
* process produces some sample output and exits successfully.
* The forking parent process then asserts successful child program
* termination and validates child program outputs.
+ *
* |[
* static void
* test_fork_patterns (void)
* {
* if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
* {
+ * g_print ("some stdout text: somagic17\n");
+ * g_printerr ("some stderr text: semagic43\n");
* exit (0); /* successful test run */
* }
* g_test_trap_assert_passed();
@@ -25935,10 +27764,9 @@
* g_test_trap_assert_stderr ("*semagic43*");
* }
* ]|
+ *
* This function is implemented only on Unix platforms.
*
- * G_print ("some stdout text: somagic17\n");
- * G_printerr ("some stderr text: semagic43\n");
* Returns: %TRUE for the forked child and %FALSE for the executing parent process.
* Since: 2.16
*/
@@ -25973,11 +27801,15 @@
* @Returns: the new #GThread on success.
*
* This function creates a new thread with the default priority.
+ *
* If @joinable is %TRUE, you can wait for this threads termination
* calling g_thread_join(). Otherwise the thread will just disappear
* when it terminates.
+ *
* The new thread executes the function @func with the argument @data.
* If the thread was created successfully, it is returned.
+ *
+ * @error can be %NULL to ignore errors, or non-%NULL to report errors.
* The error is set, if and only if the function returns %NULL.
*/
@@ -25997,6 +27829,7 @@
* the underlying thread implementation supports it, the thread gets a
* stack size of @stack_size or the default value for the current
* platform, if @stack_size is 0.
+ *
* If @joinable is %TRUE, you can wait for this threads termination
* calling g_thread_join(). Otherwise the thread will just disappear
* when it terminates. If @bound is %TRUE, this thread will be
@@ -26004,17 +27837,23 @@
* to do scheduling in the process scope. The first variant is more
* expensive resource-wise, but generally faster. On some systems (e.g.
* Linux) all threads are bound.
+ *
* The new thread executes the function @func with the argument @data.
* If the thread was created successfully, it is returned.
+ *
+ * @error can be %NULL to ignore errors, or non-%NULL to report errors.
* The error is set, if and only if the function returns %NULL.
+ *
* <note><para>It is not guaranteed that threads with different priorities
* really behave accordingly. On some systems (e.g. Linux) there are no
* thread priorities. On other systems (e.g. Solaris) there doesn't
* seem to be different scheduling for different priorities. All in all
* try to avoid being dependent on priorities. Use
* %G_THREAD_PRIORITY_NORMAL here as a default.</para></note>
+ *
* <note><para>Only use g_thread_create_full() if you really can't use
* g_thread_create() instead. g_thread_create() does not take
+ * @stack_size, @bound, and @priority as arguments, as they should only
* be used in cases in which it is unavoidable.</para></note>
*/
@@ -26028,13 +27867,16 @@
* waiting thread will be woken up and get @retval as the return value
* of g_thread_join(). If the current thread is not joinable, @retval
* is ignored. Calling
+ *
* <informalexample>
* <programlisting>
* g_thread_exit (retval);
* </programlisting>
* </informalexample>
+ *
* is equivalent to returning @retval from the function @func, as given
* to g_thread_create().
+ *
* <note><para>Never call g_thread_exit() from within a thread of a
* #GThreadPool, as that will mess up the bookkeeping and lead to funny
* and unwanted results.</para></note>
@@ -26049,8 +27891,10 @@
* Call @thread_func on all existing #GThread structures. Note that
* threads may decide to exit while @thread_func is running, so
* without intimate knowledge about the lifetime of foreign threads,
+ * @thread_func shouldn't access the GThread* pointer passed in as
* first argument. However, @thread_func will not be called for threads
* which are known to have exited already.
+ *
* Due to thread lifetime checks, this function has an execution complexity
* which is quadratic in the number of existing threads.
*
@@ -26075,20 +27919,26 @@
* If you use GLib from more than one thread, you must initialize the
* thread system by calling g_thread_init(). Most of the time you will
* only have to call <literal>g_thread_init (NULL)</literal>.
+ *
* <note><para>Do not call g_thread_init() with a non-%NULL parameter unless
* you really know what you are doing.</para></note>
+ *
* <note><para>g_thread_init() must not be called directly or indirectly as a
* callback from GLib. Also no mutexes may be currently locked while
* calling g_thread_init().</para></note>
+ *
* <note><para>g_thread_init() changes the way in which #GTimer measures
* elapsed time. As a consequence, timers that are running while
* g_thread_init() is called may report unreliable times.</para></note>
+ *
* Calling g_thread_init() multiple times is allowed (since version
* 2.24), but nothing happens except for the first call. If the
* argument is non-%NULL on such a call a warning will be printed, but
* otherwise the argument is ignored.
+ *
* If no thread system is available and @vtable is %NULL or if not all
* elements of @vtable are non-%NULL, then g_thread_init() will abort.
+ *
* <note><para>To use g_thread_init() in your program, you have to link with
* the libraries that the command <command>pkg-config --libs
* gthread-2.0</command> outputs. This is not the case for all the
@@ -26105,6 +27955,7 @@
* Waits until @thread finishes, i.e. the function @func, as given to
* g_thread_create(), returns or g_thread_exit() is called by @thread.
* All resources of @thread including the #GThread struct are released.
+ * @thread must have been created with @joinable=%TRUE in
* g_thread_create(). The value returned by @func or given to
* g_thread_exit() by @thread is returned by this function.
*/
@@ -26117,13 +27968,17 @@
* @wait_: should the function wait for all tasks to be finished?
*
* Frees all resources allocated for @pool.
+ *
* If @immediate is %TRUE, no new task is processed for
+ * @pool. Otherwise @pool is not freed before the last task is
* processed. Note however, that no thread of this pool is
* interrupted, while processing a task. Instead at least all still
* running threads can finish their tasks before the @pool is freed.
+ *
* If @wait_ is %TRUE, the functions does not return before all tasks
* to be processed (dependent on @immediate, whether all or only the
* currently running) are ready. Otherwise the function returns immediately.
+ *
* After calling this function @pool must not be used anymore.
*/
@@ -26133,8 +27988,10 @@
*
* This function will return the maximum @interval that a thread will
* wait in the thread pool for new tasks before being stopped.
+ *
* If this function returns 0, threads waiting in the thread pool for
* new work are not stopped.
+ *
* thread pool before stopping the thread (1/1000ths of a second).
*
* Returns: the maximum @interval to wait for new tasks in the
@@ -26189,6 +28046,7 @@
* @error: return location for error
*
* This function creates a new thread pool.
+ *
* Whenever you call g_thread_pool_push(), either a new thread is
* created or an unused one is reused. At most @max_threads threads
* are running concurrently for this thread pool. @max_threads = -1
@@ -26196,6 +28054,7 @@
* newly created or reused thread now executes the function @func with
* the two arguments. The first one is the parameter to
* g_thread_pool_push() and the second one is @user_data.
+ *
* The parameter @exclusive determines, whether the thread pool owns
* all threads exclusive or whether the threads are shared
* globally. If @exclusive is %TRUE, @max_threads threads are started
@@ -26204,6 +28063,8 @@
* threads are created, when needed and shared between all
* non-exclusive thread pools. This implies that @max_threads may not
* be -1 for exclusive thread pools.
+ *
+ * @error can be %NULL to ignore errors, or non-%NULL to report
* errors. An error can only occur when @exclusive is set to %TRUE and
* not all @max_threads threads could be created.
*
@@ -26223,6 +28084,8 @@
* the properties given to g_thread_pool_new (). Otherwise @data stays
* in the queue until a thread in this pool finishes its previous task
* and processes @data.
+ *
+ * @error can be %NULL to ignore errors, or non-%NULL to report
* errors. An error can only occur when a new thread couldn't be
* created. In that case @data is simply appended to the queue of work
* to do.
@@ -26238,8 +28101,11 @@
* stopped. This function is similar to calling
* g_thread_pool_stop_unused_threads() on a regular timeout, except,
* this is done on a per thread basis.
+ *
* By setting @interval to 0, idle threads will not be stopped.
+ *
* This function makes use of g_async_queue_timed_pop () using
+ * @interval.
*
* Since: 2.10
*/
@@ -26253,14 +28119,18 @@
*
* Sets the maximal allowed number of threads for @pool. A value of -1
* means, that the maximal number of threads is unlimited.
+ *
* Setting @max_threads to 0 means stopping all work for @pool. It is
* effectively frozen until @max_threads is set to a non-zero value
* again.
+ *
* A thread is never terminated while calling @func, as supplied by
* g_thread_pool_new (). Instead the maximal number of threads only
* has effect for the allocation of new threads in g_thread_pool_push().
* A new thread is allocated, whenever the number of currently
* running threads in @pool is smaller than the maximal number.
+ *
+ * @error can be %NULL to ignore errors, or non-%NULL to report
* errors. An error can only occur when a new thread couldn't be
* created.
*/
@@ -26271,6 +28141,7 @@
* @max_threads: maximal number of unused threads
*
* Sets the maximal number of unused threads to @max_threads. If
+ * @max_threads is -1, no limit is imposed on the number of unused
* threads.
*/
@@ -26284,6 +28155,7 @@
* Sets the function used to sort the list of tasks. This allows the
* tasks to be processed by a priority determined by @func, and not
* just in the order in which they were added to the pool.
+ *
* Note, if the maximum number of threads is more than 1, the order
* that threads are executed cannot be guranteed 100%. Threads are
* scheduled by the operating system and are executed at random. It
@@ -26328,6 +28200,7 @@
* @priority: a new priority for @thread.
*
* Changes the priority of @thread to @priority.
+ *
* <note><para>It is not guaranteed that threads with different
* priorities really behave accordingly. On some systems (e.g. Linux)
* there are no thread priorities. On other systems (e.g. Solaris) there
@@ -26342,6 +28215,7 @@
*
* This function returns %TRUE if the thread system is initialized, and
* %FALSE if it is not.
+ *
* <note><para>This function is actually a macro. Apart from taking the
* address of it you can however use it as if it was a
* function.</para></note>
@@ -26352,6 +28226,7 @@
* g_thread_yield:
*
* Gives way to other threads waiting to be scheduled.
+ *
* This function is often used as a method to make busy wait less evil.
* But in most cases you will encounter, there are better methods to do
* that. So in general you shouldn't use this function.
@@ -26402,11 +28277,14 @@
* Finds an interval within @tz that corresponds to the given @time_,
* possibly adjusting @time_ if required to fit into an interval.
* The meaning of @time_ depends on @type.
+ *
* This function is similar to g_time_zone_find_interval(), with the
* difference that it always succeeds (by making the adjustments
* described below).
+ *
* In any of the cases where g_time_zone_find_interval() succeeds then
* this function returns the same value, without modifying @time_.
+ *
* This function may, however, modify @time_ in order to deal with
* non-existent times. If the non-existent local @time_ of 02:30 were
* requested on March 13th 2010 in Toronto then this function would
@@ -26426,8 +28304,10 @@
*
* Finds an the interval within @tz that corresponds to the given @time_.
* The meaning of @time_ depends on @type.
+ *
* If @type is %G_TIME_TYPE_UNIVERSAL then this function will always
* succeed (since universal time is monotonic and continuous).
+ *
* Otherwise @time_ is treated is local time. The distinction between
* %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
* the case that the given @time_ is ambiguous. In Toronto, for example,
@@ -26435,6 +28315,7 @@
* savings time and the next, an hour later, outside of daylight savings
* time). In this case, the different value of @type would result in a
* different interval being returned.
+ *
* It is still possible for this function to fail. In Toronto, for
* example, 02:00 on March 14th 2010 does not exist (due to the leap
* forward to begin daylight savings time). -1 is returned in that
@@ -26451,6 +28332,8 @@
* @interval: an interval within the timezone
*
* Determines the time zone abbreviation to be used during a particular
+ * @interval of time in the time zone @tz.
+ *
* For example, in Toronto this is currently "EST" during the winter
* months and "EDT" during the summer months when daylight savings time
* is in effect.
@@ -26467,11 +28350,13 @@
*
* Determines the offset to UTC in effect during a particular @interval
* of time in the time zone @tz.
+ *
* The offset is the number of seconds that you add to UTC time to
+ * arrive at local time for @tz (ie: negative numbers for time zones
* west of GMT, positive numbers for east).
+ *
* local time in @tz
*
- * Arrive at local time for @tz (ie: negative numbers for time zones
* Returns: the number of seconds that should be added to UTC to get the
* Since: 2.26
*/
@@ -26483,6 +28368,7 @@
* @interval: an interval within the timezone
*
* Determines if daylight savings time is in effect during a particular
+ * @interval of time in the time zone @tz.
*
* Returns: %TRUE if daylight savings time is in effect
* Since: 2.26
@@ -26494,20 +28380,26 @@
* @identifier: (allow-none): a timezone identifier
*
* Creates a #GTimeZone corresponding to @identifier.
+ *
+ * @identifier can either be an RFC3339/ISO 8601 time offset or
* something that would pass as a valid value for the
* <varname>TZ</varname> environment variable (including %NULL).
+ *
* Valid RFC3339 time offsets are <literal>"Z"</literal> (for UTC) or
* <literal>"Âhh:mm"</literal>. ISO 8601 additionally specifies
* <literal>"Âhhmm"</literal> and <literal>"Âhh"</literal>.
+ *
* The <varname>TZ</varname> environment variable typically corresponds
* to the name of a file in the zoneinfo database, but there are many
* other possibilities. Note that those other possibilities are not
* currently implemented, but are planned.
+ *
* g_time_zone_new_local() calls this function with the value of the
* <varname>TZ</varname> environment variable. This function itself is
* independent of the value of <varname>TZ</varname>, but if @identifier
* is %NULL then <filename>/etc/localtime</filename> will be consulted
* to discover the correct timezone.
+ *
* See <ulink
* url='http://tools.ietf.org/html/rfc3339#section-5.6'>RFC3339
* Â5.6</ulink> for a precise definition of valid RFC3339 time offsets
@@ -26516,6 +28408,7 @@
* url='http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html'>The
* GNU C Library manual</ulink> for an explanation of the possible
* values of the <varname>TZ</varname> environment variable.
+ *
* You should release the return value by calling g_time_zone_unref()
* when you are done with it.
*
@@ -26528,10 +28421,12 @@
* g_time_zone_new_local:
*
* Creates a #GTimeZone corresponding to local time.
+ *
* This is equivalent to calling g_time_zone_new() with the value of the
* <varname>TZ</varname> environment variable (including the possibility
* of %NULL). Changes made to <varname>TZ</varname> after the first
* call to this function may or may not be noticed by future calls.
+ *
* You should release the return value by calling g_time_zone_unref()
* when you are done with it.
*
@@ -26544,8 +28439,10 @@
* g_time_zone_new_utc:
*
* Creates a #GTimeZone corresponding to UTC.
+ *
* This is equivalent to calling g_time_zone_new() with a value like
* "Z", "UTC", "+00", etc.
+ *
* You should release the return value by calling g_time_zone_unref()
* when you are done with it.
*
@@ -26569,12 +28466,15 @@
* g_time_zone_refresh_local:
*
* Notifies #GTimeZone that the local timezone may have changed.
+ *
* In response, #GTimeZone will drop its cache of the local time zone.
* No existing #GTimeZone will be modified and no #GDateTime will change
* its timezone but future calls to g_time_zone_new_local() will start
* returning the new timezone.
+ *
* #GTimeZone does no monitoring of the local timezone on its own, which
* is why you have to call this function to notify it of the change.
+ *
* If you use #GTimeZoneMonitor to watch for changes then this function
* will automatically be called for you.
*/
@@ -26601,15 +28501,18 @@
* until it returns %FALSE, at which point the timeout is automatically
* destroyed and the function will not be called again. The first call
* to the function will be at the end of the first @interval.
+ *
* Note that timeout functions may be delayed, due to the processing of other
* event sources. Thus they should not be relied on for precise timing.
* After each call to the timeout function, the time of the next
* timeout is recalculated based on the current time and the given interval
* (it does not try to 'catch up' time lost in delays).
+ *
* If you want to have a timer in the "seconds" range and do not care
* about the exact time of the first call of the timer, use the
* g_timeout_add_seconds() function; this function allows for more
* optimizations and more efficient system power usage.
+ *
* This internally creates a main loop source using g_timeout_source_new()
* and attaches it to the main loop context using g_source_attach(). You can
* do these steps manually if you need greater control.
@@ -26632,11 +28535,13 @@
* the function will not be called again. The @notify function is
* called when the timeout is destroyed. The first call to the
* function will be at the end of the first @interval.
+ *
* Note that timeout functions may be delayed, due to the processing of other
* event sources. Thus they should not be relied on for precise timing.
* After each call to the timeout function, the time of the next
* timeout is recalculated based on the current time and the given interval
* (it does not try to 'catch up' time lost in delays).
+ *
* This internally creates a main loop source using g_timeout_source_new()
* and attaches it to the main loop context using g_source_attach(). You can
* do these steps manually if you need greater control.
@@ -26656,10 +28561,12 @@
* priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until
* it returns %FALSE, at which point the timeout is automatically destroyed
* and the function will not be called again.
+ *
* This internally creates a main loop source using
* g_timeout_source_new_seconds() and attaches it to the main loop context
* using g_source_attach(). You can do these steps manually if you need
* greater control. Also see g_timeout_add_seconds_full().
+ *
* Note that the first call of the timer may not be precise for timeouts
* of one second. If you need finer precision and have such a timeout,
* you may want to use g_timeout_add() instead.
@@ -26681,6 +28588,7 @@
* The function is called repeatedly until it returns %FALSE, at which
* point the timeout is automatically destroyed and the function will
* not be called again.
+ *
* Unlike g_timeout_add(), this function operates at whole second granularity.
* The initial starting point of the timer is determined by the implementation
* and the implementation is expected to group multiple timers together so that
@@ -26688,16 +28596,20 @@
* To allow this grouping, the @interval to the first timer is rounded
* and can deviate up to one second from the specified interval.
* Subsequent timer iterations will generally run at the specified interval.
+ *
* Note that timeout functions may be delayed, due to the processing of other
* event sources. Thus they should not be relied on for precise timing.
* After each call to the timeout function, the time of the next
* timeout is recalculated based on the current time and the given @interval
+ *
* If you want timing more precise than whole seconds, use g_timeout_add()
* instead.
+ *
* The grouping of timers to fire at the same time results in a more power
* and CPU efficient behavior so if your timer is in multiples of seconds
* and you don't require the first timer exactly one second from now, the
* use of g_timeout_add_seconds() is preferred over g_timeout_add().
+ *
* This internally creates a main loop source using
* g_timeout_source_new_seconds() and attaches it to the main loop context
* using g_source_attach(). You can do these steps manually if you need
@@ -26714,6 +28626,7 @@
* @interval: the timeout interval in milliseconds.
*
* Creates a new timeout source.
+ *
* The source will not initially be associated with any #GMainContext
* and must be added to one with g_source_attach() before it will be
* executed.
@@ -26727,9 +28640,11 @@
* @interval: the timeout interval in seconds
*
* Creates a new timeout source.
+ *
* The source will not initially be associated with any #GMainContext
* and must be added to one with g_source_attach() before it will be
* executed.
+ *
* The scheduling granularity/accuracy of this timeout source will be
* in seconds.
*
@@ -26770,6 +28685,7 @@
* stopped. The return value is the number of seconds elapsed,
* including any fractional part. The @microseconds out parameter is
* essentially useless.
+ *
* <warning><para>
* Calling initialization functions, in particular g_thread_init(), while a
* timer is running will cause invalid return values from this function.
@@ -26837,6 +28753,8 @@
*
* Calls the given function for each of the key/value pairs in the #GTree.
* The function is passed the key and value of each pair, and the given
+ * @data parameter. The tree is traversed in sorted order.
+ *
* The tree may not be modified while iterating over it (you can't
* add/remove items). To remove all items matching a predicate, you need
* to add each item to a list in your #GTraverseFunc as you walk over
@@ -26849,6 +28767,7 @@
* @tree: a #GTree.
*
* Gets the height of a #GTree.
+ *
* If the #GTree contains no nodes, the height is 0.
* If the #GTree contains only one root node the height is 1.
* If the root node has children the height is 2, etc.
@@ -26868,6 +28787,7 @@
* supplied a value_destroy_func when creating the #GTree, the old value is
* freed using that function. If you supplied a @key_destroy_func when
* creating the #GTree, the passed key is freed using that function.
+ *
* The tree is automatically 'balanced' as new key/value pairs are added,
* so that the distance from the root to every leaf is as small as possible.
*/
@@ -26881,6 +28801,7 @@
* Gets the value corresponding to the given key. Since a #GTree is
* automatically balanced as key/value pairs are added, key lookup is very
* fast.
+ *
* not found.
*
* Returns: the value corresponding to the key, or %NULL if the key was
@@ -26968,10 +28889,12 @@
* @key: the key to remove.
*
* Removes a key/value pair from a #GTree.
+ *
* If the #GTree was created using g_tree_new_full(), the key and value
* are freed using the supplied destroy functions, otherwise you have to
* make sure that any dynamically allocated values are freed yourself.
* If the key does not exist in the #GTree, the function does nothing.
+ *
* nothing)
*
* Returns: %TRUE if the key was found (prior to 2.8, this function returned
@@ -26990,6 +28913,7 @@
* creating the #GTree, the old value is freed using that function. If you
* supplied a @key_destroy_func when creating the #GTree, the old key is
* freed using that function.
+ *
* The tree is automatically 'balanced' as new key/value pairs are added,
* so that the distance from the root to every leaf is as small as possible.
*/
@@ -27002,12 +28926,15 @@
* @user_data: the data passed as the second argument to @search_func
*
* Searches a #GTree using @search_func.
+ *
* The @search_func is called with a pointer to the key of a key/value
* pair in the tree, and the passed in @user_data. If @search_func returns
* 0 for a key/value pair, then the corresponding value is returned as
* the result of g_tree_search(). If @search_func returns -1, searching
* will proceed among the key/value pairs that have a smaller key; if
+ * @search_func returns 1, searching will proceed among the key/value
* pairs that have a larger key.
+ *
* the key was not found.
*
* Returns: the value corresponding to the found key, or %NULL if
@@ -27021,7 +28948,9 @@
*
* Removes a key and its associated value from a #GTree without calling
* the key and value destroy functions.
+ *
* If the key does not exist in the #GTree, the function does nothing.
+ *
* nothing)
*
* Returns: %TRUE if the key was found (prior to 2.8, this function returned
@@ -27036,11 +28965,11 @@
* @user_data: user data to pass to the function.
*
* Calls the given function for each node in the #GTree.
+ *
+ * Deprecated:2.2: The order of a balanced tree is somewhat arbitrary. If you
* just want to visit all nodes in sorted order, use g_tree_foreach()
* instead. If you really need to visit nodes in a different order, consider
* using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
- *
- * Deprecated:2.2: The order of a balanced tree is somewhat arbitrary. If you
*/
@@ -27052,6 +28981,7 @@
* drops to 0, all keys and values will be destroyed (if destroy
* functions were specified) and all memory allocated by @tree will be
* released.
+ *
* It is safe to call this function from any thread.
*
* Since: 2.22
@@ -27220,8 +29150,10 @@
*
* Convert a string from UCS-4 to UTF-16. A 0 character will be
* added to the result after the converted text.
+ *
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
+ * @error set.
*
* Returns: a pointer to a newly allocated UTF-16 string.
*/
@@ -27237,8 +29169,10 @@
*
* Convert a string from a 32-bit fixed width representation as UCS-4.
* to UTF-8. The result will be terminated with a 0 byte.
+ *
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
+ * @error set. In that case, @items_read will be
* set to the position of the first invalid input
* character.
*
@@ -27280,13 +29214,17 @@
*
* Performs a single composition step of the
* Unicode canonical composition algorithm.
+ *
* This function does not perform algorithmic composition
* for Hangul characters, and does not include compatibility
* compositions. It does, however, include 'singleton'
* compositions which replace a character by a single
* other character. To obtain these, pass zero for @b.
+ *
* This function includes algorithmic Hangul Jamo composition.
+ *
* If @a and @b do not compose a new character, @ch is set to zero.
+ *
* See <ulink url="http://unicode.org/reports/tr15/";>UAX#15</ulink>
* for details.
*
@@ -27303,20 +29241,24 @@
*
* Performs a single decomposition step of the
* Unicode canonical decomposition algorithm.
+ *
* This function does not include compatibility
* decompositions. It does, however, include algorithmic
* Hangul Jamo decomposition, as well as 'singleton'
* decompositions which replace a character by a single
* other character. In the case of singletons * b will
* be set to zero.
+ *
* If @ch is not decomposable, * a is set to @ch and * b
* is set to zero.
+ *
* Note that the way Unicode decomposition pairs are
* defined, it is guaranteed that @b would not decompose
* further, but @a may itself decompose. To get the full
* canonical decomposition for @ch, one would need to
* recursively call this function on @a. Or use
* g_unichar_fully_decompose().
+ *
* See <ulink url="http://unicode.org/reports/tr15/";>UAX#15</ulink>
* for details.
*
@@ -27331,6 +29273,7 @@
*
* Determines the numeric value of a character as a decimal
* digit.
+ *
* g_unichar_isdigit()), its numeric value. Otherwise, -1.
*
* Returns: If @c is a decimal digit (according to
@@ -27348,11 +29291,17 @@
* Unicode character. For compatibility decomposition,
* pass %TRUE for @compat; for canonical decomposition
* pass %FALSE for @compat.
+ *
* The decomposed sequence is placed in @result. Only up to
+ * @result_len characters are written into @result. The length
* of the full decomposition (irrespective of @result_len) is
- * returned by the function. For canonical decomposition, a
- * result buffer of length 4 is always enough, whereas for
- * compatibility decomposition, a buffer of 18 is enough.
+ * returned by the function. For canonical decomposition,
+ * currently all decompositions are of length at most 4, but
+ * this may change in the future (very unlikely though).
+ * At any rate, Unicode does guarantee that a buffer of length
+ * 18 is always enough for both compatibility and canonical
+ * decompositions.
+ *
* See <ulink url="http://unicode.org/reports/tr15/";>UAX#15</ulink>
* for details.
*
@@ -27370,6 +29319,7 @@
* means that their images are mirrored horizontally in text that is laid
* out from right to left. For instance, "(" would become its mirror image,
* ")", in right-to-left text.
+ *
* If @ch has the Unicode mirrored property and there is another unicode
* character that typically has a glyph that is the mirror image of @ch's
* glyph and @mirrored_ch is set, it puts that character in the address
@@ -27388,6 +29338,7 @@
* by Unicode Standard Annex #24). No check is made for @ch being a
* valid Unicode character; if you pass in invalid character, the
* result is undefined.
+ *
* This function is equivalent to pango_script_for_unichar() and the
* two are interchangeable.
*
@@ -27489,11 +29440,12 @@
* combining mark, or enclosing mark in Unicode speak).
* Given some UTF-8 text, obtain a character value
* with g_utf8_get_char().
+ *
+ * Note: in most cases where isalpha characters are allowed,
* ismark characters should be allowed to as they are essential
* for writing most European languages as well as many non-Latin
* scripts.
*
- * Note: in most cases where isalpha characters are allowed,
* Returns: %TRUE if @c is a mark character
* Since: 2.14
*/
@@ -27531,6 +29483,7 @@
* Determines whether a character is a space, tab, or line separator
* (newline, carriage return, etc.). Given some UTF-8 text, obtain a
* character value with g_utf8_get_char().
+ *
* (Note: don't use this to do word breaking; you have to use
* Pango or equivalent to get word breaking right, the algorithm
* is fairly complex.)
@@ -27585,6 +29538,7 @@
* the converse is not necessarily true. See the
* <ulink url="http://www.unicode.org/reports/tr11/";>Unicode Standard
* Annex #11</ulink> for details.
+ *
* If a character passes the g_unichar_iswide() test then it will also pass
* this test, but not the other way around. Note that some characters may
* pas both this test and g_unichar_iszerowidth().
@@ -27612,6 +29566,7 @@
* The return value is %TRUE for all non-spacing and enclosing marks
* (e.g., combining accents), format characters, zero-width
* space, but not U+00AD SOFT HYPHEN.
+ *
* A typical use of this function is with one of g_unichar_iswide() or
* g_unichar_iswide_cjk() to determine the number of cells a string occupies
* when displayed on a grid display (terminals). However, note that not all
@@ -27638,6 +29593,7 @@
* @c: a Unicode character.
*
* Converts a character to lower case.
+ *
* If @c is not an upperlower or titlecase character,
* or has no lowercase equivalent @c is returned unchanged.
*
@@ -27650,7 +29606,9 @@
* @c: a Unicode character
*
* Converts a character to the titlecase.
+ *
* If @c is not an uppercase or lowercase character,
+ * @c is returned unchanged.
*
* Returns: the result of converting @c to titlecase.
*/
@@ -27661,6 +29619,7 @@
* @c: a Unicode character
*
* Converts a character to uppercase.
+ *
* If @c is not an lowercase or titlecase character,
* or has no upper case equivalent @c is returned unchanged.
*
@@ -27696,6 +29655,7 @@
*
* Determines the numeric value of a character as a hexidecimal
* digit.
+ *
* g_unichar_isxdigit()), its numeric value. Otherwise, -1.
*
* Returns: If @c is a hex digit (according to
@@ -27708,6 +29668,9 @@
* @result_len: location to store the length of the return value.
*
* Computes the canonical decomposition of a Unicode character.
+ *
+ * @result_len is set to the resulting length of the string.
+ *
* instead.
*
* Returns: a newly allocated string of Unicode characters.
@@ -27736,8 +29699,10 @@
* This function accepts four letter codes encoded as a @guint32 in a
* big-endian fashion. That is, the code expected for Arabic is
* 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
+ *
* See <ulink url="http://unicode.org/iso15924/codelists.html";>Codes for the
* representation of names of scripts</ulink> for details.
+ *
* of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and
* %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown.
*
@@ -27755,8 +29720,10 @@
* four letter codes are encoded as a @guint32 by this function in a
* big-endian fashion. That is, the code returned for Arabic is
* 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
+ *
* See <ulink url="http://unicode.org/iso15924/codelists.html";>Codes for the
* representation of names of scripts</ulink> for details.
+ *
* of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or
* ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood.
*
@@ -27776,6 +29743,7 @@
* the configured flags. The only supported flag currently is
* %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK,
* that must still be done separately with fcntl().
+ *
* <note>This function does *not* take %O_CLOEXEC, it takes
* %FD_CLOEXEC as if for fcntl(); these are different on
* Linux/glibc.</note>
@@ -27826,6 +29794,7 @@
* be monitored. Note that unlike the UNIX default, all sources which
* have created a watch will be dispatched, regardless of which
* underlying thread invoked g_unix_signal_source_new().
+ *
* For example, an effective use of this function is to handle SIGTERM
* cleanly; flushing any outstanding files, and then calling
* g_main_loop_quit (). It is not safe to do any of this a regular
@@ -27833,13 +29802,16 @@
* another library function is running, causing reentrancy if you
* attempt to use it from the handler. None of the GLib/GObject API
* is safe against this kind of reentrancy.
+ *
* The interaction of this source when combined with native UNIX
* functions like sigprocmask() is not defined.
+ *
* <note>For reliable behavior, if your program links to gthread
* (either directly or indirectly via GObject, GIO, or a higher level
* library), you should ensure g_thread_init() is called before using
* this function. For example, if your program uses GObject, call
* g_type_init().</note>
+ *
* The source will not initially be associated with any #GMainContext
* and must be added to one with g_source_attach() before it will be
* executed.
@@ -27857,9 +29829,11 @@
* deletes a name from the filesystem. If this was the last link to the
* file and no processes have it opened, the diskspace occupied by the
* file is freed.
+ *
* See your C library manual for more details about unlink(). Note
* that on Windows, it is in general not possible to delete files that
* are open to some process, or mapped into memory.
+ *
* occurred
*
* Returns: 0 if the name was successfully deleted, -1 if an error
@@ -27872,6 +29846,7 @@
* @variable: the environment variable to remove, must not contain '='.
*
* Removes an environment variable from the environment.
+ *
* Note that on some systems, when variables are overwritten, the memory
* used for the previous variables and its value isn't reclaimed.
* Furthermore, this function can't be guaranteed to operate in a
@@ -27888,12 +29863,14 @@
* @allow_utf8: %TRUE if the result can include UTF-8 characters.
*
* Escapes a string for use in a URI.
+ *
* Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical
* characters plus dash, dot, underscore and tilde) are escaped.
* But if you specify characters in @reserved_chars_allowed they are not
* escaped. This is useful for the "reserved" characters in the URI
* specification, since those are allowed unescaped in some portions of
* a URI.
+ *
* freed when no longer needed.
*
* Returns: an escaped version of @unescaped. The returned string should be
@@ -27908,6 +29885,7 @@
* Splits an URI list conforming to the text/uri-list
* mime type defined in RFC 2483 into individual URIs,
* discarding any comments. The URIs are not validated.
+ *
* strings holding the individual URIs. The array should
* be freed with g_strfreev().
*
@@ -27925,6 +29903,7 @@
* URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
* </programlisting>
* Common schemes include "file", "http", "svn+ssh", etc.
+ *
* The returned string should be freed when no longer needed.
*
* Returns: The "Scheme" component of the URI, or %NULL on error.
@@ -27939,11 +29918,13 @@
* @illegal_characters: an optional string of illegal characters not to be allowed.
*
* Unescapes a segment of an escaped string.
+ *
* If any of the characters in @illegal_characters or the character zero appears
* as an escaped character in @escaped_string then that is an error and %NULL
* will be returned. This is useful it you want to avoid for instance having a
* slash being expanded in an escaped path element, which might confuse pathname
* handling.
+ *
* The returned string should be freed when no longer needed.
*
* Returns: an unescaped version of @escaped_string or %NULL on error.
@@ -27957,11 +29938,13 @@
* @illegal_characters: an optional string of illegal characters not to be allowed.
*
* Unescapes a whole escaped string.
+ *
* If any of the characters in @illegal_characters or the character zero appears
* as an escaped character in @escaped_string then that is an error and %NULL
* will be returned. This is useful it you want to avoid for instance having a
* slash being expanded in an escaped path element, which might confuse pathname
* handling.
+ *
* should be freed when no longer needed.
*
* Returns: an unescaped version of @escaped_string. The returned string
@@ -27979,8 +29962,10 @@
*
* Convert a string from UTF-16 to UCS-4. The result will be
* nul-terminated.
+ *
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
+ * @error set.
*
* Returns: a pointer to a newly allocated UCS-4 string.
*/
@@ -27996,17 +29981,21 @@
*
* Convert a string from UTF-16 to UTF-8. The result will be
* terminated with a 0 byte.
+ *
* Note that the input is expected to be already in native endianness,
* an initial byte-order-mark character is not handled specially.
* g_convert() can be used to convert a byte buffer of UTF-16 data of
* ambiguous endianess.
+ *
* Further note that this function does not validate the result
* string; it may e.g. include embedded NUL characters. The only
* validation done by this function is to ensure that the input can
* be correctly interpreted as UTF-16, i.e. it doesn't contain
* things unpaired surrogates.
+ *
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
+ * @error set.
*
* Returns: a pointer to a newly allocated UTF-8 string.
*/
@@ -28021,12 +30010,14 @@
* result will not correspond to any particular case, but can be
* compared for equality or ordered with the results of calling
* g_utf8_casefold() on other strings.
+ *
* Note that calling g_utf8_casefold() followed by g_utf8_collate() is
* only an approximation to the correct linguistic case insensitive
* ordering, though it is a fairly good one. Getting this exactly
* right would require a more sophisticated collation function that
* takes case sensitivity into account. GLib does not currently
* provide such a function.
+ *
* case independent form of @str.
*
* Returns: a newly allocated string, that is a
@@ -28044,6 +30035,7 @@
* faster to obtain collation keys with g_utf8_collate_key() and
* compare the keys with strcmp() when sorting instead of sorting
* the original strings.
+ *
* 0 if they compare equal, > 0 if @str1 compares after @str2.
*
* Returns: < 0 if @str1 compares before @str2,
@@ -28058,11 +30050,14 @@
* Converts a string into a collation key that can be compared
* with other collation keys produced by the same function using
* strcmp().
+ *
* The results of comparing the collation keys of two strings
* with strcmp() will always be the same as comparing the two
* original keys with g_utf8_collate().
+ *
* Note that this function depends on the
* <link linkend="setlocale">current locale</link>.
+ *
* be freed with g_free() when you are done with it.
*
* Returns: a newly allocated string. This string should
@@ -28076,14 +30071,17 @@
*
* Converts a string into a collation key that can be compared
* with other collation keys produced by the same function using strcmp().
+ *
* In order to sort filenames correctly, this function treats the dot '.'
* as a special case. Most dictionary orderings seem to consider it
* insignificant, thus producing the ordering "event.c" "eventgenerator.c"
* "event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we
* would like to treat numbers intelligently so that "file1" "file10" "file5"
* is sorted as "file1" "file5" "file10".
+ *
* Note that this function depends on the
* <link linkend="setlocale">current locale</link>.
+ *
* be freed with g_free() when you are done with it.
*
* Returns: a newly allocated string. This string should
@@ -28097,6 +30095,8 @@
* @end: a pointer to the byte following the end of the string, or %NULL to indicate that the string is nul-terminated.
*
* Finds the start of the next UTF-8 character in the string after @p.
+ *
+ * @p does not have to be at the beginning of a UTF-8 character. No check
* is made to see if the character found is actually valid other than
* it starts with an appropriate byte.
*
@@ -28112,6 +30112,8 @@
* Given a position @p with a UTF-8 encoded string @str, find the start
* of the previous UTF-8 character starting before @p. Returns %NULL if no
* UTF-8 characters are present in @str before @p.
+ *
+ * @p does not have to be at the beginning of a UTF-8 character. No check
* is made to see if the character found is actually valid other than
* it starts with an appropriate byte.
*
@@ -28142,6 +30144,7 @@
* This function checks for incomplete characters, for invalid characters
* such as characters that are out of the range of Unicode, and for
* overlong encodings of valid characters.
+ *
* sequence at the end of a string that could begin a valid
* character (or if @max_len is zero), returns (gunichar)-2;
* otherwise, if @p does not point to a valid UTF-8 encoded
@@ -28177,6 +30180,7 @@
* string has to be valid UTF-8, otherwise %NULL is
* returned. You should generally call g_utf8_normalize()
* before comparing two Unicode strings.
+ *
* The normalization mode %G_NORMALIZE_DEFAULT only
* standardizes differences that do not affect the
* text content, such as the above-mentioned accent
@@ -28186,6 +30190,7 @@
* (in this case DIGIT THREE). Formatting information
* may be lost but for most text operations such
* characters should be considered the same.
+ *
* %G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE
* are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL,
* but returned a result with composed forms rather
@@ -28193,6 +30198,7 @@
* useful if you intend to convert the string to
* a legacy encoding or pass it to a system with
* less capable Unicode handling.
+ *
* normalized form of @str, or %NULL if @str is not
* valid UTF-8.
*
@@ -28207,14 +30213,17 @@
*
* Converts from an integer character offset to a pointer to a position
* within the string.
+ *
* Since 2.10, this function allows to pass a negative @offset to
* step backwards. It is usually worth stepping backwards from the end
* instead of forwards if @offset is in the last fourth of the string,
* since moving forward is about 3 times faster than moving backward.
+ *
* <note><para>
* This function doesn't abort when reaching the end of @str. Therefore
* you should be sure that @offset is within string boundaries before
* calling that function. Call g_utf8_strlen() when unsure.
+ *
* This limitation exists as this function is called frequently during
* text rendering and therefore has to be as fast as possible.
* </para></note>
@@ -28230,6 +30239,7 @@
*
* Converts from a pointer to position within a string to a integer
* character offset.
+ *
* Since 2.10, this function allows @pos to be before @str, and returns
* a negative offset in this case.
*
@@ -28242,6 +30252,8 @@
* @p: a pointer to a position within a UTF-8 encoded string
*
* Finds the previous UTF-8 character in the string before @p.
+ *
+ * @p does not have to be at the beginning of a UTF-8 character. No check
* is made to see if the character found is actually valid other than
* it starts with an appropriate byte. If @p might be the first
* character of the string, you must use g_utf8_find_prev_char() instead.
@@ -28259,6 +30271,7 @@
* Finds the leftmost occurrence of the given Unicode character
* in a UTF-8 encoded string, while limiting the search to @len bytes.
* If @len is -1, allow unbounded search.
+ *
* otherwise, a pointer to the start of the leftmost occurrence of
* the character in the string.
*
@@ -28275,6 +30288,7 @@
* to lowercase. The exact manner that this is done depends
* on the current locale, and may result in the number of
* characters in the string changing.
+ *
* converted to lowercase.
*
* Returns: a newly allocated string, with all characters
@@ -28318,6 +30332,7 @@
* Find the rightmost occurrence of the given Unicode character
* in a UTF-8 encoded string, while limiting the search to @len bytes.
* If @len is -1, allow unbounded search.
+ *
* otherwise, a pointer to the start of the rightmost occurrence of the
* character in the string.
*
@@ -28333,11 +30348,13 @@
* Reverses a UTF-8 string. @str must be valid UTF-8 encoded text.
* (Use g_utf8_validate() on all text before trying to use UTF-8
* utility functions with it.)
+ *
* This function is intended for programmatic uses of reversed strings.
* It pays no attention to decomposed characters, combining marks, byte
* order marks, directional indicators (LRM, LRO, etc) and similar
* characters which might need special handling when reversing a string
* for display purposes.
+ *
* Note that unlike g_strreverse(), this function returns
* newly-allocated memory, which should be freed with g_free() when
* no longer needed.
@@ -28357,6 +30374,7 @@
* on the current locale, and may result in the number of
* characters in the string increasing. (For instance, the
* German ess-zet will be changed to SS.)
+ *
* converted to uppercase.
*
* Returns: a newly allocated string, with all characters
@@ -28372,6 +30390,7 @@
* Copies a substring out of a UTF-8 encoded string.
* The substring will contain @end_pos - @start_pos
* characters.
+ *
* substring. Free with g_free() when no longer needed.
*
* Returns: a newly allocated copy of the requested
@@ -28390,8 +30409,10 @@
* Convert a string from UTF-8 to a 32-bit fixed width
* representation as UCS-4. A trailing 0 character will be added to the
* string after the converted text.
+ *
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
+ * @error set.
*
* Returns: a pointer to a newly allocated UCS-4 string.
*/
@@ -28408,6 +30429,7 @@
* This function is roughly twice as fast as g_utf8_to_ucs4()
* but does no error checking on the input. A trailing 0 character
* will be added to the string after the converted text.
+ *
* This value must be freed with g_free().
*
* Returns: a pointer to a newly allocated UCS-4 string.
@@ -28424,8 +30446,10 @@
*
* Convert a string from UTF-8 to UTF-16. A 0 character will be
* added to the result after the converted text.
+ *
* This value must be freed with g_free(). If an
* error occurs, %NULL will be returned and
+ * @error set.
*
* Returns: a pointer to a newly allocated UTF-16 string.
*/
@@ -28435,16 +30459,19 @@
* g_utf8_validate:
* @str: a pointer to character data
* @max_len: max bytes to validate, or -1 to go until NUL
- * @end: return location for end of valid data
+ * @end: (allow-none) (out): return location for end of valid data
*
* Validates UTF-8 encoded text. @str is the text to validate;
* if @str is nul-terminated, then @max_len can be -1, otherwise
+ * @max_len should be the number of bytes to validate.
* If @end is non-%NULL, then the end of the valid range
* will be stored there (i.e. the start of the first invalid
* character if some bytes were invalid, or the end of the text
* being validated otherwise).
+ *
* Note that g_utf8_validate() returns %FALSE if @max_len is
* positive and NUL is met before @max_len bytes have been read.
+ *
* Returns %TRUE if all of @str was valid. Many GLib and GTK+
* routines <emphasis>require</emphasis> valid UTF-8 as input;
* so data read from a file or the network should be checked
@@ -28461,8 +30488,10 @@
*
* A wrapper for the POSIX utime() function. The utime() function
* sets the access and modification timestamps of a file.
+ *
* See your C library manual for more details about how utime() works
* on your system.
+ *
* occurred
*
* Returns: 0 if the operation was successful, -1 if an error
@@ -28477,22 +30506,28 @@
* @...: arguments, as per @format_string
*
* Adds to a #GVariantBuilder.
+ *
* This call is a convenience wrapper that is exactly equivalent to
* calling g_variant_new() followed by g_variant_builder_add_value().
+ *
* This function might be used as follows:
+ *
* <programlisting>
* GVariant *
* make_pointless_dictionary (void)
* {
* GVariantBuilder *builder;
* int i;
+ *
* builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
* for (i = 0; i < 16; i++)
* {
* gchar buf[3];
+ *
* sprintf (buf, "%d", i);
* g_variant_builder_add (builder, "{is}", i, buf);
* }
+ *
* return g_variant_builder_end (builder);
* }
* </programlisting>
@@ -28508,16 +30543,20 @@
* @...: arguments as per @format
*
* Adds to a #GVariantBuilder.
+ *
* This call is a convenience wrapper that is exactly equivalent to
* calling g_variant_new_parsed() followed by
* g_variant_builder_add_value().
+ *
* This function might be used as follows:
+ *
* <programlisting>
* GVariant *
* make_pointless_dictionary (void)
* {
* GVariantBuilder *builder;
* int i;
+ *
* builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
* g_variant_builder_add_parsed (builder, "{'width', <%i>}", 600);
* g_variant_builder_add_parsed (builder, "{'title', <%s>}", "foo");
@@ -28536,11 +30575,13 @@
* @value: a #GVariant
*
* Adds @value to @builder.
+ *
* It is an error to call this function in any way that would create an
* inconsistent value to be constructed. Some examples of this are
* putting different types of items into an array, putting the wrong
* types or number of items in a tuple, putting more than one value into
* a variant, etc.
+ *
* If @value is a floating reference (see g_variant_ref_sink()),
* the @builder instance takes ownership of @value.
*
@@ -28554,12 +30595,14 @@
*
* Releases all memory associated with a #GVariantBuilder without
* freeing the #GVariantBuilder structure itself.
+ *
* It typically only makes sense to do this on a stack-allocated
* #GVariantBuilder if you want to abort building the value part-way
* through. This function need not be called if you call
* g_variant_builder_end() and it also doesn't need to be called on
* builders allocated with g_variant_builder_new (see
* g_variant_builder_unref() for that).
+ *
* This function leaves the #GVariantBuilder structure set to all-zeros.
* It is valid to call this function on either an initialised
* #GVariantBuilder or one that is set to all-zeros but it is not valid
@@ -28575,10 +30618,11 @@
*
* Closes the subcontainer inside the given @builder that was opened by
* the most recent call to g_variant_builder_open().
+ *
* It is an error to call this function in any way that would create an
+ * inconsistent value to be constructed (ie: too few values added to the
* subcontainer).
*
- * Inconsistent value to be constructed (ie: too few values added to the
* Since: 2.24
*/
@@ -28589,18 +30633,20 @@
* @returns: (transfer none): a new, floating, #GVariant
*
* Ends the builder process and returns the constructed value.
+ *
* It is not permissible to use @builder in any way after this call
* except for reference counting operations (in the case of a
* heap-allocated #GVariantBuilder) or by reinitialising it with
* g_variant_builder_init() (in the case of stack-allocated).
+ *
* It is an error to call this function in any way that would create an
+ * inconsistent value to be constructed (ie: insufficient number of
* items added to a container with a specific number of children
* required). It is also an error to call this function if the builder
* was created with an indefinite array or maybe type and no children
* have been added; in this case it is impossible to infer the type of
* the empty array.
*
- * Inconsistent value to be constructed (ie: insufficient number of
* Since: 2.24
*/
@@ -28611,21 +30657,27 @@
* @type: a container type
*
* Initialises a #GVariantBuilder structure.
+ *
+ * @type must be non-%NULL. It specifies the type of container to
* construct. It can be an indefinite type such as
* %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
* Maybe, array, tuple, dictionary entry and variant-typed values may be
* constructed.
+ *
* After the builder is initialised, values are added using
* g_variant_builder_add_value() or g_variant_builder_add().
+ *
* After all the child values are added, g_variant_builder_end() frees
* the memory associated with the builder and returns the #GVariant that
* was created.
+ *
* This function completely ignores the previous contents of @builder.
* On one hand this means that it is valid to pass in completely
* uninitialised memory. On the other hand, this means that if you are
* initialising over top of an existing #GVariantBuilder you need to
* first call g_variant_builder_clear() in order to avoid leaking
* memory.
+ *
* You must not call g_variant_builder_ref() or
* g_variant_builder_unref() on a #GVariantBuilder that was initialised
* with this function. If you ever pass a reference to a
@@ -28644,9 +30696,11 @@
* @returns: (transfer full): a #GVariantBuilder
*
* Allocates and initialises a new #GVariantBuilder.
+ *
* You should call g_variant_builder_unref() on the return value when it
* is no longer needed. The memory will not be automatically freed by
* any other call.
+ *
* In most cases it is easier to place a #GVariantBuilder directly on
* the stack of the calling function and initialise it with
* g_variant_builder_init().
@@ -28662,10 +30716,11 @@
*
* Opens a subcontainer inside the given @builder. When done adding
* items to the subcontainer, g_variant_builder_close() must be called.
+ *
* It is an error to call this function in any way that would cause an
+ * inconsistent value to be constructed (ie: adding too many values or
* a value of an incorrect type).
*
- * Inconsistent value to be constructed (ie: adding too many values or
* Since: 2.24
*/
@@ -28676,6 +30731,7 @@
* @returns: (transfer full): a new reference to @builder
*
* Increases the reference count on @builder.
+ *
* Don't call this on stack-allocated #GVariantBuilder instances or bad
* things will happen.
*
@@ -28688,8 +30744,10 @@
* @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new()
*
* Decreases the reference count on @builder.
+ *
* In the event that there are no more references, releases all memory
* associated with the #GVariantBuilder.
+ *
* Don't call this on stack-allocated #GVariantBuilder instances or bad
* things will happen.
*
@@ -28707,9 +30765,11 @@
* byteswapped. That includes 16, 32, and 64bit signed and unsigned
* integers as well as file handles and double precision floating point
* values.
+ *
* This function is an identity mapping on any value that does not
* contain multi-byte numeric data. That include strings, booleans,
* bytes and containers containing only these things (recursively).
+ *
* The returned value is always in normal form and is marked as trusted.
*
* Since: 2.24
@@ -28734,21 +30794,25 @@
* @returns: negative value if a < b; zero if a = b; positive value if a > b.
*
* Compares @one and @two.
+ *
* The types of @one and @two are #gconstpointer only to allow use of
* this function with #GTree, #GPtrArray, etc. They must each be a
* #GVariant.
+ *
+ * Comparison is only defined for basic types (ie: booleans, numbers,
* strings). For booleans, %FALSE is less than %TRUE. Numbers are
* ordered in the usual way. Strings are in ASCII lexographical order.
+ *
* It is a programmer error to attempt to compare container values or
* two values that have types that are not exactly equal. For example,
* you cannot compare a 32-bit signed integer with a 32-bit unsigned
* integer. Also note that this function is not particularly
* well-behaved when it comes to comparison of doubles; in particular,
+ * the handling of incomparable values (ie: NaN) is undefined.
+ *
* If you only require an equality comparison, g_variant_equal() is more
* general.
*
- * Comparison is only defined for basic types (ie: booleans, numbers,
- * The handling of incomparable values (ie: NaN) is undefined.
* Since: 2.26
*/
@@ -28757,10 +30821,11 @@
* g_variant_dup_bytestring:
* @value: an array-of-bytes #GVariant instance
* @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store the length (not including the nul terminator)
- * @returns: (transfer full) (array zero-terminated=1): a newly allocated string
+ * @returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8): a newly allocated string
*
* Similar to g_variant_get_bytestring() except that instead of
* returning a constant string, the string is duplicated.
+ *
* The return value must be freed using g_free().
*
* Since: 2.26
@@ -28776,9 +30841,11 @@
* Gets the contents of an array of array of bytes #GVariant. This call
* makes a deep copy; the return result should be released with
* g_strfreev().
+ *
* If @length is non-%NULL then the number of elements in the result is
* stored there. In any case, the resulting array will be
* %NULL-terminated.
+ *
* For an empty array, @length will be set to 0 and a pointer to a
* %NULL pointer will be returned.
*
@@ -28795,9 +30862,11 @@
* Gets the contents of an array of object paths #GVariant. This call
* makes a deep copy; the return result should be released with
* g_strfreev().
+ *
* If @length is non-%NULL then the number of elements in the result
* is stored there. In any case, the resulting array will be
* %NULL-terminated.
+ *
* For an empty array, @length will be set to 0 and a pointer to a
* %NULL pointer will be returned.
*
@@ -28813,7 +30882,9 @@
*
* Similar to g_variant_get_string() except that instead of returning
* a constant string, the string is duplicated.
+ *
* The string will always be utf8 encoded.
+ *
* The return value must be freed using g_free().
*
* Since: 2.24
@@ -28829,9 +30900,11 @@
* Gets the contents of an array of strings #GVariant. This call
* makes a deep copy; the return result should be released with
* g_strfreev().
+ *
* If @length is non-%NULL then the number of elements in the result
* is stored there. In any case, the resulting array will be
* %NULL-terminated.
+ *
* For an empty array, @length will be set to 0 and a pointer to a
* %NULL pointer will be returned.
*
@@ -28846,6 +30919,7 @@
* @returns: %TRUE if @one and @two are equal
*
* Checks if @one and @two have the same type and value.
+ *
* The types of @one and @two are #gconstpointer only to allow use of
* this function with #GHashTable. They must each be a #GVariant.
*
@@ -28860,7 +30934,9 @@
* @...: arguments, as per @format_string
*
* Deconstructs a #GVariant instance.
+ *
* Think of this function as an analogue to scanf().
+ *
* The arguments that are expected by this function are entirely
* determined by @format_string. @format_string also restricts the
* permissible types of @value. It is an error to give a value with
@@ -28879,6 +30955,7 @@
* @returns: %TRUE or %FALSE
*
* Returns the boolean value of @value.
+ *
* It is an error to call this function with a @value of any type
* other than %G_VARIANT_TYPE_BOOLEAN.
*
@@ -28892,6 +30969,7 @@
* @returns: a #guchar
*
* Returns the byte value of @value.
+ *
* It is an error to call this function with a @value of any type
* other than %G_VARIANT_TYPE_BYTE.
*
@@ -28902,18 +30980,22 @@
/**
* g_variant_get_bytestring:
* @value: an array-of-bytes #GVariant instance
- * @returns: (transfer none) (array zero-terminated=1): the constant string
+ * @returns: (transfer none) (array zero-terminated=1) (element-type guint8): the constant string
*
* Returns the string value of a #GVariant instance with an
* array-of-bytes type. The string has no particular encoding.
+ *
* If the array does not end with a nul terminator character, the empty
* string is returned. For this reason, you can always trust that a
* non-%NULL nul-terminated string will be returned by this function.
+ *
* If the array contains a nul terminator character somewhere other than
* the last byte then the returned string is the string, up to the first
* such nul character.
+ *
* It is an error to call this function with a @value that is not an
* array of bytes.
+ *
* The return value remains valid as long as @value exists.
*
* Since: 2.26
@@ -28929,9 +31011,11 @@
* Gets the contents of an array of array of bytes #GVariant. This call
* makes a shallow copy; the return result should be released with
* g_free(), but the individual strings must not be modified.
+ *
* If @length is non-%NULL then the number of elements in the result is
* stored there. In any case, the resulting array will be
* %NULL-terminated.
+ *
* For an empty array, @length will be set to 0 and a pointer to a
* %NULL pointer will be returned.
*
@@ -28965,8 +31049,10 @@
* includes variants, maybes, arrays, tuples and dictionary
* entries. It is an error to call this function on any other type of
* #GVariant.
+ *
* It is an error if @index_ is greater than the number of child items
* in the container. See g_variant_n_children().
+ *
* This function is O(1).
*
* Since: 2.24
@@ -28976,17 +31062,19 @@
/**
* g_variant_get_data:
* @value: a #GVariant instance
- * @returns: the serialised form of @value, or %NULL
+ * @returns: (transfer none): the serialised form of @value, or %NULL
*
* Returns a pointer to the serialised form of a #GVariant instance.
* The returned data may not be in fully-normalised form if read from an
* untrusted source. The returned data must not be freed; it remains
* valid for as long as @value exists.
+ *
* If @value is a fixed-sized value that was deserialised from a
* corrupted serialised container then %NULL may be returned. In this
* case, the proper thing to do is typically to use the appropriate
* number of nul bytes in place of @value. If @value is not fixed-sized
* then %NULL is never returned.
+ *
* In the case that @value is already in serialised form, this function
* is O(1). If the value is not already in serialised form,
* serialisation occurs implicitly and is approximately O(n) in the size
@@ -29002,6 +31090,7 @@
* @returns: a #gdouble
*
* Returns the double precision floating point value of @value.
+ *
* It is an error to call this function with a @value of any type
* other than %G_VARIANT_TYPE_DOUBLE.
*
@@ -29014,15 +31103,21 @@
* @value: a #GVariant array with fixed-sized elements
* @n_elements: (out): a pointer to the location to store the number of items
* @element_size: the size of each element
- * @returns: (array length=n_elements): a pointer to the fixed array
+ * @returns: (array length=n_elements) (transfer none): a pointer to the fixed array
*
* Provides access to the serialised data for an array of fixed-sized
* items.
+ *
+ * @value must be an array with fixed-sized elements. Numeric types are
* fixed-size as are tuples containing only other fixed-sized types.
+ *
+ * @element_size must be the size of a single element in the array. For
* example, if calling this function for an array of 32 bit integers,
* you might say <code>sizeof (gint32)</code>. This value isn't used
* except for the purpose of a double-check that the form of the
* seralised data matches the caller's expectation.
+ *
+ * @n_elements, which must be non-%NULL is set equal to the number of
* items in the array.
*
* Since: 2.24
@@ -29035,8 +31130,10 @@
* @returns: a #gint32
*
* Returns the 32-bit signed integer value of @value.
+ *
* It is an error to call this function with a @value of any type other
* than %G_VARIANT_TYPE_HANDLE.
+ *
* By convention, handles are indexes into an array of file descriptors
* that are sent alongside a D-Bus message. If you're not interacting
* with D-Bus, you probably don't need them.
@@ -29051,6 +31148,7 @@
* @returns: a #gint16
*
* Returns the 16-bit signed integer value of @value.
+ *
* It is an error to call this function with a @value of any type
* other than %G_VARIANT_TYPE_INT16.
*
@@ -29064,6 +31162,7 @@
* @returns: a #gint32
*
* Returns the 32-bit signed integer value of @value.
+ *
* It is an error to call this function with a @value of any type
* other than %G_VARIANT_TYPE_INT32.
*
@@ -29077,6 +31176,7 @@
* @returns: a #gint64
*
* Returns the 64-bit signed integer value of @value.
+ *
* It is an error to call this function with a @value of any type
* other than %G_VARIANT_TYPE_INT64.
*
@@ -29103,13 +31203,17 @@
*
* Gets a #GVariant instance that has the same value as @value and is
* trusted to be in normal form.
+ *
* If @value is already trusted to be in normal form then a new
* reference to @value is returned.
+ *
* If @value is not already trusted, then it is scanned to check if it
* is in normal form. If it is found to be in normal form then it is
* marked as trusted and a new reference to it is returned.
+ *
* If @value is found not to be in normal form then a new trusted
* #GVariant is created with the same value as @value.
+ *
* It makes sense to call this function if you've received #GVariant
* data from untrusted sources and you want to ensure your serialised
* output is definitely in normal form.
@@ -29127,9 +31231,11 @@
* Gets the contents of an array of object paths #GVariant. This call
* makes a shallow copy; the return result should be released with
* g_free(), but the individual strings must not be modified.
+ *
* If @length is non-%NULL then the number of elements in the result
* is stored there. In any case, the resulting array will be
* %NULL-terminated.
+ *
* For an empty array, @length will be set to 0 and a pointer to a
* %NULL pointer will be returned.
*
@@ -29144,14 +31250,16 @@
*
* Determines the number of bytes that would be required to store @value
* with g_variant_store().
+ *
* If @value has a fixed-sized type then this function always returned
* that fixed size.
+ *
* In the case that @value is already in serialised form or the size has
+ * already been calculated (ie: this function has been called before)
* then this function is O(1). Otherwise, the size is calculated, an
* operation which is approximately O(n) in the number of values
* involved.
*
- * Already been calculated (ie: this function has been called before)
* Since: 2.24
*/
@@ -29165,12 +31273,16 @@
* Returns the string value of a #GVariant instance with a string
* type. This includes the types %G_VARIANT_TYPE_STRING,
* %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
+ *
* The string will always be utf8 encoded.
+ *
* If @length is non-%NULL then the length of the string (in bytes) is
* returned there. For trusted values, this information is already
* known. For untrusted values, a strlen() will be performed.
+ *
* It is an error to call this function with a @value of any type
* other than those three.
+ *
* The return value remains valid as long as @value exists.
*
* Since: 2.24
@@ -29186,9 +31298,11 @@
* Gets the contents of an array of strings #GVariant. This call
* makes a shallow copy; the return result should be released with
* g_free(), but the individual strings must not be modified.
+ *
* If @length is non-%NULL then the number of elements in the result
* is stored there. In any case, the resulting array will be
* %NULL-terminated.
+ *
* For an empty array, @length will be set to 0 and a pointer to a
* %NULL pointer will be returned.
*
@@ -29202,6 +31316,7 @@
* @returns: a #GVariantType
*
* Determines the type of @value.
+ *
* The return value is valid for the lifetime of @value and must not
* be freed.
*
@@ -29228,6 +31343,7 @@
* @returns: a #guint16
*
* Returns the 16-bit unsigned integer value of @value.
+ *
* It is an error to call this function with a @value of any type
* other than %G_VARIANT_TYPE_UINT16.
*
@@ -29241,6 +31357,7 @@
* @returns: a #guint32
*
* Returns the 32-bit unsigned integer value of @value.
+ *
* It is an error to call this function with a @value of any type
* other than %G_VARIANT_TYPE_UINT32.
*
@@ -29254,6 +31371,7 @@
* @returns: a #guint64
*
* Returns the 64-bit unsigned integer value of @value.
+ *
* It is an error to call this function with a @value of any type
* other than %G_VARIANT_TYPE_UINT64.
*
@@ -29271,12 +31389,19 @@
* This function is intended to be used by libraries based on #GVariant
* that want to provide g_variant_get()-like functionality to their
* users.
+ *
* The API is more general than g_variant_get() to allow a wider range
* of possible uses.
+ *
+ * @format_string must still point to a valid format string, but it only
* need to be nul-terminated if @endptr is %NULL. If @endptr is
* non-%NULL then it is updated to point to the first character past the
* end of the format string.
+ *
+ * @app is a pointer to a #va_list. The arguments, according to
+ * @format_string, are collected from this #va_list and the list is left
* pointing to the argument following the last.
+ *
* These two generalisations allow mixing of multiple calls to
* g_variant_new_va() and g_variant_get_va() within a single actual
* varargs call by the user.
@@ -29303,10 +31428,12 @@
* @returns: a hash value corresponding to @value
*
* Generates a hash value for a #GVariant instance.
+ *
* The output of this function is guaranteed to be the same for a given
* value only per-process. It may change between different processor
* architectures or even different versions of GLib. Do not use this
* function as a basis for building protocols or file formats.
+ *
* The type of @value is #gconstpointer only to allow use of this
* function with #GHashTable. @value must be a #GVariant.
*
@@ -29329,10 +31456,12 @@
* @returns: whether @value is floating
*
* Checks whether @value has a floating reference count.
+ *
* This function should only ever be used to assert that a given variant
* is or is not floating, or for debug purposes. To acquire a reference
* to a variant that might be floating, always use g_variant_ref_sink()
* or g_variant_take_ref().
+ *
* See g_variant_ref_sink() for more information about floating reference
* counts.
*
@@ -29346,14 +31475,16 @@
* @returns: %TRUE if @value is in normal form
*
* Checks if @value is in normal form.
+ *
* The main reason to do this is to detect if a given chunk of
+ * serialised data is in normal form: load the data into a #GVariant
* using g_variant_new_from_data() and then use this function to
* check.
+ *
* If @value is found to be in normal form then it will be marked as
* being trusted. If the value was already marked as being trusted then
* this function will immediately return %TRUE.
*
- * Serialised data is in normal form: load the data into a #GVariant
* Since: 2.24
*/
@@ -29366,6 +31497,7 @@
* Determines if a given string is a valid D-Bus object path. You
* should ensure that a string is a valid D-Bus object path before
* passing it to g_variant_new_object_path().
+ *
* A valid object path starts with '/' followed by zero or more
* sequences of characters separated by '/' characters. Each sequence
* must contain only the characters "[A-Z][a-z][0-9]_". No sequence
@@ -29395,6 +31527,7 @@
* Determines if a given string is a valid D-Bus type signature. You
* should ensure that a string is a valid D-Bus type signature before
* passing it to g_variant_new_signature().
+ *
* D-Bus type signatures consist of zero or more definite #GVariantType
* strings in sequence.
*
@@ -29411,8 +31544,10 @@
* container that was being iterated over by @iter. Iteration begins on
* the new iterator from the current position of the old iterator but
* the two copies are independent past that point.
+ *
* Use g_variant_iter_free() to free the return value when you no longer
* need it.
+ *
* A reference is taken to the container that @iter is iterating over
* and will be releated only when g_variant_iter_free() is called.
*
@@ -29441,6 +31576,7 @@
* Initialises (without allocating) a #GVariantIter. @iter may be
* completely uninitialised prior to this call; its old value is
* ignored.
+ *
* The iterator remains valid for as long as @value exists, and need not
* be freed in any way.
*
@@ -29457,13 +31593,16 @@
*
* Gets the next item in the container and unpacks it into the variable
* argument list according to @format_string, returning %TRUE.
+ *
* If no more items remain then %FALSE is returned.
+ *
* On the first call to this function, the pointers appearing on the
* variable argument list are assumed to point at uninitialised memory.
* On the second and later calls, it is assumed that the same pointers
* will be given and that they will point to the memory as set by the
* previous call to this function. This allows the previous values to
* be freed, as appropriate.
+ *
* This function is intended to be used with a while loop as
* demonstrated in the following example. This function can only be
* used when iterating over an array. It is only valid to call this
@@ -29471,8 +31610,10 @@
* string constant must be used each time. Mixing calls to this
* function and g_variant_iter_next() or g_variant_iter_next_value() on
* the same iterator is not recommended.
+ *
* See the section on <link linkend='gvariant-format-strings'>GVariant
* Format Strings</link>.
+ *
* <example>
* <title>Memory management with g_variant_iter_loop()</title>
* <programlisting>
@@ -29483,20 +31624,25 @@
* GVariantIter iter;
* GVariant *value;
* gchar *key;
+ *
* g_variant_iter_init (&iter, dictionary);
* while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
* {
* g_print ("Item '%s' has type '%s'\n", key,
* g_variant_get_type_string (value));
+ *
* /<!-- -->* no need to free 'key' and 'value' here *<!-- -->/
* }
* }
* </programlisting>
* </example>
+ *
* For most cases you should use g_variant_iter_next().
+ *
* This function is really only useful when unpacking into #GVariant or
* #GVariantIter in order to allow you to skip the call to
* g_variant_unref() or g_variant_iter_free().
+ *
* For example, if you are only looping over simple integer and string
* types, g_variant_iter_next() is definitely preferred. For string
* types, use the '&' prefix to avoid allocating any memory at all (and
@@ -29514,6 +31660,7 @@
* Queries the number of child items in the container that we are
* iterating over. This is the total number of items -- not the number
* of items remaining.
+ *
* This function might be useful for preallocation of arrays.
*
* Since: 2.24
@@ -29527,8 +31674,10 @@
*
* Creates a heap-allocated #GVariantIter for iterating over the items
* in @value.
+ *
* Use g_variant_iter_free() to free the return value when you no longer
* need it.
+ *
* A reference is taken to @value and will be released only when
* g_variant_iter_free() is called.
*
@@ -29545,13 +31694,17 @@
*
* Gets the next item in the container and unpacks it into the variable
* argument list according to @format_string, returning %TRUE.
+ *
* If no more items remain then %FALSE is returned.
+ *
* All of the pointers given on the variable arguments list of this
* function are assumed to point at uninitialised memory. It is the
* responsibility of the caller to free all of the values returned by
* the unpacking process.
+ *
* See the section on <link linkend='gvariant-format-strings'>GVariant
* Format Strings</link>.
+ *
* <example>
* <title>Memory management with g_variant_iter_next()</title>
* <programlisting>
@@ -29562,11 +31715,13 @@
* GVariantIter iter;
* GVariant *value;
* gchar *key;
+ *
* g_variant_iter_init (&iter, dictionary);
* while (g_variant_iter_next (&iter, "{sv}", &key, &value))
* {
* g_print ("Item '%s' has type '%s'\n", key,
* g_variant_get_type_string (value));
+ *
* /<!-- -->* must free data for ourselves *<!-- -->/
* g_variant_unref (value);
* g_free (key);
@@ -29574,6 +31729,7 @@
* }
* </programlisting>
* </example>
+ *
* For a solution that is likely to be more convenient to C programmers
* when dealing with loops, see g_variant_iter_loop().
*
@@ -29588,8 +31744,10 @@
*
* Gets the next item in the container. If no more items remain then
* %NULL is returned.
+ *
* Use g_variant_unref() to drop your reference on the return value when
* you no longer need it.
+ *
* <example>
* <title>Iterating with g_variant_iter_next_value()</title>
* <programlisting>
@@ -29599,12 +31757,15 @@
* {
* GVariantIter iter;
* GVariant *child;
+ *
* g_variant_iter_init (&iter, container);
* while ((child = g_variant_iter_next_value (&iter)))
* {
* g_print ("type '%s'\n", g_variant_get_type_string (child));
+ *
* if (g_variant_is_container (child))
* iterate_container_recursive (child);
+ *
* g_variant_unref (child);
* }
* }
@@ -29623,10 +31784,12 @@
* @...: the arguments to unpack the value into
*
* Looks up a value in a dictionary #GVariant.
+ *
* This function is a wrapper around g_variant_lookup_value() and
* g_variant_get(). In the case that %NULL would have been returned,
* this function returns %FALSE. Otherwise, it unpacks the returned
* value and returns %TRUE.
+ *
* See g_variant_get() for information about @format_string.
*
* Returns: %TRUE if a value was unpacked
@@ -29641,10 +31804,12 @@
* @expected_type: (allow-none): a #GVariantType, or %NULL
*
* Looks up a value in a dictionary #GVariant.
+ *
* This function works with dictionaries of the type
* <literal>a{s*}</literal> (and equally well with type
* <literal>a{o*}</literal>, but we only further discuss the string case
* for sake of clarity).
+ *
* In the event that @dictionary has the type <literal>a{sv}</literal>,
* the @expected_type string specifies what type of value is expected to
* be inside of the variant. If the value inside the variant has a
@@ -29652,8 +31817,10 @@
* has a value type other than <literal>v</literal> then @expected_type
* must directly match the key type and it is used to unpack the value
* directly or an error occurs.
+ *
* In either case, if @key is not found in @dictionary, %NULL is
* returned.
+ *
* If the key is found and the value has the correct type, it is
* returned. If @expected_type was specified then any non-%NULL return
* value will have this type.
@@ -29672,10 +31839,12 @@
* This includes variants, maybes, arrays, tuples and dictionary
* entries. It is an error to call this function on any other type of
* #GVariant.
+ *
* For variants, the return value is always 1. For values with maybe
* types, it is always zero or one. For arrays, it is the length of the
* array. For tuples it is the number of tuple items (which depends
* only on the type). For dictionary entries, it is always 2
+ *
* This function is O(1).
*
* Since: 2.24
@@ -29689,12 +31858,15 @@
* @returns: a new floating #GVariant instance
*
* Creates a new #GVariant instance.
+ *
* Think of this function as an analogue to g_strdup_printf().
+ *
* The type of the created instance and the arguments that are
* expected by this function are determined by @format_string. See the
* section on <link linkend='gvariant-format-strings'>GVariant Format
* Strings</link>. Please note that the syntax of the format string is
* very likely to be extended in the future.
+ *
* The first character of the format string must not be '*' '?' '@' or
* 'r'; in essence, a new #GVariant must always be constructed by this
* function (and not merely passed through it unmodified).
@@ -29711,12 +31883,18 @@
* @returns: (transfer none): a floating reference to a new #GVariant array
*
* Creates a new #GVariant array from @children.
+ *
+ * @child_type must be non-%NULL if @n_children is zero. Otherwise, the
* child type is determined by inspecting the first element of the
+ * @children array. If @child_type is non-%NULL then it must be a
* definite type.
+ *
* The items of the array are taken from the @children array. No entry
* in the @children array may be %NULL.
+ *
* All items in the array must have the same type, which must be the
* same as @child_type, if given.
+ *
* If the @children are floating references (see g_variant_ref_sink()), the
* new instance takes ownership of them as if via g_variant_ref_sink().
*
@@ -29748,12 +31926,13 @@
/**
* g_variant_new_bytestring:
- * @string: (array zero-terminated=1): a normal nul-terminated string in no particular encoding
+ * @string: (array zero-terminated=1) (element-type guint8): a normal nul-terminated string in no particular encoding
* @returns: (transfer none): a floating reference to a new bytestring #GVariant instance
*
* Creates an array-of-bytes #GVariant with the contents of @string.
* This function is just like g_variant_new_string() except that the
* string need not be valid utf8.
+ *
* The nul terminator character at the end of the string is stored in
* the array.
*
@@ -29769,6 +31948,7 @@
*
* Constructs an array of bytestring #GVariant from the given array of
* strings.
+ *
* If @length is -1 then @strv is %NULL-terminated.
*
* Since: 2.26
@@ -29782,10 +31962,11 @@
* @returns: (transfer none): a floating reference to a new dictionary entry #GVariant
*
* Creates a new dictionary entry #GVariant. @key and @value must be
+ * non-%NULL. @key must be a value of a basic type (ie: not a container).
+ *
* If the @key or @value are floating references (see g_variant_ref_sink()),
* the new instance takes ownership of them as if via g_variant_ref_sink().
*
- * Non-%null. @key must be a value of a basic type (ie: not a container).
* Since: 2.24
*/
@@ -29812,14 +31993,23 @@
* @returns: (transfer none): a new floating #GVariant of type @type
*
* Creates a new #GVariant instance from serialised data.
+ *
+ * @type is the type of #GVariant instance that will be constructed.
* The interpretation of @data depends on knowing the type.
+ *
+ * @data is not modified by this function and must remain valid with an
* unchanging value until such a time as @notify is called with
+ * @user_data. If the contents of @data change before that time then
* the result is undefined.
+ *
* If @data is trusted to be serialised data in normal form then
+ * @trusted should be %TRUE. This applies to serialised data created
* within this process or read from a trusted location on the disk (such
* as a file installed in /usr/lib alongside your application). You
* should set trusted to %FALSE if @data is read from the network, a
* file in the user's home directory, etc.
+ *
+ * @notify will be called with @user_data when @data is no longer
* needed. The exact time of this call is unspecified and might even be
* before this function returns.
*
@@ -29833,6 +32023,7 @@
* @returns: (transfer none): a floating reference to a new handle #GVariant instance
*
* Creates a new handle #GVariant instance.
+ *
* By convention, handles are indexes into an array of file descriptors
* that are sent alongside a D-Bus message. If you're not interacting
* with D-Bus, you probably don't need them.
@@ -29882,10 +32073,12 @@
*
* Depending on if @child is %NULL, either wraps @child inside of a
* maybe container or creates a Nothing instance for the given @type.
+ *
* At least one of @child_type and @child must be non-%NULL.
* If @child_type is non-%NULL then it must be a definite type.
* If they are both non-%NULL then @child_type must be the type
* of @child.
+ *
* If @child is a floating reference (see g_variant_ref_sink()), the new
* instance takes ownership of @child.
*
@@ -29899,6 +32092,7 @@
* @returns: (transfer none): a floating reference to a new object path #GVariant instance
*
* Creates a D-Bus object path #GVariant with the contents of @string.
+ * @string must be a valid D-Bus object path. Use
* g_variant_is_object_path() if you're not sure.
*
* Since: 2.24
@@ -29913,8 +32107,10 @@
*
* Constructs an array of object paths #GVariant from the given array of
* strings.
+ *
* Each string must be a valid #GVariant object path; see
* g_variant_is_object_path().
+ *
* If @length is -1 then @strv is %NULL-terminated.
*
* Since: 2.30
@@ -29929,20 +32125,26 @@
* @format must be a text format #GVariant with one extension: at any
*
* Parses @format and returns the result.
+ *
* point that a value may appear in the text, a '%' character followed
* by a GVariant format string (as per g_variant_new()) may appear. In
* that case, the same arguments are collected from the argument list as
* g_variant_new() would have collected.
+ *
* Consider this simple example:
+ *
* <informalexample><programlisting>
* g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
* </programlisting></informalexample>
+ *
* In the example, the variable argument parameters are collected and
* filled in as if they were part of the original string to produce the
* result of <code>[('one', 1), ('two', 2), ('three', 3)]</code>.
+ *
* This function is intended only to be used with @format as a string
* literal. Any parse error is fatal to the calling process. If you
* want to parse data from untrusted sources, use g_variant_parse().
+ *
* You may not use this function to return, unmodified, a single
* #GVariant pointer from the argument list. ie: @format may not solely
* be anything along the lines of "%*", "%?", "%r", or anything starting
@@ -29957,20 +32159,22 @@
* @returns: a new, usually floating, #GVariant
*
* Parses @format and returns the result.
+ *
* This is the version of g_variant_new_parsed() intended to be used
* from libraries.
+ *
* The return value will be floating if it was a newly created GVariant
* instance. In the case that @format simply specified the collection
+ * of a #GVariant pointer (eg: @format was "%*") then the collected
* #GVariant pointer will be returned unmodified, without adding any
* additional references.
+ *
* In order to behave correctly in all cases it is necessary for the
* calling function to g_variant_ref_sink() the return result before
* returning control to the user that originally provided the pointer.
* At this point, the caller will have their own full reference to the
* result. This can also be done by adding the result to a container,
* or by passing it to another g_variant_new() call.
- *
- * Of a #gvariant pointer (eg: @format was "%*") then the collected
*/
@@ -29980,6 +32184,7 @@
* @returns: (transfer none): a floating reference to a new signature #GVariant instance
*
* Creates a D-Bus type signature #GVariant with the contents of
+ * @string. @string must be a valid D-Bus type signature. Use
* g_variant_is_signature() if you're not sure.
*
* Since: 2.24
@@ -29993,6 +32198,8 @@
*
* Creates a string #GVariant with the contents of @string.
*
+ * @string must be valid utf8.
+ *
* Since: 2.24
*/
@@ -30005,6 +32212,7 @@
*
* Constructs an array of strings #GVariant from the given array of
* strings.
+ *
* If @length is -1 then @strv is %NULL-terminated.
*
* Since: 2.24
@@ -30019,7 +32227,10 @@
*
* Creates a new tuple #GVariant out of the items in @children. The
* type is determined from the types of @children. No entry in the
+ * @children array may be %NULL.
+ *
* If @n_children is 0 then the unit tuple is constructed.
+ *
* If the @children are floating references (see g_variant_ref_sink()), the
* new instance takes ownership of them as if via g_variant_ref_sink().
*
@@ -30070,20 +32281,29 @@
* This function is intended to be used by libraries based on
* #GVariant that want to provide g_variant_new()-like functionality
* to their users.
+ *
* The API is more general than g_variant_new() to allow a wider range
* of possible uses.
+ *
+ * @format_string must still point to a valid format string, but it only
* needs to be nul-terminated if @endptr is %NULL. If @endptr is
* non-%NULL then it is updated to point to the first character past the
* end of the format string.
+ *
+ * @app is a pointer to a #va_list. The arguments, according to
+ * @format_string, are collected from this #va_list and the list is left
* pointing to the argument following the last.
+ *
* These two generalisations allow mixing of multiple calls to
* g_variant_new_va() and g_variant_get_va() within a single actual
* varargs call by the user.
+ *
* The return value will be floating if it was a newly created GVariant
* instance (for example, if the format string was "(ii)"). In the case
* that the format_string was '*', '?', 'r', or a format starting with
* '@' then the collected #GVariant pointer will be returned unmodified,
* without adding any additional references.
+ *
* In order to behave correctly in all cases it is necessary for the
* calling function to g_variant_ref_sink() the return result before
* returning control to the user that originally provided the pointer.
@@ -30102,6 +32322,7 @@
*
* Boxes @value. The result is a #GVariant instance representing a
* variant containing the original value.
+ *
* If @child is a floating reference (see g_variant_ref_sink()), the new
* instance takes ownership of @child.
*
@@ -30119,25 +32340,33 @@
* @Returns: a reference to a #GVariant, or %NULL
*
* Parses a #GVariant from a text representation.
+ *
* A single #GVariant is parsed from the content of @text.
+ *
* The format is described <link linkend='gvariant-text'>here</link>.
+ *
* The memory at @limit will never be accessed and the parser behaves as
* if the character at @limit is the nul terminator. This has the
* effect of bounding @text.
+ *
* If @endptr is non-%NULL then @text is permitted to contain data
* following the value that this function parses and @endptr will be
* updated to point to the first character past the end of the text
* parsed by this function. If @endptr is %NULL and there is extra data
* then an error is returned.
+ *
* If @type is non-%NULL then the value will be parsed to have that
* type. This may result in additional parse errors (in the case that
* the parsed value doesn't fit the type) but may also result in fewer
* errors (in the case that the type would have been ambiguous, such as
* with empty arrays).
+ *
* In the event that the parsing is successful, the resulting #GVariant
* is returned.
+ *
* In case of any error, %NULL will be returned. If @error is non-%NULL
* then it will be set to reflect the error that occured.
+ *
* Officially, the language understood by the parser is "any string
* produced by g_variant_print()".
*/
@@ -30150,7 +32379,9 @@
* @returns: (transfer full): a newly-allocated string holding the result.
*
* Pretty-prints @value in the format understood by g_variant_parse().
+ *
* The format is described <link linkend='gvariant-text'>here</link>.
+ *
* If @type_annotate is %TRUE, then type information is included in
* the output.
*/
@@ -30164,6 +32395,7 @@
* @returns: a #GString containing the string
*
* Behaves as g_variant_print(), but operates on a #GString.
+ *
* If @string is non-%NULL then it is appended to and returned. Else,
* a new empty #GString is allocated and it is returned.
*
@@ -30190,14 +32422,17 @@
* #GVariant uses a floating reference count system. All functions with
* names starting with <literal>g_variant_new_</literal> return floating
* references.
+ *
* Calling g_variant_ref_sink() on a #GVariant with a floating reference
* will convert the floating reference into a full reference. Calling
* g_variant_ref_sink() on a non-floating #GVariant results in an
* additional normal reference being added.
+ *
* In other words, if the @value is floating, then this call "assumes
* ownership" of the floating reference, converting it to a normal
* reference. If the @value is not floating, then this call adds a
* new normal reference increasing the reference count by one.
+ *
* All calls that result in a #GVariant instance being inserted into a
* container will call g_variant_ref_sink() on the instance. This means
* that if the value was just created (and has only its floating
@@ -30218,9 +32453,11 @@
*
* Stores the serialised form of @value at @data. @data should be
* large enough. See g_variant_get_size().
+ *
* The stored data is in machine native byte order but may not be in
* fully-normalised form if read from an untrusted source. See
* g_variant_get_normal_form() for a solution.
+ *
* This function is approximately O(n) in the size of @data.
*
* Since: 2.24
@@ -30233,23 +32470,29 @@
* @returns: the same @value
*
* If @value is floating, sink it. Otherwise, do nothing.
+ *
* Typically you want to use g_variant_ref_sink() in order to
* automatically do the correct thing with respect to floating or
* non-floating references, but there is one specific scenario where
* this function is helpful.
+ *
* The situation where this function is helpful is when creating an API
* that allows the user to provide a callback function that returns a
* #GVariant. We certainly want to allow the user the flexibility to
* return a non-floating reference from this callback (for the case
* where the value that is being returned already exists).
+ *
* At the same time, the style of the #GVariant API makes it likely that
* for newly-created #GVariant instances, the user can be saved some
* typing if they are allowed to return a #GVariant with a floating
* reference.
+ *
* Using this function on the return value of the user's callback allows
* the user to do whichever is more convenient for them. The caller
+ * will alway receives exactly one full reference to the value: either
* the one that was returned in the first place, or a floating reference
* that has been converted to a full reference.
+ *
* This function has an odd interaction when combined with
* g_variant_ref_sink() running at the same time in another thread on
* the same #GVariant instance. If g_variant_ref_sink() runs first then
@@ -30258,8 +32501,6 @@
* be that the floating reference is converted to a hard reference and
* an additional reference on top of that one is added. It is best to
* avoid this situation.
- *
- * Will alway receives exactly one full reference to the value: either
*/
@@ -30270,6 +32511,7 @@
*
* Makes a copy of a #GVariantType. It is appropriate to call
* g_variant_type_free() on the return value. @type may not be %NULL.
+ *
* Since 2.24
*/
@@ -30280,7 +32522,9 @@
* @returns: (transfer full): the corresponding type string
*
* Returns a newly-allocated copy of the type string corresponding to
+ * @type. The returned string is nul-terminated. It is appropriate to
* call g_free() on the return value.
+ *
* Since 2.24
*/
@@ -30291,7 +32535,9 @@
* @returns: (transfer none): the element type of @type
*
* Determines the element type of an array or maybe type.
+ *
* This function may only be used with array or maybe types.
+ *
* Since 2.24
*/
@@ -30303,13 +32549,16 @@
* @returns: %TRUE if @type1 and @type2 are exactly equal
*
* Compares @type1 and @type2 for equality.
+ *
* Only returns %TRUE if the types are exactly equal. Even if one type
* is an indefinite type and the other is a subtype of it, %FALSE will
* be returned if they are not exactly equal. If you want to check for
* subtypes, use g_variant_type_is_subtype_of().
+ *
* The argument types of @type1 and @type2 are only #gconstpointer to
* allow use with #GHashTable without function pointer casting. For
* both arguments, a valid #GVariantType must be provided.
+ *
* Since 2.24
*/
@@ -30321,14 +32570,19 @@
*
* Determines the first item type of a tuple or dictionary entry
* type.
+ *
* This function may only be used with tuple or dictionary entry types,
* but must not be used with the generic tuple type
* %G_VARIANT_TYPE_TUPLE.
+ *
* In the case of a dictionary entry type, this returns the type of
* the key.
+ *
* %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
+ *
* This call, together with g_variant_type_next() provides an iterator
* interface over tuple and dictionary entry types.
+ *
* Since 2.24
*/
@@ -30340,7 +32594,9 @@
* Frees a #GVariantType that was allocated with
* g_variant_type_copy(), g_variant_type_new() or one of the container
* type constructor functions.
+ *
* In the case that @type is %NULL, this function does nothing.
+ *
* Since 2.24
*/
@@ -30351,7 +32607,9 @@
* @returns: the length of the corresponding type string
*
* Returns the length of the type string corresponding to the given
+ * @type. This function must be used to determine the valid extent of
* the memory region returned by g_variant_type_peek_string().
+ *
* Since 2.24
*/
@@ -30362,9 +32620,11 @@
* @returns: the hash value
*
* Hashes @type.
+ *
* The argument type of @type is only #gconstpointer to allow use with
* #GHashTable without function pointer casting. A valid
* #GVariantType must be provided.
+ *
* Since 2.24
*/
@@ -30376,9 +32636,11 @@
*
* Determines if the given @type is an array type. This is true if the
* type string for @type starts with an 'a'.
+ *
* This function returns %TRUE for any indefinite type for which every
* definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
* example.
+ *
* Since 2.24
*/
@@ -30389,11 +32651,15 @@
* @returns: %TRUE if @type is a basic type
*
* Determines if the given @type is a basic type.
+ *
* Basic types are booleans, bytes, integers, doubles, strings, object
* paths and signatures.
+ *
* Only a basic type may be used as the key of a dictionary entry.
+ *
* This function returns %FALSE for all indefinite types except
* %G_VARIANT_TYPE_BASIC.
+ *
* Since 2.24
*/
@@ -30404,11 +32670,14 @@
* @returns: %TRUE if @type is a container type
*
* Determines if the given @type is a container type.
+ *
* Container types are any array, maybe, tuple, or dictionary
* entry types plus the variant type.
+ *
* This function returns %TRUE for any indefinite type for which every
* definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
* example.
+ *
* Since 2.24
*/
@@ -30418,16 +32687,18 @@
* @type: a #GVariantType
* @returns: %TRUE if @type is definite
*
+ * Determines if the given @type is definite (ie: not indefinite).
+ *
* A type is definite if its type string does not contain any indefinite
* type characters ('*', '?', or 'r').
+ *
* A #GVariant instance may not have an indefinite type, so calling
* this function on the result of g_variant_get_type() will always
* result in %TRUE being returned. Calling this function on an
* indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
* %FALSE being returned.
- * Since 2.24
*
- * Determines if the given @type is definite (ie: not indefinite).
+ * Since 2.24
*/
@@ -30438,9 +32709,11 @@
*
* Determines if the given @type is a dictionary entry type. This is
* true if the type string for @type starts with a '{'.
+ *
* This function returns %TRUE for any indefinite type for which every
* definite subtype is a dictionary entry type --
* %G_VARIANT_TYPE_DICT_ENTRY, for example.
+ *
* Since 2.24
*/
@@ -30452,9 +32725,11 @@
*
* Determines if the given @type is a maybe type. This is true if the
* type string for @type starts with an 'm'.
+ *
* This function returns %TRUE for any indefinite type for which every
* definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
* example.
+ *
* Since 2.24
*/
@@ -30466,9 +32741,11 @@
* @returns: %TRUE if @type is a subtype of @supertype
*
* Checks if @type is a subtype of @supertype.
+ *
* This function returns %TRUE if @type is a subtype of @supertype. All
* types are considered to be subtypes of themselves. Aside from that,
* only indefinite types can have subtypes.
+ *
* Since 2.24
*/
@@ -30481,9 +32758,11 @@
* Determines if the given @type is a tuple type. This is true if the
* type string for @type starts with a '(' or if @type is
* %G_VARIANT_TYPE_TUPLE.
+ *
* This function returns %TRUE for any indefinite type for which every
* definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
* example.
+ *
* Since 2.24
*/
@@ -30494,6 +32773,7 @@
* @returns: %TRUE if @type is the variant type
*
* Determines if the given @type is the variant type.
+ *
* Since 2.24
*/
@@ -30504,9 +32784,11 @@
* @returns: (transfer none): the key type of the dictionary entry
*
* Determines the key type of a dictionary entry type.
+ *
* This function may only be used with a dictionary entry type. Other
* than the additional restriction, this call is equivalent to
* g_variant_type_first().
+ *
* Since 2.24
*/
@@ -30518,11 +32800,14 @@
*
* Determines the number of items contained in a tuple or
* dictionary entry type.
+ *
* This function may only be used with tuple or dictionary entry types,
* but must not be used with the generic tuple type
* %G_VARIANT_TYPE_TUPLE.
+ *
* In the case of a dictionary entry type, this function will always
* return 2.
+ *
* Since 2.24
*/
@@ -30535,6 +32820,7 @@
* Creates a new #GVariantType corresponding to the type string given
* by @type_string. It is appropriate to call g_variant_type_free() on
* the return value.
+ *
* It is a programmer error to call this function with an invalid type
* string. Use g_variant_type_string_is_valid() if you are unsure.
*
@@ -30549,7 +32835,9 @@
*
* Constructs the type corresponding to an array of elements of the
* type @type.
+ *
* It is appropriate to call g_variant_type_free() on the return value.
+ *
* Since 2.24
*/
@@ -30562,7 +32850,9 @@
*
* Constructs the type corresponding to a dictionary entry with a key
* of type @key and a value of type @value.
+ *
* It is appropriate to call g_variant_type_free() on the return value.
+ *
* Since 2.24
*/
@@ -30574,7 +32864,9 @@
*
* Constructs the type corresponding to a maybe instance containing
* type @type or Nothing.
+ *
* It is appropriate to call g_variant_type_free() on the return value.
+ *
* Since 2.24
*/
@@ -30586,7 +32878,12 @@
* @returns: (transfer full): a new tuple #GVariantType
*
* Constructs a new tuple type, from @items.
+ *
+ * @length is the number of items in @items, or -1 to indicate that
+ * @items is %NULL-terminated.
+ *
* It is appropriate to call g_variant_type_free() on the return value.
+ *
* Since 2.24
*/
@@ -30598,11 +32895,16 @@
*
* Determines the next item type of a tuple or dictionary entry
* type.
+ *
+ * @type must be the result of a previous call to
* g_variant_type_first() or g_variant_type_next().
+ *
* If called on the key type of a dictionary entry then this call
* returns the value type. If called on the value type of a dictionary
* entry then this call returns %NULL.
+ *
* For tuples, %NULL is returned when @type is the last item in a tuple.
+ *
* Since 2.24
*/
@@ -30615,7 +32917,9 @@
* Returns the type string corresponding to the given @type. The
* result is not nul-terminated; in order to determine its length you
* must call g_variant_type_get_string_length().
+ *
* To get a nul-terminated string, see g_variant_type_dup_string().
+ *
* Since 2.24
*/
@@ -30628,6 +32932,7 @@
* Checks if @type_string is a valid GVariant type string. This call is
* equivalent to calling g_variant_type_string_scan() and confirming
* that the following character is a nul terminator.
+ *
* Since 2.24
*/
@@ -30635,18 +32940,21 @@
/**
* g_variant_type_string_scan:
* @string: a pointer to any string
- * @limit: the end of @string, or %NULL
- * @endptr: location to store the end pointer, or %NULL
+ * @limit: (allow-none): the end of @string, or %NULL
+ * @endptr: (out) (allow-none): location to store the end pointer, or %NULL
* @returns: %TRUE if a valid type string was found
*
* Scan for a single complete and valid GVariant type string in @string.
* The memory pointed to by @limit (or bytes beyond it) is never
* accessed.
+ *
* If a valid type string is found, @endptr is updated to point to the
* first character past the end of the string that was found and %TRUE
* is returned.
+ *
* If there is no valid type string starting at @string, or if the type
* string does not end before @limit then %FALSE is returned.
+ *
* For the simple case of checking if a string is a valid type string,
* see g_variant_type_string_is_valid().
*
@@ -30660,7 +32968,9 @@
* @returns: (transfer none): the value type of the dictionary entry
*
* Determines the value type of a dictionary entry type.
+ *
* This function may only be used with a dictionary entry type.
+ *
* Since 2.24
*/
@@ -30730,16 +33040,21 @@
* A safer form of the standard vsprintf() function. The output is guaranteed
* to not exceed @n characters (including the terminating nul character), so
* it is easy to ensure that a buffer overflow cannot occur.
+ *
* See also g_strdup_vprintf().
+ *
* In versions of GLib prior to 1.2.3, this function may return -1 if the
* output was truncated, and the truncated string may not be nul-terminated.
* In versions prior to 1.3.12, this function returns the length of the output
* string.
+ *
* The return value of g_vsnprintf() conforms to the vsnprintf() function
* as standardized in ISO C99. Note that this is different from traditional
* vsnprintf(), which returns the length of the output string.
+ *
* The format string may contain positional parameters, as specified in
* the Single Unix Specification.
+ *
* was large enough.
*
* Returns: the number of bytes which would be produced if the buffer
@@ -30761,6 +33076,75 @@
/**
+ * g_wakeup_acknowledge:
+ * @wakeup: a #GWakeup
+ *
+ * Acknowledges receipt of a wakeup signal on @wakeup.
+ *
+ * You must call this after @wakeup polls as ready. If not, it will
+ * continue to poll as ready until you do so.
+ *
+ * If you call this function and @wakeup is not signaled, nothing
+ * happens.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_wakeup_free:
+ * @wakeup: a #GWakeup
+ *
+ * Frees @wakeup.
+ *
+ * You must not currently be polling on the #GPollFD returned by
+ * g_wakeup_get_pollfd(), or the result is undefined.
+ */
+
+
+/**
+ * g_wakeup_get_pollfd:
+ * @wakeup: a #GWakeup
+ * @poll_fd: a #GPollFD
+ *
+ * Prepares a @poll_fd such that polling on it will succeed when
+ * g_wakeup_signal() has been called on @wakeup.
+ *
+ * @poll_fd is valid until @wakeup is freed.
+ *
+ * Since: 2.30
+ */
+
+
+/**
+ * g_wakeup_new:
+ *
+ * Creates a new #GWakeup.
+ *
+ * You should use g_wakeup_free() to free it when you are done.
+ *
+ * Returns: a new #GWakeup
+ * Since: 2.30
+ */
+
+
+/**
+ * g_wakeup_signal:
+ * @wakeup: a #GWakeup
+ *
+ * Signals @wakeup.
+ *
+ * Any future (or present) polling on the #GPollFD returned by
+ * g_wakeup_get_pollfd() will immediately succeed until such a time as
+ * g_wakeup_acknowledge() is called.
+ *
+ * This function is safe to call from a UNIX signal handler.
+ *
+ * Since: 2.30
+ */
+
+
+/**
* g_warn_if_fail:
* @expr: the expression to check
*
@@ -30800,10 +33184,13 @@
* @dll_name: The name of a DLL that a package provides in UTF-8, or %NULL.
*
* Try to determine the installation directory for a software package.
+ *
* This function is deprecated. Use
* g_win32_get_package_installation_directory_of_module() instead.
+ *
* The use of @package is deprecated. You should always pass %NULL. A
* warning is printed if non-NULL is passed as @package.
+ *
* The original intended use of @package was for a short identifier of
* the package, typically the same identifier as used for
* <literal>GETTEXT_PACKAGE</literal> in software configured using GNU
@@ -30811,15 +33198,19 @@
* value <literal>#InstallationDirectory</literal> in the key
* <literal>#HKLM\Software\ package</literal>, and if that value
* exists and is a string, returns that.
+ *
* It is strongly recommended that packagers of GLib-using libraries
* for Windows do not store installation paths in the Registry to be
* used by this function as that interfers with having several
* parallel installations of the library. Enabling multiple
* installations of different versions of some GLib-using library, or
* GLib itself, is desirable for various reasons.
+ *
* For this reason it is recommeded to always pass %NULL as
+ * @package to this function, to avoid the temptation to use the
* Registry. In version 2.20 of GLib the @package parameter
* will be ignored and this function won't look in the Registry at all.
+ *
* If @package is %NULL, or the above value isn't found in the
* Registry, but @dll_name is non-%NULL, it should name a DLL loaded
* into the current process. Typically that would be the name of the
@@ -30828,11 +33219,16 @@
* was loaded from. If that directory's last component is "bin" or
* "lib", the parent directory is returned, otherwise the directory
* itself. If that DLL isn't loaded, the function proceeds as if
+ * @dll_name was %NULL.
+ *
* If both @package and @dll_name are %NULL, the directory from where
* the main executable of the process was loaded is used instead in
* the same way as above.
+ *
+ * @package. The string is in the GLib file name encoding,
* i.e. UTF-8. The return value should be freed with g_free() when not
* needed any longer. If the function fails %NULL is returned.
+ *
* g_win32_get_package_installation_directory_of_module() instead.
*
* Returns: a string containing the installation directory for
@@ -30847,10 +33243,14 @@
* This function tries to determine the installation directory of a
* software package based on the location of a DLL of the software
* package.
+ *
+ * @hmodule should be the handle of a loaded DLL or %NULL. The
* function looks up the directory that DLL was loaded from. If
+ * @hmodule is NULL, the directory the main executable of the current
* process is looked up. If that directory's last component is "bin"
* or "lib", its parent directory is returned, otherwise the directory
* itself.
+ *
* It thus makes sense to pass only the handle to a "public" DLL of a
* software package to this function, as such DLLs typically are known
* to be installed in a "bin" or occasionally "lib" subfolder of the
@@ -30858,10 +33258,12 @@
* or plugin variety are often located in more private locations
* deeper down in the tree, from which it is impossible for GLib to
* deduce the root of the package installation.
+ *
* The typical use case for this function is to have a DllMain() that
* saves the handle for the DLL. Then when code in the DLL needs to
* construct names of files in the installation tree it calls this
* function passing the DLL handle.
+ *
* the software package @hmodule is from. The string is in the GLib
* file name encoding, i.e. UTF-8. The return value should be freed
* with g_free() when not needed any longer. If the function fails
@@ -30881,16 +33283,20 @@
* This function is deprecated. Use
* g_win32_get_package_installation_directory_of_module() and
* g_build_filename() instead.
+ *
* Returns a newly-allocated string containing the path of the
* subdirectory @subdir in the return value from calling
* g_win32_get_package_installation_directory() with the @package and
+ * @dll_name parameters. See the documentation for
* g_win32_get_package_installation_directory() for more details. In
* particular, note that it is deprecated to pass anything except NULL
* as @package.
+ *
* the installation directory of @package. The returned string is in
* the GLib file name encoding, i.e. UTF-8. The return value should be
* freed with g_free() when no longer needed. If something goes wrong,
* %NULL is returned.
+ *
* g_win32_get_package_installation_directory_of_module() instead, and
* then construct a subdirectory pathname with g_build_filename().
*
@@ -30937,12 +33343,14 @@
* @utf8filename: a UTF-8 encoded filename.
*
* Converts a filename from UTF-8 to the system codepage.
+ *
* On NT-based Windows, on NTFS file systems, file names are in
* Unicode. It is quite possible that Unicode file names contain
* characters not representable in the system codepage. (For instance,
* Greek or Cyrillic characters on Western European or US Windows
* installations, or various less common CJK characters on CJK Windows
* installations.)
+ *
* In such a case, and if the filename refers to an existing file, and
* the file system stores alternate short (8.3) names for directory
* entries, the short form of the filename is returned. Note that the
@@ -30950,8 +33358,10 @@
* Unicode name has very short pathname components containing
* non-ASCII characters. If no system codepage name for the file is
* possible, %NULL is returned.
+ *
* The return value is dynamically allocated and should be freed with
* g_free() when no longer needed.
+ *
* failure and lack of short names.
*
* Returns: The converted filename, or %NULL on conversion
@@ -30979,15 +33389,18 @@
* a check that the library in use is compatible with
* the version of GLib the application or module was compiled
* against.
+ *
+ * Compatibility is defined by two things: first the version
* of the running library is newer than the version
+ * @required_major required_minor required_micro Second
* the running library must be binary compatible with the
* version @required_major required_minor required_micro
* (same major version.)
+ *
* given version, or a string describing the version mismatch.
* The returned string is owned by GLib and must not be modified
* or freed.
*
- * Compatibility is defined by two things: first the version
* Returns: %NULL if the GLib library is compatible with the
* Since: 2.6
*/
@@ -31023,6 +33436,7 @@
* This function is a variant of glib_gettext() which supports
* a disambiguating message context. See g_dpgettext() for full
* details.
+ *
* This is an internal function and should only be used by
* the internals of glib (such as libgio).
*
@@ -31035,11 +33449,14 @@
*
* A type which can hold any UTF-32 or UCS-4 character code,
* also known as a Unicode code point.
+ *
* If you want to produce the UTF-8 representation of a #gunichar,
* use g_ucs4_to_utf8(). See also g_utf8_to_ucs4() for the reverse
* process.
+ *
* To print/scan values of this type as integer, use
* %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
+ *
* The notation to express a Unicode code point in running text is
* as a hexadecimal number with four to six digits and uppercase
* letters, prefixed by the string "U+". Leading zeros are omitted,
@@ -31047,6 +33464,7 @@
* For example, "U+0041 LATIN CAPITAL LETTER A". To print a code point
* in the U+-notation, use the format string "U+%04"G_GINT32_FORMAT"X".
* To scan, use the format string "U+%06"G_GINT32_FORMAT"X".
+ *
* |[
* gunichar c;
* sscanf ("U+0041", "U+%06"G_GINT32_FORMAT"X", &c)
@@ -31064,8 +33482,10 @@
* the BMP as pairs of 16bit numbers. Surrogate pairs cannot be stored
* in a single gunichar2 field, but all GLib functions accepting gunichar2
* arrays will correctly interpret surrogate pairs.</footnote>.
+ *
* To print/scan values of this type to/from text you need to convert
* to/from UTF-8, using g_utf16_to_utf8()/g_utf8_to_utf16().
+ *
* To print/scan values of this type as integer, use
* %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
*/
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index b254b24..974afab 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -95,6 +95,7 @@
*
* Flags to be passed to g_object_bind_property() or
* g_object_bind_property_full().
+ *
* This enumeration can be extended at later date.
*
* Since: 2.26
@@ -111,6 +112,7 @@
* A function to be called to transform the source property of @source
* from @source_value into the target property of @target
* using @target_value.
+ *
* otherwise
*
* Returns: %TRUE if the transformation was successful, and %FALSE
@@ -200,6 +202,7 @@
*
* The hashing algorithm to be used by #GChecksum when performing the
* digest of some data.
+ *
* Note that the #GChecksumType enumeration may be extended at a later
* date to include new hashing algorithm types.
*
@@ -270,6 +273,7 @@
* is performed for class initialization of derived types as well.
* An example may help to correspond the intend of the different class
* initializers:
+ *
* |[
* typedef struct {
* GObjectClass parent_class;
@@ -291,6 +295,7 @@
* {
* class->static_integer = 42;
* }
+ *
* typedef struct {
* TypeAClass parent_class;
* gfloat static_float;
@@ -493,6 +498,17 @@
/**
+ * GHmac:
+ *
+ * An opaque structure representing a HMAC operation.
+ * To create a new GHmac, use g_hmac_new(). To free
+ * a GHmac, use g_hmac_unref().
+ *
+ * Since: 2.30
+ */
+
+
+/**
* GIconv:
*
* The <structname>GIConv</structname> struct wraps an
@@ -573,6 +589,7 @@
*
* Checks the version of the GLib library that is being compiled
* against.
+ *
* <example>
* <title>Checking the version of the GLib library</title>
* <programlisting>
@@ -580,7 +597,9 @@
* g_error ("GLib version 1.2.0 or above is needed");
* </programlisting>
* </example>
+ *
* See glib_check_version() for a runtime check.
+ *
* is the same as or newer than the passed-in version.
*
* Returns: %TRUE if the version of the GLib header files
@@ -622,6 +641,7 @@
*
* A parse context is used to parse a stream of bytes that
* you expect to contain marked-up text.
+ *
* See g_markup_parse_context_new(), #GMarkupParser, and so
* on for more details.
*/
@@ -707,6 +727,7 @@
* doesn't guarantee that the value of the property has actually
* changed, it may also be emitted when the setter for the property
* is called to reinstate the previous value.
+ *
* This signal is typically used to obtain change notification for a
* single property, by specifying the property name as a detail in the
* g_signal_connect() call, like this:
@@ -724,7 +745,7 @@
/**
* GObjectClass:
* @g_type_class: the parent class
- * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons.
+ * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the @constructor of the parent class. Overriding @constructor should be rarely needed, e.g. to handle construct properties, or to implement singletons.
* @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system.
* @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties.
* @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class.
@@ -734,16 +755,19 @@
* @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation.
*
* The class structure for the <structname>GObject</structname> type.
+ *
* <example>
* <title>Implementing singletons using a constructor</title>
* <programlisting>
* static MySingleton *the_singleton = NULL;
+ *
* static GObject*
* my_singleton_constructor (GType type,
* guint n_construct_params,
* GObjectConstructParam *construct_params)
* {
* GObject *object;
+ *
* if (!the_singleton)
* {
* object = G_OBJECT_CLASS (parent_class)->constructor (type,
@@ -753,6 +777,7 @@
* }
* else
* object = g_object_ref (G_OBJECT (the_singleton));
+ *
* return object;
* }
* </programlisting></example>
@@ -816,8 +841,7 @@
* options expect to find. If an option expects an extra argument, it
* can be specified in several ways; with a short option:
* <option>-x arg</option>, with a long option: <option>--name arg</option>
- *
- * Or combined in a single argument: <option>--name=arg</option>.
+ * or combined in a single argument: <option>--name=arg</option>.
*/
@@ -830,6 +854,7 @@
*
* The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
* options.
+ *
* occurred, in which case @error should be set with g_set_error()
*
* Returns: %TRUE if the option was successfully parsed, %FALSE if an error
@@ -901,6 +926,7 @@
*
* A <structname>GOptionGroup</structname> struct defines the options in a single
* group. The struct has only private fields and should not be directly accessed.
+ *
* All options in a group share the same translation function. Libraries which
* need to parse commandline options are expected to provide a function for
* getting a <structname>GOptionGroup</structname> holding their options, which
@@ -916,6 +942,7 @@
* @error: A return location for error details
*
* The type of function that can be called before and after parsing.
+ *
* occurred, in which case @error should be set with g_set_error()
*
* Returns: %TRUE if the function completed successfully, %FALSE if an error
@@ -1262,6 +1289,7 @@
* GPid:
*
* A type which is used to hold a process identification.
+ *
* On UNIX, processes are identified by a process id (an integer),
* while Windows uses process handles (which are pointers).
*/
@@ -1285,6 +1313,7 @@
*
* Specifies the type of function passed to g_main_context_set_poll_func().
* The semantics of the function should match those of the poll() system call.
+ *
* reported, or -1 if an error occurred.
*
* Returns: the number of #GPollFD elements which have events or errors
@@ -1330,8 +1359,7 @@
* @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
* @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set.
* @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern.
- * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes.
- * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
+ * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
* @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches.
* @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched.
* @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
@@ -1404,6 +1432,7 @@
* Specifies the type of the function passed to g_regex_replace_eval().
* It is called for each occurance of the pattern in the string passed
* to g_regex_replace_eval(), and it should append the replacement to
+ * @result.
*
* Returns: %FALSE to continue the replacement process, %TRUE to stop it
* Since: 2.14
@@ -1441,6 +1470,7 @@
* creation time, if it is left %NULL, no accumulation of callback return
* values is performed. The return value of signal emissions is then the
* value returned by the last callback.
+ *
* should be aborted. Returning %FALSE means to abort the
* current emission and %TRUE is returned for continuation.
*
@@ -1469,7 +1499,9 @@
* A simple function pointer to get invoked when the signal is emitted. This
* allows you to tie a hook to the signal type, so that it will trap all
* emissions of that signal, from any object.
+ *
* You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
+ *
* hook is disconnected (and destroyed).
*
* Returns: whether it wants to stay connected. If it returns %FALSE, the signal
@@ -1527,7 +1559,7 @@
* @signal_flags: The signal flags as passed in to g_signal_new().
* @return_type: The return type for user callbacks.
* @n_params: The number of parameters that user callbacks take.
- * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting>
+ * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> @return_type callback (#gpointer data1, [#param_types param_names,] #gpointer data2); </programlisting>
*
* A structure holding in-depth information for a specific signal. It is
* filled in by the g_signal_query() function.
@@ -1546,10 +1578,9 @@
* GSourceCallbackFuncs:
* @ref: Called when a reference is added to the callback object
* @unref: Called when a reference to the callback object is dropped
- * @get: Called to extract the callback function and data from the callback object.
+ * @get: Called to extract the callback function and data from the callback object. The <structname>GSourceCallbackFuncs</structname> struct contains functions for managing callback objects.
+ *
*
- * The <structname>GSourceCallbackFuncs</structname> struct contains
- * functions for managing callback objects.
*/
@@ -1574,22 +1605,25 @@
/**
* GSourceFuncs:
- * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the
+ * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the @timeout_ values returned which were >= 0.
* @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here.
* @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source.
* @finalize: Called when the source is finalized.
*
* The <structname>GSourceFuncs</structname> struct contains a table of
* functions used to handle event sources in a generic manner.
+ *
* For idle sources, the prepare and check functions always return %TRUE
* to indicate that the source is always ready to be processed. The prepare
* function also returns a timeout value of 0 to ensure that the poll() call
* doesn't block (since that would be time wasted which could have been spent
* running the idle function).
+ *
* For timeout sources, the prepare and check functions both return %TRUE
* if the timeout interval has expired. The prepare function also returns
* a timeout value to ensure that the poll() call doesn't block too long
* and miss the next timeout.
+ *
* For file descriptor sources, the prepare function typically returns %FALSE,
* since it must wait until poll() has been called before it knows whether
* any events need to be processed. It sets the returned timeout to -1 to
@@ -1608,12 +1642,15 @@
* is called in the child after GLib has performed all the setup it plans
* to perform but before calling exec(). On POSIX actions taken in this
* function will thus only affect the child, not the parent.
+ *
* Note that POSIX allows only async-signal-safe functions (see signal(7))
* to be called in the child between fork() and exec(), which drastically
* limits the usefulness of child setup functions.
+ *
* Also note that modifying the environment from the child setup function
* may not have the intended effect, since it will get overridden by
* a non-%NULL @env argument to the <literal>g_spawn...</literal> functions.
+ *
* On Windows the function is called in the parent. Its usefulness on
* Windows is thus questionable. In many cases executing the child setup
* function in the parent can have ill effects, and you should be very
@@ -1710,7 +1747,9 @@
* @G_TIME_TYPE_UNIVERSAL: the time is in UTC
*
* Disambiguates a given time in two ways.
+ *
* First, specifies if the given time is in universal or local time.
+ *
* Second, if the time is in local time, specifies if it is local
* standard time or local daylight time. This is important for the case
* where the same local time occurs twice (during daylight savings time
@@ -1736,6 +1775,7 @@
*
* The type of functions which are used to translate user-visible
* strings, for <option>--help</option> output.
+ *
* The returned string is owned by GLib and must not be freed.
*
* Returns: a translation of the string for the current locale.
@@ -1779,9 +1819,11 @@
* being freed. You should not call g_type_class_unref() from a
* #GTypeClassCacheFunc function to prevent infinite recursion, use
* g_type_class_unref_uncached() instead.
+ *
* The functions have to check the class id passed in to figure
* whether they actually want to cache the class of this type, since all
* classes are routed through the same #GTypeClassCacheFunc chain.
+ *
* called, %FALSE to continue.
*
* Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
@@ -1979,12 +2021,12 @@
* GTypeValueTable:
* @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]|
* @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]|
- * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
+ * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of @src_value into @dest_value in a way, that even after @src_value has been freed, the contents of @dest_value remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
* @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]|
* @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i
' needs to be used, and for collection of floats 'd'.
- * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_p
ointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour i
s undefined.
+ * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup @value similar to value_init(); e.g. for a string value that does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. @n_collect_values is exactly the string length of @collect_format, and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. @collect_flags is an argument provided as a hint by the caller. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @valu
e lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementatio
n for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, h
owever, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined.
* @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations.
- * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as
NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
+ * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. @n_collect_values equals the string length of @lcopy_format, and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (
!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
*
* The #GTypeValueTable provides the functions required by the #GValue implementation,
* to serve as a container for values of a type.
@@ -2032,10 +2074,12 @@
* @G_UNICODE_BREAK_CLOSE_PARANTHESIS: Closing Parenthesis (CP). Since 2.28
*
* These are the possible line break classifications.
+ *
* The five Hangul types were added in Unicode 4.1, so, has been
* introduced in GLib 2.10. Note that new types may be added in the future.
* Applications should be ready to handle unknown values.
* They may be regarded as %G_UNICODE_BREAK_UNKNOWN.
+ *
* See <ulink url="http://www.unicode.org/unicode/reports/tr14/";>http://www.unicode.org/unicode/reports/tr14/</ulink>.
*/
@@ -2129,11 +2173,11 @@
* @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28
* @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28
*
- * a value never returned from g_unichar_get_script()
* The #GUnicodeScript enumeration identifies different writing
* systems. The values correspond to the names as defined in the
* Unicode standard. The enumeration has been added in GLib 2.14,
* and is interchangeable with #PangoScript.
+ *
* Note that new types may be added in the future. Applications
* should be ready to handle unknown values.
* See <ulink
@@ -2196,6 +2240,7 @@
* These are logical ids for special directories which are defined
* depending on the platform used. You should use g_get_user_special_dir()
* to retrieve the full path associated to the logical id.
+ *
* The #GUserDirectory enumeration can be extended at later date. Not
* every platform has a directory for every logical id in this
* enumeration.
@@ -2208,14 +2253,13 @@
* GValue:
*
* An opaque structure used to hold different types of values.
+ * The data within the structure has protected scope: it is accessible only
* to functions within a #GTypeValueTable structure, or implementations of
* the g_value_*() API. That is, code portions which implement new fundamental
* types.
* #GValue users cannot make any assumptions about how data is stored
* within the 2 element @data union, and the @g_type member should
* only be accessed through the G_VALUE_TYPE() macro.
- *
- * The data within the structure has protected scope: it is accessible only
*/
@@ -2242,6 +2286,7 @@
* GVariantType:
*
* A type in the GVariant type system.
+ *
* Two types may not be compared by value; use g_variant_type_equal() or
* g_variant_type_is_subtype_of(). May be copied using
* g_variant_type_copy() and freed using g_variant_type_free().
@@ -2282,6 +2327,7 @@
* G_BREAKPOINT:
*
* Inserts a breakpoint instruction into the code.
+ *
* On x86 and alpha systems this is implemented as a soft interrupt
* and on other architectures it raises a %SIGTRAP signal.
*/
@@ -2312,6 +2358,8 @@
*
* Check if the closure still needs a marshaller. See g_closure_set_marshal().
*
+ * @closure.
+ *
* Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
*/
@@ -2418,6 +2466,7 @@
* A convenience macro for dynamic type implementations, which declares a
* class initialization function, an instance initialization function (see
* #GTypeInfo for information about these) and a static variable named
+ * @t_n<!-- -->_parent_class pointing to the parent class. Furthermore,
* it defines a <function>*_get_type()</function> and a static
* <function>*_register_type()</function> function for use in your
* <function>module_init()</function>.
@@ -2437,6 +2486,7 @@
*
* A more general version of G_DEFINE_DYNAMIC_TYPE() which
* allows to specify #GTypeFlags and custom code.
+ *
* |[
* G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
* gtk_gadget,
@@ -2450,18 +2500,22 @@
* static void gtk_gadget_init (GtkGadget *self);
* static void gtk_gadget_class_init (GtkGadgetClass *klass);
* static void gtk_gadget_class_finalize (GtkGadgetClass *klass);
+ *
* static gpointer gtk_gadget_parent_class = NULL;
* static GType gtk_gadget_type_id = 0;
+ *
* static void gtk_gadget_class_intern_init (gpointer klass)
* {
* gtk_gadget_parent_class = g_type_class_peek_parent (klass);
* gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
+ *
* GType
* gtk_gadget_get_type (void)
* {
* return gtk_gadget_type_id;
* }
+ *
* static void
* gtk_gadget_register_type (GTypeModule *type_module)
* {
@@ -2504,6 +2558,7 @@
* A convenience macro for #GTypeInterface definitions, which declares
* a default vtable initialization function and defines a *_get_type()
* function.
+ *
* The macro expects the interface initialization function to have the
* name <literal>t_n ## _default_init</literal>, and the interface
* structure to have the name <literal>TN ## Interface</literal>.
@@ -2581,6 +2636,7 @@
*
* The most general convenience macro for type implementations, on which
* G_DEFINE_TYPE(), etc are based.
+ *
* |[
* G_DEFINE_TYPE_EXTENDED (GtkGadget,
* gtk_gadget,
@@ -2599,6 +2655,7 @@
* gtk_gadget_parent_class = g_type_class_peek_parent (klass);
* gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
+ *
* GType
* gtk_gadget_get_type (void)
* {
@@ -2712,6 +2769,7 @@
* A convenience macro to ease interface addition in the @_C_ section
* of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
* See G_DEFINE_TYPE_EXTENDED() for an example.
+ *
* Note that this macro can only be used together with the G_DEFINE_TYPE_*
* macros, since it depends on variable names from those macros.
*
@@ -2727,6 +2785,7 @@
* A convenience macro to ease interface addition in the @_C_ section
* of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED()
* for an example.
+ *
* Note that this macro can only be used together with the
* G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
* names from that macro.
@@ -3091,6 +3150,7 @@
* @node: a #GNode
*
* Returns %TRUE if a #GNode is a leaf node.
+ *
* (i.e. it has no children)
*
* Returns: %TRUE if the #GNode is a leaf node
@@ -3102,6 +3162,7 @@
* @node: a #GNode
*
* Returns %TRUE if a #GNode is the root of a tree.
+ *
* (i.e. it has no parent or siblings)
*
* Returns: %TRUE if the #GNode is the root of a tree
@@ -3131,6 +3192,7 @@
* @class: a valid #GObjectClass
*
* Return the name of a class structure's type.
+ *
* should not be freed.
*
* Returns: Type name of @class. The string is owned by the type system and
@@ -3172,6 +3234,7 @@
* @object: Object to return the type name for.
*
* Get the name of an object's type.
+ *
* should not be freed.
*
* Returns: Type name of @object. The string is owned by the type system and
@@ -3206,6 +3269,8 @@
* otherwise be left in <literal>argv</literal>. The option must be of type
* %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
* or %G_OPTION_ARG_FILENAME_ARRAY.
+ *
+ *
* Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
* for leftover arguments has the advantage that GOption takes care of
* necessary encoding conversions for strings or filenames.
@@ -3471,6 +3536,7 @@
* G_PARAM_STATIC_STRINGS:
*
* #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
+ *
* Since 2.13.0
*/
@@ -3487,6 +3553,7 @@
* G_PRIORITY_DEFAULT:
*
* Use this for default priority event sources.
+ *
* In GLib this priority is used when adding timeout functions
* with g_timeout_add(). In GDK this priority is used for events
* from the X server.
@@ -3497,6 +3564,7 @@
* G_PRIORITY_DEFAULT_IDLE:
*
* Use this for default priority idle functions.
+ *
* In GLib this priority is used when adding idle functions with
* g_idle_add().
*/
@@ -3506,6 +3574,7 @@
* G_PRIORITY_HIGH:
*
* Use this for high priority event sources.
+ *
* It is not used within GLib or GTK+.
*/
@@ -3514,6 +3583,7 @@
* G_PRIORITY_HIGH_IDLE:
*
* Use this for high priority idle functions.
+ *
* GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
* and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
* done to ensure that any pending resizes are processed before any
@@ -3525,6 +3595,7 @@
* G_PRIORITY_LOW:
*
* Use this for very low priority background tasks.
+ *
* It is not used within GLib or GTK+.
*/
@@ -3536,6 +3607,7 @@
* macro before it can be used. This macro can be used to initialize
* a variable, but it cannot be assigned to a variable. In that case
* you have to use g_queue_init().
+ *
* |[
* GQueue my_queue = G_QUEUE_INIT;
* ]|
@@ -3575,6 +3647,7 @@
* This macro flags signal argument types for which the signal system may
* assume that instances thereof remain persistent across all signal emissions
* they are used in. This is only useful for non ref-counted, value-copy types.
+ *
* To flag a signal argument in this way, add
* <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
* of g_signal_new().
@@ -3695,6 +3768,7 @@
* Checks that @g_class is a class structure of the type identified by @g_type
* and issues a warning if this is not the case. Returns @g_class casted
* to a pointer to @c_type.
+ *
* This macro should only be used in type implementations.
*/
@@ -3705,6 +3779,8 @@
* @g_type: The type to be checked.
*
* Checks if @g_class is a class structure of the type identified by
+ * @g_type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -3717,6 +3793,7 @@
*
* Checks if @instance is a valid #GTypeInstance structure,
* otherwise issues a warning and returns %FALSE.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -3732,6 +3809,7 @@
* Checks that @instance is an instance of the type identified by @g_type
* and issues a warning if this is not the case. Returns @instance casted
* to a pointer to @c_type.
+ *
* This macro should only be used in type implementations.
*/
@@ -3742,6 +3820,7 @@
* @g_type: The type to be checked
*
* Checks if @instance is an instance of the type identified by @g_type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -3754,6 +3833,7 @@
*
* Checks if @value has been initialized to hold values
* of a value type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -3767,6 +3847,7 @@
*
* Checks if @value has been initialized to hold values
* of type @g_type.
+ *
* This macro should only be used in type implementations.
*
* Returns: %TRUE on success.
@@ -3782,6 +3863,7 @@
* Gets the private class structure for a particular type.
* The private structure must have been registered in the
* get_type() function with g_type_add_class_private().
+ *
* This macro should only be used in type implementations.
*
* Since: 2.24
@@ -3861,6 +3943,7 @@
* @g_class: Location of a valid #GTypeClass structure.
*
* Get the type identifier from a given @class structure.
+ *
* This macro should only be used in type implementations.
*
* Returns: the #GType
@@ -3872,6 +3955,7 @@
* @instance: Location of a valid #GTypeInstance structure.
*
* Get the type identifier from a given @instance structure.
+ *
* This macro should only be used in type implementations.
*
* Returns: the #GType
@@ -3883,6 +3967,7 @@
* @g_iface: Location of a valid #GTypeInterface structure.
*
* Get the type identifier from a given @interface structure.
+ *
* This macro should only be used in type implementations.
*
* Returns: the #GType
@@ -3962,8 +4047,10 @@
*
* Get the class structure of a given @instance, casted
* to a specified ancestor type @g_type of the instance.
+ *
* Note that while calling a GInstanceInitFunc(), the class pointer gets
* modified, so it might not always return the expected pointer.
+ *
* This macro should only be used in type implementations.
*
* Returns: a pointer to the class structure
@@ -3977,6 +4064,7 @@
* @c_type: The C type of the interface structure.
*
* Get the interface structure for interface @g_type of a given @instance.
+ *
* This macro should only be used in type implementations.
*
* Returns: a pointer to the interface structure
@@ -3992,6 +4080,7 @@
* Gets the private structure for a particular type.
* The private structure must have been registered in the
* class_init function with g_type_class_add_private().
+ *
* This macro should only be used in type implementations.
*
* Since: 2.4
@@ -4498,9 +4587,11 @@
* G_TYPE_STRV:
*
* The #GType for a boxed type holding a %NULL-terminated array of strings.
+ *
* The code fragments in the following example show the use of a property of
* type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
* and g_object_get().
+ *
* |[
* g_object_class_install_property (object_class,
* PROP_AUTHORS,
@@ -4509,8 +4600,10 @@
* _("List of authors"),
* G_TYPE_STRV,
* G_PARAM_READWRITE));
+ *
* gchar *authors[] = { "Owen", "Tim", NULL };
* g_object_set (obj, "authors", authors, NULL);
+ *
* gchar *writers[];
* g_object_get (obj, "authors", &writers, NULL);
* /* do something with writers */
@@ -4569,14 +4662,17 @@
* G_TYPE_VARIANT:
*
* The fundamental type corresponding to #GVariant.
+ *
* All floating #GVariant instances passed through the #GType system are
* consumed.
+ *
* Note that callbacks in closures, and signal handlers
* for signals of return type %G_TYPE_VARIANT, must never return floating
* variants.
- * with this fundamental type in 2.26.
*
* Note: GLib 2.24 did include a boxed type with this name. It was replaced
+ * with this fundamental type in 2.26.
+ *
* Since: 2.26
*/
@@ -4653,10 +4749,10 @@
* Collects a variable argument value from a va_list. We have to
* implement the varargs collection as a macro, because on some systems
* va_list variables cannot be passed by reference.
- * you should use the #G_VALUE_COLLECT_INIT variant and pass the unitialized
- * #GValue. That variant is faster than #G_VALUE_COLLECT.
*
* Note: If you are creating the @value argument just before calling this macro,
+ * you should use the #G_VALUE_COLLECT_INIT variant and pass the unitialized
+ * #GValue. That variant is faster than #G_VALUE_COLLECT.
*/
@@ -4901,6 +4997,22 @@
/**
+ * G_VALUE_INIT:
+ *
+ * A #GValue must be initialized before it can be used.
+ * This macro can be used as initializer instead of an explicit
+ * <literal>{ 0 }</literal> when declaring a variable,
+ * but it cannot be assigned to a variable.
+ *
+ * |[
+ * GValue value = G_VALUE_INIT;
+ * ]|
+ *
+ * Since: 2.30
+ */
+
+
+/**
* G_VALUE_LCOPY:
* @value: a #GValue return location. @value is supposed to be initialized according to the value type to be collected
* @var_args: the va_list variable; it may be evaluated multiple times
@@ -4948,8 +5060,10 @@
* Converts a string to a const #GVariantType. Depending on the
* current debugging level, this function may perform a runtime check
* to ensure that @string is a valid GVariant type string.
+ *
* It is always a programmer error to use this macro with an invalid
* type string.
+ *
* Since 2.24
*/
@@ -5042,6 +5156,7 @@
* The type of a 32bit signed integer value, that by convention, is used
* as an index into an array of file descriptors that are sent alongside
* a D-Bus message.
+ *
* If you are not interacting with D-Bus, then there is no reason to make
* use of this type.
*/
@@ -5083,6 +5198,7 @@
* The type of a D-Bus object reference. These are strings of a
* specific format used to identify objects at a given destination on
* the bus.
+ *
* If you are not interacting with D-Bus, then there is no reason to make
* use of this type. If you are, then the D-Bus specification contains a
* precise description of valid object paths.
@@ -5101,6 +5217,7 @@
*
* The type of a D-Bus type signature. These are strings of a specific
* format used as type signatures for D-Bus methods and messages.
+ *
* If you are not interacting with D-Bus, then there is no reason to make
* use of this type. If you are, then the D-Bus specification contains a
* precise description of valid signature strings.
@@ -5195,6 +5312,7 @@
* nickname. When an enumeration or flags type is registered with the
* GLib type system, it can be used as value type for object
* properties, using g_param_spec_enum() or g_param_spec_flags().
+ *
* GObject ships with a utility called <link
* linkend="glib-mkenums">glib-mkenums</link> that can construct
* suitable type registration functions from C enumeration
@@ -5212,27 +5330,34 @@
* instance (or target). Whenever the source property changes, the same
* value is applied to the target property; for instance, the following
* binding:
+ *
* |[
* g_object_bind_property (object1, "property-a",
* object2, "property-b",
* G_BINDING_DEFAULT);
* ]|
+ *
* will cause <emphasis>object2:property-b</emphasis> to be updated every
* time g_object_set() or the specific accessor changes the value of
* <emphasis>object1:property-a</emphasis>.
+ *
* It is possible to create a bidirectional binding between two properties
* of two #GObject instances, so that if either property changes, the
* other is updated as well, for instance:
+ *
* |[
* g_object_bind_property (object1, "property-a",
* object2, "property-b",
* G_BINDING_BIDIRECTIONAL);
* ]|
+ *
* will keep the two properties in sync.
+ *
* It is also possible to set a custom transformation function (in both
* directions, in case of a bidirectional binding) to apply a custom
* transformation from the source value to the target value before
* applying it; for instance, the following binding:
+ *
* |[
* g_object_bind_property_full (adjustment1, "value",
* adjustment2, "value",
@@ -5241,6 +5366,7 @@
* fahrenheit_to_celsius,
* NULL, NULL);
* ]|
+ *
* will keep the <emphasis>value</emphasis> property of the two adjustments
* in sync; the <function>celsius_to_fahrenheit</function> function will be
* called whenever the <emphasis>adjustment1:value</emphasis> property changes
@@ -5250,21 +5376,26 @@
* the <emphasis>adjustment2:value</emphasis> property changes, and will
* transform the current value of the property before applying it to the
* <emphasis>adjustment1:value</emphasis>.
+ *
* Note that #GBinding does not resolve cycles by itself; a cycle like
+ *
* |[
* object1:propertyA -> object2:propertyB
* object2:propertyB -> object3:propertyC
* object3:propertyC -> object1:propertyA
* ]|
+ *
* might lead to an infinite loop. The loop, in this particular case,
* can be avoided if the objects emit the #GObject::notify signal only
* if the value has effectively been changed. A binding is implemented
* using the #GObject::notify signal, so it is susceptible to all the
* various ways of blocking a signal emission, like g_signal_stop_emission()
* or g_signal_handler_block().
+ *
* A binding will be severed, and the resources it allocates freed, whenever
* either one of the #GObject instances it refers to are finalized, or when
* the #GBinding instance loses its last reference.
+ *
* #GBinding is available since GObject 2.26
*/
@@ -5278,6 +5409,7 @@
* GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
* thing the type system needs to know about the structures is how to copy and
* free them, beyond that they are treated as opaque chunks of memory.
+ *
* Boxed types are useful for simple value-holder structures like rectangles or
* points. They can also be used for wrapping structures defined in non-GObject
* based libraries.
@@ -5295,6 +5427,7 @@
* convert the arguments for the invocation from #GValue<!-- -->s into
* a suitable form, perform the callback on the converted arguments,
* and transform the return value back into a #GValue.
+ *
* In the case of C programs, a closure usually just holds a pointer
* to a function and maybe a data argument, and the marshaller
* converts between #GValue<!-- --> and native C types. The GObject
@@ -5302,8 +5435,10 @@
* other languages need marshallers which convert between #GValue<!--
* -->s and suitable representations in the runtime of the language in
* order to use functions written in that languages as callbacks.
+ *
* Within GObject, closures play an important role in the
* implementation of signals. When a signal is registered, the
+ * @c_marshaller argument to g_signal_new() specifies the default C
* marshaller for any closure which is connected to this
* signal. GObject provides a number of C marshallers for this
* purpose, see the g_cclosure_marshal_*() functions. Additional C
@@ -5314,6 +5449,7 @@
* GObject create a closure automatically by using one of the
* g_signal_connect_*() functions which take a callback function/user
* data pair.
+ *
* Using closures has a number of important advantages over a simple
* callback function/data pointer combination:
* <itemizedlist>
@@ -5352,10 +5488,13 @@
* by the #GTypeValueTable associated with the type ID stored in the #GValue.
* Other #GValue operations (such as converting values between types) are
* provided by this interface.
+ *
* The code in the example program below demonstrates #GValue's
* features.
+ *
* |[
* #include <glib-object.h>
+ *
* static void
* int2string (const GValue *src_value,
* GValue *dest_value)
@@ -5365,33 +5504,43 @@
* else
* g_value_set_static_string (dest_value, "What's that?");
* }
+ *
* int
* main (int argc,
* char *argv[])
* {
- * /* GValues must start zero-filled */
- * GValue a = {0};
- * GValue b = {0};
+ * /* GValues must be initialized */
+ * GValue a = G_VALUE_INIT;
+ * GValue b = G_VALUE_INIT;
* const gchar *message;
+ *
* g_type_init ();
+ *
* /* The GValue starts empty */
* g_assert (!G_VALUE_HOLDS_STRING (&a));
+ *
* /* Put a string in it */
* g_value_init (&a, G_TYPE_STRING);
* g_assert (G_VALUE_HOLDS_STRING (&a));
* g_value_set_static_string (&a, "Hello, world!");
* g_printf ("%s\n", g_value_get_string (&a));
+ *
* /* Reset it to its pristine state */
* g_value_unset (&a);
+ *
* /* It can then be reused for another type */
* g_value_init (&a, G_TYPE_INT);
* g_value_set_int (&a, 42);
+ *
* /* Attempt to transform it into a GValue of type STRING */
* g_value_init (&b, G_TYPE_STRING);
+ *
* /* An INT is transformable to a STRING */
* g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
+ *
* g_value_transform (&a, &b);
* g_printf ("%s\n", g_value_get_string (&b));
+ *
* /* Attempt to transform it again using a custom transform function */
* g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
* g_value_transform (&a, &b);
@@ -5410,6 +5559,7 @@
*
* #GParamSpec is an object structure that encapsulates the metadata
* required to specify parameters, such as e.g. #GObject properties.
+ *
* <para id="canonical-parameter-name">
* Parameter names need to start with a letter (a-z or A-Z). Subsequent
* characters can be letters, numbers or a '-'.
@@ -5429,7 +5579,9 @@
* user-defined object and interface types. Before using any GType
* or GObject functions, g_type_init() must be called to initialize the
* type system.
+ *
* For type creation and registration purposes, all types fall into one of
+ * two categories: static or dynamic. Static types are never loaded or
* unloaded at run-time as dynamic types may be. Static types are created
* with g_type_register_static() that gets type specific information passed
* in via a #GTypeInfo structure.
@@ -5446,13 +5598,12 @@
* types called g_type_register_fundamental() which requires both a #GTypeInfo
* structure and a #GTypeFundamentalInfo structure but it is seldom used
* since most fundamental types are predefined rather than user-defined.
+ *
* A final word about type names.
* Such an identifier needs to be at least three characters long. There is no
* upper length limit. The first character needs to be a letter (a-z or A-Z)
* or an underscore '_'. Subsequent characters can be letters, numbers or
* any of '-_+'.
- *
- * Two categories: static or dynamic. Static types are never loaded or
*/
@@ -5473,6 +5624,7 @@
* will be reloaded. Note that the last unref cannot happen in module
* code, since that would lead to the caller's code being unloaded before
* g_object_unref() returns to it.
+ *
* Keeping track of whether the module should be loaded or not is done by
* using a use count - it starts at zero, and whenever it is greater than
* zero, the module is loaded. The use count is maintained internally by
@@ -5482,6 +5634,7 @@
* it so that it can initialize its types. At some later point, when the
* module no longer needs to be loaded except for the type
* implementations it contains, g_type_module_unuse() is called.
+ *
* #GTypeModule does not actually provide any implementation of module
* loading and unloading. To create a particular module type you must
* derive from #GTypeModule and implement the load and unload functions
@@ -5498,6 +5651,7 @@
* The GObject type system supports dynamic loading of types. The
* #GTypePlugin interface is used to handle the lifecycle of
* dynamically loaded types. It goes as follows:
+ *
* <orderedlist>
* <listitem><para>
* The type is initially introduced (usually upon loading the module
@@ -5537,6 +5691,7 @@
* Things may repeat from the second step.
* </para></listitem>
* </orderedlist>
+ *
* So basically, you need to implement a #GTypePlugin type that
* carries a use_count, once use_count goes from zero to one, you need
* to load the implementation to successfully handle the upcoming
@@ -5545,6 +5700,7 @@
* unload the implementation again. The type system makes sure to call
* g_type_plugin_use() and g_type_plugin_complete_type_info() again
* when the type is needed again.
+ *
* #GTypeModule is an implementation of #GTypePlugin that already
* implements most of this except for the actual module loading and
* unloading. It even handles multiple registered types per module.
@@ -5563,6 +5719,7 @@
* construction and destruction, property access methods, and signal
* support. Signals are described in detail in <xref
* linkend="gobject-Signals"/>.
+ *
* <para id="floating-ref">
* GInitiallyUnowned is derived from GObject. The only difference between
* the two is that the initial reference of a GInitiallyUnowned is flagged
@@ -5596,9 +5753,11 @@
* maintenance (such as smart pointers or garbage collection) should not
* expose floating references in their API.
* </para>
+ *
* Some object implementations may need to save an objects floating state
* across certain code portions (an example is #GtkMenu), to achieve this,
* the following sequence can be used:
+ *
* |[
* /* save floating state */
* gboolean was_floating = g_object_is_floating (object);
@@ -5626,6 +5785,7 @@
* specifications for most value types can be created as #GParamSpec
* derived instances, to implement e.g. #GObject properties which
* operate on #GValue containers.
+ *
* Parameter names need to start with a letter (a-z or A-Z). Subsequent
* characters can be letters, numbers or a '-'.
* All other characters are replaced by a '-' during construction.
@@ -5657,6 +5817,7 @@
* frequently happens at the end of an object class' creation), while user
* provided handlers are frequently connected and disconnected to/from a certain
* signal on certain object instances.
+ *
* A signal emission consists of five stages, unless prematurely stopped:
* <variablelist>
* <varlistentry><term></term><listitem><para>
@@ -6248,11 +6409,16 @@
* @object_ptr: a pointer to a #GObject reference
*
* Clears a reference to a #GObject.
+ *
+ * @object_ptr must not be %NULL.
+ *
* If the reference is %NULL then this function does nothing.
* Otherwise, the reference count of the object is decreased and the
* pointer is set to %NULL.
+ *
* This function is threadsafe and modifies the pointer atomically,
* using memory barriers where needed.
+ *
* A macro is also included that allows this function to be used without
* pointer casts.
*
@@ -6282,6 +6448,7 @@
* @notify_func: the callback function to register
*
* Registers an invalidation notifier which will be called when the
+ * @closure is invalidated with g_closure_invalidate(). Invalidation
* notifiers are invoked before finalization notifiers, in an
* unspecified order.
*/
@@ -6315,6 +6482,7 @@
* unref the closure and cause it to be destroyed, so if you need to
* access the closure after calling g_closure_invalidate(), make sure
* that you've previously called g_closure_ref().
+ *
* Note that g_closure_invalidate() will also be called when the
* reference count of a closure drops to zero (unless it has already
* been invalidated before).
@@ -6339,6 +6507,8 @@
* @object: a #GObject pointer to store in the @data field of the newly allocated #GClosure
*
* A variant of g_closure_new_simple() which stores @object in the
+ * @data field of the closure and calls g_object_watch_closure() on
+ * @object and the created closure. This function is mainly useful
* when implementing new types of closures.
*
* Returns: (transfer full): a newly allocated #GClosure
@@ -6353,6 +6523,7 @@
* Allocates a struct of the given size and initializes the initial
* part as a #GClosure. This function is mainly useful when
* implementing new types of closures.
+ *
* |[
* typedef struct _MyClosure MyClosure;
* struct _MyClosure
@@ -6360,20 +6531,26 @@
* GClosure closure;
* // extra data goes here
* };
+ *
* static void
* my_closure_finalize (gpointer notify_data,
* GClosure *closure)
* {
* MyClosure *my_closure = (MyClosure *)closure;
+ *
* // free extra data here
* }
+ *
* MyClosure *my_closure_new (gpointer data)
* {
* GClosure *closure;
* MyClosure *my_closure;
+ *
* closure = g_closure_new_simple (sizeof (MyClosure), data);
* my_closure = (MyClosure *) closure;
+ *
* // initialize extra data here
+ *
* g_closure_add_finalize_notifier (closure, notify_data,
* my_closure_finalize);
* return my_closure;
@@ -6402,6 +6579,7 @@
* @notify_func: the callback function to remove
*
* Removes a finalization notifier.
+ *
* Notice that notifiers are automatically removed after they are run.
*/
@@ -6413,6 +6591,7 @@
* @notify_func: the callback function to remove
*
* Removes an invalidation notifier.
+ *
* Notice that notifiers are automatically removed after they are run.
*/
@@ -6427,6 +6606,7 @@
* information to the marshaller. (See g_closure_set_meta_marshal().) For
* GObject's C predefined marshallers (the g_cclosure_marshal_*()
* functions), what it provides is a callback function to use instead of
+ * @closure->callback.
*/
@@ -6437,6 +6617,7 @@
* @meta_marshal: a #GClosureMarshal function
*
* Sets the meta marshaller of @closure. A meta marshaller wraps
+ * @closure->marshal and modifies the way it is called in some
* fashion. The most common use of this facility is for C callbacks.
* The same marshallers (generated by <link
* linkend="glib-genmarshal">glib-genmarshal</link>) are used
@@ -6444,10 +6625,12 @@
* differs. In most cases we want to use @closure->callback, but in
* other cases we want to use some different technique to retrieve the
* callback function.
+ *
* For example, class closures for signals (see
* g_signal_type_cclosure_new()) retrieve the callback function from a
* fixed offset in the class structure. The meta marshaller retrieves
* the right callback and passes it to the marshaller as the
+ * @marshal_data argument.
*/
@@ -6473,6 +6656,7 @@
* |[
* g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
* ]|
+ *
* Generally, this function is used together with g_closure_ref(). Ane example
* of storing a closure for later notification looks like:
* |[
@@ -6490,6 +6674,7 @@
* }
* }
* ]|
+ *
* Because g_closure_sink() may decrement the reference count of a closure
* (if it hasn't been called on @closure yet) just like g_closure_unref(),
* g_closure_ref() should be called prior to this function.
@@ -6515,6 +6700,7 @@
* This function is meant to be called from the complete_type_info()
* function of a #GTypePlugin implementation, as in the following
* example:
+ *
* |[
* static void
* my_enum_complete_type_info (GTypePlugin *plugin,
@@ -6527,6 +6713,7 @@
* { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
* { 0, NULL, NULL }
* };
+ *
* g_enum_complete_type_info (type, info, values);
* }
* ]|
@@ -6539,6 +6726,7 @@
* @value: the value to look up
*
* Returns the #GEnumValue for a value.
+ *
* member of the enumeration
*
* Returns: the #GEnumValue for @value, or %NULL if @value is not a
@@ -6551,6 +6739,7 @@
* @name: the name to look up
*
* Looks up a #GEnumValue by name.
+ *
* enumeration doesn't have a member with that name
*
* Returns: the #GEnumValue with name @name, or %NULL if the
@@ -6563,6 +6752,7 @@
* @nick: the nickname to look up
*
* Looks up a #GEnumValue by nickname.
+ *
* enumeration doesn't have a member with that nickname
*
* Returns: the #GEnumValue with nickname @nick, or %NULL if the
@@ -6575,6 +6765,7 @@
* @const_static_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated.
*
* Registers a new static enumeration type with the name @name.
+ *
* It is normally more convenient to let <link
* linkend="glib-mkenums">glib-mkenums</link> generate a
* my_enum_get_type() function from a usual C enumeration definition
@@ -6602,6 +6793,7 @@
* @value: the value
*
* Returns the first #GFlagsValue which is set in @value.
+ *
* none is set
*
* Returns: the first #GFlagsValue which is set in @value, or %NULL if
@@ -6614,6 +6806,7 @@
* @name: the name to look up
*
* Looks up a #GFlagsValue by name.
+ *
* flag with that name
*
* Returns: the #GFlagsValue with name @name, or %NULL if there is no
@@ -6626,6 +6819,7 @@
* @nick: the nickname to look up
*
* Looks up a #GFlagsValue by nickname.
+ *
* no flag with that nickname
*
* Returns: the #GFlagsValue with nickname @nick, or %NULL if there is
@@ -6638,6 +6832,7 @@
* @const_static_values: An array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated.
*
* Registers a new static flags type with the name @name.
+ *
* It is normally more convenient to let <link
* linkend="glib-mkenums">glib-mkenums</link> generate a
* my_flags_get_type() function from a usual C enumeration definition
@@ -6714,8 +6909,10 @@
* Checks if any events are pending for the default #GMainContext
* (i.e. ready to be processed).
*
- * Returns: %TRUE if any events are pending.
+ *
* Deprected: 2.2: Use g_main_context_pending() instead.
+ *
+ * Returns: %TRUE if any events are pending.
*/
@@ -6760,6 +6957,7 @@
* The returned pointer is cast to a pointer to the given type.
* If @n_structs is 0 it returns %NULL.
* Care is taken to avoid overflow when calculating the size of the allocated block.
+ *
* Since the returned pointer is already casted to the right type,
* it is normally unnecessary to cast it explicitly, and doing
* so might hide memory allocation errors.
@@ -6777,6 +6975,7 @@
* The returned pointer is cast to a pointer to the given type.
* If @n_structs is 0 it returns %NULL.
* Care is taken to avoid overflow when calculating the size of the allocated block.
+ *
* Since the returned pointer is already casted to the right type,
* it is normally unnecessary to cast it explicitly, and doing
* so might hide memory allocation errors.
@@ -6823,6 +7022,7 @@
* @node: a #GNode
*
* Gets the first child of a #GNode.
+ *
* or has no children
*
* Returns: the first child of @node, or %NULL if @node is %NULL
@@ -6858,6 +7058,7 @@
* @node: a #GNode
*
* Gets the next sibling of a #GNode.
+ *
* or %NULL
*
* Returns: the next sibling of @node, or %NULL if @node is the last node
@@ -6880,6 +7081,7 @@
* @node: a #GNode
*
* Gets the previous sibling of a #GNode.
+ *
* node or %NULL
*
* Returns: the previous sibling of @node, or %NULL if @node is the first
@@ -6896,26 +7098,31 @@
* callback to be called when all other references to the object are
* dropped, or when this is already the last reference to the object
* and another reference is established.
+ *
* This functionality is intended for binding @object to a proxy
* object managed by another memory manager. This is done with two
+ * paired references: the strong reference added by
* g_object_add_toggle_ref() and a reverse reference to the proxy
* object which is either a strong reference or weak reference.
+ *
* The setup is that when there are no other references to @object,
* only a weak reference is held in the reverse direction from @object
* to the proxy object, but when there are other references held to
+ * @object, a strong reference is held. The @notify callback is called
* when the reference from @object to the proxy object should be
* <firstterm>toggled</firstterm> from strong to weak (@is_last_ref
* true) or weak to strong (@is_last_ref false).
+ *
* Since a (normal) reference must be held to the object before
* calling g_object_toggle_ref(), the initial state of the reverse
* link is always strong.
+ *
* Multiple toggle references may be added to the same gobject,
* however if there are multiple toggle references to an object, none
* of them will ever be notified until all but one are removed. For
* this reason, you should only ever use a toggle reference if there
* is important state in the proxy object.
*
- * Paired references: the strong reference added by
* Since: 2.8
*/
@@ -6928,6 +7135,7 @@
* Adds a weak reference from weak_pointer to @object to indicate that
* the pointer located at @weak_pointer_location is only valid during
* the lifetime of @object. When the @object is finalized,
+ * @weak_pointer will be set to %NULL.
*/
@@ -6942,18 +7150,26 @@
* Creates a binding between @source_property on @source and @target_property
* on @target. Whenever the @source_property is changed the @target_property is
* updated using the same value. For instance:
+ *
* |[
* g_object_bind_property (action, "active", widget, "sensitive", 0);
* ]|
+ *
* Will result in the "sensitive" property of the widget #GObject instance to be
* updated with the same value of the "active" property of the action #GObject
* instance.
+ *
* If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
* if @target_property on @target changes then the @source_property on @source
* will be updated as well.
+ *
* The binding will automatically be removed when either the @source or the
+ * @target instances are finalized. To remove the binding without affecting the
+ * @source and the @target you can just call g_object_unref() on the returned
* #GBinding instance.
+ *
* A #GObject can have multiple bindings.
+ *
* binding between the two #GObject instances. The binding is released
* whenever the #GBinding reference count reaches zero.
*
@@ -6975,21 +7191,29 @@
* @notify: function to be called when disposing the binding, to free the resources used by the transformation functions
*
* Complete version of g_object_bind_property().
+ *
* Creates a binding between @source_property on @source and @target_property
* on @target, allowing you to set the transformation functions to be used by
* the binding.
+ *
* If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual:
* if @target_property on @target changes then the @source_property on @source
* will be updated as well. The @transform_from function is only used in case
* of bidirectional bindings, otherwise it will be ignored
+ *
* The binding will automatically be removed when either the @source or the
+ * @target instances are finalized. To remove the binding without affecting the
+ * @source and the @target you can just call g_object_unref() on the returned
* #GBinding instance.
+ *
* A #GObject can have multiple bindings.
+ *
* <note>The same @user_data parameter will be used for both @transform_to
* and @transform_from transformation functions; the @notify function will
* be called once, when the binding is removed. If you need different data
* for each transformation function, please use
* g_object_bind_property_with_closures() instead.</note>
+ *
* binding between the two #GObject instances. The binding is released
* whenever the #GBinding reference count reaches zero.
*
@@ -7011,9 +7235,12 @@
* Creates a binding between @source_property on @source and @target_property
* on @target, allowing you to set the transformation functions to be used by
* the binding.
+ *
* This function is the language bindings friendly version of
* g_object_bind_property_full(), using #GClosure<!-- -->s instead of
* function pointers.
+ *
+ *
* binding between the two #GObject instances. The binding is released
* whenever the #GBinding reference count reaches zero.
*
@@ -7029,6 +7256,7 @@
* @property_name: the name of the property to look up
*
* Looks up the #GParamSpec for a property of a class.
+ *
* %NULL if the class doesn't have a property of that name
*
* Returns: (transfer none): the #GParamSpec for the property, or
@@ -7043,31 +7271,40 @@
*
* Installs new properties from an array of #GParamSpec<!-- -->s. This is
* usually done in the class initializer.
+ *
* The property id of each property is the index of each #GParamSpec in
* the @pspecs array.
+ *
* The property id of 0 is treated specially by #GObject and it should not
* be used to store a #GParamSpec.
+ *
* This function should be used if you plan to use a static array of
* #GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this
* class initialization:
+ *
* |[
* enum {
* PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES
* };
+ *
* static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, };
+ *
* static void
* my_object_class_init (MyObjectClass *klass)
* {
* GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+ *
* obj_properties[PROP_FOO] =
* g_param_spec_int ("foo", "Foo", "Foo",
* -1, G_MAXINT,
* 0,
* G_PARAM_READWRITE);
+ *
* obj_properties[PROP_BAR] =
* g_param_spec_string ("bar", "Bar", "Bar",
* NULL,
* G_PARAM_READWRITE);
+ *
* gobject_class->set_property = my_object_set_property;
* gobject_class->get_property = my_object_get_property;
* g_object_class_install_properties (gobject_class,
@@ -7075,7 +7312,9 @@
* obj_properties);
* }
* ]|
+ *
* allows calling g_object_notify_by_pspec() to notify of property changes:
+ *
* |[
* void
* my_object_set_foo (MyObject *self, gint foo)
@@ -7099,6 +7338,7 @@
* @pspec: the #GParamSpec for the new property
*
* Installs a new property. This is usually done in the class initializer.
+ *
* Note that it is possible to redefine a property in a derived class,
* by installing a property with the same name. This can be useful at times,
* e.g. to change the range of allowed values or the default value.
@@ -7111,6 +7351,7 @@
* @n_properties: (out): return location for the length of the returned array
*
* Get an array of #GParamSpec* for all properties of a class.
+ *
* #GParamSpec* which should be freed after use
*
* Returns: (array length=n_properties) (transfer container): an array of
@@ -7128,6 +7369,7 @@
* by @oclass. This allows this class to <firstterm>override</firstterm>
* a property implementation in a parent class or to provide
* the implementation of a property from an interface.
+ *
* <note>
* Internally, overriding is implemented by creating a property of type
* #GParamSpecOverride; generally operations that query the properties of
@@ -7152,6 +7394,7 @@
* @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL
*
* A convenience function to connect multiple signals at once.
+ *
* The signal specs expected by this function have the form
* "modifier::signal_name", where modifier can be one of the following:
* <variablelist>
@@ -7211,6 +7454,7 @@
* </para></listitem>
* </varlistentry>
* </variablelist>
+ *
* |[
* menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
* "type", GTK_WINDOW_POPUP,
@@ -7233,6 +7477,7 @@
* @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL
*
* A convenience function to disconnect multiple signals at once.
+ *
* The signal specs expected by this function have the form
* "any_signal", which means to disconnect any signal with matching
* callback and data, or "any_signal::signal_name", which only
@@ -7246,10 +7491,10 @@
*
* This function is intended for #GObject implementations to re-enforce a
* <link linkend="floating-ref">floating</link> object reference.
+ * Doing this is seldomly required: all
* #GInitiallyUnowned<!-- -->s are created with a floating reference which
* usually just needs to be sunken by calling g_object_ref_sink().
*
- * Doing this is seldomly required: all
* Since: 2.10
*/
@@ -7262,6 +7507,7 @@
* non-zero, the emission of "notify" signals on @object is
* stopped. The signals are queued until the freeze count is decreased
* to zero.
+ *
* This is necessary for accessors that modify multiple properties to prevent
* premature notification while the object is still being modified.
*/
@@ -7274,9 +7520,11 @@
* @...: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL
*
* Gets properties of an object.
+ *
* In general, a copy is made of the property contents and the caller
* is responsible for freeing the memory in the appropriate manner for
* the type, for instance by calling g_free() or g_object_unref().
+ *
* <example>
* <title>Using g_object_get(<!-- -->)</title>
* An example of using g_object_get() to get the contents
@@ -7286,12 +7534,15 @@
* gint intval;
* gchar *strval;
* GObject *objval;
+ *
* g_object_get (my_object,
* "int-property", &intval,
* "str-property", &strval,
* "obj-property", &objval,
* NULL);
+ *
* // Do something with intval, strval, objval
+ *
* g_free (strval);
* g_object_unref (objval);
* </programlisting>
@@ -7319,8 +7570,10 @@
* Gets a property of an object. @value must have been initialized to the
* expected type of the property (or a type to which the expected type can be
* transformed) using g_value_init().
+ *
* In general, a copy is made of the property contents and the caller is
* responsible for freeing the memory by calling g_value_unset().
+ *
* Note that g_object_get_property() is really intended for language
* bindings, g_object_get() is much more convenient for C programming.
*/
@@ -7345,9 +7598,11 @@
* @var_args: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL
*
* Gets properties of an object.
+ *
* In general, a copy is made of the property contents and the caller
* is responsible for freeing the memory in the appropriate manner for
* the type, for instance by calling g_free() or g_object_unref().
+ *
* See g_object_get().
*/
@@ -7362,6 +7617,8 @@
* will be the default vtable from g_type_default_interface_ref(), or,
* if you know the interface has already been loaded,
* g_type_default_interface_peek().
+ *
+ *
* interface with the name @property_name, or %NULL if no
* such property exists.
*
@@ -7384,6 +7641,7 @@
* class only needs to provide an implementation and inherits the
* property description, default value, bounds, and so forth from the
* interface property.
+ *
* This function is meant to be called from the interface's default
* vtable initialization function (the @class_init member of
* #GTypeInfo.) It must not be called after after @class_init has
@@ -7402,6 +7660,8 @@
* vtable passed in as @g_iface will be the default vtable from
* g_type_default_interface_ref(), or, if you know the interface has
* already been loaded, g_type_default_interface_peek().
+ *
+ *
* pointer to an array of pointers to #GParamSpec
* structures. The paramspecs are owned by GLib, but the
* array should be freed with g_free() when you are done with
@@ -7431,6 +7691,7 @@
* @...: the value of the first property, followed optionally by more name/value pairs, followed by %NULL
*
* Creates a new instance of a #GObject subtype and sets its properties.
+ *
* Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
* which are not explicitly specified are set to their default values.
*
@@ -7445,6 +7706,7 @@
* @var_args: the value of the first property, followed optionally by more name/value pairs, followed by %NULL
*
* Creates a new instance of a #GObject subtype and sets its properties.
+ *
* Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
* which are not explicitly specified are set to their default values.
*
@@ -7459,9 +7721,12 @@
* @parameters: (array length=n_parameters): an array of #GParameter
*
* Creates a new instance of a #GObject subtype and sets its properties.
+ *
* Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
* which are not explicitly specified are set to their default values.
*
+ * @object_type
+ *
* Rename to: g_object_new
* Returns: (type GObject.Object) (transfer full): a new instance of
*/
@@ -7473,6 +7738,7 @@
* @property_name: the name of a property installed on the class of @object.
*
* Emits a "notify" signal for the property @property_name on @object.
+ *
* When possible, eg. when signaling a property change from within the class
* that registered the property, you should use g_object_notify_by_pspec()
* instead.
@@ -7485,12 +7751,15 @@
* @pspec: the #GParamSpec of a property installed on the class of @object.
*
* Emits a "notify" signal for the property specified by @pspec on @object.
+ *
* This function omits the property name lookup, hence it is faster than
* g_object_notify().
+ *
* One way to avoid using g_object_notify() from within the
* class that registered the properties, and using g_object_notify_by_pspec()
* instead, is to store the GParamSpec used with
* g_object_class_install_property() inside a static array, e.g.:
+ *
* |[
* enum
* {
@@ -7498,7 +7767,9 @@
* PROP_FOO,
* PROP_LAST
* };
+ *
* static GParamSpec *properties[PROP_LAST];
+ *
* static void
* my_object_class_init (MyObjectClass *klass)
* {
@@ -7511,7 +7782,9 @@
* properties[PROP_FOO]);
* }
* ]|
+ *
* and then notify a change on the "foo" property with:
+ *
* |[
* g_object_notify_by_pspec (self, properties[PROP_FOO]);
* ]|
@@ -7537,6 +7810,7 @@
* Increase the reference count of @object, and possibly remove the
* <link linkend="floating-ref">floating</link> reference, if @object
* has a floating reference.
+ *
* In other words, if the object is floating, then this call "assumes
* ownership" of the floating reference, converting it to a normal
* reference by clearing the floating flag while leaving the reference
@@ -7578,6 +7852,7 @@
*
* Releases all references to other objects. This can be used to break
* reference cycles.
+ *
* This functions should only be called from object system implementations.
*/
@@ -7600,6 +7875,7 @@
*
* Each object carries around a table of associations from
* strings to pointers. This function lets you set an association.
+ *
* If the object already had an association with that name,
* the old association will be destroyed.
*/
@@ -7615,6 +7891,7 @@
* Like g_object_set_data() except it adds notification
* for when the association is destroyed, either by setting it
* to a different value or when the object is destroyed.
+ *
* Note that the @destroy callback is not called if @data is %NULL.
*/
@@ -7703,6 +7980,7 @@
* GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
* // retrive the old string list
* GList *list = g_object_steal_qdata (object, quark_string_list);
+ *
* // prepend new string
* list = g_list_prepend (list, g_strdup (new_string));
* // this changed 'list', so we need to set it again
@@ -7712,6 +7990,7 @@
* free_string_list (gpointer data)
* {
* GList *node, *list = data;
+ *
* for (node = list; node; node = node->next)
* g_free (node->data);
* g_list_free (list);
@@ -7733,6 +8012,7 @@
* Reverts the effect of a previous call to
* g_object_freeze_notify(). The freeze count is decreased on @object
* and when it reaches zero, all queued "notify" signals are emitted.
+ *
* It is an error to call this function when the freeze count is zero.
*/
@@ -7758,6 +8038,7 @@
* (nonexisting) object. Also, g_object_ref() and g_object_unref() are
* added as marshal guards to the @closure, to ensure that an extra
* reference count is held on @object during invocation of the
+ * @closure. Usually, this function will be called on closures that
* use this @object as closure data.
*/
@@ -7796,6 +8077,7 @@
*
* Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN
* property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -7812,6 +8094,7 @@
*
* Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED
* derived property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -7846,6 +8129,7 @@
*
* Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE
* property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -7863,6 +8147,7 @@
*
* Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM
* property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -7880,6 +8165,7 @@
*
* Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS
* property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -7897,6 +8183,7 @@
* @flags: flags for the property specified
*
* Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -7918,6 +8205,7 @@
* @pspec: a valid #GParamSpec
*
* Get the name of a #GParamSpec.
+ *
* The name is always an "interned" string (as per g_intern_string()).
* This allows for pointer-value comparisons.
*
@@ -7957,6 +8245,8 @@
* type. Redirection is established by creating a property
* of type #GParamSpecOverride. See g_object_class_override_property()
* for an example of the use of this capability.
+ *
+ *
* paramspec should be redirected, or %NULL if none.
*
* Since: 2.4
@@ -7974,6 +8264,7 @@
*
* Creates a new #GParamSpecGType instance specifying a
* %G_TYPE_GTYPE property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Since: 2.10
@@ -7992,6 +8283,7 @@
* @flags: flags for the property specified
*
* Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8009,6 +8301,7 @@
* @flags: flags for the property specified
*
* Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8024,17 +8317,21 @@
* @flags: a combination of #GParamFlags
*
* Creates a new #GParamSpec instance.
+ *
* A property name consists of segments consisting of ASCII letters and
* digits, separated by either the '-' or '_' character. The first
* character of a property name must be a letter. Names which violate these
* rules lead to undefined behaviour.
+ *
* When creating and looking up a #GParamSpec, either separator can be
* used, but they cannot be mixed. Using '-' is considerably more
* efficient and in fact required when using property names as detail
* strings for signals.
+ *
* Beyond the name, #GParamSpec<!-- -->s have two more descriptive
* strings associated with them, the @nick, which should be suitable
* for use as a label for the property in a property editor, and the
+ * @blurb, which should be a somewhat longer description, suitable for
* e.g. a tooltip. The @nick and @blurb should ideally be localized.
*
* Returns: a newly allocated #GParamSpec instance
@@ -8052,6 +8349,7 @@
* @flags: flags for the property specified
*
* Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8068,6 +8366,7 @@
*
* Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT
* derived property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8098,6 +8397,7 @@
*
* Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM
* property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8112,6 +8412,7 @@
* @flags: flags for the property specified
*
* Creates a new #GParamSpecPoiner instance specifying a pointer property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8136,6 +8437,7 @@
*
* Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in
* the pool.
+ *
* allocated array containing pointers to all #GParamSpecs
* owned by @owner_type in the pool
*
@@ -8150,6 +8452,7 @@
*
* Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in
* the pool.
+ *
* #GList of all #GParamSpec<!-- -->s owned by @owner_type in
* the pool#GParamSpec<!-- -->s.
*
@@ -8165,6 +8468,7 @@
* @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type.
*
* Looks up a #GParamSpec in the pool.
+ *
* matching #GParamSpec was found.
*
* Returns: (transfer none): The found #GParamSpec, or %NULL if no
@@ -8176,6 +8480,7 @@
* @type_prefixing: Whether the pool will support type-prefixed property names.
*
* Creates a new #GParamSpecPool.
+ *
* If @type_prefixing is %TRUE, lookups in the newly created pool will
* allow to specify the owner as a colon-separated prefix of the
* property name, like "GtkContainer:border-width". This feature is
@@ -8282,6 +8587,7 @@
* @flags: flags for the property specified
*
* Creates a new #GParamSpecString instance.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8315,6 +8621,7 @@
* @flags: flags for the property specified
*
* Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8333,6 +8640,7 @@
*
* Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64
* property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8351,6 +8659,7 @@
*
* Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG
* property.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8368,6 +8677,7 @@
* Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT
* property. #GValue structures for this property can be accessed with
* g_value_set_uint() and g_value_get_uint().
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8394,6 +8704,7 @@
* %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a
* %G_TYPE_BOXED type, as such, #GValue structures for this property
* can be accessed with g_value_set_boxed() and g_value_get_boxed().
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: a newly created parameter specification
@@ -8411,7 +8722,9 @@
*
* Creates a new #GParamSpecVariant instance specifying a #GVariant
* property.
+ *
* If @default_value is floating, it is consumed.
+ *
* See g_param_spec_internal() for details on property names.
*
* Returns: the newly created #GParamSpec
@@ -8442,9 +8755,12 @@
*
* Transforms @src_value into @dest_value if possible, and then
* validates @dest_value, in order for it to conform to @pspec. If
+ * @strict_validation is %TRUE this function will only succeed if the
* transformed @dest_value complied to @pspec without modifications.
+ *
* See also g_value_type_transformable(), g_value_transform() and
* g_param_value_validate().
+ *
* %FALSE otherwise and @dest_value is left untouched.
*
* Returns: %TRUE if transformation and validation were successful,
@@ -8519,6 +8835,7 @@
* @n_structs: the number of elements to allocate
*
* Reallocates the memory pointed to by @mem, so that it now has space for
+ * @n_structs elements of type @struct_type. It returns the new address of
* the memory, which may have been moved.
* Care is taken to avoid overflow when calculating the size of the allocated block.
*
@@ -8539,10 +8856,11 @@
* signal don't make much sense (except for the case of the default
* handler defined in the class structure, in which case you will
* usually want the signal connection to override the class handler).
+ *
* This accumulator will use the return value from the first signal
* handler that is run as the return value for the signal and not run
+ * any further handlers (ie: the first handler "wins").
*
- * Any further handlers (ie: the first handler "wins").
* Returns: standard #GSignalAccumulator result
* Since: 2.28
*/
@@ -8557,12 +8875,12 @@
*
* A predefined #GSignalAccumulator for signals that return a
* boolean values. The behavior that this accumulator gives is
+ * that a return of %TRUE stops the signal emission: no further
* callbacks will be invoked, while a return of %FALSE allows
* the emission to continue. The idea here is that a %TRUE return
* indicates that the callback <emphasis>handled</emphasis> the signal,
* and no further handling is needed.
*
- * That a return of %true stops the signal emission: no further
* Since: 2.4
* Returns: standard #GSignalAccumulator result
*/
@@ -8618,6 +8936,7 @@
* @data: data to pass to @c_handler calls.
*
* Connects a #GCallback function to a signal for a particular object.
+ *
* The handler will be called before the default handler of the signal.
*
* Returns: the handler id
@@ -8632,6 +8951,7 @@
* @data: data to pass to @c_handler calls.
*
* Connects a #GCallback function to a signal for a particular object.
+ *
* The handler will be called after the default handler of the signal.
*
* Returns: the handler id
@@ -8695,15 +9015,18 @@
* This is similar to g_signal_connect_data(), but uses a closure which
* ensures that the @gobject stays alive during the call to @c_handler
* by temporarily adding a reference count to @gobject.
+ *
* Note that there is a bug in GObject that makes this function
* much less useful than it might seem otherwise. Once @gobject is
* disposed, the callback will no longer be called, but, the signal
* handler is <emphasis>not</emphasis> currently disconnected. If the
+ * @instance is itself being freed at the same time than this doesn't
* matter, since the signal will automatically be removed, but
* if @instance persists, then the signal handler will leak. You
* should not remove the signal yourself because in a future versions of
* GObject, the handler <emphasis>will</emphasis> automatically
* be disconnected.
+ *
* It's possible to work around this problem in a way that will
* continue to work with future versions of GObject by checking
* that the signal handler is still connected before disconnected it:
@@ -8724,6 +9047,7 @@
* @data: data to pass to @c_handler calls.
*
* Connects a #GCallback function to a signal for a particular object.
+ *
* The instance on which the signal is emitted and @data will be swapped when
* calling the handler.
*
@@ -8739,6 +9063,7 @@
* @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted.
*
* Emits a signal.
+ *
* Note that g_signal_emit() resets the return value to the default
* if no handlers are connected, in contrast to g_signal_emitv().
*/
@@ -8751,6 +9076,7 @@
* @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted.
*
* Emits a signal.
+ *
* Note that g_signal_emit_by_name() resets the return value to the default
* if no handlers are connected, in contrast to g_signal_emitv().
*/
@@ -8764,6 +9090,7 @@
* @var_args: a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted.
*
* Emits a signal.
+ *
* Note that g_signal_emit_valist() resets the return value to the default
* if no handlers are connected, in contrast to g_signal_emitv().
*/
@@ -8777,6 +9104,7 @@
* @return_value: Location to store the return value of the signal emission.
*
* Emits a signal.
+ *
* Note that g_signal_emitv() doesn't change @return_value if no handlers are
* connected, in contrast to g_signal_emit() and g_signal_emit_valist().
*/
@@ -8802,6 +9130,7 @@
* signal handler means to temporarily deactive it, a signal handler
* has to be unblocked exactly the same amount of times it has been
* blocked before to become active again.
+ *
* The @handler_id has to be a valid signal handler id, connected to a
* signal of @instance.
*/
@@ -8815,6 +9144,7 @@
* Disconnects a handler from an instance so it will not be called during
* any future or currently ongoing emissions of the signal it has been
* connected to. The @handler_id becomes invalid and may be reused.
+ *
* The @handler_id has to be a valid signal handler id, connected to a
* signal of @instance.
*/
@@ -8866,6 +9196,7 @@
* whether the unblocked handler in question is called as part of a
* currently ongoing emission depends on how far that emission has
* proceeded yet).
+ *
* The @handler_id has to be a valid id of a signal handler that is
* connected to a signal of @instance and is currently blocked.
*/
@@ -8984,10 +9315,12 @@
*
* Returns whether there are any handlers connected to @instance for the
* given signal id and detail.
+ *
* One example of when you might use this is when the arguments to the
* signal are difficult to compute. A class implementor may opt to not
* emit the signal if no one is attached anyway, thus saving the cost
* of building the arguments.
+ *
* otherwise.
*
* Returns: %TRUE if a handler is connected to the signal, %FALSE
@@ -9015,7 +9348,9 @@
* Given the name of the signal and the type of object it connects to, gets
* the signal's identifying integer. Emitting the signal by number is
* somewhat faster than using the name each time.
+ *
* Also tries the ancestors of the given type.
+ *
* See g_signal_new() for details on allowed signal names.
*
* Returns: the signal's identifying number, or 0 if no signal was found.
@@ -9027,6 +9362,7 @@
* @signal_id: the signal's identifying number.
*
* Given the signal's identifier, finds its name.
+ *
* Two different signals may have the same name, if they have differing types.
*
* Returns: the signal name, or %NULL if the signal number was invalid.
@@ -9047,17 +9383,21 @@
* @...: a list of types, one for each parameter.
*
* Creates a new signal. (This is usually done in the class initializer.)
+ *
* A signal name consists of segments consisting of ASCII letters and
* digits, separated by either the '-' or '_' character. The first
* character of a signal name must be a letter. Names which violate these
* rules lead to undefined behaviour of the GSignal system.
+ *
* When registering a signal and looking up a signal, either separator can
* be used, but they cannot be mixed.
+ *
* If 0 is used for @class_offset subclasses cannot override the class handler
* in their <code>class_init</code> method by doing
* <code>super_class->signal_handler = my_signal_handler</code>. Instead they
* will have to use g_signal_override_class_handler().
- * If c_marshaller is %NULL @g_cclosure_marshal_generic will be used as
+ *
+ * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
* the marshaller for this signal.
*
* Returns: the signal id
@@ -9078,6 +9418,7 @@
* @...: a list of types, one for each parameter.
*
* Creates a new signal. (This is usually done in the class initializer.)
+ *
* This is a variant of g_signal_new() that takes a C callback instead
* off a class offset for the signal's class handler. This function
* doesn't need a function pointer exposed in the class structure of
@@ -9087,7 +9428,9 @@
* g_signal_override_class_handler()and chained to with
* g_signal_chain_from_overridden() or
* g_signal_chain_from_overridden_handler().
+ *
* See g_signal_new() for information about signal names.
+ *
* If c_marshaller is %NULL @g_cclosure_marshal_generic will be used as
* the marshaller for this signal.
*
@@ -9110,8 +9453,10 @@
* @args: va_list of #GType, one for each parameter.
*
* Creates a new signal. (This is usually done in the class initializer.)
+ *
* See g_signal_new() for details on allowed signal names.
- * If c_marshaller is %NULL @g_cclosure_marshal_generic will be used as
+ *
+ * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
* the marshaller for this signal.
*
* Returns: the signal id
@@ -9132,7 +9477,9 @@
* @param_types: an array of types, one for each parameter
*
* Creates a new signal. (This is usually done in the class initializer.)
+ *
* See g_signal_new() for details on allowed signal names.
+ *
* If c_marshaller is %NULL @g_cclosure_marshal_generic will be used as
* the marshaller for this signal.
*
@@ -9149,6 +9496,7 @@
* Overrides the class closure (i.e. the default handler) for the given signal
* for emissions on instances of @instance_type. @instance_type must be derived
* from the type to which the signal belongs.
+ *
* See g_signal_chain_from_overridden() and
* g_signal_chain_from_overridden_handler() for how to chain up to the
* parent class closure from inside the overridden one.
@@ -9165,6 +9513,7 @@
* given signal for emissions on instances of @instance_type with
* callabck @class_handler. @instance_type must be derived from the
* type to which the signal belongs.
+ *
* See g_signal_chain_from_overridden() and
* g_signal_chain_from_overridden_handler() for how to chain up to the
* parent class closure from inside the overridden one.
@@ -9218,9 +9567,11 @@
* @detail: the detail which the signal was emitted with.
*
* Stops a signal's current emission.
+ *
* This will prevent the default method from running, if the signal was
* %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after"
* flag).
+ *
* Prints a warning if used on a signal which isn't being emitted.
*/
@@ -9231,6 +9582,7 @@
* @detailed_signal: a string of the form "signal-name::detail".
*
* Stops a signal's current emission.
+ *
* This is just like g_signal_stop_emission() except it will look up the
* signal id for you.
*/
@@ -9242,6 +9594,7 @@
* @struct_offset: the offset of the member function of @itype's class structure which is to be invoked by the new closure
*
* Creates a new closure which invokes the function found at the offset
+ * @struct_offset in the class structure of the interface or classed type
* identified by @itype.
*
* Returns: a new #GCClosure
@@ -9254,6 +9607,7 @@
* @closure: a #GClosure
*
* Set the callback for a source as a #GClosure.
+ *
* If the source is not one of the standard GLib types, the @closure_callback
* and @closure_marshal fields of the #GSourceFuncs structure must have been
* filled in with pointers to appropriate functions.
@@ -9269,7 +9623,9 @@
* (If the source expects any other type of return value, it will return
* a 0/%NULL value; whatever g_value_init() initializes a #GValue to for
* that type.)
+ *
* If the source is not one of the standard GLib types, the
+ * @closure_callback and @closure_marshal fields of the #GSourceFuncs
* structure must have been filled in with pointers to appropriate
* functions.
*/
@@ -9377,6 +9733,7 @@
* Adds a function to be called after an interface vtable is
* initialized for any class (i.e. after the @interface_init member of
* #GInterfaceInfo has been called).
+ *
* This function is useful when you want to check an invariant that
* depends on the interfaces of a class. For instance, the
* implementation of #GObject uses this facility to check that an
@@ -9428,6 +9785,7 @@
*
* Return a newly allocated and 0-terminated array of type IDs, listing the
* child types of @type. The return value has to be g_free()ed after use.
+ *
* and 0-terminated array of child types.
*
* Returns: (array length=n_children) (transfer full): Newly allocated
@@ -9440,35 +9798,45 @@
* @private_size: size of private structure.
*
* Registers a private structure for an instantiatable type.
+ *
* When an object is allocated, the private structures for
* the type and all of its parent types are allocated
* sequentially in the same memory block as the public
* structures.
+ *
* Note that the accumulated size of the private structures of
* a type and all its parent types cannot excced 64kB.
+ *
* This function should be called in the type's class_init() function.
* The private structure can be retrieved using the
* G_TYPE_INSTANCE_GET_PRIVATE() macro.
+ *
* The following example shows attaching a private structure
* <structname>MyObjectPrivate</structname> to an object
* <structname>MyObject</structname> defined in the standard GObject
* fashion.
* type's class_init() function.
+ *
* |[
* typedef struct _MyObject MyObject;
* typedef struct _MyObjectPrivate MyObjectPrivate;
+ *
* struct _MyObject {
* GObject parent;
+ *
* MyObjectPrivate *priv;
* };
+ *
* struct _MyObjectPrivate {
* int some_field;
* };
+ *
* static void
* my_object_class_init (MyObjectClass *klass)
* {
* g_type_class_add_private (klass, sizeof (MyObjectPrivate));
* }
+ *
* static void
* my_object_init (MyObject *my_object)
* {
@@ -9476,10 +9844,12 @@
* MY_TYPE_OBJECT,
* MyObjectPrivate);
* }
+ *
* static int
* my_object_get_some_field (MyObject *my_object)
* {
* MyObjectPrivate *priv = my_object->priv;
+ *
* return priv->some_field;
* }
* ]|
@@ -9496,6 +9866,7 @@
* the classes reference count isn't incremented. As a consequence, this function
* may return %NULL if the class of the type passed in does not currently
* exist (hasn't been referenced before).
+ *
* structure for the given type ID or %NULL if the class does not
* currently exist.
*
@@ -9513,9 +9884,11 @@
* their parent classes as long as they are instantiated, the returned
* class will always exist. This function is essentially equivalent
* to:
+ *
* <programlisting>
* g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
* </programlisting>
+ *
* of @g_class.
*
* Returns: (type GObject.TypeClass) (transfer none): The parent class
@@ -9528,6 +9901,7 @@
*
* A more efficient version of g_type_class_peek() which works only for
* static types.
+ *
* structure for the given type ID or %NULL if the class does not
* currently exist or is dynamically loaded.
*
@@ -9541,7 +9915,9 @@
* @type: Type ID of a classed type.
*
* Increments the reference count of the class structure belonging to
+ * @type. This function will demand-create the class if it doesn't
* exist already.
+ *
* structure for the given type ID.
*
* Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass
@@ -9576,19 +9952,20 @@
*
* Creates and initializes an instance of @type if @type is valid and
* can be instantiated. The type system only performs basic allocation
+ * and structure setups for instances: actual instance creation should
* happen through functions supplied by the type's fundamental type
* implementation. So use of g_type_create_instance() is reserved for
* implementators of fundamental types only. E.g. instances of the
* #GObject hierarchy should be created via g_object_new() and
* <emphasis>never</emphasis> directly through
* g_type_create_instance() which doesn't handle things like singleton
+ * objects or object construction. Note: Do <emphasis>not</emphasis>
* use this function, unless you're implementing a fundamental
* type. Also language bindings should <emphasis>not</emphasis> use
* this function but g_object_new() instead.
+ *
* treatment by the fundamental type implementation.
*
- * And structure setups for instances: actual instance creation should
- * Objects or object construction. note: Do <emphasis>not</emphasis>
* Returns: An allocated and initialized instance, subject to further
*/
@@ -9599,6 +9976,8 @@
*
* If the interface type @g_type is currently in use, returns its
* default interface vtable.
+ *
+ *
* vtable for the interface, or %NULL if the type is not currently in
* use.
*
@@ -9613,6 +9992,7 @@
*
* Increments the reference count for the interface type @g_type,
* and returns the default interface vtable for the type.
+ *
* If the type is not currently in use, then the default vtable
* for the type will be created and initalized by calling
* the base interface init and default vtable init functions for
@@ -9621,6 +10001,8 @@
* Calling g_type_default_interface_ref() is useful when you
* want to make sure that signals and properties for an interface
* have been installed.
+ *
+ *
* vtable for the interface; call g_type_default_interface_unref()
* when you are done using the interface.
*
@@ -9661,6 +10043,7 @@
*
* Frees an instance of a type, returning it to the instance pool for
* the type, if there is one.
+ *
* Like g_type_create_instance(), this function is reserved for
* implementors of fundamental types.
*/
@@ -9697,6 +10080,7 @@
* register a new fundamental type with g_type_register_fundamental().
* The returned type ID represents the highest currently registered
* fundamental type identifier.
+ *
* or 0 if the type system ran out of fundamental type IDs.
*
* Returns: The nextmost fundamental type ID to be registered,
@@ -9709,6 +10093,7 @@
*
* Returns the #GTypePlugin structure for @type or
* %NULL if @type does not have a #GTypePlugin structure.
+ *
* dynamic type, %NULL otherwise.
*
* Returns: (transfer none): The corresponding plugin if @type is a
@@ -9722,6 +10107,7 @@
*
* Obtains data which has previously been attached to @type
* with g_type_set_qdata().
+ *
* Note that this does not take subtyping into account; data
* attached to one type with g_type_set_qdata() cannot
* be retrieved from a subtype using g_type_get_qdata().
@@ -9737,6 +10123,7 @@
* to initialize the type system and assorted other code portions
* (such as the various fundamental type implementations or the signal
* system).
+ *
* Since version 2.24 this also initializes the thread system
*/
@@ -9756,6 +10143,7 @@
*
* Adds @prerequisite_type to the list of prerequisites of @interface_type.
* This means that any type implementing @interface_type must also implement
+ * @prerequisite_type. Prerequisites can be thought of as an alternative to
* interface derivation (which GType doesn't support). An interface can have
* at most one instantiatable prerequisite type.
*/
@@ -9767,7 +10155,10 @@
* @interface_type: the #GType value of an interface type.
*
* Returns the #GTypePlugin structure for the dynamic interface
+ * @interface_type which has been added to @instance_type, or %NULL if
+ * @interface_type has not been added to @instance_type or does not
* have a #GTypePlugin structure. See g_type_add_interface_dynamic().
+ *
* interface @interface_type of @instance_type.
*
* Returns: (transfer none): the #GTypePlugin for the dynamic
@@ -9781,6 +10172,7 @@
*
* Returns the #GTypeInterface structure of an interface to which the
* passed in class conforms.
+ *
* structure of iface_type if implemented by @instance_class, %NULL
* otherwise
*
@@ -9796,6 +10188,7 @@
* of the instance type to which @g_iface belongs. This is useful when
* deriving the implementation of an interface from the parent type and
* then possibly overriding some methods.
+ *
* corresponding #GTypeInterface structure of the parent type of the
* instance type to which @g_iface belongs, or %NULL if the parent
* type doesn't conform to the interface.
@@ -9810,6 +10203,8 @@
* @n_prerequisites: (out) (allow-none): location to return the number of prerequisites, or %NULL
*
* Returns the prerequisites of an interfaces type.
+ *
+ *
* newly-allocated zero-terminated array of #GType containing
* the prerequisites of @interface_type
*
@@ -9826,6 +10221,7 @@
* Return a newly allocated and 0-terminated array of type IDs, listing the
* interface types that @type conforms to. The return value has to be
* g_free()ed after use.
+ *
* allocated and 0-terminated array of interface types.
*
* Returns: (array length=n_interfaces) (transfer full): Newly
@@ -9855,6 +10251,7 @@
* Registers an additional interface for a type, whose interface lives
* in the given type plugin. If the interface was already registered
* for the type in this plugin, nothing will be done.
+ *
* As long as any instances of the type exist, the type plugin will
* not be unloaded.
*/
@@ -9870,6 +10267,7 @@
* type plugin. If a type with name @type_name was previously registered,
* the #GType identifier for the type is returned, otherwise the type
* is newly registered, and the resulting #GType identifier returned.
+ *
* As long as any instances of the type exist, the type plugin will
* not be unloaded.
*
@@ -9888,6 +10286,7 @@
* type plugin. If a type with name @type_name was previously registered,
* the #GType identifier for the type is returned, otherwise the type
* is newly registered, and the resulting #GType identifier returned.
+ *
* As long as any instances of the type exist, the type plugin will
* not be unloaded.
*
@@ -9908,9 +10307,11 @@
* type plugin. If a type with name @type_name was previously registered,
* the #GType identifier for the type is returned, otherwise the type
* is newly registered, and the resulting #GType identifier returned.
+ *
* When reregistering a type (typically because a module is unloaded
* then reloaded, and reinitialized), @module and @parent_type must
* be the same as they were previously.
+ *
* As long as any instances of the type exist, the type plugin will
* not be unloaded.
*
@@ -9947,6 +10348,7 @@
* use count was zero before, the plugin will be loaded.
* If loading the plugin fails, the use count is reset to
* its prior value.
+ *
* loading the plugin failed.
*
* Returns: %FALSE if the plugin needed to be loaded and
@@ -9976,6 +10378,7 @@
* anchestry, return the type that @root_type is the immediate parent
* of. In other words, this function determines the type that is
* derived directly from @root_type which is also a base class of
+ * @leaf_type. Given a root type and a leaf type, this function can
* be used to determine the types and order in which the leaf type is
* descended from the root type.
*
@@ -10025,6 +10428,7 @@
* @plugin: a #GTypePlugin
*
* Calls the @unuse_plugin function from the #GTypePluginClass of
+ * @plugin. There should be no need to use this function outside of
* the GObject type system itself.
*/
@@ -10034,6 +10438,7 @@
* @plugin: a #GTypePlugin
*
* Calls the @use_plugin function from the #GTypePluginClass of
+ * @plugin. There should be no need to use this function outside of
* the GObject type system itself.
*/
@@ -10056,6 +10461,7 @@
* Queries the type system for information about a specific type.
* This function will fill in a user-provided structure to hold
* type-specific information. If an invalid #GType is passed in, the
+ * @type member of the #GTypeQuery is 0. All members filled into the
* #GTypeQuery structure should be considered constant and have to be
* left untouched.
*/
@@ -10069,6 +10475,7 @@
* @flags: Bitwise combination of #GTypeFlags values.
*
* Registers @type_name as the name of a new dynamic type derived from
+ * @parent_type. The type system uses the information contained in the
* #GTypePlugin structure pointed to by @plugin to manage the type and its
* instances (if not abstract). The value of @flags determines the nature
* (e.g. abstract or not) of the type.
@@ -10104,6 +10511,7 @@
* @flags: Bitwise combination of #GTypeFlags values.
*
* Registers @type_name as the name of a new static type derived from
+ * @parent_type. The type system uses the information contained in the
* #GTypeInfo structure pointed to by @info to manage the type and its
* instances (if not abstract). The value of @flags determines the nature
* (e.g. abstract or not) of the type.
@@ -10123,6 +10531,7 @@
* @flags: Bitwise combination of #GTypeFlags values.
*
* Registers @type_name as the name of a new static type derived from
+ * @parent_type. The value of @flags determines the nature (e.g.
* abstract or not) of the type. It works by filling a #GTypeInfo
* struct and calling g_type_register_static().
*
@@ -10171,6 +10580,8 @@
* Returns the location of the #GTypeValueTable associated with @type.
* <emphasis>Note that this function should only be used from source code
* that implements or has internal knowledge of the implementation of
+ * @type.</emphasis>
+ *
* %NULL if there is no #GTypeValueTable associated with @type.
*
* Returns: Location of the #GTypeValueTable associated with @type or
@@ -10287,6 +10698,7 @@
*
* Sort @value_array using @compare_func to compare the elements accoring to
* the semantics of #GCompareFunc.
+ *
* The current implementation uses Quick-Sort as sorting algorithm.
*
* Returns: (transfer none): the #GValueArray passed in as @value_array
@@ -10301,6 +10713,7 @@
*
* Sort @value_array using @compare_func to compare the elements accoring
* to the semantics of #GCompareDataFunc.
+ *
* The current implementation uses Quick-Sort as sorting algorithm.
*
* Rename to: g_value_array_sort
@@ -10323,9 +10736,9 @@
*
* Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting,
* the boxed value is duplicated and needs to be later freed with
+ * g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value),
* return_value);
*
- * G_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value),
* Returns: boxed contents of @value
*/
@@ -10337,6 +10750,7 @@
* Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing
* its reference count. If the contents of the #GValue are %NULL, then
* %NULL will be returned.
+ *
* should be unreferenced when no longer needed.
*
* Returns: (type GObject.Object) (transfer full): object content of @value,
@@ -10349,6 +10763,7 @@
*
* Get the contents of a %G_TYPE_PARAM #GValue, increasing its
* reference count.
+ *
* no longer needed.
*
* Returns: #GParamSpec content of @value, should be unreferenced when
@@ -10370,6 +10785,7 @@
* @value: a valid #GValue of type %G_TYPE_VARIANT
*
* Get the contents of a variant #GValue, increasing its refcount.
+ *
* g_variant_unref() when no longer needed
*
* Returns: variant contents of @value, should be unrefed using
@@ -10648,7 +11064,7 @@
/**
* g_value_set_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
- * @v_boxed: boxed value to be set
+ * @v_boxed: (allow-none): boxed value to be set
*
* Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
*/
@@ -10657,7 +11073,7 @@
/**
* g_value_set_boxed_take_ownership:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
- * @v_boxed: duplicated unowned boxed value to be set
+ * @v_boxed: (allow-none): duplicated unowned boxed value to be set
*
* This is an internal function introduced mainly for C marshallers.
*
@@ -10724,7 +11140,7 @@
/**
* g_value_set_instance:
* @value: An initialized #GValue structure.
- * @instance: the instance
+ * @instance: (allow-none): the instance
*
* Sets @value from an instantiatable type via the
* value_table's collect_value() function.
@@ -10761,14 +11177,16 @@
/**
* g_value_set_object:
* @value: a valid #GValue of %G_TYPE_OBJECT derived type
- * @v_object: (type GObject.Object): object value to be set
+ * @v_object: (type GObject.Object) (allow-none): object value to be set
*
* Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
+ *
* g_value_set_object() increases the reference count of @v_object
* (the #GValue holds a reference to @v_object). If you do not wish
* to increase the reference count of the object (i.e. you wish to
* pass your current reference to the #GValue because you no longer
* need it), use g_value_take_object() instead.
+ *
* It is important that your #GValue holds a reference to @v_object (either its
* own, or one it has taken) to ensure that the object won't be destroyed while
* the #GValue still exists).
@@ -10778,7 +11196,7 @@
/**
* g_value_set_object_take_ownership: (skip)
* @value: a valid #GValue of %G_TYPE_OBJECT derived type
- * @v_object: object value to be set
+ * @v_object: (allow-none): object value to be set
*
* This is an internal function introduced mainly for C marshallers.
*
@@ -10789,7 +11207,7 @@
/**
* g_value_set_param:
* @value: a valid #GValue of type %G_TYPE_PARAM
- * @param: the #GParamSpec to be set
+ * @param: (allow-none): the #GParamSpec to be set
*
* Set the contents of a %G_TYPE_PARAM #GValue to @param.
*/
@@ -10798,7 +11216,7 @@
/**
* g_value_set_param_take_ownership: (skip)
* @value: a valid #GValue of type %G_TYPE_PARAM
- * @param: the #GParamSpec to be set
+ * @param: (allow-none): the #GParamSpec to be set
*
* This is an internal function introduced mainly for C marshallers.
*
@@ -10818,7 +11236,7 @@
/**
* g_value_set_static_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
- * @v_boxed: static boxed value to be set
+ * @v_boxed: (allow-none): static boxed value to be set
*
* Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
* The boxed value is assumed to be static, and is thus not duplicated
@@ -10896,7 +11314,7 @@
/**
* g_value_set_variant:
* @value: a valid #GValue of type %G_TYPE_VARIANT
- * @variant: a #GVariant, or %NULL
+ * @variant: (allow-none): a #GVariant, or %NULL
*
* Set the contents of a variant #GValue to @variant.
* If the variant is floating, it is consumed.
@@ -10908,7 +11326,7 @@
/**
* g_value_take_boxed:
* @value: a valid #GValue of %G_TYPE_BOXED derived type
- * @v_boxed: duplicated unowned boxed value to be set
+ * @v_boxed: (allow-none): duplicated unowned boxed value to be set
*
* Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed
* and takes over the ownership of the callers reference to @v_boxed;
@@ -10921,12 +11339,13 @@
/**
* g_value_take_object: (skip)
* @value: a valid #GValue of %G_TYPE_OBJECT derived type
- * @v_object: object value to be set
+ * @v_object: (allow-none): object value to be set
*
* Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object
* and takes over the ownership of the callers reference to @v_object;
* the caller doesn't have to unref it any more (i.e. the reference
* count of the object is not increased).
+ *
* If you want the #GValue to hold its own reference to @v_object, use
* g_value_set_object() instead.
*
@@ -10937,7 +11356,7 @@
/**
* g_value_take_param: (skip)
* @value: a valid #GValue of type %G_TYPE_PARAM
- * @param: the #GParamSpec to be set
+ * @param: (allow-none): the #GParamSpec to be set
*
* Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes
* over the ownership of the callers reference to @param; the caller
@@ -10961,16 +11380,19 @@
/**
* g_value_take_variant:
* @value: a valid #GValue of type %G_TYPE_VARIANT
- * @variant: a #GVariant, or %NULL
+ * @variant: (allow-none): a #GVariant, or %NULL
*
* Set the contents of a variant #GValue to @variant, and takes over
* the ownership of the caller's reference to @variant;
* the caller doesn't have to unref it any more (i.e. the reference
* count of the variant is not increased).
+ *
* If @variant was floating then its floating reference is converted to
* a hard reference.
+ *
* If you want the #GValue to hold its own reference to @variant, use
* g_value_set_variant() instead.
+ *
* This is an internal function introduced mainly for C marshallers.
*
* Since: 2.26
@@ -10989,6 +11411,7 @@
* transformations into strings might reveal seemingly arbitrary
* results and shouldn't be relied upon for production code (such
* as rcfile value or object property serialization).
+ *
* Upon failing transformations, @dest_value is left untouched.
*
* Returns: Whether a transformation rule was found and could be applied.
@@ -11071,11 +11494,14 @@
*
* A type which can hold any UTF-32 or UCS-4 character code,
* also known as a Unicode code point.
+ *
* If you want to produce the UTF-8 representation of a #gunichar,
* use g_ucs4_to_utf8(). See also g_utf8_to_ucs4() for the reverse
* process.
+ *
* To print/scan values of this type as integer, use
* %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
+ *
* The notation to express a Unicode code point in running text is
* as a hexadecimal number with four to six digits and uppercase
* letters, prefixed by the string "U+". Leading zeros are omitted,
@@ -11083,6 +11509,7 @@
* For example, "U+0041 LATIN CAPITAL LETTER A". To print a code point
* in the U+-notation, use the format string "U+%04"G_GINT32_FORMAT"X".
* To scan, use the format string "U+%06"G_GINT32_FORMAT"X".
+ *
* |[
* gunichar c;
* sscanf ("U+0041", "U+%06"G_GINT32_FORMAT"X", &c)
@@ -11100,8 +11527,10 @@
* the BMP as pairs of 16bit numbers. Surrogate pairs cannot be stored
* in a single gunichar2 field, but all GLib functions accepting gunichar2
* arrays will correctly interpret surrogate pairs.</footnote>.
+ *
* To print/scan values of this type to/from text you need to convert
* to/from UTF-8, using g_utf16_to_utf8()/g_utf8_to_utf16().
+ *
* To print/scan values of this type as integer, use
* %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
