/************************************************************/
/**
+ * GAction:
+ *
+ * #GAction is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GAction:enabled:
*
* If @action is currently enabled.
* GAction:name:
*
* The name of the action. This is mostly meaningful for identifying
- * the action once it has been added to a #GActionGroup.
+ * the action once it has been added to a #GActionGroup. It is immutable.
*
* Since: 2.28
*/
* GAction:parameter-type:
*
* The type of the parameter that must be given when activating the
- * action.
+ * action. This is immutable, and may be %NULL if no parameter is needed when
+ * activating the action.
*
* Since: 2.28
*/
* GAction:state-type:
*
* The #GVariantType of the state that the action has, or %NULL if the
- * action is stateless.
+ * action is stateless. This is immutable.
*
* Since: 2.28
*/
* GActionEntry:
* @name: the name of the action
* @activate: the callback to connect to the "activate" signal of the
- * action
+ * action. Since GLib 2.40, this can be %NULL for stateful
+ * actions, in which case the default handler is used. For
+ * boolean-stated actions with no parameter, this is a
+ * toggle. For other state types (and parameter type equal
+ * to the state type) this will be a function that
+ * just calls @change_state (which you should provide).
* @parameter_type: the type of the parameter that must be passed to the
* activate function for this action, given as a single
* GVariant type string (or %NULL for no parameter)
- * @state: the initial state for this action, given in GVariant text
- * format. The state is parsed with no extra type information,
- * so type tags must be added to the string if they are
- * necessary.
+ * @state: the initial state for this action, given in
+ * [GVariant text format][gvariant-text]. The state is parsed
+ * with no extra type information, so type tags must be added to
+ * the string if they are necessary. Stateless actions should
+ * give %NULL here.
* @change_state: the callback to connect to the "change-state" signal
- * of the action
+ * of the action. All stateful actions should provide a
+ * handler here; stateless actions should not.
*
* This struct defines a single action. It is for use with
* g_action_map_add_action_entries().
/**
+ * GActionGroup:
+ *
+ * #GActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GActionGroup::action-added:
* @action_group: the #GActionGroup that changed
* @action_name: the name of the action in @action_group
/**
+ * GActionMap:
+ *
+ * #GActionMap is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GActionMapInterface:
* @lookup_action: the virtual function pointer for g_action_map_lookup_action()
* @add_action: the virtual function pointer for g_action_map_add_action()
/**
+ * GAppInfoMonitor::changed:
+ *
+ * Signal emitted when the app info database for changes (ie: newly installed
+ * or removed applications).
+ */
+
+
+/**
+ * GAppLaunchContext::launch-failed:
+ * @context: the object emitting the signal
+ * @startup_notify_id: the startup notification id for the failed launch
+ *
+ * The ::launch-failed signal is emitted when a #GAppInfo launch
+ * fails. The startup notification id is provided, so that the launcher
+ * can cancel the startup notification.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * GAppLaunchContext::launched:
+ * @context: the object emitting the signal
+ * @info: the #GAppInfo that was just launched
+ * @platform_data: additional platform-specific data for this launch
+ *
+ * The ::launched signal is emitted when a #GAppInfo is successfully
+ * launched. The @platform_data is an GVariant dictionary mapping
+ * strings to variants (ie a{sv}), which contains additional,
+ * platform-specific data about this launch. On UNIX, at least the
+ * "pid" and "startup-notification-id" keys will be present.
+ *
+ * Since: 2.36
+ */
+
+
+/**
+ * GApplication:
+ *
+ * #GApplication is an opaque data structure and can only be accessed
+ * using the following functions.
+ *
+ * Since: 2.28
+ */
+
+
+/**
* GApplication::activate:
* @application: the application
*
* decide to perform certain actions, including direct local handling
* (which may be useful for options like --version).
*
- * If the options have been "handled" then a non-negative value should
- * be returned. In this case, the return value is the exit status: 0
- * for success and a positive value for failure. -1 means to continue
- * normal processing.
- *
* In the event that the application is marked
* %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
* send the @option dictionary to the primary instance where it can be
* capabilities than what is provided here, but this should not
* normally be required.
*
+ * Returns: an exit code. If you have handled your options and want
+ * to exit the process, return a non-negative option, 0 for success,
+ * and a positive value for failure. To continue, return -1 to let
+ * the default option processing continue.
* Since: 2.40
*/
/**
+ * GApplication:is-busy:
+ *
+ * Whether the application is currently marked as busy through
+ * g_application_mark_busy() or g_application_bind_busy_property().
+ *
+ * Since: 2.44
+ */
+
+
+/**
* GApplicationClass:
* @startup: invoked on the primary instance immediately after registration
* @shutdown: invoked only on the registered primary instance immediately
* @dbus_unregister: invoked locally during unregistration, if the application
* is using its D-Bus backend. Use this to undo anything done by the
* @dbus_register vfunc. Since: 2.34
+ * @handle_local_options: invoked locally after the parsing of the commandline
+ * options has occurred.
*
* Virtual function table for #GApplication.
*
/**
+ * GApplicationCommandLine:
+ *
+ * #GApplicationCommandLine is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GApplicationCommandLineClass:
*
* The #GApplicationCommandLineClass-struct
/**
+ * GDBusActionGroup:
+ *
+ * #GDBusActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDBusAuthMechanism:credentials:
*
* If authenticating as a server, this property contains the
/**
+ * GDBusMenuModel:
+ *
+ * #GDBusMenuModel is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDBusMessage:
*
* The #GDBusMessage structure contains only private data and should
/**
+ * GDBusObject:
+ *
+ * #GDBusObject is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDBusObject::interface-added:
* @object: The #GDBusObject emitting the signal.
* @interface: The #GDBusInterface that was added.
/**
+ * GDBusObjectManager:
+ *
+ * #GDBusObjectManager is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDBusObjectManager::interface-added:
* @manager: The #GDBusObjectManager emitting the signal.
* @object: The #GDBusObject on which an interface was added.
/**
+ * GDesktopAppInfoLookup:
+ *
+ * #GDesktopAppInfoLookup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GDrive::changed:
* @drive: a #GDrive.
*
/**
+ * GIOExtension:
+ *
+ * #GIOExtension is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GIOExtensionPoint:
+ *
+ * #GIOExtensionPoint is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GIOModuleScope:
*
* Represents a scope for loading IO modules. A scope can be used for blocking
/**
+ * GListModel:
+ *
+ * #GListModel is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GListModel::items-changed:
+ * @list: the #GListModel that changed
+ * @position: the position at which @list changed
+ * @removed: the number of items removed
+ * @added: the number of items added
+ *
+ * This signal is emitted whenever items were added or removed to
+ * @list. At @position, @removed items were removed and @added items
+ * were added in their place.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GListModelInterface:
+ * @g_iface: parent #GTypeInterface
+ * @get_item_type: the virtual function pointer for g_list_model_get_item_type()
+ * @get_n_items: the virtual function pointer for g_list_model_get_n_items()
+ * @get_item: the virtual function pointer for g_list_model_get_item()
+ *
+ * The virtual function table for #GListModel.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GListStore:
+ *
+ * #GListStore is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GListStore:item-type:
+ *
+ * The type of items contained in this list store. Items must be
+ * subclasses of #GObject.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* GMemoryOutputStream:data:
*
* Pointer to buffer where data will be written.
/**
+ * GNetworkMonitor:connectivity:
+ *
+ * More detailed information about the host's network connectivity.
+ * See g_network_monitor_get_connectivity() and
+ * #GNetworkConnectivity for more details.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* GNetworkMonitor:network-available:
*
* Whether the network is considered available. That is, whether the
/**
+ * GNetworkMonitorInterface:
+ * @g_iface: The parent interface.
+ * @network_changed: the virtual function pointer for the
+ * GNetworkMonitor::network-changed signal.
+ * @can_reach: the virtual function pointer for g_network_monitor_can_reach()
+ * @can_reach_async: the virtual function pointer for
+ * g_network_monitor_can_reach_async()
+ * @can_reach_finish: the virtual function pointer for
+ * g_network_monitor_can_reach_finish()
+ *
+ * The virtual function table for #GNetworkMonitor.
+ *
+ * Since: 2.32
+ */
+
+
+/**
* GNetworkService:
*
* A #GSocketConnectable for resolving a SRV record and connecting to
/**
+ * GProxyAddressClass:
+ *
+ * Class structure for #GProxyAddress.
+ *
+ * Since: 2.26
+ */
+
+
+/**
* GProxyAddressEnumerator:default-port:
*
* The default port to use if #GProxyAddressEnumerator:uri does not
/**
+ * GProxyResolverInterface:
+ * @g_iface: The parent interface.
+ * @is_supported: the virtual function pointer for g_proxy_resolver_is_supported()
+ * @lookup: the virtual function pointer for g_proxy_resolver_lookup()
+ * @lookup_async: the virtual function pointer for
+ * g_proxy_resolver_lookup_async()
+ * @lookup_finish: the virtual function pointer for
+ * g_proxy_resolver_lookup_finish()
+ *
+ * The virtual function table for #GProxyResolver.
+ */
+
+
+/**
+ * GRemoteActionGroup:
+ *
+ * #GRemoteActionGroup is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GRemoteActionGroupInterface:
* @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()
* @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full()
/**
+ * GSettings:
+ *
+ * #GSettings is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GSettings::change-event:
* @settings: the object on which the signal was emitted
* @keys: (array length=n_keys) (element-type GQuark) (allow-none):
/**
+ * GSettingsSchemaKey:
+ *
+ * #GSettingsSchemaKey is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GSettingsSchemaSource:
*
* This is an opaque structure type. You may not access it directly.
/**
+ * GSimpleAction:
+ *
+ * #GSimpleAction is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GSimpleAction::activate:
* @simple: the #GSimpleAction
* @parameter: (allow-none): the parameter to the activation
/**
+ * GSimpleIOStream:
+ *
+ * A wrapper around a #GInputStream and a #GOutputStream.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GSimpleIOStream:input-stream:
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * GSimpleIOStream:output-stream:
+ *
+ * Since: 2.44
+ */
+
+
+/**
* GSimplePermission:
*
* #GSimplePermission is an opaque data structure. There are no methods
/**
+ * GStaticResource:
+ *
+ * #GStaticResource is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GTask:
*
* The opaque object representing a synchronous or asynchronous task
/**
+ * GTask:completed:
+ *
+ * Whether the task has completed, meaning its callback (if set) has been
+ * invoked. This can only happen after g_task_return_pointer(),
+ * g_task_return_error() or one of the other return functions have been called
+ * on the task.
+ *
+ * This property is guaranteed to change from %FALSE to %TRUE exactly once.
+ *
+ * The #GObject::notify signal for this change is emitted in the same main
+ * context as the task’s callback, immediately after that callback is invoked.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* GTaskThreadFunc:
* @task: the #GTask
* @source_object: (type GObject): @task's source object
/**
+ * GTcpWrapperConnection:
+ *
+ * #GTcpWrapperConnection is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GTestDBus:
*
* The #GTestDBus structure contains only private data and
/**
- * GTlsClientConnection:accepted-cas:
+ * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray)
*
* A list of the distinguished names of the Certificate Authorities
* that the server will accept client certificates signed by. If the
/**
* GTlsClientConnection:use-ssl3:
*
- * If %TRUE, tells the connection to use SSL 3.0 rather than trying
- * to negotiate the best version of TLS or SSL to use. This can be
- * used when talking to servers that don't implement version
- * negotiation correctly and therefore refuse to handshake at all with
- * a "modern" TLS handshake.
+ * If %TRUE, tells the connection to use a fallback version of TLS
+ * or SSL, rather than trying to negotiate the best version of TLS
+ * to use. This can be used when talking to servers that don't
+ * implement version negotiation correctly and therefore refuse to
+ * handshake at all with a "modern" TLS handshake.
+ *
+ * Despite the property name, the fallback version is not
+ * necessarily SSL 3.0; if SSL 3.0 has been disabled, the
+ * #GTlsClientConnection will use the next highest available version
+ * (normally TLS 1.0) as the fallback version.
*
* Since: 2.28
*/
/**
+ * GUnixConnection:
+ *
+ * #GUnixConnection is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GUnixCredentialsMessage:credentials:
*
* The credentials stored in the message.
/**
+ * GUnixFDList:
+ *
+ * #GUnixFDList is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
+ * GUnixFDMessage:
+ *
+ * #GUnixFDMessage is an opaque data structure and can only be accessed
+ * using the following functions.
+ */
+
+
+/**
* GUnixInputStream:close-fd:
*
* Whether to close the file descriptor when the stream is closed.
/**
+ * GUnixMountType:
+ * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_CDROM: CDROM UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_ZIP: ZIP UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_CF: Compact Flash UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_SM: Smart Media UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_IPOD: iPod UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_HD: Hard drive UNIX mount type.
+ *
+ * Types of UNIX mounts.
+ */
+
+
+/**
* GUnixOutputStream:close-fd:
*
* Whether to close the file descriptor when the stream is closed.
* (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
* for an desktop-file based application with Exec key `totem
- * \%U` and a single URI, `sftp://foo/file.avi`, then
+ * %U` and a single URI, `sftp://foo/file.avi`, then
* `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
* only work if a set of suitable GIO extensions (such as gvfs 2.26
* compiled with FUSE support), is available and operational; if this
* credential type is a struct cmsgcred. This corresponds
* to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
*
+ * On NetBSD, the native credential type is a struct unpcbid.
+ * This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID.
+ *
* On OpenBSD, the native credential type is a struct sockpeercred.
* This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
*
* processes owned by the same uid as the server, you would use a
* signal handler like the following:
*
- * |[
+ * |[<!-- language="C" -->
* static gboolean
* on_authorize_authenticated_peer (GDBusAuthObserver *observer,
* GIOStream *stream,
* 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(),
+ * a 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.
*
* As an exception to the usual GLib rule that a particular object must not
* 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:
+ * It is highly recommended to use asynchronous calls when running within a
+ * shared main loop, such as in the main thread of an application. This avoids
+ * I/O operations blocking other sources on the main loop from being dispatched.
+ * Synchronous I/O operations should be performed from worker threads. See the
+ * [introduction to asynchronous programming section][async-programming] for
+ * more.
+ *
+ * Some #GFile operations almost always take a noticeable amount of time, and
+ * so do not have synchronous analogs. 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.
* implements methods for getting information that all files should
* contain, and allows for manipulation of extended attributes.
*
- * See [GFileAttribute][gio-GFileAttribute for more information on how
+ * See [GFileAttribute][gio-GFileAttribute] for more information on how
* GIO handles file attributes.
*
* To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
/**
+ * SECTION:glistmodel
+ * @title: GListModel
+ * @short_description: An interface describing a dynamic list of objects
+ * @include: gio/gio.h
+ * @see_also: #GListStore
+ *
+ * #GListModel is an interface that represents a mutable list of
+ * #GObjects. Its main intention is as a model for various widgets in
+ * user interfaces, such as list views, but it can also be used as a
+ * convenient method of returning lists of data, with support for
+ * updates.
+ *
+ * Each object in the list may also report changes in itself via some
+ * mechanism (normally the #GObject::notify signal). Taken together
+ * with the #GListModel::items-changed signal, this provides for a list
+ * that can change its membership, and in which the members can change
+ * their individual properties.
+ *
+ * A good example would be the list of visible wireless network access
+ * points, where each access point can report dynamic properties such as
+ * signal strength.
+ *
+ * It is important to note that the #GListModel itself does not report
+ * changes to the individual items. It only reports changes to the list
+ * membership. If you want to observe changes to the objects themselves
+ * then you need to connect signals to the objects that you are
+ * interested in.
+ *
+ * All items in a #GListModel are of (or derived from) the same type.
+ * g_list_model_get_item_type() returns that type. The type may be an
+ * interface, in which case all objects in the list must implement it.
+ *
+ * The semantics are close to that of an array:
+ * g_list_model_get_length() returns the number of items in the list and
+ * g_list_model_get_item() returns an item at a (0-based) position. In
+ * order to allow implementations to calculate the list length lazily,
+ * you can also iterate over items: starting from 0, repeatedly call
+ * g_list_model_get_item() until it returns %NULL.
+ *
+ * An implementation may create objects lazily, but must take care to
+ * return the same object for a given position until all references to
+ * it are gone.
+ *
+ * On the other side, a consumer is expected only to hold references on
+ * objects that are currently "user visible", in order to faciliate the
+ * maximum level of laziness in the implementation of the list and to
+ * reduce the required number of signal connections at a given time.
+ *
+ * This interface is intended only to be used from a single thread. The
+ * thread in which it is appropriate to use it depends on the particular
+ * implementation, but typically it will be from the thread that owns
+ * the [thread-default main context][g-main-context-push-thread-default]
+ * in effect at the time that the model was created.
+ */
+
+
+/**
+ * SECTION:gliststore
+ * @title: GListStore
+ * @short_description: A simple implementation of #GListModel
+ * @include: gio/gio.h
+ *
+ * #GListStore is a simple implementation of #GListModel that stores all
+ * items in memory.
+ *
+ * It provides insertions, deletions, and lookups in logarithmic time
+ * with a fast path for the common case of iterating the list linearly.
+ */
+
+
+/**
* SECTION:gloadableicon
* @short_description: Loadable Icons
* @include: gio/gio.h
* the names must begin with a lowercase character, must not end
* with a '-', and must not contain consecutive dashes.
*
+ * GSettings supports change notification. The primary mechanism to
+ * watch for changes is to connect to the "changed" signal. You can
+ * optionally watch for changes on only a single key by using a signal
+ * detail. Signals are only guaranteed to be emitted for a given key
+ * after you have read the value of that key while a signal handler was
+ * connected for that key. Signals may or may not be emitted in the
+ * case that the key "changed" to the value that you had previously
+ * read. Signals may be reported in additional cases as well and the
+ * "changed" signal should really be treated as "may have changed".
+ *
* 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
* </key>
*
* <key name='flags-key' flags='org.gtk.Test.myflags'>
- * <default>["flag1",flag2"]</default>
+ * <default>["flag1","flag2"]</default>
* </key>
* </schema>
* </schemalist>
/**
+ * SECTION:gsimpleiostream
+ * @short_description: A wrapper around an input and an output stream.
+ * @include: gio/gio.h
+ * @see_also: #GIOStream
+ *
+ * GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and
+ * #GOutputStream. This allows any pair of input and output streams to be used
+ * with #GIOStream methods.
+ *
+ * This is useful when you obtained a #GInputStream and a #GOutputStream
+ * by other means, for instance creating them with platform specific methods as
+ * g_unix_input_stream_new() or g_win32_input_stream_new(), and you want
+ * to take advantage of the methods provided by #GIOStream.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* SECTION:gsimplepermission
* @title: GSimplePermission
* @short_description: A GPermission that doesn't change value
* account the fact that your program will not automatically be killed
* if it tries to write to %stdout after it has been closed.
*
+ * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use
+ * a #GSocket concurrently from multiple threads, you must implement your own
+ * locking.
+ *
* Since: 2.22
*/
* task = g_task_new (self, cancellable, callback, user_data);
* g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free);
* g_task_run_in_thread (task, bake_cake_thread);
+ * g_object_unref (task);
* }
*
* Cake *
* @title: GTlsBackend
* @short_description: TLS backend implementation
* @include: gio/gio.h
+ *
+ * TLS (Transport Layer Security, aka SSL) backend
+ *
+ * Since: 2.28
*/
/**
+ * _g_dbus_initialize:
+ *
+ * Does various one-time init things such as
+ *
+ * - registering the G_DBUS_ERROR error domain
+ * - parses the G_DBUS_DEBUG environment variable
+ */
+
+
+/**
+ * _g_file_attribute_value_as_string:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Converts a #GFileAttributeValue to a string for display.
+ * The returned string should be freed when no longer needed.
+ *
+ * Returns: a string from the @attr, %NULL on error, or "<invalid>"
+ * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID.
+ */
+
+
+/**
+ * _g_file_attribute_value_clear:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Clears the value of @attr and sets its type to
+ * %G_FILE_ATTRIBUTE_TYPE_INVALID.
+ */
+
+
+/**
+ * _g_file_attribute_value_free:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Frees the memory used by @attr.
+ */
+
+
+/**
+ * _g_file_attribute_value_get_boolean:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the boolean value from a file attribute value. If the value is not the
+ * right type then %FALSE will be returned.
+ *
+ * Returns: the boolean value contained within the attribute, or %FALSE.
+ */
+
+
+/**
+ * _g_file_attribute_value_get_byte_string:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the byte string from a file attribute value. If the value is not the
+ * right type then %NULL will be returned.
+ *
+ * Returns: the byte string contained within the attribute or %NULL.
+ */
+
+
+/**
+ * _g_file_attribute_value_get_int32:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the signed 32-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
+ *
+ * Returns: the signed 32-bit integer from the attribute, or 0.
+ */
+
+
+/**
+ * _g_file_attribute_value_get_int64:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the signed 64-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
+ *
+ * Returns: the signed 64-bit integer from the attribute, or 0.
+ */
+
+
+/**
+ * _g_file_attribute_value_get_object:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the GObject from a file attribute value. If the value
+ * is not the right type then %NULL will be returned.
+ *
+ * Returns: the GObject from the attribute, or %NULL.
+ */
+
+
+/**
+ * _g_file_attribute_value_get_string:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the string from a file attribute value. If the value is not the
+ * right type then %NULL will be returned.
+ *
+ * Returns: the UTF-8 string value contained within the attribute, or %NULL.
+ */
+
+
+/**
+ * _g_file_attribute_value_get_uint32:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the unsigned 32-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
+ *
+ * Returns: the unsigned 32-bit integer from the attribute, or 0.
+ */
+
+
+/**
+ * _g_file_attribute_value_get_uint64:
+ * @attr: a #GFileAttributeValue.
+ *
+ * Gets the unsigned 64-bit integer from a file attribute value. If the value
+ * is not the right type then 0 will be returned.
+ *
+ * Returns: the unsigned 64-bit integer from the attribute, or 0.
+ */
+
+
+/**
+ * _g_file_attribute_value_new:
+ *
+ * Creates a new file attribute.
+ *
+ * Returns: a #GFileAttributeValue.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_boolean:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #gboolean to set within the type.
+ *
+ * Sets the attribute value to the given boolean value.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_byte_string:
+ * @attr: a #GFileAttributeValue.
+ * @string: a byte string to set within the type.
+ *
+ * Sets the attribute value to a given byte string.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_int32:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #gint32 to set within the type.
+ *
+ * Sets the attribute value to the given signed 32-bit integer.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_int64:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #gint64 to set within the type.
+ *
+ * Sets the attribute value to a given signed 64-bit integer.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_object:
+ * @attr: a #GFileAttributeValue.
+ * @obj: a #GObject.
+ *
+ * Sets the attribute to contain the value @obj.
+ * The @attr references the GObject internally.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_string:
+ * @attr: a #GFileAttributeValue.
+ * @string: a UTF-8 string to set within the type.
+ *
+ * Sets the attribute value to a given UTF-8 string.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_uint32:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #guint32 to set within the type.
+ *
+ * Sets the attribute value to the given unsigned 32-bit integer.
+ */
+
+
+/**
+ * _g_file_attribute_value_set_uint64:
+ * @attr: a #GFileAttributeValue.
+ * @value: a #guint64 to set within the type.
+ *
+ * Sets the attribute value to a given unsigned 64-bit integer.
+ */
+
+
+/**
* _g_freedesktop_dbus_call_add_match:
* @proxy: A #_GFreedesktopDBusProxy.
* @arg_rule: Argument to pass with the method invocation.
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Returns: (transfer full): the state range hint
+ * Returns: (nullable) (transfer full): the state range hint
* Since: 2.28
*/
* possible for an action to be removed and for a new action to be added
* with the same name but a different parameter type.
*
- * Returns: the parameter type
+ * Returns: (nullable): the parameter type
* Since: 2.28
*/
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Returns: (allow-none): the current state of the action
+ * Returns: (nullable): the current state of the action
* Since: 2.28
*/
* The return value (if non-%NULL) should be freed with
* g_variant_unref() when it is no longer required.
*
- * Returns: (transfer full): the state range hint
+ * Returns: (nullable) (transfer full): the state range hint
* Since: 2.28
*/
* possible for an action to be removed and for a new action to be added
* with the same name but a different state type.
*
- * Returns: (transfer full): the state type, if the action is stateful
+ * Returns: (nullable) (transfer full): the state type, if the action
+ * is stateful
* Since: 2.28
*/
/**
+ * g_application_add_main_option:
+ * @application: the #GApplication
+ * @long_name: the long name of an option used to specify it in a commandline
+ * @short_name: the short name of an option
+ * @flags: flags from #GOptionFlags
+ * @arg: the type of the option, as a #GOptionArg
+ * @description: the description for the option in `--help` output
+ * @arg_description: (nullable): the placeholder to use for the extra argument
+ * parsed by the option in `--help` output
+ *
+ * Add an option to be handled by @application.
+ *
+ * Calling this function is the equivalent of calling
+ * g_application_add_main_option_entries() with a single #GOptionEntry
+ * that has its arg_data member set to %NULL.
+ *
+ * The parsed arguments will be packed into a #GVariantDict which
+ * is passed to #GApplication::handle-local-options. If
+ * %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also
+ * be sent to the primary instance. See
+ * g_application_add_main_option_entries() for more details.
+ *
+ * See #GOptionEntry for more documentation of the arguments.
+ *
+ * Since: 2.42
+ */
+
+
+/**
* g_application_add_main_option_entries:
* @application: a #GApplication
- * @entries: a %NULL-terminated list of #GOptionEntrys
+ * @entries: (array zero-terminated=1) (element-type GOptionEntry): a
+ * %NULL-terminated list of #GOptionEntrys
*
* Adds main option entries to be handled by @application.
*
/**
+ * g_application_bind_busy_property:
+ * @application: a #GApplication
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of a boolean property of @object
+ *
+ * Marks @application as busy (see g_application_mark_busy()) while
+ * @property on @object is %TRUE.
+ *
+ * The binding holds a reference to @application while it is active, but
+ * not to @object. Instead, the binding is destroyed when @object is
+ * finalized.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* g_application_command_line_create_file_for_arg:
* @cmdline: a #GApplicationCommandLine
* @arg: an argument from @cmdline
*
* For local invocation, it will be %NULL.
*
- * Returns: (allow-none): the platform data, or %NULL
+ * Returns: (nullable): the platform data, or %NULL
* Since: 2.28
*/
/**
+ * g_application_get_is_busy:
+ * @application: a #GApplication
+ *
+ * Gets the application's current busy state, as set through
+ * g_application_mark_busy() or g_application_bind_busy_property().
+ *
+ * Returns: %TRUE if @application is currenty marked as busy
+ * Since: 2.44
+ */
+
+
+/**
* g_application_get_is_registered:
* @application: a #GApplication
*
/**
+ * g_application_get_resource_base_path:
+ * @application: a #GApplication
+ *
+ * Gets the resource base path of @application.
+ *
+ * See g_application_set_resource_base_path() for more information.
+ *
+ * Returns: (nullable): the base resource path, if one is set
+ * Since: 2.42
+ */
+
+
+/**
* g_application_hold:
* @application: a #GApplication
*
* use.
*
* This function sets the prgname (g_set_prgname()), if not already set,
- * to the basename of argv[0]. Since 2.38, if %G_APPLICATION_IS_SERVICE
- * is specified, the prgname is set to the application ID. The main
- * impact of this is is that the wmclass of windows created by Gtk+ will
- * be set accordingly, which helps the window manager determine which
- * application is showing the window.
+ * to the basename of argv[0].
*
* Since 2.40, applications that are not explicitly flagged as services
* or launchers (ie: neither %G_APPLICATION_IS_SERVICE or
/**
+ * g_application_set_resource_base_path:
+ * @application: a #GApplication
+ * @resource_path: (nullable): the resource path to use
+ *
+ * Sets (or unsets) the base resource path of @application.
+ *
+ * The path is used to automatically load various [application
+ * resources][gresource] such as menu layouts and action descriptions.
+ * The various types of resources will be found at fixed names relative
+ * to the given base path.
+ *
+ * By default, the resource base path is determined from the application
+ * ID by prefixing '/' and replacing each '.' with '/'. This is done at
+ * the time that the #GApplication object is constructed. Changes to
+ * the application ID after that point will not have an impact on the
+ * resource base path.
+ *
+ * As an example, if the application has an ID of "org.example.app" then
+ * the default resource base path will be "/org/example/app". If this
+ * is a #GtkApplication (and you have not manually changed the path)
+ * then Gtk will then search for the menus of the application at
+ * "/org/example/app/gtk/menus.ui".
+ *
+ * See #GResource for more information about adding resources to your
+ * application.
+ *
+ * You can disable automatic resource loading functionality by setting
+ * the path to %NULL.
+ *
+ * Changing the resource base path once the application is running is
+ * not recommended. The point at which the resource path is consulted
+ * for forming paths for various purposes is unspecified.
+ *
+ * Since: 2.42
+ */
+
+
+/**
+ * g_application_unbind_busy_property:
+ * @application: a #GApplication
+ * @object: (type GObject.Object): a #GObject
+ * @property: the name of a boolean property of @object
+ *
+ * Destroys a binding between @property and the busy state of
+ * @application that was previously created with
+ * g_application_bind_busy_property().
+ *
+ * Since: 2.44
+ */
+
+
+/**
* g_application_unmark_busy:
* @application: a #GApplication
*
/**
* g_cancellable_cancel:
- * @cancellable: a #GCancellable object.
+ * @cancellable: (nullable): a #GCancellable object.
*
* Will set @cancellable to cancelled, and will emit the
* #GCancellable::cancelled signal. (However, see the warning about
* 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
+ * If @cancellable is %NULL, this function returns immediately for convenience.
+ *
+ * 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,
* then the operation's #GAsyncReadyCallback will not be invoked until
*
* Gets the top cancellable from the stack.
*
- * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
- * if the stack is empty.
+ * Returns: (nullable) (transfer none): a #GCancellable from the top
+ * of the stack, or %NULL if the stack is empty.
*/
*
* If cancellable is currently in use by any cancellable operation
* then the behavior of this function is undefined.
+ *
+ * Note that it is generally not a good idea to reuse an existing
+ * cancellable for more operations after it has been cancelled once,
+ * as this function might tempt you to do. The recommended practice
+ * is to drop the reference to a cancellable after cancelling it,
+ * and let it die with the outstanding async operations. You should
+ * create a fresh cancellable for further async operations.
*/
* For convenience, you can call this with a %NULL #GCancellable,
* in which case the source will never trigger.
*
+ * The new #GSource will hold a reference to the #GCancellable.
+ *
* Returns: (transfer full): the new #GSource.
* Since: 2.28
*/
*
* Tries to find a content type based on the mime type name.
*
- * Returns: (allow-none): Newly allocated string with content type
- * or %NULL. Free with g_free()
+ * Returns: (nullable): Newly allocated string with content type or
+ * %NULL. Free with g_free()
* Since: 2.18
*/
*
* Gets the mime type for the content type, if one is registered.
*
- * Returns: (allow-none): the registered mime type for the given @type,
+ * Returns: (nullable): the registered mime type for the given @type,
* or %NULL if unknown.
*/
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
- * 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: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
+ * a 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.
*/
* string encoding in g_data_input_stream_read_line() applies here as
* well.
*
- * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
- * 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: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8):
+ * a 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.
* Since: 2.20
*/
* Finish an asynchronous call started by
* g_data_input_stream_read_line_async().
*
- * Returns: (transfer full): a string 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. For UTF-8 conversion errors, the set error domain is
- * %G_CONVERT_ERROR. If there's no content to read, it will still
- * return %NULL, but @error won't be set.
+ * Returns: (nullable) (transfer full): a string 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. For UTF-8 conversion errors, the set
+ * error domain is %G_CONVERT_ERROR. If there's no content to read,
+ * it will still return %NULL, but @error won't be set.
* Since: 2.30
*/
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * Returns: (transfer full): a NUL terminated UTF-8 string 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. For UTF-8 conversion errors,
- * the set error domain is %G_CONVERT_ERROR. If there's no content to
- * read, it will still return %NULL, but @error won't be set.
+ * Returns: (nullable) (transfer full): a NUL terminated UTF-8 string
+ * 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. For UTF-8
+ * conversion errors, the set error domain is %G_CONVERT_ERROR. If
+ * there's no content to read, it will still return %NULL, but @error
+ * won't be set.
* Since: 2.30
*/
*
* Gets the body of a message.
*
- * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
+ * Returns: (transfer none): A #GVariant or %NULL if the body is
+ * empty. Do not free, it is owned by @message.
* Since: 2.26
*/
* #GObject::notify signal to track changes to the
* #GDBusObjectManagerClient:name-owner property.
*
- * Returns: The name owner or %NULL if no name owner exists. Free with
- * g_free().
+ * Returns: (nullable): The name owner or %NULL if no name owner
+ * exists. Free with g_free().
* Since: 2.30
*/
/**
+ * g_desktop_app_info_get_implementations:
+ * @interface: the name of the interface
+ *
+ * Gets all applications that implement @interface.
+ *
+ * An application implements an interface if that interface is listed in
+ * the Implements= line of the desktop file of the application.
+ *
+ * Returns: (element-type GDesktopAppInfo) (transfer full): a list of #GDesktopAppInfo
+ * objects.
+ * Since: 2.42
+ */
+
+
+/**
* g_desktop_app_info_get_is_hidden:
* @info: a #GDesktopAppInfo.
*
/**
* g_desktop_app_info_get_show_in:
* @info: a #GDesktopAppInfo
- * @desktop_env: a string specifying a desktop name
+ * @desktop_env: (nullable): 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
* `OnlyShowIn` and `NotShowIn` keys.
*
- * If @desktop_env is %NULL, then the name of the desktop set with
- * g_desktop_app_info_set_desktop_env() is used.
+ * @desktop_env should typically be given as %NULL, in which case the
+ * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want
+ * to override the default mechanism then you may specify @desktop_env,
+ * but this is not recommended.
*
* Note that g_app_info_should_show() for @info will include this check (with
* %NULL for @desktop_env) as well as additional checks.
* `OnlyShowIn` and `NotShowIn`
* desktop entry fields.
*
- * The
- * [Desktop Menu specification](http://standards.freedesktop.org/menu-spec/latest/)
- * recognizes the following:
- * - GNOME
- * - KDE
- * - ROX
- * - XFCE
- * - LXDE
- * - Unity
- * - Old
- *
* Should be called only once; subsequent calls are ignored.
+ *
+ * Deprecated: 2.42: do not use this API. Since 2.42 the value of the
+ * `XDG_CURRENT_DESKTOP` environment variable will be used.
*/
/**
+ * g_file_attribute_value_dup:
+ * @other: a #GFileAttributeValue to duplicate.
+ *
+ * Duplicates a file attribute.
+ *
+ * Returns: a duplicate of the @other.
+ */
+
+
+/**
+ * g_file_attribute_value_set:
+ * @attr: a #GFileAttributeValue to set the value in.
+ * @new_value: a #GFileAttributeValue to get the value from.
+ *
+ * Sets an attribute's value from another attribute.
+ */
+
+
+/**
* g_file_copy:
* @source: input #GFile
* @destination: destination #GFile
* 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.
+ * just like in g_file_copy(). The callback will run in the default main context
+ * of the thread calling g_file_copy_async() — the same context as @callback is
+ * run in.
*
* When the operation is finished, @callback will be called. You can then call
* g_file_copy_finish() to get the result of the operation.
/**
+ * g_file_enumerator_iterate:
+ * @direnum: an open #GFileEnumerator
+ * @out_info: (out) (transfer none) (allow-none): Output location for the next #GFileInfo, or %NULL
+ * @out_child: (out) (transfer none) (allow-none): Output location for the next #GFile, or %NULL
+ * @cancellable: a #GCancellable
+ * @error: a #GError
+ *
+ * This is a version of g_file_enumerator_next_file() that's easier to
+ * use correctly from C programs. With g_file_enumerator_next_file(),
+ * the gboolean return value signifies "end of iteration or error", which
+ * requires allocation of a temporary #GError.
+ *
+ * In contrast, with this function, a %FALSE return from
+ * gs_file_enumerator_iterate() *always* means
+ * "error". End of iteration is signaled by @out_info or @out_child being %NULL.
+ *
+ * Another crucial difference is that the references for @out_info and
+ * @out_child are owned by @direnum (they are cached as hidden
+ * properties). You must not unref them in your own code. This makes
+ * memory management significantly easier for C code in combination
+ * with loops.
+ *
+ * Finally, this function optionally allows retrieving a #GFile as
+ * well.
+ *
+ * You must specify at least one of @out_info or @out_child.
+ *
+ * The code pattern for correctly using g_file_enumerator_iterate() from C
+ * is:
+ *
+ * |[
+ * direnum = g_file_enumerate_children (file, ...);
+ * while (TRUE)
+ * {
+ * GFileInfo *info;
+ * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
+ * goto out;
+ * if (!info)
+ * break;
+ * ... do stuff with "info"; do not unref it! ...
+ * }
+ *
+ * out:
+ * g_object_unref (direnum); // Note: frees the last @info
+ * ]|
+ *
+ * Since: 2.44
+ */
+
+
+/**
* g_file_enumerator_next_file:
* @enumerator: a #GFileEnumerator.
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* enumerator is at the end, %NULL will be returned and @error will
* be unset.
*
- * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
- * Free the returned object with g_object_unref() when no longer needed.
+ * Returns: (nullable) (transfer full): A #GFileInfo or %NULL on error
+ * or end of enumerator. Free the returned object with
+ * g_object_unref() when no longer needed.
*/
*
* Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
*
- * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
+ * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfos. You must free the list with
* g_list_free() and unref the infos with g_object_unref() when you're
* done with them.
*/
* @file1: the first #GFile
* @file2: the second #GFile
*
- * Checks equality of two given #GFiles.
+ * Checks if the two given #GFiles refer to the same file.
*
* Note that two #GFiles that differ can still refer to the same
* file on the filesystem due to various forms of filename
* This call does no blocking I/O.
*
* Returns: %TRUE if @file1 and @file2 are equal.
- * %FALSE if either is not a #GFile.
*/
*
* This call does no blocking I/O.
*
- * Returns: string containing the #GFile's base name, or %NULL
- * if given #GFile is invalid. The returned string should be
+ * Returns: (nullable): string containing the #GFile's base name, or
+ * %NULL if given #GFile is invalid. The returned string should be
* freed with g_free() when no longer needed.
*/
*
* This call does no blocking I/O.
*
- * Returns: (transfer full): a #GFile structure to the
- * parent of the given #GFile or %NULL if there is
- * no parent. Free the returned object with g_object_unref().
+ * Returns: (nullable) (transfer full): a #GFile structure to the
+ * parent of the given #GFile or %NULL if there is no parent. Free
+ * the returned object with g_object_unref().
*/
*
* This call does no blocking I/O.
*
- * Returns: string containing the #GFile's path, or %NULL if
- * no such path exists. The returned string should be
- * freed with g_free() when no longer needed.
+ * Returns: (nullable): string containing the #GFile's path, or %NULL
+ * if no such path exists. The returned string should be freed
+ * with g_free() when no longer needed.
*/
*
* This call does no blocking I/O.
*
- * Returns: string with the relative path from @descendant
- * 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.
+ * Returns: (nullable): string with the relative path from @descendant
+ * 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.
*/
* so a path like /foo is not considered a prefix of /foobar, only
* of /foo/bar.
*
+ * A #GFile is not a prefix of itself. If you want to check for
+ * equality, use g_file_equal().
+ *
* 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
*
* Lists the file info structure's attributes.
*
- * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the
- * possible attribute types for the given @name_space, or
- * %NULL on error.
+ * Returns: (nullable) (array zero-terminated=1) (transfer full): a
+ * null-terminated array of strings of all of the possible attribute
+ * types for the given @name_space, or %NULL on error.
*/
* 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
- * that the file has been changed since you last read it. You can get
- * the new etag from g_file_output_stream_get_etag() after you've
- * 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 you pass in a non-%NULL @etag value and @file already exists, 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 that the file has been changed since you last read
+ * it. You can get the new etag from g_file_output_stream_get_etag()
+ * after you've 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
* (such as `/path/to/my icon.png`) without escaping
* if the #GFile for @icon is a native file. If the file is not
* native, the returned string is the result of g_file_get_uri()
- * (such as `sftp://path/to/my\%20icon.png`).
+ * (such as `sftp://path/to/my%20icon.png`).
*
* - If @icon is a #GThemedIcon with exactly one name, the encoding is
* simply the name (such as `network-server`).
*
- * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
- * be serialized. Use g_free() to free.
+ * Returns: (nullable): An allocated NUL-terminated UTF8 string or
+ * %NULL if @icon can't be serialized. Use g_free() to free.
* Since: 2.20
*/
/**
- * g_input_stream_async_read_is_via_threads:
- * @stream: input stream
- *
- * Checks if an input stream's read_async function uses threads.
- *
- * Returns: %TRUE if @stream's read_async function uses threads.
- */
-
-
-/**
* g_input_stream_clear_pending:
* @stream: input stream
*
* 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.
*
+ * The returned @buffer is not a nul-terminated string, it can contain nul bytes
+ * at any position, and this function doesn't nul-terminate 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
* 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.
+ * is set to indicate the error status.
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_read will be set to the number of bytes that were successfully
+ * read before the error was encountered. This functionality is only
+ * available from C. If you need it from another language then you must
+ * write your own loop around g_input_stream_read().
+ *
+ * Returns: %TRUE on success, %FALSE if there was an error
+ */
+
+
+/**
+ * g_input_stream_read_all_async:
+ * @stream: A #GInputStream
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ * read data into (which should be at least count bytes long)
+ * @count: the number of bytes that will be read from the stream
+ * @io_priority: the [I/O priority][io-priority] of the request
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
+ *
+ * Request an asynchronous read of @count bytes from the stream into the
+ * buffer starting at @buffer.
+ *
+ * This is the asynchronous equivalent of g_input_stream_read_all().
+ *
+ * Call g_input_stream_read_all_finish() to collect the result.
+ *
+ * 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.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_input_stream_read_all_finish:
+ * @stream: a #GInputStream
+ * @result: a #GAsyncResult
+ * @bytes_read: (out): location to store the number of bytes that was read from the stream
+ * @error: a #GError location to store the error occurring, or %NULL to ignore
+ *
+ * Finishes an asynchronous stream read operation started with
+ * g_input_stream_read_all_async().
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_read will be set to the number of bytes that were successfully
+ * read before the error was encountered. This functionality is only
+ * available from C. If you need it from another language then you must
+ * write your own loop around g_input_stream_read_async().
*
* Returns: %TRUE on success, %FALSE if there was an error
+ * Since: 2.44
*/
* On error %NULL is returned and @error is set accordingly.
*
* Returns: a new #GBytes, or %NULL on error
+ * Since: 2.34
*/
* 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.
+ *
+ * Since: 2.34
*/
* Finishes an asynchronous stream read-into-#GBytes operation.
*
* Returns: the newly-allocated #GBytes, or %NULL on error
+ * Since: 2.34
*/
* g_io_error_from_errno:
* @err_no: Error number as defined in errno.h.
*
- * Converts errno.h error codes into GIO error codes.
+ * Converts errno.h error codes into GIO error codes. The fallback
+ * value %G_IO_ERROR_FAILED is returned for error codes not currently
+ * handled (but note that future GLib releases may return a more
+ * specific value instead).
*
* Returns: #GIOErrorEnum value for the given errno.h error number.
*/
* g_io_error_from_win32_error:
* @error_code: Windows error number.
*
- * Converts some common error codes into GIO error codes. The
- * fallback value G_IO_ERROR_FAILED is returned for error codes not
- * handled.
+ * Converts some common error codes (as returned from GetLastError()
+ * or WSAGetLastError()) into GIO error codes. The fallback value
+ * %G_IO_ERROR_FAILED is returned for error codes not currently
+ * handled (but note that future GLib releases may return a more
+ * specific value instead).
+ *
+ * You can use g_win32_error_message() to get a localized string
+ * corresponding to @error_code. (But note that unlike g_strerror(),
+ * g_win32_error_message() returns a string that must be freed.)
*
* Returns: #GIOErrorEnum value for the given error number.
* Since: 2.26
/**
+ * g_list_model_get_item: (skip)
+ * @list: a #GListModel
+ * @position: the position of the item to fetch
+ *
+ * Get the item at @position. If @position is greater than the number of
+ * items in @list, %NULL is returned.
+ *
+ * %NULL is never returned for an index that is smaller than the length
+ * of the list. See g_list_model_get_n_items().
+ *
+ * Returns: (transfer full) (nullable) (type GObject): the item at @position.
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_model_get_item_type:
+ * @list: a #GListModel
+ *
+ * Gets the type of the items in @list. All items returned from
+ * g_list_model_get_type() are of that type or a subtype, or are an
+ * implementation of that interface.
+ *
+ * The item type of a #GListModel can not change during the life of the
+ * model.
+ *
+ * Returns: the #GType of the items contained in @list.
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_model_get_n_items:
+ * @list: a #GListModel
+ *
+ * Gets the number of items in @list.
+ *
+ * Depending on the model implementation, calling this function may be
+ * less efficient than iterating the list with increasing values for
+ * @position until g_list_model_get_item() returns %NULL.
+ *
+ * Returns: the number of items in @list.
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_model_get_object: (rename-to g_list_model_get_item)
+ * @list: a #GListModel
+ * @position: the position of the item to fetch
+ *
+ * Get the item at @position. If @position is greater than the number of
+ * items in @list, %NULL is returned.
+ *
+ * %NULL is never returned for an index that is smaller than the length
+ * of the list. See g_list_model_get_n_items().
+ *
+ * Returns: (transfer full) (nullable): the object at @position.
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_model_items_changed:
+ * @list: a #GListModel
+ * @position: the position at which @list changed
+ * @removed: the number of items removed
+ * @added: the number of items added
+ *
+ * Emits the #GListModel::items-changed signal on @list.
+ *
+ * This function should only be called by classes implementing
+ * #GListModel. It has to be called after the internal representation
+ * of @list has been updated, because handlers connected to this signal
+ * might query the new state of the list.
+ *
+ * Implementations must only make changes to the model (as visible to
+ * its consumer) in places that will not cause problems for that
+ * consumer. For models that are driven directly by a write API (such
+ * as #GListStore), changes can be reported in response to uses of that
+ * API. For models that represent remote data, changes should only be
+ * made from a fresh mainloop dispatch. It is particularly not
+ * permitted to make changes in response to a call to the #GListModel
+ * consumer API.
+ *
+ * Stated another way: in general, it is assumed that code making a
+ * series of accesses to the model via the API, without returning to the
+ * mainloop, and without calling other code, will continue to view the
+ * same contents of the model.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_append:
+ * @store: a #GListStore
+ * @item: the new item
+ *
+ * Appends @item to @store. @item must be of type #GListStore:item-type.
+ *
+ * This function takes a ref on @item.
+ *
+ * Use g_list_store_splice() to append multiple items at the same time
+ * efficiently.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_insert:
+ * @store: a #GListStore
+ * @position: the position at which to insert the new item
+ * @item: the new item
+ *
+ * Inserts @item into @store at @position. @item must be of type
+ * #GListStore:item-type or derived from it. @position must be smaller
+ * than the length of the list, or equal to it to append.
+ *
+ * This function takes a ref on @item.
+ *
+ * Use g_list_store_splice() to insert multiple items at the same time
+ * efficiently.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_insert_sorted:
+ * @store: a #GListStore
+ * @item: the new item
+ * @compare_func: pairwise comparison function for sorting
+ * @user_data: (closure): user data for @compare_func
+ *
+ * Inserts @item into @store at a position to be determined by the
+ * @compare_func.
+ *
+ * The list must already be sorted before calling this function or the
+ * result is undefined. Usually you would approach this by only ever
+ * inserting items by way of this function.
+ *
+ * This function takes a ref on @item.
+ *
+ * Returns: the position at which @item was inserted
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_new:
+ * @item_type: the #GType of items in the list
+ *
+ * Creates a new #GListStore with items of type @item_type. @item_type
+ * must be a subclass of #GObject.
+ *
+ * Returns: a new #GListStore
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_remove:
+ * @store: a #GListStore
+ * @position: the position of the item that is to be removed
+ *
+ * Removes the item from @store that is at @position. @position must be
+ * smaller than the current length of the list.
+ *
+ * Use g_list_store_splice() to remove multiple items at the same time
+ * efficiently.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_remove_all:
+ * @store: a #GListStore
+ *
+ * Removes all items from @store.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_list_store_splice:
+ * @store: a #GListStore
+ * @position: the position at which to make the change
+ * @n_removals: the number of items to remove
+ * @additions: (array length=n_additions): the items to add
+ * @n_additions: the number of items to add
+ *
+ * Changes @store by removing @n_removals items and adding @n_additions
+ * items to it. @additions must contain @n_additions items of type
+ * #GListStore:item-type. %NULL is not permitted.
+ *
+ * This function is more efficient than g_list_store_insert() and
+ * g_list_store_remove(), because it only emits
+ * #GListModel::items-changed once for the change.
+ *
+ * This function takes a ref on each item in @additions.
+ *
+ * The parameters @position and @n_removals must be correct (ie:
+ * @position + @n_removals must be less than or equal to the length of
+ * the list at the time this function is called).
+ *
+ * Since: 2.44
+ */
+
+
+/**
* g_loadable_icon_load:
* @icon: a #GLoadableIcon.
* @size: an integer.
- * @type: (out) (allow-none): a location to store the type of the
- * loaded icon, %NULL to ignore.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @error: a #GError location to store the error occurring, or %NULL to
+ * @type: (out) (optional): a location to store the type of the loaded
+ * icon, %NULL to ignore.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to
* ignore.
+ * @error: a #GError location to store the error occurring, or %NULL
+ * to ignore.
*
* Loads a loadable icon. For the asynchronous version of this function,
* see g_loadable_icon_load_async().
* g_loadable_icon_load_finish:
* @icon: a #GLoadableIcon.
* @res: a #GAsyncResult.
- * @type: (out) (allow-none): a location to store the type of the
- * loaded icon, %NULL to ignore.
+ * @type: (out) (optional): a location to store the type of the loaded
+ * icon, %NULL to ignore.
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
*
* Creates a new #GSocketConnectable for connecting to the given
* @hostname and @port.
*
+ * Note that depending on the configuration of the machine, a
+ * @hostname of `localhost` may refer to the IPv4 loopback address
+ * only, or to both IPv4 and IPv6; use
+ * g_network_address_new_loopback() to create a #GNetworkAddress that
+ * is guaranteed to resolve to both addresses.
+ *
* Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
* Since: 2.22
*/
/**
+ * g_network_address_new_loopback:
+ * @port: the port
+ *
+ * Creates a new #GSocketConnectable for connecting to the local host
+ * over a loopback connection to the given @port. This is intended for
+ * use in connecting to local services which may be running on IPv4 or
+ * IPv6.
+ *
+ * The connectable will return IPv4 and IPv6 loopback addresses,
+ * regardless of how the host resolves `localhost`. By contrast,
+ * g_network_address_new() will often only return an IPv4 address when
+ * resolving `localhost`, and an IPv6 address for `localhost6`.
+ *
+ * g_network_address_get_hostname() will always return `localhost` for
+ * #GNetworkAddresses created with this constructor.
+ *
+ * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
+ * Since: 2.44
+ */
+
+
+/**
* g_network_address_parse:
* @host_and_port: the hostname and optionally a port
* @default_port: the default port if not in @host_and_port
/**
+ * g_network_monitor_get_connectivity:
+ * @monitor: the #GNetworkMonitor
+ *
+ * Gets a more detailed networking state than
+ * g_network_monitor_get_network_available().
+ *
+ * If #GNetworkMonitor:network-available is %FALSE, then the
+ * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL.
+ *
+ * If #GNetworkMonitor:network-available is %TRUE, then the
+ * connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there
+ * is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if
+ * the host has a default route, but appears to be unable to actually
+ * reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the
+ * host is trapped behind a "captive portal" that requires some sort
+ * of login or acknowledgement before allowing full Internet access).
+ *
+ * Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and
+ * %G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are
+ * reachable but others are not. In this case, applications can
+ * attempt to connect to remote servers, but should gracefully fall
+ * back to their "offline" behavior if the connection attempt fails.
+ *
+ * Returns: the network connectivity state
+ * Since: 2.44
+ */
+
+
+/**
* g_network_monitor_get_default:
*
* Gets the default #GNetworkMonitor for the system.
* @notification: a #GNotification
* @label: label of the button
* @action: an action name
- * @target_format: (allow-none): a GVariant format string, or %NULL
- * @...: positional parameters, as determined by @format_string
+ * @target_format: (allow-none): a #GVariant format string, or %NULL
+ * @...: positional parameters, as determined by @target_format
*
* Adds a button to @notification that activates @action when clicked.
* @action must be an application-wide action (it must start with "app.").
*
* If @target_format is given, it is used to collect remaining
- * positional parameters into a GVariant instance, similar to
- * g_variant_new(). @action will be activated with that GVariant as its
+ * positional parameters into a #GVariant instance, similar to
+ * g_variant_new(). @action will be activated with that #GVariant as its
* parameter.
*
* Since: 2.40
* @notification: a #GNotification
* @label: label of the button
* @action: an action name
- * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
+ * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
*
* Adds a button to @notification that activates @action when clicked.
* @action must be an application-wide action (it must start with "app.").
* g_notification_set_default_action_and_target: (skip)
* @notification: a #GNotification
* @action: an action name
- * @target_format: (allow-none): a GVariant format string, or %NULL
- * @...: positional parameters, as determined by @format_string
+ * @target_format: (allow-none): a #GVariant format string, or %NULL
+ * @...: positional parameters, as determined by @target_format
*
* Sets the default action of @notification to @action. This action is
* activated when the notification is clicked on. It must be an
* application-wide action (it must start with "app.").
*
* If @target_format is given, it is used to collect remaining
- * positional parameters into a GVariant instance, similar to
- * g_variant_new(). @action will be activated with that GVariant as its
+ * positional parameters into a #GVariant instance, similar to
+ * g_variant_new(). @action will be activated with that #GVariant as its
* parameter.
*
* When no default action is set, the application that the notification
* g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target)
* @notification: a #GNotification
* @action: an action name
- * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
+ * @target: (allow-none): a #GVariant to use as @action's parameter, or %NULL
*
* Sets the default action of @notification to @action. This action is
* activated when the notification is clicked on. It must be an
* application-wide action (start with "app.").
*
- * If @target_format is given, it is used to collect remaining
- * positional parameters into a GVariant instance, similar to
- * g_variant_new().
- *
* If @target is non-%NULL, @action will be activated with @target as
* its parameter.
*
/**
+ * g_notification_set_priority:
+ * @notification: a #GNotification
+ * @priority: a #GNotificationPriority
+ *
+ * Sets the priority of @notification to @priority. See
+ * #GNotificationPriority for possible values.
+ */
+
+
+/**
* g_notification_set_title:
* @notification: a #GNotification
* @title: the new title for @notification
* @notification: a #GNotification
* @urgent: %TRUE if @notification is urgent
*
- * Sets or unsets whether @notification is marked as urgent.
+ * Deprecated in favor of g_notification_set_priority().
*
* Since: 2.40
*/
/**
- * g_output_stream_async_write_is_via_threads:
- * @stream: a #GOutputStream.
- *
- * Checks if an ouput stream's write_async function uses threads.
- *
- * Returns: %TRUE if @stream's write_async function uses threads.
- */
-
-
-/**
* g_output_stream_clear_pending:
* @stream: output stream
*
* 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.
+ * is set to indicate the error status.
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_written will be set to the number of bytes that were
+ * successfully written before the error was encountered. This
+ * functionality is only available from C. If you need it from another
+ * language then you must write your own loop around
+ * g_output_stream_write().
*
* Returns: %TRUE on success, %FALSE if there was an error
*/
/**
+ * g_output_stream_write_all_async:
+ * @stream: A #GOutputStream
+ * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write
+ * @count: the number of bytes to write
+ * @io_priority: the io priority of the request
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
+ *
+ * Request an asynchronous write of @count bytes from @buffer into
+ * the stream. When the operation is finished @callback will be called.
+ * You can then call g_output_stream_write_all_finish() to get the result of the
+ * operation.
+ *
+ * This is the asynchronous version of g_output_stream_write_all().
+ *
+ * Call g_output_stream_write_all_finish() to collect the result.
+ *
+ * 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.
+ *
+ * Note that no copy of @buffer will be made, so it must stay valid
+ * until @callback is called.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_output_stream_write_all_finish:
+ * @stream: a #GOutputStream
+ * @result: a #GAsyncResult
+ * @bytes_written: (out): location to store the number of bytes that was written to the stream
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ *
+ * Finishes an asynchronous stream write operation started with
+ * g_output_stream_write_all_async().
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_written will be set to the number of bytes that were
+ * successfully written before the error was encountered. This
+ * functionality is only available from C. If you need it from another
+ * language then you must write your own loop around
+ * g_output_stream_write_async().
+ *
+ * Returns: %TRUE on success, %FALSE if there was an error
+ * Since: 2.44
+ */
+
+
+/**
* g_output_stream_write_async:
* @stream: A #GOutputStream.
* @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
/**
* g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking)
* @stream: a #GPollableInputStream
- * @buffer: a buffer to read data into (which should be at least @count
- * bytes long).
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ * read data into (which should be at least @count bytes long).
* @count: the number of bytes you want to read
* @cancellable: (allow-none): a #GCancellable, or %NULL
* @error: #GError for error reporting, or %NULL to ignore.
/**
* g_pollable_stream_read:
* @stream: a #GInputStream
- * @buffer: a buffer to read data into
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ * read data into
* @count: the number of bytes to read
* @blocking: whether to do blocking I/O
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
/**
* g_property_action_new:
* @name: the name of the action to create
- * @object: the object that has the property to wrap
+ * @object: (type GObject.Object): the object that has the property
+ * to wrap
* @property_name: the name of the property
*
* Creates a #GAction corresponding to the value of property
* 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
+ * On success, g_resolver_lookup_by_name() will return a non-empty #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
* 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.
+ * value from #GResolverError and %NULL will be returned.
*
* If @cancellable is non-%NULL, it can be used to cancel the
* operation, in which case @error (if non-%NULL) will be set to
* address, it may be easier to create a #GNetworkAddress and use its
* #GSocketConnectable interface.
*
- * Returns: (element-type GInetAddress) (transfer full): a #GList
+ * Returns: (element-type GInetAddress) (transfer full): a non-empty #GList
* 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.)
* information on what the records contain for each @record_type.
*
* If the DNS resolution fails, @error (if non-%NULL) will be set to
- * a value from #GResolverError.
+ * a value from #GResolverError and %NULL will be returned.
*
* 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.
*
- * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant,
- * or %NULL on error. You must free each of the records and the list when you are
- * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
+ * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
+ * #GVariant, or %NULL on error. You must free each of the records and the list
+ * when you are done with it. (You can use g_list_free_full() with
+ * g_variant_unref() to do this.)
* Since: 2.34
*/
* @error: return location for a #GError, or %NULL
*
* Retrieves the result of a previous call to
- * g_resolver_lookup_records_async(). Returns a list of records as #GVariant
- * tuples. See #GResolverRecordType for information on what the records contain.
+ * g_resolver_lookup_records_async(). Returns a non-empty list of records as
+ * #GVariant tuples. See #GResolverRecordType for information on what the
+ * records contain.
*
* 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.
*
- * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant,
- * or %NULL on error. You must free each of the records and the list when you are
- * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
+ * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
+ * #GVariant, or %NULL on error. You must free each of the records and the list
+ * when you are done with it. (You can use g_list_free_full() with
+ * g_variant_unref() to do this.)
* Since: 2.34
*/
* @service and @protocol arguments do not include the leading underscore
* that appears in the actual DNS entry.
*
- * On success, g_resolver_lookup_service() will return a #GList of
+ * On success, g_resolver_lookup_service() will return a non-empty #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.
+ * a value from #GResolverError and %NULL will be returned.
*
* If @cancellable is non-%NULL, it can be used to cancel the
* operation, in which case @error (if non-%NULL) will be set to
* to create a #GNetworkService and use its #GSocketConnectable
* interface.
*
- * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
- * 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.)
+ * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
+ * #GSrvTarget, 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.)
* Since: 2.22
*/
* a value from #GResolverError. If the operation was cancelled,
* @error will be set to %G_IO_ERROR_CANCELLED.
*
- * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
- * or %NULL on error. See g_resolver_lookup_service() for more details.
+ * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
+ * #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
+ * details.
* Since: 2.22
*/
/**
* g_settings_list_relocatable_schemas:
*
+ * <!-- -->
+ *
* Returns: (element-type utf8) (transfer none): a list of relocatable
* #GSettings schemas that are available. The list must not be
* modified or freed.
/**
* g_settings_list_schemas:
*
+ * <!-- -->
+ *
* Returns: (element-type utf8) (transfer none): a list of #GSettings
* schemas that are available. The list must not be modified or
* freed.
* backend, and a #GMainContext to which signals are dispatched.
*
* This constructor therefore gives you full control over constructing
- * #GSettings instances. The first 4 parameters are given directly as
+ * #GSettings instances. The first 3 parameters are given directly as
* @schema, @backend and @path, and the main context is taken from the
* thread-default (as per g_settings_new()).
*
* If @backend is %NULL then the default backend is used.
*
* If @path is %NULL then the path from the schema is used. It is an
- * error f @path is %NULL and the schema has no path of its own or if
+ * error if @path is %NULL and the schema has no path of its own or if
* @path is non-%NULL and not equal to the path that the schema does
* have.
*
/**
+ * g_settings_schema_key_get_name:
+ * @key: a #GSettingsSchemaKey
+ *
+ * Gets the name of @key.
+ *
+ * Returns: the name of @key.
+ * Since: 2.44
+ */
+
+
+/**
* g_settings_schema_key_get_range:
* @key: a #GSettingsSchemaKey
*
/**
+ * g_settings_schema_list_children:
+ * @schema: a #GSettingsSchema
+ *
+ * Gets the list of children in @schema.
+ *
+ * You should free the return value with g_strfreev() when you are done
+ * with it.
+ *
+ * Returns: (transfer full) (element-type utf8): a list of the children on @settings
+ * Since: 2.44
+ */
+
+
+/**
* g_settings_schema_ref:
* @schema: a #GSettingsSchema
*
* g_settings_schema_source_list_schemas:
* @source: a #GSettingsSchemaSource
* @recursive: if we should recurse
- * @non_relocatable: (out) (transfer full): the list of non-relocatable
- * schemas
- * @relocatable: (out) (transfer full): the list of relocatable schemas
+ * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the
+ * list of non-relocatable schemas
+ * @relocatable: (out) (transfer full) (array zero-terminated=1): the list
+ * of relocatable schemas
*
* Lists the schemas in a given source.
*
*
* If the schema isn't found, %NULL is returned.
*
- * Returns: (transfer full): a new #GSettingsSchema
+ * Returns: (nullable) (transfer full): a new #GSettingsSchema
* Since: 2.32
*/
/**
* g_settings_unbind:
- * @object: the object
+ * @object: (type GObject.Object): the object
* @property: the property whose binding is removed
*
* Removes an existing binding for @property on @object.
/**
+ * g_simple_action_set_state_hint:
+ * @simple: a #GSimpleAction
+ * @state_hint: (allow-none): a #GVariant representing the state hint
+ *
+ * Sets the state hint for the action.
+ *
+ * See g_action_get_state_hint() for more information about
+ * action state hints.
+ *
+ * Since: 2.44
+ */
+
+
+/**
* g_simple_async_report_error_in_idle: (skip)
* @object: (allow-none): a #GObject, or %NULL.
* @callback: a #GAsyncReadyCallback.
/**
+ * g_simple_io_stream_new:
+ * @input_stream: a #GInputStream.
+ * @output_stream: a #GOutputStream.
+ *
+ * Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream.
+ * See also #GIOStream.
+ *
+ * Returns: a new #GSimpleIOStream instance.
+ * Since: 2.44
+ */
+
+
+/**
* g_simple_permission_new:
* @allowed: %TRUE if the action is allowed
*
* @condition: a #GIOCondition mask to monitor
* @cancellable: (allow-none): a %GCancellable or %NULL
*
- * Creates a %GSource that can be attached to a %GMainContext to monitor
- * for the availibility of the specified @condition on the socket.
+ * Creates a #GSource that can be attached to a %GMainContext to monitor
+ * for the availability of the specified @condition on the socket. The #GSource
+ * keeps a reference to the @socket.
*
* The callback on the source is of the #GSocketSourceFunc type.
*
* useful if you're listening on multiple addresses and do
* different things depending on what address is connected to.
*
+ * The @socket will not be automatically closed when the @listener is finalized
+ * unless the listener held the final reference to the socket. Before GLib 2.42,
+ * the @socket was automatically closed on finalization of the @listener, even
+ * if references to it were held elsewhere.
+ *
* Returns: %TRUE on success, %FALSE on error.
* Since: 2.22
*/
/**
+ * g_socket_send_messages:
+ * @socket: a #GSocket
+ * @messages: (array length=num_messages): an array of #GOutputMessage structs
+ * @num_messages: the number of elements in @messages
+ * @flags: an int containing #GSocketMsgFlags flags
+ * @cancellable: (allow-none): a %GCancellable or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Send multiple data messages from @socket in one go. This is the most
+ * complicated and fully-featured version of this call. For easier use, see
+ * g_socket_send(), g_socket_send_to(), and g_socket_send_message().
+ *
+ * @messages must point to an array of #GOutputMessage structs and
+ * @num_messages must be the length of this array. Each #GOutputMessage
+ * contains an address to send the data to, and a pointer to an array of
+ * #GOutputVector structs to describe the buffers that the data to be sent
+ * for each message will be gathered from. Using multiple #GOutputVectors 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(). Sending multiple messages in one go avoids the
+ * overhead of making a lot of syscalls in scenarios where a lot of data
+ * packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP),
+ * or where the same data needs to be sent to multiple recipients.
+ *
+ * @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 all 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
+ * will be returned if no data was written at all, otherwise the number of
+ * messages sent will be returned. To be notified when space is available,
+ * wait for the %G_IO_OUT condition. Note though that you may still receive
+ * %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.
+ *
+ * Returns: number of messages sent, or -1 on error. Note that the number of
+ * messages sent may be smaller than @num_messages if the socket is
+ * non-blocking or if @num_messages was larger than UIO_MAXIOV (1024),
+ * in which case the caller may re-try to send the remaining messages.
+ * Since: 2.44
+ */
+
+
+/**
* g_socket_send_to:
* @socket: a #GSocket
* @address: (allow-none): a #GSocketAddress, or %NULL
* @callback: Callback
* @user_data: User data
*
- * Asynchronous version of g_subprocess_communicate_utf(). Complete
+ * Asynchronous version of g_subprocess_communicate_utf8(). Complete
* invocation with g_subprocess_communicate_utf8_finish().
*/
* g_subprocess_get_identifier:
* @subprocess: a #GSubprocess
*
- * On UNIX, returns the process ID as a decimal string. On Windows,
- * returns the result of GetProcessId() also as a string.
+ * On UNIX, returns the process ID as a decimal string.
+ * On Windows, returns the result of GetProcessId() also as a string.
*/
* @argv0: Command line arguments
* @...: Continued arguments, %NULL terminated
*
- * A convenience helper for creating a #GSubprocess given a provided
- * varargs list of arguments.
+ * Creates a #GSubprocess given a provided varargs list of arguments.
*
* Since: 2.40
* Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
* @argv: (array zero-terminated=1) (element-type utf8): Command line arguments
* @error: Error
*
- * A convenience helper for creating a #GSubprocess given a provided
- * array of arguments.
+ * Creates a #GSubprocess given a provided array of arguments.
*
* Since: 2.40
* Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
* g_subprocess_new: (skip)
* @flags: flags that define the behaviour of the subprocess
* @error: (allow-none): return location for an error, or %NULL
- * @argv0: first commandline argument to pass to the subprocess,
- * followed by more arguments, followed by %NULL
+ * @argv0: first commandline argument to pass to the subprocess
+ * @...: more commandline arguments, followed by %NULL
*
* Create a new process with the given flags and varargs argument
* list. By default, matching the g_spawn_async() defaults, the
* This function does not fail in the case of the subprocess having
* abnormal termination. See g_subprocess_wait_check() for that.
*
+ * Cancelling @cancellable doesn't kill the subprocess. Call
+ * g_subprocess_force_exit() if it is desirable.
+ *
* Returns: %TRUE on success, %FALSE if @cancellable was cancelled
* Since: 2.40
*/
/**
+ * g_task_get_completed:
+ * @task: a #GTask.
+ *
+ * Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after
+ * the task’s callback is invoked, and will return %FALSE if called from inside
+ * the callback.
+ *
+ * Returns: %TRUE if the task has completed, %FALSE otherwise.
+ * Since: 2.44
+ */
+
+
+/**
* g_task_get_context:
* @task: a #GTask
*
* Normally this is used with tasks created with a %NULL
* `callback`, but note that even if the task does
* have a callback, it will not be invoked when @task_func returns.
+ * #GTask:completed will be set to %TRUE just before this function returns.
*
* Since: 2.36
*/
* @connection: a #GTcpConnection
* @graceful_disconnect: Whether to do graceful disconnects or not
*
- * This enabled graceful disconnects on close. A graceful disconnect
+ * This enables 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.
*
* @file: file containing a PEM-encoded certificate to import
* @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
+ * Creates a #GTlsCertificate from the PEM-encoded data in @file. The
+ * returned certificate will be the first certificate found in @file. As
+ * of GLib 2.44, if @file contains more certificates it will try to load
+ * a certificate chain. All certificates will be verified in the order
+ * found (top-level certificate should be the last one in the file) and
+ * the #GTlsCertificate:issuer property of each certificate will be set
+ * accordingly if the verification succeeds. If any certificate in the
+ * chain cannot be verified, the first certificate in the file will
+ * still be returned.
+ *
+ * If @file cannot be read or parsed, the function will return %NULL and
* set @error. Otherwise, this behaves like
* g_tls_certificate_new_from_pem().
*
/**
* g_tls_certificate_new_from_files:
- * @cert_file: file containing a PEM-encoded certificate to import
+ * @cert_file: file containing one or more PEM-encoded certificates to
+ * import
* @key_file: file containing a PEM-encoded private key to import
* @error: #GError for error reporting, or %NULL to ignore.
*
* Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
- * and @key_file. If either file cannot be read or parsed, the
- * function will return %NULL and set @error. Otherwise, this behaves
- * like g_tls_certificate_new_from_pem().
+ * and @key_file. The returned certificate will be the first certificate
+ * found in @cert_file. As of GLib 2.44, if @cert_file contains more
+ * certificates it will try to load a certificate chain. All
+ * certificates will be verified in the order found (top-level
+ * certificate should be the last one in the file) and the
+ * #GTlsCertificate:issuer property of each certificate will be set
+ * accordingly if the verification succeeds. If any certificate in the
+ * chain cannot be verified, the first certificate in the file will
+ * still be returned.
+ *
+ * If either file cannot be read or parsed, the function will return
+ * %NULL and set @error. Otherwise, this behaves like
+ * g_tls_certificate_new_from_pem().
*
* Returns: the new certificate, or %NULL on error
* Since: 2.28
* @length: the length of @data, or -1 if it's 0-terminated.
* @error: #GError for error reporting, or %NULL to ignore.
*
- * Creates a new #GTlsCertificate from the PEM-encoded data in @data.
- * If @data includes both a certificate and a private key, then the
+ * Creates a #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. (See
* the #GTlsCertificate:private-key-pem property for information about
* supported formats.)
*
- * If @data includes multiple certificates, only the first one will be
- * parsed.
+ * The returned certificate will be the first certificate found in
+ * @data. As of GLib 2.44, if @data contains more certificates it will
+ * try to load a certificate chain. All certificates will be verified in
+ * the order found (top-level certificate should be the last one in the
+ * file) and the #GTlsCertificate:issuer property of each certificate
+ * will be set accordingly if the verification succeeds. If any
+ * certificate in the chain cannot be verified, the first certificate in
+ * the file will still be returned.
*
* Returns: the new certificate, or %NULL if @data is invalid
* Since: 2.28
* 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.
+ * Returns: (nullable): a newly allocated string containing the
+ * handle.
* Since: 2.30
*/
/**
+ * g_unix_mount_guess_type:
+ * @mount_entry: a #GUnixMount.
+ *
+ * Guesses the type of a unix mount. If the mount type cannot be
+ * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
+ *
+ * Returns: a #GUnixMountType.
+ */
+
+
+/**
* g_unix_mount_is_readonly:
* @mount_entry: a #GUnixMount.
*
/**
+ * g_unix_mount_monitor_get:
+ *
+ * Gets the #GUnixMountMonitor for the current thread-default main
+ * context.
+ *
+ * The mount monitor can be used to monitor for changes to the list of
+ * mounted filesystems as well as the list of mount points (ie: fstab
+ * entries).
+ *
+ * You must only call g_object_unref() on the return value from under
+ * the same main context as you called this function.
+ *
+ * Returns: (transfer full): the #GUnixMountMonitor.
+ * Since: 2.44
+ */
+
+
+/**
* g_unix_mount_monitor_new:
*
- * Gets a new #GUnixMountMonitor. The default rate limit for which the
- * monitor will report consecutive changes for the mount and mount
- * point entry files is the default for a #GFileMonitor. Use
- * g_unix_mount_monitor_set_rate_limit() to change this.
+ * Deprecated alias for g_unix_mount_monitor_get().
+ *
+ * This function was never a true constructor, which is why it was
+ * renamed.
*
* Returns: a #GUnixMountMonitor.
+ * Deprecated: 2.44: Use g_unix_mount_monitor_get() instead.
*/
* @limit_msec: a integer with the limit in milliseconds to
* poll for changes.
*
- * Sets the rate limit to which the @mount_monitor will report
- * consecutive change events to the mount and mount point entry files.
+ * This function does nothing.
+ *
+ * Before 2.44, this was a partially-effective way of controlling the
+ * rate at which events would be reported under some uncommon
+ * circumstances. Since @mount_monitor is a singleton, it also meant
+ * that calling this function would have side effects for other users of
+ * the monitor.
*
* Since: 2.18
+ * Deprecated: 2.44: This function does nothing. Don't call it.
*/
/**
+ * g_unix_mount_point_guess_type:
+ * @mount_point: a #GUnixMountPoint.
+ *
+ * Guesses the type of a unix mount point.
+ * If the mount type cannot be determined,
+ * returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
+ *
+ * Returns: a #GUnixMountType.
+ */
+
+
+/**
* g_unix_mount_point_is_loopback:
* @mount_point: a #GUnixMountPoint.
*
* implementations to find the underlying mount to shadow, see
* g_mount_is_shadowed() for more details.
*
- * Returns: (transfer full): the activation root of @volume or %NULL. Use
- * g_object_unref() to free.
+ * Returns: (nullable) (transfer full): the activation root of @volume
+ * or %NULL. Use g_object_unref() to free.
* Since: 2.18
*/
/**
- * get_all_desktop_entries_for_mime_type:
- * @mime_type: a mime type.
- * @except: NULL or a strv list
- *
- * Returns all the desktop ids for @mime_type. The desktop files
- * 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
+ * get_viewable_logical_drives:
*
- * Returns: a #GList containing the desktop ids which claim
- * to handle @mime_type.
- */
-
-
-/**
- * mime_info_cache_reload:
- * @dir: directory path which needs reloading.
+ * Returns the list of logical and viewable drives as defined by
+ * GetLogicalDrives() and the registry keys
+ * Software\Microsoft\Windows\CurrentVersion\Policies\Explorer under
+ * HKLM or HKCU. If neither key exists the result of
+ * GetLogicalDrives() is returned.
*
- * Reload the mime information for the @dir.
+ * Returns: bitmask with same meaning as returned by GetLogicalDrives()
*/
projects / platform / upstream / gobject-introspection.git / blobdiff