diff options
Diffstat (limited to 'gir')
| -rw-r--r-- | gir/gio-2.0.c | 38100 | ||||
| -rw-r--r-- | gir/gobject-2.0.c | 12233 |
2 files changed, 25200 insertions, 25133 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 3706c7d8..883d7713 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -3,407 +3,379 @@ /************************************************************/ /** - * g_mount_guess_content_type: - * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback - * @user_data: user data passed to @callback + * GAction:enabled: * - * Tries to guess the type of content stored on @mount. Returns one or - * more textual identifiers of well-known content types (typically - * prefixed with "x-content/"), e.g. x-content/image-dcf for camera - * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> - * specification for more on x-content types. - * This is an asynchronous operation (see - * g_mount_guess_content_type_sync() for the synchronous version), and - * is finished by calling g_mount_guess_content_type_finish() with the + * If @action is currently enabled. + * If the action is disabled then calls to g_action_activate() and + * g_action_set_state() have no effect. * - * Since: 2.18 + * Since: 2.28 */ /** - * GFileQueryInfoFlags: - * @G_FILE_QUERY_INFO_NONE: No flags set. - * @G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS: Don't follow symlinks. + * GAction:name: * - * Flags used when querying a #GFileInfo. - */ - - -/** - * g_output_stream_flush_async: - * @stream: a #GOutputStream. - * @io_priority: the io priority of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * The name of the action. This is mostly meaningful for identifying + * the action once it has been added to a #GActionGroup. * - * Flushes a stream asynchronously. - * For behaviour details see g_output_stream_flush(). - * When the operation is finished @callback will be - * called. You can then call g_output_stream_flush_finish() to get the - * result of the operation. + * Since: 2.28 */ /** - * GZlibDecompressor:file-info: + * GAction:parameter-type: * - * A #GFileInfo containing the information found in the GZIP header - * of the data stream processed, or %NULL if the header was not yet - * fully processed, is not present at all, or the compressor's - * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP. + * The type of the parameter that must be given when activating the + * action. * - * Since: 2.26 + * Since: 2.28 */ /** - * G_VARIANT_TYPE_STRING_ARRAY: + * GAction:state: * - * The type of an array of strings. + * The state of the action, or %NULL if the action is stateless. + * + * Since: 2.28 */ /** - * g_file_attribute_info_list_ref: - * @list: a #GFileAttributeInfoList to reference. + * GAction:state-type: * - * References a file attribute info list. + * The #GVariantType of the state that the action has, or %NULL if the + * action is stateless. * - * Returns: #GFileAttributeInfoList or %NULL on error. + * Since: 2.28 */ /** - * g_drive_is_media_check_automatic: - * @drive: a #GDrive. + * GActionGroup::action-added: + * @action_group: the #GActionGroup that changed + * @action_name: the name of the action in @action_group * - * Checks if @drive is capabable of automatically detecting media changes. - * media changes, %FALSE otherwise. + * Signals that a new action was just added to the group. This signal + * is emitted after the action has been added and is now visible. * - * Returns: %TRUE if the @drive is capabable of automatically detecting + * Since: 2.28 */ /** - * GUnixCredentialsMessage: + * GActionGroup::action-enabled-changed: + * @action_group: the #GActionGroup that changed + * @action_name: the name of the action in @action_group + * @enabled: whether the action is enabled or not * - * The #GUnixCredentialsMessage structure contains only private data - * and should only be accessed using the provided API. + * Signals that the enabled status of the named action has changed. * - * Since: 2.26 + * Since: 2.28 */ /** - * g_dbus_message_set_header: - * @message: A #GDBusMessage. - * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) - * @value: A #GVariant to set the header field or %NULL to clear the header field. + * GActionGroup::action-removed: + * @action_group: the #GActionGroup that changed + * @action_name: the name of the action in @action_group * - * Sets a header field on @message. - * If @value is floating, @message assumes ownership of @value. + * Signals that an action is just about to be removed from the group. + * This signal is emitted before the action is removed, so the action + * is still visible and can be queried from the signal handler. * - * Since: 2.26 + * Since: 2.28 */ /** - * G_FILE_ATTRIBUTE_FILESYSTEM_TYPE: + * GActionGroup::action-state-changed: + * @action_group: the #GActionGroup that changed + * @action_name: the name of the action in @action_group + * @value: the new value of the state * - * A key in the "filesystem" namespace for getting the file system's type. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * Signals that the state of the named action has changed. + * + * Since: 2.28 */ /** - * g_app_info_add_supports_type: - * @appinfo: a #GAppInfo. - * @content_type: a string. - * @error: a #GError. + * GActionGroupInterface: + * @has_action: the virtual function pointer for g_action_group_has_action() + * @list_actions: the virtual function pointer for g_action_group_list_actions() + * @get_parameter_type: the virtual function pointer for g_action_group_get_parameter_type() + * @get_state_type: the virtual function pointer for g_action_group_get_state_type() + * @get_state_hint: the virtual function pointer for g_action_group_get_state_hint() + * @get_enabled: the virtual function pointer for g_action_group_get_enabled() + * @get_state: the virtual function pointer for g_action_group_get_state() + * @set_state: the virtual function pointer for g_action_group_set_state() + * @activate: the virtual function pointer for g_action_group_activate() + * @action_added: the class closure for the action-added signal + * @action_removed: the class closure for the action-removed signal + * @action_enabled_changed: the class closure for the action-enabled-changed signal + * @action_state_changed: the class closure for the action-enabled-changed signal * - * Adds a content type to the application information to indicate the - * application is capable of opening files with the given content type. + * The virtual function table for #GActionGroup. * - * Returns: %TRUE on success, %FALSE on error. + * Since: 2.26 */ /** - * g_file_info_get_size: - * @info: a #GFileInfo. + * GActionInterface: + * @get_name: the virtual function pointer for g_action_get_name() + * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type() + * @get_state_type: the virtual function pointer for g_action_get_state_type() + * @get_state_hint: the virtual function pointer for g_action_get_state_hint() + * @get_enabled: the virtual function pointer for g_action_get_enabled() + * @get_state: the virtual function pointer for g_action_get_state() + * @set_state: the virtual function pointer for g_action_set_state() + * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an 'activate' signal but that implementations of it may have one. * - * Gets the file's size. * - * Returns: a #goffset containing the file's size. + * + * Since: 2.26 */ /** - * g_dbus_interface_info_lookup_signal: - * @info: A #GDBusInterfaceInfo. - * @name: A D-Bus signal name (typically in CamelCase) - * - * Looks up information about a signal. - * This cost of this function is O(n) in number of signals. + * GAppInfo: * - * Returns: A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. - * Since: 2.26 + * Information about an installed application and methods to launch + * it (with file arguments). */ /** - * g_dbus_connection_flush_sync: - * @connection: A #GDBusConnection. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Synchronously flushes @connection. The calling thread is blocked - * until this is done. See g_dbus_connection_flush() for the - * asynchronous version of this method and more details about what it - * does. + * GAppInfoCreateFlags: + * @G_APP_INFO_CREATE_NONE: No flags. + * @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens in a terminal window. + * @G_APP_INFO_CREATE_SUPPORTS_URIS: Application supports URI arguments. + * @G_APP_INFO_CREATE_SUPPORTS_STARTUP_NOTIFICATION: Application supports startup notification. Since 2.26 * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. - * Since: 2.26 + * Flags used when creating a #GAppInfo. */ /** - * g_dbus_message_set_signature: - * @message: A #GDBusMessage. - * @value: The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. + * GAppInfoIface: + * @g_iface: The parent interface. + * @dup: Copies a #GAppInfo. + * @equal: Checks two #GAppInfo<!-- -->s for equality. + * @get_id: Gets a string identifier for a #GAppInfo. + * @get_name: Gets the name of the application for a #GAppInfo. + * @get_description: Gets a short description for the application described by the #GAppInfo. + * @get_executable: Gets the executable name for the #GAppInfo. + * @get_icon: Gets the #GIcon for the #GAppInfo. + * @launch: Launches an application specified by the #GAppInfo. + * @supports_uris: Indicates whether the application specified supports launching URIs. + * @supports_files: Indicates whether the application specified accepts filename arguments. + * @launch_uris: Launches an application with a list of URIs. + * @should_show: Returns whether an application should be shown (e.g. when getting a list of installed applications). <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"> <citetitle>FreeDesktop.Org Startup Notification Specification</citetitle></ulink>. + * @set_as_default_for_type: Sets an application as default for a given content type. + * @set_as_default_for_extension: Sets an application as default for a given file extension. + * @add_supports_type: Adds to the #GAppInfo information about supported file types. + * @can_remove_supports_type: Checks for support for removing supported file types from a #GAppInfo. + * @remove_supports_type: Removes a supported application type from a #GAppInfo. + * @can_delete: Checks if a #GAppInfo can be deleted. Since 2.20 + * @do_delete: Deletes a #GAppInfo. Since 2.20 + * @get_commandline: Gets the commandline for the #GAppInfo. Since 2.20 + * @get_display_name: Gets the display name for the #GAppInfo. Since 2.24 * - * Since: 2.26 + * Application Information interface, for operating system portability. */ /** - * GTlsBackendInterface: - * @g_iface: The parent interface. - * @get_certificate_type: returns the #GTlsCertificate implementation type - * @get_client_connection_type: returns the #GTlsClientConnection implementation type - * @get_server_connection_type: returns the #GTlsServerConnection implementation type - * - * Provides an interface for describing TLS-related types. + * GAppLaunchContext: * - * Since: 2.28 + * Integrating the launch with the launching application. This is used to + * handle for instance startup notification and launching the new application + * on the same screen as the launching window. */ /** - * g_file_make_symbolic_link: - * @file: a #GFile with the name of the symlink to create - * @symlink_value: a string with the path for the target of the new symlink - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * GApplication: * - * Creates a symbolic link named @file which contains the string - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * The <structname>GApplication</structname> structure contains private + * data and should only be accessed using the provided API * - * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise. + * Since: 2.26 */ /** - * g_io_stream_has_pending: - * @stream: a #GIOStream - * - * Checks if a stream has pending actions. + * GApplication::activate: + * @application: the application * - * Returns: %TRUE if @stream has pending actions. - * Since: 2.22 + * The ::activate signal is emitted on the primary instance when an + * activation occurs. See g_application_activate(). */ /** - * G_TYPE_FROM_CLASS: - * @g_class: Location of a valid #GTypeClass structure. - * - * Get the type identifier from a given @class structure. - * This macro should only be used in type implementations. + * GApplication::command-line: + * @application: the application + * @command_line: a #GApplicationCommandLine representing the passed commandline * - * Returns: the #GType + * The ::command-line signal is emitted on the primary instance when + * a commandline is not handled locally. See g_application_run() for + * more information. */ /** - * GAsyncResultIface: - * @g_iface: The parent interface. - * @get_user_data: Gets the user data passed to the callback. - * @get_source_object: Gets the source object that issued the asynchronous operation. + * GApplication::open: + * @application: the application + * @files: (array length=n_files) (element-type GFile): an array of #GFiles + * @n_files: the length of @files + * @hint: a hint provided by the calling instance * - * Interface definition for #GAsyncResult. + * The ::open signal is emitted on the primary instance when there are + * files to open. See g_application_open() for more information. */ /** - * G_TYPE_UCHAR: + * GApplication::startup: + * @application: the application * - * The fundamental type corresponding to #guchar. + * The ::startup signal is emitted on the primary instance immediately + * after registration. See g_activation_register(). */ /** - * g_dbus_message_get_message_type: - * @message: A #GDBusMessage. + * GApplicationClass: + * @startup: invoked on the primary instance immediately after registration + * @activate: invoked on the primary instance when an activation occurs + * @open: invoked on the primary instance when there are files to open + * @command_line: invoked on the primary instance when a command-line is not handled locally + * @local_command_line: invoked (locally) when the process has been invoked via commandline execution. The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information. + * @before_emit: invoked on the primary instance before 'activate', 'open' or any action invocation + * @after_emit: invoked on the primary instance after 'activate', 'open' or any action invocation + * @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions + * @quit_mainloop: invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested) + * @run_mainloop: invoked on the primary instance from g_application_run() if the use-count is non-zero + * * - * Gets the type of @message. * - * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). * Since: 2.26 */ /** - * SECTION:gdbusnamewatchin: - * @title: Watching Bus Names - * @short_description: Simple API for watching bus names - * @include: gio/gio.h + * GApplicationCommandLine: * - * Convenience API for watching bus names. - * <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * The <structname>GApplicationCommandLine</structname> structure contains private + * data and should only be accessed using the provided API + * + * Since: 2.26 */ /** - * GDBusProxy:g-flags: + * GApplicationCommandLineClass: * - * Flags from the #GDBusProxyFlags enumeration. + * The <structname>GApplicationCommandLineClass</structname> structure contains + * private data only * * Since: 2.26 */ /** - * g_socket_listener_new: + * GApplicationFlags: + * @G_APPLICATION_FLAGS_NONE: Default + * @G_APPLICATION_IS_SERVICE: Run as a service. In this mode, registration fails if the service is already running, and the application will stay around for a while when the use count falls to zero. + * @G_APPLICATION_IS_LAUNCHER: Don't try to become the primary instance. + * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in the primary instance) + * @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command line arguments (in the primary instance) + * @G_APPLICATION_SEND_ENVIRONMENT: Send the environment of the launching process to the primary instance * - * Creates a new #GSocketListener with no sockets to listen for. - * New listeners can be added with e.g. g_socket_listener_add_address() - * or g_socket_listener_add_inet_port(). + * Flags used to define the behaviour of a #GApplication. * - * Returns: a new #GSocketListener. - * Since: 2.22 + * Since: 2.26 */ /** - * g_tls_client_connection_set_use_ssl3: - * @conn: the #GTlsClientConnection - * @use_ssl3: whether to use SSL 3.0 - * - * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than - * trying to properly negotiate the right version of TLS or SSL to use. - * This can be used when talking to servers that do not implement the - * fallbacks correctly and which will therefore fail to handshake with - * a "modern" TLS handshake attempt. + * GAskPasswordFlags: + * @G_ASK_PASSWORD_NEED_PASSWORD: operation requires a password. + * @G_ASK_PASSWORD_NEED_USERNAME: operation requires a username. + * @G_ASK_PASSWORD_NEED_DOMAIN: operation requires a domain. + * @G_ASK_PASSWORD_SAVING_SUPPORTED: operation supports saving settings. + * @G_ASK_PASSWORD_ANONYMOUS_SUPPORTED: operation supports anonymous users. * - * Since: 2.28 + * #GAskPasswordFlags are used to request specific information from the + * user, or to notify the user of their choices in an authentication + * situation. */ /** - * g_bus_watch_name_with_closures: - * @bus_type: The type of bus to watch a name on. - * @name: The name (well-known or unique) to watch. - * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. - * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. + * GAsyncInitable: * - * Version of g_bus_watch_name() using closures instead of callbacks for - * easier binding in other languages. - * g_bus_unwatch_name() to stop watching the name. + * Interface for asynchronously initializable objects. * - * Returns: An identifier (never 0) that an be used with - * Rename to: g_bus_watch_name - * Since: 2.26 + * Since: 2.22 */ /** - * g_tls_connection_set_certificate: - * @conn: a #GTlsConnection - * @certificate: the certificate to use for @conn + * GAsyncInitableIface: + * @g_iface: The parent interface. + * @init_async: Starts initialization of the object. + * @init_finish: Finishes initialization of the object. * - * This sets the certificate that @conn will present to its peer - * during the TLS handshake. For a #GTlsServerConnection, it is - * mandatory to set this, and that will normally be done at construct - * time. - * For a #GTlsClientConnection, this is optional. If a handshake fails - * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server - * requires a certificate, and if you try connecting again, you should - * call this method first. You can call - * g_tls_client_connection_get_accepted_cas() on the failed connection - * to get a list of Certificate Authorities that the server will - * accept certificates from. - * (It is also possible that a server will allow the connection with - * or without a certificate; in that case, if you don't provide a - * certificate, you can tell that the server requested one by the fact - * that g_tls_client_connection_get_accepted_cas() will return - * non-%NULL.) + * Provides an interface for asynchronous initializing object such that + * initialization may fail. * - * Since: 2.28 + * Since: 2.22 */ /** - * GObjectSetPropertyFunc: - * @object: a #GObject - * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). - * @value: the new value for the property - * @pspec: the #GParamSpec describing the property + * GAsyncReadyCallback: + * @source_object: the object the asynchronous operation was started with. + * @res: a #GAsyncResult. + * @user_data: user data passed to the callback. * - * The type of the @set_property function of #GObjectClass. + * Type definition for a function that will be called back when an asynchronous + * operation within GIO has been completed. */ /** - * GSocketControlMessageClass: - * @get_size: gets the size of the message. - * @get_level: gets the protocol of the message. - * @get_type: gets the protocol specific type of the message. - * @serialize: Writes out the message data. - * @deserialize: Tries to deserialize a message. - * + * GAsyncResult: * + * Holds results information for an asynchronous operation, + * usually passed directly to a asynchronous _finish() operation. */ /** - * g_converter_output_stream_new: - * @base_stream: a #GOutputStream - * @converter: a #GConverter - * - * Creates a new converter output stream for the @base_stream. + * GAsyncResultIface: + * @g_iface: The parent interface. + * @get_user_data: Gets the user data passed to the callback. + * @get_source_object: Gets the source object that issued the asynchronous operation. * - * Returns: a new #GOutputStream. + * Interface definition for #GAsyncResult. */ /** - * GPollableOutputStreamInterface: - * @g_iface: The parent interface. - * @can_poll: Checks if the #GPollableOutputStream instance is actually pollable - * @is_writable: Checks if the stream is writable - * @create_source: Creates a #GSource to poll the stream - * @write_nonblocking: Does a non-blocking write or returns %G_IO_ERROR_WOULD_BLOCK - * - * The interface for pollable output streams. - * The default implementation of @can_poll always returns %TRUE. - * The default implementation of @write_nonblocking calls - * g_pollable_output_stream_is_writable(), and then calls - * g_output_stream_write() if it returns %TRUE. This means you only - * need to override it if it is possible that your @is_writable - * implementation may return %TRUE when the stream is not actually - * writable. + * GBaseFinalizeFunc: + * @g_class: The #GTypeClass structure to finalize. * - * Since: 2.28 + * A callback function used by the type system to finalize those portions + * of a derived types class structure that were setup from the corresponding + * GBaseInitFunc() function. Class finalization basically works the inverse + * way in which class intialization is performed. + * See GClassInitFunc() for a discussion of the class intialization process. */ @@ -423,1624 +395,1734 @@ /** - * GUnixMountPoint: + * GBinding: * - * Defines a Unix mount point (e.g. <filename>/dev</filename>). - * This corresponds roughly to a fstab entry. + * <structname>GBinding</structname> is an opaque structure whose members + * cannot be accessed directly. + * + * Since: 2.26 */ /** - * g_async_result_get_user_data: - * @res: a #GAsyncResult. + * GBindingFlags: + * @G_BINDING_DEFAULT: The default binding; if the source property changes, the target property is updated with its value. + * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. + * @G_BINDING_SYNC_CREATE: Synchronize the values of the source and target properties when creating the binding; the direction of the synchronization is always from the source to the target. + * @G_BINDING_INVERT_BOOLEAN: If the two properties being bound are booleans, setting one to %TRUE will result in the other being set to %FALSE and vice versa. This flag will only work for boolean properties, and cannot be used when passing custom transformation functions to g_object_bind_property_full(). * - * Gets the user data from a #GAsyncResult. + * Flags to be passed to g_object_bind_property() or + * g_object_bind_property_full(). + * This enumeration can be extended at later date. * - * Returns: (transfer full): the user data for @res. + * Since: 2.26 */ /** - * g_file_poll_mountable: - * @file: input #GFile. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. - * @user_data: the data to pass to callback function + * GBindingTransformFunc: + * @binding: a #GBinding + * @source_value: the value of the source property + * @target_value: the value of the target property + * @user_data: data passed to the transform function * - * Polls a file of type G_FILE_TYPE_MOUNTABLE. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * When the operation is finished, @callback will be called. You can then call - * g_file_mount_mountable_finish() to get the result of the operation. + * A function to be called to transform the source property of @source + * from @source_value into the target property of @target + * using @target_value. + * otherwise * - * Since: 2.22 + * Returns: %TRUE if the transformation was successful, and %FALSE + * Since: 2.26 */ /** - * g_socket_check_connect_result: - * @socket: a #GSocket - * @error: #GError for error reporting, or %NULL to ignore. - * - * Checks and resets the pending connect error for the socket. - * This is used to check for errors when g_socket_connect() is - * used in non-blocking mode. + * GBookmarkFile: * - * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error - * Since: 2.22 + * The <structname>GBookmarkFile</structname> struct contains only + * private data and should not be directly accessed. */ /** - * g_io_module_new: - * @filename: filename of the shared library module. - * - * Creates a new GIOModule that will load the specific - * shared library when in use. - * or %NULL on error. + * GBookmarkFileError: + * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed + * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found + * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not register a bookmark + * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found + * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed + * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding + * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing + * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found * - * Returns: a #GIOModule from given @filename, + * Error codes returned by bookmark file parsing. */ /** - * GTlsConnection::accept-certificate: - * @conn: a #GTlsConnection - * @peer_cert: the peer's #GTlsCertificate - * @errors: the problems with @peer_cert. + * GBoxedCopyFunc: + * @boxed: The boxed structure to be copied. * - * Emitted during the TLS handshake after the peer certificate has - * been received. You can examine @peer_cert's certification path by - * calling g_tls_certificate_get_issuer() on it. - * For a client-side connection, @peer_cert is the server's - * certificate, and the signal will only be emitted if the - * certificate was not acceptable according to @conn's - * #GTlsClientConnection:validation_flags. If you would like the - * certificate to be accepted despite @errors, return %TRUE from the - * signal handler. Otherwise, if no handler accepts the certificate, - * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. - * For a server-side connection, @peer_cert is the certificate - * presented by the client, if this was requested via the server's - * #GTlsServerConnection:authentication_mode. On the server side, - * the signal is always emitted when the client presents a - * certificate, and the certificate will only be accepted if a - * handler returns %TRUE. - * Note that if this signal is emitted as part of asynchronous I/O - * in the main thread, then you should not attempt to interact with - * the user before returning from the signal handler. If you want to - * let the user decide whether or not to accept the certificate, you - * would have to return %FALSE from the signal handler on the first - * attempt, and then after the connection attempt returns a - * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if - * the user decides to accept the certificate, remember that fact, - * create a new connection, and return %TRUE from the signal handler - * the next time. - * If you are doing I/O in another thread, you do not - * need to worry about this, and can simply block in the signal - * handler until the UI thread returns an answer. - * immediately end the signal emission). %FALSE to allow the signal - * emission to continue, which will cause the handshake to fail if - * no one else overrides it. + * This function is provided by the user and should produce a copy of the passed + * in boxed structure. * - * Returns: %TRUE to accept @peer_cert (which will also - * Since: 2.28 + * Returns: The newly created copy of the boxed structure. */ /** - * GOptionArgFunc: - * @option_name: The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name. - * @value: The value to be parsed. - * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() - * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks. + * GBoxedFreeFunc: + * @boxed: The boxed structure to be freed. * - * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK - * options. - * occurred, in which case @error should be set with g_set_error() + * This function is provided by the user and should free the boxed + * structure passed. + */ + + +/** + * GBufferedInputStream: * - * Returns: %TRUE if the option was successfully parsed, %FALSE if an error + * Implements #GFilterInputStream with a sized input buffer. */ /** - * g_application_new: - * @application_id: the application id - * @flags: the application flags - * @returns: a new #GApplication instance + * GBufferedOutputStream: * - * Creates a new #GApplication instance. - * This function calls g_type_init() for you. - * The application id must be valid. See g_application_id_is_valid(). + * An implementation of #GFilterOutputStream with a sized buffer. */ /** - * g_dbus_connection_get_capabilities: - * @connection: A #GDBusConnection. + * GBusAcquiredCallback: + * @connection: The #GDBusConnection to a message bus. + * @name: The name that is requested to be owned. + * @user_data: User data passed to g_bus_own_name(). * - * Gets the capabilities negotiated with the remote peer + * Invoked when a connection to a message bus has been obtained. * - * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration. * Since: 2.26 */ /** - * GSrvTarget: + * GBusNameAcquiredCallback: + * @connection: The #GDBusConnection on which to acquired the name. + * @name: The name being owned. + * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection(). * - * A single target host/port that a network service is running on. + * Invoked when the name is acquired. + * + * Since: 2.26 */ /** - * g_dbus_connection_close: - * @connection: A #GDBusConnection. - * @cancellable: A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. - * @user_data: The data to pass to @callback. + * GBusNameAppearedCallback: + * @connection: The #GDBusConnection the name is being watched on. + * @name: The name being watched. + * @name_owner: Unique name of the owner of the name being watched. + * @user_data: User data passed to g_bus_watch_name(). * - * Closes @connection. Note that this never causes the process to - * exit (this might only happen if the other end of a shared message - * bus connection disconnects, see #GDBusConnection:exit-on-close). - * Once the connection is closed, operations such as sending a message - * will return with the error %G_IO_ERROR_CLOSED. Closing a connection - * will not automatically flush the connection so queued messages may - * be lost. Use g_dbus_connection_flush() if you need such guarantees. - * If @connection is already closed, this method fails with - * %G_IO_ERROR_CLOSED. - * When @connection has been closed, the #GDBusConnection::closed - * signal is emitted in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread that @connection was constructed in. - * This is an asynchronous method. When the operation is finished, - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread you are calling this method from. You can - * then call g_dbus_connection_close_finish() to get the result of the - * operation. See g_dbus_connection_close_sync() for the synchronous - * version. + * Invoked when the name being watched is known to have to have a owner. * * Since: 2.26 */ /** - * g_resolver_lookup_by_address: - * @resolver: a #GResolver - * @address: the address to reverse-resolve - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL + * GBusNameLostCallback: + * @connection: The #GDBusConnection on which to acquire the name or %NULL if the connection was disconnected. + * @name: The name being owned. + * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection(). * - * Synchronously reverse-resolves @address to determine its - * associated hostname. - * If the DNS resolution fails, @error (if non-%NULL) will be set to - * a value from #GResolverError. - * If @cancellable is non-%NULL, it can be used to cancel the - * operation, in which case @error (if non-%NULL) will be set to - * %G_IO_ERROR_CANCELLED. - * form), or %NULL on error. + * Invoked when the name is lost or @connection has been closed. * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded - * Since: 2.22 + * Since: 2.26 */ /** - * GDataStream:newline-type: + * GBusNameOwnerFlags: + * @G_BUS_NAME_OWNER_FLAGS_NONE: No flags set. + * @G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT: Allow another message bus connection to claim the the name. + * @G_BUS_NAME_OWNER_FLAGS_REPLACE: If another message bus connection owns the name and have specified #G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection. * - * The :newline-type property determines what is considered - * as a line ending when reading complete lines from the stream. + * Flags used in g_bus_own_name(). + * + * Since: 2.26 */ /** - * GFileProgressCallback: - * @current_num_bytes: the current number of bytes in the operation. - * @total_num_bytes: the total number of bytes in the operation. - * @user_data: user data passed to the callback. + * GBusNameVanishedCallback: + * @connection: The #GDBusConnection the name is being watched on. + * @name: The name being watched. + * @user_data: User data passed to g_bus_watch_name(). * - * When doing file operations that may take a while, such as moving - * a file or copying a file, a progress callback is used to pass how - * far along that operation is to the application. + * Invoked when the name being watched is known not to have to have a owner. + * + * Since: 2.26 */ /** - * GInitiallyUnowned: + * GBusNameWatcherFlags: + * @G_BUS_NAME_WATCHER_FLAGS_NONE: No flags set. + * @G_BUS_NAME_WATCHER_FLAGS_AUTO_START: If no-one owns the name when beginning to watch the name, ask the bus to launch an owner for the name. * - * All the fields in the <structname>GInitiallyUnowned</structname> structure - * are private to the #GInitiallyUnowned implementation and should never be - * accessed directly. + * Flags used in g_bus_watch_name(). + * + * Since: 2.26 */ /** - * GApplication: + * GBusType: + * @G_BUS_TYPE_STARTER: An alias for the message bus that activated the process, if any. + * @G_BUS_TYPE_NONE: Not a message bus. + * @G_BUS_TYPE_SYSTEM: The system-wide message bus. + * @G_BUS_TYPE_SESSION: The login session message bus. * - * The <structname>GApplication</structname> structure contains private - * data and should only be accessed using the provided API + * An enumeration for well-known message buses. * * Since: 2.26 */ /** - * SECTION:gdbusnameownin: - * @title: Owning Bus Names - * @short_description: Simple API for owning bus names - * @include: gio/gio.h + * GCClosure: + * @closure: the #GClosure + * @callback: the callback function * - * Convenience API for owning bus names. - * <example id="gdbus-owning-names"><title>Simple application owning a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * A #GCClosure is a specialization of #GClosure for C function callbacks. */ /** - * GInetAddress:is-loopback: - * - * Whether this is the loopback address for its family. - * See g_inet_address_get_is_loopback(). + * GCallback: * - * Since: 2.22 + * The type used for callback functions in structure definitions and function + * signatures. This doesn't mean that all callback functions must take no + * parameters and return void. The required signature of a callback function + * is determined by the context in which is used (e.g. the signal to which it + * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. */ /** - * G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER: + * GCancellable: * - * A key in the "standard" namespace for setting the sort order of a file. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32. - * An example use would be in file managers, which would use this key - * to set the order files are displayed. Files with smaller sort order - * should be sorted first, and files without sort order as if sort order - * was zero. + * Allows actions to be cancelled. */ /** - * GTypeInterface: + * GCancellable::cancelled: + * @cancellable: a #GCancellable. * - * An opaque structure used as the base of all interface types. + * Emitted when the operation has been cancelled. + * Can be used by implementations of cancellable operations. If the + * operation is cancelled from another thread, the signal will be + * emitted in the thread that cancelled the operation, not the + * thread that is running the operation. + * Note that disconnecting from this signal (or any signal) in a + * multi-threaded program is prone to race conditions. For instance + * it is possible that a signal handler may be invoked even + * <emphasis>after</emphasis> a call to + * g_signal_handler_disconnect() for that handler has already + * returned. + * There is also a problem when cancellation happen + * right before connecting to the signal. If this happens the + * signal will unexpectedly not be emitted, and checking before + * connecting to the signal leaves a race condition where this is + * still happening. + * In order to make it safe and easy to connect handlers there + * g_cancellable_disconnect() which protect against problems + * like this. + * An example of how to us this: + * |[ + * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/ + * if (g_cancellable_set_error_if_cancelled (cancellable)) + * return; + * /<!-- -->* Set up all the data needed to be able to + * * handle cancellation of the operation *<!-- -->/ + * my_data = my_data_new (...); + * id = 0; + * if (cancellable) + * id = g_cancellable_connect (cancellable, + * G_CALLBACK (cancelled_handler) + * data, NULL); + * /<!-- -->* cancellable operation here... *<!-- -->/ + * g_cancellable_disconnect (cancellable, id); + * /<!-- -->* cancelled_handler is never called after this, it + * * is now safe to free the data *<!-- -->/ + * my_data_free (my_data); + * ]| + * Note that the cancelled signal is emitted in the thread that + * the user cancelled from, which may be the main thread. So, the + * cancellable signal should not do something that can block. + * + * Are two helper functions: g_cancellable_connect() and */ /** - * G_TYPE_VALUE: + * GCancellableSourceFunc: + * @cancellable: the #GCancellable + * @user_data: data passed in by the user. * - * The type ID of the "GValue" type which is a boxed type, - * used to pass around pointers to GValues. + * This is the function type of the callback used for the #GSource + * returned by g_cancellable_source_new(). + * + * Returns: it should return %FALSE if the source should be removed. + * Since: 2.28 */ /** - * GSettings:path: + * GCharsetConverter: * - * The path within the backend where the settings are stored. + * Conversions between character sets. */ /** - * GDBusMethodInvocationClass: + * GChecksum: * - * Class structure for #GDBusMethodInvocation. + * An opaque structure representing a checksumming operation. + * To create a new GChecksum, use g_checksum_new(). To free + * a GChecksum, use g_checksum_free(). * - * Since: 2.26 + * Since: 2.16 */ /** - * G_PARAM_SPEC_TYPE_NAME: - * @pspec: a valid #GParamSpec + * GChecksumType: + * @G_CHECKSUM_MD5: Use the MD5 hashing algorithm + * @G_CHECKSUM_SHA1: Use the SHA-1 hashing algorithm + * @G_CHECKSUM_SHA256: Use the SHA-256 hashing algorithm * - * Retrieves the #GType name of this @pspec. + * The hashing algorithm to be used by #GChecksum when performing the + * digest of some data. + * Note that the #GChecksumType enumeration may be extended at a later + * date to include new hashing algorithm types. + * + * Since: 2.16 */ /** - * g_dbus_method_invocation_get_user_data: (skip) - * @invocation: A #GDBusMethodInvocation. + * GChildWatchFunc: + * @pid: the process id of the child process + * @status: Status information about the child process, see waitpid(2) for more information about this field + * @data: user data passed to g_child_watch_add() * - * Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). + * The type of functions to be called when a child exists. + */ + + +/** + * GClassFinalizeFunc: + * @g_class: The #GTypeClass structure to finalize. + * @class_data: The @class_data member supplied via the #GTypeInfo structure. * - * Returns: A #gpointer. - * Since: 2.26 + * A callback function used by the type system to finalize a class. + * This function is rarely needed, as dynamically allocated class resources + * should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). + * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo + * structure of a static type is invalid, because classes of static types + * will never be finalized (they are artificially kept alive when their + * reference count drops to zero). */ /** - * g_unix_mount_point_guess_icon: - * @mount_point: a #GUnixMountPoint + * GClassInitFunc: + * @g_class: The #GTypeClass structure to initialize. + * @class_data: The @class_data member supplied via the #GTypeInfo structure. * - * Guesses the icon of a Unix mount point. + * A callback function used by the type system to initialize the class + * of a specific type. This function should initialize all static class + * members. + * The initialization process of a class involves: + * <itemizedlist> + * <listitem><para> + * 1 - Copying common members from the parent class over to the + * derived class structure. + * </para></listitem> + * <listitem><para> + * 2 - Zero initialization of the remaining members not copied + * over from the parent class. + * </para></listitem> + * <listitem><para> + * 3 - Invocation of the GBaseInitFunc() initializers of all parent + * types and the class' type. + * </para></listitem> + * <listitem><para> + * 4 - Invocation of the class' GClassInitFunc() initializer. + * </para></listitem> + * </itemizedlist> + * Since derived classes are partially initialized through a memory copy + * of the parent class, the general rule is that GBaseInitFunc() and + * GBaseFinalizeFunc() should take care of necessary reinitialization + * and release of those class members that were introduced by the type + * that specified these GBaseInitFunc()/GBaseFinalizeFunc(). + * GClassInitFunc() should only care about initializing static + * class members, while dynamic class members (such as allocated strings + * or reference counted resources) are better handled by a GBaseInitFunc() + * for this type, so proper initialization of the dynamic class members + * is performed for class initialization of derived types as well. + * An example may help to correspond the intend of the different class + * initializers: + * |[ + * typedef struct { + * GObjectClass parent_class; + * gint static_integer; + * gchar *dynamic_string; + * } TypeAClass; + * static void + * type_a_base_class_init (TypeAClass *class) + * { + * class->dynamic_string = g_strdup ("some string"); + * } + * static void + * type_a_base_class_finalize (TypeAClass *class) + * { + * g_free (class->dynamic_string); + * } + * static void + * type_a_class_init (TypeAClass *class) + * { + * class->static_integer = 42; + * } + * typedef struct { + * TypeAClass parent_class; + * gfloat static_float; + * GString *dynamic_gstring; + * } TypeBClass; + * static void + * type_b_base_class_init (TypeBClass *class) + * { + * class->dynamic_gstring = g_string_new ("some other string"); + * } + * static void + * type_b_base_class_finalize (TypeBClass *class) + * { + * g_string_free (class->dynamic_gstring); + * } + * static void + * type_b_class_init (TypeBClass *class) + * { + * class->static_float = 3.14159265358979323846; + * } + * ]| + * Initialization of TypeBClass will first cause initialization of + * TypeAClass (derived classes reference their parent classes, see + * g_type_class_ref() on this). + * Initialization of TypeAClass roughly involves zero-initializing its fields, + * then calling its GBaseInitFunc() type_a_base_class_init() to allocate + * its dynamic members (dynamic_string), and finally calling its GClassInitFunc() + * type_a_class_init() to initialize its static members (static_integer). + * The first step in the initialization process of TypeBClass is then + * a plain memory copy of the contents of TypeAClass into TypeBClass and + * zero-initialization of the remaining fields in TypeBClass. + * The dynamic members of TypeAClass within TypeBClass now need + * reinitialization which is performed by calling type_a_base_class_init() + * with an argument of TypeBClass. + * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() + * is called to allocate the dynamic members of TypeBClass (dynamic_gstring), + * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), + * is called to complete the initialization process with the static members + * (static_float). + * Corresponding finalization counter parts to the GBaseInitFunc() functions + * have to be provided to release allocated resources at class finalization + * time. + */ + + +/** + * GClosure: + * @in_marshal: Indicates whether the closure is currently being invoked with g_closure_invoke() + * @is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate() * - * Returns: (transfer full): a #GIcon + * A #GClosure represents a callback supplied by the programmer. */ /** - * g_settings_get: - * @settings: a #GSettings object - * @key: the key to get the value for - * @format: a #GVariant format string - * @...: arguments as per @format + * GClosureMarshal: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. + * @n_param_values: the length of the @param_values array + * @param_values: an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() * - * Gets the value that is stored at @key in @settings. - * A convenience function that combines g_settings_get_value() with - * g_variant_get(). - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or for the #GVariantType of @format to mismatch - * the type given in the schema. + * The type used for marshaller functions. + */ + + +/** + * GClosureNotify: + * @data: data specified when registering the notification callback + * @closure: the #GClosure on which the notification is emitted * - * Since: 2.26 + * The type used for the various notification callbacks which can be registered + * on closures. */ /** - * g_socket_control_message_get_size: - * @message: a #GSocketControlMessage + * GConnectFlags: + * @G_CONNECT_AFTER: whether the handler should be called before or after the default handler of the signal. + * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when calling the handler. * - * Returns the space required for the control message, not including - * headers or alignment. + * The connection flags are used to specify the behaviour of a signal's + * connection. + */ + + +/** + * GConvertError: + * @G_CONVERT_ERROR_NO_CONVERSION: Conversion between the requested character sets is not supported. + * @G_CONVERT_ERROR_ILLEGAL_SEQUENCE: Invalid byte sequence in conversion input. + * @G_CONVERT_ERROR_FAILED: Conversion failed for some reason. + * @G_CONVERT_ERROR_PARTIAL_INPUT: Partial character sequence at end of input. + * @G_CONVERT_ERROR_BAD_URI: URI is invalid. + * @G_CONVERT_ERROR_NOT_ABSOLUTE_PATH: Pathname is not an absolute path. * - * Returns: The number of bytes required. - * Since: 2.22 + * Error codes returned by character set conversion routines. */ /** - * g_settings_new_with_path: - * @schema: the name of the schema - * @path: the path to use - * @returns: a new #GSettings object + * GConverter: * - * Creates a new #GSettings object with a given schema and path. - * You only need to do this if you want to directly create a settings - * object with a schema that doesn't have a specified path of its own. - * That's quite rare. - * It is a programmer error to call this function for a schema that - * has an explicitly specified path. + * Seek object for streaming operations. * - * Since: 2.26 + * Since: 2.24 */ /** - * g_file_info_set_edit_name: - * @info: a #GFileInfo. - * @edit_name: a string containing an edit name. + * GConverterFlags: + * @G_CONVERTER_NO_FLAGS: No flags. + * @G_CONVERTER_INPUT_AT_END: At end of input data + * @G_CONVERTER_FLUSH: Flush data * - * Sets the edit name for the current file. - * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. + * Flags used when calling a g_converter_convert(). + * + * Since: 2.24 */ /** - * g_drive_can_start: - * @drive: a #GDrive. + * GConverterIface: + * @g_iface: The parent interface. + * @convert: Converts data. + * @reset: Reverts the internal state of the converter to its initial state. * - * Checks if a drive can be started. + * Provides an interface for converting data from one type + * to another type. The conversion can be stateful + * and may fail at any place. * - * Returns: %TRUE if the @drive can be started, %FALSE otherwise. - * Since: 2.22 + * Since: 2.24 */ /** - * g_socket_service_is_active: - * @service: a #GSocketService + * GConverterInputStream: * - * Check whether the service is active or not. An active - * service will accept new clients that connect, while - * a non-active service will let connecting clients queue - * up until the service is started. + * An implementation of #GFilterInputStream that allows data + * conversion. + */ + + +/** + * GConverterOutputStream: * - * Returns: %TRUE if the service is active, %FALSE otherwise - * Since: 2.22 + * An implementation of #GFilterOutputStream that allows data + * conversion. */ /** - * G_NODE_IS_LEAF: - * @node: a #GNode + * GConverterResult: + * @G_CONVERTER_ERROR: There was an error during conversion. + * @G_CONVERTER_CONVERTED: Some data was consumed or produced + * @G_CONVERTER_FINISHED: The conversion is finished + * @G_CONVERTER_FLUSHED: Flushing is finished * - * Returns %TRUE if a #GNode is a leaf node. - * (i.e. it has no children) + * Results returned from g_converter_convert(). * - * Returns: %TRUE if the #GNode is a leaf node + * Since: 2.24 */ /** - * GTlsConnection:rehandshake-mode: + * GCopyFunc: + * @src: A pointer to the data which should be copied + * @data: Additional data * - * The rehandshaking mode. See - * g_tls_connection_set_rehandshake_mode(). + * A function of this signature is used to copy the node data + * when doing a deep-copy of a tree. * - * Since: 2.28 + * Returns: A pointer to the copy + * Since: 2.4 */ /** - * g_proxy_address_get_usernam: - * @proxy: a #GProxyAddress + * GCredentials: * - * Gets @proxy's username. + * The #GCredentials structure contains only private data and + * should only be accessed using the provided API. * - * Returns: the @proxy's username * Since: 2.26 */ /** - * g_initable_init: - * @initable: a #GInitable. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * GCredentialsClass: * - * Initializes the object implementing the interface. This must be - * done before any real use of the object after initial construction. - * Implementations may also support cancellation. If @cancellable is not %NULL, - * then initialization can be cancelled by triggering the cancellable object - * from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and - * the object doesn't support cancellable initialization the error - * %G_IO_ERROR_NOT_SUPPORTED will be returned. - * If this function is not called, or returns with an error then all - * operations on the object should fail, generally returning the - * error %G_IO_ERROR_NOT_INITIALIZED. - * Implementations of this method must be idempotent, i.e. multiple calls - * to this function with the same argument should return the same results. - * Only the first call initializes the object, further calls return the result - * of the first call. This is so that its safe to implement the singleton - * pattern in the GObject constructor function. - * return %FALSE and set @error appropriately if present. + * Class structure for #GCredentials. * - * Returns: %TRUE if successful. If an error has occurred, this function will - * Since: 2.22 + * Since: 2.26 */ /** - * g_drive_enumerate_identifiers: - * @drive: a #GDrive + * GCredentialsType: + * @G_CREDENTIALS_TYPE_INVALID: Indicates an invalid native credential type. + * @G_CREDENTIALS_TYPE_LINUX_UCRED: The native credentials type is a <type>struct ucred</type>. + * @G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED: The native credentials type is a <type>struct cmsgcred</type>. * - * Gets the kinds of identifiers that @drive has. - * Use g_drive_get_identifer() to obtain the identifiers - * themselves. - * array of strings containing kinds of identifiers. Use g_strfreev() - * to free. + * Enumeration describing different kinds of native credential types. * - * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated + * Since: 2.26 */ /** - * g_volume_monitor_get_volumes: - * @volume_monitor: a #GVolumeMonitor. + * GDBusAnnotationInfo: + * @ref_count: The reference count or -1 if statically allocated. + * @key: The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated". + * @value: The value of the annotation. + * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. * - * Gets a list of the volumes on the system. - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). + * Information about an annotation. * - * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects. + * Since: 2.26 */ /** - * g_dbus_message_new_signal: - * @path: A valid object path. - * @interface_: A valid D-Bus interface name. - * @signal: A valid signal name. + * GDBusArgInfo: + * @ref_count: The reference count or -1 if statically allocated. + * @name: Name of the argument, e.g. @unix_user_id. + * @signature: D-Bus signature of the argument (a single complete type). + * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. * - * Creates a new #GDBusMessage for a signal emission. + * Information about an argument for a method or a signal. * - * Returns: A #GDBusMessage. Free with g_object_unref(). * Since: 2.26 */ /** - * g_settings_bind_writable: - * @settings: a #GSettings object - * @key: the key to bind - * @object: (type GObject.Object): a #GObject - * @property: the name of a boolean property to bind - * @inverted: whether to 'invert' the value - * - * Create a binding between the writability of @key in the - * The property must be boolean; "sensitive" or "visible" - * properties of widgets are the most likely candidates. - * Writable bindings are always uni-directional; changes of the - * writability of the setting will be propagated to the object - * property, not the other way. - * When the @inverted argument is %TRUE, the binding inverts the - * value as it passes from the setting to the object, i.e. @property - * will be set to %TRUE if the key is <emphasis>not</emphasis> - * writable. - * Note that the lifecycle of the binding is tied to the object, - * and that you can have only one binding per object property. - * If you bind the same property twice on the same object, the second - * binding overrides the first one. + * GDBusAuthMechanism:credentials: * - * Since: 2.26 + * If authenticating as a server, this property contains the + * received credentials, if any. + * If authenticating as a client, the property contains the + * credentials that were sent, if any. */ /** - * g_memory_input_stream_new_from_data: - * @data: (array length=len) (element-type guint8): input data - * @len: length of the data, may be -1 if @data is a nul-terminated string - * @destroy: (allow-none): function that is called to free @data, or %NULL + * GDBusAuthObserver: * - * Creates a new #GMemoryInputStream with data in memory of a given size. + * The #GDBusAuthObserver structure contains only private data and + * should only be accessed using the provided API. * - * Returns: new #GInputStream read from @data of @len bytes. + * Since: 2.26 */ /** - * G_ENUM_CLASS_TYPE_NAME: - * @class: a #GEnumClass + * GDBusAuthObserver::authorize-authenticated-peer: + * @observer: The #GDBusAuthObserver emitting the signal. + * @stream: A #GIOStream for the #GDBusConnection. + * @credentials: Credentials received from the peer or %NULL. * - * Get the static type name from a given #GEnumClass structure. + * Emitted to check if a peer that is successfully authenticated + * is authorized. * - * Returns: the type name. + * Returns: %TRUE if the peer is authorized, %FALSE if not. + * Since: 2.26 */ /** - * GInputVector: - * @buffer: Pointer to a buffer where data will be written. - * @size: the available size in @buffer. + * GDBusAuthObserverClass: + * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal. * - * Structure used for scatter/gather data input. - * You generally pass in an array of #GInputVector<!-- -->s - * and the operation will store the read data starting in the - * first buffer, switching to the next as needed. + * Class structure for #GDBusAuthObserverClass. * - * Since: 2.22 + * Since: 2.26 */ /** - * g_socket_connection_get_socket: - * @connection: a #GSocketConnection + * GDBusCallFlags: + * @G_DBUS_CALL_FLAGS_NONE: No flags set. + * @G_DBUS_CALL_FLAGS_NO_AUTO_START: The bus must not launch an owner for the destination name in response to this method invocation. * - * Gets the underlying #GSocket object of the connection. - * This can be useful if you want to do something unusual on it - * not supported by the #GSocketConnection APIs. + * Flags used in g_dbus_connection_call() and similar APIs. * - * Returns: (transfer none): a #GSocketAddress or %NULL on error. - * Since: 2.22 + * Since: 2.26 */ /** - * g_input_stream_is_closed: - * @stream: input stream. + * GDBusCapabilityFlags: + * @G_DBUS_CAPABILITY_FLAGS_NONE: No flags set. + * @G_DBUS_CAPABILITY_FLAGS_UNIX_FD_PASSING: The connection supports exchanging UNIX file descriptors with the remote peer. * - * Checks if an input stream is closed. + * Capabilities negotiated with the remote peer. * - * Returns: %TRUE if the stream is closed. + * Since: 2.26 */ /** - * g_credentials_get_native: (skip) - * @credentials: A #GCredentials. - * @native_type: The type of native credentials to get. + * GDBusConnection: * - * Gets a pointer to native credentials of type @native_type from - * It is a programming error (which will cause an warning to be - * logged) to use this method if there is no #GCredentials support for - * the OS or if @native_type isn't supported by the OS. - * operation there is no #GCredentials support for the OS or if - * data, it is owned by @credentials. + * The #GDBusConnection structure contains only private data and + * should only be accessed using the provided API. * - * Returns: The pointer to native credentials or %NULL if the * Since: 2.26 */ /** - * G_TYPE_PARAM_UCHAR: + * GDBusConnection::closed: + * @connection: The #GDBusConnection emitting the signal. + * @remote_peer_vanished: %TRUE if @connection is closed because the remote peer closed its end of the connection. + * @error: A #GError with more details about the event or %NULL. * - * The #GType of #GParamSpecUChar. + * Emitted when the connection is closed. + * The cause of this event can be + * <itemizedlist> + * <listitem><para> + * If g_dbus_connection_close() is called. In this case + * </para></listitem> + * <listitem><para> + * If the remote peer closes the connection. In this case + * </para></listitem> + * <listitem><para> + * If the remote peer sends invalid or malformed data. In this + * case @remote_peer_vanished is set to %FALSE and @error + * is set. + * </para></listitem> + * </itemizedlist> + * Upon receiving this signal, you should give up your reference to + * once. + * + * Since: 2.26 */ /** - * G_TYPE_PARAM_POINTER: + * GDBusConnection:address: * - * The #GType of #GParamSpecPointer. + * A D-Bus address specifying potential endpoints that can be used + * when establishing the connection. + * + * Since: 2.26 */ /** - * g_file_replace_contents: - * @file: input #GFile. - * @contents: a string containing the new contents for @file. - * @length: the length of @contents in bytes. - * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link> for the document, or %NULL - * @make_backup: %TRUE if a backup should be created. - * @flags: a set of #GFileCreateFlags. - * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when no longer needed, or %NULL - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * GDBusConnection:authentication-observer: * - * Replaces the contents of @file with @contents of @length bytes. - * If @etag is specified (not %NULL) any existing file must have that etag, or - * the error %G_IO_ERROR_WRONG_ETAG will be returned. - * If @make_backup is %TRUE, this function will attempt to make a backup of @file. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * The returned @new_etag can be used to verify that the file hasn't changed the - * next time it is saved over. - * has occurred, this function will return %FALSE and set @error - * appropriately if present. + * A #GDBusAuthObserver object to assist in the authentication process or %NULL. * - * Returns: %TRUE if successful. If an error + * Since: 2.26 */ /** - * g_inet_address_to_bytes: (skip) - * @address: a #GInetAddress + * GDBusConnection:capabilities: * - * Gets the raw binary address data from @address. - * which should not be modified, stored, or freed. The size of this - * array can be gotten with g_inet_address_get_native_size(). + * Flags from the #GDBusCapabilityFlags enumeration + * representing connection features negotiated with the other peer. * - * Returns: a pointer to an internal array of the bytes in @address, - * Since: 2.22 + * Since: 2.26 */ /** - * G_TYPE_HASH_TABLE: + * GDBusConnection:closed: * - * The #GType for a boxed type holding a #GHashTable reference. + * A boolean specifying whether the connection has been closed. * - * Since: 2.10 + * Since: 2.26 */ /** - * g_file_get_path: - * @file: input #GFile. + * GDBusConnection:exit-on-close: * - * Gets the local pathname for #GFile, if one exists. - * This call does no blocking i/o. - * no such path exists. The returned string should be - * freed with g_free() when no longer needed. + * A boolean specifying whether the process will be terminated (by + * calling <literal>raise(SIGTERM)</literal>) if the connection + * is closed by the remote peer. * - * Returns: string containing the #GFile's path, or %NULL if + * Since: 2.26 */ /** - * GIOErrorEnum: - * @G_IO_ERROR_FAILED: Generic error condition for when any operation fails. - * @G_IO_ERROR_NOT_FOUND: File not found error. - * @G_IO_ERROR_EXISTS: File already exists error. - * @G_IO_ERROR_IS_DIRECTORY: File is a directory error. - * @G_IO_ERROR_NOT_DIRECTORY: File is not a directory. - * @G_IO_ERROR_NOT_EMPTY: File is a directory that isn't empty. - * @G_IO_ERROR_NOT_REGULAR_FILE: File is not a regular file. - * @G_IO_ERROR_NOT_SYMBOLIC_LINK: File is not a symbolic link. - * @G_IO_ERROR_NOT_MOUNTABLE_FILE: File cannot be mounted. - * @G_IO_ERROR_FILENAME_TOO_LONG: Filename is too many characters. - * @G_IO_ERROR_INVALID_FILENAME: Filename is invalid or contains invalid characters. - * @G_IO_ERROR_TOO_MANY_LINKS: File contains too many symbolic links. - * @G_IO_ERROR_NO_SPACE: No space left on drive. - * @G_IO_ERROR_INVALID_ARGUMENT: Invalid argument. - * @G_IO_ERROR_PERMISSION_DENIED: Permission denied. - * @G_IO_ERROR_NOT_SUPPORTED: Operation not supported for the current backend. - * @G_IO_ERROR_NOT_MOUNTED: File isn't mounted. - * @G_IO_ERROR_ALREADY_MOUNTED: File is already mounted. - * @G_IO_ERROR_CLOSED: File was closed. - * @G_IO_ERROR_CANCELLED: Operation was cancelled. See #GCancellable. - * @G_IO_ERROR_PENDING: Operations are still pending. - * @G_IO_ERROR_READ_ONLY: File is read only. - * @G_IO_ERROR_CANT_CREATE_BACKUP: Backup couldn't be created. - * @G_IO_ERROR_WRONG_ETAG: File's Entity Tag was incorrect. - * @G_IO_ERROR_TIMED_OUT: Operation timed out. - * @G_IO_ERROR_WOULD_RECURSE: Operation would be recursive. - * @G_IO_ERROR_BUSY: File is busy. - * @G_IO_ERROR_WOULD_BLOCK: Operation would block. - * @G_IO_ERROR_HOST_NOT_FOUND: Host couldn't be found (remote operations). - * @G_IO_ERROR_WOULD_MERGE: Operation would merge files. - * @G_IO_ERROR_FAILED_HANDLED: Operation failed and a helper program has already interacted with the user. Do not display any error dialog. - * @G_IO_ERROR_TOO_MANY_OPEN_FILES: The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20 - * @G_IO_ERROR_NOT_INITIALIZED: The object has not been initialized. Since 2.22 - * @G_IO_ERROR_ADDRESS_IN_USE: The requested address is already in use. Since 2.22 - * @G_IO_ERROR_PARTIAL_INPUT: Need more input to finish operation. Since 2.24 - * @G_IO_ERROR_INVALID_DATA: There input data was invalid. Since 2.24 - * @G_IO_ERROR_DBUS_ERROR: A remote object generated an error that doesn't correspond to a locally registered #GError error domain. Use g_dbus_error_get_remote_error() to extract the D-Bus error name and g_dbus_error_strip_remote_error() to fix up the message so it matches what was received on the wire. Since 2.26. - * @G_IO_ERROR_HOST_UNREACHABLE: Host unreachable. Since 2.26 - * @G_IO_ERROR_NETWORK_UNREACHABLE: Network unreachable. Since 2.26 - * @G_IO_ERROR_CONNECTION_REFUSED: Connection refused. Since 2.26 - * @G_IO_ERROR_PROXY_FAILED: Connection to proxy server failed. Since 2.26 - * @G_IO_ERROR_PROXY_AUTH_FAILED: Proxy authentication failed. Since 2.26 - * @G_IO_ERROR_PROXY_NEED_AUTH: Proxy server needs authentication. Since 2.26 - * @G_IO_ERROR_PROXY_NOT_ALLOWED: Proxy connection is not allowed by ruleset. Since 2.26 + * GDBusConnection:flags: * - * Error codes returned by GIO functions. + * Flags from the #GDBusConnectionFlags enumeration. + * + * Since: 2.26 */ /** - * g_file_input_stream_query_info: - * @stream: a #GFileInputStream. - * @attributes: a file attribute query string. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * GDBusConnection:guid: * - * Queries a file input stream the given @attributes. This function blocks - * while querying the stream. For the asynchronous (non-blocking) version - * of this function, see g_file_input_stream_query_info_async(). While the - * stream is blocked, the stream will set the pending flag internally, and - * any other operations on the stream will fail with %G_IO_ERROR_PENDING. + * The GUID of the peer performing the role of server when + * authenticating. + * If you are constructing a #GDBusConnection and pass + * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the + * #GDBusConnection:flags property then you MUST also set this + * property to a valid guid. + * If you are constructing a #GDBusConnection and pass + * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the + * #GDBusConnection:flags property you will be able to read the GUID + * of the other peer here after the connection has been successfully + * initialized. * - * Returns: (transfer full): a #GFileInfo, or %NULL on error. + * Since: 2.26 */ /** - * G_IS_PARAM_SPEC_ENUM: - * @pspec: a valid #GParamSpec instance + * GDBusConnection:locked: * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. + * A boolean specifying whether the message is locked. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME: + * GDBusConnection:stream: * - * A key in the "standard" namespace for getting the display name of the file. - * A display name is guaranteed to be in UTF8 and can thus be displayed in - * the UI. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * The underlying #GIOStream used for I/O. + * + * Since: 2.26 */ /** - * g_permission_acquire_finish: - * @permission: a #GPermission instance - * @result: the #GAsyncResult given to the #GAsyncReadyCallback - * @error: a pointer to a %NULL #GError, or %NULL - * @returns: %TRUE if the permission was successfully acquired + * GDBusConnection:unique-name: * - * Collects the result of attempting to acquire the permission - * represented by @permission. - * This is the second half of the asynchronous version of - * g_permission_acquire(). + * The unique name as assigned by the message bus or %NULL if the + * connection is not open or not a message bus connection. * * Since: 2.26 */ /** - * G_TYPE_INTERFACE: + * GDBusConnectionClass: + * @closed: Signal class handler for the #GDBusConnection::closed signal. * - * The fundamental type from which all interfaces are derived. + * Class structure for #GDBusConnection. + * + * Since: 2.26 */ /** - * g_file_mount_enclosing_volume_finish: - * @location: input #GFile. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * GDBusConnectionFlags: + * @G_DBUS_CONNECTION_FLAGS_NONE: No flags set. + * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT: Perform authentication against server. + * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER: Perform authentication against client. + * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: When authenticating as a server, allow the anonymous authentication method. + * @G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION: Pass this flag if connecting to a peer that is a message bus. This means that the Hello() method will be invoked as part of the connection setup. + * @G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING: If set, processing of D-Bus messages is delayed until g_dbus_connection_start_message_processing() is called. * - * Finishes a mount operation started by g_file_mount_enclosing_volume(). - * has occurred, this function will return %FALSE and set @error - * appropriately if present. + * Flags used when creating a new #GDBusConnection. * - * Returns: %TRUE if successful. If an error + * Since: 2.26 */ /** - * g_application_id_is_valid: - * @application_id: a potential application identifier - * @returns: %TRUE if @application_id is valid + * GDBusError: * - * Checks if @application_id is a valid application identifier. - * A valid ID is required for calls to g_application_new() and - * g_application_set_application_id(). - * For convenience, the restrictions on application identifiers are - * reproduced here: - * <itemizedlist> - * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.</listitem> - * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least two elements).</listitem> - * <listitem>Application identifiers must not begin with a '.' (period) character.</listitem> - * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem> - * <listitem>Application identifiers must not exceed 255 characters.</listitem> - * </itemizedlist> + * A generic error; "something went wrong" - see the error message for + * more. + * There was not enough memory to complete an operation. + * The bus doesn't know how to launch a service to supply the bus name + * you wanted. + * The bus name you referenced doesn't exist (i.e. no application owns + * it). + * No reply to a message expecting one, usually means a timeout occurred. + * Something went wrong reading or writing to a socket, for example. + * A D-Bus bus address was malformed. + * Requested operation isn't supported (like ENOSYS on UNIX). + * Some limited resource is exhausted. + * Security restrictions don't allow doing what you're trying to do. + * Authentication didn't work. + * Unable to connect to server (probably caused by ECONNREFUSED on a + * socket). + * Certain timeout errors, possibly ETIMEDOUT on a socket. Note that + * %G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning: + * this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also + * exists. We can't fix it for compatibility reasons so just be + * careful. + * No network access (probably ENETUNREACH on a socket). + * Can't bind a socket since its address is in use (i.e. EADDRINUSE). + * The connection is disconnected and you're trying to use it. + * Invalid arguments passed to a method call. + * Missing file. + * Existing file and the operation you're using does not silently overwrite. + * Method name you invoked isn't known by the object you invoked it on. + * confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We + * can't fix it for compatibility reasons so just be careful. + * Tried to remove or modify a match rule that didn't exist. + * The match rule isn't syntactically valid. + * While starting a new process, the exec() call failed. + * While starting a new process, the fork() call failed. + * While starting a new process, the child exited with a status code. + * While starting a new process, the child exited on a signal. + * While starting a new process, something went wrong. + * We failed to setup the environment correctly. + * We failed to setup the config parser correctly. + * Bus name was not valid. + * Service file not found in system-services directory. + * Permissions are incorrect on the setuid helper. + * Service file invalid (Name, User or Exec missing). + * Tried to get a UNIX process ID and it wasn't available. + * Tried to get a UNIX process ID and it wasn't available. + * A type signature is not valid. + * A file contains invalid syntax or is otherwise broken. + * Asked for SELinux security context and it wasn't available. + * Asked for ADT audit data and it wasn't available. + * There's already an object with the requested object path. + * Error codes for the %G_DBUS_ERROR error domain. + * + * Certain timeout errors, e.g. while starting a service. warning: this is + * Since: 2.26 */ /** - * g_resolver_lookup_service_async: - * @resolver: a #GResolver - * @service: the service type to look up (eg, "ldap") - * @protocol: the networking protocol to use for @service (eg, "tcp") - * @domain: the DNS domain to look up the service in - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback + * GDBusErrorEntry: + * @error_code: An error code. + * @dbus_error_name: The D-Bus error name to associate with @error_code. * - * Begins asynchronously performing a DNS SRV lookup for the given - * get the final result. See g_resolver_lookup_service() for more - * details. + * Struct used in g_dbus_error_register_error_domain(). * - * Since: 2.22 + * Since: 2.26 */ /** - * g_proxy_resolver_lookup: - * @resolver: a #GProxyResolver - * @uri: a URI representing the destination to connect to - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL + * GDBusInterfaceGetPropertyFunc: + * @connection: A #GDBusConnection. + * @sender: The unique bus name of the remote caller. + * @object_path: The object path that the method was invoked on. + * @interface_name: The D-Bus interface name for the property. + * @property_name: The name of the property to get the value of. + * @error: Return location for error. + * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object(). * - * Looks into the system proxy configuration to determine what proxy, - * if any, to use to connect to @uri. The returned proxy URIs are of the - * form <literal><protocol>://[user[:password]@]host:port</literal> - * or <literal>direct://</literal>, where <protocol> could be - * http, rtsp, socks or other proxying protocol. - * If you don't know what network protocol is being used on the - * socket, you should use <literal>none</literal> as the URI protocol. - * In this case, the resolver might still return a generic proxy type - * (such as SOCKS), but would not return protocol-specific proxy types - * (such as http). - * <literal>direct://</literal> is used when no proxy is needed. - * Direct connection should not be attempted unless it is part of the - * returned array of proxies. - * NULL-terminated array of proxy URIs. Must be freed - * with g_strfreev(). + * The type of the @get_property function in #GDBusInterfaceVTable. + * consumed - otherwise its reference count is decreased by one. * - * Returns: (transfer full) (array zero-terminated=1): A + * Returns: A #GVariant with the value for @property_name or %NULL if * Since: 2.26 */ /** - * g_data_output_stream_new: - * @base_stream: a #GOutputStream. + * GDBusInterfaceInfo: + * @ref_count: The reference count or -1 if statically allocated. + * @name: The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties". + * @methods: A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods. + * @signals: A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals. + * @properties: A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties. + * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. * - * Creates a new data output stream for @base_stream. + * Information about a D-Bus interface. * - * Returns: #GDataOutputStream. + * Since: 2.26 */ /** - * SECTION:gpollableinputstrea: - * @short_description: Interface for pollable input streams - * @include: gio/gio.h - * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased + * GDBusInterfaceMethodCallFunc: + * @connection: A #GDBusConnection. + * @sender: The unique bus name of the remote caller. + * @object_path: The object path that the method was invoked on. + * @interface_name: The D-Bus interface name the method was invoked on. + * @method_name: The name of the method that was invoked. + * @parameters: A #GVariant tuple with parameters. + * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error. + * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object(). * - * #GPollableInputStream is implemented by #GInputStream<!-- -->s that - * can be polled for readiness to read. This can be used when - * interfacing with a non-GIO API that expects - * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. + * The type of the @method_call function in #GDBusInterfaceVTable. * - * Since: 2.28 + * Since: 2.26 */ /** - * GParamSpecString: - * @parent_instance: private #GParamSpec portion - * @default_value: default value for the property specified - * @cset_first: a string containing the allowed values for the first byte - * @cset_nth: a string containing the allowed values for the subsequent bytes - * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth. - * @null_fold_if_empty: replace empty string by %NULL - * @ensure_non_null: replace %NULL strings by an empty string + * GDBusInterfaceSetPropertyFunc: + * @connection: A #GDBusConnection. + * @sender: The unique bus name of the remote caller. + * @object_path: The object path that the method was invoked on. + * @interface_name: The D-Bus interface name for the property. + * @property_name: The name of the property to get the value of. + * @value: The value to set the property to. + * @error: Return location for error. + * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object(). * - * A #GParamSpec derived structure that contains the meta data for string - * properties. + * The type of the @set_property function in #GDBusInterfaceVTable. + * + * Returns: %TRUE if the property was set to @value, %FALSE if @error is set. + * Since: 2.26 */ /** - * g_file_make_director: - * @file: input #GFile. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * GDBusInterfaceVTable: + * @method_call: Function for handling incoming method calls. + * @get_property: Function for getting a property. + * @set_property: Function for setting a property. * - * Creates a directory. Note that this will only create a child directory of - * the immediate parent directory of the path or URI given by the #GFile. To - * recursively create directories, see g_file_make_directory_with_parents(). - * This function will fail if the parent directory does not exist, setting - * directories, this function will fail, setting @error to - * %G_IO_ERROR_NOT_SUPPORTED. - * For a local #GFile the newly created directory will have the default - * (current) ownership and permissions of the current process. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Virtual table for handling properties and method calls for a D-Bus + * interface. + * If you want to handle getting/setting D-Bus properties asynchronously, simply + * register an object with the <literal>org.freedesktop.DBus.Properties</literal> + * D-Bus interface using g_dbus_connection_register_object(). * - * Returns: %TRUE on successful creation, %FALSE otherwise. + * Since: 2.26 */ /** - * g_zlib_compressor_set_file_info: - * @compressor: a #GZlibCompressor - * @file_info: (allow-none): a #GFileInfo + * GDBusMessage: * - * Sets @file_info in @compressor. If non-%NULL, and @compressor's - * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, - * it will be used to set the file name and modification time in - * the GZIP header of the compressed data. - * progress; it may only be called immediately after creation of @compressor, - * or after resetting it with g_converter_reset(). + * The #GDBusMessage structure contains only private data and should + * only be accessed using the provided API. * - * Note: it is an error to call this function while a compression is in * Since: 2.26 */ /** - * g_cancellable_make_pollfd: - * @cancellable: a #GCancellable or %NULL - * @pollfd: a pointer to a #GPollFD + * GDBusMessageByteOrder: + * @G_DBUS_MESSAGE_BYTE_ORDER_BIG_ENDIAN: The byte order is big endian. + * @G_DBUS_MESSAGE_BYTE_ORDER_LITTLE_ENDIAN: The byte order is little endian. * - * Creates a #GPollFD corresponding to @cancellable; this can be passed - * to g_poll() and used to poll for cancellation. This is useful both - * for unix systems without a native poll and for portability to - * windows. - * When this function returns %TRUE, you should use - * g_cancellable_release_fd() to free up resources allocated for the - * If this function returns %FALSE, either no @cancellable was given or - * resource limits prevent this function from allocating the necessary - * structures for polling. (On Linux, you will likely have reached - * the maximum number of file descriptors.) The suggested way to handle - * these cases is to ignore the @cancellable. - * You are not supposed to read from the fd yourself, just check for - * readable status. Reading to unset the readable status is done - * with g_cancellable_reset(). - * failure to prepare the cancellable. + * Enumeration used to describe the byte order of a D-Bus message. * - * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on - * Since: 2.22 + * Since: 2.26 */ /** - * g_file_icon_get_file: - * @icon: a #GIcon. + * GDBusMessageClass: * - * Gets the #GFile associated with the given @icon. + * Class structure for #GDBusMessage. * - * Returns: (transfer none): a #GFile, or %NULL. + * Since: 2.26 */ /** - * GSocketService: + * GDBusMessageFilterFunction: + * @connection: (transfer none): A #GDBusConnection. + * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of. + * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is a message to be sent to the other peer. + * @user_data: User data passed when adding the filter. * - * A helper class for handling accepting incomming connections in the - * glib mainloop. + * Signature for function used in g_dbus_connection_add_filter(). + * A filter function is passed a #GDBusMessage and expected to return + * a #GDBusMessage too. Passive filter functions that don't modify the + * message can simply return the @message object: + * |[ + * static GDBusMessage * + * passive_filter (GDBusConnection *connection + * GDBusMessage *message, + * gboolean incoming, + * gpointer user_data) + * { + * /<!-- -->* inspect @message *<!-- -->/ + * return message; + * } + * ]| + * Filter functions that wants to drop a message can simply return %NULL: + * |[ + * static GDBusMessage * + * drop_filter (GDBusConnection *connection + * GDBusMessage *message, + * gboolean incoming, + * gpointer user_data) + * { + * if (should_drop_message) + * { + * g_object_unref (message); + * message = NULL; + * } + * return message; + * } + * ]| + * Finally, a filter function may modify a message by copying it: + * |[ + * static GDBusMessage * + * modifying_filter (GDBusConnection *connection + * GDBusMessage *message, + * gboolean incoming, + * gpointer user_data) + * { + * GDBusMessage *copy; + * GError *error; + * error = NULL; + * copy = g_dbus_message_copy (message, &error); + * /<!-- -->* handle @error being is set *<!-- -->/ + * g_object_unref (message); + * /<!-- -->* modify @copy *<!-- -->/ + * return copy; + * } + * ]| + * If the returned #GDBusMessage is different from @message and cannot + * be sent on @connection (it could use features, such as file + * descriptors, not compatible with @connection), then a warning is + * logged to <emphasis>standard error</emphasis>. Applications can + * check this ahead of time using g_dbus_message_to_blob() passing a + * #GDBusCapabilityFlags value obtained from @connection. + * g_object_unref() or %NULL to drop the message. Passive filter + * functions can simply return the passed @message object. * - * Since: 2.22 + * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME: + * GDBusMessageFlags: + * @G_DBUS_MESSAGE_FLAGS_NONE: No flags set. + * @G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED: A reply is not expected. + * @G_DBUS_MESSAGE_FLAGS_NO_AUTO_START: The bus must not launch an owner for the destination name in response to this message. * - * A key in the "access" namespace for checking renaming privileges. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - * This attribute will be %TRUE if the user is able to rename the file. + * Message flags used in #GDBusMessage. + * + * Since: 2.26 */ /** - * g_seekable_seek: - * @seekable: a #GSeekable. - * @offset: a #goffset. - * @type: a #GSeekType. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * GDBusMessageHeaderField: + * @G_DBUS_MESSAGE_HEADER_FIELD_INVALID: Not a valid header field. + * @G_DBUS_MESSAGE_HEADER_FIELD_PATH: The object path. + * @G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE: The interface name. + * @G_DBUS_MESSAGE_HEADER_FIELD_MEMBER: The method or signal name. + * @G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME: The name of the error that occurred. + * @G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL: The serial number the message is a reply to. + * @G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION: The name the message is intended for. + * @G_DBUS_MESSAGE_HEADER_FIELD_SENDER: Unique name of the sender of the message (filled in by the bus). + * @G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE: The signature of the message body. + * @G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS: The number of UNIX file descriptors that accompany the message. * - * Seeks in the stream by the given @offset, modified by @type. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * has occurred, this function will return %FALSE and set @error - * appropriately if present. + * Header fields used in #GDBusMessage. * - * Returns: %TRUE if successful. If an error + * Since: 2.26 */ /** - * G_TYPE_IS_INTERFACE: - * @type: A #GType value. + * GDBusMessageType: + * @G_DBUS_MESSAGE_TYPE_INVALID: Message is of invalid type. + * @G_DBUS_MESSAGE_TYPE_METHOD_CALL: Method call. + * @G_DBUS_MESSAGE_TYPE_METHOD_RETURN: Method reply. + * @G_DBUS_MESSAGE_TYPE_ERROR: Error reply. + * @G_DBUS_MESSAGE_TYPE_SIGNAL: Signal emission. * - * Checks if @type is an interface type. - * An interface type provides a pure API, the implementation - * of which is provided by another type (which is then said to conform - * to the interface). GLib interfaces are somewhat analogous to Java - * interfaces and C++ classes containing only pure virtual functions, - * with the difference that GType interfaces are not derivable (but see - * g_type_interface_add_prerequisite() for an alternative). + * Message types used in #GDBusMessage. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * GDBusSubtreeVTable: - * @enumerate: Function for enumerating child nodes. - * @introspect: Function for introspecting a child node. - * @dispatch: Function for dispatching a remote call on a child node. + * GDBusMethodInfo: + * @ref_count: The reference count or -1 if statically allocated. + * @name: The name of the D-Bus method, e.g. @RequestName. + * @in_args: A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments. + * @out_args: A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments. + * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. * - * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree(). + * Information about a method on an D-Bus interface. * * Since: 2.26 */ /** - * SECTION:gcontenttyp: - * @short_description: Platform-specific content typing - * @include: gio/gio.h + * GDBusMethodInvocation: * - * A content type is a platform specific string that defines the type - * of a file. On unix it is a mime type, on win32 it is an extension string - * like ".doc", ".txt" or a percieved string like "audio". Such strings - * can be looked up in the registry at HKEY_CLASSES_ROOT. + * The #GDBusMethodInvocation structure contains only private data and + * should only be accessed using the provided API. + * + * Since: 2.26 */ /** - * GDBusConnection:locked: + * GDBusMethodInvocationClass: * - * A boolean specifying whether the message is locked. + * Class structure for #GDBusMethodInvocation. * * Since: 2.26 */ /** - * g_dbus_proxy_call_finish: - * @proxy: A #GDBusProxy. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call(). - * @error: Return location for error or %NULL. + * GDBusNodeInfo: + * @ref_count: The reference count or -1 if statically allocated. + * @path: The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details. + * @interfaces: A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces. + * @nodes: A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes. + * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. * - * Finishes an operation started with g_dbus_proxy_call(). - * return values. Free with g_variant_unref(). + * Information about nodes in a remote object hierarchy. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with * Since: 2.26 */ /** - * g_socket_client_get_timeout: - * @client: a #GSocketClient + * GDBusPropertyInfo: + * @ref_count: The reference count or -1 if statically allocated. + * @name: The name of the D-Bus property, e.g. "SupportedFilesystems". + * @signature: The D-Bus signature of the property (a single complete type). + * @flags: Access control flags for the property. + * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. * - * Gets the I/O timeout time for sockets created by @client. - * See g_socket_client_set_timeout() for details. + * Information about a D-Bus property on a D-Bus interface. * - * Returns: the timeout in seconds * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT: + * GDBusPropertyInfoFlags: + * @G_DBUS_PROPERTY_INFO_FLAGS_NONE: No flags set. + * @G_DBUS_PROPERTY_INFO_FLAGS_READABLE: Property is readable. + * @G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE: Property is writable. * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * Flags describing the access control of a D-Bus property. + * + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT: + * GDBusProxy: * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * The #GDBusProxy structure contains only private data and + * should only be accessed using the provided API. + * + * Since: 2.26 */ /** - * g_socket_address_to_native: - * @address: a #GSocketAddress - * @dest: a pointer to a memory location that will contain the native <type>struct sockaddr</type>. - * @destlen: the size of @dest. Must be at least as large as g_socket_address_get_native_size(). - * @error: #GError for error reporting, or %NULL to ignore. + * GDBusProxy::g-properties-changed: + * @proxy: The #GDBusProxy emitting the signal. + * @changed_properties: A #GVariant containing the properties that changed + * @invalidated_properties: A %NULL terminated array of properties that was invalidated * - * Converts a #GSocketAddress to a native <type>struct - * sockaddr</type>, which can be passed to low-level functions like - * connect() or bind(). - * If not enough space is availible, a %G_IO_ERROR_NO_SPACE error is - * returned. If the address type is not known on the system - * then a %G_IO_ERROR_NOT_SUPPORTED error is returned. + * Emitted when one or more D-Bus properties on @proxy changes. The + * local cache has already been updated when this signal fires. Note + * that both @changed_properties and @invalidated_properties are + * guaranteed to never be %NULL (either may be empty though). + * This signal corresponds to the + * <literal>PropertiesChanged</literal> D-Bus signal on the + * <literal>org.freedesktop.DBus.Properties</literal> interface. * - * Returns: %TRUE if @dest was filled in, %FALSE on error - * Since: 2.22 + * Since: 2.26 */ /** - * g_bus_own_name_on_connection_with_closures: - * @connection: A #GDBusConnection. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. - * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. + * GDBusProxy::g-signal: + * @proxy: The #GDBusProxy emitting the signal. + * @sender_name: The sender of the signal or %NULL if the connection is not a bus connection. + * @signal_name: The name of the signal. + * @parameters: A #GVariant tuple with parameters for the signal. * - * Version of g_bus_own_name_on_connection() using closures instead of callbacks for - * easier binding in other languages. - * g_bus_unown_name() to stop owning the name. + * Emitted when a signal from the remote object and interface that @proxy is for, has been received. * - * Returns: An identifier (never 0) that an be used with - * Rename to: g_bus_own_name_on_connection * Since: 2.26 */ /** - * g_socket_client_connect: - * @client: a #GSocketClient. - * @connectable: a #GSocketConnectable specifying the remote address. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting, or %NULL to ignore. + * GDBusProxy:g-bus-type: * - * Tries to resolve the @connectable and make a network connection to it.. - * Upon a successful connection, a new #GSocketConnection is constructed - * and returned. The caller owns this new object and must drop their - * reference to it when finished with it. - * The type of the #GSocketConnection object returned depends on the type of - * the underlying socket that is used. For instance, for a TCP/IP connection - * it will be a #GTcpConnection. - * The socket created will be the same family as the the address that the - * or indirectly via g_socket_client_set_local_address(). The socket type - * defaults to %G_SOCKET_TYPE_STREAM but can be set with - * g_socket_client_set_socket_type(). - * If a local address is specified with g_socket_client_set_local_address() the - * socket will be bound to this address before connecting. + * If this property is not %G_BUS_TYPE_NONE, then + * #GDBusProxy:g-connection must be %NULL and will be set to the + * #GDBusConnection obtained by calling g_bus_get() with the value + * of this property. * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 + * Since: 2.26 */ /** - * g_settings_unbind: - * @object: the object - * @property: the property whose binding is removed + * GDBusProxy:g-connection: * - * Removes an existing binding for @property on @object. - * Note that bindings are automatically removed when the - * object is finalized, so it is rarely necessary to call this - * function. + * The #GDBusConnection the proxy is for. * * Since: 2.26 */ /** - * GSeekableIface: - * @g_iface: The parent interface. - * @tell: Tells the current location within a stream. - * @can_seek: Checks if seeking is supported by the stream. - * @seek: Seeks to a location within a stream. - * @can_truncate: Chekcs if truncation is suppored by the stream. - * @truncate_fn: Truncates a stream. + * GDBusProxy:g-default-timeout: * - * Provides an interface for implementing seekable functionality on I/O Streams. + * The timeout to use if -1 (specifying default timeout) is passed + * as @timeout_msec in the g_dbus_proxy_call() and + * g_dbus_proxy_call_sync() functions. + * This allows applications to set a proxy-wide timeout for all + * remote method invocations on the proxy. If this property is -1, + * the default timeout (typically 25 seconds) is used. If set to + * %G_MAXINT, then no timeout is used. + * + * Since: 2.26 */ /** - * G_TYPE_PARAM_FLAGS: + * GDBusProxy:g-flags: * - * The #GType of #GParamSpecFlags. + * Flags from the #GDBusProxyFlags enumeration. + * + * Since: 2.26 */ /** - * g_file_input_stream_query_info_finish: - * @stream: a #GFileInputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * GDBusProxy:g-interface-info: * - * Finishes an asynchronous info query operation. + * Ensure that interactions with this proxy conform to the given + * interface. For example, when completing a method call, if the + * type signature of the message isn't what's expected, the given + * #GError is set. Signals that have a type signature mismatch are + * simply dropped. * - * Returns: (transfer full): #GFileInfo. + * Since: 2.26 */ /** - * GInetAddress:is-mc-link-local: + * GDBusProxy:g-interface-name: * - * Whether this is a link-local multicast address. - * See g_inet_address_get_is_mc_link_local(). + * The D-Bus interface name the proxy is for. * - * Since: 2.22 + * Since: 2.26 */ /** - * GUnixCredentialsMessage:credentials: + * GDBusProxy:g-name: * - * The credentials stored in the message. + * The well-known or unique name that the proxy is for. * * Since: 2.26 */ /** - * g_mount_is_shadowed: - * @mount: A #GMount. + * GDBusProxy:g-name-owner: * - * Determines if @mount is shadowed. Applications or libraries should - * avoid displaying @mount in the user interface if it is shadowed. - * A mount is said to be shadowed if there exists one or more user - * visible objects (currently #GMount objects) with a root that is - * inside the root of @mount. - * One application of shadow mounts is when exposing a single file - * system that is used to address several logical volumes. In this - * situation, a #GVolumeMonitor implementation would create two - * #GVolume objects (for example, one for the camera functionality of - * the device and one for a SD card reader on the device) with - * activation URIs <literal>gphoto2://[usb:001,002]/store1/</literal> - * and <literal>gphoto2://[usb:001,002]/store2/</literal>. When the - * underlying mount (with root - * <literal>gphoto2://[usb:001,002]/</literal>) is mounted, said - * #GVolumeMonitor implementation would create two #GMount objects - * (each with their root matching the corresponding volume activation - * root) that would shadow the original mount. - * The proxy monitor in GVfs 2.26 and later, automatically creates and - * manage shadow mounts (and shadows the underlying mount) if the - * activation root on a #GVolume is set. + * The unique name that owns #GDBusProxy:name or %NULL if no-one + * currently owns that name. You may connect to #GObject::notify signal to + * track changes to this property. * - * Returns: %TRUE if @mount is shadowed. - * Since: 2.20 + * Since: 2.26 */ /** - * GDBusMethodInfo: - * @ref_count: The reference count or -1 if statically allocated. - * @name: The name of the D-Bus method, e.g. @RequestName. - * @in_args: A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments. - * @out_args: A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments. - * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. + * GDBusProxy:g-object-path: * - * Information about a method on an D-Bus interface. + * The object path the proxy is for. * * Since: 2.26 */ /** - * G_TYPE_INITIALLY_UNOWNED: + * GDBusProxyClass: + * @g_properties_changed: Signal class handler for the #GDBusProxy::g-properties-changed signal. + * @g_signal: Signal class handler for the #GDBusProxy::g-signal signal. * - * The type for #GInitiallyUnowned. + * Class structure for #GDBusProxy. + * + * Since: 2.26 */ /** - * g_io_scheduler_push_job: - * @job_func: a #GIOSchedulerJobFunc. - * @user_data: data to pass to @job_func - * @notify: a #GDestroyNotify for @user_data, or %NULL - * @io_priority: the <link linkend="gioscheduler">I/O priority</link> of the request. - * @cancellable: optional #GCancellable object, %NULL to ignore. + * GDBusProxyFlags: + * @G_DBUS_PROXY_FLAGS_NONE: No flags set. + * @G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES: Don't load properties. + * @G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS: Don't connect to signals on the remote object. + * @G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START: If not set and the proxy if for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in proxies for well-known names. * - * Schedules the I/O job to run. - * regardless whether the job was cancelled or has run to completion. - * If @cancellable is not %NULL, it can be used to cancel the I/O job - * by calling g_cancellable_cancel() or by calling - * g_io_scheduler_cancel_all_jobs(). + * Flags used when constructing an instance of a #GDBusProxy derived class. + * + * Since: 2.26 */ /** - * GIOSchedulerJobFunc: - * @job: a #GIOSchedulerJob. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @user_data: the data to pass to callback function + * GDBusSendMessageFlags: + * @G_DBUS_SEND_MESSAGE_FLAGS_NONE: No flags set. + * @G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL: Do not automatically assign a serial number from the #GDBusConnection object when sending a message. * - * I/O Job function. - * Note that depending on whether threads are available, the - * #GIOScheduler may run jobs in separate threads or in an idle - * in the mainloop. - * Long-running jobs should periodically check the @cancellable - * to see if they have been cancelled. - * complete the job, %FALSE if the job is complete (or cancelled) + * Flags used when sending #GDBusMessage<!-- -->s on a #GDBusConnection. * - * Returns: %TRUE if this function should be called again to + * Since: 2.26 */ /** - * g_dbus_message_set_serial: - * @message: A #GDBusMessage. - * @serial: A #guint32. + * GDBusServer: * - * Sets the serial for @message. + * The #GDBusServer structure contains only private data and + * should only be accessed using the provided API. * * Since: 2.26 */ /** - * g_dbus_auth_observer_authorize_authenticated_peer: - * @observer: A #GDBusAuthObserver. - * @stream: A #GIOStream for the #GDBusConnection. - * @credentials: Credentials received from the peer or %NULL. + * GDBusServer::new-connection: + * @server: The #GDBusServer emitting the signal. + * @connection: A #GDBusConnection for the new connection. * - * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. + * Emitted when a new authenticated connection has been made. Use + * g_dbus_connection_get_peer_credentials() to figure out what + * identity (if any), was authenticated. + * If you want to accept the connection, take a reference to the + * connection call g_dbus_connection_close() and give up your + * reference. Note that the other peer may disconnect at any time - + * a typical thing to do when accepting a connection is to listen to + * the #GDBusConnection::closed signal. + * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD + * then the signal is emitted in a new thread dedicated to the + * connection. Otherwise the signal is emitted in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread that @server was constructed in. + * You are guaranteed that signal handlers for this signal runs + * before incoming messages on @connection are processed. This means + * that it's suitable to call g_dbus_connection_register_object() or + * similar from the signal handler. + * run. * - * Returns: %TRUE if the peer is authorized, %FALSE if not. + * Returns: %TRUE to claim @connection, %FALSE to let other handlers * Since: 2.26 */ /** - * GInterfaceInfo: - * @interface_init: location of the interface initialization function - * @interface_finalize: location of the interface finalization function - * @interface_data: user-supplied data passed to the interface init/finalize functions + * GDBusServer:active: * - * A structure that provides information to the type system which is - * used specifically for managing interface types. + * Whether the server is currently active. + * + * Since: 2.26 */ /** - * g_io_stream_get_output_stream: - * @stream: a #GIOStream + * GDBusServer:address: * - * Gets the output stream for this object. This is used for - * writing. - * Do not free. + * The D-Bus address to listen on. * - * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. - * Since: 2.22 + * Since: 2.26 */ /** - * G_PARAM_READWRITE: + * GDBusServer:authentication-observer: * - * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. + * A #GDBusAuthObserver object to assist in the authentication process or %NULL. + * + * Since: 2.26 */ /** - * GVolume: + * GDBusServer:client-address: * - * Opaque mountable volume object. + * The D-Bus address that clients can use. + * + * Since: 2.26 */ /** - * g_file_query_settable_attributes: - * @file: input #GFile. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * GDBusServer:flags: * - * Obtain the list of settable attributes for the file. - * Returns the type and full attribute name of all the attributes - * that can be set on this file. This doesn't mean setting it will always - * succeed though, you might get an access failure, or some specific - * file may not support a specific attribute. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * When you are done with it, release it with g_file_attribute_info_list_unref() + * Flags from the #GDBusServerFlags enumeration. * - * Returns: a #GFileAttributeInfoList describing the settable attributes. + * Since: 2.26 */ /** - * G_VALUE_HOLDS_POINTER: - * @value: a valid #GValue structure + * GDBusServer:guid: * - * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. + * The guid of the server. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * GActionGroup::action-added: - * @action_group: the #GActionGroup that changed - * @action_name: the name of the action in @action_group + * GDBusServerClass: + * @new_connection: Signal class handler for the #GDBusServer::new-connection signal. * - * Signals that a new action was just added to the group. This signal - * is emitted after the action has been added and is now visible. + * Class structure for #GDBusServer. * - * Since: 2.28 + * Since: 2.26 */ /** - * GWin32InputStream:close-handle: + * GDBusServerFlags: + * @G_DBUS_SERVER_FLAGS_NONE: No flags set. + * @G_DBUS_SERVER_FLAGS_RUN_IN_THREAD: All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details). + * @G_DBUS_SERVER_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: Allow the anonymous authentication method. * - * Whether to close the file handle when the stream is closed. + * Flags used when creating a #GDBusServer. * * Since: 2.26 */ /** - * GMemVTable: - * @malloc: function to use for allocating memory. - * @realloc: function to use for reallocating memory. - * @free: function to use to free memory. - * @calloc: function to use for allocating zero-filled memory. - * @try_malloc: function to use for allocating memory without a default error handler. - * @try_realloc: function to use for reallocating memory without a default error handler. + * GDBusSignalCallback: + * @connection: A #GDBusConnection. + * @sender_name: The unique bus name of the sender of the signal. + * @object_path: The object path that the signal was emitted on. + * @interface_name: The name of the interface. + * @signal_name: The name of the signal. + * @parameters: A #GVariant tuple with parameters for the signal. + * @user_data: User data passed when subscribing to the signal. * - * A set of functions used to perform memory allocation. The same #GMemVTable must - * be used for all allocations in the same program; a call to g_mem_set_vtable(), - * if it exists, should be prior to any use of GLib. + * Signature for callback function used in g_dbus_connection_signal_subscribe(). + * + * Since: 2.26 */ /** - * g_socket_listener_set_backlog: - * @listener: a #GSocketListener - * @listen_backlog: an integer + * GDBusSignalFlags: + * @G_DBUS_SIGNAL_FLAGS_NONE: No flags set. + * @G_DBUS_SIGNAL_FLAGS_NO_MATCH_RULE: Don't actually send the AddMatch DBus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). * - * Sets the listen backlog on the sockets in the listener. - * See g_socket_set_listen_backlog() for details + * Flags used when subscribing to signals via g_dbus_connection_signal_subscribe(). * - * Since: 2.22 + * Since: 2.26 */ /** - * GFilenameCompleter::got-completion-data: + * GDBusSignalInfo: + * @ref_count: The reference count or -1 if statically allocated. + * @name: The name of the D-Bus signal, e.g. "NameOwnerChanged". + * @args: A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments. + * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. * - * Emitted when the file name completion information comes available. + * Information about a signal on a D-Bus interface. + * + * Since: 2.26 */ /** - * g_dbus_connection_flush_finish: + * GDBusSubtreeDispatchFunc: * @connection: A #GDBusConnection. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush(). - * @error: Return location for error or %NULL. + * @sender: The unique bus name of the remote caller. + * @object_path: The object path that was registered with g_dbus_connection_register_subtree(). + * @interface_name: The D-Bus interface name that the method call or property access is for. + * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. + * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL). + * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree(). * - * Finishes an operation started with g_dbus_connection_flush(). + * The type of the @dispatch function in #GDBusSubtreeVTable. + * Subtrees are flat. @node, if non-%NULL, is always exactly one * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Segment of the object path (ie: it never contains a slash). + * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods. * Since: 2.26 */ /** - * g_dbus_method_invocation_get_message: - * @invocation: A #GDBusMethodInvocation. + * GDBusSubtreeEnumerateFunc: + * @connection: A #GDBusConnection. + * @sender: The unique bus name of the remote caller. + * @object_path: The object path that was registered with g_dbus_connection_register_subtree(). + * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree(). * - * Gets the #GDBusMessage for the method invocation. This is useful if - * you need to use low-level protocol features, such as UNIX file - * descriptor passing, that cannot be properly expressed in the - * #GVariant API. - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * The type of the @enumerate function in #GDBusSubtreeVTable. + * This function is called when generating introspection data and also + * when preparing to dispatch incoming messages in the event that the + * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not + * Hierarchies are not supported; the items that you return should not + * contain the '/' character. + * The return value will be freed with g_strfreev(). * - * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation. + * Specified (ie: to verify that the object path is valid). + * Returns: A newly allocated array of strings for node names that are children of @object_path. * Since: 2.26 */ /** - * GParamSpecBoolean: - * @parent_instance: private #GParamSpec portion - * @default_value: default value for the property specified + * GDBusSubtreeFlags: + * @G_DBUS_SUBTREE_FLAGS_NONE: No flags set. + * @G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES: Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree. * - * A #GParamSpec derived structure that contains the meta data for boolean properties. + * Flags passed to g_dbus_connection_register_subtree(). + * + * Since: 2.26 */ /** - * g_socket_create_source: (skip) - * @socket: a #GSocket - * @condition: a #GIOCondition mask to monitor - * @cancellable: (allow-none): a %GCancellable or %NULL + * GDBusSubtreeIntrospectFunc: + * @connection: A #GDBusConnection. + * @sender: The unique bus name of the remote caller. + * @object_path: The object path that was registered with g_dbus_connection_register_subtree(). + * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. + * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree(). * - * Creates a %GSource that can be attached to a %GMainContext to monitor - * for the availibility of the specified @condition on the socket. - * The callback on the source is of the #GSocketSourceFunc type. - * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; - * these conditions will always be reported output if they are true. - * cause the source to trigger, reporting the current condition (which - * is likely 0 unless cancellation happened at the same time as a - * condition change). You can check for this in the callback using - * g_cancellable_is_cancelled(). - * If @socket has a timeout set, and it is reached before @condition - * occurs, the source will then trigger anyway, reporting %G_IO_IN or - * %G_IO_OUT depending on @condition. However, @socket will have been - * marked as having had a timeout, and so the next #GSocket I/O method - * you call will then fail with a %G_IO_ERROR_TIMED_OUT. + * The type of the @introspect function in #GDBusSubtreeVTable. + * Subtrees are flat. @node, if non-%NULL, is always exactly one + * This function should return %NULL to indicate that there is no object + * at this node. + * If this function returns non-%NULL, the return value is expected to + * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo + * structures describing the interfaces implemented by @node. This + * array will have g_dbus_interface_info_unref() called on each item + * before being freed with g_free(). + * The difference between returning %NULL and an array containing zero + * items is that the standard DBus interfaces will returned to the + * remote introspector in the empty array case, but not in the %NULL + * case. * - * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref(). - * Since: 2.22 + * Segment of the object path (ie: it never contains a slash). + * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL. + * Since: 2.26 */ /** - * GTlsCertificate:private-key-pem: + * GDBusSubtreeVTable: + * @enumerate: Function for enumerating child nodes. + * @introspect: Function for introspecting a child node. + * @dispatch: Function for dispatching a remote call on a child node. * - * The PEM (ASCII) encoded representation of the certificate's - * private key. This property (or the #GTlsCertificate:private-key - * property) can be set when constructing a key (eg, from a file), - * but cannot be read. + * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree(). * - * Since: 2.28 + * Since: 2.26 */ /** - * GInitableIface: - * @g_iface: The parent interface. - * @init: Initializes the object. + * GDataInputStream: * - * Provides an interface for initializing object such that initialization - * may fail. + * An implementation of #GBufferedInputStream that allows for high-level + * data manipulation of arbitrary data (including binary operations). + */ + + +/** + * GDataOutputStream: * - * Since: 2.22 + * An implementation of #GBufferedOutputStream that allows for high-level + * data manipulation of arbitrary data (including binary operations). */ /** - * GVfs: + * GDataOutputStream:byte-order: * - * Virtual File System object. + * Determines the byte ordering that is used when writing + * multi-byte entities (such as integers) to the stream. */ /** - * G_IS_PARAM_SPEC_INT: - * @pspec: a valid #GParamSpec instance + * GDataStream:byte-order: * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. + * The ::byte-order property determines the byte ordering that + * is used when reading multi-byte entities (such as integers) + * from the stream. + */ + + +/** + * GDataStream:newline-type: * - * Returns: %TRUE on success. + * The :newline-type property determines what is considered + * as a line ending when reading complete lines from the stream. */ /** - * GSignalEmissionHook: - * @ihint: Signal invocation hint, see #GSignalInvocationHint. - * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted. - * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission. - * @data: user data associated with the hook. + * GDataStreamByteOrder: + * @G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN: Selects Big Endian byte order. + * @G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN: Selects Little Endian byte order. + * @G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN: Selects endianness based on host machine's architecture. * - * A simple function pointer to get invoked when the signal is emitted. This - * allows you to tie a hook to the signal type, so that it will trap all - * emissions of that signal, from any object. - * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. - * hook is disconnected (and destroyed). + * #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources + * across various machine architectures. + */ + + +/** + * GDataStreamNewlineType: + * @G_DATA_STREAM_NEWLINE_TYPE_LF: Selects "LF" line endings, common on most modern UNIX platforms. + * @G_DATA_STREAM_NEWLINE_TYPE_CR: Selects "CR" line endings. + * @G_DATA_STREAM_NEWLINE_TYPE_CR_LF: Selects "CR, LF" line ending, common on Microsoft Windows. + * @G_DATA_STREAM_NEWLINE_TYPE_ANY: Automatically try to handle any line ending type. * - * Returns: whether it wants to stay connected. If it returns %FALSE, the signal + * #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. */ /** - * GBinding: + * GDateTime: * - * <structname>GBinding</structname> is an opaque structure whose members + * <structname>GDateTime</structname> is an opaque structure whose members * cannot be accessed directly. * * Since: 2.26 @@ -2048,570 +2130,674 @@ /** - * GSettingsBindSetMapping: - * @value: a #GValue containing the property value to map - * @expected_type: the #GVariantType to create - * @user_data: user data that was specified when the binding was created - * @returns: a new #GVariant holding the data from @value, or %NULL in case of an error + * GDesktopAppInfo: * - * The type for the function that is used to convert an object property - * value to a #GVariant for storing it in #GSettings. + * Information about an installed application from a desktop file. */ /** - * G_RESOLVER_ERROR: + * GDesktopAppInfoLookup: * - * Error domain for #GResolver. Errors in this domain will be from the - * #GResolverError enumeration. See #GError for more information on - * error domains. + * Interface that is used by backends to associate default + * handlers with URI schemes. */ /** - * g_file_attribute_matcher_enumerate_namespace: - * @matcher: a #GFileAttributeMatcher. - * @ns: a string containing a file attribute namespace. - * - * Checks if the matcher will match all of the keys in a given namespace. - * This will always return %TRUE if a wildcard character is in use (e.g. if - * matcher was created with "standard::*" and @ns is "standard", or if matcher was created - * using "*" and namespace is anything.) - * in the given @ns, %FALSE otherwise. + * GDesktopAppLaunchCallback: + * @appinfo: a #GDesktopAppInfo + * @pid: Process identifier + * @user_data: User data * - * Todo: this is awkwardly worded. - * Returns: %TRUE if the matcher matches all of the entries + * During invocation, g_desktop_app_info_launch_uris_as_manager() may + * create one or more child processes. This callback is invoked once + * for each, providing the process ID. */ /** - * g_simple_async_result_get_op_res_gboolean: - * @simple: a #GSimpleAsyncResult. - * - * Gets the operation result boolean from within the asynchronous result. - * if the operation's result was %FALSE. + * GDrive: * - * Returns: %TRUE if the operation's result was %TRUE, %FALSE + * Opaque drive object. */ /** - * GDBusServerFlags: - * @G_DBUS_SERVER_FLAGS_NONE: No flags set. - * @G_DBUS_SERVER_FLAGS_RUN_IN_THREAD: All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details). - * @G_DBUS_SERVER_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: Allow the anonymous authentication method. - * - * Flags used when creating a #GDBusServer. + * GDrive::changed: + * @drive: a #GDrive. * - * Since: 2.26 + * Emitted when the drive's state has changed. */ /** - * SECTION:gnetworkaddres: - * @short_description: A GSocketConnectable for resolving hostnames - * @include: gio/gio.h + * GDrive::disconnected: + * @drive: a #GDrive. * - * #GNetworkAddress provides an easy way to resolve a hostname and - * then attempt to connect to that host, handling the possibility of - * multiple IP addresses and multiple address families. - * See #GSocketConnectable for and example of using the connectable - * interface. + * This signal is emitted when the #GDrive have been + * disconnected. If the recipient is holding references to the + * object they should release them so the object can be + * finalized. */ /** - * g_application_get_is_remote: - * @application: a #GApplication - * @returns: %TRUE if @application is remote - * - * Checks if @application is remote. - * If @application is remote then it means that another instance of - * application already exists (the 'primary' instance). Calls to - * perform actions on @application will result in the actions being - * performed by the primary instance. - * The value of this property can not be accessed before - * g_application_register() has been called. See - * g_application_get_is_registered(). + * GDrive::eject-button: + * @drive: a #GDrive. * - * Since: 2.28 + * Emitted when the physical eject button (if any) of a drive has + * been pressed. */ /** - * g_tls_client_connection_set_server_identity: - * @conn: the #GTlsClientConnection - * @identity: a #GSocketConnectable describing the expected server identity + * GDrive::stop-button: + * @drive: a #GDrive. * - * Sets @conn's expected server identity, which is used both to tell - * servers on virtual hosts which certificate to present, and also - * to let @conn know what name to look for in the certificate when - * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. + * Emitted when the physical stop button (if any) of a drive has + * been pressed. * - * Since: 2.28 + * Since: 2.22 */ /** - * G_OPTION_ERROR: + * GDriveIface: + * @g_iface: The parent interface. + * @changed: Signal emitted when the drive is changed. + * @disconnected: The removed signal that is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. + * @eject_button: Signal emitted when the physical eject button (if any) of a drive have been pressed. + * @get_name: Returns the name for the given #GDrive. + * @get_icon: Returns a #GIcon for the given #GDrive. + * @has_volumes: Returns %TRUE if the #GDrive has mountable volumes. + * @get_volumes: Returns a list #GList of #GVolume for the #GDrive. + * @is_media_removable: Returns %TRUE if the #GDrive supports removal and insertion of media. + * @has_media: Returns %TRUE if the #GDrive has media inserted. + * @is_media_check_automatic: Returns %TRUE if the #GDrive is capabable of automatically detecting media changes. + * @can_poll_for_media: Returns %TRUE if the #GDrive is capable of manually polling for media change. + * @can_eject: Returns %TRUE if the #GDrive can eject media. + * @eject: Ejects a #GDrive. + * @eject_finish: Finishes an eject operation. + * @poll_for_media: Poll for media insertion/removal on a #GDrive. + * @poll_for_media_finish: Finishes a media poll operation. + * @get_identifier: Returns the identifier of the given kind, or %NULL if the #GDrive doesn't have one. + * @enumerate_identifiers: Returns an array strings listing the kinds of identifiers which the #GDrive has. + * @get_start_stop_type: Gets a #GDriveStartStopType with details about starting/stopping the drive. Since 2.22. + * @can_stop: Returns %TRUE if a #GDrive can be stopped. Since 2.22. + * @stop: Stops a #GDrive. Since 2.22. + * @stop_finish: Finishes a stop operation. Since 2.22. + * @can_start: Returns %TRUE if a #GDrive can be started. Since 2.22. + * @can_start_degraded: Returns %TRUE if a #GDrive can be started degraded. Since 2.22. + * @start: Starts a #GDrive. Since 2.22. + * @start_finish: Finishes a start operation. Since 2.22. + * @stop_button: Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22. + * @eject_with_operation: Starts ejecting a #GDrive using a #GMountOperation. Since 2.22. + * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22. * - * Error domain for option parsing. Errors in this domain will - * be from the #GOptionError enumeration. See #GError for information on - * error domains. + * Interface for creating #GDrive implementations. */ /** - * GVolumeMonitor::drive-changed: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: the drive that changed + * GDriveStartFlags: + * @G_DRIVE_START_NONE: No flags set. * - * Emitted when a drive changes. + * Flags used when starting a drive. + * + * Since: 2.22 */ /** - * G_VALUE_HOLDS_BOOLEAN: - * @value: a valid #GValue structure + * GDriveStartStopType: + * @G_DRIVE_START_STOP_TYPE_UNKNOWN: Unknown or drive doesn't support start/stop. + * @G_DRIVE_START_STOP_TYPE_SHUTDOWN: The stop method will physically shut down the drive and e.g. power down the port the drive is attached to. + * @G_DRIVE_START_STOP_TYPE_NETWORK: The start/stop methods are used for connecting/disconnect to the drive over the network. + * @G_DRIVE_START_STOP_TYPE_MULTIDISK: The start/stop methods will assemble/disassemble a virtual drive from several physical drives. + * @G_DRIVE_START_STOP_TYPE_PASSWORD: The start/stop methods will unlock/lock the disk (for example using the ATA <quote>SECURITY UNLOCK DEVICE</quote> command) * - * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. + * Enumeration describing how a drive can be started/stopped. * - * Returns: %TRUE on success. + * Since: 2.22 */ /** - * GMount: + * GEmblem: * - * A handle to an object implementing the #GMountIface interface. + * An object for Emblems */ /** - * GDBusCallFlags: - * @G_DBUS_CALL_FLAGS_NONE: No flags set. - * @G_DBUS_CALL_FLAGS_NO_AUTO_START: The bus must not launch an owner for the destination name in response to this method invocation. + * GEmblemOrigin: + * @G_EMBLEM_ORIGIN_UNKNOWN: Emblem of unknown origin + * @G_EMBLEM_ORIGIN_DEVICE: Emblem adds device-specific information + * @G_EMBLEM_ORIGIN_LIVEMETADATA: Emblem depicts live metadata, such as "readonly" + * @G_EMBLEM_ORIGIN_TAG: Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) * - * Flags used in g_dbus_connection_call() and similar APIs. + * GEmblemOrigin is used to add information about the origin of the emblem + * to #GEmblem. * - * Since: 2.26 + * Since: 2.18 */ /** - * G_VARIANT_TYPE_SIGNATURE: + * GEmblemedIcon: * - * The type of a DBus type signature. These are strings of a specific - * format used as type signatures for DBus methods and messages. - * If you are not interacting with DBus, then there is no reason to make - * use of this type. If you are, then the DBus specification contains a - * precise description of valid signature strings. + * An implementation of #GIcon for icons with emblems. */ /** - * g_credentials_get_unix_user: - * @credentials: A #GCredentials - * @error: Return location for error or %NULL. - * - * Tries to get the UNIX user identifier from @credentials. This - * method is only available on UNIX platforms. - * This operation can fail if #GCredentials is not supported on the - * OS or if the native credentials type does not contain information - * about the UNIX user. + * GEnumClass: + * @g_type_class: the parent class + * @minimum: the smallest possible value. + * @maximum: the largest possible value. + * @n_values: the number of possible values. + * @values: an array of #GEnumValue structs describing the individual values. * - * Returns: The UNIX user identifier or -1 if @error is set. - * Since: 2.26 + * The class of an enumeration type holds information about its + * possible values. */ /** - * SECTION:gemblemedico: - * @short_description: Icon with emblems - * @include: gio/gio.h - * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem + * GEnumValue: + * @value: the enum value + * @value_name: the name of the value + * @value_nick: the nickname of the value * - * #GEmblemedIcon is an implementation of #GIcon that supports - * adding an emblem to an icon. Adding multiple emblems to an - * icon is ensured via g_emblemed_icon_add_emblem(). - * Note that #GEmblemedIcon allows no control over the position - * of the emblems. See also #GEmblem for more information. + * A structure which contains a single enum value, its name, and its + * nickname. */ /** - * g_file_enumerator_set_pending: - * @enumerator: a #GFileEnumerator. - * @pending: a boolean value. + * GFile: * - * Sets the file enumerator as having pending operations. + * A handle to an object implementing the #GFileIface interface. + * Generally stores a location within the file system. Handles do not + * necessarily represent files or directories that currently exist. */ /** - * g_dbus_proxy_get_default_timeout: - * @proxy: A #GDBusProxy. - * - * Gets the timeout to use if -1 (specifying default timeout) is - * passed as @timeout_msec in the g_dbus_proxy_call() and - * g_dbus_proxy_call_sync() functions. - * See the #GDBusProxy:g-default-timeout property for more details. + * GFileAttributeInfo: + * @name: the name of the attribute. + * @type: the #GFileAttributeType type of the attribute. + * @flags: a set of #GFileAttributeInfoFlags. * - * Returns: Timeout to use for @proxy. - * Since: 2.26 + * Information about a specific attribute. */ /** - * g_application_release: - * @application: a #GApplication + * GFileAttributeInfoFlags: + * @G_FILE_ATTRIBUTE_INFO_NONE: no flags set. + * @G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE: copy the attribute values when the file is copied. + * @G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED: copy the attribute values when the file is moved. * - * Decrease the use count of @application. - * When the use count reaches zero, the application will stop running. - * Never call this function except to cancel the effect of a previous - * call to g_application_hold(). + * Flags specifying the behaviour of an attribute. */ /** - * GSocketService::incoming: - * @service: the #GSocketService. - * @connection: a new #GSocketConnection object. - * @source_object: the source_object passed to g_socket_listener_add_address(). - * - * The ::incoming signal is emitted when a new incoming connection - * to @service needs to be handled. The handler must initiate the - * handling of @connection, but may not block; in essence, - * asynchronous operations must be used. + * GFileAttributeInfoList: + * @infos: an array of #GFileAttributeInfo<!-- -->s. + * @n_infos: the number of values in the array. * - * Returns: %TRUE to stop other handlers from being called - * Since: 2.22 + * Acts as a lightweight registry for possible valid file attributes. + * The registry stores Key-Value pair formats as #GFileAttributeInfo<!-- -->s. */ /** - * g_io_error_from_errno: - * @err_no: Error number as defined in errno.h. - * - * Converts errno.h error codes into GIO error codes. + * GFileAttributeMatcher: * - * Returns: #GIOErrorEnum value for the given errno.h error number. + * Determines if a string matches a file attribute. */ /** - * g_file_enumerator_get_container: - * @enumerator: a #GFileEnumerator - * - * Get the #GFile container which is being enumerated. + * GFileAttributeStatus: + * @G_FILE_ATTRIBUTE_STATUS_UNSET: Attribute value is unset (empty). + * @G_FILE_ATTRIBUTE_STATUS_SET: Attribute value is set. + * @G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING: Indicates an error in setting the value. * - * Returns: (transfer full): the #GFile which is being enumerated. - * Since: 2.18 + * Used by g_file_set_attributes_from_info() when setting file attributes. */ /** - * g_volume_monitor_adopt_orphan_mount: - * @mount: a #GMount object to find a parent for + * GFileAttributeType: + * @G_FILE_ATTRIBUTE_TYPE_INVALID: indicates an invalid or uninitalized type. + * @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated UTF8 string. + * @G_FILE_ATTRIBUTE_TYPE_BYTE_STRING: a zero terminated string of non-zero bytes. + * @G_FILE_ATTRIBUTE_TYPE_BOOLEAN: a boolean value. + * @G_FILE_ATTRIBUTE_TYPE_UINT32: an unsigned 4-byte/32-bit integer. + * @G_FILE_ATTRIBUTE_TYPE_INT32: a signed 4-byte/32-bit integer. + * @G_FILE_ATTRIBUTE_TYPE_UINT64: an unsigned 8-byte/64-bit integer. + * @G_FILE_ATTRIBUTE_TYPE_INT64: a signed 8-byte/64-bit integer. + * @G_FILE_ATTRIBUTE_TYPE_OBJECT: a #GObject. + * @G_FILE_ATTRIBUTE_TYPE_STRINGV: a %NULL terminated char **. Since 2.22 * - * This function should be called by any #GVolumeMonitor - * implementation when a new #GMount object is created that is not - * associated with a #GVolume object. It must be called just before - * emitting the @mount_added signal. - * If the return value is not %NULL, the caller must associate the - * returned #GVolume object with the #GMount. This involves returning - * it in its g_mount_get_volume() implementation. The caller must - * also listen for the "removed" signal on the returned object - * and give up its reference when handling that signal - * Similary, if implementing g_volume_monitor_adopt_orphan_mount(), - * the implementor must take a reference to @mount and return it in - * its g_volume_get_mount() implemented. Also, the implementor must - * listen for the "unmounted" signal on @mount and give up its - * reference upon handling that signal. - * There are two main use cases for this function. - * One is when implementing a user space file system driver that reads - * blocks of a block device that is already represented by the native - * volume monitor (for example a CD Audio file system driver). Such - * a driver will generate its own #GMount object that needs to be - * assoicated with the #GVolume object that represents the volume. - * The other is for implementing a #GVolumeMonitor whose sole purpose - * is to return #GVolume objects representing entries in the users - * "favorite servers" list or similar. - * if no wants to adopt the #GMount. - * implementations should instead create shadow mounts with the URI of - * the mount they intend to adopt. See the proxy volume monitor in - * gvfs for an example of this. Also see g_mount_is_shadowed(), - * g_mount_shadow() and g_mount_unshadow() functions. + * The data types for file attributes. + */ + + +/** + * GFileCopyFlags: + * @G_FILE_COPY_NONE: No flags set. + * @G_FILE_COPY_OVERWRITE: Overwrite any existing files + * @G_FILE_COPY_BACKUP: Make a backup of any existing files. + * @G_FILE_COPY_NOFOLLOW_SYMLINKS: Don't follow symlinks. + * @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set used for copy (see #GFileInfo). + * @G_FILE_COPY_NO_FALLBACK_FOR_MOVE: Don't use copy and delete fallback if native move not supported. + * @G_FILE_COPY_TARGET_DEFAULT_PERMS: Leaves target file with default perms, instead of setting the source file perms. * - * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL - * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor + * Flags used when copying or moving files. */ /** - * g_action_get_state: - * @action: a #GAction + * GFileCreateFlags: + * @G_FILE_CREATE_NONE: No flags set. + * @G_FILE_CREATE_PRIVATE: Create a file that can only be accessed by the current user. + * @G_FILE_CREATE_REPLACE_DESTINATION: Replace the destination as if it didn't exist before. Don't try to keep any old permissions, replace instead of following links. This is generally useful if you're doing a "copy over" rather than a "save new version of" replace operation. You can think of it as "unlink destination" before writing to it, although the implementation may not be exactly like that. Since 2.20 * - * Queries the current state of @action. - * If the action is not stateful then %NULL will be returned. If the - * action is stateful then the type of the return value is the type - * given by g_action_get_state_type(). - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. + * Flags used when an operation may create a file. + */ + + +/** + * GFileDescriptorBased: * - * Returns: (transfer full): the current state of the action - * Since: 2.28 + * An interface for file descriptor based io objects. */ /** - * g_dbus_connection_emit_signal: - * @connection: A #GDBusConnection. - * @destination_bus_name: The unique bus name for the destination for the signal or %NULL to emit to all listeners. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to emit a signal on. - * @signal_name: The name of the signal to emit. - * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. - * @error: Return location for error or %NULL. + * GFileDescriptorBasedIface: + * @g_iface: The parent interface. * - * Emits a signal. - * If the parameters GVariant is floating, it is consumed. - * This can only fail if @parameters is not compatible with the D-Bus protocol. * - * Returns: %TRUE unless @error is set. - * Since: 2.26 */ /** - * G_PARAM_SPEC_BOOLEAN: - * @pspec: a valid #GParamSpec instance + * GFileEnumerator: * - * Cast a #GParamSpec instance into a #GParamSpecBoolean. + * A per matched file iterator. */ /** - * GParamSpecUnichar: - * @parent_instance: private #GParamSpec portion - * @default_value: default value for the property specified + * GFileIOStream: * - * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. + * A subclass of GIOStream for opened files. This adds + * a few file-specific operations and seeking and truncating. + * #GFileIOStream implements GSeekable. */ /** - * g_emblemed_icon_add_emblem: - * @emblemed: a #GEmblemedIcon - * @emblem: a #GEmblem - * - * Adds @emblem to the #GList of #GEmblem <!-- -->s. + * GFileIcon: * - * Since: 2.18 + * Gets an icon for a #GFile. Implements #GLoadableIcon. */ /** - * g_tls_client_connection_get_use_ssl3: - * @conn: the #GTlsClientConnection - * - * Gets whether @conn will use SSL 3.0 rather than the - * highest-supported version of TLS; see - * g_tls_client_connection_set_use_ssl3(). + * GFileIcon:file: * - * Returns: whether @conn will use SSL 3.0 - * Since: 2.28 + * The file containing the icon. */ /** - * g_emblem_get_icon: - * @emblem: a #GEmblem from which the icon should be extracted. - * - * Gives back the icon from @emblem. - * the emblem and should not be modified or freed. + * GFileIface: + * @g_iface: The parent interface. + * @dup: Duplicates a #GFile. + * @hash: Creates a hash of a #GFile. + * @equal: Checks equality of two given #GFile<!-- -->s. + * @is_native: Checks to see if a file is native to the system. + * @has_uri_scheme: Checks to see if a #GFile has a given URI scheme. + * @get_uri_scheme: Gets the URI scheme for a #GFile. + * @get_basename: Gets the basename for a given #GFile. + * @get_path: Gets the current path within a #GFile. + * @get_uri: Gets a URI for the path within a #GFile. + * @get_parse_name: Gets the parsed name for the #GFile. + * @get_parent: Gets the parent directory for the #GFile. + * @prefix_matches: Checks whether a #GFile contains a specified file. + * @get_relative_path: Gets the path for a #GFile relative to a given path. + * @resolve_relative_path: Resolves a relative path for a #GFile to an absolute path. + * @get_child_for_display_name: Gets the child #GFile for a given display name. + * @enumerate_children: Gets a #GFileEnumerator with the children of a #GFile. + * @enumerate_children_async: Asynchronously gets a #GFileEnumerator with the children of a #GFile. + * @enumerate_children_finish: Finishes asynchronously enumerating the children. + * @query_info: Gets the #GFileInfo for a #GFile. + * @query_info_async: Asynchronously gets the #GFileInfo for a #GFile. + * @query_info_finish: Finishes an asynchronous query info operation. + * @query_filesystem_info: Gets a #GFileInfo for the file system #GFile is on. + * @query_filesystem_info_async: Asynchronously gets a #GFileInfo for the file system #GFile is on. + * @query_filesystem_info_finish: Finishes asynchronously getting the file system info. + * @find_enclosing_mount: Gets a #GMount for the #GFile. + * @find_enclosing_mount_async: Asynchronously gets the #GMount for a #GFile. + * @find_enclosing_mount_finish: Finishes asynchronously getting the volume. + * @set_display_name: Sets the display name for a #GFile. + * @set_display_name_async: Asynchronously sets a #GFile's display name. + * @set_display_name_finish: Finishes asynchronously setting a #GFile's display name. + * @query_settable_attributes: Returns a list of #GFileAttribute<!-- -->s that can be set. + * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttribute<!-- -->s that can be set. + * @_query_settable_attributes_finish: Finishes asynchronously querying settable attributes. + * @query_writable_namespaces: Returns a list of #GFileAttribute namespaces that are writable. + * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttribute namespaces that are writable. + * @_query_writable_namespaces_finish: Finishes asynchronously querying the writable namespaces. + * @set_attribute: Sets a #GFileAttribute. + * @set_attributes_from_info: Sets a #GFileAttribute with information from a #GFileInfo. + * @set_attributes_async: Asynchronously sets a file's attributes. + * @set_attributes_finish: Finishes setting a file's attributes asynchronously. + * @read_fn: Reads a file asynchronously. + * @read_async: Asynchronously reads a file. + * @read_finish: Finishes asynchronously reading a file. + * @append_to: Writes to the end of a file. + * @append_to_async: Asynchronously writes to the end of a file. + * @append_to_finish: Finishes an asynchronous file append operation. + * @create: Creates a new file. + * @create_async: Asynchronously creates a file. + * @create_finish: Finishes asynchronously creating a file. + * @replace: Replaces the contents of a file. + * @replace_async: Asynchronously replaces the contents of a file. + * @replace_finish: Finishes asynchronously replacing a file. + * @delete_file: Deletes a file. + * @_delete_file_async: Asynchronously deletes a file. + * @_delete_file_finish: Finishes an asynchronous delete. + * @trash: Sends a #GFile to the Trash location. + * @_trash_async: Asynchronously sends a #GFile to the Trash location. + * @_trash_finish: Finishes an asynchronous file trashing operation. + * @make_directory: Makes a directory. + * @_make_directory_async: Asynchronously makes a directory. + * @_make_directory_finish: Finishes making a directory asynchronously. + * @make_symbolic_link: Makes a symbolic link. + * @_make_symbolic_link_async: Asynchronously makes a symbolic link + * @_make_symbolic_link_finish: Finishes making a symbolic link asynchronously. + * @copy: Copies a file. + * @copy_async: Asynchronously copies a file. + * @copy_finish: Finishes an asynchronous copy operation. + * @move: Moves a file. + * @_move_async: Asynchronously moves a file. + * @_move_finish: Finishes an asynchronous move operation. + * @mount_mountable: Mounts a mountable object. + * @mount_mountable_finish: Finishes a mounting operation. + * @unmount_mountable: Unmounts a mountable object. + * @unmount_mountable_finish: Finishes an unmount operation. + * @eject_mountable: Ejects a mountable. + * @eject_mountable_finish: Finishes an eject operation. + * @mount_enclosing_volume: Mounts a specified location. + * @mount_enclosing_volume_finish: Finishes mounting a specified location. + * @monitor_dir: Creates a #GFileMonitor for the location. + * @monitor_file: Creates a #GFileMonitor for the location. + * @open_readwrite: Open file read/write. Since 2.22. + * @open_readwrite_async: Asynchronously opens file read/write. Since 2.22. + * @open_readwrite_finish: Finishes an asynchronous open read/write. Since 2.22. + * @create_readwrite: Creates file read/write. Since 2.22. + * @create_readwrite_async: Asynchronously creates file read/write. Since 2.22. + * @create_readwrite_finish: Finishes an asynchronous creates read/write. Since 2.22. + * @replace_readwrite: Replaces file read/write. Since 2.22. + * @replace_readwrite_async: Asynchronously replaces file read/write. Since 2.22. + * @replace_readwrite_finish: Finishes an asynchronous replace read/write. Since 2.22. + * @start_mountable: Starts a mountable object. Since 2.22. + * @start_mountable_finish: Finishes an start operation. Since 2.22. + * @stop_mountable: Stops a mountable. Since 2.22. + * @stop_mountable_finish: Finishes an stop operation. Since 2.22. + * @supports_thread_contexts: a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22. + * @unmount_mountable_with_operation: Unmounts a mountable object using a #GMountOperation. Since 2.22. + * @unmount_mountable_with_operation_finish: Finishes an unmount operation using a #GMountOperation. Since 2.22. + * @eject_mountable_with_operation: Ejects a mountable object using a #GMountOperation. Since 2.22. + * @eject_mountable_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22. + * @poll_mountable: Polls a mountable object for media changes. Since 2.22. + * @poll_mountable_finish: Finishes an poll operation for media changes. Since 2.22. * - * Returns: (transfer none): a #GIcon. The returned object belongs to - * Since: 2.18 + * An interface for writing VFS file handles. */ /** - * SECTION:gfilemonito: - * @short_description: File Monitor - * @include: gio/gio.h + * GFileInfo: * - * Monitors a file or directory for changes. - * To obtain a #GFileMonitor for a file or directory, use - * g_file_monitor(), g_file_monitor_file(), or - * g_file_monitor_directory(). - * To get informed about changes to the file or directory you are - * monitoring, connect to the #GFileMonitor::changed signal. The - * signal will be emitted in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * context</link> of the thread that the monitor was created in - * (though if the global default main context is blocked, this may - * cause notifications to be blocked even if the thread-default - * context is still running). + * Stores information about a file system object referenced by a #GFile. */ /** - * GParamSpecPointer: - * @parent_instance: private #GParamSpec portion + * GFileInputStream: * - * A #GParamSpec derived structure that contains the meta data for pointer properties. + * A subclass of GInputStream for opened files. This adds + * a few file-specific operations and seeking. + * #GFileInputStream implements #GSeekable. */ /** - * g_dbus_node_info_ref: - * @info: A #GDBusNodeInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * GFileMonitor: * - * Returns: The same @info. - * Since: 2.26 + * Watches for changes to a file. */ /** - * g_action_get_enabled: - * @action: a #GAction + * GFileMonitor::changed: + * @monitor: a #GFileMonitor. + * @file: a #GFile. + * @other_file: a #GFile or #NULL. + * @event_type: a #GFileMonitorEvent. * - * Checks if @action is currently enabled. - * An action must be enabled in order to be activated or in order to - * have its state changed from outside callers. + * Emitted when @file has been changed. + * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is + * #G_FILE_MONITOR_SEND_MOVED, @file will be set to a #GFile containing the + * old path, and @other_file will be set to a #GFile containing the new path. + * In all the other cases, @other_file will be set to #NULL. + */ + + +/** + * GFileMonitorEvent: + * @G_FILE_MONITOR_EVENT_CHANGED: a file changed. + * @G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT: a hint that this was probably the last change in a set of changes. + * @G_FILE_MONITOR_EVENT_DELETED: a file was deleted. + * @G_FILE_MONITOR_EVENT_CREATED: a file was created. + * @G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED: a file attribute was changed. + * @G_FILE_MONITOR_EVENT_PRE_UNMOUNT: the file location will soon be unmounted. + * @G_FILE_MONITOR_EVENT_UNMOUNTED: the file location was unmounted. + * @G_FILE_MONITOR_EVENT_MOVED: the file was moved. * - * Returns: whether the action is enabled - * Since: 2.28 + * Specifies what type of event a monitor event is. */ /** - * g_dbus_connection_new_for_address: - * @address: A D-Bus address. - * @flags: Flags describing how to make the connection. - * @observer: A #GDBusAuthObserver or %NULL. - * @cancellable: A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * GFileMonitorFlags: + * @G_FILE_MONITOR_NONE: No flags set. + * @G_FILE_MONITOR_WATCH_MOUNTS: Watch for mount events. + * @G_FILE_MONITOR_SEND_MOVED: Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead (NB: not supported on all backends; the default behaviour -without specifying this flag- is to send single DELETED and CREATED events). * - * Asynchronously connects and sets up a D-Bus client connection for - * exchanging D-Bus messages with an endpoint specified by @address - * which must be in the D-Bus address format. - * This constructor can only be used to initiate client-side - * connections - use g_dbus_connection_new() if you need to act as the - * server. In particular, @flags cannot contain the - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags. - * When the operation is finished, @callback will be invoked. You can - * then call g_dbus_connection_new_finish() to get the result of the - * operation. - * If @observer is not %NULL it may be used to control the - * authentication process. - * This is a asynchronous failable constructor. See - * g_dbus_connection_new_for_address_sync() for the synchronous - * version. + * Flags used to set what a #GFileMonitor will watch for. + */ + + +/** + * GFileOutputStream: * - * Since: 2.26 + * A subclass of GOutputStream for opened files. This adds + * a few file-specific operations and seeking and truncating. + * #GFileOutputStream implements GSeekable. */ /** - * g_drive_get_identifier: - * @drive: a #GDrive - * @kind: the kind of identifier to return + * GFileProgressCallback: + * @current_num_bytes: the current number of bytes in the operation. + * @total_num_bytes: the total number of bytes in the operation. + * @user_data: user data passed to the callback. * - * Gets the identifier of the given kind for @drive. - * requested identfier, or %NULL if the #GDrive - * doesn't have this kind of identifier. + * When doing file operations that may take a while, such as moving + * a file or copying a file, a progress callback is used to pass how + * far along that operation is to the application. + */ + + +/** + * GFileQueryInfoFlags: + * @G_FILE_QUERY_INFO_NONE: No flags set. + * @G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS: Don't follow symlinks. * - * Returns: a newly allocated string containing the + * Flags used when querying a #GFileInfo. */ /** - * GThreadedSocketService: + * GFileReadMoreCallback: + * @file_contents: the data as currently read. + * @file_size: the size of the data currently read. + * @callback_data: data passed to the callback. * - * A helper class for handling accepting incomming connections in the - * glib mainloop and handling them in a thread. + * When loading the partial contents of a file with g_file_load_partial_contents_async(), + * it may become necessary to determine if any more data from the file should be loaded. + * A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data + * should be read, or %FALSE otherwise. * - * Since: 2.22 + * Returns: %TRUE if more data should be read back. %FALSE otherwise. */ /** - * GMountOperation:password: + * GFileType: + * @G_FILE_TYPE_UNKNOWN: File's type is unknown. + * @G_FILE_TYPE_REGULAR: File handle represents a regular file. + * @G_FILE_TYPE_DIRECTORY: File handle represents a directory. + * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link (Unix systems). + * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, block device, or character device. + * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems). + * @G_FILE_TYPE_MOUNTABLE: File is a mountable location. * - * The password that is used for authentication when carrying out - * the mount operation. + * Indicates the file's on-disk type. */ /** - * g_network_service_set_scheme: - * @srv: a #GNetworkService - * @scheme: a URI scheme + * GFilenameCompleter: * - * Set's the URI scheme used to resolve proxies. By default, the service name - * is used as scheme. + * Completes filenames based on files that exist within the file system. + */ + + +/** + * GFilenameCompleter::got-completion-data: * - * Since: 2.26 + * Emitted when the file name completion information comes available. */ /** - * g_win32_output_stream_new: - * @handle: a Win32 file handle - * @close_handle: %TRUE to close the handle when done + * GFilesystemPreviewType: + * @G_FILESYSTEM_PREVIEW_TYPE_IF_ALWAYS: Only preview files if user has explicitly requested it. + * @G_FILESYSTEM_PREVIEW_TYPE_IF_LOCAL: Preview files if user has requested preview of "local" files. + * @G_FILESYSTEM_PREVIEW_TYPE_NEVER: Never preview files. * - * Creates a new #GWin32OutputStream for the given @handle. - * If @close_handle, is %TRUE, the handle will be closed when the - * output stream is destroyed. + * Indicates a hint from the file system whether files should be + * previewed in a file manager. Returned as the value of the key + * #G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW. + */ + + +/** + * GFilterInputStream: * - * Returns: a new #GOutputStream - * Since: 2.26 + * A base class for all input streams that work on an underlying stream. */ /** - * GSignalMatchType: - * @G_SIGNAL_MATCH_ID: The signal id must be equal. - * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal. - * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same. - * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same. - * @G_SIGNAL_MATCH_DATA: The closure data must be the same. - * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched. + * GFilterOutputStream: * - * The match types specify what g_signal_handlers_block_matched(), - * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() - * match signals by. + * A base class for all output streams that work on an underlying stream. */ /** - * GTypeFundamentalFlags: - * @G_TYPE_FLAG_CLASSED: Indicates a classed type. - * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed). - * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type. - * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable). + * GFlagsClass: + * @g_type_class: the parent class + * @mask: a mask covering all possible values. + * @n_values: the number of possible values. + * @values: an array of #GFlagsValue structs describing the individual values. * - * Bit masks used to check or determine specific characteristics of a - * fundamental type. + * The class of a flags type holds information about its + * possible values. */ /** - * g_volume_get_mount: - * @volume: a #GVolume. + * GFlagsValue: + * @value: the flags value + * @value_name: the name of the value + * @value_nick: the nickname of the value * - * Gets the mount for the @volume. - * The returned object should be unreffed with g_object_unref() - * when no longer needed. + * A structure which contains a single flags value, its name, and its + * nickname. + */ + + +/** + * GIOErrorEnum: + * @G_IO_ERROR_FAILED: Generic error condition for when any operation fails. + * @G_IO_ERROR_NOT_FOUND: File not found error. + * @G_IO_ERROR_EXISTS: File already exists error. + * @G_IO_ERROR_IS_DIRECTORY: File is a directory error. + * @G_IO_ERROR_NOT_DIRECTORY: File is not a directory. + * @G_IO_ERROR_NOT_EMPTY: File is a directory that isn't empty. + * @G_IO_ERROR_NOT_REGULAR_FILE: File is not a regular file. + * @G_IO_ERROR_NOT_SYMBOLIC_LINK: File is not a symbolic link. + * @G_IO_ERROR_NOT_MOUNTABLE_FILE: File cannot be mounted. + * @G_IO_ERROR_FILENAME_TOO_LONG: Filename is too many characters. + * @G_IO_ERROR_INVALID_FILENAME: Filename is invalid or contains invalid characters. + * @G_IO_ERROR_TOO_MANY_LINKS: File contains too many symbolic links. + * @G_IO_ERROR_NO_SPACE: No space left on drive. + * @G_IO_ERROR_INVALID_ARGUMENT: Invalid argument. + * @G_IO_ERROR_PERMISSION_DENIED: Permission denied. + * @G_IO_ERROR_NOT_SUPPORTED: Operation not supported for the current backend. + * @G_IO_ERROR_NOT_MOUNTED: File isn't mounted. + * @G_IO_ERROR_ALREADY_MOUNTED: File is already mounted. + * @G_IO_ERROR_CLOSED: File was closed. + * @G_IO_ERROR_CANCELLED: Operation was cancelled. See #GCancellable. + * @G_IO_ERROR_PENDING: Operations are still pending. + * @G_IO_ERROR_READ_ONLY: File is read only. + * @G_IO_ERROR_CANT_CREATE_BACKUP: Backup couldn't be created. + * @G_IO_ERROR_WRONG_ETAG: File's Entity Tag was incorrect. + * @G_IO_ERROR_TIMED_OUT: Operation timed out. + * @G_IO_ERROR_WOULD_RECURSE: Operation would be recursive. + * @G_IO_ERROR_BUSY: File is busy. + * @G_IO_ERROR_WOULD_BLOCK: Operation would block. + * @G_IO_ERROR_HOST_NOT_FOUND: Host couldn't be found (remote operations). + * @G_IO_ERROR_WOULD_MERGE: Operation would merge files. + * @G_IO_ERROR_FAILED_HANDLED: Operation failed and a helper program has already interacted with the user. Do not display any error dialog. + * @G_IO_ERROR_TOO_MANY_OPEN_FILES: The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20 + * @G_IO_ERROR_NOT_INITIALIZED: The object has not been initialized. Since 2.22 + * @G_IO_ERROR_ADDRESS_IN_USE: The requested address is already in use. Since 2.22 + * @G_IO_ERROR_PARTIAL_INPUT: Need more input to finish operation. Since 2.24 + * @G_IO_ERROR_INVALID_DATA: There input data was invalid. Since 2.24 + * @G_IO_ERROR_DBUS_ERROR: A remote object generated an error that doesn't correspond to a locally registered #GError error domain. Use g_dbus_error_get_remote_error() to extract the D-Bus error name and g_dbus_error_strip_remote_error() to fix up the message so it matches what was received on the wire. Since 2.26. + * @G_IO_ERROR_HOST_UNREACHABLE: Host unreachable. Since 2.26 + * @G_IO_ERROR_NETWORK_UNREACHABLE: Network unreachable. Since 2.26 + * @G_IO_ERROR_CONNECTION_REFUSED: Connection refused. Since 2.26 + * @G_IO_ERROR_PROXY_FAILED: Connection to proxy server failed. Since 2.26 + * @G_IO_ERROR_PROXY_AUTH_FAILED: Proxy authentication failed. Since 2.26 + * @G_IO_ERROR_PROXY_NEED_AUTH: Proxy server needs authentication. Since 2.26 + * @G_IO_ERROR_PROXY_NOT_ALLOWED: Proxy connection is not allowed by ruleset. Since 2.26 * - * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted. + * Error codes returned by GIO functions. */ @@ -2623,3492 +2809,2908 @@ /** - * g_unix_socket_address_new: - * @path: the socket path + * GIOSchedulerJob: * - * Creates a new #GUnixSocketAddress for @path. - * To create abstract socket addresses, on systems that support that, - * use g_unix_socket_address_new_abstract(). + * Opaque class for definining and scheduling IO jobs. + */ + + +/** + * GIOSchedulerJobFunc: + * @job: a #GIOSchedulerJob. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @user_data: the data to pass to callback function * - * Returns: a new #GUnixSocketAddress - * Since: 2.22 + * I/O Job function. + * Note that depending on whether threads are available, the + * #GIOScheduler may run jobs in separate threads or in an idle + * in the mainloop. + * Long-running jobs should periodically check the @cancellable + * to see if they have been cancelled. + * complete the job, %FALSE if the job is complete (or cancelled) + * + * Returns: %TRUE if this function should be called again to */ /** - * GMountOperation:password-save: + * GIOStream: * - * Determines if and how the password information should be saved. + * Base class for read-write streams. */ /** - * g_pollable_output_stream_can_poll: - * @stream: a #GPollableOutputStream. + * GIOStreamSpliceFlags: + * @G_IO_STREAM_SPLICE_NONE: Do not close either stream. + * @G_IO_STREAM_SPLICE_CLOSE_STREAM1: Close the first stream after the splice. + * @G_IO_STREAM_SPLICE_CLOSE_STREAM2: Close the second stream after the splice. + * @G_IO_STREAM_SPLICE_WAIT_FOR_BOTH: Wait for both splice operations to finish before calling the callback. * - * Checks if @stream is actually pollable. Some classes may implement - * #GPollableOutputStream but have only certain instances of that - * class be pollable. If this method returns %FALSE, then the behavior - * of other #GPollableOutputStream methods is undefined. - * For any given stream, the value returned by this method is constant; - * a stream cannot switch from pollable to non-pollable or vice versa. + * GIOStreamSpliceFlags determine how streams should be spliced. * - * Returns: %TRUE if @stream is pollable, %FALSE if not. * Since: 2.28 */ /** - * g_inet_address_get_is_mc_global: - * @address: a #GInetAddress - * - * Tests whether @address is a global multicast address. + * GIcon: * - * Returns: %TRUE if @address is a global multicast address. - * Since: 2.22 + * An abstract type that specifies an icon. */ /** - * GPermission:can-acquire: + * GIconIface: + * @g_iface: The parent interface. + * @hash: A hash for a given #GIcon. + * @equal: Checks if two #GIcon<!-- -->s are equal. + * @to_tokens: Serializes a #GIcon into tokens. The tokens must not contain any whitespace. Don't implement if the #GIcon can't be serialized (Since 2.20). + * @from_tokens: Constructs a #GIcon from tokens. Set the #GError if the tokens are malformed. Don't implement if the #GIcon can't be serialized (Since 2.20). * - * %TRUE if it is generally possible to acquire the permission by calling - * g_permission_acquire(). + * GIconIface is used to implement GIcon types for various + * different systems. See #GThemedIcon and #GLoadableIcon for + * examples of how to implement this interface. */ /** - * GMemoryOutputStream:realloc-function: (skip) - * - * Function with realloc semantics called to enlarge the buffer. + * GIconv: * - * Since: 2.24 + * The <structname>GIConv</structname> struct wraps an + * iconv() conversion descriptor. It contains private data + * and should only be accessed using the following functions. */ /** - * g_unix_input_stream_get_close_fd: - * @stream: a #GUnixInputStream - * - * Returns whether the file descriptor of @stream will be - * closed when the stream is closed. + * GInetAddress: * - * Returns: %TRUE if the file descriptor is closed when done - * Since: 2.20 + * An IPv4 or IPv6 internet address. */ /** - * g_dbus_proxy_new_sync: - * @connection: A #GDBusConnection. - * @flags: Flags used when constructing the proxy. - * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. - * @object_path: An object path. - * @interface_name: A D-Bus interface name. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: (allow-none): Return location for error or %NULL. + * GInetAddress:is-any: * - * Creates a proxy for accessing @interface_name on the remote object - * at @object_path owned by @name at @connection and synchronously - * loads D-Bus properties unless the - * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. - * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up - * match rules for signals. Connect to the #GDBusProxy::g-signal signal - * to handle signals from the remote object. - * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name - * owner currently exists, the message bus will be requested to launch - * a name owner for the name. - * This is a synchronous failable constructor. See g_dbus_proxy_new() - * and g_dbus_proxy_new_finish() for the asynchronous version. - * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. + * Whether this is the "any" address for its family. + * See g_inet_address_get_is_any(). * - * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). - * Since: 2.26 + * Since: 2.22 */ /** - * g_try_new0: - * @struct_type: the type of the elements to allocate - * @n_structs: the number of elements to allocate + * GInetAddress:is-link-local: * - * Attempts to allocate @n_structs elements of type @struct_type, initialized - * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts - * the program on failure. - * The returned pointer is cast to a pointer to the given type. - * The function returns %NULL when @n_structs is 0 of if an overflow occurs. + * Whether this is a link-local address. + * See g_inet_address_get_is_link_local(). * - * Since: 2.8 - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type + * Since: 2.22 */ /** - * SECTION:gdbusconnectio: - * @short_description: D-Bus Connections - * @include: gio/gio.h + * GInetAddress:is-loopback: * - * The #GDBusConnection type is used for D-Bus connections to remote - * peers such as a message buses. It is a low-level API that offers a - * lot of flexibility. For instance, it lets you establish a connection - * over any transport that can by represented as an #GIOStream. - * This class is rarely used directly in D-Bus clients. If you are writing - * an D-Bus client, it is often easier to use the g_bus_own_name(), - * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. - * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> - * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> - * <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> - * <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * Whether this is the loopback address for its family. + * See g_inet_address_get_is_loopback(). + * + * Since: 2.22 */ /** - * SECTION:gfileinputstrea: - * @short_description: File input streaming operations - * @include: gio/gio.h - * @see_also: #GInputStream, #GDataInputStream, #GSeekable + * GInetAddress:is-mc-global: * - * GFileInputStream provides input streams that take their - * content from a file. - * GFileInputStream implements #GSeekable, which allows the input - * stream to jump to arbitrary positions in the file, provided the - * filesystem of the file allows it. To find the position of a file - * input stream, use g_seekable_tell(). To find out if a file input - * stream supports seeking, use g_seekable_stream_can_seek(). - * To position a file input stream, use g_seekable_seek(). + * Whether this is a global multicast address. + * See g_inet_address_get_is_mc_global(). + * + * Since: 2.22 */ /** - * g_socket_client_new: + * GInetAddress:is-mc-link-local: * - * Creates a new #GSocketClient with the default options. - * Free the returned object with g_object_unref(). + * Whether this is a link-local multicast address. + * See g_inet_address_get_is_mc_link_local(). * - * Returns: a #GSocketClient. * Since: 2.22 */ /** - * GDBusProxy:g-connection: + * GInetAddress:is-mc-node-local: * - * The #GDBusConnection the proxy is for. + * Whether this is a node-local multicast address. + * See g_inet_address_get_is_mc_node_local(). * - * Since: 2.26 + * Since: 2.22 */ /** - * g_file_enumerator_has_pending: - * @enumerator: a #GFileEnumerator. + * GInetAddress:is-mc-org-local: * - * Checks if the file enumerator has pending operations. + * Whether this is an organization-local multicast address. + * See g_inet_address_get_is_mc_org_local(). * - * Returns: %TRUE if the @enumerator has pending operations. + * Since: 2.22 */ /** - * g_socket_send_to: - * @socket: a #GSocket - * @address: a #GSocketAddress, or %NULL - * @buffer: (array length=size): the buffer containing the data to send. - * @size: the number of bytes to send - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * GInetAddress:is-mc-site-local: * - * Tries to send @size bytes from @buffer to @address. If @address is - * %NULL then the message is sent to the default receiver (set by - * g_socket_connect()). - * See g_socket_send() for additional information. - * on error + * Whether this is a site-local multicast address. + * See g_inet_address_get_is_mc_site_local(). * - * Returns: Number of bytes written (which may be less than @size), or -1 * Since: 2.22 */ /** - * g_file_new_for_uri: - * @uri: a UTF8 string containing a URI. + * GInetAddress:is-multicast: * - * Constructs a #GFile for a given URI. This operation never - * fails, but the returned object might not support any I/O - * operation if @uri is malformed or if the uri type is - * not supported. + * Whether this is a multicast address. + * See g_inet_address_get_is_multicast(). * - * Returns: (transfer full): a #GFile for the given @uri. + * Since: 2.22 */ /** - * g_mount_operation_set_anonymous: - * @op: a #GMountOperation. - * @anonymous: boolean value. + * GInetAddress:is-site-local: * - * Sets the mount operation to use an anonymous user if @anonymous is %TRUE. + * Whether this is a site-local address. + * See g_inet_address_get_is_loopback(). + * + * Since: 2.22 */ /** - * G_TYPE_PARAM_OBJECT: + * GInetSocketAddress: * - * The #GType of #GParamSpecObject. + * An IPv4 or IPv6 socket address, corresponding to a <type>struct + * sockaddr_in</type> or <type>struct sockaddr_in6</type>. */ /** - * SECTION: - * @title: GUnixFDMessage - * @short_description: A GSocketControlMessage containing a GUnixFDList - * @include: gio/gunixfdmessage.h - * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage + * GInitable: * - * This #GSocketControlMessage contains a #GUnixFDList. - * It may be sent using g_socket_send_message() and received using - * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied - * between processes by the kernel. - * For an easier way to send and receive file descriptors over - * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and - * g_unix_connection_receive_fd(). - * Note that <filename><gio/gunixfdmessage.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Interface for initializable objects. * - * G_socket_receive_message() over unix sockets (ie: sockets in the + * Since: 2.22 */ /** - * SECTION:gdriv: - * @short_description: Drive management - * @include: gio/gio.h + * GInitableIface: + * @g_iface: The parent interface. + * @init: Initializes the object. * - * #GDrive - this represent a piece of hardware connected to the machine. - * It's generally only created for removable hardware or hardware with - * removable media. - * #GDrive is a container class for #GVolume objects that stem from - * the same piece of media. As such, #GDrive abstracts a drive with - * (or without) removable media and provides operations for querying - * whether media is available, determing whether media change is - * automatically detected and ejecting the media. - * If the #GDrive reports that media isn't automatically detected, one - * can poll for media; typically one should not do this periodically - * as a poll for media operation is potententially expensive and may - * spin up the drive creating noise. - * #GDrive supports starting and stopping drives with authentication - * support for the former. This can be used to support a diverse set - * of use cases including connecting/disconnecting iSCSI devices, - * powering down external disk enclosures and starting/stopping - * multi-disk devices such as RAID devices. Note that the actual - * semantics and side-effects of starting/stopping a #GDrive may vary - * according to implementation. To choose the correct verbs in e.g. a - * file manager, use g_drive_get_start_stop_type(). - * For porting from GnomeVFS note that there is no equivalent of - * #GDrive in that API. + * Provides an interface for initializing object such that initialization + * may fail. + * + * Since: 2.22 */ /** - * GTypePluginCompleteTypeInfo: - * @plugin: the #GTypePlugin - * @g_type: the #GType whose info is completed - * @info: the #GTypeInfo struct to fill in - * @value_table: the #GTypeValueTable to fill in + * GInitiallyUnowned: * - * The type of the @complete_type_info function of #GTypePluginClass. + * All the fields in the <structname>GInitiallyUnowned</structname> structure + * are private to the #GInitiallyUnowned implementation and should never be + * accessed directly. */ /** - * g_dbus_message_get_header_fields: - * @message: A #GDBusMessage. - * - * Gets an array of all header fields on @message that are set. - * %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a - * #guchar. Free with g_free(). + * GInitiallyUnownedClass: * - * Returns: An array of header fields terminated by - * Since: 2.26 + * The class structure for the <structname>GInitiallyUnowned</structname> type. */ /** - * g_application_get_application_id: - * @application: a #GApplication - * @returns: the identifier for @application, owned by @application - * - * Gets the unique identifier for @application. + * GInputStream: * - * Since: 2.28 + * Base class for streaming input operations. */ /** - * g_socket_connection_factory_create_connection: - * @socket: a #GSocket + * GInputVector: + * @buffer: Pointer to a buffer where data will be written. + * @size: the available size in @buffer. * - * Creates a #GSocketConnection subclass of the right type for + * Structure used for scatter/gather data input. + * You generally pass in an array of #GInputVector<!-- -->s + * and the operation will store the read data starting in the + * first buffer, switching to the next as needed. * - * Returns: (transfer full): a #GSocketConnection * Since: 2.22 */ /** - * g_drive_poll_for_media: - * @drive: a #GDrive. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback + * GInstanceInitFunc: + * @instance: The instance to initialize. + * @g_class: The class of the type the instance is created for. * - * Asynchronously polls @drive to see if media has been inserted or removed. - * When the operation is finished, @callback will be called. - * You can then call g_drive_poll_for_media_finish() to obtain the - * result of the operation. + * A callback function used by the type system to initialize a new + * instance of a type. This function initializes all instance members and + * allocates any resources required by it. + * Initialization of a derived instance involves calling all its parent + * types instance initializers, so the class member of the instance + * is altered during its initialization to always point to the class that + * belongs to the type the current initializer was introduced for. */ /** - * g_file_trash: - * @file: #GFile to send to trash. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL - * - * Sends @file to the "Trashcan", if possible. This is similar to - * deleting it, but the user can recover it before emptying the trashcan. - * Not all file systems support trashing, so this call can return the - * %G_IO_ERROR_NOT_SUPPORTED error. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * GInterfaceFinalizeFunc: + * @g_iface: The interface structure to finalize. + * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. * - * Returns: %TRUE on successful trash, %FALSE otherwise. + * A callback function used by the type system to finalize an interface. + * This function should destroy any internal data and release any resources + * allocated by the corresponding GInterfaceInitFunc() function. */ /** - * g_unix_mounts_get: (skip) - * @time_read: (out) (allow-none): guint64 to contain a timestamp, or %NULL - * - * Gets a #GList of #GUnixMountEntry containing the unix mounts. - * If @time_read is set, it will be filled with the mount - * timestamp, allowing for checking if the mounts have changed - * with g_unix_mounts_changed_since(). - * a #GList of the UNIX mounts. + * GInterfaceInfo: + * @interface_init: location of the interface initialization function + * @interface_finalize: location of the interface finalization function + * @interface_data: user-supplied data passed to the interface init/finalize functions * - * Returns: (element-type GUnixMountEntry) (transfer full): + * A structure that provides information to the type system which is + * used specifically for managing interface types. */ /** - * SECTION:gappinf: - * @short_description: Application information and launch contexts - * @include: gio/gio.h + * GInterfaceInitFunc: + * @g_iface: The interface structure to initialize. + * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. * - * #GAppInfo and #GAppLaunchContext are used for describing and launching - * applications installed on the system. - * As of GLib 2.20, URIs will always be converted to POSIX paths - * (using g_file_get_path()) when using g_app_info_launch() even if - * the application requested an URI and not a POSIX path. For example - * for an desktop-file based application with Exec key <literal>totem - * %%U</literal> and a single URI, - * <literal>sftp://foo/file.avi</literal>, then - * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> 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 is not the case, the URI will be passed - * unmodified to the application. Some URIs, such as - * <literal>mailto:</literal>, of course cannot be mapped to a POSIX - * path (in gvfs there's no FUSE mount for it); such URIs will be - * passed unmodified to the application. - * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped - * back to the GIO URI in the #GFile constructors (since gvfs - * implements the #GVfs extension point). As such, if the application - * needs to examine the URI, it needs to use g_file_get_uri() or - * similar on #GFile. In other words, an application cannot assume - * that the URI passed to e.g. g_file_new_for_commandline_arg() is - * equal to the result of g_file_get_uri(). The following snippet - * illustrates this: - * <programlisting> - * GFile *f; - * char *uri; - * file = g_file_new_for_commandline_arg (uri_from_commandline); - * uri = g_file_get_uri (file); - * strcmp (uri, uri_from_commandline) == 0; // FALSE - * g_free (uri); - * if (g_file_has_uri_scheme (file, "cdda")) - * { - * // do something special with uri - * } - * g_object_unref (file); - * </programlisting> - * This code will work when both <literal>cdda://sr0/Track - * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track - * 1.wav</literal> is passed to the application. It should be noted - * that it's generally not safe for applications to rely on the format - * of a particular URIs. Different launcher applications (e.g. file - * managers) may have different ideas of what a given URI means. + * A callback function used by the type system to initialize a new + * interface. This function should initialize all internal data and + * allocate any resources required by the interface. */ /** - * G_PRIORITY_LOW: + * GLoadableIcon: * - * Use this for very low priority background tasks. - * It is not used within GLib or GTK+. + * Generic type for all kinds of icons that can be loaded + * as a stream. */ /** - * g_proxy_address_get_destination_por: - * @proxy: a #GProxyAddress - * - * Gets @proxy's destination port. + * GLoadableIconIface: + * @g_iface: The parent interface. + * @load: Loads an icon. + * @load_async: Loads an icon asynchronously. + * @load_finish: Finishes an asynchronous icon load. * - * Returns: the @proxy's destination port - * Since: 2.26 + * Interface for icons that can be loaded as a stream. */ /** - * g_action_group_get_action_state_type: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query - * - * Queries the type of the state of the named action within - * If the action is stateful then this function returns the - * #GVariantType of the state. All calls to g_action_group_set_state() - * must give a #GVariant of this type and g_action_group_get_state() - * will return a #GVariant of the same type. - * If the action is not stateful then this function will return %NULL. - * In that case, g_action_group_get_state() will return %NULL and you - * must not call g_action_group_set_state(). - * The state type of a particular action will never change but it is - * possible for an action to be removed and for a new action to be added - * with the same name but a different state type. + * GMainContext: * - * Returns: (transfer full): the state type, if the action is stateful - * Since: 2.28 + * The <structname>GMainContext</structname> struct is an opaque data + * type representing a set of sources to be handled in a main loop. */ /** - * GDriveStartFlags: - * @G_DRIVE_START_NONE: No flags set. - * - * Flags used when starting a drive. + * GMainLoop: * - * Since: 2.22 + * The <structname>GMainLoop</structname> struct is an opaque data type + * representing the main event loop of a GLib or GTK+ application. */ /** - * g_application_activate: - * @application: a #GApplication - * - * Activates the application. - * In essence, this results in the #GApplication::activate() signal being - * emitted in the primary instance. - * The application must be registered before calling this function. + * GMarkupError: + * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8 + * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace + * @G_MARKUP_ERROR_PARSE: document was ill-formed + * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known + * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known + * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid + * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing * - * Since: 2.28 + * Error codes returned by markup parsing. */ /** - * G_TYPE_PARAM_STRING: + * GMarkupParseContext: * - * The #GType of #GParamSpecString. + * A parse context is used to parse a stream of bytes that + * you expect to contain marked-up text. + * See g_markup_parse_context_new(), #GMarkupParser, and so + * on for more details. */ /** - * g_mount_unmount_with_operation: - * @mount: a #GMount. - * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. - * - * Unmounts a mount. This is an asynchronous operation, and is - * finished by calling g_mount_unmount_with_operation_finish() with the @mount - * and #GAsyncResult data returned in the @callback. + * GMarkupParseFlags: + * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use + * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked sections are not passed literally to the @passthrough function of the parser. Instead, the content of the section (without the <literal><![CDATA[</literal> and <literal>]]></literal>) is passed to the @text function. This flag was added in GLib 2.12 + * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup itself have line/column information prefixed to them to let the caller know the location of the error. When this flag is set the location information is also prefixed to errors generated by the #GMarkupParser implementation functions * - * Since: 2.22 + * Flags that affect the behaviour of the parser. */ /** - * 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. + * GMarkupParser: + * @start_element: Callback to invoke when the opening tag of an element is seen. + * @end_element: Callback to invoke when the closing tag of an element is seen. Note that this is also called for empty tags like <literal><empty/></literal>. + * @text: Callback to invoke when some text is seen (text is always inside an element). Note that the text of an element may be spread over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also called for the content of CDATA marked sections. + * @passthrough: Callback to invoke for comments, processing instructions and doctype declarations; if you're re-writing the parsed document, write the passthrough text back out in the same position. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also called for CDATA marked sections. + * @error: Callback to invoke when an error occurs. * - * Returns: #GIOErrorEnum value for the given error number. - * Since: 2.26 + * Any of the fields in #GMarkupParser can be %NULL, in which case they + * will be ignored. Except for the @error function, any of these callbacks + * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT, + * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT + * errors are intended to be set from these callbacks. If you set an error + * from a callback, g_markup_parse_context_parse() will report that error + * back to its caller. */ /** - * g_file_stop_mountable_finish: - * @file: input #GFile. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes an stop operation, see g_file_stop_mountable() for details. - * Finish an asynchronous stop operation that was started - * with g_file_stop_mountable(). - * otherwise. + * GMemVTable: + * @malloc: function to use for allocating memory. + * @realloc: function to use for reallocating memory. + * @free: function to use to free memory. + * @calloc: function to use for allocating zero-filled memory. + * @try_malloc: function to use for allocating memory without a default error handler. + * @try_realloc: function to use for reallocating memory without a default error handler. * - * Returns: %TRUE if the operation finished successfully. %FALSE - * Since: 2.22 + * A set of functions used to perform memory allocation. The same #GMemVTable must + * be used for all allocations in the same program; a call to g_mem_set_vtable(), + * if it exists, should be prior to any use of GLib. */ /** - * g_cancellable_get_current: - * - * Gets the top cancellable from the stack. - * if the stack is empty. + * GMemoryInputStream: * - * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL + * Implements #GInputStream for arbitrary memory chunks. */ /** - * GSimpleAsyncResult: + * GMemoryOutputStream: * - * A simple implementation of #GAsyncResult. + * Implements #GOutputStream for arbitrary memory chunks. */ /** - * GTypeFundamentalInfo: - * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type + * GMemoryOutputStream:data: * - * A structure that provides information to the type system which is - * used specifically for managing fundamental types. + * Pointer to buffer where data will be written. + * + * Since: 2.24 */ /** - * g_file_replace_readwrite_async: - * @file: input #GFile. - * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore. - * @make_backup: %TRUE if a backup should be created. - * @flags: a set of #GFileCreateFlags. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * GMemoryOutputStream:data-size: * - * Asynchronously overwrites the file in read-write mode, replacing the - * contents, possibly creating a backup copy of the file first. - * For more details, see g_file_replace_readwrite() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then - * call g_file_replace_readwrite_finish() to get the result of the operation. + * Size of data written to the buffer. * - * Since: 2.22 + * Since: 2.24 */ /** - * g_dbus_server_new_sync: - * @address: A D-Bus address. - * @flags: Flags from the #GDBusServerFlags enumeration. - * @guid: A D-Bus GUID. - * @observer: A #GDBusAuthObserver or %NULL. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for server or %NULL. + * GMemoryOutputStream:destroy-function: (skip) * - * Creates a new D-Bus server that listens on the first address in - * Once constructed, you can use g_dbus_server_get_client_address() to - * get a D-Bus address string that clients can use to connect. - * Connect to the #GDBusServer::new-connection signal to handle - * incoming connections. - * The returned #GDBusServer isn't active - you have to start it with - * g_dbus_server_start(). - * See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can - * be used. - * This is a synchronous failable constructor. See - * g_dbus_server_new() for the asynchronous version. - * g_object_unref(). + * Function called with the buffer as argument when the stream is destroyed. * - * Returns: A #GDBusServer or %NULL if @error is set. Free with - * Since: 2.26 + * Since: 2.24 */ /** - * g_settings_backend_flatten_tree: - * @tree: a #GTree containing the changes - * @path: (out): the location to save the path - * @keys: (out) (transfer container) (array zero-terminated=1): the location to save the relative keys - * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): the location to save the values, or %NULL + * GMemoryOutputStream:realloc-function: (skip) * - * Calculate the longest common prefix of all keys in a tree and write - * out an array of the key names relative to that prefix and, - * optionally, the value to store at each of those keys. - * You must free the value returned in @path, @keys and @values using - * g_free(). You should not attempt to free or unref the contents of + * Function with realloc semantics called to enlarge the buffer. * - * Since: 2.26 + * Since: 2.24 */ /** - * g_poll_file_monitor_new: - * @file: a #GFile. + * GMemoryOutputStream:size: * - * Polls @file for changes. + * Current size of the data buffer. * - * Returns: a new #GFileMonitor for the given #GFile. + * Since: 2.24 */ /** - * GInterfaceInitFunc: - * @g_iface: The interface structure to initialize. - * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. + * GMount: * - * A callback function used by the type system to initialize a new - * interface. This function should initialize all internal data and - * allocate any resources required by the interface. + * A handle to an object implementing the #GMountIface interface. */ /** - * g_filter_output_stream_get_base_stream: - * @stream: a #GFilterOutputStream. - * - * Gets the base stream for the filter stream. + * GMount::changed: + * @mount: the object on which the signal is emitted * - * Returns: (transfer none): a #GOutputStream. + * Emitted when the mount has been changed. */ /** - * g_unix_mount_compare: - * @mount1: first #GUnixMountEntry to compare. - * @mount2: second #GUnixMountEntry to compare. + * GMount::pre-unmount: + * @mount: the object on which the signal is emitted * - * Compares two unix mounts. - * or less than @mount2, respectively. + * This signal is emitted when the #GMount is about to be + * unmounted. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * Since: 2.22 */ /** - * g_socket_client_get_tls: - * @client: a #GSocketClient. - * - * Gets whether @client creates TLS connections. See - * g_socket_client_set_tls() for details. + * GMount::unmounted: + * @mount: the object on which the signal is emitted * - * Returns: whether @client uses TLS - * Since: 2.28 + * This signal is emitted when the #GMount have been + * unmounted. If the recipient is holding references to the + * object they should release them so the object can be + * finalized. */ /** - * g_action_group_get_action_parameter_type: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query - * - * Queries the type of the parameter that must be given when activating - * the named action within @action_group. - * When activating the action using g_action_group_activate(), the - * #GVariant given to that function must be of the type returned by this - * function. - * In the case that this function returns %NULL, you must not give any - * #GVariant, but %NULL instead. - * The parameter type of a particular action will never change but it is - * possible for an action to be removed and for a new action to be added - * with the same name but a different parameter type. + * GMountIface: + * @g_iface: The parent interface. + * @changed: Changed signal that is emitted when the mount's state has changed. + * @unmounted: The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. + * @pre_unmount: The pre_unmout signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file. + * @get_root: Gets a #GFile to the root directory of the #GMount. + * @get_name: Gets a string containing the name of the #GMount. + * @get_icon: Gets a #GIcon for the #GMount. + * @get_uuid: Gets the UUID for the #GMount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. + * @get_volume: Gets a #GVolume the mount is located on. Returns %NULL if the #GMount is not associated with a #GVolume. + * @get_drive: Gets a #GDrive the volume of the mount is located on. Returns %NULL if the #GMount is not associated with a #GDrive or a #GVolume. This is convenience method for getting the #GVolume and using that to get the #GDrive. + * @can_unmount: Checks if a #GMount can be unmounted. + * @can_eject: Checks if a #GMount can be ejected. + * @unmount: Starts unmounting a #GMount. + * @unmount_finish: Finishes an unmounting operation. + * @eject: Starts ejecting a #GMount. + * @eject_finish: Finishes an eject operation. + * @remount: Starts remounting a #GMount. + * @remount_finish: Finishes a remounting operation. + * @guess_content_type: Starts guessing the type of the content of a #GMount. See g_mount_guess_content_type() for more information on content type guessing. This operation was added in 2.18. + * @guess_content_type_finish: Finishes a contenet type guessing operation. Added in 2.18. + * @guess_content_type_sync: Synchronous variant of @guess_content_type. Added in 2.18 + * @unmount_with_operation: Starts unmounting a #GMount using a #GMountOperation. Since 2.22. + * @unmount_with_operation_finish: Finishes an unmounting operation using a #GMountOperation. Since 2.22. + * @eject_with_operation: Starts ejecting a #GMount using a #GMountOperation. Since 2.22. + * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22. + * @get_default_location: Gets a #GFile indication a start location that can be use as the entry point for this mount. Since 2.24. * - * Returns: the parameter type - * Since: 2.28 + * Interface for implementing operations for mounts. */ /** - * g_dbus_property_info_unref: - * @info: A #GDBusPropertyInfo. - * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. + * GMountMountFlags: + * @G_MOUNT_MOUNT_NONE: No flags set. * - * Since: 2.26 + * Flags used when mounting a mount. */ /** - * G_VARIANT_TYPE_DICTIONARY: + * GMountOperation: * - * An indefinite type that is a supertype of every dictionary type -- - * that is, any array type that has an element type equal to any - * dictionary entry type. + * Class for providing authentication methods for mounting operations, + * such as mounting a file locally, or authenticating with a server. */ /** - * GParamSpecObject: - * @parent_instance: private #GParamSpec portion + * GMountOperation::aborted: * - * A #GParamSpec derived structure that contains the meta data for object properties. + * Emitted by the backend when e.g. a device becomes unavailable + * while a mount operation is in progress. + * Implementations of GMountOperation should handle this signal + * by dismissing open password dialogs. + * + * Since: 2.20 */ /** - * g_file_unmount_mountable_with_operation: - * @file: input #GFile. - * @flags: flags affecting the operation - * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. - * @user_data: (closure): the data to pass to callback function - * - * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * When the operation is finished, @callback will be called. You can then call - * g_file_unmount_mountable_finish() to get the result of the operation. + * GMountOperation::ask-password: + * @op: a #GMountOperation requesting a password. + * @message: string containing a message to display to the user. + * @default_user: string containing the default user name. + * @default_domain: string containing the default domain. + * @flags: a set of #GAskPasswordFlags. * - * Since: 2.22 + * Emitted when a mount operation asks the user for a password. + * If the message contains a line break, the first line should be + * presented as a heading. For example, it may be used as the + * primary text in a #GtkMessageDialog. */ /** - * G_TYPE_BOXED: + * GMountOperation::ask-question: + * @op: a #GMountOperation asking a question. + * @message: string containing a message to display to the user. + * @choices: an array of strings for each possible choice. * - * The fundamental type from which all boxed types are derived. + * Emitted when asking the user a question and gives a list of + * choices for the user to choose from. + * If the message contains a line break, the first line should be + * presented as a heading. For example, it may be used as the + * primary text in a #GtkMessageDialog. */ /** - * GTlsCertificate:private-key: - * - * The DER (binary) encoded representation of the certificate's - * private key. This property (or the - * #GTlsCertificate:private-key-pem property) can be set when - * constructing a key (eg, from a file), but cannot be read. + * GMountOperation::reply: + * @op: a #GMountOperation. + * @result: a #GMountOperationResult indicating how the request was handled * - * Since: 2.28 + * Emitted when the user has replied to the mount operation. */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED: + * GMountOperation::show-processes: + * @op: a #GMountOperation. + * @message: string containing a message to display to the user. + * @processes: an array of #GPid for processes blocking the operation. + * @choices: an array of strings for each possible choice. * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started - * degraded. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * Emitted when one or more processes are blocking an operation + * e.g. unmounting/ejecting a #GMount or stopping a #GDrive. + * Note that this signal may be emitted several times to update the + * list of blocking processes as processes close files. The + * application should only respond with g_mount_operation_reply() to + * the latest signal (setting #GMountOperation:choice to the choice + * the user made). + * If the message contains a line break, the first line should be + * presented as a heading. For example, it may be used as the + * primary text in a #GtkMessageDialog. * * Since: 2.22 */ /** - * g_permission_acquire_async: - * @permission: a #GPermission instance - * @cancellable: a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback to call when done - * @user_data: the user data to pass to @callback - * - * Attempts to acquire the permission represented by @permission. - * This is the first half of the asynchronous version of - * g_permission_acquire(). + * GMountOperation:anonymous: * - * Since: 2.26 + * Whether to use an anonymous user when authenticating. */ /** - * GSettingsBindGetMapping: - * @value: return location for the property value - * @variant: the #GVariant - * @user_data: user data that was specified when the binding was created - * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error + * GMountOperation:choice: * - * The type for the function that is used to convert from #GSettings to - * an object property. The @value is already initialized to hold values - * of the appropriate type. + * The index of the user's choice when a question is asked during the + * mount operation. See the #GMountOperation::ask-question signal. */ /** - * SECTION:gdataoutputstrea: - * @short_description: Data Output Stream - * @include: gio/gio.h - * @see_also: #GOutputStream + * GMountOperation:domain: * - * Data output stream implements #GOutputStream and includes functions for - * writing data directly to an output stream. + * The domain to use for the mount operation. */ /** - * g_output_stream_splice_async: - * @stream: a #GOutputStream. - * @source: a #GInputStream. - * @flags: a set of #GOutputStreamSpliceFlags. - * @io_priority: the io priority of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. + * GMountOperation:password: * - * Splices a stream asynchronously. - * When the operation is finished @callback will be called. - * You can then call g_output_stream_splice_finish() to get the - * result of the operation. - * For the synchronous, blocking version of this function, see - * g_output_stream_splice(). + * The password that is used for authentication when carrying out + * the mount operation. */ /** - * GMarkupParseContext: + * GMountOperation:password-save: * - * A parse context is used to parse a stream of bytes that - * you expect to contain marked-up text. - * See g_markup_parse_context_new(), #GMarkupParser, and so - * on for more details. + * Determines if and how the password information should be saved. */ /** - * g_file_info_dup: - * @other: a #GFileInfo. - * - * Duplicates a file info structure. + * GMountOperation:username: * - * Returns: (transfer full): a duplicate #GFileInfo of @other. + * The user name that is used for authentication when carrying out + * the mount operation. */ /** - * g_simple_action_group_lookup: - * @simple: a #GSimpleActionGroup - * @action_name: the name of an action - * - * Looks up the action with the name @action_name in the group. - * If no such action exists, returns %NULL. + * GMountOperationResult: + * @G_MOUNT_OPERATION_HANDLED: The request was fulfilled and the user specified data is now available + * @G_MOUNT_OPERATION_ABORTED: The user requested the mount operation to be aborted + * @G_MOUNT_OPERATION_UNHANDLED: The request was unhandled (i.e. not implemented) * - * Returns: (transfer none): a #GAction, or %NULL - * Since: 2.28 + * #GMountOperationResult is returned as a result when a request for + * information is send by the mounting operation. */ /** - * g_output_stream_flush: - * @stream: a #GOutputStream. - * @cancellable: (allow-none): optional cancellable object - * @error: location to store the error occuring, or %NULL to ignore - * - * Flushed any outstanding buffers in the stream. Will block during - * the operation. Closing the stream will implicitly cause a flush. - * This function is optional for inherited classes. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * GMountUnmountFlags: + * @G_MOUNT_UNMOUNT_NONE: No flags set. + * @G_MOUNT_UNMOUNT_FORCE: Unmount even if there are outstanding file operations on the mount. * - * Returns: %TRUE on success, %FALSE on error + * Flags used when an unmounting a mount. */ /** - * g_dbus_is_guid: - * @string: The string to check. - * - * Checks if @string is a D-Bus GUID. - * See the D-Bus specification regarding what strings are valid D-Bus - * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). + * GNetworkAddress: * - * Returns: %TRUE if @string is a guid, %FALSE otherwise. - * Since: 2.26 + * A #GSocketConnectable for resolving a hostname and connecting to + * that host. */ /** - * g_file_io_stream_get_etag: - * @stream: a #GFileIOStream. - * - * Gets the entity tag for the file when it has been written. - * This must be called after the stream has been written - * and closed, as the etag can change while writing. + * GNetworkService: * - * Returns: the entity tag for the stream. - * Since: 2.22 + * A #GSocketConnectable for resolving a SRV record and connecting to + * that service. */ /** - * g_buffered_input_stream_read_byte: - * @stream: a #GBufferedInputStream - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: location to store the error occuring, or %NULL to ignore - * - * Tries to read a single byte from the stream or the buffer. Will block - * during this read. - * On success, the byte read from the stream is returned. On end of stream - * -1 is returned but it's not an exceptional error and @error is not set. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * On error -1 is returned and @error is set accordingly. + * GObject: * - * Returns: the byte read from the @stream, or -1 on end of stream or error. + * All the fields in the <structname>GObject</structname> structure are private + * to the #GObject implementation and should never be accessed directly. */ /** - * GSimpleActionGroup: - * - * The #GSimpleActionGroup structure contains private data and should only be accessed using the provided API. + * GObjectClass: + * @g_type_class: the parent class + * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons. + * @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system. + * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties. + * @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class. + * @finalize: instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class. + * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed. + * @notify: the class closure for the notify signal + * @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation. * - * Since: 2.26 + * The class structure for the <structname>GObject</structname> type. + * <example> + * <title>Implementing singletons using a constructor</title> + * <programlisting> + * static MySingleton *the_singleton = NULL; + * static GObject* + * my_singleton_constructor (GType type, + * guint n_construct_params, + * GObjectConstructParam *construct_params) + * { + * GObject *object; + * if (!the_singleton) + * { + * object = G_OBJECT_CLASS (parent_class)->constructor (type, + * n_construct_params, + * construct_params); + * the_singleton = MY_SINGLETON (object); + * } + * else + * object = g_object_ref (G_OBJECT (the_singleton)); + * return object; + * } + * </programlisting></example> */ /** - * g_socket_set_blocking: - * @socket: a #GSocket. - * @blocking: Whether to use blocking I/O or not. - * - * Sets the blocking mode of the socket. In blocking mode - * all operations block until they succeed or there is an error. In - * non-blocking mode all functions return results immediately or - * with a %G_IO_ERROR_WOULD_BLOCK error. - * All sockets are created in blocking mode. However, note that the - * platform level socket is always non-blocking, and blocking mode - * is a GSocket level feature. + * GObjectConstructParam: + * @pspec: the #GParamSpec of the construct parameter + * @value: the value to set the parameter to * - * Since: 2.22 + * The <structname>GObjectConstructParam</structname> struct is an auxiliary + * structure used to hand #GParamSpec/#GValue pairs to the @constructor of + * a #GObjectClass. */ /** - * g_buffered_input_stream_get_buffer_size: - * @stream: a #GBufferedInputStream - * - * Gets the size of the input buffer. + * GObjectFinalizeFunc: + * @object: the #GObject being finalized * - * Returns: the current buffer size. + * The type of the @finalize function of #GObjectClass. */ /** - * g_unix_fd_list_peek_fds: - * @list: a #GUnixFDList - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL - * - * Returns the array of file descriptors that is contained in this - * object. - * After this call, the descriptors remain the property of @list. The - * caller must not close them and must not free the array. The array is - * valid only until @list is changed in any way. - * If @length is non-%NULL then it is set to the number of file - * descriptors in the returned array. The returned array is also - * terminated with -1. - * This function never returns %NULL. In case there are no file - * descriptors contained in @list, an empty array is returned. - * descriptors + * GObjectGetPropertyFunc: + * @object: a #GObject + * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). + * @value: a #GValue to return the property value in + * @pspec: the #GParamSpec describing the property * - * Returns: (array length=length) (transfer none): an array of file - * Since: 2.24 + * The type of the @get_property function of #GObjectClass. */ /** - * g_network_address_new: - * @hostname: the hostname - * @port: the port - * - * Creates a new #GSocketConnectable for connecting to the given + * GObjectSetPropertyFunc: + * @object: a #GObject + * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). + * @value: the new value for the property + * @pspec: the #GParamSpec describing the property * - * Returns: (transfer full): the new #GNetworkAddress - * Since: 2.22 + * The type of the @set_property function of #GObjectClass. */ /** - * g_settings_backend_get_default: - * @returns: (transfer full): the default #GSettingsBackend + * GOptionArg: + * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags. + * @G_OPTION_ARG_STRING: The option takes a string argument. + * @G_OPTION_ARG_INT: The option takes an integer argument. + * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument. + * @G_OPTION_ARG_FILENAME: The option takes a filename as argument. + * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings. + * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings. + * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12 + * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>). Since 2.12 * - * Returns the default #GSettingsBackend. It is possible to override - * the default by setting the <envar>GSETTINGS_BACKEND</envar> - * environment variable to the name of a settings backend. - * The user gets a reference to the backend. + * The #GOptionArg enum values determine which type of extra argument the + * options expect to find. If an option expects an extra argument, it + * can be specified in several ways; with a short option: + * <option>-x arg</option>, with a long option: <option>--name arg</option> * - * Since: 2.28 + * Or combined in a single argument: <option>--name=arg</option>. */ /** - * g_file_info_has_namespace: - * @info: a #GFileInfo. - * @name_space: a file attribute namespace. + * GOptionArgFunc: + * @option_name: The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name. + * @value: The value to be parsed. + * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks. * - * Checks if a file info structure has an attribute in the - * specified @name_space. - * %FALSE otherwise. + * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK + * options. + * occurred, in which case @error should be set with g_set_error() * - * Returns: %TRUE if @Ginfo has an attribute in @name_space, - * Since: 2.22 + * Returns: %TRUE if the option was successfully parsed, %FALSE if an error */ /** - * g_data_output_stream_put_uint32: - * @stream: a #GDataOutputStream. - * @data: a #guint32. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts an unsigned 32-bit integer into the stream. + * GOptionContext: * - * Returns: %TRUE if @data was successfully added to the @stream. + * A <structname>GOptionContext</structname> struct defines which options + * are accepted by the commandline option parser. The struct has only private + * fields and should not be directly accessed. */ /** - * g_file_set_attribute: - * @file: input #GFile. - * @attribute: a string containing the attribute's name. - * @type: The type of the attribute - * @value_p: a pointer to the value (or the pointer itself if the type is a pointer type) - * @flags: a set of #GFileQueryInfoFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * GOptionEntry: + * @long_name: The long name of an option can be used to specify it in a commandline as --<replaceable>long_name</replaceable>. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>. + * @short_name: If an option has a short name, it can be specified -<replaceable>short_name</replaceable> in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name. + * @flags: Flags from #GOptionFlags. + * @arg: The type of the option, as a #GOptionArg. + * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: <variablelist> <varlistentry> <term>%G_OPTION_ARG_NONE</term> <listitem><para>%gboolean</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_INT</term> <listitem><para>%gint</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_DOUBLE</term> <listitem><para>%gdouble</para></listitem> </varlistentry> </variablelist> If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). + * @description: the description for the option in <option>--help</option> output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). + * @arg_description: The placeholder to use for the extra argument parsed by the option in <option>--help</option> output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). * - * Sets an attribute in the file with attribute name @attribute to @value. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * A <structname>GOptionEntry</structname> defines a single option. + * To have an effect, they must be added to a #GOptionGroup with + * g_option_context_add_main_entries() or g_option_group_add_entries(). + */ + + +/** + * GOptionError: + * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options(). + * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed. + * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed. * - * Returns: %TRUE if the attribute was set, %FALSE otherwise. + * Error codes returned by option parsing. */ /** - * g_filename_completer_get_completion_suffix: - * @completer: the filename completer. - * @initial_text: text to be completed. + * GOptionErrorFunc: + * @context: The active #GOptionContext + * @group: The group to which the function belongs + * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + * @error: The #GError containing details about the parse error * - * Obtains a completion for @initial_text from @completer. - * This string is not owned by GIO, so remember to g_free() it - * when finished. + * The type of function to be used as callback when a parse error occurs. + */ + + +/** + * GOptionFlags: + * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output. + * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the <option>--help</option> output, even if it is defined in a group. + * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed. + * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8 + * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8 + * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8 + * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution which prefixes long option names with <literal>groupname-</literal> if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8. * - * Returns: a completed string, or %NULL if no completion exists. + * Flags which modify individual options. */ /** - * GFileMonitorFlags: - * @G_FILE_MONITOR_NONE: No flags set. - * @G_FILE_MONITOR_WATCH_MOUNTS: Watch for mount events. - * @G_FILE_MONITOR_SEND_MOVED: Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead (NB: not supported on all backends; the default behaviour -without specifying this flag- is to send single DELETED and CREATED events). + * GOptionGroup: * - * Flags used to set what a #GFileMonitor will watch for. + * A <structname>GOptionGroup</structname> struct defines the options in a single + * group. The struct has only private fields and should not be directly accessed. + * All options in a group share the same translation function. Libraries which + * need to parse commandline options are expected to provide a function for + * getting a <structname>GOptionGroup</structname> holding their options, which + * the application can then add to its #GOptionContext. */ /** - * g_file_icon_new: - * @file: a #GFile. + * GOptionParseFunc: + * @context: The active #GOptionContext + * @group: The group to which the function belongs + * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + * @error: A return location for error details * - * Creates a new icon for a file. + * The type of function that can be called before and after parsing. + * occurred, in which case @error should be set with g_set_error() * - * Returns: (transfer full): a #GIcon for the given @file, or %NULL on error. + * Returns: %TRUE if the function completed successfully, %FALSE if an error */ /** - * g_app_info_get_recommended_for_type: - * @content_type: the content type to find a #GAppInfo for - * - * Gets a list of recommended #GAppInfos for a given content type, i.e. - * those applications which claim to support the given content type exactly, - * and not by MIME type subclassing. - * Note that the first application of the list is the last used one, i.e. - * the last one for which #g_app_info_set_as_last_used_for_type has been - * called. - * for given @content_type or %NULL on error. + * GOutputStream: * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos - * Since: 2.28 + * Base class for writing output. + * All classes derived from GOutputStream should implement synchronous + * writing, splicing, flushing and closing streams, but may implement + * asynchronous versions. */ /** - * SECTION:gnetworkservic: - * @short_description: A GSocketConnectable for resolving SRV records - * @include: gio/gio.h + * GOutputStreamSpliceFlags: + * @G_OUTPUT_STREAM_SPLICE_NONE: Do not close either stream. + * @G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE: Close the source stream after the splice. + * @G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET: Close the target stream after the splice. * - * Like #GNetworkAddress does with hostnames, #GNetworkService - * provides an easy way to resolve a SRV record, and then attempt to - * connect to one of the hosts that implements that service, handling - * service priority/weighting, multiple IP addresses, and multiple - * address families. - * See #GSrvTarget for more information about SRV records, and see - * #GSocketConnectable for and example of using the connectable - * interface. + * GOutputStreamSpliceFlags determine how streams should be spliced. */ /** - * g_file_start_mountable: - * @file: input #GFile. - * @flags: flags affecting the operation - * @start_operation: a #GMountOperation, or %NULL to avoid user interaction. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. - * @user_data: the data to pass to callback function + * GOutputVector: + * @buffer: Pointer to a buffer of data to read. + * @size: the size of @buffer. * - * Starts a file of type G_FILE_TYPE_MOUNTABLE. - * Using @start_operation, you can request callbacks when, for instance, - * passwords are needed during authentication. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * When the operation is finished, @callback will be called. You can then call - * g_file_mount_mountable_finish() to get the result of the operation. + * Structure used for scatter/gather data output. + * You generally pass in an array of #GOutputVector<!-- -->s + * and the operation will use all the buffers as if they were + * one buffer. * * Since: 2.22 */ /** - * G_OBJECT_WARN_INVALID_PROPERTY_ID: - * @object: the #GObject on which set_property() or get_property() was called - * @property_id: the numeric id of the property - * @pspec: the #GParamSpec of the property + * GParamFlags: + * @G_PARAM_READABLE: the parameter is readable + * @G_PARAM_WRITABLE: the parameter is writable + * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction + * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction + * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required + * @G_PARAM_STATIC_NAME: the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 + * @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8 + * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 + * @G_PARAM_PRIVATE: internal + * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26 * - * This macro should be used to emit a standard warning about unexpected - * properties in set_property() and get_property() implementations. + * Through the #GParamFlags flag values, certain aspects of parameters + * can be configured. */ /** - * g_app_info_get_default_for_uri_scheme: - * @uri_scheme: a string containing a URI scheme. - * - * Gets the default application for launching applications - * using this URI scheme. A URI scheme is the initial part - * of the URI, up to but not including the ':', e.g. "http", - * "ftp" or "sip". + * GParamSpec: + * @g_type_instance: private #GTypeInstance portion + * @name: name of this parameter + * @flags: #GParamFlags flags for this parameter + * @value_type: the #GValue type for this parameter + * @owner_type: #GType type that uses (introduces) this parameter * - * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. + * All other fields of the <structname>GParamSpec</structname> struct are private and + * should not be used directly. */ /** - * g_file_set_attributes_finish: - * @file: input #GFile. - * @result: a #GAsyncResult. - * @info: (out) (transfer full): a #GFileInfo. - * @error: a #GError, or %NULL - * - * Finishes setting an attribute started in g_file_set_attributes_async(). + * GParamSpecBoolean: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified * - * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise. + * A #GParamSpec derived structure that contains the meta data for boolean properties. */ /** - * G_VARIANT_TYPE_ARRAY: + * GParamSpecBoxed: + * @parent_instance: private #GParamSpec portion * - * An indefinite type that is a supertype of every array type. + * A #GParamSpec derived structure that contains the meta data for boxed properties. */ /** - * g_socket_listener_accept: - * @listener: a #GSocketListener - * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Blocks waiting for a client to connect to any of the sockets added - * to the listener. Returns a #GSocketConnection for the socket that was - * accepted. - * If @source_object is not %NULL it will be filled out with the source - * object specified when the corresponding socket or address was added - * to the listener. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * GParamSpecChar: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 + * A #GParamSpec derived structure that contains the meta data for character properties. */ /** - * g_dbus_node_info_unref: - * @info: A #GDBusNodeInfo. - * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. + * GParamSpecClass: + * @g_type_class: the parent class + * @value_type: the #GValue type for this parameter + * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class. + * @value_set_default: Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default(). + * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_set_validate(). + * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp(). * - * Since: 2.26 + * The class structure for the <structname>GParamSpec</structname> type. + * Normally, <structname>GParamSpec</structname> classes are filled by + * g_param_type_register_static(). */ /** - * g_unix_mount_point_guess_can_eject: - * @mount_point: a #GUnixMountPoint - * - * Guesses whether a Unix mount point can be ejected. + * GParamSpecDouble: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90. * - * Returns: %TRUE if @mount_point is deemed to be ejectable. + * A #GParamSpec derived structure that contains the meta data for double properties. */ /** - * GValueArray: - * @n_values: number of values contained in the array - * @values: array of values + * GParamSpecEnum: + * @parent_instance: private #GParamSpec portion + * @enum_class: the #GEnumClass for the enum + * @default_value: default value for the property specified * - * A #GValueArray contains an array of #GValue elements. + * A #GParamSpec derived structure that contains the meta data for enum + * properties. */ /** - * g_file_enumerate_children_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @error: a #GError. - * - * Finishes an async enumerate children operation. - * See g_file_enumerate_children_async(). - * Free the returned object with g_object_unref(). + * GParamSpecFlags: + * @parent_instance: private #GParamSpec portion + * @flags_class: the #GFlagsClass for the flags + * @default_value: default value for the property specified * - * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred. + * A #GParamSpec derived structure that contains the meta data for flags + * properties. */ /** - * g_dbus_connection_flush: - * @connection: A #GDBusConnection. - * @cancellable: A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. - * @user_data: The data to pass to @callback. - * - * Asynchronously flushes @connection, that is, writes all queued - * outgoing message to the transport and then flushes the transport - * (using g_output_stream_flush_async()). This is useful in programs - * that wants to emit a D-Bus signal and then exit - * immediately. Without flushing the connection, there is no guarantee - * that the message has been sent to the networking buffers in the OS - * kernel. - * This is an asynchronous method. When the operation is finished, - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread you are calling this method from. You can - * then call g_dbus_connection_flush_finish() to get the result of the - * operation. See g_dbus_connection_flush_sync() for the synchronous - * version. + * GParamSpecFloat: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30. * - * Since: 2.26 + * A #GParamSpec derived structure that contains the meta data for float properties. */ /** - * g_inet_address_new_any: - * @family: the address family + * GParamSpecGType: + * @parent_instance: private #GParamSpec portion + * @is_a_type: a #GType whose subtypes can occur as values * - * Creates a #GInetAddress for the "any" address (unassigned/"don't - * care") for @family. - * for @family. + * A #GParamSpec derived structure that contains the meta data for #GType properties. * - * Returns: a new #GInetAddress corresponding to the "any" address - * Since: 2.22 + * Since: 2.10 */ /** - * GProxyAddress: - * - * A #GInetSocketAddress representing a connection via a proxy server + * GParamSpecInt: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Since: 2.26 + * A #GParamSpec derived structure that contains the meta data for integer properties. */ /** - * g_emblemed_icon_get_emblems: - * @emblemed: a #GEmblemedIcon - * - * Gets the list of emblems for the @icon. - * #GEmblem <!-- -->s that is owned by @emblemed + * GParamSpecInt64: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Returns: (element-type Gio.Emblem) (transfer none): a #GList of - * Since: 2.18 + * A #GParamSpec derived structure that contains the meta data for 64bit integer properties. */ /** - * GMainLoop: + * GParamSpecLong: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * The <structname>GMainLoop</structname> struct is an opaque data type - * representing the main event loop of a GLib or GTK+ application. + * A #GParamSpec derived structure that contains the meta data for long integer properties. */ /** - * g_file_io_stream_query_info_finish: - * @stream: a #GFileIOStream. - * @result: a #GAsyncResult. - * @error: a #GError, %NULL to ignore. - * - * Finalizes the asynchronous query started - * by g_file_io_stream_query_info_async(). + * GParamSpecObject: + * @parent_instance: private #GParamSpec portion * - * Returns: (transfer full): A #GFileInfo for the finished query. - * Since: 2.22 + * A #GParamSpec derived structure that contains the meta data for object properties. */ /** - * g_file_hash: - * @file: #gconstpointer to a #GFile. + * GParamSpecOverride: * - * Creates a hash value for a #GFile. - * This call does no blocking i/o. - * integer that can be used as hash value for the #GFile. - * This function is intended for easily hashing a #GFile to - * add to a #GHashTable or similar data structure. + * This is a type of #GParamSpec type that simply redirects operations to + * another paramspec. All operations other than getting or + * setting the value are redirected, including accessing the nick and + * blurb, validating a value, and so forth. See + * g_param_spec_get_redirect_target() for retrieving the overidden + * property. #GParamSpecOverride is used in implementing + * g_object_class_override_property(), and will not be directly useful + * unless you are implementing a new base type similar to GObject. * - * Virtual: hash - * Returns: 0 if @file is not a valid #GFile, otherwise an + * Since: 2.4 */ /** - * g_inet_address_new_loopback: - * @family: the address family - * - * Creates a #GInetAddress for the loopback address for @family. - * for @family. + * GParamSpecParam: + * @parent_instance: private #GParamSpec portion * - * Returns: a new #GInetAddress corresponding to the loopback address - * Since: 2.22 + * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM + * properties. */ /** - * g_unix_mount_monitor_set_rate_limit: - * @mount_monitor: a #GUnixMountMonitor - * @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. + * GParamSpecPointer: + * @parent_instance: private #GParamSpec portion * - * Since: 2.18 + * A #GParamSpec derived structure that contains the meta data for pointer properties. */ /** - * g_file_copy: - * @source: input #GFile. - * @destination: destination #GFile - * @flags: set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @progress_callback: (scope call): function to callback with progress information - * @progress_callback_data: (closure): user data to pass to @progress_callback - * @error: #GError to set on error, or %NULL + * GParamSpecString: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified + * @cset_first: a string containing the allowed values for the first byte + * @cset_nth: a string containing the allowed values for the subsequent bytes + * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth. + * @null_fold_if_empty: replace empty string by %NULL + * @ensure_non_null: replace %NULL strings by an empty string * - * Copies the file @source to the location specified by @destination. - * Can not handle recursive copies of directories. - * If the flag #G_FILE_COPY_OVERWRITE is specified an already - * existing @destination file is overwritten. - * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks - * will be copied as symlinks, otherwise the target of the - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If @progress_callback is not %NULL, then the operation can be monitored by - * setting this to a #GFileProgressCallback function. @progress_callback_data - * will be passed to this function. It is guaranteed that this callback will - * be called after all data has been transferred with the total number of bytes - * copied during the operation. - * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND - * error is returned, independent on the status of the @destination. - * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the - * error G_IO_ERROR_EXISTS is returned. - * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY - * error is returned. If trying to overwrite a directory with a directory the - * G_IO_ERROR_WOULD_MERGE error is returned. - * If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is - * specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error - * is returned. - * If you are interested in copying the #GFile object itself (not the on-disk - * file), see g_file_dup(). + * A #GParamSpec derived structure that contains the meta data for string + * properties. + */ + + +/** + * GParamSpecTypeInfo: + * @instance_size: Size of the instance (object) structure. + * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. + * @instance_init: Location of the instance initialization function (optional). + * @value_type: The #GType of values conforming to this #GParamSpec + * @finalize: The instance finalization function (optional). + * @value_set_default: Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default(). + * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_set_validate(). + * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp(). * - * Returns: %TRUE on success, %FALSE otherwise. + * This structure is used to provide the type system with the information + * required to initialize and destruct (finalize) a parameter's class and + * instances thereof. + * The initialized structure is passed to the g_param_type_register_static() + * The type system will perform a deep copy of this structure, so its memory + * does not need to be persistent across invocation of + * g_param_type_register_static(). */ /** - * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE: + * GParamSpecUChar: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * A key in the "dos" namespace for checking if the file's archive flag - * is set. This attribute is %TRUE if the archive flag is set. This attribute - * is only available for DOS file systems. Corresponding #GFileAttributeType - * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * A #GParamSpec derived structure that contains the meta data for unsigned character properties. */ /** - * g_file_set_attribute_int64: - * @file: input #GFile. - * @attribute: a string containing the attribute's name. - * @value: a #guint64 containing the attribute's new value. - * @flags: a #GFileQueryInfoFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * GParamSpecUInt: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. - * If @attribute is of a different type, this operation will fail. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * A #GParamSpec derived structure that contains the meta data for unsigned integer properties. + */ + + +/** + * GParamSpecUInt64: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise. + * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. */ /** - * G_FILE_ATTRIBUTE_STANDARD_TYPE: + * GParamSpecULong: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * A key in the "standard" namespace for storing file types. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - * The value for this key should contain a #GFileType. + * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. */ /** - * g_file_enumerator_next_files_finish: - * @enumerator: a #GFileEnumerator. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * GParamSpecUnichar: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified * - * Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). - * g_list_free() and unref the infos with g_object_unref() when you're - * done with them. + * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. + */ + + +/** + * GParamSpecValueArray: + * @parent_instance: private #GParamSpec portion + * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL + * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements * - * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with + * A #GParamSpec derived structure that contains the meta data for #GValueArray properties. */ /** - * g_dbus_is_name: - * @string: The string to check. + * GParamSpecVariant: + * @parent_instance: private #GParamSpec portion + * @type: a #GVariantType, or %NULL + * @default_value: a #GVariant, or %NULL * - * Checks if @string is a valid D-Bus bus name (either unique or well-known). + * A #GParamSpec derived structure that contains the meta data for #GVariant properties. * - * Returns: %TRUE if valid, %FALSE otherwise. * Since: 2.26 */ /** - * G_DEFINE_ABSTRACT_TYPE_WITH_CODE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * @_C_: Custom code that gets inserted in the @type_name_get_type() function. - * - * A convenience macro for type implementations. - * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to - * insert custom code into the *_get_type() function, e.g. interface implementations - * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. + * GParameter: + * @name: the parameter name + * @value: the parameter value * - * Since: 2.4 + * The <structname>GParameter</structname> struct is an auxiliary structure used + * to hand parameter name/value pairs to g_object_newv(). */ /** - * g_tls_backend_supports_tls: - * @backend: the #GTlsBackend - * - * Checks if TLS is supported; if this returns %FALSE for the default - * #GTlsBackend, it means no "real" TLS backend is available. + * GPasswordSave: + * @G_PASSWORD_SAVE_NEVER: never save a password. + * @G_PASSWORD_SAVE_FOR_SESSION: save a password for the session. + * @G_PASSWORD_SAVE_PERMANENTLY: save a password permanently. * - * Returns: whether or not TLS is supported - * Since: 2.28 + * #GPasswordSave is used to indicate the lifespan of a saved password. + * #Gvfs stores passwords in the Gnome keyring when this flag allows it + * to, and later retrieves it again from there. */ /** - * g_unix_fd_message_new_with_fd_list: - * @fd_list: a #GUnixFDList - * - * Creates a new #GUnixFDMessage containing @list. + * GPermission: * - * Returns: a new #GUnixFDMessage - * Since: 2.24 + * #GPermission is an opaque data structure and can only be accessed + * using the following functions. */ /** - * GDBusConnection:flags: - * - * Flags from the #GDBusConnectionFlags enumeration. + * GPermission:allowed: * - * Since: 2.26 + * %TRUE if the caller currently has permission to perform the action that */ /** - * g_application_run: - * @application: a #GApplication - * @argc: the argc from main() - * @argv: (array length=argc): the argv from main() - * @returns: the exit status - * - * Runs the application. - * This function is intended to be run from main() and its return value - * is intended to be returned by main(). - * First, the local_command_line() virtual function is invoked. This - * function always runs on the local instance. If that function returns - * %FALSE then the application is registered and the #GApplication::command-line - * signal is emitted in the primary instance (which may or may not be - * this instance). - * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE - * flag set then the default implementation of local_command_line() - * always returns %FALSE immediately, resulting in the commandline - * always being handled in the primary instance. - * Otherwise, the default implementation of local_command_line() tries - * to do a couple of things that are probably reasonable for most - * applications. First, g_application_register() is called to attempt - * to register the application. If that works, then the command line - * arguments are inspected. If no commandline arguments are given, then - * g_application_activate() is called. If commandline arguments are - * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they - * are assumed to be filenames and g_application_open() is called. - * If you are interested in doing more complicated local handling of the - * commandline then you should implement your own #GApplication subclass - * and override local_command_line(). See - * <xref linkend="gapplication-example-cmdline2"/> for an example. - * If, after the above is done, the use count of the application is zero - * then the exit status is returned immediately. If the use count is - * non-zero then the mainloop is run until the use count falls to zero, - * at which point 0 is returned. - * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at - * around to provide its <emphasis>service</emphasis> to others). + * GPermission:can-acquire: * - * Use count of zero is delayed for a while (ie: the instance stays - * Since: 2.28 + * %TRUE if it is generally possible to acquire the permission by calling + * g_permission_acquire(). */ /** - * g_socket_service_new: - * - * Creates a new #GSocketService with no sockets to listen for. - * New listeners can be added with e.g. g_socket_listener_add_address() - * or g_socket_listener_add_inet_port(). + * GPermission:can-release: * - * Returns: a new #GSocketService. - * Since: 2.22 + * %TRUE if it is generally possible to release the permission by calling + * g_permission_release(). */ /** - * G_VALUE_HOLDS_GTYPE: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. + * GPid: * - * Since: 2.12 - * Returns: %TRUE on success. + * A type which is used to hold a process identification. + * On UNIX, processes are identified by a process id (an integer), + * while Windows uses process handles (which are pointers). */ /** - * g_unix_connection_receive_fd: - * @connection: a #GUnixConnection - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: (allow-none): #GError for error reporting, or %NULL to ignore + * GPollFD: + * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32) + * @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR. + * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred. * - * Receives a file descriptor from the sending end of the connection. - * The sending end has to call g_unix_connection_send_fd() for this - * to work. - * As well as reading the fd this also reads a single byte from the - * stream, as this is required for fd passing to work on some - * implementations. * - * Returns: a file descriptor on success, -1 on error. - * Since: 2.22 */ /** - * GMountOperation::show-processes: - * @op: a #GMountOperation. - * @message: string containing a message to display to the user. - * @processes: an array of #GPid for processes blocking the operation. - * @choices: an array of strings for each possible choice. + * GPollFunc: + * @ufds: an array of #GPollFD elements + * @nfsd: the number of elements in @ufds + * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout. * - * Emitted when one or more processes are blocking an operation - * e.g. unmounting/ejecting a #GMount or stopping a #GDrive. - * Note that this signal may be emitted several times to update the - * list of blocking processes as processes close files. The - * application should only respond with g_mount_operation_reply() to - * the latest signal (setting #GMountOperation:choice to the choice - * the user made). - * If the message contains a line break, the first line should be - * presented as a heading. For example, it may be used as the - * primary text in a #GtkMessageDialog. + * Specifies the type of function passed to g_main_context_set_poll_func(). + * The semantics of the function should match those of the poll() system call. + * reported, or -1 if an error occurred. * - * Since: 2.22 + * Returns: the number of #GPollFD elements which have events or errors */ /** - * G_OBJECT_CLASS: - * @class: a valid #GObjectClass + * GPollableInputStream: * - * Casts a derived #GObjectClass structure into a #GObjectClass structure. + * An interface for a #GInputStream that can be polled for readability. + * + * Since: 2.28 */ /** - * g_simple_async_result_set_error: (skip) - * @simple: a #GSimpleAsyncResult. - * @domain: a #GQuark (usually #G_IO_ERROR). - * @code: an error code. - * @format: a formatted error reporting string. - * @...: a list of variables to fill in @format. + * GPollableInputStreamInterface: + * @g_iface: The parent interface. + * @can_poll: Checks if the #GPollableInputStream instance is actually pollable + * @is_readable: Checks if the stream is readable + * @create_source: Creates a #GSource to poll the stream + * @read_nonblocking: Does a non-blocking read or returns %G_IO_ERROR_WOULD_BLOCK * - * Sets an error within the asynchronous result without a #GError. + * The interface for pollable input streams. + * The default implementation of @can_poll always returns %TRUE. + * The default implementation of @read_nonblocking calls + * g_pollable_input_stream_is_readable(), and then calls + * g_input_stream_read() if it returns %TRUE. This means you only need + * to override it if it is possible that your @is_readable + * implementation may return %TRUE when the stream is not actually + * readable. + * + * Since: 2.28 */ /** - * GBindingFlags: - * @G_BINDING_DEFAULT: The default binding; if the source property changes, the target property is updated with its value. - * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. - * @G_BINDING_SYNC_CREATE: Synchronize the values of the source and target properties when creating the binding; the direction of the synchronization is always from the source to the target. - * @G_BINDING_INVERT_BOOLEAN: If the two properties being bound are booleans, setting one to %TRUE will result in the other being set to %FALSE and vice versa. This flag will only work for boolean properties, and cannot be used when passing custom transformation functions to g_object_bind_property_full(). + * GPollableOutputStream: * - * Flags to be passed to g_object_bind_property() or - * g_object_bind_property_full(). - * This enumeration can be extended at later date. + * An interface for a #GOutputStream that can be polled for readability. * - * Since: 2.26 + * Since: 2.28 */ /** - * G_CLOSURE_N_NOTIFIERS: - * @cl: a #GClosure + * GPollableOutputStreamInterface: + * @g_iface: The parent interface. + * @can_poll: Checks if the #GPollableOutputStream instance is actually pollable + * @is_writable: Checks if the stream is writable + * @create_source: Creates a #GSource to poll the stream + * @write_nonblocking: Does a non-blocking write or returns %G_IO_ERROR_WOULD_BLOCK * - * Get the total number of notifiers connected with the closure @cl. - * The count includes the meta marshaller, the finalize and invalidate notifiers - * and the marshal guards. Note that each guard counts as two notifiers. - * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), - * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). + * The interface for pollable output streams. + * The default implementation of @can_poll always returns %TRUE. + * The default implementation of @write_nonblocking calls + * g_pollable_output_stream_is_writable(), and then calls + * g_output_stream_write() if it returns %TRUE. This means you only + * need to override it if it is possible that your @is_writable + * implementation may return %TRUE when the stream is not actually + * writable. * - * Returns: number of notifiers + * Since: 2.28 */ /** - * g_file_info_remove_attribute: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * GPollableSourceFunc: + * @pollable_stream: the #GPollableInputStream or #GPollableOutputStream + * @user_data: data passed in by the user. * - * Removes all cases of @attribute from @info if it exists. + * This is the function type of the callback used for the #GSource + * returned by g_pollable_input_stream_create_source() and + * g_pollable_output_stream_create_source(). + * + * Returns: it should return %FALSE if the source should be removed. + * Since: 2.28 */ /** - * g_tcp_wrapper_connection_get_base_io_stream: - * @conn: a #GTcpWrapperConnection + * GProxy: * - * Get's @conn's base #GIOStream + * Interface that handles proxy connection and payload. * - * Returns: (transfer none): @conn's base #GIOStream + * Since: 2.26 */ /** - * G_IS_PARAM_SPEC_GTYPE: - * @pspec: a #GParamSpec + * GProxyAddress: * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. + * A #GInetSocketAddress representing a connection via a proxy server * - * Since: 2.10 - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * g_unix_input_stream_get_fd: - * @stream: a #GUnixInputStream - * - * Return the UNIX file descriptor that the stream reads from. + * GProxyAddressEnumerator: * - * Returns: The file descriptor of @stream - * Since: 2.20 + * A subclass of #GSocketAddressEnumerator that takes another address + * enumerator and wraps its results in #GProxyAddress<!-- -->es as + * directed by the default #GProxyResolver. */ /** - * g_dbus_connection_add_filter: - * @connection: A #GDBusConnection. - * @filter_function: A filter function. - * @user_data: User data to pass to @filter_function. - * @user_data_free_func: Function to free @user_data with when filter is removed or %NULL. + * GProxyInterface: + * @g_iface: The parent interface. + * @connect: Connect to proxy server and wrap (if required) the #connection to handle payload. + * @connect_async: Same has connect() but asynchronous. + * @connect_finish: Returns the result of connect_async() * - * Adds a message filter. Filters are handlers that are run on all - * incoming and outgoing messages, prior to standard dispatch. Filters - * are run in the order that they were added. The same handler can be - * added as a filter more than once, in which case it will be run more - * than once. Filters added during a filter callback won't be run on - * the message being processed. Filter functions are allowed to modify - * and even drop messages - see the #GDBusMessageFilterResult - * enumeration for details. - * Note that filters are run in a dedicated message handling thread so - * they can't block and, generally, can't do anything but signal a - * worker thread. Also note that filters are rarely needed - use API - * such as g_dbus_connection_send_message_with_reply(), - * g_dbus_connection_signal_subscribe() or - * g_dbus_connection_call() instead. - * If a filter consumes an incoming message the message is not - * dispatched anywhere else - not even the standard dispatch machinery - * (that API such as g_dbus_connection_signal_subscribe() and - * g_dbus_connection_send_message_with_reply() relies on) will see the - * message. Similary, if a filter consumes an outgoing message, the - * message will not be sent to the other peer. - * g_dbus_connection_remove_filter(). + * Provides an interface for handling proxy connection and payload. * - * Returns: A filter identifier that can be used with * Since: 2.26 */ /** - * GAppInfo: + * GProxyResolver: * - * Information about an installed application and methods to launch - * it (with file arguments). + * Interface that can be used to resolve proxy address. */ /** - * g_dbus_method_invocation_return_dbus_error: - * @invocation: A #GDBusMethodInvocation. - * @error_name: A valid D-Bus error name. - * @error_message: A valid D-Bus error message. + * GReallocFunc: + * @data: memory block to reallocate + * @size: size to reallocate @data to * - * Finishes handling a D-Bus method call by returning an error. - * This method will free @invocation, you cannot use it afterwards. + * Changes the size of the memory block pointed to by @data to + * The function should have the same semantics as realloc(). * - * Since: 2.26 + * Returns: a pointer to the reallocated memory */ /** - * g_file_info_get_attribute_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * GRegex: * - * Gets the value of a string attribute. If the attribute does - * not contain a string, %NULL will be returned. - * %NULL otherwise. + * A GRegex is the "compiled" form of a regular expression pattern. This + * structure is opaque and its fields cannot be accessed directly. * - * Returns: the contents of the @attribute value as a string, or + * Since: 2.14 */ /** - * g_content_type_equals: - * @type1: a content type string - * @type2: a content type string + * GRegexCompileFlags: + * @G_REGEX_CASELESS: Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting. + * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting. + * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting. + * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting. + * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. + * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set. + * @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern. + * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. + * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way). + * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches. + * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched. + * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'. + * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'. + * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'. * - * Compares two content types for equality. - * %FALSE otherwise. + * Flags specifying compile-time options. * - * Returns: %TRUE if the two strings are identical or equivalent, + * Since: 2.14 */ /** - * g_file_info_set_size: - * @info: a #GFileInfo. - * @size: a #goffset containing the file's size. + * GRegexError: + * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed. + * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed. + * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string. + * @G_REGEX_ERROR_MATCH: The match process failed. + * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16 + * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16 + * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16 + * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16 + * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16 + * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16 + * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16 + * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16 + * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16 + * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16 + * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16 + * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16 + * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16 + * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16 + * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16 + * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16 + * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16 + * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16 + * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16 + * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16 + * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16 + * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16 + * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16 + * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16 + * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16 + * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16 + * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16 + * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16 + * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16 + * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16 + * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16 + * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16 + * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16 + * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16 + * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16 + * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16 + * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16 + * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16 * - * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info - * to the given size. + * Error codes returned by regular expressions functions. + * + * Since: 2.14 */ /** - * GApplication::startup: - * @application: the application + * GRegexEvalCallback: + * @match_info: the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string. + * @result: a #GString containing the new string + * @user_data: user data passed to g_regex_replace_eval() * - * The ::startup signal is emitted on the primary instance immediately - * after registration. See g_activation_register(). + * Specifies the type of the function passed to g_regex_replace_eval(). + * It is called for each occurance of the pattern in the string passed + * to g_regex_replace_eval(), and it should append the replacement to + * + * Returns: %FALSE to continue the replacement process, %TRUE to stop it + * Since: 2.14 */ /** - * GDBusConnectionFlags: - * @G_DBUS_CONNECTION_FLAGS_NONE: No flags set. - * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT: Perform authentication against server. - * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER: Perform authentication against client. - * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: When authenticating as a server, allow the anonymous authentication method. - * @G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION: Pass this flag if connecting to a peer that is a message bus. This means that the Hello() method will be invoked as part of the connection setup. - * @G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING: If set, processing of D-Bus messages is delayed until g_dbus_connection_start_message_processing() is called. + * GRegexMatchFlags: + * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. + * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A". + * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z". + * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b". + * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match(). + * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator. + * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator. + * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator. + * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized. * - * Flags used when creating a new #GDBusConnection. + * Flags specifying match-time options. * - * Since: 2.26 + * Since: 2.14 */ /** - * SECTION:gfileinf: - * @short_description: File Information and Attributes - * @include: gio/gio.h - * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link> + * GResolver: * - * Functionality for manipulating basic metadata for files. #GFileInfo - * implements methods for getting information that all files should - * contain, and allows for manipulation of extended attributes. - * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more - * information on how GIO handles file attributes. - * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its - * async variant). To obtain a #GFileInfo for a file input or output - * stream, use g_file_input_stream_query_info() or - * g_file_output_stream_query_info() (or their async variants). - * To change the actual attributes of a file, you should then set the - * attribute in the #GFileInfo and call g_file_set_attributes_from_info() - * or g_file_set_attributes_async() on a GFile. - * However, not all attributes can be changed in the file. For instance, - * the actual size of a file cannot be changed via g_file_info_set_size(). - * You may call g_file_query_settable_attributes() and - * g_file_query_writable_namespaces() to discover the settable attributes - * of a particular file at runtime. - * #GFileAttributeMatcher allows for searching through a #GFileInfo for - * attributes. + * The object that handles DNS resolution. Use g_resolver_get_default() + * to get the default resolver. */ /** - * g_socket_bind: - * @socket: a #GSocket. - * @address: a #GSocketAddress specifying the local address. - * @allow_reuse: whether to allow reusing this address - * @error: #GError for error reporting, or %NULL to ignore. - * - * When a socket is created it is attached to an address family, but it - * doesn't have an address in this family. g_socket_bind() assigns the - * address (sometimes called name) of the socket. - * It is generally required to bind to a local address before you can - * receive connections. (See g_socket_listen() and g_socket_accept() ). - * In certain situations, you may also want to bind a socket that will be - * used to initiate connections, though this is not normally required. - * eventually call g_socket_accept() on), and %FALSE for client sockets. - * (Specifically, if it is %TRUE, then g_socket_bind() will set the - * %SO_REUSEADDR flag on the socket, allowing it to bind @address even if - * that address was previously used by another socket that has not yet been - * fully cleaned-up by the kernel. Failing to set this flag on a server - * socket may cause the bind call to return %G_IO_ERROR_ADDRESS_IN_USE if - * the server program is stopped and then immediately restarted.) + * GResolver::reload: + * @resolver: a #GResolver * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 + * Emitted when the resolver notices that the system resolver + * configuration has changed. */ /** - * g_input_stream_read_all: - * @stream: a #GInputStream. - * @buffer: 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 - * @bytes_read: (out): location to store the number of bytes that was read from the stream - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occuring, or %NULL to ignore + * GResolverError: + * @G_RESOLVER_ERROR_NOT_FOUND: the requested name/address/service was not found + * @G_RESOLVER_ERROR_TEMPORARY_FAILURE: the requested information could not be looked up due to a network error or similar problem + * @G_RESOLVER_ERROR_INTERNAL: unknown error * - * Tries to read @count bytes from the stream into the buffer starting at - * This function is similar to g_input_stream_read(), except it tries to - * read as many bytes as requested, only stopping on an error or end of stream. - * On a successful read of @count bytes, or if we reached the end of the - * stream, %TRUE is returned, and @bytes_read is set to the number of bytes - * read into @buffer. - * If there is an error during the operation %FALSE is returned and @error - * is set to indicate the error status, @bytes_read is updated to contain - * the number of bytes read into @buffer before the error occurred. + * An error code used with %G_RESOLVER_ERROR in a #GError returned + * from a #GResolver routine. * - * Returns: %TRUE on success, %FALSE if there was an error + * Since: 2.22 */ /** - * G_VFS_EXTENSION_POINT_NAME: + * GSeekable: * - * Extension point for #GVfs functionality. - * See <link linkend="extending-gio">Extending GIO</link>. + * Seek object for streaming operations. */ /** - * GParamSpecTypeInfo: - * @instance_size: Size of the instance (object) structure. - * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. - * @instance_init: Location of the instance initialization function (optional). - * @value_type: The #GType of values conforming to this #GParamSpec - * @finalize: The instance finalization function (optional). - * @value_set_default: Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default(). - * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_set_validate(). - * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp(). + * GSeekableIface: + * @g_iface: The parent interface. + * @tell: Tells the current location within a stream. + * @can_seek: Checks if seeking is supported by the stream. + * @seek: Seeks to a location within a stream. + * @can_truncate: Chekcs if truncation is suppored by the stream. + * @truncate_fn: Truncates a stream. * - * This structure is used to provide the type system with the information - * required to initialize and destruct (finalize) a parameter's class and - * instances thereof. - * The initialized structure is passed to the g_param_type_register_static() - * The type system will perform a deep copy of this structure, so its memory - * does not need to be persistent across invocation of - * g_param_type_register_static(). + * Provides an interface for implementing seekable functionality on I/O Streams. */ /** - * G_TYPE_IS_VALUE_ABSTRACT: - * @type: A #GType value. + * GSettings::change-event: + * @settings: the object on which the signal was emitted + * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL + * @n_keys: the length of the @keys array, or 0 + * @returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. * - * Checks if @type is an abstract value type. An abstract value type introduces - * a value table, but can't be used for g_value_init() and is normally used as - * an abstract base type for derived value types. + * The "change-event" signal is emitted once per change event that + * affects this settings object. You should connect to this signal + * only if you are interested in viewing groups of changes before they + * are split out into multiple emissions of the "changed" signal. + * For most use cases it is more appropriate to use the "changed" signal. + * In the event that the change event applies to one or more specified + * keys, @keys will be an array of #GQuark of length @n_keys. In the + * event that the change event applies to the #GSettings object as a + * be %NULL and @n_keys will be 0. + * The default handler for this signal invokes the "changed" signal + * for each affected key. If any other connected handler returns + * %TRUE then this default functionality will be supressed. * - * Returns: %TRUE on success. + * Whole (ie: potentially every key has been changed) then @keys will */ /** - * g_cancellable_pop_current: - * @cancellable: a #GCancellable object + * GSettings::changed: + * @settings: the object on which the signal was emitted + * @key: the name of the key that changed * - * Pops @cancellable off the cancellable stack (verifying that @cancellable - * is on the top of the stack). + * The "changed" signal is emitted when a key has potentially changed. + * You should call one of the g_settings_get() calls to check the new + * value. + * This signal supports detailed connections. You can connect to the + * detailed signal "changed::x" in order to only receive callbacks + * when key "x" changes. */ /** - * SECTION:gthemedico: - * @short_description: Icon theming support - * @include: gio/gio.h - * @see_also: #GIcon, #GLoadableIcon + * GSettings::writable-change-event: + * @settings: the object on which the signal was emitted + * @key: the quark of the key, or 0 + * @returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. * - * #GThemedIcon is an implementation of #GIcon that supports icon themes. - * #GThemedIcon contains a list of all of the icons present in an icon - * theme, so that icons can be looked up quickly. #GThemedIcon does - * not provide actual pixmaps for icons, just the icon names. - * Ideally something like gtk_icon_theme_choose_icon() should be used to - * resolve the list of names so that fallback icons work nicely with - * themes that inherit other themes. + * The "writable-change-event" signal is emitted once per writability + * change event that affects this settings object. You should connect + * to this signal if you are interested in viewing groups of changes + * before they are split out into multiple emissions of the + * "writable-changed" signal. For most use cases it is more + * appropriate to use the "writable-changed" signal. + * In the event that the writability change applies only to a single + * key, @key will be set to the #GQuark for that key. In the event + * that the writability change affects the entire settings object, + * The default handler for this signal invokes the "writable-changed" + * and "changed" signals for each affected key. This is done because + * changes in writability might also imply changes in value (if for + * example, a new mandatory setting is introduced). If any other + * connected handler returns %TRUE then this default functionality + * will be supressed. */ /** - * G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN: + * GSettings::writable-changed: + * @settings: the object on which the signal was emitted + * @key: the key * - * A key in the "standard" namespace for checking if a file is hidden. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * The "writable-changed" signal is emitted when the writability of a + * key has potentially changed. You should call + * g_settings_is_writable() in order to determine the new status. + * This signal supports detailed connections. You can connect to the + * detailed signal "writable-changed::x" in order to only receive + * callbacks when the writability of "x" changes. */ /** - * GMountUnmountFlags: - * @G_MOUNT_UNMOUNT_NONE: No flags set. - * @G_MOUNT_UNMOUNT_FORCE: Unmount even if there are outstanding file operations on the mount. + * GSettings:context: * - * Flags used when an unmounting a mount. + * The name of the context that the settings are stored in. */ /** - * GAsyncInitableIface: - * @g_iface: The parent interface. - * @init_async: Starts initialization of the object. - * @init_finish: Finishes initialization of the object. + * GSettings:delay-apply: * - * Provides an interface for asynchronous initializing object such that - * initialization may fail. + * Whether the #GSettings object is in 'delay-apply' mode. See + * g_settings_delay() for details. * - * Since: 2.22 + * Since: 2.28 */ /** - * G_VALUE_HOLDS_UINT64: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. + * GSettings:has-unapplied: * - * Returns: %TRUE on success. + * If this property is %TRUE, the #GSettings object has outstanding + * changes that will be applied when g_settings_apply() is called. */ /** - * g_file_info_list_attributes: - * @info: a #GFileInfo. - * @name_space: a file attribute key's namespace. - * - * Lists the file info structure's attributes. - * possible attribute types for the given @name_space, or - * %NULL on error. + * GSettings:path: * - * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the + * The path within the backend where the settings are stored. */ /** - * GActionGroup::action-enabled-changed: - * @action_group: the #GActionGroup that changed - * @action_name: the name of the action in @action_group - * @enabled: whether the action is enabled or not - * - * Signals that the enabled status of the named action has changed. + * GSettings:schema: * - * Since: 2.28 + * The name of the schema that describes the types of keys + * for this #GSettings object. */ /** - * g_dbus_connection_new_sync: - * @stream: A #GIOStream. - * @guid: The GUID to use if a authenticating as a server or %NULL. - * @flags: Flags describing how to make the connection. - * @observer: A #GDBusAuthObserver or %NULL. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Synchronously sets up a D-Bus connection for exchanging D-Bus messages - * with the end represented by @stream. - * If @observer is not %NULL it may be used to control the - * authentication process. - * This is a synchronous failable constructor. See - * g_dbus_connection_new() for the asynchronous version. + * GSettingsBackend: * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). - * Since: 2.26 + * An implementation of a settings storage repository. */ /** - * GSocketListenerClass: - * @changed: virtual method called when the set of socket listened to changes - * + * GSettingsBindFlags: + * @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal> + * @G_SETTINGS_BIND_GET: Update the #GObject property when the setting changes. It is an error to use this flag if the property is not writable. + * @G_SETTINGS_BIND_SET: Update the setting when the #GObject property changes. It is an error to use this flag if the property is not readable. + * @G_SETTINGS_BIND_NO_SENSITIVITY: Do not try to bind a "sensitivity" property to the writability of the setting + * @G_SETTINGS_BIND_GET_NO_CHANGES: When set in addition to #G_SETTINGS_BIND_GET, set the #GObject property value initially from the setting, but do not listen for changes of the setting + * @G_SETTINGS_BIND_INVERT_BOOLEAN: When passed to g_settings_bind(), uses a pair of mapping functions that invert the boolean value when mapping between the setting and the property. The setting and property must both be booleans. You can not pass this flag to g_settings_bind_with_mapping(). * + * Flags used when creating a binding. These flags determine in which + * direction the binding works. The default is to synchronize in both + * directions. */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE: + * GSettingsBindGetMapping: + * @value: return location for the property value + * @variant: the #GVariant + * @user_data: user data that was specified when the binding was created + * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error * - * A key in the "mountable" namespace for getting the unix device. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * The type for the function that is used to convert from #GSettings to + * an object property. The @value is already initialized to hold values + * of the appropriate type. */ /** - * GTypeModuleClass: - * @parent_class: the parent class - * @load: loads the module and registers one or more types using g_type_module_register_type(). - * @unload: unloads the module + * GSettingsBindSetMapping: + * @value: a #GValue containing the property value to map + * @expected_type: the #GVariantType to create + * @user_data: user data that was specified when the binding was created + * @returns: a new #GVariant holding the data from @value, or %NULL in case of an error * - * In order to implement dynamic loading of types based on #GTypeModule, - * the @load and @unload functions in #GTypeModuleClass must be implemented. + * The type for the function that is used to convert an object property + * value to a #GVariant for storing it in #GSettings. */ /** - * SECTION:gbufferedinputstrea: - * @short_description: Buffered Input Stream - * @include: gio/gio.h - * @see_also: #GFilterInputStream, #GInputStream + * GSettingsGetMapping: + * @value: the #GVariant to map, or %NULL + * @result: (out): the result of the mapping + * @user_data: (closure): the user data that was passed to g_settings_get_mapped() + * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error * - * Buffered input stream implements #GFilterInputStream and provides - * for buffered reads. - * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes. - * To create a buffered input stream, use g_buffered_input_stream_new(), - * or g_buffered_input_stream_new_sized() to specify the buffer's size at - * construction. - * To get the size of a buffer within a buffered input stream, use - * g_buffered_input_stream_get_buffer_size(). To change the size of a - * buffered input stream's buffer, use - * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size - * cannot be reduced below the size of the data within the buffer. + * The type of the function that is used to convert from a value stored + * in a #GSettings to a value that is useful to the application. + * If the value is successfully mapped, the result should be stored at + * is not in the right format) then %FALSE should be returned. + * If @value is %NULL then it means that the mapping function is being + * given a "last chance" to successfully return a valid value. %TRUE + * must be returned in this case. */ /** - * g_proxy_connect_async: - * @proxy: a #GProxy - * @connection: a #GIOStream - * @proxy_address: a #GProxyAddress - * @cancellable: (allow-none): a #GCancellable - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): callback data + * GSignalAccumulator: + * @ihint: Signal invocation hint, see #GSignalInvocationHint. + * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission. + * @handler_return: A #GValue holding the return value of the signal handler. + * @data: Callback data that was specified when creating the signal. * - * Asynchronous version of g_proxy_connect(). + * The signal accumulator is a special callback function that can be used + * to collect return values of the various callbacks that are called + * during a signal emission. The signal accumulator is specified at signal + * creation time, if it is left %NULL, no accumulation of callback return + * values is performed. The return value of signal emissions is then the + * value returned by the last callback. + * should be aborted. Returning %FALSE means to abort the + * current emission and %TRUE is returned for continuation. * - * Since: 2.26 + * Returns: The accumulator function returns whether the signal emission */ /** - * GSettings:delay-apply: - * - * Whether the #GSettings object is in 'delay-apply' mode. See - * g_settings_delay() for details. + * GSignalCMarshaller: * - * Since: 2.28 + * This is the signature of marshaller functions, required to marshall + * arrays of parameter values to signal emissions into C language callback + * invocations. It is merely an alias to #GClosureMarshal since the #GClosure + * mechanism takes over responsibility of actual function invocation for the + * signal system. */ /** - * g_resolver_lookup_service: - * @resolver: a #GResolver - * @service: the service type to look up (eg, "ldap") - * @protocol: the networking protocol to use for @service (eg, "tcp") - * @domain: the DNS domain to look up the service in - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL + * GSignalEmissionHook: + * @ihint: Signal invocation hint, see #GSignalInvocationHint. + * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted. + * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission. + * @data: user data associated with the hook. * - * Synchronously performs a DNS SRV lookup for the given @service and - * include the leading underscore that appears in the actual DNS - * entry. - * On success, g_resolver_lookup_service() will return a #GList of - * #GSrvTarget, sorted in order of preference. (That is, you should - * attempt to connect to the first target first, then the second if - * the first fails, etc.) - * If the DNS resolution fails, @error (if non-%NULL) will be set to - * a value from #GResolverError. - * If @cancellable is non-%NULL, it can be used to cancel the - * operation, in which case @error (if non-%NULL) will be set to - * %G_IO_ERROR_CANCELLED. - * If you are planning to connect to the service, it is usually easier - * to create a #GNetworkService and use its #GSocketConnectable - * interface. - * or %NULL on error. You must free each of the targets and the list when you are - * done with it. (You can use g_resolver_free_targets() to do this.) + * A simple function pointer to get invoked when the signal is emitted. This + * allows you to tie a hook to the signal type, so that it will trap all + * emissions of that signal, from any object. + * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. + * hook is disconnected (and destroyed). * - * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, - * Since: 2.22 + * Returns: whether it wants to stay connected. If it returns %FALSE, the signal */ /** - * g_file_create: - * @file: input #GFile. - * @flags: a set of #GFileCreateFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL - * - * Creates a new file and returns an output stream for writing to it. - * The file must not already exist. - * By default files created are generally readable by everyone, - * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file - * will be made readable only to the current user, to the level that - * is supported on the target filesystem. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If a file or directory with this name already exists the G_IO_ERROR_EXISTS - * error will be returned. - * Some file systems don't allow all file names, and may - * return an G_IO_ERROR_INVALID_FILENAME error, and if the name - * is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned. - * Other errors are possible too, and depend on what kind of - * filesystem the file is on. - * %NULL on error. - * Free the returned object with g_object_unref(). + * GSignalFlags: + * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage. + * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage. + * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage. + * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted. + * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions. + * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code. + * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. * - * Returns: (transfer full): a #GFileOutputStream for the newly created file, or + * The signal flags are used to specify a signal's behaviour, the overall + * signal description outlines how especially the RUN flags control the + * stages of a signal emission. */ /** - * g_buffered_input_stream_fill: - * @stream: a #GBufferedInputStream - * @count: the number of bytes that will be read from the stream - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: location to store the error occuring, or %NULL to ignore - * - * Tries to read @count bytes from the stream into the buffer. - * Will block during this read. - * If @count is zero, returns zero and does nothing. A value of @count - * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * On success, the number of bytes read into the buffer is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. near the end of a file. Zero is returned on end of file - * (or if @count is zero), but never otherwise. - * If @count is -1 then the attempted read size is equal to the number of - * bytes that are required to fill the buffer. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * On error -1 is returned and @error is set accordingly. - * For the asynchronous, non-blocking, version of this function, see - * g_buffered_input_stream_fill_async(). - * or -1 on error. + * GSignalInvocationHint: + * @signal_id: The signal id of the signal invoking the callback + * @detail: The detail passed on for this emission + * @run_type: The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. * - * Returns: the number of bytes read into @stream's buffer, up to @count, + * The #GSignalInvocationHint structure is used to pass on additional information + * to callbacks during a signal emission. */ /** - * GDBusInterfaceVTable: - * @method_call: Function for handling incoming method calls. - * @get_property: Function for getting a property. - * @set_property: Function for setting a property. - * - * Virtual table for handling properties and method calls for a D-Bus - * interface. - * If you want to handle getting/setting D-Bus properties asynchronously, simply - * register an object with the <literal>org.freedesktop.DBus.Properties</literal> - * D-Bus interface using g_dbus_connection_register_object(). + * GSignalMatchType: + * @G_SIGNAL_MATCH_ID: The signal id must be equal. + * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal. + * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same. + * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same. + * @G_SIGNAL_MATCH_DATA: The closure data must be the same. + * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched. * - * Since: 2.26 + * The match types specify what g_signal_handlers_block_matched(), + * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() + * match signals by. */ /** - * g_settings_backend_writable_changed: - * @backend: a #GSettingsBackend implementation - * @key: the name of the key - * - * Signals that the writability of a single key has possibly changed. - * Since GSettings performs no locking operations for itself, this call - * will always be made in response to external events. + * GSignalQuery: + * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown. + * @signal_name: The signal name. + * @itype: The interface/instance type that this signal can be emitted for. + * @signal_flags: The signal flags as passed in to g_signal_new(). + * @return_type: The return type for user callbacks. + * @n_params: The number of parameters that user callbacks take. + * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting> * - * Since: 2.26 + * A structure holding in-depth information for a specific signal. It is + * filled in by the g_signal_query() function. */ /** - * g_dbus_proxy_new: - * @connection: A #GDBusConnection. - * @flags: Flags used when constructing the proxy. - * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - * @name: A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. - * @object_path: An object path. - * @interface_name: A D-Bus interface name. - * @cancellable: A #GCancellable or %NULL. - * @callback: Callback function to invoke when the proxy is ready. - * @user_data: User data to pass to @callback. + * GSimpleAction: * - * Creates a proxy for accessing @interface_name on the remote object - * at @object_path owned by @name at @connection and asynchronously - * loads D-Bus properties unless the - * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to - * the #GDBusProxy::g-properties-changed signal to get notified about - * property changes. - * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up - * match rules for signals. Connect to the #GDBusProxy::g-signal signal - * to handle signals from the remote object. - * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name - * owner currently exists, the message bus will be requested to launch - * a name owner for the name. - * This is a failable asynchronous constructor - when the proxy is - * ready, @callback will be invoked and you can use - * g_dbus_proxy_new_finish() to get the result. - * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. - * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. + * The <structname>GSimpleAction</structname> structure contains private + * data and should only be accessed using the provided API * * Since: 2.26 */ /** - * g_unix_mount_point_free: - * @mount_point: unix mount point to free. + * GSimpleAction::activate: + * @simple: the #GSimpleAction + * @parameter: (allow-none): the parameter to the activation * - * Frees a unix mount point. + * Indicates that the action was just activated. + * an incorrect type was given, no signal will be emitted. + * + * Since: 2.28 */ /** - * GInetSocketAddress: + * GSimpleAction:enabled: * - * An IPv4 or IPv6 socket address, corresponding to a <type>struct - * sockaddr_in</type> or <type>struct sockaddr_in6</type>. + * If @action is currently enabled. + * If the action is disabled then calls to g_simple_action_activate() and + * g_simple_action_set_state() have no effect. + * + * Since: 2.28 */ /** - * g_dbus_error_set_dbus_error_valist: - * @error: A pointer to a #GError or %NULL. - * @dbus_error_name: D-Bus error name. - * @dbus_error_message: D-Bus error message. - * @format: printf()-style format to prepend to @dbus_error_message or %NULL. - * @var_args: Arguments for @format. + * GSimpleAction:name: * - * Like g_dbus_error_set_dbus_error() but intended for language bindings. + * The name of the action. This is mostly meaningful for identifying + * the action once it has been added to a #GSimpleActionGroup. * - * Since: 2.26 + * Since: 2.28 */ /** - * g_pollable_input_stream_can_poll: - * @stream: a #GPollableInputStream. + * GSimpleAction:parameter-type: * - * Checks if @stream is actually pollable. Some classes may implement - * #GPollableInputStream but have only certain instances of that class - * be pollable. If this method returns %FALSE, then the behavior of - * other #GPollableInputStream methods is undefined. - * For any given stream, the value returned by this method is constant; - * a stream cannot switch from pollable to non-pollable or vice versa. + * The type of the parameter that must be given when activating the + * action. * - * Returns: %TRUE if @stream is pollable, %FALSE if not. * Since: 2.28 */ /** - * GDBusSignalFlags: - * @G_DBUS_SIGNAL_FLAGS_NONE: No flags set. - * @G_DBUS_SIGNAL_FLAGS_NO_MATCH_RULE: Don't actually send the AddMatch DBus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). + * GSimpleAction:state: * - * Flags used when subscribing to signals via g_dbus_connection_signal_subscribe(). + * The state of the action, or %NULL if the action is stateless. * - * Since: 2.26 + * Since: 2.28 */ /** - * g_drive_start: - * @drive: a #GDrive. - * @flags: flags affecting the start operation. - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback + * GSimpleAction:state-type: * - * Asynchronously starts a drive. - * When the operation is finished, @callback will be called. - * You can then call g_drive_start_finish() to obtain the - * result of the operation. + * The #GVariantType of the state that the action has, or %NULL if the + * action is stateless. * - * Since: 2.22 + * Since: 2.28 */ /** - * g_unix_credentials_message_new_with_credentials: - * @credentials: A #GCredentials object. + * GSimpleActionClass: + * @activate: the class closure for the activate signal + * * - * Creates a new #GUnixCredentialsMessage holding @credentials. * - * Returns: a new #GUnixCredentialsMessage * Since: 2.26 */ /** - * g_file_create_readwrite: - * @file: a #GFile - * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: return location for a #GError, or %NULL + * GSimpleActionGroup: * - * Creates a new file and returns a stream for reading and writing to it. - * The file must not already exist. - * By default files created are generally readable by everyone, - * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file - * will be made readable only to the current user, to the level that - * is supported on the target filesystem. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If a file or directory with this name already exists the %G_IO_ERROR_EXISTS - * error will be returned. Some file systems don't allow all file names, - * and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name - * is too long, %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors - * are possible too, and depend on what kind of filesystem the file is on. - * Note that in many non-local file cases read and write streams are not - * supported, so make sure you really need to do read and write streaming, - * rather than just opening for reading or writing. - * Free the returned object with g_object_unref(). + * The #GSimpleActionGroup structure contains private data and should only be accessed using the provided API. * - * Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error. - * Since: 2.22 + * Since: 2.26 */ /** - * G_PARAM_SPEC_VALUE_ARRAY: - * @pspec: a valid #GParamSpec instance + * GSimpleAsyncResult: * - * Cast a #GParamSpec instance into a #GParamSpecValueArray. + * A simple implementation of #GAsyncResult. */ /** - * g_dbus_message_set_member: - * @message: A #GDBusMessage. - * @value: The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. + * GSimpleAsyncThreadFunc: + * @res: a #GSimpleAsyncResult. + * @object: a #GObject. + * @cancellable: optional #GCancellable object, %NULL to ignore. * - * Since: 2.26 + * Simple thread function that runs an asynchronous operation and + * checks for cancellation. */ /** - * g_socket_receive_from: - * @socket: a #GSocket - * @address: a pointer to a #GSocketAddress pointer, or %NULL - * @buffer: a buffer to read data into (which should be at least @size bytes long). - * @size: the number of bytes you want to read from the socket - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Receive data (up to @size bytes) from a socket. - * If @address is non-%NULL then @address will be set equal to the - * source address of the received packet. - * See g_socket_receive() for additional information. + * GSimplePermission: * - * Returns: Number of bytes read, or -1 on error - * Since: 2.22 + * #GSimplePermission is an opaque data structure. There are no methods + * except for those defined by #GPermission. */ /** - * g_seekable_can_seek: - * @seekable: a #GSeekable. + * GSocket: * - * Tests if the stream supports the #GSeekableIface. + * A lowlevel network socket object. * - * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise. + * Since: 2.22 */ /** - * GCredentialsClass: + * GSocket:timeout: * - * Class structure for #GCredentials. + * The timeout in seconds on socket I/O * * Since: 2.26 */ /** - * GDBusMessageFilterFunction: - * @connection: (transfer none): A #GDBusConnection. - * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of. - * @incoming: %TRUE if it is a message received from the other peer, %FALSE if it is a message to be sent to the other peer. - * @user_data: User data passed when adding the filter. - * - * Signature for function used in g_dbus_connection_add_filter(). - * A filter function is passed a #GDBusMessage and expected to return - * a #GDBusMessage too. Passive filter functions that don't modify the - * message can simply return the @message object: - * |[ - * static GDBusMessage * - * passive_filter (GDBusConnection *connection - * GDBusMessage *message, - * gboolean incoming, - * gpointer user_data) - * { - * /<!-- -->* inspect @message *<!-- -->/ - * return message; - * } - * ]| - * Filter functions that wants to drop a message can simply return %NULL: - * |[ - * static GDBusMessage * - * drop_filter (GDBusConnection *connection - * GDBusMessage *message, - * gboolean incoming, - * gpointer user_data) - * { - * if (should_drop_message) - * { - * g_object_unref (message); - * message = NULL; - * } - * return message; - * } - * ]| - * Finally, a filter function may modify a message by copying it: - * |[ - * static GDBusMessage * - * modifying_filter (GDBusConnection *connection - * GDBusMessage *message, - * gboolean incoming, - * gpointer user_data) - * { - * GDBusMessage *copy; - * GError *error; - * error = NULL; - * copy = g_dbus_message_copy (message, &error); - * /<!-- -->* handle @error being is set *<!-- -->/ - * g_object_unref (message); - * /<!-- -->* modify @copy *<!-- -->/ - * return copy; - * } - * ]| - * If the returned #GDBusMessage is different from @message and cannot - * be sent on @connection (it could use features, such as file - * descriptors, not compatible with @connection), then a warning is - * logged to <emphasis>standard error</emphasis>. Applications can - * check this ahead of time using g_dbus_message_to_blob() passing a - * #GDBusCapabilityFlags value obtained from @connection. - * g_object_unref() or %NULL to drop the message. Passive filter - * functions can simply return the passed @message object. + * GSocketAddress: * - * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with - * Since: 2.26 + * A socket endpoint address, corresponding to <type>struct sockaddr</type> + * or one of its subtypes. */ /** - * g_unix_mount_get_fs_type: - * @mount_entry: a #GUnixMount. - * - * Gets the filesystem type for the unix mount. + * GSocketAddressEnumerator: * - * Returns: a string containing the file system type. + * Enumerator type for objects that contain or generate + * #GSocketAddress<!-- -->es. */ /** - * g_file_attribute_matcher_new: - * @attributes: an attribute string to match. + * GSocketClient: * - * Creates a new file attribute matcher, which matches attributes - * against a given string. #GFileAttributeMatcher<!-- -->s are reference - * counted structures, and are created with a reference count of 1. If - * the number of references falls to 0, the #GFileAttributeMatcher is - * automatically destroyed. - * The @attribute string should be formatted with specific keys separated - * from namespaces with a double colon. Several "namespace::key" strings may be - * concatenated with a single comma (e.g. "standard::type,standard::is-hidden"). - * The wildcard "*" may be used to match all keys and namespaces, or - * "namespace::*" will match all keys in a given namespace. - * Examples of strings to use: - * <table> - * <title>File Attribute Matcher strings and results</title> - * <tgroup cols='2' align='left'><thead> - * <row><entry> Matcher String </entry><entry> Matches </entry></row></thead> - * <tbody> - * <row><entry>"*"</entry><entry>matches all attributes.</entry></row> - * <row><entry>"standard::is-hidden"</entry><entry>matches only the key is-hidden in the standard namespace.</entry></row> - * <row><entry>"standard::type,unix::*"</entry><entry>matches the type key in the standard namespace and - * all keys in the unix namespace.</entry></row> - * </tbody></tgroup> - * </table> + * A helper class for network servers to listen for and accept connections. * - * Returns: a #GFileAttributeMatcher. + * Since: 2.22 */ /** - * GDBusMethodInvocation: + * GSocketConnectable: * - * The #GDBusMethodInvocation structure contains only private data and - * should only be accessed using the provided API. + * Interface for objects that contain or generate #GSocketAddress<!-- -->es. + */ + + +/** + * GSocketConnectableIface: + * @g_iface: The parent interface. + * @enumerate: Creates a #GSocketAddressEnumerator + * @proxy_enumerate: Creates a #GProxyAddressEnumerator * - * Since: 2.26 + * Provides an interface for returning a #GSocketAddressEnumerator + * and #GProxyAddressEnumerator */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE: + * GSocketConnection: * - * A key in the "mountable" namespace for getting the #GDriveStartStopType. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * A socket connection GIOStream object for connection-oriented sockets. * * Since: 2.22 */ /** - * GInetAddress: + * GSocketControlMessage: * - * An IPv4 or IPv6 internet address. + * Base class for socket-type specific control messages that can be sent and + * received over #GSocket. */ /** - * g_tls_connection_set_require_close_notify: - * @conn: a #GTlsConnection - * @require_close_notify: whether or not to require close notification + * GSocketControlMessageClass: + * @get_size: gets the size of the message. + * @get_level: gets the protocol of the message. + * @get_type: gets the protocol specific type of the message. + * @serialize: Writes out the message data. + * @deserialize: Tries to deserialize a message. * - * Sets whether or not @conn expects a proper TLS close notification - * before the connection is closed. If this is %TRUE (the default), - * then @conn will expect to receive a TLS close notification from its - * peer before the connection is closed, and will return a - * %G_TLS_ERROR_EOF error if the connection is closed without proper - * notification (since this may indicate a network error, or - * man-in-the-middle attack). - * In some protocols, the application will know whether or not the - * connection was closed cleanly based on application-level data - * (because the application-level data includes a length field, or is - * somehow self-delimiting); in this case, the close notify is - * redundant and sometimes omitted. (TLS 1.1 explicitly allows this; - * in TLS 1.0 it is technically an error, but often done anyway.) You - * can use g_tls_connection_set_require_close_notify() to tell @conn - * to allow an "unannounced" connection close, in which case the close - * will show up as a 0-length read, as in a non-TLS - * #GSocketConnection, and it is up to the application to check that - * the data has been fully received. - * Note that this only affects the behavior when the peer closes the - * connection; when the application calls g_io_stream_close() itself - * on @conn, this will send a close notification regardless of the - * setting of this property. If you explicitly want to do an unclean - * close, you can close @conn's #GTlsConnection:base-io-stream rather - * than closing @conn itself. * - * Since: 2.28 */ /** - * g_pollable_input_stream_is_readable: - * @stream: a #GPollableInputStream. + * GSocketFamily: + * @G_SOCKET_FAMILY_INVALID: no address family + * @G_SOCKET_FAMILY_IPV4: the IPv4 family + * @G_SOCKET_FAMILY_IPV6: the IPv6 family + * @G_SOCKET_FAMILY_UNIX: the UNIX domain family * - * Checks if @stream can be read. - * Note that some stream types may not be able to implement this 100% - * reliably, and it is possible that a call to g_input_stream_read() - * after this returns %TRUE would still block. To guarantee - * non-blocking behavior, you should always use - * g_pollable_input_stream_read_nonblocking(), which will return a - * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. - * has occurred on @stream, this will result in - * g_pollable_input_stream_is_readable() returning %TRUE, and the - * next attempt to read will return the error. + * The protocol family of a #GSocketAddress. (These values are + * identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX, + * if available.) * - * Returns: %TRUE if @stream is readable, %FALSE if not. If an error - * Since: 2.28 + * Since: 2.22 */ /** - * GDBusPropertyInfoFlags: - * @G_DBUS_PROPERTY_INFO_FLAGS_NONE: No flags set. - * @G_DBUS_PROPERTY_INFO_FLAGS_READABLE: Property is readable. - * @G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE: Property is writable. + * GSocketListenerClass: + * @changed: virtual method called when the set of socket listened to changes * - * Flags describing the access control of a D-Bus property. * - * Since: 2.26 */ /** - * g_node_next_sibling: - * @node: a #GNode + * GSocketMsgFlags: + * @G_SOCKET_MSG_NONE: No flags. + * @G_SOCKET_MSG_OOB: Request to send/receive out of band data. + * @G_SOCKET_MSG_PEEK: Read data from the socket without removing it from the queue. + * @G_SOCKET_MSG_DONTROUTE: Don't use a gateway to send out the packet, only send to hosts on directly connected networks. * - * Gets the next sibling of a #GNode. - * or %NULL + * Flags used in g_socket_receive_message() and g_socket_send_message(). + * The flags listed in the enum are some commonly available flags, but the + * values used for them are the same as on the platform, and any other flags + * are passed in/out as is. So to use a platform specific flag, just include + * the right system header and pass in the flag. * - * Returns: the next sibling of @node, or %NULL if @node is the last node + * Since: 2.22 */ /** - * GTlsServerConnection: + * GSocketProtocol: + * @G_SOCKET_PROTOCOL_UNKNOWN: The protocol type is unknown + * @G_SOCKET_PROTOCOL_DEFAULT: The default protocol for the family/type + * @G_SOCKET_PROTOCOL_TCP: TCP over IP + * @G_SOCKET_PROTOCOL_UDP: UDP over IP + * @G_SOCKET_PROTOCOL_SCTP: SCTP over IP * - * TLS server-side connection. This is the server-side implementation - * of a #GTlsConnection. + * A protocol identifier is specified when creating a #GSocket, which is a + * family/type specific identifier, where 0 means the default protocol for + * the particular family/type. + * This enum contains a set of commonly available and used protocols. You + * can also pass any other identifiers handled by the platform in order to + * use protocols not listed here. * - * Since: 2.28 + * Since: 2.22 */ /** - * G_PARAM_SPEC_ENUM: - * @pspec: a valid #GParamSpec instance + * GSocketService: * - * Cast a #GParamSpec instance into a #GParamSpecEnum. + * A helper class for handling accepting incomming connections in the + * glib mainloop. + * + * Since: 2.22 */ /** - * g_file_info_get_attribute_type: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * GSocketService::incoming: + * @service: the #GSocketService. + * @connection: a new #GSocketConnection object. + * @source_object: the source_object passed to g_socket_listener_add_address(). * - * Gets the attribute type for an attribute key. - * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. + * The ::incoming signal is emitted when a new incoming connection + * to @service needs to be handled. The handler must initiate the + * handling of @connection, but may not block; in essence, + * asynchronous operations must be used. * - * Returns: a #GFileAttributeType for the given @attribute, or + * Returns: %TRUE to stop other handlers from being called + * Since: 2.22 */ /** - * g_inet_socket_address_get_port: - * @address: a #GInetSocketAddress + * GSocketServiceClass: + * @incomming: signal emitted when new connections are accepted * - * Gets @address's port. * - * Returns: the port for @address - * Since: 2.22 */ /** - * g_dbus_message_get_destination: - * @message: A #GDBusMessage. + * GSocketSourceFunc: + * @socket: the #GSocket + * @condition: the current condition at the source fired. + * @user_data: data passed in by the user. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. + * This is the function type of the callback used for the #GSource + * returned by g_socket_create_source(). * - * Returns: The value. - * Since: 2.26 + * Returns: it should return %FALSE if the source should be removed. + * Since: 2.22 */ /** - * GTimeSpan: + * GSocketType: + * @G_SOCKET_TYPE_INVALID: Type unknown or wrong + * @G_SOCKET_TYPE_STREAM: Reliable connection-based byte streams (e.g. TCP). + * @G_SOCKET_TYPE_DATAGRAM: Connectionless, unreliable datagram passing. (e.g. UDP) + * @G_SOCKET_TYPE_SEQPACKET: Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP). * - * A value representing an interval of time, in microseconds. + * Flags used when creating a #GSocket. Some protocols may not implement + * all the socket types. * - * Since: 2.26 + * Since: 2.22 */ /** - * GDBusNodeInfo: - * @ref_count: The reference count or -1 if statically allocated. - * @path: The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details. - * @interfaces: A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces. - * @nodes: A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes. - * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. - * - * Information about nodes in a remote object hierarchy. + * GSource: * - * Since: 2.26 + * The <structname>GSource</structname> struct is an opaque data type + * representing an event source. */ /** - * G_TYPE_IS_OBJECT: - * @type: Type id to check - * - * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. + * GSourceCallbackFuncs: + * @ref: Called when a reference is added to the callback object + * @unref: Called when a reference to the callback object is dropped + * @get: Called to extract the callback function and data from the callback object. * - * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT. + * The <structname>GSourceCallbackFuncs</structname> struct contains + * functions for managing callback objects. */ /** - * g_settings_list_schemas: - * - * Gets a list of the #GSettings schemas installed on the system. The - * returned list is exactly the list of schemas for which you may call - * g_settings_new() without adverse effects. - * This function does not list the schemas that do not provide their own - * g_settings_new_with_path()). See - * g_settings_list_relocatable_schemas() for that. - * schemas that are available. The list must not be modified or - * freed. + * GSourceFuncs: + * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the + * @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here. + * @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source. + * @finalize: Called when the source is finalized. * - * Paths (ie: schemas for which you must use - * Returns: (element-type utf8) (transfer none): a list of #GSettings - * Since: 2.26 + * The <structname>GSourceFuncs</structname> struct contains a table of + * functions used to handle event sources in a generic manner. + * For idle sources, the prepare and check functions always return %TRUE + * to indicate that the source is always ready to be processed. The prepare + * function also returns a timeout value of 0 to ensure that the poll() call + * doesn't block (since that would be time wasted which could have been spent + * running the idle function). + * For timeout sources, the prepare and check functions both return %TRUE + * if the timeout interval has expired. The prepare function also returns + * a timeout value to ensure that the poll() call doesn't block too long + * and miss the next timeout. + * For file descriptor sources, the prepare function typically returns %FALSE, + * since it must wait until poll() has been called before it knows whether + * any events need to be processed. It sets the returned timeout to -1 to + * indicate that it doesn't mind how long the poll() call blocks. In the + * check function, it tests the results of the poll() call to see if the + * required condition has been met, and returns %TRUE if so. */ /** - * g_file_load_contents: - * @file: input #GFile. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @contents: (out) (transfer full): a location to place the contents of the file. - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed - * @error: a #GError, or %NULL + * GSrvTarget: * - * Loads the content of the file into memory. The data is always - * zero-terminated, but this is not included in the resultant @length. - * The returned @content should be freed with g_free() when no longer - * needed. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * %FALSE if there were errors. + * A single target host/port that a network service is running on. + */ + + +/** + * GStrv: * - * Returns: %TRUE if the @file's contents were successfully loaded. + * A C representable type name for #G_TYPE_STRV. */ /** - * g_inet_address_get_is_multicast: - * @address: a #GInetAddress + * GTcpConnection: * - * Tests whether @address is a multicast address. + * A #GSocketConnection for UNIX domain socket connections. * - * Returns: %TRUE if @address is a multicast address. * Since: 2.22 */ /** - * GDBusServer:flags: + * GTestLogFatalFunc: + * @log_domain: the log domain of the message + * @log_level: the log level of the message (including the fatal and recursion flags) + * @message: the message to process + * @user_data: user data, set in g_test_log_set_fatal_handler() * - * Flags from the #GDBusServerFlags enumeration. + * Specifies the prototype of fatal log handler functions. * - * Since: 2.26 + * Returns: %TRUE if the program should abort, %FALSE otherwise + * Since: 2.22 */ /** - * GConverterOutputStream: + * GThemedIcon: * - * An implementation of #GFilterOutputStream that allows data - * conversion. + * An implementation of #GIcon for themed icons. */ /** - * GSettings:schema: + * GThemedIcon:name: * - * The name of the schema that describes the types of keys - * for this #GSettings object. + * The icon name. */ /** - * G_TYPE_IS_VALUE_TYPE: - * @type: A #GType value. + * GThemedIcon:names: * - * Checks if @type is a value type and can be used with g_value_init(). + * A %NULL-terminated array of icon names. + */ + + +/** + * GThemedIcon:use-default-fallbacks: * - * Returns: %TRUE on success. + * Whether to use the default fallbacks found by shortening the icon name + * at '-' characters. If the "names" array has more than one element, + * ignores any past the first. + * For example, if the icon name was "gnome-dev-cdrom-audio", the array + * would become + * |[ + * { + * "gnome-dev-cdrom-audio", + * "gnome-dev-cdrom", + * "gnome-dev", + * "gnome", + * NULL + * }; + * ]| */ /** - * g_volume_monitor_get_volume_for_uuid: - * @volume_monitor: a #GVolumeMonitor. - * @uuid: the UUID to look for + * GThreadedSocketService: * - * Finds a #GVolume object by its UUID (see g_volume_get_uuid()) - * Free the returned object with g_object_unref(). + * A helper class for handling accepting incomming connections in the + * glib mainloop and handling them in a thread. * - * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. + * Since: 2.22 */ /** - * G_SIGNAL_FLAGS_MASK: + * GThreadedSocketService::run: + * @service: the #GThreadedSocketService. + * @connection: a new #GSocketConnection object. + * @source_object: the source_object passed to g_socket_listener_add_address(). * - * A mask for all #GSignalFlags bits. + * The ::run signal is emitted in a worker thread in response to an + * incoming connection. This thread is dedicated to handling + * not return until the connection is closed. + * + * Returns: %TRUE to stope further signal handlers from being called */ /** - * G_TYPE_DBUS_INTERFACE_INFO: + * GTimeSpan: * - * The #GType for a boxed type holding a #GDBusInterfaceInfo. + * A value representing an interval of time, in microseconds. * * Since: 2.26 */ /** - * g_settings_set_enum: - * @settings: a #GSettings object - * @key: a key, within @settings - * @value: an enumerated value - * @returns: %TRUE, if the set succeeds + * GTimeType: + * @G_TIME_TYPE_STANDARD: the time is in local standard time + * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time + * @G_TIME_TYPE_UNIVERSAL: the time is in UTC * - * Looks up the enumerated type nick for @value and writes it to @key, - * within @settings. - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or is not marked as an enumerated type, or for - * After performing the write, accessing @key directly with - * g_settings_get_string() will return the 'nick' associated with + * Disambiguates a given time in two ways. + * First, specifies if the given time is in universal or local time. + * Second, if the time is in local time, specifies if it is local + * standard time or local daylight time. This is important for the case + * where the same local time occurs twice (during daylight savings time + * transitions, for example). */ /** - * g_network_address_parse: - * @host_and_port: the hostname and optionally a port - * @default_port: the default port if not in @host_and_port - * @error: a pointer to a #GError, or %NULL + * GTlsAuthenticationMode: + * @G_TLS_AUTHENTICATION_NONE: client authentication not required + * @G_TLS_AUTHENTICATION_REQUESTED: client authentication is requested + * @G_TLS_AUTHENTICATION_REQUIRED: client authentication is required * - * Creates a new #GSocketConnectable for connecting to the given - * parsing @host_and_port fails. - * address, an IPv4 address, or a domain name (in which case a DNS - * lookup is performed). Quoting with [] is supported for all address - * types. A port override may be specified in the usual way with a - * colon. Ports may be given as decimal numbers or symbolic names (in - * which case an /etc/services lookup is performed). - * If no port is specified in @host_and_port then @default_port will be - * used as the port number to connect to. - * In general, @host_and_port is expected to be provided by the user - * (allowing them to give the hostname, and a port overide if necessary) - * and @default_port is expected to be provided by the application. + * The client authentication mode for a #GTlsServerConnection. * - * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error - * Since: 2.22 + * Since: 2.28 */ /** - * g_newa: - * @struct_type: Type of memory chunks to be allocated - * @n_structs: Number of chunks to be allocated + * GTlsBackend: * - * Wraps g_alloca() in a more typesafe manner. + * TLS (Transport Layer Security, aka SSL) backend. This is an + * internal type used to coordinate the different classes implemented + * by a TLS backend. * - * Returns: Pointer to stack space for @n_structs chunks of type @struct_type + * Since: 2.28 */ /** - * G_IMPLEMENT_INTERFACE_DYNAMIC: - * @TYPE_IFACE: The #GType of the interface to add - * @iface_init: The interface init function + * GTlsBackendInterface: + * @g_iface: The parent interface. + * @get_certificate_type: returns the #GTlsCertificate implementation type + * @get_client_connection_type: returns the #GTlsClientConnection implementation type + * @get_server_connection_type: returns the #GTlsServerConnection implementation type * - * A convenience macro to ease interface addition in the @_C_ section - * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() - * for an example. - * Note that this macro can only be used together with the - * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable - * names from that macro. + * Provides an interface for describing TLS-related types. * - * Since: 2.24 + * Since: 2.28 */ /** - * g_settings_backend_path_changed: - * @backend: a #GSettingsBackend implementation - * @path: the path containing the changes - * @origin_tag: the origin tag + * GTlsCertificate: * - * Signals that all keys below a given path may have possibly changed. - * Backend implementations should call this if an entire path of keys - * have possibly changed their values. - * not containing '//'). - * The meaning of this signal is that any of the key which has a name - * starting with @path may have changed. - * The same rules for when notifications must occur apply as per - * g_settings_backend_changed(). This call might be an appropriate - * reasponse to a 'reset' call but implementations are also free to - * explicitly list the keys that were affected by that call if they can - * easily do so. - * For efficiency reasons, the implementation should strive for @path to - * keys that were changed) but this is not strictly required. As an - * example, if this function is called with the path of "/" then every - * single key in the application will be notified of a possible change. + * Abstract base class for TLS certificate types. * - * Be as long as possible (ie: the longest common prefix of all of the - * Since: 2.26 + * Since: 2.28 */ /** - * g_socket_listener_accept_socket: - * @listener: a #GSocketListener - * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting, or %NULL to ignore. + * GTlsCertificate:certificate: * - * Blocks waiting for a client to connect to any of the sockets added - * to the listener. Returns the #GSocket that was accepted. - * If you want to accept the high-level #GSocketConnection, not a #GSocket, - * which is often the case, then you should use g_socket_listener_accept() - * instead. - * If @source_object is not %NULL it will be filled out with the source - * object specified when the corresponding socket or address was added - * to the listener. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * The DER (binary) encoded representation of the certificate's + * public key. This property and the + * #GTlsCertificate:certificate-pem property represent the same + * data, just in different forms. * - * Returns: (transfer full): a #GSocket on success, %NULL on error. - * Since: 2.22 + * Since: 2.28 */ /** - * GVolumeMonitor::mount-removed: - * @volume_monitor: The volume monitor emitting the signal. - * @mount: a #GMount that was removed. + * GTlsCertificate:certificate-pem: * - * Emitted when a mount is removed. + * The PEM (ASCII) encoded representation of the certificate's + * public key. This property and the #GTlsCertificate:certificate + * property represent the same data, just in different forms. + * + * Since: 2.28 */ /** - * g_socket_address_get_family: - * @address: a #GSocketAddress + * GTlsCertificate:issuer: * - * Gets the socket family type of @address. + * A #GTlsCertificate representing the entity that issued this + * certificate. If %NULL, this means that the certificate is either + * self-signed, or else the certificate of the issuer is not + * available. * - * Returns: the socket family type of @address. - * Since: 2.22 + * Since: 2.28 */ /** - * G_DEFINE_BOXED_TYPE_WITH_CODE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @copy_func: the #GBoxedCopyFunc for the new type - * @free_func: the #GBoxedFreeFunc for the new type - * @_C_: Custom code that gets inserted in the *_get_type() function. + * GTlsCertificate:private-key: * - * A convenience macro for boxed type implementations. - * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the - * type_name_get_type() function, e.g. to register value transformations with - * g_value_register_transform_func(). + * The DER (binary) encoded representation of the certificate's + * private key. This property (or the + * #GTlsCertificate:private-key-pem property) can be set when + * constructing a key (eg, from a file), but cannot be read. * - * Since: 2.26 + * Since: 2.28 */ /** - * g_unix_mount_at: (skip) - * @mount_path: path for a possible unix mount. - * @time_read: (out) (allow-none): guint64 to contain a timestamp. + * GTlsCertificate:private-key-pem: * - * Gets a #GUnixMountEntry for a given mount path. If @time_read - * is set, it will be filled with a unix timestamp for checking - * if the mounts have changed since with g_unix_mounts_changed_since(). + * The PEM (ASCII) encoded representation of the certificate's + * private key. This property (or the #GTlsCertificate:private-key + * property) can be set when constructing a key (eg, from a file), + * but cannot be read. * - * Returns: (transfer full): a #GUnixMountEntry. + * Since: 2.28 */ /** - * g_simple_async_result_get_op_res_gssize: - * @simple: a #GSimpleAsyncResult. + * GTlsCertificateFlags: + * @G_TLS_CERTIFICATE_UNKNOWN_CA: The signing certificate authority is not known. + * @G_TLS_CERTIFICATE_BAD_IDENTITY: The certificate does not match the expected identity of the site that it was retrieved from. + * @G_TLS_CERTIFICATE_NOT_ACTIVATED: The certificate's activation time is still in the future + * @G_TLS_CERTIFICATE_EXPIRED: The certificate has expired + * @G_TLS_CERTIFICATE_REVOKED: The certificate has been revoked according to the #GTlsContext's certificate revocation list. + * @G_TLS_CERTIFICATE_INSECURE: The certificate's algorithm is considered insecure. + * @G_TLS_CERTIFICATE_GENERIC_ERROR: Some other error occurred validating the certificate + * @G_TLS_CERTIFICATE_VALIDATE_ALL: the combination of all of the above flags * - * Gets a gssize from the asynchronous result. + * A set of flags describing TLS certification validation. This can be + * used to set which validation steps to perform (eg, with + * g_tls_client_connection_set_validation_flags()), or to describe why + * a particular certificate was rejected (eg, in + * #GTlsConnection::accept-certificate). * - * Returns: a gssize returned from the asynchronous function. + * Since: 2.28 */ /** - * G_TYPE_DBUS_NODE_INFO: + * GTlsClientConnection: * - * The #GType for a boxed type holding a #GDBusNodeInfo. + * TLS client-side connection; the client-side implementation of a + * #GTlsConnection * - * Since: 2.26 + * Since: 2.28 */ /** - * g_vfs_get_default: + * GTlsClientConnection:accepted-cas: * - * Gets the default #GVfs for the system. + * A list of the distinguished names of the Certificate Authorities + * that the server will accept client certificates signed by. If the + * server requests a client certificate during the handshake, then + * this property will be set after the handshake completes. + * Each item in the list is a #GByteArray which contains the complete + * subject DN of the certificate authority. * - * Returns: (transfer none): a #GVfs. + * Since: 2.28 */ /** - * g_simple_action_new_stateful: - * @name: the name of the action - * @parameter_type: (allow-none): the type of the parameter to the activate function - * @state: the initial state of the action + * GTlsClientConnection:server-identity: * - * Creates a new stateful action. - * must have the same #GVariantType as the initial state. - * If the @state GVariant is floating, it is consumed. + * A #GSocketConnectable describing the identity of the server that + * is expected on the other end of the connection. + * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in + * #GTlsClientConnection:validation-flags, this object will be used + * to determine the expected identify of the remote end of the + * connection; if #GTlsClientConnection:server-identity is not set, + * or does not match the identity presented by the server, then the + * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. + * In addition to its use in verifying the server certificate, + * this is also used to give a hint to the server about what + * certificate we expect, which is useful for servers that serve + * virtual hosts. * - * Returns: a new #GSimpleAction * Since: 2.28 */ /** - * g_file_mount_mountable_finish: - * @file: input #GFile. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * GTlsClientConnection:use-ssl3: * - * Finishes a mount operation. See g_file_mount_mountable() for details. - * Finish an asynchronous mount operation that was started - * with g_file_mount_mountable(). - * Free the returned object with g_object_unref(). + * 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. * - * Returns: (transfer full): a #GFile or %NULL on error. + * Since: 2.28 */ /** - * G_PARAM_SPEC: - * @pspec: a valid #GParamSpec + * GTlsClientConnection:validation-flags: * - * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into - * a #GParamSpec object. + * What steps to perform when validating a certificate received from + * a server. Server certificates that fail to validate in all of the + * ways indicated here will be rejected unless the application + * overrides the default via #GTlsConnection::accept-certificate. + * + * Since: 2.28 */ /** - * g_drive_poll_for_media_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * GTlsConnection: * - * Finishes an operation started with g_drive_poll_for_media() on a drive. - * %FALSE otherwise. + * TLS connection. This is an abstract type that will be subclassed by + * a TLS-library-specific subtype. * - * Returns: %TRUE if the drive has been poll_for_mediaed successfully, + * Since: 2.28 */ /** - * G_TYPE_PARAM_UNICHAR: + * GTlsConnection::accept-certificate: + * @conn: a #GTlsConnection + * @peer_cert: the peer's #GTlsCertificate + * @errors: the problems with @peer_cert. * - * The #GType of #GParamSpecUnichar. + * Emitted during the TLS handshake after the peer certificate has + * been received. You can examine @peer_cert's certification path by + * calling g_tls_certificate_get_issuer() on it. + * For a client-side connection, @peer_cert is the server's + * certificate, and the signal will only be emitted if the + * certificate was not acceptable according to @conn's + * #GTlsClientConnection:validation_flags. If you would like the + * certificate to be accepted despite @errors, return %TRUE from the + * signal handler. Otherwise, if no handler accepts the certificate, + * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. + * For a server-side connection, @peer_cert is the certificate + * presented by the client, if this was requested via the server's + * #GTlsServerConnection:authentication_mode. On the server side, + * the signal is always emitted when the client presents a + * certificate, and the certificate will only be accepted if a + * handler returns %TRUE. + * Note that if this signal is emitted as part of asynchronous I/O + * in the main thread, then you should not attempt to interact with + * the user before returning from the signal handler. If you want to + * let the user decide whether or not to accept the certificate, you + * would have to return %FALSE from the signal handler on the first + * attempt, and then after the connection attempt returns a + * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if + * the user decides to accept the certificate, remember that fact, + * create a new connection, and return %TRUE from the signal handler + * the next time. + * If you are doing I/O in another thread, you do not + * need to worry about this, and can simply block in the signal + * handler until the UI thread returns an answer. + * immediately end the signal emission). %FALSE to allow the signal + * emission to continue, which will cause the handshake to fail if + * no one else overrides it. + * + * Returns: %TRUE to accept @peer_cert (which will also + * Since: 2.28 */ /** - * g_dbus_message_set_reply_serial: - * @message: A #GDBusMessage. - * @value: The value to set. + * GTlsConnection:base-io-stream: * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. + * The #GIOStream that the connection wraps * - * Since: 2.26 + * Since: 2.28 */ /** - * GParameter: - * @name: the parameter name - * @value: the parameter value + * GTlsConnection:certificate: * - * The <structname>GParameter</structname> struct is an auxiliary structure used - * to hand parameter name/value pairs to g_object_newv(). + * The connection's certificate; see + * g_tls_connection_set_certificate(). + * + * Since: 2.28 */ /** - * SECTION:gdbusmethodinvocatio: - * @short_description: Object for handling remote calls - * @include: gio/gio.h + * GTlsConnection:peer-certificate: * - * Instances of the #GDBusMethodInvocation class are used when - * handling D-Bus method calls. It provides a way to asynchronously - * return results and errors. - * The normal way to obtain a #GDBusMethodInvocation object is to receive - * it as an argument to the handle_method_call() function in a - * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object(). + * The connection's peer's certificate, after the TLS handshake has + * completed and the certificate has been accepted. Note in + * particular that this is not yet set during the emission of + * #GTlsConnection::accept-certificate. + * (You can watch for a #GObject::notify signal on this property to + * detect when a handshake has occurred.) + * + * Since: 2.28 */ /** - * g_async_initable_new_async: - * @object_type: a #GType supporting #GAsyncInitable. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished - * @user_data: the data to pass to callback function - * @first_property_name: the name of the first property, or %NULL if no properties - * @...: the value of the first property, followed by other property value pairs, and ended by %NULL. + * GTlsConnection:peer-certificate-errors: * - * Helper function for constructing #GAsyncInitiable object. This is - * similar to g_object_new() but also initializes the object asynchronously. - * When the initialization is finished, @callback will be called. You can - * then call g_async_initable_new_finish() to get the new object and check - * for any errors. + * The errors noticed-and-ignored while verifying + * #GTlsConnection:peer-certificate. Normally this should be %0, but + * it may not be if #GTlsClientConnection::validation-flags is not + * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if + * #GTlsConnection::accept-certificate overrode the default + * behavior. * - * Since: 2.22 + * Since: 2.28 */ /** - * GFilterOutputStream: + * GTlsConnection:rehandshake-mode: * - * A base class for all output streams that work on an underlying stream. + * The rehandshaking mode. See + * g_tls_connection_set_rehandshake_mode(). + * + * Since: 2.28 */ /** - * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC: + * GTlsConnection:require-close-notify: * - * A key in the "time" namespace for getting the microseconds of the time - * the file was last changed. This should be used in conjunction with - * #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Whether or not proper TLS close notification is required. + * See g_tls_connection_set_require_close_notify(). + * + * Since: 2.28 */ /** - * GWin32OutputStream:handle: + * GTlsConnection:use-system-certdb: * - * The file handle that the stream writes to. + * Whether or not the system certificate database will be used to + * verify peer certificates. See + * g_tls_connection_set_use_system_certdb(). * - * Since: 2.26 + * Since: 2.28 */ /** - * SECTION:gasyncresul: - * @short_description: Asynchronous Function Results - * @include: gio/gio.h - * @see_also: #GSimpleAsyncResult + * GTlsError: + * @G_TLS_ERROR_UNAVAILABLE: No TLS provider is available + * @G_TLS_ERROR_MISC: Miscellaneous TLS error + * @G_TLS_ERROR_BAD_CERTIFICATE: A certificate could not be parsed + * @G_TLS_ERROR_NOT_TLS: The TLS handshake failed because the peer does not seem to be a TLS server. + * @G_TLS_ERROR_HANDSHAKE: The TLS handshake failed because the peer's certificate was not acceptable. + * @G_TLS_ERROR_CERTIFICATE_REQUIRED: The TLS handshake failed because the server requested a client-side certificate, but none was provided. See g_tls_connection_set_certificate(). + * @G_TLS_ERROR_EOF: The TLS connection was closed without proper notice, which may indicate an attack. See g_tls_connection_set_require_close_notify(). * - * Provides a base class for implementing asynchronous function results. - * Asynchronous operations are broken up into two separate operations - * which are chained together by a #GAsyncReadyCallback. To begin - * an asynchronous operation, provide a #GAsyncReadyCallback to the - * asynchronous function. This callback will be triggered when the - * operation has completed, and will be passed a #GAsyncResult instance - * filled with the details of the operation's success or failure, the - * object the asynchronous function was started for and any error codes - * returned. The asynchronous callback function is then expected to call - * the corresponding "_finish()" function, passing the object the - * function was called for, the #GAsyncResult instance, and (optionally) - * an @error to grab any error conditions that may have occurred. - * The "_finish()" function for an operation takes the generic result - * (of type #GAsyncResult) and returns the specific result that the - * operation in question yields (e.g. a #GFileEnumerator for a - * "enumerate children" operation). If the result or error status of the - * operation is not needed, there is no need to call the "_finish()" - * function; GIO will take care of cleaning up the result and error - * information after the #GAsyncReadyCallback returns. Applications may - * also take a reference to the #GAsyncResult and call "_finish()" - * later; however, the "_finish()" function may be called at most once. - * Example of a typical asynchronous operation flow: - * |[ - * void _theoretical_frobnitz_async (Theoretical *t, - * GCancellable *c, - * GAsyncReadyCallback *cb, - * gpointer u); - * gboolean _theoretical_frobnitz_finish (Theoretical *t, - * GAsyncResult *res, - * GError **e); - * static void - * frobnitz_result_func (GObject *source_object, - * GAsyncResult *res, - * gpointer user_data) - * { - * gboolean success = FALSE; - * success = _theoretical_frobnitz_finish (source_object, res, NULL); - * if (success) - * g_printf ("Hurray!\n"); - * else - * g_printf ("Uh oh!\n"); - * /<!-- -->* ... *<!-- -->/ - * } - * int main (int argc, void *argv[]) - * { - * /<!-- -->* ... *<!-- -->/ - * _theoretical_frobnitz_async (theoretical_data, - * NULL, - * frobnitz_result_func, - * NULL); - * /<!-- -->* ... *<!-- -->/ - * } - * ]| - * The callback for an asynchronous operation is called only once, and is - * always called, even in the case of a cancelled operation. On cancellation - * the result is a %G_IO_ERROR_CANCELLED error. - * Some asynchronous operations are implemented using synchronous calls. - * These are run in a separate thread, if #GThread has been initialized, but - * otherwise they are sent to the Main Event Loop and processed in an idle - * function. So, if you truly need asynchronous operations, make sure to - * initialize #GThread. + * An error code used with %G_TLS_ERROR in a #GError returned from a + * TLS-related routine. + * + * Since: 2.28 */ /** - * g_icon_new_for_string: - * @str: A string obtained via g_icon_to_string(). - * @error: Return location for error. + * GTlsRehandshakeMode: + * @G_TLS_REHANDSHAKE_NEVER: Never allow rehandshaking + * @G_TLS_REHANDSHAKE_SAFELY: Allow safe rehandshaking only + * @G_TLS_REHANDSHAKE_UNSAFELY: Allow unsafe rehandshaking * - * Generate a #GIcon instance from @str. This function can fail if - * If your application or library provides one or more #GIcon - * implementations you need to ensure that each #GType is registered - * with the type system prior to calling g_icon_new_for_string(). - * interface or %NULL if @error is set. + * When to allow rehandshaking. See + * g_tls_connection_set_rehandshake_mode(). * - * Returns: (transfer full): An object implementing the #GIcon - * Since: 2.20 + * Since: 2.28 */ /** - * g_app_info_supports_files: - * @appinfo: a #GAppInfo. + * GTlsServerConnection: * - * Checks if the application accepts files as arguments. + * TLS server-side connection. This is the server-side implementation + * of a #GTlsConnection. * - * Returns: %TRUE if the @appinfo supports files. + * Since: 2.28 */ /** - * g_action_group_get_action_state: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query + * GTlsServerConnection:authentication-mode: * - * Queries the current state of the named action within @action_group. - * If the action is not stateful then %NULL will be returned. If the - * action is stateful then the type of the return value is the type - * given by g_action_group_get_state_type(). - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. + * The #GTlsAuthenticationMode for the server. This can be changed + * before calling g_tls_connection_handshake() if you want to + * rehandshake with a different mode from the initial handshake. * - * Returns: (allow-none): the current state of the action * Since: 2.28 */ /** - * g_drive_can_stop: - * @drive: a #GDrive. - * - * Checks if a drive can be stopped. + * GToggleNotify: + * @data: Callback data passed to g_object_add_toggle_ref() + * @object: The object on which g_object_add_toggle_ref() was called. + * @is_last_ref: %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references. * - * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise. - * Since: 2.22 + * A callback function used for notification when the state + * of a toggle reference changes. See g_object_add_toggle_ref(). */ /** - * g_file_input_stream_query_info_async: - * @stream: a #GFileInputStream. - * @attributes: a file attribute query string. - * @io_priority: the <link linkend="io-priority">I/O priority</link> 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 + * GTranslateFunc: + * @str: the untranslated string + * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func() * - * Queries the stream information asynchronously. - * When the operation is finished @callback will be called. - * You can then call g_file_input_stream_query_info_finish() - * to get the result of the operation. - * For the synchronous version of this function, - * see g_file_input_stream_query_info(). - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set + * The type of functions which are used to translate user-visible + * strings, for <option>--help</option> output. + * The returned string is owned by GLib and must not be freed. + * + * Returns: a translation of the string for the current locale. */ /** - * GSimplePermission: + * GType: * - * #GSimplePermission is an opaque data structure. There are no methods - * except for those defined by #GPermission. + * A numerical value which represents the unique identifier of a registered + * type. */ /** - * G_TYPE_RESERVED_GLIB_LAST: + * GTypeClass: * - * Last fundamental type number reserved for GLib. + * An opaque structure used as the base of all classes. */ /** - * g_data_input_stream_read_until: - * @stream: a given #GDataInputStream. - * @stop_chars: characters to terminate the read. - * @length: (out): a #gsize to get the length of the data read in. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * GTypeClassCacheFunc: + * @cache_data: data that was given to the g_type_add_class_cache_func() call + * @g_class: The #GTypeClass structure which is unreferenced * - * Reads a string from the data input stream, up to the first - * occurrence of any of the stop characters. - * Note that, in contrast to g_data_input_stream_read_until_async(), - * this function consumes the stop character that it finds. - * Don't use this function in new code. Its functionality is - * inconsistent with g_data_input_stream_read_until_async(). Both - * functions will be marked as deprecated in a future release. Use - * g_data_input_stream_read_upto() instead, but note that that function - * does not consume the stop character. - * before encountering any of the stop characters. Set @length to - * a #gsize to get the length of the string. This function will - * return %NULL on an error. + * A callback function which is called when the reference count of a class + * drops to zero. It may use g_type_class_ref() to prevent the class from + * being freed. You should not call g_type_class_unref() from a + * #GTypeClassCacheFunc function to prevent infinite recursion, use + * g_type_class_unref_uncached() instead. + * The functions have to check the class id passed in to figure + * whether they actually want to cache the class of this type, since all + * classes are routed through the same #GTypeClassCacheFunc chain. + * called, %FALSE to continue. * - * Returns: (transfer full): a string with the data that was read + * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being */ /** - * GInitable: - * - * Interface for initializable objects. + * GTypeDebugFlags: + * @G_TYPE_DEBUG_NONE: Print no messages. + * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping. + * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions. + * @G_TYPE_DEBUG_MASK: Mask covering all debug flags. * - * Since: 2.22 + * The <type>GTypeDebugFlags</type> enumeration values can be passed to + * g_type_init_with_debug_flags() to trigger debugging messages during runtime. + * Note that the messages can also be triggered by setting the + * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of + * "objects" and "signals". */ /** - * g_cancellable_connect: - * @cancellable: A #GCancellable. - * @callback: The #GCallback to connect. - * @data: Data to pass to @callback. - * @data_destroy_func: Free function for @data or %NULL. - * - * Convenience function to connect to the #GCancellable::cancelled - * signal. Also handles the race condition that may happen - * if the cancellable is cancelled right before connecting. - * time of the connect if @cancellable is already cancelled, - * or when @cancellable is cancelled in some thread. - * disconnected, or immediately if the cancellable is already - * cancelled. - * See #GCancellable::cancelled for details on how to use this. - * been cancelled. + * GTypeFlags: + * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type. + * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init(). * - * Returns: The id of the signal handler or 0 if @cancellable has already - * Since: 2.22 + * Bit masks used to check or determine characteristics of a type. */ /** - * GSettingsBindFlags: - * @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal> - * @G_SETTINGS_BIND_GET: Update the #GObject property when the setting changes. It is an error to use this flag if the property is not writable. - * @G_SETTINGS_BIND_SET: Update the setting when the #GObject property changes. It is an error to use this flag if the property is not readable. - * @G_SETTINGS_BIND_NO_SENSITIVITY: Do not try to bind a "sensitivity" property to the writability of the setting - * @G_SETTINGS_BIND_GET_NO_CHANGES: When set in addition to #G_SETTINGS_BIND_GET, set the #GObject property value initially from the setting, but do not listen for changes of the setting - * @G_SETTINGS_BIND_INVERT_BOOLEAN: When passed to g_settings_bind(), uses a pair of mapping functions that invert the boolean value when mapping between the setting and the property. The setting and property must both be booleans. You can not pass this flag to g_settings_bind_with_mapping(). + * GTypeFundamentalFlags: + * @G_TYPE_FLAG_CLASSED: Indicates a classed type. + * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed). + * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type. + * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable). * - * Flags used when creating a binding. These flags determine in which - * direction the binding works. The default is to synchronize in both - * directions. + * Bit masks used to check or determine specific characteristics of a + * fundamental type. */ /** - * g_tls_connection_get_require_close_notify: - * @conn: a #GTlsConnection - * - * Tests whether or not @conn expects a proper TLS close notification - * when the connection is closed. See - * g_tls_connection_set_require_close_notify() for details. - * notification. + * GTypeFundamentalInfo: + * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type * - * Returns: %TRUE if @conn requires a proper TLS close - * Since: 2.28 + * A structure that provides information to the type system which is + * used specifically for managing fundamental types. */ @@ -6137,482 +5739,402 @@ /** - * GSimpleAction:enabled: + * GTypeInstance: * - * If @action is currently enabled. - * If the action is disabled then calls to g_simple_action_activate() and - * g_simple_action_set_state() have no effect. + * An opaque structure used as the base of all type instances. + */ + + +/** + * GTypeInterface: * - * Since: 2.28 + * An opaque structure used as the base of all interface types. */ /** - * g_app_launch_context_new: + * GTypeInterfaceCheckFunc: + * @check_data: data passed to g_type_add_interface_check(). + * @g_iface: the interface that has been initialized * - * Creates a new application launch context. This is not normally used, - * instead you instantiate a subclass of this, such as #GdkAppLaunchContext. + * A callback called after an interface vtable is initialized. + * See g_type_add_interface_check(). * - * Returns: a #GAppLaunchContext. + * Since: 2.4 */ /** - * g_simple_async_result_set_op_res_gpointer: (skip) - * @simple: a #GSimpleAsyncResult. - * @op_res: a pointer result from an asynchronous function. - * @destroy_op_res: a #GDestroyNotify function. + * GTypeModule: + * @name: the name of the module * - * Sets the operation result within the asynchronous result to a pointer. + * The members of the <structname>GTypeModule</structname> structure should not + * be accessed directly, except for the @name field. */ /** - * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE: + * GTypeModuleClass: + * @parent_class: the parent class + * @load: loads the module and registers one or more types using g_type_module_register_type(). + * @unload: unloads the module * - * A key in the "access" namespace for getting execution privileges. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - * This attribute will be %TRUE if the user is able to execute the file. + * In order to implement dynamic loading of types based on #GTypeModule, + * the @load and @unload functions in #GTypeModuleClass must be implemented. */ /** - * g_unix_mount_get_device_path: - * @mount_entry: a #GUnixMount. - * - * Gets the device path for a unix mount. + * GTypePlugin: * - * Returns: a string containing the device path. + * The <structname>GTypePlugin</structname> typedef is used as a placeholder + * for objects that implement the <structname>GTypePlugin</structname> + * interface. */ /** - * g_dbus_error_strip_remote_error: - * @error: A #GError. - * - * Looks for extra information in the error message used to recover - * the D-Bus error name and strips it if found. If stripped, the - * message field in @error will correspond exactly to what was - * received on the wire. - * This is typically used when presenting errors to the end user. + * GTypePluginClass: + * @use_plugin: Increases the use count of the plugin. + * @unuse_plugin: Decreases the use count of the plugin. + * @complete_type_info: Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. + * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. * - * Returns: %TRUE if information was stripped, %FALSE otherwise. - * Since: 2.26 + * The #GTypePlugin interface is used by the type system in order to handle + * the lifecycle of dynamically loaded types. */ /** - * GParamSpecInt: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * GTypePluginCompleteInterfaceInfo: + * @plugin: the #GTypePlugin + * @instance_type: the #GType of an instantiable type to which the interface is added + * @interface_type: the #GType of the interface whose info is completed + * @info: the #GInterfaceInfo to fill in * - * A #GParamSpec derived structure that contains the meta data for integer properties. + * The type of the @complete_interface_info function of #GTypePluginClass. */ /** - * G_PARAM_SPEC_ULONG: - * @pspec: a valid #GParamSpec instance + * GTypePluginCompleteTypeInfo: + * @plugin: the #GTypePlugin + * @g_type: the #GType whose info is completed + * @info: the #GTypeInfo struct to fill in + * @value_table: the #GTypeValueTable to fill in * - * Cast a #GParamSpec instance into a #GParamSpecULong. + * The type of the @complete_type_info function of #GTypePluginClass. */ /** - * g_socket_control_message_deserialize: - * @level: a socket level - * @type: a socket control message type for the given @level - * @size: the size of the data in bytes - * @data: (array length=size) (element-type guint8): pointer to the message data - * - * Tries to deserialize a socket control message of a given - * of #GSocketControlMessage if they can understand this kind - * of message and if so deserialize it into a #GSocketControlMessage. - * If there is no implementation for this kind of control message, %NULL - * will be returned. + * GTypePluginUnuse: + * @plugin: the #GTypePlugin whose use count should be decreased * - * Returns: (transfer full): the deserialized message or %NULL - * Since: 2.22 + * The type of the @unuse_plugin function of #GTypePluginClass. */ /** - * g_file_enumerate_children: - * @file: input #GFile. - * @attributes: an attribute query string. - * @flags: a set of #GFileQueryInfoFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Gets the requested information about the files in a directory. The result - * is a #GFileEnumerator object that will give out #GFileInfo objects for - * all the files in the directory. - * The @attributes value is a string that specifies the file attributes that - * should be gathered. It is not an error if it's not possible to read a particular - * requested attribute from a file - it just won't be set. @attributes should - * be a comma-separated list of attributes or attribute wildcards. The wildcard "*" - * means all attributes, and a wildcard like "standard::*" means all attributes in the standard - * namespace. An example attribute query be "standard::*,owner::user". - * The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. - * If the file is not a directory, the G_FILE_ERROR_NOTDIR error will be returned. - * Other errors are possible too. - * Free the returned object with g_object_unref(). + * GTypePluginUse: + * @plugin: the #GTypePlugin whose use count should be increased * - * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error. + * The type of the @use_plugin function of #GTypePluginClass, which gets called + * to increase the use count of @plugin. */ /** - * GTlsCertificate:issuer: - * - * A #GTlsCertificate representing the entity that issued this - * certificate. If %NULL, this means that the certificate is either - * self-signed, or else the certificate of the issuer is not - * available. + * GTypeQuery: + * @type: the #GType value of the type. + * @type_name: the name of the type. + * @class_size: the size of the class structure. + * @instance_size: the size of the instance structure. * - * Since: 2.28 + * A structure holding information for a specific type. It is + * filled in by the g_type_query() function. */ /** - * g_output_stream_clear_pending: - * @stream: output stream + * GTypeValueTable: + * @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]| + * @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]| + * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]| + * @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]| + * @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i' needs to be used, and for collection of floats 'd'. + * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined. + * @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations. + * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]| * - * Clears the pending flag on @stream. + * The #GTypeValueTable provides the functions required by the #GValue implementation, + * to serve as a container for values of a type. */ /** - * G_TYPE_GSTRING: + * GUnixCredentialsMessage: * - * The #GType for #GString. + * The #GUnixCredentialsMessage structure contains only private data + * and should only be accessed using the provided API. + * + * Since: 2.26 */ /** - * g_permission_get_can_release: - * @permission: a #GPermission instance - * @returns: the value of the 'can-release' property + * GUnixCredentialsMessage:credentials: * - * Gets the value of the 'can-release' property. This property is %TRUE - * if it is generally possible to release the permission by calling - * g_permission_release(). + * The credentials stored in the message. * * Since: 2.26 */ /** - * g_mount_get_default_location: - * @mount: a #GMount. + * GUnixCredentialsMessageClass: * - * Gets the default location of @mount. The default location of the given - * the home directory, or the root of the volume). - * The returned object should be unreffed with - * g_object_unref() when no longer needed. + * Class structure for #GUnixCredentialsMessage. * - * Returns: (transfer full): a #GFile. + * Since: 2.26 */ /** - * G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME: + * GUnixInputStream: * - * Extension point for default handler to URI association. See - * <link linkend="extending-gio">Extending GIO</link>. + * Implements #GInputStream for reading from selectable unix file descriptors */ /** - * g_io_scheduler_job_send_to_mainloop: - * @job: a #GIOSchedulerJob - * @func: a #GSourceFunc callback that will be called in the original thread - * @user_data: data to pass to @func - * @notify: a #GDestroyNotify for @user_data, or %NULL + * GUnixInputStream:close-fd: * - * Used from an I/O job to send a callback to be run in the thread - * that the job was started from, waiting for the result (and thus - * blocking the I/O job). + * Whether to close the file descriptor when the stream is closed. * - * Returns: The return value of @func + * Since: 2.20 */ /** - * G_IS_FLAGS_CLASS: - * @class: a #GFlagsClass + * GUnixInputStream:fd: * - * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS - * or derived. + * The file descriptor that the stream reads from. + * + * Since: 2.20 */ /** - * SECTION:gdatainputstrea: - * @short_description: Data Input Stream - * @include: gio/gio.h - * @see_also: #GInputStream + * GUnixMount: * - * Data input stream implements #GInputStream and includes functions for - * reading structured data directly from a binary input stream. + * Implementation of the #GMount interface for Unix systems. */ /** - * g_socket_client_get_family: - * @client: a #GSocketClient. - * - * Gets the socket family of the socket client. - * See g_socket_client_set_family() for details. + * GUnixMountEntry: * - * Returns: a #GSocketFamily - * Since: 2.22 + * Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>). + * This corresponds roughly to a mtab entry. */ /** - * g_simple_async_result_new: - * @source_object: (allow-none): a #GObject, or %NULL. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * @source_tag: the asynchronous function. - * - * Creates a #GSimpleAsyncResult. + * GUnixMountMonitor: * - * Returns: a #GSimpleAsyncResult. + * Watches #GUnixMount<!-- -->s for changes. */ /** - * g_content_type_get_mime_type: - * @type: a content type string - * - * Gets the mime type for the content type, if one is registered. - * or %NULL if unknown. + * GUnixMountMonitor::mountpoints-changed: + * @monitor: the object on which the signal is emitted * - * Returns: (allow-none): the registered mime type for the given @type, + * Emitted when the unix mount points have changed. */ /** - * G_FILE_ATTRIBUTE_OWNER_GROUP: + * GUnixMountMonitor::mounts-changed: + * @monitor: the object on which the signal is emitted * - * A key in the "owner" namespace for getting the file owner's group. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * Emitted when the unix mounts have changed. */ /** - * g_file_find_enclosing_mount_async: - * @file: a #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * GUnixMountPoint: * - * Asynchronously gets the mount for the file. - * For more details, see g_file_find_enclosing_mount() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_find_enclosing_mount_finish() to get the result of the operation. + * Defines a Unix mount point (e.g. <filename>/dev</filename>). + * This corresponds roughly to a fstab entry. */ /** - * GLoadableIconIface: - * @g_iface: The parent interface. - * @load: Loads an icon. - * @load_async: Loads an icon asynchronously. - * @load_finish: Finishes an asynchronous icon load. + * GUnixOutputStream: * - * Interface for icons that can be loaded as a stream. + * Implements #GOutputStream for outputting to selectable unix file descriptors */ /** - * g_file_open_readwrite_async: - * @file: input #GFile. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * GUnixOutputStream:close-fd: * - * Asynchronously opens @file for reading and writing. - * For more details, see g_file_open_readwrite() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_open_readwrite_finish() to get the result of the operation. + * Whether to close the file descriptor when the stream is closed. * - * Since: 2.22 + * Since: 2.20 */ /** - * SECTION:gproxyresolve: - * @short_description: Asynchronous and cancellable network proxy resolver - * @include: gio/gio.h + * GUnixOutputStream:fd: * - * #GProxyResolver provides synchronous and asynchronous network proxy - * resolution. #GProxyResolver is used within #GClientSocket through - * the method g_socket_connectable_proxy_enumerate(). + * The file descriptor that the stream writes to. + * + * Since: 2.20 */ /** - * g_socket_client_set_enable_proxy: - * @client: a #GSocketClient. - * @enable: whether to enable proxies - * - * Sets whether or not @client attempts to make connections via a - * proxy server. When enabled (the default), #GSocketClient will use a - * #GProxyResolver to determine if a proxy protocol such as SOCKS is - * needed, and automatically do the necessary proxy negotiation. + * GUnixSocketAddress: * - * Since: 2.26 + * A UNIX-domain (local) socket address, corresponding to a + * <type>struct sockaddr_un</type>. */ /** - * GChecksum: + * GUnixSocketAddress:abstract: * - * An opaque structure representing a checksumming operation. - * To create a new GChecksum, use g_checksum_new(). To free - * a GChecksum, use g_checksum_free(). + * Whether or not this is an abstract address + * distinguishes between zero-padded and non-zero-padded + * abstract addresses. * - * Since: 2.16 + * Deprecated: Use #GUnixSocketAddress:address-type, which */ /** - * G_CCLOSURE_SWAP_DATA: - * @cclosure: a #GCClosure + * GUnixSocketAddressType: + * @G_UNIX_SOCKET_ADDRESS_INVALID: invalid + * @G_UNIX_SOCKET_ADDRESS_ANONYMOUS: anonymous + * @G_UNIX_SOCKET_ADDRESS_PATH: a filesystem path + * @G_UNIX_SOCKET_ADDRESS_ABSTRACT: an abstract name + * @G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED: an abstract name, 0-padded to the full length of a unix socket name * - * Checks whether the user data of the #GCClosure should be passed as the - * first parameter to the callback. See g_cclosure_new_swap(). + * The type of name used by a #GUnixSocketAddress. + * %G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain + * socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS + * indicates a socket not bound to any name (eg, a client-side socket, + * or a socket created with socketpair()). + * For abstract sockets, there are two incompatible ways of naming + * sockaddr_un</literal> as the name, padding the unused parts of the + * %sun_path field with zeroes; this corresponds to + * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs + * instead just use a portion of %sun_path, and pass an appropriate + * smaller length to bind() or connect(). This is + * %G_UNIX_SOCKET_ADDRESS_ABSTRACT. * - * Returns: %TRUE if data has to be swapped. + * Them: the man pages suggest using the entire <literal>struct + * Since: 2.26 */ /** - * G_TYPE_IS_DEEP_DERIVABLE: - * @type: A #GType value. + * GUserDirectory: + * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory + * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory + * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory + * @G_USER_DIRECTORY_MUSIC: the user's Music directory + * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory + * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory + * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory + * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory + * @G_USER_N_DIRECTORIES: the number of enum values * - * Checks if @type is a deep derivable type. A deep derivable type - * can be used as the base class of a deep (multi-level) class hierarchy. + * These are logical ids for special directories which are defined + * depending on the platform used. You should use g_get_user_special_dir() + * to retrieve the full path associated to the logical id. + * The #GUserDirectory enumeration can be extended at later date. Not + * every platform has a directory for every logical id in this + * enumeration. * - * Returns: %TRUE on success. + * Since: 2.14 */ /** - * g_file_attribute_matcher_matches: - * @matcher: a #GFileAttributeMatcher. - * @attribute: a file attribute key. + * GValue: * - * Checks if an attribute will be matched by an attribute matcher. If - * the matcher was created with the "*" matching string, this function - * will always return %TRUE. + * An opaque structure used to hold different types of values. + * to functions within a #GTypeValueTable structure, or implementations of + * the g_value_*() API. That is, code portions which implement new fundamental + * types. + * #GValue users can not make any assumptions about how data is stored + * within the 2 element @data union, and the @g_type member should + * only be accessed through the G_VALUE_TYPE() macro. * - * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise. + * The data within the structure has protected scope: it is accessible only */ /** - * g_resolver_lookup_service_finish: - * @resolver: a #GResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL - * - * Retrieves the result of a previous call to - * g_resolver_lookup_service_async(). - * If the DNS resolution failed, @error (if non-%NULL) will be set to - * a value from #GResolverError. If the operation was cancelled, - * or %NULL on error. See g_resolver_lookup_service() for more details. + * GValueArray: + * @n_values: number of values contained in the array + * @values: array of values * - * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, - * Since: 2.22 + * A #GValueArray contains an array of #GValue elements. */ /** - * g_file_info_set_attribute_int32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a signed 32-bit integer + * GValueTransform: + * @src_value: Source value. + * @dest_value: Target value. * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * The type of value transformation functions which can be registered with + * g_value_register_transform_func(). */ /** - * g_socket_client_connect_to_service_finish: - * @client: a #GSocketClient. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. - * - * Finishes an async connect operation. See g_socket_client_connect_to_service_async() + * GVariantType: * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 + * A type in the GVariant type system. + * Two types may not be compared by value; use g_variant_type_equal() or + * g_variant_type_is_subtype(). May be copied using + * g_variant_type_copy() and freed using g_variant_type_free(). */ /** - * GTranslateFunc: - * @str: the untranslated string - * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func() - * - * The type of functions which are used to translate user-visible - * strings, for <option>--help</option> output. - * The returned string is owned by GLib and must not be freed. + * GVfs: * - * Returns: a translation of the string for the current locale. + * Virtual File System object. */ /** - * G_VOLUME_IDENTIFIER_KIND_HAL_UDI: + * GVolume: * - * The string used to obtain a Hal UDI with g_volume_get_identifier(). + * Opaque mountable volume object. */ /** - * g_cancellable_cancel: - * @cancellable: a #GCancellable object. + * GVolume::changed: * - * Will set @cancellable to cancelled, and will emit the - * #GCancellable::cancelled signal. (However, see the warning about - * race conditions in the documentation for that signal if you are - * planning to connect to it.) - * This function is thread-safe. In other words, you can safely call - * it from a thread other than the one running the operation that was - * passed the @cancellable. - * The convention within gio is that cancelling an asynchronous - * operation causes it to complete asynchronously. That is, if you - * cancel the operation from the same thread in which it is running, - * then the operation's #GAsyncReadyCallback will not be invoked until - * the application returns to the main loop. + * Emitted when the volume has been changed. */ /** - * g_dbus_arg_info_ref: - * @info: A #GDBusArgInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * GVolume::removed: * - * Returns: The same @info. - * Since: 2.26 + * This signal is emitted when the #GVolume have been removed. If + * the recipient is holding references to the object they should + * release them so the object can be finalized. */ @@ -6644,788 +6166,754 @@ /** - * g_file_attribute_matcher_enumerate_next: - * @matcher: a #GFileAttributeMatcher. + * GVolumeMonitor: * - * Gets the next matched attribute from a #GFileAttributeMatcher. - * no more attribute exist. + * A Volume Monitor that watches for volume events. + */ + + +/** + * GVolumeMonitor::drive-changed: + * @volume_monitor: The volume monitor emitting the signal. + * @drive: the drive that changed * - * Returns: a string containing the next attribute or %NULL if + * Emitted when a drive changes. */ /** - * G_TYPE_INSTANCE_GET_PRIVATE: - * @instance: the instance of a type deriving from @private_type. - * @g_type: the type identifying which private data to retrieve. - * @c_type: The C type for the private structure. + * GVolumeMonitor::drive-connected: + * @volume_monitor: The volume monitor emitting the signal. + * @drive: a #GDrive that was connected. * - * Gets the private structure for a particular type. - * The private structure must have been registered in the - * class_init function with g_type_class_add_private(). - * This macro should only be used in type implementations. + * Emitted when a drive is connected to the system. + */ + + +/** + * GVolumeMonitor::drive-disconnected: + * @volume_monitor: The volume monitor emitting the signal. + * @drive: a #GDrive that was disconnected. * - * Since: 2.4 - * Returns: a pointer to the private data structure. + * Emitted when a drive is disconnected from the system. */ /** - * g_file_enumerator_close: - * @enumerator: a #GFileEnumerator. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occuring, or %NULL to ignore + * GVolumeMonitor::drive-eject-button: + * @volume_monitor: The volume monitor emitting the signal. + * @drive: the drive where the eject button was pressed * - * Releases all resources used by this enumerator, making the - * enumerator return %G_IO_ERROR_CLOSED on all calls. - * This will be automatically called when the last reference - * is dropped, but you might want to call this function to make - * sure resources are released as early as possible. + * Emitted when the eject button is pressed on @drive. * - * Returns: #TRUE on success or #FALSE on error. + * Since: 2.18 */ /** - * g_socket_control_message_get_msg_type: - * @message: a #GSocketControlMessage + * GVolumeMonitor::drive-stop-button: + * @volume_monitor: The volume monitor emitting the signal. + * @drive: the drive where the stop button was pressed * - * Returns the protocol specific type of the control message. - * For instance, for UNIX fd passing this would be SCM_RIGHTS. + * Emitted when the stop button is pressed on @drive. * - * Returns: an integer describing the type of control message * Since: 2.22 */ /** - * GThemedIcon:names: + * GVolumeMonitor::mount-added: + * @volume_monitor: The volume monitor emitting the signal. + * @mount: a #GMount that was added. * - * A %NULL-terminated array of icon names. + * Emitted when a mount is added. */ /** - * GSeekable: + * GVolumeMonitor::mount-changed: + * @volume_monitor: The volume monitor emitting the signal. + * @mount: a #GMount that changed. * - * Seek object for streaming operations. + * Emitted when a mount changes. */ /** - * g_memory_output_stream_get_data: - * @ostream: a #GMemoryOutputStream - * - * Gets any loaded data from the @ostream. - * Note that the returned pointer may become invalid on the next - * write or truncate operation on the stream. + * GVolumeMonitor::mount-pre-unmount: + * @volume_monitor: The volume monitor emitting the signal. + * @mount: a #GMount that is being unmounted. * - * Returns: (transfer none): pointer to the stream's data + * Emitted when a mount is about to be removed. */ /** - * GFileMonitorEvent: - * @G_FILE_MONITOR_EVENT_CHANGED: a file changed. - * @G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT: a hint that this was probably the last change in a set of changes. - * @G_FILE_MONITOR_EVENT_DELETED: a file was deleted. - * @G_FILE_MONITOR_EVENT_CREATED: a file was created. - * @G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED: a file attribute was changed. - * @G_FILE_MONITOR_EVENT_PRE_UNMOUNT: the file location will soon be unmounted. - * @G_FILE_MONITOR_EVENT_UNMOUNTED: the file location was unmounted. - * @G_FILE_MONITOR_EVENT_MOVED: the file was moved. + * GVolumeMonitor::mount-removed: + * @volume_monitor: The volume monitor emitting the signal. + * @mount: a #GMount that was removed. * - * Specifies what type of event a monitor event is. + * Emitted when a mount is removed. */ /** - * GTlsClientConnection:validation-flags: - * - * What steps to perform when validating a certificate received from - * a server. Server certificates that fail to validate in all of the - * ways indicated here will be rejected unless the application - * overrides the default via #GTlsConnection::accept-certificate. + * GVolumeMonitor::volume-added: + * @volume_monitor: The volume monitor emitting the signal. + * @volume: a #GVolume that was added. * - * Since: 2.28 + * Emitted when a mountable volume is added to the system. */ /** - * g_data_input_stream_read_upto_finish: - * @stream: a #GDataInputStream - * @result: the #GAsyncResult that was provided to the callback - * @length: (out): a #gsize to get the length of the data read in - * @error: #GError for error reporting + * GVolumeMonitor::volume-changed: + * @volume_monitor: The volume monitor emitting the signal. + * @volume: a #GVolume that changed. * - * Finish an asynchronous call started by - * g_data_input_stream_read_upto_async(). - * Note that this function does <emphasis>not</emphasis> consume the - * stop character. You have to use g_data_input_stream_read_byte() to - * get it before calling g_data_input_stream_read_upto_async() again. - * before encountering any of the stop characters. Set @length to - * a #gsize to get the length of the string. This function will - * return %NULL on an error. + * Emitted when mountable volume is changed. + */ + + +/** + * GVolumeMonitor::volume-removed: + * @volume_monitor: The volume monitor emitting the signal. + * @volume: a #GVolume that was removed. * - * Returns: (transfer full): a string with the data that was read - * Since: 2.24 + * Emitted when a mountable volume is removed from the system. */ /** - * g_simple_action_group_remove: - * @simple: a #GSimpleActionGroup - * @action_name: the name of the action + * GWeakNotify: + * @data: data that was provided when the weak reference was established + * @where_the_object_was: the object being finalized * - * Removes the named action from the action group. - * If no action of this name is in the group then nothing happens. + * A #GWeakNotify function can be added to an object as a callback that gets + * triggered when the object is finalized. Since the object is already being + * finalized when the #GWeakNotify is called, there's not much you could do + * with the object, apart from e.g. using its adress as hash-index or the like. + */ + + +/** + * GWin32InputStream: * - * Since: 2.28 + * Implements #GInputStream for reading from selectable Windows file handles */ /** - * g_output_stream_splice: - * @stream: a #GOutputStream. - * @source: a #GInputStream. - * @flags: a set of #GOutputStreamSpliceFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * GWin32InputStream:close-handle: * - * Splices an input stream into an output stream. - * -1 if an error occurred. + * Whether to close the file handle when the stream is closed. * - * Returns: a #gssize containing the size of the data spliced, or + * Since: 2.26 */ /** - * G_TYPE_FLAG_RESERVED_ID_BIT: + * GWin32InputStream:handle: * - * A bit in the type number that's supposed to be left untouched. + * The handle that the stream reads from. + * + * Since: 2.26 */ /** - * GIOStreamSpliceFlags: - * @G_IO_STREAM_SPLICE_NONE: Do not close either stream. - * @G_IO_STREAM_SPLICE_CLOSE_STREAM1: Close the first stream after the splice. - * @G_IO_STREAM_SPLICE_CLOSE_STREAM2: Close the second stream after the splice. - * @G_IO_STREAM_SPLICE_WAIT_FOR_BOTH: Wait for both splice operations to finish before calling the callback. - * - * GIOStreamSpliceFlags determine how streams should be spliced. + * GWin32Mount: * - * Since: 2.28 + * Implementation of the #GMount interface for Win32 systems. */ /** - * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITER: + * GWin32OutputStream: * - * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". + * Implements #GOutputStream for outputting to Windows file handles */ /** - * g_socket_client_connect_to_uri: - * @client: a #GSocketClient - * @uri: A network URI - * @default_port: the default port to connect to - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: a pointer to a #GError, or %NULL + * GWin32OutputStream:close-handle: * - * This is a helper function for g_socket_client_connect(). - * Attempts to create a TCP connection with a network URI. - * component. If a port is not specified in the URI, @default_port - * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE. - * (#GSocketClient does not know to automatically assume TLS for - * certain URI schemes.) - * Using this rather than g_socket_client_connect() or - * g_socket_client_connect_to_host() allows #GSocketClient to - * determine when to use application-specific proxy protocols. - * Upon a successful connection, a new #GSocketConnection is constructed - * and returned. The caller owns this new object and must drop their - * reference to it when finished with it. - * In the event of any failure (DNS error, service not found, no hosts - * connectable) %NULL is returned and @error (if non-%NULL) is set - * accordingly. + * Whether to close the file handle when the stream is closed. * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. * Since: 2.26 */ /** - * g_unix_mount_points_get: (skip) - * @time_read: (out) (allow-none): guint64 to contain a timestamp. + * GWin32OutputStream:handle: * - * Gets a #GList of #GUnixMountPoint containing the unix mount points. - * If @time_read is set, it will be filled with the mount timestamp, - * allowing for checking if the mounts have changed with - * g_unix_mounts_points_changed_since(). - * a #GList of the UNIX mountpoints. + * The file handle that the stream writes to. * - * Returns: (element-type GUnixMountPoint) (transfer full): + * Since: 2.26 */ /** - * GDataStreamByteOrder: - * @G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN: Selects Big Endian byte order. - * @G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN: Selects Little Endian byte order. - * @G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN: Selects endianness based on host machine's architecture. + * GZlibCompressor: * - * #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources - * across various machine architectures. + * Zlib decompression */ /** - * g_mount_guess_content_type_sync: - * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: a #GError location to store the error occuring, or %NULL to ignore + * GZlibCompressor:file-info: * - * Tries to guess the type of content stored on @mount. Returns one or - * more textual identifiers of well-known content types (typically - * prefixed with "x-content/"), e.g. x-content/image-dcf for camera - * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> - * specification for more on x-content types. - * This is an synchronous operation and as such may block doing IO; - * see g_mount_guess_content_type() for the asynchronous version. - * Caller should free this array with g_strfreev() when done with it. + * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is + * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name + * and modification time from the file info to the the GZIP header. * - * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. - * Since: 2.18 + * Since: 2.26 */ /** - * g_async_initable_init_async: - * @initable: a #GAsyncInitable. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to callback function + * GZlibCompressorFormat: + * @G_ZLIB_COMPRESSOR_FORMAT_ZLIB: deflate compression with zlib header + * @G_ZLIB_COMPRESSOR_FORMAT_GZIP: gzip file format + * @G_ZLIB_COMPRESSOR_FORMAT_RAW: deflate compression with no header * - * Starts asynchronous initialization of the object implementing the - * interface. This must be done before any real use of the object after - * initial construction. If the object also implements #GInitable you can - * optionally call g_initable_init() instead. - * When the initialization is finished, @callback will be called. You can - * then call g_async_initable_init_finish() to get the result of the - * initialization. - * Implementations may also support cancellation. If @cancellable is not - * %NULL, then initialization can be cancelled by triggering the cancellable - * object from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and - * the object doesn't support cancellable initialization, the error - * %G_IO_ERROR_NOT_SUPPORTED will be returned. - * If this function is not called, or returns with an error, then all - * operations on the object should fail, generally returning the - * error %G_IO_ERROR_NOT_INITIALIZED. - * to this function with the same argument should return the same results. - * Only the first call initializes the object; further calls return the result - * of the first call. This is so that it's safe to implement the singleton - * pattern in the GObject constructor function. - * For classes that also support the #GInitable interface, the default - * implementation of this method will run the g_initable_init() function - * in a thread, so if you want to support asynchronous initialization via - * threads, just implement the #GAsyncInitable interface without overriding - * any interface methods. + * Used to select the type of data format to use for #GZlibDecompressor + * and #GZlibCompressor. * - * Implementations of this method must be idempotent: i.e. multiple calls - * Since: 2.22 + * Since: 2.24 */ /** - * g_file_new_for_path: - * @path: a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. - * - * Constructs a #GFile for a given path. This operation never - * fails, but the returned object might not support any I/O - * operation if @path is malformed. + * GZlibDecompressor: * - * Returns: (transfer full): a new #GFile for the given @path. + * Zlib decompression */ /** - * g_new: - * @struct_type: the type of the elements to allocate - * @n_structs: the number of elements to allocate + * GZlibDecompressor:file-info: * - * Allocates @n_structs elements of type @struct_type. - * The returned pointer is cast to a pointer to the given type. - * If @n_structs is 0 it returns %NULL. - * Care is taken to avoid overflow when calculating the size of the allocated block. - * Since the returned pointer is already casted to the right type, - * it is normally unnecessary to cast it explicitly, and doing - * so might hide memory allocation errors. + * A #GFileInfo containing the information found in the GZIP header + * of the data stream processed, or %NULL if the header was not yet + * fully processed, is not present at all, or the compressor's + * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP. * - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type + * Since: 2.26 */ /** - * g_file_copy_attributes: - * @source: a #GFile with attributes. - * @destination: a #GFile to copy attributes to. - * @flags: a set of #GFileCopyFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Copies the file attributes from @source to @destination. - * Normally only a subset of the file attributes are copied, - * those that are copies in a normal file copy operation - * (which for instance does not include e.g. owner). However - * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then - * all the metadata that is possible to copy is copied. This - * is useful when implementing move by copy + delete source. + * G_BOOKMARK_FILE_ERROR: * - * Returns: %TRUE if the attributes were copied successfully, %FALSE otherwise. + * Error domain for bookmark file parsing. + * Errors in this domain will be from the #GBookmarkFileError + * enumeration. See #GError for information on error domains. */ /** - * G_IS_PARAM_SPEC_CHAR: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. + * G_CALLBACK: + * @f: a function pointer. * - * Returns: %TRUE on success. + * Cast a function pointer to a #GCallback. */ /** - * g_dbus_message_get_byte_order: - * @message: A #GDBusMessage. + * G_CCLOSURE_SWAP_DATA: + * @cclosure: a #GCClosure * - * Gets the byte order of @message. + * Checks whether the user data of the #GCClosure should be passed as the + * first parameter to the callback. See g_cclosure_new_swap(). * - * Returns: The byte order. + * Returns: %TRUE if data has to be swapped. */ /** - * GValueTransform: - * @src_value: Source value. - * @dest_value: Target value. + * G_CLOSURE_NEEDS_MARSHAL: + * @closure: a #GClosure * - * The type of value transformation functions which can be registered with - * g_value_register_transform_func(). + * Check if the closure still needs a marshaller. See g_closure_set_marshal(). + * + * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on */ /** - * g_app_info_get_default_for_type: - * @content_type: the content type to find a #GAppInfo for - * @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs + * G_CLOSURE_N_NOTIFIERS: + * @cl: a #GClosure * - * Gets the #GAppInfo that corresponds to a given content type. - * %NULL on error. + * Get the total number of notifiers connected with the closure @cl. + * The count includes the meta marshaller, the finalize and invalidate notifiers + * and the marshal guards. Note that each guard counts as two notifiers. + * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), + * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). * - * Returns: (transfer full): #GAppInfo for given @content_type or + * Returns: number of notifiers */ /** - * G_IS_PARAM_SPEC_UNICHAR: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. + * G_CONVERT_ERROR: * - * Returns: %TRUE on success. + * Error domain for character set conversions. Errors in this domain will + * be from the #GConvertError enumeration. See #GError for information on + * error domains. */ /** - * g_settings_apply: - * @settings: a #GSettings instance + * G_DATALIST_FLAGS_MASK: * - * Applies any changes that have been made to the settings. This - * function does nothing unless @settings is in 'delay-apply' mode; - * see g_settings_delay(). In the normal case settings are always - * applied immediately. + * A bitmask that restricts the possible flags passed to + * g_datalist_set_flags(). Passing a flags value where + * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. */ /** - * g_file_info_get_symlink_target: - * @info: a #GFileInfo. + * G_DBUS_ERROR: * - * Gets the symlink target for a given #GFileInfo. + * Error domain for errors generated by a remote message bus. Errors + * in this domain will be from the #GDBusError enumeration. See + * #GError for more information on error domains. + * Note that errors in this error domain is intended only for + * returning errors from a remote message bus process. Errors + * generated locally in-process by e.g. #GDBusConnection is from the + * %G_IO_ERROR domain. * - * Returns: a string containing the symlink target. + * Since: 2.26 */ /** - * G_SIGNAL_TYPE_STATIC_SCOPE: + * G_DEFINE_ABSTRACT_TYPE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. * - * This macro flags signal argument types for which the signal system may - * assume that instances thereof remain persistent across all signal emissions - * they are used in. This is only useful for non ref-counted, value-copy types. - * To flag a signal argument in this way, add - * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument - * of g_signal_new(). - * |[ - * g_signal_new ("size_request", - * G_TYPE_FROM_CLASS (gobject_class), - * G_SIGNAL_RUN_FIRST, - * G_STRUCT_OFFSET (GtkWidgetClass, size_request), - * NULL, NULL, - * _gtk_marshal_VOID__BOXED, - * G_TYPE_NONE, 1, - * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); - * ]| + * A convenience macro for type implementations. + * Similar to G_DEFINE_TYPE(), but defines an abstract type. + * See G_DEFINE_TYPE_EXTENDED() for an example. + * + * Since: 2.4 */ /** - * g_output_stream_is_closed: - * @stream: a #GOutputStream. + * G_DEFINE_ABSTRACT_TYPE_WITH_CODE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. + * @_C_: Custom code that gets inserted in the @type_name_get_type() function. * - * Checks if an output stream has already been closed. + * A convenience macro for type implementations. + * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to + * insert custom code into the *_get_type() function, e.g. interface implementations + * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. * - * Returns: %TRUE if @stream is closed. %FALSE otherwise. + * Since: 2.4 */ /** - * g_file_load_partial_contents_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @contents: (out) (transfer full): a location to place the contents of the file. - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed - * @error: a #GError, or %NULL + * G_DEFINE_BOXED_TYPE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @copy_func: the #GBoxedCopyFunc for the new type + * @free_func: the #GBoxedFreeFunc for the new type * - * Finishes an asynchronous partial load operation that was started - * with g_file_load_partial_contents_async(). The data is always - * zero-terminated, but this is not included in the resultant @length. - * The returned @content should be freed with g_free() when no longer - * needed. - * present, it will be set appropriately. + * A convenience macro for boxed type implementations, which defines a + * type_name_get_type() function registering the boxed type. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is + * Since: 2.26 */ /** - * g_socket_listener_add_address: - * @listener: a #GSocketListener - * @address: a #GSocketAddress - * @type: a #GSocketType - * @protocol: a #GSocketProtocol - * @source_object: (allow-none): Optional #GObject identifying this source - * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL. - * @error: #GError for error reporting, or %NULL to ignore. + * G_DEFINE_BOXED_TYPE_WITH_CODE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @copy_func: the #GBoxedCopyFunc for the new type + * @free_func: the #GBoxedFreeFunc for the new type + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Creates a socket of type @type and protocol @protocol, binds - * it to @address and adds it to the set of sockets we're accepting - * sockets from. - * Note that adding an IPv6 address, depending on the platform, - * may or may not result in a listener that also accepts IPv4 - * connections. For more determinstic behaviour, see - * g_socket_listener_add_inet_port(). - * to accept to identify this particular source, which is - * useful if you're listening on multiple addresses and do - * different things depending on what address is connected to. - * If successful and @effective_address is non-%NULL then it will - * be set to the address that the binding actually occured at. This - * is helpful for determining the port number that was used for when - * requested, belongs to the caller and must be freed. + * A convenience macro for boxed type implementations. + * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the + * type_name_get_type() function, e.g. to register value transformations with + * g_value_register_transform_func(). * - * Requesting a binding to port 0 (ie: "any port"). This address, if - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 + * Since: 2.26 */ /** - * g_socket_get_socket_type: - * @socket: a #GSocket. + * G_DEFINE_DYNAMIC_TYPE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. * - * Gets the socket type of the socket. + * A convenience macro for dynamic type implementations, which declares a + * class initialization function, an instance initialization function (see + * #GTypeInfo for information about these) and a static variable named + * it defines a <function>*_get_type()</function> and a static + * <function>*_register_type()</function> function for use in your + * <function>module_init()</function>. + * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. * - * Returns: a #GSocketType - * Since: 2.22 + * Since: 2.14 */ /** - * G_VALUE_HOLDS_BOXED: - * @value: a valid #GValue structure + * G_DEFINE_DYNAMIC_TYPE_EXTENDED: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @TYPE_PARENT: The #GType of the parent type. + * @flags: #GTypeFlags to pass to g_type_module_register_type() + * @CODE: Custom code that gets inserted in the *_get_type() function. * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. + * A more general version of G_DEFINE_DYNAMIC_TYPE() which + * allows to specify #GTypeFlags and custom code. + * |[ + * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, + * gtk_gadget, + * GTK_TYPE_THING, + * 0, + * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, + * gtk_gadget_gizmo_init)); + * ]| + * expands to + * |[ + * static void gtk_gadget_init (GtkGadget *self); + * static void gtk_gadget_class_init (GtkGadgetClass *klass); + * static void gtk_gadget_class_finalize (GtkGadgetClass *klass); + * static gpointer gtk_gadget_parent_class = NULL; + * static GType gtk_gadget_type_id = 0; + * static void gtk_gadget_class_intern_init (gpointer klass) + * { + * gtk_gadget_parent_class = g_type_class_peek_parent (klass); + * gtk_gadget_class_init ((GtkGadgetClass*) klass); + * } + * GType + * gtk_gadget_get_type (void) + * { + * return gtk_gadget_type_id; + * } + * static void + * gtk_gadget_register_type (GTypeModule *type_module) + * { + * const GTypeInfo g_define_type_info = { + * sizeof (GtkGadgetClass), + * (GBaseInitFunc) NULL, + * (GBaseFinalizeFunc) NULL, + * (GClassInitFunc) gtk_gadget_class_intern_init, + * (GClassFinalizeFunc) gtk_gadget_class_finalize, + * NULL, // class_data + * sizeof (GtkGadget), + * 0, // n_preallocs + * (GInstanceInitFunc) gtk_gadget_init, + * NULL // value_table + * }; + * gtk_gadget_type_id = g_type_module_register_type (type_module, + * GTK_TYPE_THING, + * GtkGadget, + * &g_define_type_info, + * (GTypeFlags) flags); + * { + * const GInterfaceInfo g_implement_interface_info = { + * (GInterfaceInitFunc) gtk_gadget_gizmo_init + * }; + * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); + * } + * } + * ]| * - * Returns: %TRUE on success. + * Since: 2.14 */ /** - * GFileIOStream: + * G_DEFINE_INTERFACE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. * - * A subclass of GIOStream for opened files. This adds - * a few file-specific operations and seeking and truncating. - * #GFileIOStream implements GSeekable. + * A convenience macro for #GTypeInterface definitions, which declares + * a default vtable initialization function and defines a *_get_type() + * function. + * The macro expects the interface initialization function to have the + * name <literal>t_n ## _default_init</literal>, and the interface + * structure to have the name <literal>TN ## Interface</literal>. + * + * Since: 2.24 */ /** - * g_vfs_get_supported_uri_schemes: - * @vfs: a #GVfs. + * G_DEFINE_INTERFACE_WITH_CODE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Gets a list of URI schemes supported by @vfs. - * The returned array belongs to GIO and must - * not be freed or modified. + * A convenience macro for #GTypeInterface definitions. Similar to + * G_DEFINE_INTERFACE(), but allows you to insert custom code into the + * *_get_type() function, e.g. additional interface implementations + * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See + * G_DEFINE_TYPE_EXTENDED() for a similar example using + * G_DEFINE_TYPE_WITH_CODE(). * - * Returns: (transfer none): a %NULL-terminated array of strings. + * Since: 2.24 */ /** - * GRegex: + * G_DEFINE_POINTER_TYPE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. * - * A GRegex is the "compiled" form of a regular expression pattern. This - * structure is opaque and its fields cannot be accessed directly. + * A convenience macro for pointer type implementations, which defines a + * type_name_get_type() function registering the pointer type. * - * Since: 2.14 + * Since: 2.26 */ /** - * GFileAttributeInfoList: - * @infos: an array of #GFileAttributeInfo<!-- -->s. - * @n_infos: the number of values in the array. + * G_DEFINE_POINTER_TYPE_WITH_CODE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Acts as a lightweight registry for possible valid file attributes. - * The registry stores Key-Value pair formats as #GFileAttributeInfo<!-- -->s. + * A convenience macro for pointer type implementations. + * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the + * type_name_get_type() function. + * + * Since: 2.26 */ /** - * GMount::changed: - * @mount: the object on which the signal is emitted + * G_DEFINE_TYPE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. * - * Emitted when the mount has been changed. + * A convenience macro for type implementations, which declares a + * class initialization function, an instance initialization function (see #GTypeInfo for information about + * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines + * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example. + * + * Since: 2.4 */ /** - * g_action_get_state_hint: - * @action: a #GAction + * G_DEFINE_TYPE_EXTENDED: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. + * @_f_: #GTypeFlags to pass to g_type_register_static() + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Requests a hint about the valid range of values for the state of - * If %NULL is returned it either means that the action is not stateful - * or that there is no hint about the valid range of values for the - * state of the action. - * If a #GVariant array is returned then each item in the array is a - * returned then the tuple specifies the inclusive lower and upper bound - * of valid values for the state. - * In any case, the information is merely a hint. It may be possible to - * have a state value outside of the hinted range and setting a value - * within the range may fail. - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. + * The most general convenience macro for type implementations, on which + * G_DEFINE_TYPE(), etc are based. + * |[ + * G_DEFINE_TYPE_EXTENDED (GtkGadget, + * gtk_gadget, + * GTK_TYPE_WIDGET, + * 0, + * G_IMPLEMENT_INTERFACE (TYPE_GIZMO, + * gtk_gadget_gizmo_init)); + * ]| + * expands to + * |[ + * static void gtk_gadget_init (GtkGadget *self); + * static void gtk_gadget_class_init (GtkGadgetClass *klass); + * static gpointer gtk_gadget_parent_class = NULL; + * static void gtk_gadget_class_intern_init (gpointer klass) + * { + * gtk_gadget_parent_class = g_type_class_peek_parent (klass); + * gtk_gadget_class_init ((GtkGadgetClass*) klass); + * } + * GType + * gtk_gadget_get_type (void) + * { + * static volatile gsize g_define_type_id__volatile = 0; + * if (g_once_init_enter (&g_define_type_id__volatile)) + * { + * GType g_define_type_id = + * g_type_register_static_simple (GTK_TYPE_WIDGET, + * g_intern_static_string ("GtkGadget"), + * sizeof (GtkGadgetClass), + * (GClassInitFunc) gtk_gadget_class_intern_init, + * sizeof (GtkGadget), + * (GInstanceInitFunc) gtk_gadget_init, + * (GTypeFlags) flags); + * { + * static const GInterfaceInfo g_implement_interface_info = { + * (GInterfaceInitFunc) gtk_gadget_gizmo_init + * }; + * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); + * } + * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); + * } + * return g_define_type_id__volatile; + * } + * ]| + * The only pieces which have to be manually provided are the definitions of + * the instance and class structure and the definitions of the instance and + * class init functions. * - * Possible value for the state. if a #gvariant pair (ie: two-tuple) is - * Returns: (transfer full): the state range hint - * Since: 2.28 + * Since: 2.4 */ /** - * g_action_group_activate_action: - * @action_group: a #GActionGroup - * @action_name: the name of the action to activate - * @parameter: (allow-none): parameters to the activation + * G_DEFINE_TYPE_WITH_CODE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Activate the named action within @action_group. - * If the action is expecting a parameter, then the correct type of - * parameter must be given as @parameter. If the action is expecting no - * parameters then @parameter must be %NULL. See - * g_action_group_get_parameter_type(). + * A convenience macro for type implementations. + * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the + * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). + * See G_DEFINE_TYPE_EXTENDED() for an example. * - * Since: 2.28 + * Since: 2.4 */ /** - * g_main_quit: - * @loop: a #GMainLoop + * G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME: * - * Stops the #GMainLoop. - * If g_main_run() was called to run the #GMainLoop, it will now return. + * Extension point for default handler to URI association. See + * <link linkend="extending-gio">Extending GIO</link>. + */ + + +/** + * G_ENUM_CLASS: + * @class: a valid #GEnumClass * - * Deprecated: 2.2: Use g_main_loop_quit() instead + * Casts a derived #GEnumClass structure into a #GEnumClass structure. */ /** - * g_file_info_get_edit_name: - * @info: a #GFileInfo. + * G_ENUM_CLASS_TYPE: + * @class: a #GEnumClass * - * Gets the edit name for a file. + * Get the type identifier from a given #GEnumClass structure. * - * Returns: a string containing the edit name. + * Returns: the #GType */ /** - * g_dbus_address_get_stream: - * @address: A valid D-Bus address. - * @cancellable: A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: Data to pass to @callback. + * G_ENUM_CLASS_TYPE_NAME: + * @class: a #GEnumClass * - * Asynchronously connects to an endpoint specified by @address and - * sets up the connection so it is in a state to run the client-side - * of the D-Bus authentication conversation. - * When the operation is finished, @callback will be invoked. You can - * then call g_dbus_address_get_stream_finish() to get the result of - * the operation. - * This is an asynchronous failable function. See - * g_dbus_address_get_stream_sync() for the synchronous version. + * Get the static type name from a given #GEnumClass structure. * - * Since: 2.26 + * Returns: the type name. */ /** - * G_PARAM_SPEC_PARAM: - * @pspec: a valid #GParamSpec instance + * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE: * - * Casts a #GParamSpec instance into a #GParamSpecParam. + * A key in the "access" namespace for checking deletion privileges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This attribute will be %TRUE if the user is able to delete the file. */ /** - * G_VALUE_HOLDS_VARIANT: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. + * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE: * - * Returns: %TRUE on success. - * Since: 2.26 + * A key in the "access" namespace for getting execution privileges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This attribute will be %TRUE if the user is able to execute the file. */ /** - * SECTION:gunixsocketaddres: - * @short_description: UNIX GSocketAddress - * @include: gio/gunixsocketaddress.h + * G_FILE_ATTRIBUTE_ACCESS_CAN_READ: * - * Support for UNIX-domain (also known as local) sockets. - * UNIX domain sockets are generally visible in the filesystem. - * However, some systems support abstract socket names which are not - * visible in the filesystem and not affected by the filesystem - * permissions, visibility, etc. Currently this is only supported - * under Linux. If you attempt to use abstract sockets on other - * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED - * errors. You can use g_unix_socket_address_abstract_names_supported() - * to see if abstract names are supported. - * Note that <filename><gio/gunixsocketaddress.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * A key in the "access" namespace for getting read privileges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This attribute will be %TRUE if the user is able to read the file. */ /** - * g_file_read: - * @file: #GFile to read. - * @cancellable: (allow-none): a #GCancellable - * @error: a #GError, or %NULL - * - * Opens a file for reading. The result is a #GFileInputStream that - * can be used to read the contents of the file. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. - * If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned. - * Other errors are possible too, and depend on what kind of filesystem the file is on. - * Free the returned object with g_object_unref(). + * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME: * - * Virtual: read_fn - * Returns: (transfer full): #GFileInputStream or %NULL on error. + * A key in the "access" namespace for checking renaming privileges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This attribute will be %TRUE if the user is able to rename the file. */ /** - * GVolumeMonitor::volume-added: - * @volume_monitor: The volume monitor emitting the signal. - * @volume: a #GVolume that was added. + * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH: * - * Emitted when a mountable volume is added to the system. + * A key in the "access" namespace for checking trashing privileges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This attribute will be %TRUE if the user is able to move the file to + * the trash. */ /** - * GSource: + * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE: * - * The <structname>GSource</structname> struct is an opaque data type - * representing an event source. + * A key in the "access" namespace for getting write privileges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This attribute will be %TRUE if the user is able to write to the file. */ /** - * g_volume_monitor_get_connected_drives: - * @volume_monitor: a #GVolumeMonitor. - * - * Gets a list of drives connected to the system. - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). + * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE: * - * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects. + * A key in the "dos" namespace for checking if the file's archive flag + * is set. This attribute is %TRUE if the archive flag is set. This attribute + * is only available for DOS file systems. Corresponding #GFileAttributeType + * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * GDBusProxy::g-properties-changed: - * @proxy: The #GDBusProxy emitting the signal. - * @changed_properties: A #GVariant containing the properties that changed - * @invalidated_properties: A %NULL terminated array of properties that was invalidated - * - * Emitted when one or more D-Bus properties on @proxy changes. The - * local cache has already been updated when this signal fires. Note - * that both @changed_properties and @invalidated_properties are - * guaranteed to never be %NULL (either may be empty though). - * This signal corresponds to the - * <literal>PropertiesChanged</literal> D-Bus signal on the - * <literal>org.freedesktop.DBus.Properties</literal> interface. + * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM: * - * Since: 2.26 + * A key in the "dos" namespace for checking if the file's backup flag + * is set. This attribute is %TRUE if the backup flag is set. This attribute + * is only available for DOS file systems. Corresponding #GFileAttributeType + * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * g_simple_async_result_propagate_error: - * @simple: a #GSimpleAsyncResult. - * @dest: (out): a location to propagate the error to. - * - * Propagates an error from within the simple asynchronous result to - * a given destination. + * G_FILE_ATTRIBUTE_ETAG_VALUE: * - * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise. + * A key in the "etag" namespace for getting the value of the file's + * entity tag. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * g_file_replace_readwrite_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file replace operation started with - * g_file_replace_readwrite_async(). - * Free the returned object with g_object_unref(). + * G_FILE_ATTRIBUTE_FILESYSTEM_FREE: * - * Returns: (transfer full): a #GFileIOStream, or %NULL on error. - * Since: 2.22 + * A key in the "filesystem" namespace for getting the number of bytes of free space left on the + * file system. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT64. */ @@ -7439,1233 +6927,906 @@ /** - * g_settings_new: - * @schema: the name of the schema - * @returns: a new #GSettings object - * - * Creates a new #GSettings object with a given schema. - * Signals on the newly created #GSettings object will be dispatched - * via the thread-default #GMainContext in effect at the time of the - * call to g_settings_new(). The new #GSettings will hold a reference - * on the context. See g_main_context_push_thread_default(). + * G_FILE_ATTRIBUTE_FILESYSTEM_SIZE: * - * Since: 2.26 + * A key in the "filesystem" namespace for getting the total size (in bytes) of the file system, + * used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType + * is %G_FILE_ATTRIBUTE_TYPE_UINT64. */ /** - * GPollableInputStreamInterface: - * @g_iface: The parent interface. - * @can_poll: Checks if the #GPollableInputStream instance is actually pollable - * @is_readable: Checks if the stream is readable - * @create_source: Creates a #GSource to poll the stream - * @read_nonblocking: Does a non-blocking read or returns %G_IO_ERROR_WOULD_BLOCK - * - * The interface for pollable input streams. - * The default implementation of @can_poll always returns %TRUE. - * The default implementation of @read_nonblocking calls - * g_pollable_input_stream_is_readable(), and then calls - * g_input_stream_read() if it returns %TRUE. This means you only need - * to override it if it is possible that your @is_readable - * implementation may return %TRUE when the stream is not actually - * readable. + * G_FILE_ATTRIBUTE_FILESYSTEM_TYPE: * - * Since: 2.28 + * A key in the "filesystem" namespace for getting the file system's type. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * GUnixInputStream:fd: - * - * The file descriptor that the stream reads from. + * G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW: * - * Since: 2.20 + * A key in the "filesystem" namespace for hinting a file manager + * application whether it should preview (e.g. thumbnail) files on the + * file system. The value for this key contain a + * #GFilesystemPreviewType. */ /** - * g_io_module_query: - * - * Optional API for GIO modules to implement. - * Should return a list of all the extension points that may be - * implemented in this module. - * This method will not be called in normal use, however it may be - * called when probing existing modules and recording which extension - * points that this modle is used for. This means we won't have to - * load and initialze this module unless its needed. - * If this function is not implemented by the module the module will - * always be loaded, initialized and then unloaded on application startup - * so that it can register its extension points during init. - * Note that a module need not actually implement all the extension points - * that g_io_module_query returns, since the exact list of extension may - * depend on runtime issues. However all extension points actually implemented - * must be returned by g_io_module_query() (if defined). - * When installing a module that implements g_io_module_query you must - * run gio-querymodules in order to build the cache files required for - * lazy loading. - * extension points of the module. The array must be suitable for - * freeing with g_strfreev(). + * G_FILE_ATTRIBUTE_GVFS_BACKEND: * - * Returns: (transfer full): A %NULL-terminated array of strings, listing the supported - * Since: 2.24 + * A key in the "gvfs" namespace that gets the name of the current + * GVFS backend in use. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * g_file_io_stream_query_info_async: - * @stream: a #GFileIOStream. - * @attributes: a file attribute query string. - * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 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 - * - * Asynchronously queries the @stream for a #GFileInfo. When completed, - * finish the operation with g_file_io_stream_query_info_finish(). - * For the synchronous version of this function, see - * g_file_io_stream_query_info(). + * G_FILE_ATTRIBUTE_ID_FILE: * - * Since: 2.22 + * A key in the "id" namespace for getting a file identifier. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * An example use would be during listing files, to avoid recursive + * directory scanning. */ /** - * g_io_extension_point_register: - * @name: The name of the extension point - * - * Registers an extension point. - * and should not be freed + * G_FILE_ATTRIBUTE_ID_FILESYSTEM: * - * Returns: the new #GIOExtensionPoint. This object is owned by GIO + * A key in the "id" namespace for getting the file system identifier. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * An example use would be during drag and drop to see if the source + * and target are on the same filesystem (default to move) or not (default + * to copy). */ /** - * g_vfs_get_file_for_uri: - * @vfs: a#GVfs. - * @uri: a string containing a URI - * - * Gets a #GFile for @uri. - * This operation never fails, but the returned object - * might not support any I/O operation if the URI - * is malformed or if the URI scheme is not supported. - * Free the returned object with g_object_unref(). + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT: * - * Returns: (transfer full): a #GFile. + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * g_simple_async_result_new_from_error: - * @source_object: (allow-none): a #GObject, or %NULL. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * @error: a #GError - * - * Creates a #GSimpleAsyncResult from an error condition. + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT: * - * Returns: a #GSimpleAsyncResult. + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * g_main_iteration: - * @may_block: set to %TRUE if it should block (i.e. wait) until an event source becomes ready. It will return after an event source has been processed. If set to %FALSE it will return immediately if no event source is ready to be processed. + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL: * - * Runs a single iteration for the default #GMainContext. + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * - * Returns: %TRUE if more events are pending. - * Deprecated: 2.2: Use g_main_context_iteration() instead. + * Since: 2.22 */ /** - * G_TYPE_PARAM_GTYPE: + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START: * - * The #GType of #GParamSpecGType. + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * - * Since: 2.10 + * Since: 2.22 */ /** - * g_file_info_get_sort_order: - * @info: a #GFileInfo. + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED: * - * Gets the value of the sort_order attribute from the #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started + * degraded. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * - * Returns: a #gint32 containing the value of the "standard::sort_order" attribute. + * Since: 2.22 */ /** - * g_themed_icon_new: - * @iconname: a string containing an icon name. + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP: * - * Creates a new themed icon for @iconname. + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * - * Returns: (transfer full): a new #GThemedIcon. + * Since: 2.22 */ /** - * GVariantType: + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT: * - * A type in the GVariant type system. - * Two types may not be compared by value; use g_variant_type_equal() or - * g_variant_type_is_subtype(). May be copied using - * g_variant_type_copy() and freed using g_variant_type_free(). + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * g_dbus_message_get_unix_fd_list: - * @message: A #GDBusMessage. - * - * Gets the UNIX file descriptors associated with @message, if any. - * This method is only available on UNIX. - * associated. Do not free, this object is owned by @message. + * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI: * - * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are - * Since: 2.26 + * A key in the "mountable" namespace for getting the HAL UDI for the mountable + * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * g_action_get_state_type: - * @action: a #GAction + * G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC: * - * Queries the type of the state of @action. - * g_action_new_stateful()) then this function returns the #GVariantType - * of the state. This is the type of the initial value given as the - * state. All calls to g_action_set_state() must give a #GVariant of - * this type and g_action_get_state() will return a #GVariant of the - * same type. - * this function will return %NULL. In that case, g_action_get_state() - * will return %NULL and you must not call g_action_set_state(). + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) + * is automatically polled for media. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * - * If the action is stateful (ie: was created with - * If the action is not stateful (ie: created with g_action_new()) then - * Returns: (allow-none): the state type, if the action is stateful - * Since: 2.28 + * Since: 2.22 */ /** - * g_dbus_proxy_new_for_bus_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus(). - * @error: Return location for error or %NULL. + * G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE: * - * Finishes creating a #GDBusProxy. + * A key in the "mountable" namespace for getting the #GDriveStartStopType. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * - * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). - * Since: 2.26 + * Since: 2.22 */ /** - * g_unix_mount_guess_can_eject: - * @mount_entry: a #GUnixMountEntry - * - * Guesses whether a Unix mount can be ejected. + * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE: * - * Returns: %TRUE if @mount_entry is deemed to be ejectable. + * A key in the "mountable" namespace for getting the unix device. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * g_drive_stop_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE: * - * Finishes stopping a drive. - * %FALSE otherwise. + * A key in the "mountable" namespace for getting the unix device file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * - * Returns: %TRUE if the drive has been stopped successfully, * Since: 2.22 */ /** - * g_memory_output_stream_new: (skip) - * @data: pointer to a chunk of memory to use, or %NULL - * @size: the size of @data - * @realloc_function: a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL - * @destroy_function: a function to be called on @data when the stream is finalized, or %NULL - * - * Creates a new #GMemoryOutputStream. - * If @data is non-%NULL, the stream will use that for its internal storage. - * If @realloc_fn is non-%NULL, it will be used for resizing the internal - * storage when necessary. To construct a fixed-size output stream, - * pass %NULL as @realloc_fn. - * |[ - * /* a stream that can grow */ - * stream = g_memory_output_stream_new (NULL, 0, realloc, free); - * /* another stream that can grow */ - * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); - * /* a fixed-size stream */ - * data = malloc (200); - * stream3 = g_memory_output_stream_new (data, 200, NULL, free); - * ]| + * G_FILE_ATTRIBUTE_OWNER_GROUP: * - * Returns: A newly created #GMemoryOutputStream object. + * A key in the "owner" namespace for getting the file owner's group. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * g_buffered_output_stream_set_buffer_size: - * @stream: a #GBufferedOutputStream. - * @size: a #gsize. + * G_FILE_ATTRIBUTE_OWNER_USER: * - * Sets the size of the internal buffer to @size. + * A key in the "owner" namespace for getting the user name of the + * file's owner. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * GDBusConnection: - * - * The #GDBusConnection structure contains only private data and - * should only be accessed using the provided API. + * G_FILE_ATTRIBUTE_OWNER_USER_REAL: * - * Since: 2.26 + * A key in the "owner" namespace for getting the real name of the + * user that owns the file. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * g_proxy_address_get_passwor: - * @proxy: a #GProxyAddress + * G_FILE_ATTRIBUTE_PREVIEW_ICON: * - * Gets @proxy's password. + * A key in the "preview" namespace for getting a #GIcon that can be + * used to get preview of the file. For example, it may be a low + * resolution thumbnail without metadata. Corresponding + * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value + * for this key should contain a #GIcon. * - * Returns: the @proxy's password - * Since: 2.26 + * Since: 2.20 */ /** - * g_file_replace_contents_async: - * @file: input #GFile. - * @contents: string of contents to replace the file with. - * @length: the length of @contents in bytes. - * @etag: (allow-none): a new <link linkend="gfile-etag">entity tag</link> for the @file, or %NULL - * @make_backup: %TRUE if a backup should be created. - * @flags: a set of #GFileCreateFlags. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to callback function + * G_FILE_ATTRIBUTE_SELINUX_CONTEXT: * - * Starts an asynchronous replacement of @file with the given - * current entity tag. - * When this operation has completed, @callback will be called with - * g_file_replace_contents_finish(). - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If @make_backup is %TRUE, this function will attempt to - * make a backup of @file. + * A key in the "selinux" namespace for getting the file's SELinux + * context. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only + * available if GLib has been built with SELinux support. */ /** - * GDBusProxyFlags: - * @G_DBUS_PROXY_FLAGS_NONE: No flags set. - * @G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES: Don't load properties. - * @G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS: Don't connect to signals on the remote object. - * @G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START: If not set and the proxy if for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only be used in proxies for well-known names. + * G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE: * - * Flags used when constructing an instance of a #GDBusProxy derived class. + * A key in the "standard" namespace for getting the amount of disk space + * that is consumed by the file (in bytes). This will generally be larger + * than the file size (due to block size overhead) but can occasionally be + * smaller (for example, for sparse files). + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. * - * Since: 2.26 + * Since: 2.20 */ /** - * g_file_info_get_attribute_object: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a #GObject attribute. If the attribute does - * not contain a #GObject, %NULL will be returned. - * %NULL otherwise. + * G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE: * - * Returns: (transfer none): a #GObject associated with the given @attribute, or + * A key in the "standard" namespace for getting the content type of the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * The value for this key should contain a valid content type. */ /** - * GBookmarkFileError: - * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed - * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found - * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not register a bookmark - * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found - * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed - * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding - * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing - * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found + * G_FILE_ATTRIBUTE_STANDARD_COPY_NAME: * - * Error codes returned by bookmark file parsing. + * A key in the "standard" namespace for getting the copy name of the file. + * The copy name is an optional version of the name. If available it's always + * in UTF8, and corresponds directly to the original filename (only transcoded to + * UTF8). This is useful if you want to copy the file to another filesystem that + * might have a different encoding. If the filename is not a valid string in the + * encoding selected for the filesystem it is in then the copy name will not be set. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * GSocketProtocol: - * @G_SOCKET_PROTOCOL_UNKNOWN: The protocol type is unknown - * @G_SOCKET_PROTOCOL_DEFAULT: The default protocol for the family/type - * @G_SOCKET_PROTOCOL_TCP: TCP over IP - * @G_SOCKET_PROTOCOL_UDP: UDP over IP - * @G_SOCKET_PROTOCOL_SCTP: SCTP over IP - * - * A protocol identifier is specified when creating a #GSocket, which is a - * family/type specific identifier, where 0 means the default protocol for - * the particular family/type. - * This enum contains a set of commonly available and used protocols. You - * can also pass any other identifiers handled by the platform in order to - * use protocols not listed here. + * G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION: * - * Since: 2.22 + * A key in the "standard" namespace for getting the description of the file. + * The description is a utf8 string that describes the file, generally containing + * the filename, but can also contain furter information. Example descriptions + * could be "filename (on hostname)" for a remote file or "filename (in trash)" + * for a file in the trash. This is useful for instance as the window title + * when displaying a directory or for a bookmarks menu. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * g_action_set_state: - * @action: a #GAction - * @value: the new state - * - * Request for the state of @action to be changed to @value. - * The action must be stateful and @value must be of the correct type. - * See g_action_get_state_type(). - * This call merely requests a change. The action may refuse to change - * its state or may change its state to something other than @value. - * See g_action_get_state_hint(). - * If the @value GVariant is floating, it is consumed. + * G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME: * - * Since: 2.28 + * A key in the "standard" namespace for getting the display name of the file. + * A display name is guaranteed to be in UTF8 and can thus be displayed in + * the UI. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * g_file_replace_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file replace operation started with - * g_file_replace_async(). - * Free the returned object with g_object_unref(). + * G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME: * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * A key in the "standard" namespace for edit name of the file. + * An edit name is similar to the display name, but it is meant to be + * used when you want to rename the file in the UI. The display name + * might contain information you don't want in the new filename (such as + * "(invalid unicode)" if the filename was in an invalid encoding). + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * g_file_has_parent: - * @file: input #GFile - * @parent: the parent to check for, or %NULL - * - * Checks if @file has a parent, and optionally, if it is @parent. - * If @parent is %NULL then this function returns %TRUE if @file has any - * parent at all. If @parent is non-%NULL then %TRUE is only returned - * if @file is a child of @parent. - * case that @parent is %NULL). + * G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE: * - * Returns: %TRUE if @file is a child of @parent (or any parent in the - * Since: 2.24 + * A key in the "standard" namespace for getting the fast content type. + * The fast content type isn't as reliable as the regular one, as it + * only uses the filename to guess it, but it is faster to calculate than the + * regular content type. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * g_dbus_is_supported_address: - * @string: A string. - * @error: Return location for error or %NULL. - * - * Like g_dbus_is_address() but also checks if the library suppors the - * transports in @string and that key/value pairs for each transport - * are valid. - * supported by this library, %FALSE if @error is set. + * G_FILE_ATTRIBUTE_STANDARD_ICON: * - * Returns: %TRUE if @string is a valid D-Bus address that is - * Since: 2.26 + * A key in the "standard" namespace for getting the icon for the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. + * The value for this key should contain a #GIcon. */ /** - * g_socket_connection_get_remote_address: - * @connection: a #GSocketConnection - * @error: #GError for error reporting, or %NULL to ignore. - * - * Try to get the remote address of a socket connection. - * Free the returned object with g_object_unref(). + * G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP: * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Since: 2.22 + * A key in the "standard" namespace for checking if a file is a backup file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * GParamSpecUInt64: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN: * - * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. + * A key in the "standard" namespace for checking if a file is hidden. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * g_dbus_message_new_method_call: - * @name: A valid D-Bus name or %NULL. - * @path: A valid object path. - * @interface_: A valid D-Bus interface name or %NULL. - * @method: A valid method name. - * - * Creates a new #GDBusMessage for a method call. + * G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK: * - * Returns: A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * A key in the "standard" namespace for checking if the file is a symlink. + * Typically the actual type is something else, if we followed the symlink + * to get the type. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * g_simple_async_result_new_error: - * @source_object: (allow-none): a #GObject, or %NULL. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * @domain: a #GQuark. - * @code: an error code. - * @format: a string with format characters. - * @...: a list of values to insert into @format. - * - * Creates a new #GSimpleAsyncResult with a set error. + * G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL: * - * Returns: a #GSimpleAsyncResult. + * A key in the "standard" namespace for checking if a file is virtual. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * g_simple_async_report_take_gerror_in_idle: (skip) - * @object: (allow-none): a #GObject, or %NULL - * @callback: a #GAsyncReadyCallback. - * @user_data: user data passed to @callback. - * @error: the #GError to report - * - * Reports an error in an idle function. Similar to - * g_simple_async_report_gerror_in_idle(), but takes over the caller's - * ownership of @error, so the caller does not have to free it any more. + * G_FILE_ATTRIBUTE_STANDARD_NAME: * - * Since: 2.28 + * A key in the "standard" namespace for getting the name of the file. + * The name is the on-disk filename which may not be in any known encoding, + * and can thus not be generally displayed as is. + * Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the + * name in a user interface. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. */ /** - * g_file_unmount_mountable_finish: - * @file: input #GFile. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes an unmount operation, see g_file_unmount_mountable() for details. - * Finish an asynchronous unmount operation that was started - * with g_file_unmount_mountable(). - * otherwise. + * G_FILE_ATTRIBUTE_STANDARD_SIZE: * - * Returns: %TRUE if the operation finished successfully. %FALSE - * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead. + * A key in the "standard" namespace for getting the file's size (in bytes). + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. */ /** - * G_TYPE_IS_DERIVED: - * @type: A #GType value. - * - * Checks if @type is derived (or in object-oriented terminology: - * inherited) from another type (this holds true for all non-fundamental - * types). + * G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER: * - * Returns: %TRUE on success. + * A key in the "standard" namespace for setting the sort order of a file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32. + * An example use would be in file managers, which would use this key + * to set the order files are displayed. Files with smaller sort order + * should be sorted first, and files without sort order as if sort order + * was zero. */ /** - * GTypePluginUse: - * @plugin: the #GTypePlugin whose use count should be increased + * G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET: * - * The type of the @use_plugin function of #GTypePluginClass, which gets called - * to increase the use count of @plugin. + * A key in the "standard" namespace for getting the symlink target, if the file + * is a symlink. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. */ /** - * G_OBJECT_GET_CLASS: - * @object: a #GObject instance. - * - * Get the class structure associated to a #GObject instance. + * G_FILE_ATTRIBUTE_STANDARD_TARGET_URI: * - * Returns: pointer to object class structure. + * A key in the "standard" namespace for getting the target URI for the file, in + * the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. */ /** - * G_TYPE_IS_DERIVABLE: - * @type: A #GType value. - * - * Checks if @type is a derivable type. A derivable type can - * be used as the base class of a flat (single-level) class hierarchy. + * G_FILE_ATTRIBUTE_STANDARD_TYPE: * - * Returns: %TRUE on success. + * A key in the "standard" namespace for storing file types. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * The value for this key should contain a #GFileType. */ /** - * g_app_info_can_remove_supports_type: - * @appinfo: a #GAppInfo. - * - * Checks if a supported content type can be removed from an application. - * content types from a given @appinfo, %FALSE if not. + * G_FILE_ATTRIBUTE_THUMBNAILING_FAILED: * - * Returns: %TRUE if it is possible to remove supported + * A key in the "thumbnail" namespace for checking if thumbnailing failed. + * This attribute is %TRUE if thumbnailing failed. Corresponding + * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * G_PARAM_SPEC_INT: - * @pspec: a valid #GParamSpec instance + * G_FILE_ATTRIBUTE_THUMBNAIL_PATH: * - * Cast a #GParamSpec instance into a #GParamSpecInt. + * A key in the "thumbnail" namespace for getting the path to the thumbnail + * image. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. */ /** - * g_input_stream_read_finish: - * @stream: a #GInputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. - * - * Finishes an asynchronous stream read operation. + * G_FILE_ATTRIBUTE_TIME_ACCESS: * - * Returns: number of bytes read in, or -1 on error. + * A key in the "time" namespace for getting the time the file was last + * accessed. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the + * file was last accessed. */ /** - * g_tls_connection_get_rehandshake_mode: - * @conn: a #GTlsConnection - * - * Gets @conn rehandshaking mode. See - * g_tls_connection_set_rehandshake() for details. + * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC: * - * Returns: @conn's rehandshaking mode - * Since: 2.28 + * A key in the "time" namespace for getting the microseconds of the time + * the file was last accessed. This should be used in conjunction with + * #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * G_TYPE_RESERVED_BSE_FIRST: + * G_FILE_ATTRIBUTE_TIME_CHANGED: * - * First fundamental type number to create a new fundamental type id with - * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. + * A key in the "time" namespace for getting the time the file was last + * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, + * and contains the UNIX time since the file was last changed. + * This corresponds to the traditional UNIX ctime. */ /** - * g_node_first_child: - * @node: a #GNode - * - * Gets the first child of a #GNode. - * or has no children + * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC: * - * Returns: the first child of @node, or %NULL if @node is %NULL + * A key in the "time" namespace for getting the microseconds of the time + * the file was last changed. This should be used in conjunction with + * #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * g_dbus_signal_info_ref: - * @info: A #GDBusSignalInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * G_FILE_ATTRIBUTE_TIME_CREATED: * - * Returns: The same @info. - * Since: 2.26 + * A key in the "time" namespace for getting the time the file was created. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, + * and contains the UNIX time since the file was created. + * This corresponds to the NTFS ctime. */ /** - * g_main_set_poll_func: - * @func: the function to call to poll all file descriptors - * - * Sets the function to use for the handle polling of file descriptors - * for the default main context. + * G_FILE_ATTRIBUTE_TIME_CREATED_USEC: * - * Deprecated: 2.2: Use g_main_context_set_poll_func() again + * A key in the "time" namespace for getting the microseconds of the time + * the file was created. This should be used in conjunction with + * #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * 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 occuring, or %NULL to ignore. - * - * Loads a loadable icon. For the asynchronous version of this function, - * see g_loadable_icon_load_async(). + * G_FILE_ATTRIBUTE_TIME_MODIFIED: * - * Returns: (transfer full): a #GInputStream to read the icon from. + * A key in the "time" namespace for getting the time the file was last + * modified. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the + * file was modified. */ /** - * G_PRIORITY_DEFAULT_IDLE: + * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC: * - * Use this for default priority idle functions. - * In GLib this priority is used when adding idle functions with - * g_idle_add(). + * A key in the "time" namespace for getting the miliseconds of the time + * the file was last modified. This should be used in conjunction with + * #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * GMountOperation:domain: + * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE: * - * The domain to use for the mount operation. + * A key in the "trash" namespace. When requested against + * items in "trash:///", will return the date and time when the file + * was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * + * Since: 2.24. */ /** - * g_socket_client_connect_to_uri_async: - * @client: a #GSocketClient - * @uri: a network uri - * @default_port: the default port to connect to - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * This is the asynchronous version of g_socket_client_connect_to_uri(). - * When the operation is finished @callback will be - * called. You can then call g_socket_client_connect_to_uri_finish() to get - * the result of the operation. + * G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT: * - * Since: 2.26 + * A key in the "trash" namespace. When requested against + * "trash:///" returns the number of (toplevel) items in the trash folder. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * g_app_info_delete: - * @appinfo: a #GAppInfo + * G_FILE_ATTRIBUTE_TRASH_ORIG_PATH: * - * Tries to delete a #GAppInfo. - * On some platforms, there may be a difference between user-defined - * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which - * cannot. See g_app_info_can_delete(). + * A key in the "trash" namespace. When requested against + * items in "trash:///", will return the original path to the file before it + * was trashed. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_STRING. * - * Virtual: do_delete - * Returns: %TRUE if @appinfo has been deleted - * Since: 2.20 + * Since: 2.24. */ /** - * g_socket_client_get_tls_validation_flags: - * @client: a #GSocketClient. - * - * Gets the TLS validation flags used creating TLS connections via + * G_FILE_ATTRIBUTE_UNIX_BLOCKS: * - * Returns: the TLS validation flags - * Since: 2.28 + * A key in the "unix" namespace for getting the number of blocks allocated + * for the file. This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. */ /** - * GTlsConnection:require-close-notify: - * - * Whether or not proper TLS close notification is required. - * See g_tls_connection_set_require_close_notify(). + * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE: * - * Since: 2.28 + * A key in the "unix" namespace for getting the block size for the file + * system. This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * g_socket_control_message_get_level: - * @message: a #GSocketControlMessage - * - * Returns the "level" (i.e. the originating protocol) of the control message. - * This is often SOL_SOCKET. + * G_FILE_ATTRIBUTE_UNIX_DEVICE: * - * Returns: an integer describing the level - * Since: 2.22 + * A key in the "unix" namespace for getting the device id of the device the + * file is located on (see stat() documentation). This attribute is only + * available for UNIX file systems. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * G_TYPE_VARIANT_TYPE: - * - * The #GType for a boxed type holding a #GVariantType. + * G_FILE_ATTRIBUTE_UNIX_GID: * - * Since: 2.24 + * A key in the "unix" namespace for getting the group ID for the file. + * This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * GObjectClass: - * @g_type_class: the parent class - * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons. - * @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system. - * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties. - * @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class. - * @finalize: instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class. - * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed. - * @notify: the class closure for the notify signal - * @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation. + * G_FILE_ATTRIBUTE_UNIX_INODE: * - * The class structure for the <structname>GObject</structname> type. - * <example> - * <title>Implementing singletons using a constructor</title> - * <programlisting> - * static MySingleton *the_singleton = NULL; - * static GObject* - * my_singleton_constructor (GType type, - * guint n_construct_params, - * GObjectConstructParam *construct_params) - * { - * GObject *object; - * if (!the_singleton) - * { - * object = G_OBJECT_CLASS (parent_class)->constructor (type, - * n_construct_params, - * construct_params); - * the_singleton = MY_SINGLETON (object); - * } - * else - * object = g_object_ref (G_OBJECT (the_singleton)); - * return object; - * } - * </programlisting></example> + * A key in the "unix" namespace for getting the inode of the file. + * This attribute is only available for UNIX file systems. Corresponding + * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. */ /** - * GRegexEvalCallback: - * @match_info: the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string. - * @result: a #GString containing the new string - * @user_data: user data passed to g_regex_replace_eval() - * - * Specifies the type of the function passed to g_regex_replace_eval(). - * It is called for each occurance of the pattern in the string passed - * to g_regex_replace_eval(), and it should append the replacement to + * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT: * - * Returns: %FALSE to continue the replacement process, %TRUE to stop it - * Since: 2.14 + * A key in the "unix" namespace for checking if the file represents a + * UNIX mount point. This attribute is %TRUE if the file is a UNIX mount + * point. This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. */ /** - * SECTION:gdbusutil: - * @title: D-Bus Utilities - * @short_description: Various utilities related to D-Bus. - * @include: gio/gio.h + * G_FILE_ATTRIBUTE_UNIX_MODE: * - * Various utility routines related to D-Bus. + * A key in the "unix" namespace for getting the mode of the file + * (e.g. whether the file is a regular file, symlink, etc). See lstat() + * documentation. This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * g_node_insert_data_before: - * @parent: the #GNode to place the new #GNode under - * @sibling: the sibling #GNode to place the new #GNode before - * @data: the data for the new #GNode - * - * Inserts a new #GNode before the given sibling. + * G_FILE_ATTRIBUTE_UNIX_NLINK: * - * Returns: the new #GNode + * A key in the "unix" namespace for getting the number of hard links + * for a file. See lstat() documentation. This attribute is only available + * for UNIX file systems. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * g_file_info_get_attribute_boolean: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a boolean attribute. If the attribute does not - * contain a boolean value, %FALSE will be returned. + * G_FILE_ATTRIBUTE_UNIX_RDEV: * - * Returns: the boolean value contained within the attribute. + * A key in the "unix" namespace for getting the device ID for the file + * (if it is a special file). See lstat() documentation. This attribute + * is only available for UNIX file systems. Corresponding #GFileAttributeType + * is %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * g_mount_operation_set_domain: - * @op: a #GMountOperation. - * @domain: the domain to set. + * G_FILE_ATTRIBUTE_UNIX_UID: * - * Sets the mount operation's domain. + * A key in the "unix" namespace for getting the user ID for the file. + * This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. */ /** - * GTypeValueTable: - * @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]| - * @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]| - * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]| - * @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]| - * @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i' needs to be used, and for collection of floats 'd'. - * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined. - * @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations. - * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]| + * G_FLAGS_CLASS: + * @class: a valid #GFlagsClass * - * The #GTypeValueTable provides the functions required by the #GValue implementation, - * to serve as a container for values of a type. + * Casts a derived #GFlagsClass structure into a #GFlagsClass structure. */ /** - * g_try_renew: - * @struct_type: the type of the elements to allocate - * @mem: the currently allocated memory - * @n_structs: the number of elements to allocate + * G_FLAGS_CLASS_TYPE: + * @class: a #GFlagsClass * - * Attempts to reallocate the memory pointed to by @mem, so that it now has - * space for @n_structs elements of type @struct_type, and returns %NULL on - * failure. Contrast with g_renew(), which aborts the program on failure. - * It returns the new address of the memory, which may have been moved. - * The function returns %NULL if an overflow occurs. + * Get the type identifier from a given #GFlagsClass structure. * - * Since: 2.8 - * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type + * Returns: the #GType */ /** - * g_unix_mount_point_is_loopback: - * @mount_point: a #GUnixMountPoint. + * G_FLAGS_CLASS_TYPE_NAME: + * @class: a #GFlagsClass * - * Checks if a unix mount point is a loopback device. + * Get the static type name from a given #GFlagsClass structure. * - * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise. + * Returns: the type name. */ /** - * g_mount_operation_get_password: - * @op: a #GMountOperation. + * G_IMPLEMENT_INTERFACE: + * @TYPE_IFACE: The #GType of the interface to add + * @iface_init: The interface init function * - * Gets a password from the mount operation. + * A convenience macro to ease interface addition in the @_C_ section + * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). + * See G_DEFINE_TYPE_EXTENDED() for an example. + * Note that this macro can only be used together with the G_DEFINE_TYPE_* + * macros, since it depends on variable names from those macros. * - * Returns: a string containing the password within @op. + * Since: 2.4 */ /** - * SECTION:gfilenamecomplete: - * @short_description: Filename Completer - * @include: gio/gio.h + * G_IMPLEMENT_INTERFACE_DYNAMIC: + * @TYPE_IFACE: The #GType of the interface to add + * @iface_init: The interface init function * - * Completes partial file and directory names given a partial string by - * looking in the file system for clues. Can return a list of possible - * completion strings for widget implementations. + * A convenience macro to ease interface addition in the @_C_ section + * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() + * for an example. + * Note that this macro can only be used together with the + * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable + * names from that macro. + * + * Since: 2.24 */ /** - * G_TYPE_PARAM_CHAR: + * G_INITIALLY_UNOWNED: + * @object: Object which is subject to casting. * - * The #GType of #GParamSpecChar. + * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) + * pointer. Depending on the current debugging level, this function may invoke + * certain runtime checks to identify invalid casts. */ /** - * g_dbus_message_get_interface: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. + * G_INITIALLY_UNOWNED_CLASS: + * @class: a valid #GInitiallyUnownedClass * - * Returns: The value. - * Since: 2.26 + * Casts a derived #GInitiallyUnownedClass structure into a + * #GInitiallyUnownedClass structure. */ /** - * g_content_types_get_registered: + * G_INITIALLY_UNOWNED_GET_CLASS: + * @object: a #GInitiallyUnowned instance. * - * Gets a list of strings containing all the registered content types - * known to the system. The list and its data should be freed using - * <programlisting> - * g_list_foreach (list, g_free, NULL); - * g_list_free (list); - * </programlisting> + * Get the class structure associated to a #GInitiallyUnowned instance. * - * Returns: (element-type utf8) (transfer full): #GList of the registered content types + * Returns: pointer to object class structure. */ /** - * g_dbus_interface_info_ref: - * @info: A #GDBusInterfaceInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * G_IO_ERROR: * - * Returns: The same @info. - * Since: 2.26 + * Error domain for GIO. Errors in this domain will be from the #GIOErrorEnum enumeration. + * See #GError for more information on error domains. */ /** - * GTypeClassCacheFunc: - * @cache_data: data that was given to the g_type_add_class_cache_func() call - * @g_class: The #GTypeClass structure which is unreferenced - * - * A callback function which is called when the reference count of a class - * drops to zero. It may use g_type_class_ref() to prevent the class from - * being freed. You should not call g_type_class_unref() from a - * #GTypeClassCacheFunc function to prevent infinite recursion, use - * g_type_class_unref_uncached() instead. - * The functions have to check the class id passed in to figure - * whether they actually want to cache the class of this type, since all - * classes are routed through the same #GTypeClassCacheFunc chain. - * called, %FALSE to continue. + * G_IS_ENUM_CLASS: + * @class: a #GEnumClass * - * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being + * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM + * or derived. */ /** - * GTimeType: - * @G_TIME_TYPE_STANDARD: the time is in local standard time - * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time - * @G_TIME_TYPE_UNIVERSAL: the time is in UTC + * G_IS_FLAGS_CLASS: + * @class: a #GFlagsClass * - * Disambiguates a given time in two ways. - * First, specifies if the given time is in universal or local time. - * Second, if the time is in local time, specifies if it is local - * standard time or local daylight time. This is important for the case - * where the same local time occurs twice (during daylight savings time - * transitions, for example). + * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS + * or derived. */ /** - * g_file_info_clear_status: - * @info: a #GFileInfo. + * G_IS_INITIALLY_UNOWNED: + * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. * - * Clears the status information from @info. + * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. */ /** - * g_file_eject_mountable: - * @file: input #GFile. - * @flags: flags affecting the operation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. - * @user_data: (closure): the data to pass to callback function - * - * Starts an asynchronous eject on a mountable. - * When this operation has completed, @callback will be called with - * g_file_eject_mountable_finish(). - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * G_IS_INITIALLY_UNOWNED_CLASS: + * @class: a #GInitiallyUnownedClass * - * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead. + * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type + * %G_TYPE_INITIALLY_UNOWNED or derived. */ /** - * g_dbus_message_get_member: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. + * G_IS_OBJECT: + * @object: Instance to check for being a %G_TYPE_OBJECT. * - * Returns: The value. - * Since: 2.26 + * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. */ /** - * GParamSpecULong: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_IS_OBJECT_CLASS: + * @class: a #GObjectClass * - * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. + * Checks whether @class "is a" valid #GObjectClass structure of type + * %G_TYPE_OBJECT or derived. */ /** - * SECTION:gfilterinputstrea: - * @short_description: Filter Input Stream - * @include: gio/gio.h + * G_IS_PARAM_SPEC: + * @pspec: a #GParamSpec * - * Base class for input stream implementations that perform some - * kind of filtering operation on a base stream. Typical examples - * of filtering operations are character set conversion, compression - * and byte order flipping. + * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM + * or derived. */ /** - * G_OBJECT_TYPE: - * @object: Object to return the type id for. + * G_IS_PARAM_SPEC_BOOLEAN: + * @pspec: a valid #GParamSpec instance * - * Get the type id of an object. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. * - * Returns: Type id of @object. + * Returns: %TRUE on success. */ /** - * G_VALUE_HOLDS: - * @value: A #GValue structure. - * @type: A #GType value. + * G_IS_PARAM_SPEC_BOXED: + * @pspec: a valid #GParamSpec instance * - * Checks if @value holds (or contains) a value of @type. - * This macro will also check for @value != %NULL and issue a - * warning if the check fails. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. * - * Returns: %TRUE if @value holds the @type. + * Returns: %TRUE on success. */ /** - * g_dbus_server_stop: - * @server: A #GDBusServer. + * G_IS_PARAM_SPEC_CHAR: + * @pspec: a valid #GParamSpec instance * - * Stops @server. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * GFileMonitor: + * G_IS_PARAM_SPEC_CLASS: + * @pclass: a #GParamSpecClass * - * Watches for changes to a file. + * Checks whether @pclass "is a" valid #GParamSpecClass structure of type + * %G_TYPE_PARAM or derived. */ /** - * g_tls_connection_emit_accept_certificate: - * @conn: a #GTlsConnection - * @peer_cert: the peer's #GTlsCertificate - * @errors: the problems with @peer_cert + * G_IS_PARAM_SPEC_DOUBLE: + * @pspec: a valid #GParamSpec instance * - * Used by #GTlsConnection implementations to emit the - * #GTlsConnection::accept-certificate signal. - * %TRUE to accept @peer_cert + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. * - * Returns: %TRUE if one of the signal handlers has returned - * Since: 2.28 + * Returns: %TRUE on success. */ /** - * g_file_replace_readwrite: - * @file: a #GFile - * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore - * @make_backup: %TRUE if a backup should be created - * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: return location for a #GError, or %NULL + * G_IS_PARAM_SPEC_ENUM: + * @pspec: a valid #GParamSpec instance * - * Returns an output stream for overwriting the file in readwrite mode, - * possibly creating a backup copy of the file first. If the file doesn't - * exist, it will be created. - * For details about the behaviour, see g_file_replace() which does the same - * thing but returns an output stream only. - * Note that in many non-local file cases read and write streams are not - * supported, so make sure you really need to do read and write streaming, - * rather than just opening for reading or writing. - * Free the returned object with g_object_unref(). + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. - * Since: 2.22 + * Returns: %TRUE on success. */ /** - * g_simple_permission_new: - * @allowed: %TRUE if the action is allowed - * @returns: the #GSimplePermission, as a #GPermission + * G_IS_PARAM_SPEC_FLAGS: + * @pspec: a valid #GParamSpec instance * - * Creates a new #GPermission instance that represents an action that is - * either always or never allowed. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * GOptionErrorFunc: - * @context: The active #GOptionContext - * @group: The group to which the function belongs - * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() - * @error: The #GError containing details about the parse error + * G_IS_PARAM_SPEC_FLOAT: + * @pspec: a valid #GParamSpec instance * - * The type of function to be used as callback when a parse error occurs. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. + * + * Returns: %TRUE on success. */ /** - * g_file_query_filesystem_info_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @error: a #GError. + * G_IS_PARAM_SPEC_GTYPE: + * @pspec: a #GParamSpec * - * Finishes an asynchronous filesystem info query. See - * g_file_query_filesystem_info_async(). - * Free the returned object with g_object_unref(). + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. * - * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. + * Since: 2.10 + * Returns: %TRUE on success. */ /** - * G_TYPE_FUNDAMENTAL: - * @type: A #GType value. + * G_IS_PARAM_SPEC_INT: + * @pspec: a valid #GParamSpec instance * - * The fundamental type which is the ancestor of @type. - * Fundamental types are types that serve as ultimate bases for the derived types, - * thus they are the roots of distinct inheritance hierarchies. - */ - - -/** - * GVolumeMonitor::mount-changed: - * @volume_monitor: The volume monitor emitting the signal. - * @mount: a #GMount that changed. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. * - * Emitted when a mount changes. + * Returns: %TRUE on success. */ /** - * g_volume_get_identifier: - * @volume: a #GVolume - * @kind: the kind of identifier to return + * G_IS_PARAM_SPEC_INT64: + * @pspec: a valid #GParamSpec instance * - * Gets the identifier of the given kind for @volume. - * See the <link linkend="volume-identifier">introduction</link> - * for more information about volume identifiers. - * requested identfier, or %NULL if the #GVolume - * doesn't have this kind of identifier + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. * - * Returns: a newly allocated string containing the + * Returns: %TRUE on success. */ /** - * g_tcp_connection_get_graceful_disconnect: - * @connection: a #GTcpConnection + * G_IS_PARAM_SPEC_LONG: + * @pspec: a valid #GParamSpec instance * - * Checks if graceful disconnects are used. See - * g_tcp_connection_set_graceful_disconnect(). + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. * - * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise - * Since: 2.22 + * Returns: %TRUE on success. */ @@ -8680,693 +7841,594 @@ /** - * SECTION:gzdecompresso: - * @short_description: Zlib decompressor - * @include: gio/gio.h + * G_IS_PARAM_SPEC_OVERRIDE: + * @pspec: a #GParamSpec * - * #GZlibDecompressor is an implementation of #GConverter that - * decompresses data compressed with zlib. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. + * + * Since: 2.4 + * Returns: %TRUE on success. */ /** - * G_IS_PARAM_SPEC_VALUE_ARRAY: + * G_IS_PARAM_SPEC_PARAM: * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. * * Returns: %TRUE on success. */ /** - * G_TYPE_ENUM: + * G_IS_PARAM_SPEC_POINTER: + * @pspec: a valid #GParamSpec instance * - * The fundamental type from which all enumeration types are derived. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. + * + * Returns: %TRUE on success. */ /** - * G_IS_PARAM_SPEC_BOXED: + * G_IS_PARAM_SPEC_STRING: * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. * * Returns: %TRUE on success. */ /** - * g_dbus_message_get_reply_serial: - * @message: A #GDBusMessage. + * G_IS_PARAM_SPEC_UCHAR: + * @pspec: a valid #GParamSpec instance * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. * - * Returns: The value. - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_tls_connection_get_use_system_certdb: - * @conn: a #GTlsConnection + * G_IS_PARAM_SPEC_UINT: + * @pspec: a valid #GParamSpec instance * - * Gets whether @conn uses the system certificate database to verify - * peer certificates. See g_tls_connection_set_use_system_certdb(). + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. * - * Returns: whether @conn uses the system certificate database - * Since: 2.28 + * Returns: %TRUE on success. */ /** - * g_emblem_get_origin: - * @emblem: a #GEmblem + * G_IS_PARAM_SPEC_UINT64: + * @pspec: a valid #GParamSpec instance * - * Gets the origin of the emblem. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. * - * Returns: (transfer none): the origin of the emblem - * Since: 2.18 + * Returns: %TRUE on success. */ /** - * GMemoryInputStream: + * G_IS_PARAM_SPEC_ULONG: + * @pspec: a valid #GParamSpec instance * - * Implements #GInputStream for arbitrary memory chunks. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. + * + * Returns: %TRUE on success. */ /** - * SECTION:gfiledescriptorbase: - * @short_description: Interface for file descriptor based IO - * @include: gio/gfiledescriptorbased.h - * @see_also: #GInputStream, #GOutputStream + * G_IS_PARAM_SPEC_UNICHAR: + * @pspec: a valid #GParamSpec instance * - * #GFileDescriptorBased is implemented by streams (implementations of - * #GInputStream or #GOutputStream) that are based on file descriptors. - * Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. * - * Since: 2.24 + * Returns: %TRUE on success. */ /** - * g_file_find_enclosing_mount_finish: - * @file: a #GFile - * @res: a #GAsyncResult - * @error: a #GError + * G_IS_PARAM_SPEC_VALUE_ARRAY: + * @pspec: a valid #GParamSpec instance * - * Finishes an asynchronous find mount request. - * See g_file_find_enclosing_mount_async(). - * Free the returned object with g_object_unref(). + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. * - * Returns: (transfer full): #GMount for given @file or %NULL on error. + * Returns: %TRUE on success. */ /** - * g_inet_address_get_is_site_local: - * @address: a #GInetAddress + * G_IS_PARAM_SPEC_VARIANT: + * @pspec: a #GParamSpec * - * Tests whether @address is a site-local address such as 10.0.0.1 - * (that is, the address identifies a host on a local network that can - * not be reached directly from the Internet, but which may have - * outgoing Internet connectivity via a NAT or firewall). + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. * - * Returns: %TRUE if @address is a site-local address. - * Since: 2.22 + * Returns: %TRUE on success + * Since: 2.26 */ /** - * GCancellable: + * G_IS_VALUE: + * @value: A #GValue structure. * - * Allows actions to be cancelled. + * Checks if @value is a valid and initialized #GValue structure. + * + * Returns: %TRUE on success. */ /** - * g_dbus_message_set_num_unix_fds: - * @message: A #GDBusMessage. - * @value: The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. + * G_MARKUP_ERROR: * - * Since: 2.26 + * Error domain for markup parsing. + * Errors in this domain will be from the #GMarkupError enumeration. + * See #GError for information on error domains. */ /** - * GWin32Mount: + * G_NODE_IS_LEAF: + * @node: a #GNode * - * Implementation of the #GMount interface for Win32 systems. + * Returns %TRUE if a #GNode is a leaf node. + * (i.e. it has no children) + * + * Returns: %TRUE if the #GNode is a leaf node */ /** - * G_TYPE_ARRAY: + * G_NODE_IS_ROOT: + * @node: a #GNode * - * The #GType for a boxed type holding a #GArray reference. + * Returns %TRUE if a #GNode is the root of a tree. + * (i.e. it has no parent or siblings) * - * Since: 2.22 + * Returns: %TRUE if the #GNode is the root of a tree */ /** - * g_file_copy_async: (skip) - * @source: input #GFile. - * @destination: destination #GFile - * @flags: set of #GFileCopyFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @progress_callback: function to callback with progress information - * @progress_callback_data: user data to pass to @progress_callback - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to callback function + * G_OBJECT: + * @object: Object which is subject to casting. * - * Copies the file @source to the location specified by @destination - * asynchronously. For details of the behaviour, see g_file_copy(). - * If @progress_callback is not %NULL, then that function that will be called - * just like in g_file_copy(), however the callback will run in the main loop, - * not in the thread that is doing the I/O operation. - * When the operation is finished, @callback will be called. You can then call - * g_file_copy_finish() to get the result of the operation. + * Casts a #GObject or derived pointer into a (GObject*) pointer. + * Depending on the current debugging level, this function may invoke + * certain runtime checks to identify invalid casts. */ /** - * G_FILE_ATTRIBUTE_UNIX_DEVICE: + * G_OBJECT_CLASS: + * @class: a valid #GObjectClass * - * A key in the "unix" namespace for getting the device id of the device the - * file is located on (see stat() documentation). This attribute is only - * available for UNIX file systems. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Casts a derived #GObjectClass structure into a #GObjectClass structure. */ /** - * G_TYPE_CHECK_VALUE: - * @value: a #GValue + * G_OBJECT_CLASS_NAME: + * @class: a valid #GObjectClass * - * Checks if @value has been initialized to hold values - * of a value type. - * This macro should only be used in type implementations. + * Return the name of a class structure's type. + * should not be freed. * - * Returns: %TRUE on success. + * Returns: Type name of @class. The string is owned by the type system and */ /** - * G_DEFINE_POINTER_TYPE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * G_OBJECT_CLASS_TYPE: + * @class: a valid #GObjectClass * - * A convenience macro for pointer type implementations, which defines a - * type_name_get_type() function registering the pointer type. + * Get the type id of a class structure. * - * Since: 2.26 + * Returns: Type id of @class. */ /** - * g_dbus_method_invocation_get_method_name: - * @invocation: A #GDBusMethodInvocation. + * G_OBJECT_GET_CLASS: + * @object: a #GObject instance. * - * Gets the name of the method that was invoked. + * Get the class structure associated to a #GObject instance. * - * Returns: A string. Do not free, it is owned by @invocation. - * Since: 2.26 + * Returns: pointer to object class structure. */ /** - * g_io_extension_ref_class: - * @extension: a #GIOExtension + * G_OBJECT_TYPE: + * @object: Object to return the type id for. * - * Gets a reference to the class for the type that is - * associated with @extension. + * Get the type id of an object. * - * Returns: (transfer full): the #GTypeClass for the type of @extension + * Returns: Type id of @object. */ /** - * GVolumeMonitor::mount-pre-unmount: - * @volume_monitor: The volume monitor emitting the signal. - * @mount: a #GMount that is being unmounted. + * G_OBJECT_TYPE_NAME: + * @object: Object to return the type name for. * - * Emitted when a mount is about to be removed. + * Get the name of an object's type. + * should not be freed. + * + * Returns: Type name of @object. The string is owned by the type system and */ /** - * GBoxedFreeFunc: - * @boxed: The boxed structure to be freed. + * G_OBJECT_WARN_INVALID_PROPERTY_ID: + * @object: the #GObject on which set_property() or get_property() was called + * @property_id: the numeric id of the property + * @pspec: the #GParamSpec of the property * - * This function is provided by the user and should free the boxed - * structure passed. + * This macro should be used to emit a standard warning about unexpected + * properties in set_property() and get_property() implementations. */ /** - * g_desktop_app_info_new_from_keyfile: - * @key_file: an opened #GKeyFile - * - * Creates a new #GDesktopAppInfo. + * G_OPTION_ERROR: * - * Returns: a new #GDesktopAppInfo or %NULL on error. - * Since: 2.18 + * Error domain for option parsing. Errors in this domain will + * be from the #GOptionError enumeration. See #GError for information on + * error domains. */ /** - * g_file_info_get_attribute_uint32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * G_OPTION_REMAINING: * - * Gets an unsigned 32-bit integer contained within the attribute. If the - * attribute does not contain an unsigned 32-bit integer, or is invalid, - * 0 will be returned. + * If a long option in the main group has this name, it is not treated as a + * regular option. Instead it collects all non-option arguments which would + * otherwise be left in <literal>argv</literal>. The option must be of type + * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY + * or %G_OPTION_ARG_FILENAME_ARRAY. + * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal> + * for leftover arguments has the advantage that GOption takes care of + * necessary encoding conversions for strings or filenames. * - * Returns: an unsigned 32-bit integer from the attribute. + * Since: 2.6 */ /** - * GSocket: - * - * A lowlevel network socket object. + * G_PARAM_MASK: * - * Since: 2.22 + * Mask containing the bits of #GParamSpec.flags which are reserved for GLib. */ /** - * g_dbus_server_is_active: - * @server: A #GDBusServer. - * - * Gets whether @server is active. + * G_PARAM_READWRITE: * - * Returns: %TRUE if server is active, %FALSE otherwise. - * Since: 2.26 + * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. */ /** - * g_application_set_inactivity_timeout: - * @application: a #GApplication - * @inactivity_timeout: the timeout, in milliseconds - * - * Sets the current inactivity timeout for the application. - * This is the amount of time (in milliseconds) after the last call to - * g_application_release() before the application stops running. - * This call has no side effects of its own. The value set here is only - * used for next time g_application_release() drops the use count to - * zero. Any timeouts currently in progress are not impacted. + * G_PARAM_SPEC: + * @pspec: a valid #GParamSpec * - * Returns: the timeout, in milliseconds - * Since: 2.28 + * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into + * a #GParamSpec object. */ /** - * GVolume::removed: + * G_PARAM_SPEC_BOOLEAN: + * @pspec: a valid #GParamSpec instance * - * This signal is emitted when the #GVolume have been removed. If - * the recipient is holding references to the object they should - * release them so the object can be finalized. + * Cast a #GParamSpec instance into a #GParamSpecBoolean. */ /** - * GDesktopAppLaunchCallback: - * @appinfo: a #GDesktopAppInfo - * @pid: Process identifier - * @user_data: User data + * G_PARAM_SPEC_BOXED: + * @pspec: a valid #GParamSpec instance * - * During invocation, g_desktop_app_info_launch_uris_as_manager() may - * create one or more child processes. This callback is invoked once - * for each, providing the process ID. + * Cast a #GParamSpec instance into a #GParamSpecBoxed. */ /** - * g_settings_set_flags: - * @settings: a #GSettings object - * @key: a key, within @settings - * @value: a flags value - * @returns: %TRUE, if the set succeeds + * G_PARAM_SPEC_CHAR: + * @pspec: a valid #GParamSpec instance * - * Looks up the flags type nicks for the bits specified by @value, puts - * them in an array of strings and writes the array to @key, withing - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or is not marked as a flags type, or for @value - * to contain any bits that are not value for the named type. - * After performing the write, accessing @key directly with - * g_settings_get_strv() will return an array of 'nicks'; one for each - * bit in @value. + * Cast a #GParamSpec instance into a #GParamSpecChar. */ /** - * g_drive_has_volumes: - * @drive: a #GDrive. - * - * Check if @drive has any mountable volumes. + * G_PARAM_SPEC_CLASS: + * @pclass: a valid #GParamSpecClass * - * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise. + * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. */ /** - * g_app_info_get_description: - * @appinfo: a #GAppInfo. - * - * Gets a human-readable description of an installed application. - * application @appinfo, or %NULL if none. + * G_PARAM_SPEC_DOUBLE: + * @pspec: a valid #GParamSpec instance * - * Returns: a string containing a description of the + * Cast a #GParamSpec instance into a #GParamSpecDouble. */ /** - * g_input_stream_close_async: - * @stream: A #GInputStream. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional cancellable object - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * G_PARAM_SPEC_ENUM: + * @pspec: a valid #GParamSpec instance * - * Requests an asynchronous closes of the stream, releasing resources related to it. - * When the operation is finished @callback will be called. - * You can then call g_input_stream_close_finish() to get the result of the - * operation. - * For behaviour details see g_input_stream_close(). - * The asyncronous methods have a default fallback that uses threads to implement - * asynchronicity, so they are optional for inheriting classes. However, if you - * override one you must override all. + * Cast a #GParamSpec instance into a #GParamSpecEnum. */ /** - * g_file_descriptor_based_get_fd: - * @fd_based: a #GFileDescriptorBased. - * - * Gets the underlying file descriptor. + * G_PARAM_SPEC_FLAGS: + * @pspec: a valid #GParamSpec instance * - * Returns: The file descriptor - * Since: 2.24 + * Cast a #GParamSpec instance into a #GParamSpecFlags. */ /** - * g_file_append_to: - * @file: input #GFile. - * @flags: a set of #GFileCreateFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * G_PARAM_SPEC_FLOAT: + * @pspec: a valid #GParamSpec instance * - * Gets an output stream for appending data to the file. If - * the file doesn't already exist it is created. - * By default files created are generally readable by everyone, - * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file - * will be made readable only to the current user, to the level that - * is supported on the target filesystem. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Some file systems don't allow all file names, and may - * return an %G_IO_ERROR_INVALID_FILENAME error. - * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be - * returned. Other errors are possible too, and depend on what kind of - * filesystem the file is on. - * Free the returned object with g_object_unref(). + * Cast a #GParamSpec instance into a #GParamSpecFloat. + */ + + +/** + * G_PARAM_SPEC_GET_CLASS: + * @pspec: a valid #GParamSpec * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * Retrieves the #GParamSpecClass of a #GParamSpec. */ /** - * g_data_input_stream_read_until_finish: - * @stream: a given #GDataInputStream. - * @result: the #GAsyncResult that was provided to the callback. - * @length: (out): a #gsize to get the length of the data read in. - * @error: #GError for error reporting. + * G_PARAM_SPEC_GTYPE: + * @pspec: a #GParamSpec * - * Finish an asynchronous call started by - * g_data_input_stream_read_until_async(). - * before encountering any of the stop characters. Set @length to - * a #gsize to get the length of the string. This function will - * return %NULL on an error. + * Casts a #GParamSpec into a #GParamSpecGType. * - * Since: 2.20 - * Returns: (transfer full): a string with the data that was read + * Since: 2.10 */ /** - * GType: + * G_PARAM_SPEC_INT: + * @pspec: a valid #GParamSpec instance * - * A numerical value which represents the unique identifier of a registered - * type. + * Cast a #GParamSpec instance into a #GParamSpecInt. */ /** - * GDrive: + * G_PARAM_SPEC_INT64: + * @pspec: a valid #GParamSpec instance * - * Opaque drive object. + * Cast a #GParamSpec instance into a #GParamSpecInt64. */ /** - * G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP: + * G_PARAM_SPEC_LONG: + * @pspec: a valid #GParamSpec instance * - * A key in the "standard" namespace for checking if a file is a backup file. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * Cast a #GParamSpec instance into a #GParamSpecLong. */ /** - * g_proxy_address_get_protocol: - * @proxy: a #GProxyAddress - * - * Gets @proxy's protocol. + * G_PARAM_SPEC_OBJECT: + * @pspec: a valid #GParamSpec instance * - * Returns: the @proxy's protocol - * Since: 2.26 + * Casts a #GParamSpec instance into a #GParamSpecObject. */ /** - * g_input_stream_set_pending: - * @stream: input stream - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * G_PARAM_SPEC_OVERRIDE: + * @pspec: a #GParamSpec * - * Sets @stream to have actions pending. If the pending flag is - * already set or @stream is closed, it will return %FALSE and set + * Casts a #GParamSpec into a #GParamSpecOverride. * - * Returns: %TRUE if pending was previously unset and is now set. + * Since: 2.4 */ /** - * g_main_pending: - * - * Checks if any events are pending for the default #GMainContext - * (i.e. ready to be processed). + * G_PARAM_SPEC_PARAM: + * @pspec: a valid #GParamSpec instance * - * Returns: %TRUE if any events are pending. - * Deprected: 2.2: Use g_main_context_pending() instead. + * Casts a #GParamSpec instance into a #GParamSpecParam. */ /** - * GIconv: + * G_PARAM_SPEC_POINTER: + * @pspec: a valid #GParamSpec instance * - * The <structname>GIConv</structname> struct wraps an - * iconv() conversion descriptor. It contains private data - * and should only be accessed using the following functions. + * Casts a #GParamSpec instance into a #GParamSpecPointer. */ /** - * g_application_command_line_get_is_remote: - * @cmdline: a #GApplicationCommandLine + * G_PARAM_SPEC_STRING: + * @pspec: a valid #GParamSpec instance * - * Determines if @cmdline represents a remote invocation. + * Casts a #GParamSpec instance into a #GParamSpecString. + */ + + +/** + * G_PARAM_SPEC_TYPE: + * @pspec: a valid #GParamSpec * - * Returns: %TRUE if the invocation was remote - * Since: 2.28 + * Retrieves the #GType of this @pspec. */ /** - * g_dbus_error_new_for_dbus_error: - * @dbus_error_name: D-Bus error name. - * @dbus_error_message: D-Bus error message. + * G_PARAM_SPEC_TYPE_NAME: + * @pspec: a valid #GParamSpec * - * Creates a #GError based on the contents of @dbus_error_name and - * Errors registered with g_dbus_error_register_error() will be looked - * up using @dbus_error_name and if a match is found, the error domain - * and code is used. Applications can use g_dbus_error_get_remote_error() - * to recover @dbus_error_name. - * If a match against a registered error is not found and the D-Bus - * error name is in a form as returned by g_dbus_error_encode_gerror() - * the error domain and code encoded in the name is used to - * create the #GError. Also, @dbus_error_name is added to the error message - * such that it can be recovered with g_dbus_error_get_remote_error(). - * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR - * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is - * added to the error message such that it can be recovered with - * g_dbus_error_get_remote_error(). - * In all three cases, @dbus_error_name can always be recovered from the - * returned #GError using the g_dbus_error_get_remote_error() function - * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error). - * This function is typically only used in object mappings to prepare - * #GError instances for applications. Regular applications should not use - * it. + * Retrieves the #GType name of this @pspec. + */ + + +/** + * G_PARAM_SPEC_UCHAR: + * @pspec: a valid #GParamSpec instance * - * Returns: An allocated #GError. Free with g_error_free(). - * Since: 2.26 + * Cast a #GParamSpec instance into a #GParamSpecUChar. */ /** - * GTlsCertificate:certificate-pem: + * G_PARAM_SPEC_UINT: + * @pspec: a valid #GParamSpec instance * - * The PEM (ASCII) encoded representation of the certificate's - * public key. This property and the #GTlsCertificate:certificate - * property represent the same data, just in different forms. + * Cast a #GParamSpec instance into a #GParamSpecUInt. + */ + + +/** + * G_PARAM_SPEC_UINT64: + * @pspec: a valid #GParamSpec instance * - * Since: 2.28 + * Cast a #GParamSpec instance into a #GParamSpecUInt64. */ /** - * g_try_new: - * @struct_type: the type of the elements to allocate - * @n_structs: the number of elements to allocate + * G_PARAM_SPEC_ULONG: + * @pspec: a valid #GParamSpec instance * - * Attempts to allocate @n_structs elements of type @struct_type, and returns - * %NULL on failure. Contrast with g_new(), which aborts the program on failure. - * The returned pointer is cast to a pointer to the given type. - * The function returns %NULL when @n_structs is 0 of if an overflow occurs. + * Cast a #GParamSpec instance into a #GParamSpecULong. + */ + + +/** + * G_PARAM_SPEC_UNICHAR: + * @pspec: a valid #GParamSpec instance * - * Since: 2.8 - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type + * Cast a #GParamSpec instance into a #GParamSpecUnichar. */ /** - * GSignalCMarshaller: + * G_PARAM_SPEC_VALUE_ARRAY: + * @pspec: a valid #GParamSpec instance * - * This is the signature of marshaller functions, required to marshall - * arrays of parameter values to signal emissions into C language callback - * invocations. It is merely an alias to #GClosureMarshal since the #GClosure - * mechanism takes over responsibility of actual function invocation for the - * signal system. + * Cast a #GParamSpec instance into a #GParamSpecValueArray. */ /** - * G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT: + * G_PARAM_SPEC_VALUE_TYPE: + * @pspec: a valid #GParamSpec * - * A key in the "trash" namespace. When requested against - * "trash:///" returns the number of (toplevel) items in the trash folder. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Retrieves the #GType to initialize a #GValue for this parameter. */ /** - * g_dbus_proxy_get_cached_property_names: - * @proxy: A #GDBusProxy. + * G_PARAM_SPEC_VARIANT: + * @pspec: a #GParamSpec * - * Gets the names of all cached properties on @proxy. - * no cached properties. Free the returned array with g_strfreev(). + * Casts a #GParamSpec into a #GParamSpecVariant. * - * Returns: A %NULL-terminated array of strings or %NULL if @proxy has * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE: + * G_PARAM_STATIC_STRINGS: * - * A key in the "access" namespace for getting write privileges. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - * This attribute will be %TRUE if the user is able to write to the file. + * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. + * Since 2.13.0 */ /** - * GZlibDecompressor: + * G_PARAM_USER_SHIFT: * - * Zlib decompression + * Minimum shift count to be used for user defined flags, to be stored in + * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT. */ /** - * GDrive::eject-button: - * @drive: a #GDrive. + * G_PRIORITY_DEFAULT: * - * Emitted when the physical eject button (if any) of a drive has - * been pressed. + * Use this for default priority event sources. + * In GLib this priority is used when adding timeout functions + * with g_timeout_add(). In GDK this priority is used for events + * from the X server. */ /** - * g_application_set_flags: - * @application: a #GApplication - * @flags: the flags for @application + * G_PRIORITY_DEFAULT_IDLE: * - * Sets the flags for @application. - * The flags can only be modified if @application has not yet been - * registered. - * See #GApplicationFlags. + * Use this for default priority idle functions. + * In GLib this priority is used when adding idle functions with + * g_idle_add(). + */ + + +/** + * G_PRIORITY_HIGH: * - * Since: 2.28 + * Use this for high priority event sources. + * It is not used within GLib or GTK+. */ /** - * GSettings::changed: - * @settings: the object on which the signal was emitted - * @key: the name of the key that changed + * G_PRIORITY_HIGH_IDLE: * - * The "changed" signal is emitted when a key has potentially changed. - * You should call one of the g_settings_get() calls to check the new - * value. - * This signal supports detailed connections. You can connect to the - * detailed signal "changed::x" in order to only receive callbacks - * when key "x" changes. + * Use this for high priority idle functions. + * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, + * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is + * done to ensure that any pending resizes are processed before any + * pending redraws, so that widgets are not redrawn twice unnecessarily.) */ /** - * g_file_delete: - * @file: input #GFile. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * G_PRIORITY_LOW: * - * Deletes a file. If the @file is a directory, it will only be deleted if it - * is empty. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Use this for very low priority background tasks. + * It is not used within GLib or GTK+. + */ + + +/** + * G_PROXY_EXTENSION_POINT_NAME: * - * Virtual: delete_file - * Returns: %TRUE if the file was deleted. %FALSE otherwise. + * Extension point for proxy functionality. + * See <link linkend="extending-gio">Extending GIO</link>. + * + * Since: 2.26 */ /** - * GSettings:context: + * G_PROXY_RESOLVER_EXTENSION_POINT_NAME: * - * The name of the context that the settings are stored in. + * Extension point for proxy resolving functionality. + * See <link linkend="extending-gio">Extending GIO</link>. */ @@ -9382,2728 +8444,2062 @@ /** - * GDBusAnnotationInfo: - * @ref_count: The reference count or -1 if statically allocated. - * @key: The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated". - * @value: The value of the annotation. - * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. - * - * Information about an annotation. + * G_RESOLVER_ERROR: * - * Since: 2.26 + * Error domain for #GResolver. Errors in this domain will be from the + * #GResolverError enumeration. See #GError for more information on + * error domains. */ /** - * g_output_stream_is_closing: - * @stream: a #GOutputStream. - * - * Checks if an output stream is being closed. This can be - * used inside e.g. a flush implementation to see if the - * flush (or other i/o operation) is called from within - * the closing operation. + * G_SETTINGS_BACKEND_EXTENSION_POINT_NAME: * - * Returns: %TRUE if @stream is being closed. %FALSE otherwise. - * Since: 2.24 + * Extension point for #GSettingsBackend functionality. */ /** - * g_data_input_stream_read_line_async: - * @stream: a given #GDataInputStream. - * @io_priority: the <link linkend="io-priority">I/O priority</link> 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. - * - * The asynchronous version of g_data_input_stream_read_line(). It is - * an error to have two outstanding calls to this function. - * When the operation is finished, @callback will be called. You - * can then call g_data_input_stream_read_line_finish() to get - * the result of the operation. + * G_SIGNAL_FLAGS_MASK: * - * Since: 2.20 + * A mask for all #GSignalFlags bits. */ /** - * g_output_stream_write_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. - * - * Finishes a stream write operation. + * G_SIGNAL_MATCH_MASK: * - * Returns: a #gssize containing the number of bytes written to the stream. + * A mask for all #GSignalMatchType bits. */ /** - * g_file_create_readwrite_async: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Asynchronously creates a new file and returns a stream for reading and - * writing to it. The file must not already exist. - * For more details, see g_file_create_readwrite() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then - * call g_file_create_readwrite_finish() to get the result of the operation. + * G_SIGNAL_TYPE_STATIC_SCOPE: * - * Since: 2.22 + * This macro flags signal argument types for which the signal system may + * assume that instances thereof remain persistent across all signal emissions + * they are used in. This is only useful for non ref-counted, value-copy types. + * To flag a signal argument in this way, add + * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument + * of g_signal_new(). + * |[ + * g_signal_new ("size_request", + * G_TYPE_FROM_CLASS (gobject_class), + * G_SIGNAL_RUN_FIRST, + * G_STRUCT_OFFSET (GtkWidgetClass, size_request), + * NULL, NULL, + * _gtk_marshal_VOID__BOXED, + * G_TYPE_NONE, 1, + * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); + * ]| */ /** - * GDBusAuthObserver::authorize-authenticated-peer: - * @observer: The #GDBusAuthObserver emitting the signal. - * @stream: A #GIOStream for the #GDBusConnection. - * @credentials: Credentials received from the peer or %NULL. + * G_TIME_SPAN_DAY: * - * Emitted to check if a peer that is successfully authenticated - * is authorized. + * Evaluates to a time span of one day. * - * Returns: %TRUE if the peer is authorized, %FALSE if not. * Since: 2.26 */ /** - * GPollFunc: - * @ufds: an array of #GPollFD elements - * @nfsd: the number of elements in @ufds - * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout. + * G_TIME_SPAN_HOUR: * - * Specifies the type of function passed to g_main_context_set_poll_func(). - * The semantics of the function should match those of the poll() system call. - * reported, or -1 if an error occurred. + * Evaluates to a time span of one hour. * - * Returns: the number of #GPollFD elements which have events or errors + * Since: 2.26 */ /** - * GSimpleAction::activate: - * @simple: the #GSimpleAction - * @parameter: (allow-none): the parameter to the activation + * G_TIME_SPAN_MILLISECOND: * - * Indicates that the action was just activated. - * an incorrect type was given, no signal will be emitted. + * Evaluates to a time span of one millisecond. * - * Since: 2.28 + * Since: 2.26 */ /** - * g_cancellable_source_new: (skip) - * @cancellable: a #GCancellable, or %NULL + * G_TIME_SPAN_MINUTE: * - * Creates a source that triggers if @cancellable is cancelled and - * calls its callback of type #GCancellableSourceFunc. This is - * primarily useful for attaching to another (non-cancellable) source - * with g_source_add_child_source() to add cancellability to it. - * For convenience, you can call this with a %NULL #GCancellable, - * in which case the source will never trigger. + * Evaluates to a time span of one minute. * - * Returns: (transfer full): the new #GSource. - * Since: 2.28 + * Since: 2.26 */ /** - * g_data_input_stream_read_byte: - * @stream: a given #GDataInputStream. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * G_TIME_SPAN_SECOND: * - * Reads an unsigned 8-bit/1-byte value from @stream. - * if an error occurred. + * Evaluates to a time span of one second. * - * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 + * Since: 2.26 */ /** - * GConverter: + * G_TLS_BACKEND_EXTENSION_POINT_NAME: * - * Seek object for streaming operations. + * Extension point for TLS functionality via #GTlsBackend. + * See <link linkend="extending-gio">Extending GIO</link>. + */ + + +/** + * G_TLS_ERROR: * - * Since: 2.24 + * Error domain for TLS. Errors in this domain will be from the + * #GTlsError enumeration. See #GError for more information on error + * domains. */ /** - * g_socket_client_connect_to_host_finish: - * @client: a #GSocketClient. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * G_TYPE_ARRAY: * - * Finishes an async connect operation. See g_socket_client_connect_to_host_async() + * The #GType for a boxed type holding a #GArray reference. * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. * Since: 2.22 */ /** - * G_FILE_ATTRIBUTE_TIME_CREATED: + * G_TYPE_BOOLEAN: * - * A key in the "time" namespace for getting the time the file was created. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, - * and contains the UNIX time since the file was created. - * This corresponds to the NTFS ctime. + * The fundamental type corresponding to #gboolean. */ /** - * GMountOperation::ask-question: - * @op: a #GMountOperation asking a question. - * @message: string containing a message to display to the user. - * @choices: an array of strings for each possible choice. + * G_TYPE_BOXED: * - * Emitted when asking the user a question and gives a list of - * choices for the user to choose from. - * If the message contains a line break, the first line should be - * presented as a heading. For example, it may be used as the - * primary text in a #GtkMessageDialog. + * The fundamental type from which all boxed types are derived. */ /** - * G_IS_INITIALLY_UNOWNED_CLASS: - * @class: a #GInitiallyUnownedClass + * G_TYPE_BYTE_ARRAY: * - * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type - * %G_TYPE_INITIALLY_UNOWNED or derived. + * The #GType for a boxed type holding a #GByteArray reference. + * + * Since: 2.22 */ /** - * GUnixOutputStream: + * G_TYPE_CHAR: * - * Implements #GOutputStream for outputting to selectable unix file descriptors + * The fundamental type corresponding to #gchar. + * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer. + * This may or may not be the same type a the C type "gchar". */ /** - * SECTION:extensionpoint: - * @short_description: Extension Points - * @include: gio.h - * @see_also: <link linkend="extending-gio">Extending GIO</link> + * G_TYPE_CHECK_CLASS_CAST: + * @g_class: Location of a #GTypeClass structure. + * @g_type: The type to be returned. + * @c_type: The corresponding C type of class structure of @g_type. * - * #GIOExtensionPoint provides a mechanism for modules to extend the - * functionality of the library or application that loaded it in an - * organized fashion. - * An extension point is identified by a name, and it may optionally - * require that any implementation must by of a certain type (or derived - * thereof). Use g_io_extension_point_register() to register an - * extension point, and g_io_extension_point_set_required_type() to - * set a required type. - * A module can implement an extension point by specifying the #GType - * that implements the functionality. Additionally, each implementation - * of an extension point has a name, and a priority. Use - * g_io_extension_point_implement() to implement an extension point. - * |[ - * GIOExtensionPoint *ep; - * /* Register an extension point */ - * ep = g_io_extension_point_register ("my-extension-point"); - * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); - * ]| - * |[ - * /* Implement an extension point */ - * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE); - * g_io_extension_point_implement ("my-extension-point", - * my_example_impl_get_type (), - * "my-example", - * 10); - * ]| - * It is up to the code that registered the extension point how - * it uses the implementations that have been associated with it. - * Depending on the use case, it may use all implementations, or - * only the one with the highest priority, or pick a specific - * one by name. - * To avoid opening all modules just to find out what extension - * points they implement, GIO makes use of a caching mechanism, - * see <link linkend="gio-querymodules">gio-querymodules</link>. - * You are expected to run this command after installing a - * GIO module. + * Checks that @g_class is a class structure of the type identified by @g_type + * and issues a warning if this is not the case. Returns @g_class casted + * to a pointer to @c_type. + * This macro should only be used in type implementations. */ /** - * g_pollable_output_stream_write_nonblocking: - * @stream: a #GPollableOutputStream - * @buffer: (array length=size) (element-type guint8): a buffer to write data from - * @size: the number of bytes you want to write - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * G_TYPE_CHECK_CLASS_TYPE: + * @g_class: Location of a #GTypeClass structure. + * @g_type: The type to be checked. * - * Attempts to write up to @size bytes from @buffer to @stream, as - * with g_output_stream_write(). If @stream is not currently writable, - * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can - * use g_pollable_output_stream_create_source() to create a #GSource - * that will be triggered when @stream is writable. - * Note that since this method never blocks, you cannot actually - * use @cancellable to cancel it. However, it will return an error - * if @cancellable has already been cancelled when you call, which - * may happen if you call this method after a source triggers due - * to having been cancelled. - * %G_IO_ERROR_WOULD_BLOCK). + * Checks if @g_class is a class structure of the type identified by + * This macro should only be used in type implementations. * - * Virtual: write_nonblocking - * Returns: the number of bytes written, or -1 on error (including + * Returns: %TRUE on success. */ /** - * g_output_stream_write: - * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. - * @count: the number of bytes to write - * @cancellable: (allow-none): optional cancellable object - * @error: location to store the error occuring, or %NULL to ignore + * G_TYPE_CHECK_INSTANCE: + * @instance: Location of a #GTypeInstance structure. * - * Tries to write @count bytes from @buffer into the stream. Will block - * during the operation. - * If count is 0, returns 0 and does nothing. A value of @count - * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * On success, the number of bytes written to the stream is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. on a partial I/O error, or if there is not enough - * storage in the stream. All writes block until at least one byte - * is written or an error occurs; 0 is never returned (unless - * If @cancellable is not NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * On error -1 is returned and @error is set accordingly. + * Checks if @instance is a valid #GTypeInstance structure, + * otherwise issues a warning and returns %FALSE. + * This macro should only be used in type implementations. * - * Returns: Number of bytes written, or -1 on error + * Returns: %TRUE on success. */ /** - * g_main_destroy: - * @loop: a #GMainLoop - * - * Frees the memory allocated for the #GMainLoop. + * G_TYPE_CHECK_INSTANCE_CAST: + * @instance: Location of a #GTypeInstance structure. + * @g_type: The type to be returned. + * @c_type: The corresponding C type of @g_type. * - * Deprecated: 2.2: Use g_main_loop_unref() instead + * Checks that @instance is an instance of the type identified by @g_type + * and issues a warning if this is not the case. Returns @instance casted + * to a pointer to @c_type. + * This macro should only be used in type implementations. */ /** - * g_dbus_connection_new: - * @stream: A #GIOStream. - * @guid: The GUID to use if a authenticating as a server or %NULL. - * @flags: Flags describing how to make the connection. - * @observer: A #GDBusAuthObserver or %NULL. - * @cancellable: A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * G_TYPE_CHECK_INSTANCE_TYPE: + * @instance: Location of a #GTypeInstance structure. + * @g_type: The type to be checked * - * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages - * with the end represented by @stream. - * If @observer is not %NULL it may be used to control the - * authentication process. - * When the operation is finished, @callback will be invoked. You can - * then call g_dbus_connection_new_finish() to get the result of the - * operation. - * This is a asynchronous failable constructor. See - * g_dbus_connection_new_sync() for the synchronous - * version. + * Checks if @instance is an instance of the type identified by @g_type. + * This macro should only be used in type implementations. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * GPasswordSave: - * @G_PASSWORD_SAVE_NEVER: never save a password. - * @G_PASSWORD_SAVE_FOR_SESSION: save a password for the session. - * @G_PASSWORD_SAVE_PERMANENTLY: save a password permanently. + * G_TYPE_CHECK_VALUE: + * @value: a #GValue * - * #GPasswordSave is used to indicate the lifespan of a saved password. - * #Gvfs stores passwords in the Gnome keyring when this flag allows it - * to, and later retrieves it again from there. + * Checks if @value has been initialized to hold values + * of a value type. + * This macro should only be used in type implementations. + * + * Returns: %TRUE on success. */ /** - * G_FILE_ATTRIBUTE_TIME_CREATED_USEC: + * G_TYPE_CHECK_VALUE_TYPE: + * @value: a #GValue + * @g_type: The type to be checked. * - * A key in the "time" namespace for getting the microseconds of the time - * the file was created. This should be used in conjunction with - * #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Checks if @value has been initialized to hold values + * of type @g_type. + * This macro should only be used in type implementations. + * + * Returns: %TRUE on success. */ /** - * G_BOOKMARK_FILE_ERROR: + * G_TYPE_CLASS_GET_PRIVATE: + * @klass: the class of a type deriving from @private_type. + * @g_type: the type identifying which private data to retrieve. + * @c_type: The C type for the private structure. * - * Error domain for bookmark file parsing. - * Errors in this domain will be from the #GBookmarkFileError - * enumeration. See #GError for information on error domains. + * Gets the private class structure for a particular type. + * The private structure must have been registered in the + * get_type() function with g_type_add_class_private(). + * This macro should only be used in type implementations. + * + * Since: 2.24 + * Returns: a pointer to the private data structure. */ /** - * g_unix_credentials_message_get_credentials: - * @message: A #GUnixCredentialsMessage. - * - * Gets the credentials stored in @message. + * G_TYPE_CLOSURE: * - * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message. - * Since: 2.26 + * The #GType for #GClosure. */ /** - * SECTION:gfileenumerato: - * @short_description: Enumerated Files Routines - * @include: gio/gio.h + * G_TYPE_DATE: * - * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s, - * returning a #GFileInfo structure for each file enumerated (e.g. - * g_file_enumerate_children() will return a #GFileEnumerator for each - * of the children within a directory). - * To get the next file's information from a #GFileEnumerator, use - * g_file_enumerator_next_file() or its asynchronous version, - * g_file_enumerator_next_files_async(). Note that the asynchronous - * version will return a list of #GFileInfo<!---->s, whereas the - * synchronous will only return the next file in the enumerator. - * To close a #GFileEnumerator, use g_file_enumerator_close(), or - * its asynchronous version, g_file_enumerator_close_async(). Once - * a #GFileEnumerator is closed, no further actions may be performed - * on it, and it should be freed with g_object_unref(). + * The #GType for #GDate. */ /** - * GThemedIcon:use-default-fallbacks: + * G_TYPE_DATE_TIME: * - * Whether to use the default fallbacks found by shortening the icon name - * at '-' characters. If the "names" array has more than one element, - * ignores any past the first. - * For example, if the icon name was "gnome-dev-cdrom-audio", the array - * would become - * |[ - * { - * "gnome-dev-cdrom-audio", - * "gnome-dev-cdrom", - * "gnome-dev", - * "gnome", - * NULL - * }; - * ]| + * The #GType for a boxed type holding a #GDateTime. + * + * Since: 2.26 */ /** - * g_mount_remount_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * G_TYPE_DBUS_ANNOTATION_INFO: * - * Finishes remounting a mount. If any errors occurred during the operation, + * The #GType for a boxed type holding a #GDBusAnnotationInfo. * - * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise. + * Since: 2.26 */ /** - * g_settings_sync: + * G_TYPE_DBUS_ARG_INFO: * - * Ensures that all pending operations for the given are complete for - * the default backend. - * Writes made to a #GSettings are handled asynchronously. For this - * reason, it is very unlikely that the changes have it to disk by the - * time g_settings_set() returns. - * This call will block until all of the writes have made it to the - * backend. Since the mainloop is not running, no change notifications - * will be dispatched during this call (but some may be queued by the - * time the call is done). + * The #GType for a boxed type holding a #GDBusArgInfo. + * + * Since: 2.26 */ /** - * GNetworkAddress: + * G_TYPE_DBUS_INTERFACE_INFO: * - * A #GSocketConnectable for resolving a hostname and connecting to - * that host. + * The #GType for a boxed type holding a #GDBusInterfaceInfo. + * + * Since: 2.26 */ /** - * G_VARIANT_TYPE_INT64: + * G_TYPE_DBUS_METHOD_INFO: * - * The type of an integer value that can range from - * -9223372036854775808 to 9223372036854775807. + * The #GType for a boxed type holding a #GDBusMethodInfo. + * + * Since: 2.26 */ /** - * g_socket_address_enumerator_next_async: - * @enumerator: a #GSocketAddressEnumerator - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * G_TYPE_DBUS_NODE_INFO: * - * Asynchronously retrieves the next #GSocketAddress from @enumerator - * and then calls @callback, which must call - * g_socket_address_enumerator_next_finish() to get the result. + * The #GType for a boxed type holding a #GDBusNodeInfo. + * + * Since: 2.26 */ /** - * g_settings_get_strv: - * @settings: a #GSettings object - * @key: the key to get the value for - * @returns: (array zero-terminated=1) (transfer full): a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings. + * G_TYPE_DBUS_PROPERTY_INFO: * - * A convenience variant of g_settings_get() for string arrays. - * It is a programmer error to give a @key that isn't specified as - * having an array of strings type in the schema for @settings. + * The #GType for a boxed type holding a #GDBusPropertyInfo. * * Since: 2.26 */ /** - * g_unix_output_stream_set_close_fd: - * @stream: a #GUnixOutputStream - * @close_fd: %TRUE to close the file descriptor when done + * G_TYPE_DBUS_SIGNAL_INFO: * - * Sets whether the file descriptor of @stream shall be closed - * when the stream is closed. + * The #GType for a boxed type holding a #GDBusSignalInfo. * - * Since: 2.20 + * Since: 2.26 */ /** - * g_tls_certificate_new_from_pem: - * @data: PEM-encoded certificate data - * @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 - * returned certificate will include the private key data as well. - * If @data includes multiple certificates, only the first one will be - * parsed. + * G_TYPE_DOUBLE: * - * Returns: the new certificate, or %NULL if @data is invalid - * Since: 2.28 + * The fundamental type corresponding to #gdouble. */ /** - * g_dbus_message_set_interface: - * @message: A #GDBusMessage. - * @value: The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. + * G_TYPE_ENUM: * - * Since: 2.26 + * The fundamental type from which all enumeration types are derived. */ /** - * g_charset_converter_new: - * @to_charset: destination charset - * @from_charset: source charset - * @error: #GError for error reporting, or %NULL to ignore. + * G_TYPE_ERROR: * - * Creates a new #GCharsetConverter. + * The #GType for a boxed type holding a #GError. * - * Returns: a new #GCharsetConverter or %NULL on error. - * Since: 2.24 + * Since: 2.26 */ /** - * GParamSpecUInt: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_TYPE_FLAGS: * - * A #GParamSpec derived structure that contains the meta data for unsigned integer properties. + * The fundamental type from which all flags types are derived. */ /** - * g_simple_async_result_set_op_res_gboolean: - * @simple: a #GSimpleAsyncResult. - * @op_res: a #gboolean. + * G_TYPE_FLAG_RESERVED_ID_BIT: * - * Sets the operation result to a boolean within the asynchronous result. + * A bit in the type number that's supposed to be left untouched. */ /** - * G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL: + * G_TYPE_FLOAT: * - * A key in the "standard" namespace for checking if a file is virtual. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * The fundamental type corresponding to #gfloat. */ /** - * g_unix_fd_list_get: - * @list: a #GUnixFDList - * @index_: the index into the list - * @error: a #GError pointer + * G_TYPE_FROM_CLASS: + * @g_class: Location of a valid #GTypeClass structure. * - * Gets a file descriptor out of @list. - * programmer error for @index_ to be out of range; see - * g_unix_fd_list_get_length(). - * The file descriptor is duplicated using dup() and set as - * close-on-exec before being returned. You must call close() on it - * when you are done. - * A possible cause of failure is exceeding the per-process or - * system-wide file descriptor limit. + * Get the type identifier from a given @class structure. + * This macro should only be used in type implementations. * - * Returns: the file descriptor, or -1 in case of error - * Since: 2.24 + * Returns: the #GType */ /** - * G_TYPE_DBUS_PROPERTY_INFO: + * G_TYPE_FROM_INSTANCE: + * @instance: Location of a valid #GTypeInstance structure. * - * The #GType for a boxed type holding a #GDBusPropertyInfo. + * Get the type identifier from a given @instance structure. + * This macro should only be used in type implementations. * - * Since: 2.26 + * Returns: the #GType */ /** - * G_TYPE_DATE: + * G_TYPE_FROM_INTERFACE: + * @g_iface: Location of a valid #GTypeInterface structure. * - * The #GType for #GDate. + * Get the type identifier from a given @interface structure. + * This macro should only be used in type implementations. + * + * Returns: the #GType */ /** - * GEmblemOrigin: - * @G_EMBLEM_ORIGIN_UNKNOWN: Emblem of unknown origin - * @G_EMBLEM_ORIGIN_DEVICE: Emblem adds device-specific information - * @G_EMBLEM_ORIGIN_LIVEMETADATA: Emblem depicts live metadata, such as "readonly" - * @G_EMBLEM_ORIGIN_TAG: Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) - * - * GEmblemOrigin is used to add information about the origin of the emblem - * to #GEmblem. + * G_TYPE_FUNDAMENTAL: + * @type: A #GType value. * - * Since: 2.18 + * The fundamental type which is the ancestor of @type. + * Fundamental types are types that serve as ultimate bases for the derived types, + * thus they are the roots of distinct inheritance hierarchies. */ /** - * GAppLaunchContext: + * G_TYPE_FUNDAMENTAL_MAX: * - * Integrating the launch with the launching application. This is used to - * handle for instance startup notification and launching the new application - * on the same screen as the launching window. + * An integer constant that represents the number of identifiers reserved + * for types that are assigned at compile-time. */ /** - * G_FILE_ATTRIBUTE_THUMBNAILING_FAILED: + * G_TYPE_FUNDAMENTAL_SHIFT: * - * A key in the "thumbnail" namespace for checking if thumbnailing failed. - * This attribute is %TRUE if thumbnailing failed. Corresponding - * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * Shift value used in converting numbers to type IDs. */ /** - * G_FILE_ATTRIBUTE_ETAG_VALUE: + * G_TYPE_GSTRING: * - * A key in the "etag" namespace for getting the value of the file's - * entity tag. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. + * The #GType for #GString. */ /** - * GFilesystemPreviewType: - * @G_FILESYSTEM_PREVIEW_TYPE_IF_ALWAYS: Only preview files if user has explicitly requested it. - * @G_FILESYSTEM_PREVIEW_TYPE_IF_LOCAL: Preview files if user has requested preview of "local" files. - * @G_FILESYSTEM_PREVIEW_TYPE_NEVER: Never preview files. + * G_TYPE_GTYPE: * - * Indicates a hint from the file system whether files should be - * previewed in a file manager. Returned as the value of the key - * #G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW. + * The type for #GType. */ /** - * g_simple_action_new: - * @name: the name of the action - * @parameter_type: (allow-none): the type of parameter to the activate function + * G_TYPE_HASH_TABLE: * - * Creates a new action. - * The created action is stateless. See g_simple_action_new_stateful(). + * The #GType for a boxed type holding a #GHashTable reference. * - * Returns: a new #GSimpleAction - * Since: 2.28 + * Since: 2.10 */ /** - * g_inet_address_get_is_link_local: - * @address: a #GInetAddress + * G_TYPE_HAS_VALUE_TABLE: + * @type: A #GType value. * - * Tests whether @address is a link-local address (that is, if it - * identifies a host on a local network that is not connected to the - * Internet). + * Checks if @type has a #GTypeValueTable. * - * Returns: %TRUE if @address is a link-local address. - * Since: 2.22 + * Returns: %TRUE on success. */ /** - * g_signal_connect_after: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. - * - * Connects a #GCallback function to a signal for a particular object. - * The handler will be called after the default handler of the signal. + * G_TYPE_INITIALLY_UNOWNED: * - * Returns: the handler id + * The type for #GInitiallyUnowned. */ /** - * g_drive_has_media: - * @drive: a #GDrive. + * G_TYPE_INSTANCE_GET_CLASS: + * @instance: Location of the #GTypeInstance structure. + * @g_type: The #GType of the class to be returned. + * @c_type: The C type of the class structure. * - * Checks if the @drive has media. Note that the OS may not be polling - * the drive for media changes; see g_drive_is_media_check_automatic() - * for more details. + * Get the class structure of a given @instance, casted + * to a specified ancestor type @g_type of the instance. + * Note that while calling a GInstanceInitFunc(), the class pointer gets + * modified, so it might not always return the expected pointer. + * This macro should only be used in type implementations. * - * Returns: %TRUE if @drive has media, %FALSE otherwise. + * Returns: a pointer to the class structure */ /** - * g_simple_async_result_set_op_res_gssize: - * @simple: a #GSimpleAsyncResult. - * @op_res: a #gssize. + * G_TYPE_INSTANCE_GET_INTERFACE: + * @instance: Location of the #GTypeInstance structure. + * @g_type: The #GType of the interface to be returned. + * @c_type: The C type of the interface structure. * - * Sets the operation result within the asynchronous result to - * the given @op_res. + * Get the interface structure for interface @g_type of a given @instance. + * This macro should only be used in type implementations. + * + * Returns: a pointer to the interface structure */ /** - * g_loadable_icon_load_finish: - * @icon: a #GLoadableIcon. - * @res: a #GAsyncResult. - * @type: a location to store the type of the loaded icon, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * G_TYPE_INSTANCE_GET_PRIVATE: + * @instance: the instance of a type deriving from @private_type. + * @g_type: the type identifying which private data to retrieve. + * @c_type: The C type for the private structure. * - * Finishes an asynchronous icon load started in g_loadable_icon_load_async(). + * Gets the private structure for a particular type. + * The private structure must have been registered in the + * class_init function with g_type_class_add_private(). + * This macro should only be used in type implementations. * - * Returns: (transfer full): a #GInputStream to read the icon from. + * Since: 2.4 + * Returns: a pointer to the private data structure. */ /** - * GOptionEntry: - * @long_name: The long name of an option can be used to specify it in a commandline as --<replaceable>long_name</replaceable>. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>. - * @short_name: If an option has a short name, it can be specified -<replaceable>short_name</replaceable> in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name. - * @flags: Flags from #GOptionFlags. - * @arg: The type of the option, as a #GOptionArg. - * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: <variablelist> <varlistentry> <term>%G_OPTION_ARG_NONE</term> <listitem><para>%gboolean</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_INT</term> <listitem><para>%gint</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_DOUBLE</term> <listitem><para>%gdouble</para></listitem> </varlistentry> </variablelist> If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). - * @description: the description for the option in <option>--help</option> output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). - * @arg_description: The placeholder to use for the extra argument parsed by the option in <option>--help</option> output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). + * G_TYPE_INT: * - * A <structname>GOptionEntry</structname> defines a single option. - * To have an effect, they must be added to a #GOptionGroup with - * g_option_context_add_main_entries() or g_option_group_add_entries(). + * The fundamental type corresponding to #gint. */ /** - * g_resolver_get_default: + * G_TYPE_INT64: * - * Gets the default #GResolver. You should unref it when you are done - * with it. #GResolver may use its reference count as a hint about how - * many threads/processes, etc it should allocate for concurrent DNS - * resolutions. + * The fundamental type corresponding to #gint64. + */ + + +/** + * G_TYPE_INTERFACE: * - * Returns: (transfer full): the default #GResolver. - * Since: 2.22 + * The fundamental type from which all interfaces are derived. */ /** - * g_application_command_line_print: - * @cmdline: a #GApplicationCommandLine - * @format: a printf-style format string - * @...: arguments, as per @format + * G_TYPE_INVALID: * - * Formats a message and prints it using the stdout print handler in the - * invoking process. - * If @cmdline is a local invocation then this is exactly equivalent to - * g_print(). If @cmdline is remote then this is equivalent to calling - * g_print() in the invoking process. + * An invalid #GType used as error return value in some functions which return + * a #GType. + */ + + +/** + * G_TYPE_IO_CHANNEL: * - * Since: 2.28 + * The #GType for #GIOChannel. */ /** - * G_PARAM_SPEC_CHAR: - * @pspec: a valid #GParamSpec instance + * G_TYPE_IO_CONDITION: * - * Cast a #GParamSpec instance into a #GParamSpecChar. + * The #GType for #GIOCondition. */ /** - * g_file_info_has_attribute: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * G_TYPE_IS_ABSTRACT: + * @type: A #GType value. * - * Checks if a file info structure has an attribute named @attribute. - * %FALSE otherwise. + * Checks if @type is an abstract type. An abstract type can not be + * instantiated and is normally used as an abstract base class for + * derived classes. * - * Returns: %TRUE if @Ginfo has an attribute named @attribute, + * Returns: %TRUE on success. */ /** - * g_drive_get_volumes: - * @drive: a #GDrive. + * G_TYPE_IS_CLASSED: + * @type: A #GType value. * - * Get a list of mountable volumes for @drive. - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). + * Checks if @type is a classed type. * - * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive. + * Returns: %TRUE on success. */ /** - * g_dbus_connection_start_message_processing: - * @connection: A #GDBusConnection. + * G_TYPE_IS_DEEP_DERIVABLE: + * @type: A #GType value. * - * If @connection was created with - * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method - * starts processing messages. Does nothing on if @connection wasn't - * created with this flag or if the method has already been called. + * Checks if @type is a deep derivable type. A deep derivable type + * can be used as the base class of a deep (multi-level) class hierarchy. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_desktop_app_info_set_desktop_env: - * @desktop_env: a string specifying what desktop this is + * G_TYPE_IS_DERIVABLE: + * @type: A #GType value. * - * Sets the name of the desktop that the application is running in. - * This is used by g_app_info_should_show() to evaluate the - * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> - * desktop entry fields. - * The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop - * Menu specification</ulink> recognizes the following: - * <simplelist> - * <member>GNOME</member> - * <member>KDE</member> - * <member>ROX</member> - * <member>XFCE</member> - * <member>Old</member> - * </simplelist> - * Should be called only once; subsequent calls are ignored. + * Checks if @type is a derivable type. A derivable type can + * be used as the base class of a flat (single-level) class hierarchy. + * + * Returns: %TRUE on success. */ /** - * GValue: + * G_TYPE_IS_DERIVED: + * @type: A #GType value. * - * An opaque structure used to hold different types of values. - * to functions within a #GTypeValueTable structure, or implementations of - * the g_value_*() API. That is, code portions which implement new fundamental - * types. - * #GValue users can not make any assumptions about how data is stored - * within the 2 element @data union, and the @g_type member should - * only be accessed through the G_VALUE_TYPE() macro. + * Checks if @type is derived (or in object-oriented terminology: + * inherited) from another type (this holds true for all non-fundamental + * types). * - * The data within the structure has protected scope: it is accessible only + * Returns: %TRUE on success. */ /** - * GFileCreateFlags: - * @G_FILE_CREATE_NONE: No flags set. - * @G_FILE_CREATE_PRIVATE: Create a file that can only be accessed by the current user. - * @G_FILE_CREATE_REPLACE_DESTINATION: Replace the destination as if it didn't exist before. Don't try to keep any old permissions, replace instead of following links. This is generally useful if you're doing a "copy over" rather than a "save new version of" replace operation. You can think of it as "unlink destination" before writing to it, although the implementation may not be exactly like that. Since 2.20 + * G_TYPE_IS_ENUM: + * @type: a #GType ID. * - * Flags used when an operation may create a file. + * Checks whether @type "is a" %G_TYPE_ENUM. + * + * Returns: %TRUE if @type "is a" %G_TYPE_ENUM. */ /** - * g_cancellable_new: + * G_TYPE_IS_FLAGS: + * @type: a #GType ID. * - * Creates a new #GCancellable object. - * Applications that want to start one or more operations - * that should be cancellable should create a #GCancellable - * and pass it to the operations. - * One #GCancellable can be used in multiple consecutive - * operations, but not in multiple concurrent operations. + * Checks whether @type "is a" %G_TYPE_FLAGS. * - * Returns: a #GCancellable. + * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS. */ /** - * G_TYPE_PARAM_ENUM: + * G_TYPE_IS_FUNDAMENTAL: + * @type: A #GType value. * - * The #GType of #GParamSpecEnum. + * Checks if @type is a fundamental type. + * + * Returns: %TRUE on success. */ /** - * g_io_extension_get_priority: - * @extension: a #GIOExtension + * G_TYPE_IS_INSTANTIATABLE: + * @type: A #GType value. * - * Gets the priority with which @extension was registered. + * Checks if @type can be instantiated. Instantiation is the + * process of creating an instance (object) of this type. * - * Returns: the priority of @extension + * Returns: %TRUE on success. */ /** - * g_file_new_for_commandline_arg: - * @arg: a command line string. + * G_TYPE_IS_INTERFACE: + * @type: A #GType value. * - * Creates a #GFile with the given argument from the command line. The value of - * relative to the current working directory. - * This operation never fails, but the returned object might not support any - * I/O operation if @arg points to a malformed path. + * Checks if @type is an interface type. + * An interface type provides a pure API, the implementation + * of which is provided by another type (which is then said to conform + * to the interface). GLib interfaces are somewhat analogous to Java + * interfaces and C++ classes containing only pure virtual functions, + * with the difference that GType interfaces are not derivable (but see + * g_type_interface_add_prerequisite() for an alternative). * - * Returns: (transfer full): a new #GFile. + * Returns: %TRUE on success. */ /** - * g_app_info_get_display_name: - * @appinfo: a #GAppInfo. + * G_TYPE_IS_OBJECT: + * @type: Type id to check * - * Gets the display name of the application. The display name is often more - * descriptive to the user than the name itself. - * no display name is available. + * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. * - * Returns: the display name of the application for @appinfo, or the name if - * Since: 2.24 + * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT. */ /** - * GApplication::activate: - * @application: the application + * G_TYPE_IS_PARAM: + * @type: a #GType ID * - * The ::activate signal is emitted on the primary instance when an - * activation occurs. See g_application_activate(). + * Checks whether @type "is a" %G_TYPE_PARAM. */ /** - * g_proxy_connect_finish: - * @proxy: a #GProxy - * @result: a #GAsyncRetult - * @error: return #GError + * G_TYPE_IS_VALUE: + * @type: A #GType value. * - * See g_proxy_connect(). + * Checks whether the passed in type ID can be used for g_value_init(). + * That is, this macro checks whether this type provides an implementation + * of the #GTypeValueTable functions required for a type to create a #GValue of. * - * Returns: (transfer full): a #GIOStream. - * Since: 2.26 + * Returns: Whether @type is suitable as a #GValue type. */ /** - * g_dbus_node_info_new_for_xml: - * @xml_data: Valid D-Bus introspection XML. - * @error: Return location for error. + * G_TYPE_IS_VALUE_ABSTRACT: + * @type: A #GType value. * - * Parses @xml_data and returns a #GDBusNodeInfo representing the data. - * with g_dbus_node_info_unref(). + * Checks if @type is an abstract value type. An abstract value type introduces + * a value table, but can't be used for g_value_init() and is normally used as + * an abstract base type for derived value types. * - * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_mount_get_icon: - * @mount: a #GMount. + * G_TYPE_IS_VALUE_TYPE: + * @type: A #GType value. * - * Gets the icon for @mount. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. + * Checks if @type is a value type and can be used with g_value_init(). * - * Returns: (transfer full): a #GIcon. + * Returns: %TRUE on success. */ /** - * g_mount_operation_reply: - * @op: a #GMountOperation - * @result: a #GMountOperationResult + * G_TYPE_LONG: * - * Emits the #GMountOperation::reply signal. + * The fundamental type corresponding to #glong. */ /** - * g_dbus_property_info_ref: - * @info: A #GDBusPropertyInfo + * G_TYPE_MAKE_FUNDAMENTAL: + * @x: the fundamental type number. * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * Get the type ID for the fundamental type number @x. + * Use g_type_fundamental_next() instead of this macro to create new fundamental + * types. * - * Returns: The same @info. - * Since: 2.26 + * Returns: the GType */ /** - * GDBusProxyClass: - * @g_properties_changed: Signal class handler for the #GDBusProxy::g-properties-changed signal. - * @g_signal: Signal class handler for the #GDBusProxy::g-signal signal. - * - * Class structure for #GDBusProxy. + * G_TYPE_NONE: * - * Since: 2.26 + * A fundamental type which is used as a replacement for the C + * <literal>void</literal> return type. */ /** - * g_themed_icon_new_with_default_fallbacks: - * @iconname: a string containing an icon name - * - * Creates a new themed icon for @iconname, and all the names - * that can be created by shortening @iconname at '-' characters. - * In the following example, @icon1 and @icon2 are equivalent: - * |[ - * const char *names[] = { - * "gnome-dev-cdrom-audio", - * "gnome-dev-cdrom", - * "gnome-dev", - * "gnome" - * }; - * icon1 = g_themed_icon_new_from_names (names, 4); - * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio"); - * ]| + * G_TYPE_OBJECT: * - * Returns: (transfer full): a new #GThemedIcon. + * The fundamental type for #GObject. */ /** - * GDataOutputStream: + * G_TYPE_PARAM: * - * An implementation of #GBufferedOutputStream that allows for high-level - * data manipulation of arbitrary data (including binary operations). + * The fundamental type from which all #GParamSpec types are derived. */ /** - * g_action_group_has_action: - * @action_group: a #GActionGroup - * @action_name: the name of the action to check for - * - * Checks if the named action exists within @action_group. + * G_TYPE_PARAM_BOOLEAN: * - * Returns: whether the named action exists - * Since: 2.28 + * The #GType of #GParamSpecBoolean. */ /** - * g_buffered_input_stream_fill_async: - * @stream: a #GBufferedInputStream - * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): a #gpointer + * G_TYPE_PARAM_BOXED: * - * Reads data into @stream's buffer asynchronously, up to @count size. - * version of this function, see g_buffered_input_stream_fill(). - * If @count is -1 then the attempted read size is equal to the number - * of bytes that are required to fill the buffer. + * The #GType of #GParamSpecBoxed. */ /** - * g_inet_address_get_is_mc_node_local: - * @address: a #GInetAddress - * - * Tests whether @address is a node-local multicast address. + * G_TYPE_PARAM_CHAR: * - * Returns: %TRUE if @address is a node-local multicast address. - * Since: 2.22 + * The #GType of #GParamSpecChar. */ /** - * SECTION:gvolum: - * @short_description: Volume management - * @include: gio/gio.h - * - * The #GVolume interface represents user-visible objects that can be - * mounted. Note, when porting from GnomeVFS, #GVolume is the moral - * equivalent of #GnomeVFSDrive. - * Mounting a #GVolume instance is an asynchronous operation. For more - * information about asynchronous operations, see #GAsyncReady and - * #GSimpleAsyncReady. To mount a #GVolume, first call - * g_volume_mount() with (at least) the #GVolume instance, optionally - * a #GMountOperation object and a #GAsyncReadyCallback. - * Typically, one will only want to pass %NULL for the - * #GMountOperation if automounting all volumes when a desktop session - * starts since it's not desirable to put up a lot of dialogs asking - * for credentials. - * The callback will be fired when the operation has resolved (either - * with success or failure), and a #GAsyncReady structure will be - * passed to the callback. That callback should then call - * g_volume_mount_finish() with the #GVolume instance and the - * #GAsyncReady data to see if the operation was completed - * successfully. If an @error is present when g_volume_mount_finish() - * is called, then it will be filled with any error information. - * <para id="volume-identifier"> - * It is sometimes necessary to directly access the underlying - * operating system object behind a volume (e.g. for passing a volume - * to an application via the commandline). For this purpose, GIO - * allows to obtain an 'identifier' for the volume. There can be - * different kinds of identifiers, such as Hal UDIs, filesystem labels, - * traditional Unix devices (e.g. <filename>/dev/sda2</filename>), - * uuids. GIO uses predefind strings as names for the different kinds - * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier() - * to obtain an identifier for a volume. - * </para> - * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available - * when the gvfs hal volume monitor is in use. Other volume monitors - * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE - * identifier, which can be used to obtain a hal device by means of - * libhal_manger_find_device_string_match(). + * G_TYPE_PARAM_DOUBLE: * - * Of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, + * The #GType of #GParamSpecDouble. */ /** - * GLoadableIcon: + * G_TYPE_PARAM_ENUM: * - * Generic type for all kinds of icons that can be loaded - * as a stream. + * The #GType of #GParamSpecEnum. */ /** - * GBufferedInputStream: + * G_TYPE_PARAM_FLAGS: * - * Implements #GFilterInputStream with a sized input buffer. + * The #GType of #GParamSpecFlags. */ /** - * g_output_stream_write_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 + * G_TYPE_PARAM_FLOAT: * - * 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_finish() to get the result of the - * operation. - * During an async request no other sync and async calls are allowed, - * and will result in %G_IO_ERROR_PENDING errors. - * A value of @count larger than %G_MAXSSIZE will cause a - * %G_IO_ERROR_INVALID_ARGUMENT error. - * On success, the number of bytes written will be passed to the - * requested size, as it can happen e.g. on a partial I/O error, - * but generally we try to write as many bytes as requested. - * You are guaranteed that this method will never fail with - * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the - * method will just wait until this changes. - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. - * The asyncronous methods have a default fallback that uses threads - * to implement asynchronicity, so they are optional for inheriting - * classes. However, if you override one you must override all. - * For the synchronous, blocking version of this function, see - * g_output_stream_write(). + * The #GType of #GParamSpecFloat. */ /** - * g_tls_certificate_new_from_file: - * @file: file containing a PEM-encoded certificate to import - * @error: #GError for error reporting, or %NULL to ignore. + * G_TYPE_PARAM_GTYPE: * - * Creates a #GTlsCertificate from the PEM-encoded data in @file. If - * set @error. Otherwise, this behaves like g_tls_certificate_new(). + * The #GType of #GParamSpecGType. * - * Returns: the new certificate, or %NULL on error - * Since: 2.28 + * Since: 2.10 */ /** - * g_socket_condition_wait: - * @socket: a #GSocket - * @condition: a #GIOCondition mask to wait for - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: a #GError pointer, or %NULL - * - * Waits for @condition to become true on @socket. When the condition - * is met, %TRUE is returned. - * If @cancellable is cancelled before the condition is met, or if the - * socket has a timeout set and it is reached before the condition is - * met, then %FALSE is returned and @error, if non-%NULL, is set to - * the appropriate value (%G_IO_ERROR_CANCELLED or - * %G_IO_ERROR_TIMED_OUT). + * G_TYPE_PARAM_INT: * - * Returns: %TRUE if the condition was met, %FALSE otherwise - * Since: 2.22 + * The #GType of #GParamSpecInt. */ /** - * g_dbus_message_to_gerror: - * @message: A #GDBusMessage. - * @error: The #GError to set. - * - * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does - * nothing and returns %FALSE. - * Otherwise this method encodes the error in @message as a #GError - * using g_dbus_error_set_dbus_error() using the information in the - * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as - * well as the first string item in @message's body. + * G_TYPE_PARAM_INT64: * - * Returns: %TRUE if @error was set, %FALSE otherwise. - * Since: 2.26 + * The #GType of #GParamSpecInt64. */ /** - * g_signal_handlers_block_by_func: - * @instance: The instance to block handlers from. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. - * - * Blocks all handlers on an instance that match @func and @data. + * G_TYPE_PARAM_LONG: * - * Returns: The number of handlers that matched. + * The #GType of #GParamSpecLong. */ /** - * g_socket_client_connect_to_service_async: - * @client: a #GSocketClient - * @domain: a domain name - * @service: the name of the service to connect to - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * This is the asynchronous version of - * g_socket_client_connect_to_service(). + * G_TYPE_PARAM_OBJECT: * - * Since: 2.22 + * The #GType of #GParamSpecObject. */ /** - * g_mount_operation_get_domain: - * @op: a #GMountOperation. + * G_TYPE_PARAM_OVERRIDE: * - * Gets the domain of the mount operation. + * The #GType of #GParamSpecOverride. * - * Returns: a string set to the domain. + * Since: 2.4 */ /** - * g_file_info_get_display_name: - * @info: a #GFileInfo. - * - * Gets a display name for a file. + * G_TYPE_PARAM_PARAM: * - * Returns: a string containing the display name. + * The #GType of #GParamSpecParam. */ /** - * g_dbus_server_get_client_address: - * @server: A #GDBusServer. + * G_TYPE_PARAM_POINTER: * - * Gets a D-Bus address string that can be used by clients to connect - * to @server. - * by @server. + * The #GType of #GParamSpecPointer. + */ + + +/** + * G_TYPE_PARAM_STRING: * - * Returns: A D-Bus address string. Do not free, the string is owned - * Since: 2.26 + * The #GType of #GParamSpecString. */ /** - * g_socket_client_connect_to_service: - * @client: a #GSocketConnection - * @domain: a domain name - * @service: the name of the service to connect to - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: a pointer to a #GError, or %NULL - * @returns: (transfer full): a #GSocketConnection if successful, or %NULL on error + * G_TYPE_PARAM_UCHAR: * - * Attempts to create a TCP connection to a service. - * This call looks up the SRV record for @service at @domain for the - * "tcp" protocol. It then attempts to connect, in turn, to each of - * the hosts providing the service until either a connection succeeds - * or there are no hosts remaining. - * Upon a successful connection, a new #GSocketConnection is constructed - * and returned. The caller owns this new object and must drop their - * reference to it when finished with it. - * In the event of any failure (DNS error, service not found, no hosts - * connectable) %NULL is returned and @error (if non-%NULL) is set - * accordingly. + * The #GType of #GParamSpecUChar. */ /** - * g_dbus_connection_register_subtree: - * @connection: A #GDBusConnection. - * @object_path: The object path to register the subtree at. - * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree. - * @flags: Flags used to fine tune the behavior of the subtree. - * @user_data: Data to pass to functions in @vtable. - * @user_data_free_func: Function to call when the subtree is unregistered. - * @error: Return location for error or %NULL. + * G_TYPE_PARAM_UINT: * - * Registers a whole subtree of <quote>dynamic</quote> objects. - * The @enumerate and @introspection functions in @vtable are used to - * convey, to remote callers, what nodes exist in the subtree rooted - * by @object_path. - * When handling remote calls into any node in the subtree, first the - * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set - * the @introspection function is used to check if the node supports the - * requested method. If so, the @dispatch function is used to determine - * where to dispatch the call. The collected #GDBusInterfaceVTable and - * #gpointer will be used to call into the interface vtable for processing - * the request. - * All calls into user-provided code will be invoked in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread you are calling this method from. - * If an existing subtree is already registered at @object_path or - * then @error is set to #G_IO_ERROR_EXISTS. - * Note that it is valid to register regular objects (using - * g_dbus_connection_register_object()) in a subtree registered with - * g_dbus_connection_register_subtree() - if so, the subtree handler - * is tried as the last resort. One way to think about a subtree - * handler is to consider it a <quote>fallback handler</quote> - * for object paths not registered via g_dbus_connection_register_object() - * or other bindings. - * Note that @vtable will be copied so you cannot change it after - * registration. - * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method. - * that can be used with g_dbus_connection_unregister_subtree() . + * The #GType of #GParamSpecUInt. + */ + + +/** + * G_TYPE_PARAM_UINT64: * - * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) - * Since: 2.26 + * The #GType of #GParamSpecUInt64. */ /** - * G_VARIANT_TYPE_INT32: + * G_TYPE_PARAM_ULONG: * - * The type of an integer value that can range from -2147483648 to - * 2147483647. + * The #GType of #GParamSpecULong. */ /** - * SECTION:gseekabl: - * @short_description: Stream seeking interface - * @include: gio/gio.h - * @see_also: #GInputStream, #GOutputStream + * G_TYPE_PARAM_UNICHAR: * - * #GSeekable is implemented by streams (implementations of - * #GInputStream or #GOutputStream) that support seeking. + * The #GType of #GParamSpecUnichar. */ /** - * GObjectGetPropertyFunc: - * @object: a #GObject - * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). - * @value: a #GValue to return the property value in - * @pspec: the #GParamSpec describing the property + * G_TYPE_PARAM_VALUE_ARRAY: * - * The type of the @get_property function of #GObjectClass. + * The #GType of #GParamSpecValueArray. */ /** - * g_mount_get_drive: - * @mount: a #GMount. + * G_TYPE_PARAM_VARIANT: * - * Gets the drive for the @mount. - * This is a convenience method for getting the #GVolume and then - * using that object to get the #GDrive. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. + * The #GType of #GParamSpecVariant. * - * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive. + * Since: 2.26 */ /** - * g_file_get_parse_name: - * @file: input #GFile. - * - * Gets the parse name of the @file. - * A parse name is a UTF-8 string that describes the - * file such that one can get the #GFile back using - * g_file_parse_name(). - * This is generally used to show the #GFile as a nice - * full-pathname kind of string in a user interface, - * like in a location entry. - * For local files with names that can safely be converted - * to UTF8 the pathname is used, otherwise the IRI is used - * (a form of URI that allows UTF8 characters unescaped). - * This call does no blocking i/o. - * string should be freed with g_free() when no longer needed. + * G_TYPE_POINTER: * - * Returns: a string containing the #GFile's parse name. The returned + * The fundamental type corresponding to #gpointer. */ /** - * g_resolver_lookup_by_name_async: - * @resolver: a #GResolver - * @hostname: the hostname to look up the address of - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback + * G_TYPE_PTR_ARRAY: * - * Begins asynchronously resolving @hostname to determine its - * associated IP address(es), and eventually calls @callback, which - * must call g_resolver_lookup_by_name_finish() to get the result. - * See g_resolver_lookup_by_name() for more details. + * The #GType for a boxed type holding a #GPtrArray reference. * * Since: 2.22 */ /** - * GBusNameVanishedCallback: - * @connection: The #GDBusConnection the name is being watched on. - * @name: The name being watched. - * @user_data: User data passed to g_bus_watch_name(). + * G_TYPE_REGEX: * - * Invoked when the name being watched is known not to have to have a owner. + * The #GType for a boxed type holding a #GRegex reference. * - * Since: 2.26 + * Since: 2.14 */ /** - * SECTION:gfilteroutputstrea: - * @short_description: Filter Output Stream - * @include: gio/gio.h + * G_TYPE_RESERVED_BSE_FIRST: * - * Base class for output stream implementations that perform some - * kind of filtering operation on a base stream. Typical examples - * of filtering operations are character set conversion, compression - * and byte order flipping. + * First fundamental type number to create a new fundamental type id with + * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. */ /** - * GEnumValue: - * @value: the enum value - * @value_name: the name of the value - * @value_nick: the nickname of the value + * G_TYPE_RESERVED_BSE_LAST: * - * A structure which contains a single enum value, its name, and its - * nickname. + * Last fundamental type number reserved for BSE. */ /** - * g_file_equal: - * @file1: the first #GFile. - * @file2: the second #GFile. - * - * Checks equality of two given #GFile<!-- -->s. Note that two - * #GFile<!-- -->s that differ can still refer to the same - * file on the filesystem due to various forms of filename - * aliasing. - * This call does no blocking i/o. - * %FALSE if either is not a #GFile. + * G_TYPE_RESERVED_GLIB_FIRST: * - * Returns: %TRUE if @file1 and @file2 are equal. + * First fundamental type number to create a new fundamental type id with + * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. */ /** - * GOptionArg: - * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags. - * @G_OPTION_ARG_STRING: The option takes a string argument. - * @G_OPTION_ARG_INT: The option takes an integer argument. - * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument. - * @G_OPTION_ARG_FILENAME: The option takes a filename as argument. - * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings. - * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings. - * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12 - * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>). Since 2.12 - * - * The #GOptionArg enum values determine which type of extra argument the - * options expect to find. If an option expects an extra argument, it - * can be specified in several ways; with a short option: - * <option>-x arg</option>, with a long option: <option>--name arg</option> + * G_TYPE_RESERVED_GLIB_LAST: * - * Or combined in a single argument: <option>--name=arg</option>. + * Last fundamental type number reserved for GLib. */ /** - * g_file_set_attributes_async: - * @file: input #GFile. - * @info: a #GFileInfo. - * @flags: a #GFileQueryInfoFlags. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): a #gpointer. + * G_TYPE_RESERVED_USER_FIRST: * - * Asynchronously sets the attributes of @file with @info. - * For more details, see g_file_set_attributes_from_info() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_set_attributes_finish() to get the result of the operation. + * First available fundamental type number to create new fundamental + * type id with G_TYPE_MAKE_FUNDAMENTAL(). */ /** - * SECTION:gcharsetconverte: - * @short_description: Convert between charsets - * @include: gio/gio.h + * G_TYPE_STRING: * - * #GCharsetConverter is an implementation of #GConverter based on - * GIConv. + * The fundamental type corresponding to nul-terminated C strings. */ /** - * G_VALUE_HOLDS_INT: - * @value: a valid #GValue structure + * G_TYPE_STRV: * - * Checks whether the given #GValue can hold values of type %G_TYPE_INT. + * The #GType for a boxed type holding a %NULL-terminated array of strings. + * The code fragments in the following example show the use of a property of + * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set() + * and g_object_get(). + * |[ + * g_object_class_install_property (object_class, + * PROP_AUTHORS, + * g_param_spec_boxed ("authors", + * _("Authors"), + * _("List of authors"), + * G_TYPE_STRV, + * G_PARAM_READWRITE)); + * gchar *authors[] = { "Owen", "Tim", NULL }; + * g_object_set (obj, "authors", authors, NULL); + * gchar *writers[]; + * g_object_get (obj, "authors", &writers, NULL); + * // do something with writers + * g_strfreev (writers); + * ]| * - * Returns: %TRUE on success. + * Since: 2.4 */ /** - * g_dbus_method_invocation_get_parameters: - * @invocation: A #GDBusMethodInvocation. - * - * Gets the parameters of the method invocation. + * G_TYPE_UCHAR: * - * Returns: A #GVariant. Do not free, it is owned by @invocation. - * Since: 2.26 + * The fundamental type corresponding to #guchar. */ /** - * g_output_stream_close_async: - * @stream: A #GOutputStream. - * @io_priority: the io priority of the request. - * @cancellable: (allow-none): optional cancellable object - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * G_TYPE_UINT: * - * Requests an asynchronous close of the stream, releasing resources - * related to it. When the operation is finished @callback will be - * called. You can then call g_output_stream_close_finish() to get - * the result of the operation. - * For behaviour details see g_output_stream_close(). - * The asyncronous methods have a default fallback that uses threads - * to implement asynchronicity, so they are optional for inheriting - * classes. However, if you override one you must override all. + * The fundamental type corresponding to #guint. */ /** - * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT: + * G_TYPE_UINT64: * - * A key in the "unix" namespace for checking if the file represents a - * UNIX mount point. This attribute is %TRUE if the file is a UNIX mount - * point. This attribute is only available for UNIX file systems. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * The fundamental type corresponding to #guint64. */ /** - * g_dbus_message_to_blob: - * @message: A #GDBusMessage. - * @out_size: Return location for size of generated blob. - * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported. - * @error: Return location for error. - * - * Serializes @message to a blob. The byte order returned by - * g_dbus_message_get_byte_order() will be used. - * generated by @message or %NULL if @error is set. Free with g_free(). + * G_TYPE_ULONG: * - * Returns: A pointer to a valid binary D-Bus message of @out_size bytes - * Since: 2.26 + * The fundamental type corresponding to #gulong. */ /** - * SECTION:giostrea: - * @short_description: Base class for implementing read/write streams - * @include: gio/gio.h - * @see_also: #GInputStream, #GOutputStream - * - * GIOStream represents an object that has both read and write streams. - * Generally the two streams acts as separate input and output streams, - * but they share some common resources and state. For instance, for - * seekable streams they may use the same position in both streams. - * Examples of #GIOStream objects are #GSocketConnection which represents - * a two-way network connection, and #GFileIOStream which represent a - * file handle opened in read-write mode. - * To do the actual reading and writing you need to get the substreams - * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream(). - * The #GIOStream object owns the input and the output streams, not the other - * way around, so keeping the substreams alive will not keep the #GIOStream - * object alive. If the #GIOStream object is freed it will be closed, thus - * closing the substream, so even if the substreams stay alive they will - * always just return a %G_IO_ERROR_CLOSED for all operations. - * To close a stream use g_io_stream_close() which will close the common - * stream object and also the individual substreams. You can also close - * the substreams themselves. In most cases this only marks the - * substream as closed, so further I/O on it fails. However, some streams - * may support "half-closed" states where one direction of the stream - * is actually shut down. + * G_TYPE_VALUE: * - * Since: 2.22 + * The type ID of the "GValue" type which is a boxed type, + * used to pass around pointers to GValues. */ /** - * g_socket_client_get_local_address: - * @client: a #GSocketClient. - * - * Gets the local address of the socket client. - * See g_socket_client_set_local_address() for details. + * G_TYPE_VALUE_ARRAY: * - * Returns: (transfer none): a #GSocketAddres or %NULL. don't free - * Since: 2.22 + * The type ID of the "GValueArray" type which is a boxed type, + * used to pass around pointers to GValueArrays. */ /** - * g_data_input_stream_read_uint64: - * @stream: a given #GDataInputStream. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * G_TYPE_VARIANT: * - * Reads an unsigned 64-bit/8-byte value from @stream. - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order(). - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * an error occurred. + * The fundamental type corresponding to #GVariant. + * All floating #GVariant instances passed through the #GType system are + * consumed. + * Note that callbacks in closures, and signal handlers + * for signals of return type %G_TYPE_VARIANT, must never return floating + * variants. + * with this fundamental type in 2.26. * - * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if + * Note: GLib 2.24 did include a boxed type with this name. It was replaced + * Since: 2.26 */ /** - * g_proxy_connect: - * @proxy: a #GProxy - * @connection: a #GIOStream - * @proxy_address: a #GProxyAddress - * @cancellable: (allow-none): a #GCancellable - * @error: return #GError + * G_TYPE_VARIANT_TYPE: * - * Given @connection to communicate with a proxy (eg, a - * #GSocketConnection that is connected to the proxy server), this - * does the necessary handshake to connect to @proxy_address, and if - * required, wraps the #GIOStream to handle proxy payload. - * be the same as @connection, in which case a reference - * will be added. + * The #GType for a boxed type holding a #GVariantType. * - * Returns: (transfer full): a #GIOStream that will replace @connection. This might - * Since: 2.26 + * Since: 2.24 */ /** - * g_content_type_guess: - * @filename: (allow-none): a string, or %NULL - * @data: (allow-none) (array length=data_size): a stream of data, or %NULL - * @data_size: the size of @data - * @result_uncertain: (allow-none) (out): return location for the certainty of the result, or %NULL - * - * Guesses the content type based on example data. If the function is - * uncertain, @result_uncertain will be set to %TRUE. Either @filename - * or @data may be %NULL, in which case the guess will be based solely - * on the other argument. - * given data. Free with g_free() + * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH: * - * Returns: a string indicating a guessed content type for the + * Allowed characters in a path. Includes "!$&'()*+,;=:@/". */ /** - * g_settings_backend_keys_changed: - * @backend: a #GSettingsBackend implementation - * @path: the path containing the changes - * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys - * @origin_tag: the origin tag - * - * Signals that a list of keys have possibly changed. Backend - * implementations should call this if keys have possibly changed their - * values. - * not containing '//'). Each string in @items must form a valid key - * end with '/' and must not contain '//'). - * The meaning of this signal is that any of the key names resulting - * from the contatenation of @path with each item in @items may have - * changed. - * The same rules for when notifications must occur apply as per - * g_settings_backend_changed(). These two calls can be used - * interchangeably if exactly one item has changed (although in that - * case g_settings_backend_changed() is definitely preferred). - * For efficiency reasons, the implementation should strive for @path to - * keys that were changed) but this is not strictly required. + * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT: * - * Name when @path is prefixed to it (ie: each item must not start or - * Be as long as possible (ie: the longest common prefix of all of the - * Since: 2.26 + * Allowed characters in path elements. Includes "!$&'()*+,;=:@". */ /** - * GDataStreamNewlineType: - * @G_DATA_STREAM_NEWLINE_TYPE_LF: Selects "LF" line endings, common on most modern UNIX platforms. - * @G_DATA_STREAM_NEWLINE_TYPE_CR: Selects "CR" line endings. - * @G_DATA_STREAM_NEWLINE_TYPE_CR_LF: Selects "CR, LF" line ending, common on Microsoft Windows. - * @G_DATA_STREAM_NEWLINE_TYPE_ANY: Automatically try to handle any line ending type. + * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO: * - * #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. + * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:". */ /** - * GOutputVector: - * @buffer: Pointer to a buffer of data to read. - * @size: the size of @buffer. - * - * Structure used for scatter/gather data output. - * You generally pass in an array of #GOutputVector<!-- -->s - * and the operation will use all the buffers as if they were - * one buffer. + * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS: * - * Since: 2.22 + * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". */ /** - * g_file_query_writable_namespaces: - * @file: input #GFile. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL - * - * Obtain the list of attribute namespaces where new attributes - * can be created by a user. An example of this is extended - * attributes (in the "xattr" namespace). - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * When you are done with it, release it with g_file_attribute_info_list_unref() + * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITER: * - * Returns: a #GFileAttributeInfoList describing the writable namespaces. + * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". */ /** - * g_file_eject_mountable_with_operation: - * @file: input #GFile. - * @flags: flags affecting the operation - * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. - * @user_data: (closure): the data to pass to callback function + * G_VALUE_HOLDS: + * @value: A #GValue structure. + * @type: A #GType value. * - * Starts an asynchronous eject on a mountable. - * When this operation has completed, @callback will be called with - * g_file_eject_mountable_with_operation_finish(). - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Checks if @value holds (or contains) a value of @type. + * This macro will also check for @value != %NULL and issue a + * warning if the check fails. * - * Since: 2.22 + * Returns: %TRUE if @value holds the @type. */ /** - * G_TYPE_PTR_ARRAY: + * G_VALUE_HOLDS_BOOLEAN: + * @value: a valid #GValue structure * - * The #GType for a boxed type holding a #GPtrArray reference. + * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. * - * Since: 2.22 + * Returns: %TRUE on success. */ /** - * g_dbus_message_new_method_error_valist: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. - * @error_name: A valid D-Bus error name. - * @error_message_format: The D-Bus error message in a printf() format. - * @var_args: Arguments for @error_message_format. + * G_VALUE_HOLDS_BOXED: + * @value: a valid #GValue structure * - * Like g_dbus_message_new_method_error() but intended for language bindings. + * Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. * - * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_socket_set_listen_backlog: - * @socket: a #GSocket. - * @backlog: the maximum number of pending connections. + * G_VALUE_HOLDS_CHAR: + * @value: a valid #GValue structure * - * Sets the maximum number of outstanding connections allowed - * when listening on this socket. If more clients than this are - * connecting to the socket and the application is not handling them - * on time then the new connections will be refused. - * Note that this must be called before g_socket_listen() and has no - * effect if called after that. + * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. * - * Since: 2.22 + * Returns: %TRUE on success. */ /** - * G_IS_PARAM_SPEC_POINTER: - * @pspec: a valid #GParamSpec instance + * G_VALUE_HOLDS_DOUBLE: + * @value: a valid #GValue structure * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. + * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. * * Returns: %TRUE on success. */ /** - * GUnixCredentialsMessageClass: + * G_VALUE_HOLDS_ENUM: + * @value: a valid #GValue structure * - * Class structure for #GUnixCredentialsMessage. + * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_proxy_resolver_get_default: + * G_VALUE_HOLDS_FLAGS: + * @value: a valid #GValue structure * - * Gets the default #GProxyResolver for the system. + * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. * - * Returns: (transfer none): the default #GProxyResolver. - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_settings_delay: - * @settings: a #GSettings object + * G_VALUE_HOLDS_FLOAT: + * @value: a valid #GValue structure * - * Changes the #GSettings object into 'delay-apply' mode. In this - * mode, changes to @settings are not immediately propagated to the - * backend, but kept locally until g_settings_apply() is called. + * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * GMemoryOutputStream:destroy-function: (skip) + * G_VALUE_HOLDS_GTYPE: + * @value: a valid #GValue structure * - * Function called with the buffer as argument when the stream is destroyed. + * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. * - * Since: 2.24 + * Since: 2.12 + * Returns: %TRUE on success. */ /** - * GFileInputStream: + * G_VALUE_HOLDS_INT: + * @value: a valid #GValue structure * - * A subclass of GInputStream for opened files. This adds - * a few file-specific operations and seeking. - * #GFileInputStream implements #GSeekable. + * Checks whether the given #GValue can hold values of type %G_TYPE_INT. + * + * Returns: %TRUE on success. */ /** - * SECTION:gwin32outputstrea: - * @short_description: Streaming output operations for Windows file handles - * @include: gio/gwin32outputstream.h - * @see_also: #GOutputStream + * G_VALUE_HOLDS_INT64: + * @value: a valid #GValue structure * - * #GWin32OutputStream implements #GOutputStream for writing to a - * Windows file handle. - * Note that <filename><gio/gwin32outputstream.h></filename> belongs - * to the Windows-specific GIO interfaces, thus you have to use the - * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it. + * Checks whether the given #GValue can hold values of type %G_TYPE_INT64. + * + * Returns: %TRUE on success. */ /** - * g_file_monitor_is_cancelled: - * @monitor: a #GFileMonitor + * G_VALUE_HOLDS_LONG: + * @value: a valid #GValue structure * - * Returns whether the monitor is canceled. + * Checks whether the given #GValue can hold values of type %G_TYPE_LONG. * - * Returns: %TRUE if monitor is canceled. %FALSE otherwise. + * Returns: %TRUE on success. */ /** - * G_PARAM_SPEC_CLASS: - * @pclass: a valid #GParamSpecClass + * G_VALUE_HOLDS_OBJECT: + * @value: a valid #GValue structure * - * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. + * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. + * + * Returns: %TRUE on success. */ /** - * g_file_set_attributes_from_info: - * @file: input #GFile. - * @info: a #GFileInfo. - * @flags: #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * G_VALUE_HOLDS_PARAM: + * @value: a valid #GValue structure * - * Tries to set all attributes in the #GFileInfo on the target values, - * not stopping on the first error. - * If there is any error during this operation then @error will be set to - * the first error. Error on particular fields are flagged by setting - * the "status" field in the attribute value to - * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect - * further errors. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. * - * Returns: %TRUE if there was any error, %FALSE otherwise. + * Returns: %TRUE on success. */ /** - * G_TYPE_IS_ABSTRACT: - * @type: A #GType value. + * G_VALUE_HOLDS_POINTER: + * @value: a valid #GValue structure * - * Checks if @type is an abstract type. An abstract type can not be - * instantiated and is normally used as an abstract base class for - * derived classes. + * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. * * Returns: %TRUE on success. */ /** - * g_settings_is_writable: - * @settings: a #GSettings object - * @name: the name of a key - * @returns: %TRUE if the key @name is writable + * G_VALUE_HOLDS_STRING: + * @value: a valid #GValue structure * - * Finds out if a key can be written or not + * Checks whether the given #GValue can hold values of type %G_TYPE_STRING. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * GCallback: + * G_VALUE_HOLDS_UCHAR: + * @value: a valid #GValue structure * - * The type used for callback functions in structure definitions and function - * signatures. This doesn't mean that all callback functions must take no - * parameters and return void. The required signature of a callback function - * is determined by the context in which is used (e.g. the signal to which it - * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. + * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. + * + * Returns: %TRUE on success. */ /** - * g_file_create_async: - * @file: input #GFile. - * @flags: a set of #GFileCreateFlags. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * G_VALUE_HOLDS_UINT: + * @value: a valid #GValue structure * - * Asynchronously creates a new file and returns an output stream for writing to it. - * The file must not already exist. - * For more details, see g_file_create() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_create_finish() to get the result of the operation. + * Checks whether the given #GValue can hold values of type %G_TYPE_UINT. + * + * Returns: %TRUE on success. */ /** - * g_output_stream_splice_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * G_VALUE_HOLDS_UINT64: + * @value: a valid #GValue structure * - * Finishes an asynchronous stream splice operation. + * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. * - * Returns: a #gssize of the number of bytes spliced. + * Returns: %TRUE on success. */ /** - * g_socket_shutdown: - * @socket: a #GSocket - * @shutdown_read: whether to shut down the read side - * @shutdown_write: whether to shut down the write side - * @error: #GError for error reporting, or %NULL to ignore. + * G_VALUE_HOLDS_ULONG: + * @value: a valid #GValue structure * - * Shut down part of a full-duplex connection. - * If @shutdown_read is %TRUE then the recieving side of the connection - * is shut down, and further reading is disallowed. - * If @shutdown_write is %TRUE then the sending side of the connection - * is shut down, and further writing is disallowed. - * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE. - * One example where this is used is graceful disconnect for TCP connections - * where you close the sending side, then wait for the other side to close - * the connection, thus ensuring that the other side saw all sent data. + * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. * - * Returns: %TRUE on success, %FALSE on error - * Since: 2.22 + * Returns: %TRUE on success. */ /** - * G_PARAM_SPEC_DOUBLE: - * @pspec: a valid #GParamSpec instance + * G_VALUE_HOLDS_VARIANT: + * @value: a valid #GValue structure * - * Cast a #GParamSpec instance into a #GParamSpecDouble. + * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. + * + * Returns: %TRUE on success. + * Since: 2.26 */ /** - * g_file_get_relative_path: - * @parent: input #GFile. - * @descendant: input #GFile. + * G_VALUE_TYPE: + * @value: A #GValue structure. * - * Gets the path for @descendant relative to @parent. - * This call does no blocking i/o. - * to @parent, or %NULL if @descendant doesn't have @parent as prefix. - * The returned string should be freed with g_free() when no longer needed. + * Get the type identifier of @value. * - * Returns: string with the relative path from @descendant + * Returns: the #GType. */ /** - * g_simple_async_result_take_error: (skip) - * @simple: a #GSimpleAsyncResult - * @error: a #GError + * G_VALUE_TYPE_NAME: + * @value: A #GValue structure. * - * Sets the result from @error, and takes over the caller's ownership - * of @error, so the caller does not need to free it any more. + * Gets the the type name of @value. * - * Since: 2.28 + * Returns: the type name. */ /** - * GClosureNotify: - * @data: data specified when registering the notification callback - * @closure: the #GClosure on which the notification is emitted + * G_VARIANT_TYPE: + * @type_string: a well-formed #GVariantType type string * - * The type used for the various notification callbacks which can be registered - * on closures. + * Converts a string to a const #GVariantType. Depending on the + * current debugging level, this function may perform a runtime check + * to ensure that @string is a valid GVariant type string. + * It is always a programmer error to use this macro with an invalid + * type string. + * Since 2.24 */ /** - * g_unix_is_mount_path_system_internal: - * @mount_path: a mount path, e.g. <filename>/media/disk</filename> or <filename>/usr</filename> - * - * Determines if @mount_path is considered an implementation of the - * OS. This is primarily used for hiding mountable and mounted volumes - * that only are used in the OS and has little to no relevance to the - * casual user. - * of the OS. + * G_VARIANT_TYPE_ANY: * - * Returns: %TRUE if @mount_path is considered an implementation detail + * An indefinite type that is a supertype of every type (including + * itself). */ /** - * g_emblemed_icon_new: - * @icon: a #GIcon - * @emblem: (allow-none): a #GEmblem, or %NULL - * - * Creates a new emblemed icon for @icon with the emblem @emblem. + * G_VARIANT_TYPE_ARRAY: * - * Returns: (transfer full): a new #GIcon - * Since: 2.18 + * An indefinite type that is a supertype of every array type. */ /** - * G_TYPE_DBUS_ANNOTATION_INFO: - * - * The #GType for a boxed type holding a #GDBusAnnotationInfo. + * G_VARIANT_TYPE_BASIC: * - * Since: 2.26 + * An indefinite type that is a supertype of every basic (ie: + * non-container) type. */ /** - * GSignalInvocationHint: - * @signal_id: The signal id of the signal invoking the callback - * @detail: The detail passed on for this emission - * @run_type: The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. + * G_VARIANT_TYPE_BOOLEAN: * - * The #GSignalInvocationHint structure is used to pass on additional information - * to callbacks during a signal emission. + * The type of a value that can be either %TRUE or %FALSE. */ /** - * g_tls_connection_get_peer_certificate: - * @conn: a #GTlsConnection - * - * Gets @conn's peer's certificate after the handshake has completed. - * (It is not set during the emission of - * #GTlsConnection::accept-certificate.) + * G_VARIANT_TYPE_BYTE: * - * Returns: (transfer none): @conn's peer's certificate, or %NULL - * Since: 2.28 + * The type of an integer value that can range from 0 to 255. */ /** - * g_file_eject_mountable_finish: - * @file: input #GFile. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes an asynchronous eject operation started by - * g_file_eject_mountable(). - * otherwise. + * G_VARIANT_TYPE_BYTESTRING: * - * Returns: %TRUE if the @file was ejected successfully. %FALSE - * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead. + * The type of an array of bytes. This type is commonly used to pass + * around strings that may not be valid utf8. In that case, the + * convention is that the nul terminator character should be included as + * the last character in the array. */ /** - * g_local_vfs_new: - * - * Returns a new #GVfs handle for a local vfs. + * G_VARIANT_TYPE_BYTESTRING_ARRAY: * - * Returns: a new #GVfs handle. + * The type of an array of byte strings (an array of arrays of bytes). */ /** - * GDBusServer::new-connection: - * @server: The #GDBusServer emitting the signal. - * @connection: A #GDBusConnection for the new connection. - * - * Emitted when a new authenticated connection has been made. Use - * g_dbus_connection_get_peer_credentials() to figure out what - * identity (if any), was authenticated. - * If you want to accept the connection, take a reference to the - * connection call g_dbus_connection_close() and give up your - * reference. Note that the other peer may disconnect at any time - - * a typical thing to do when accepting a connection is to listen to - * the #GDBusConnection::closed signal. - * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD - * then the signal is emitted in a new thread dedicated to the - * connection. Otherwise the signal is emitted in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread that @server was constructed in. - * You are guaranteed that signal handlers for this signal runs - * before incoming messages on @connection are processed. This means - * that it's suitable to call g_dbus_connection_register_object() or - * similar from the signal handler. - * run. + * G_VARIANT_TYPE_DICTIONARY: * - * Returns: %TRUE to claim @connection, %FALSE to let other handlers - * Since: 2.26 + * An indefinite type that is a supertype of every dictionary type -- + * that is, any array type that has an element type equal to any + * dictionary entry type. */ /** - * g_tls_backend_get_certificate_type: - * @backend: the #GTlsBackend - * - * Gets the #GType of @backend's #GTlsCertificate implementation. - * implementation. + * G_VARIANT_TYPE_DICT_ENTRY: * - * Returns: the #GType of @backend's #GTlsCertificate - * Since: 2.28 + * An indefinite type that is a supertype of every dictionary entry + * type. */ /** - * g_action_group_action_added: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group - * - * Emits the #GActionGroup::action-added signal on @action_group. - * This function should only be called by #GActionGroup implementations. + * G_VARIANT_TYPE_DOUBLE: * - * Since: 2.28 + * The type of a double precision IEEE754 floating point number. + * These guys go up to about 1.80e308 (plus and minus) but miss out on + * some numbers in between. In any case, that's far greater than the + * estimated number of fundamental particles in the observable + * universe. */ /** - * g_output_stream_has_pending: - * @stream: a #GOutputStream. - * - * Checks if an ouput stream has pending actions. + * G_VARIANT_TYPE_HANDLE: * - * Returns: %TRUE if @stream has pending actions. + * The type of a 32bit signed integer value, that by convention, is used + * as an index into an array of file descriptors that are sent alongside + * a DBus message. + * If you are not interacting with DBus, then there is no reason to make + * use of this type. */ /** - * GDBusConnection:capabilities: - * - * Flags from the #GDBusCapabilityFlags enumeration - * representing connection features negotiated with the other peer. + * G_VARIANT_TYPE_INT16: * - * Since: 2.26 + * The type of an integer value that can range from -32768 to 32767. */ /** - * GReallocFunc: - * @data: memory block to reallocate - * @size: size to reallocate @data to - * - * Changes the size of the memory block pointed to by @data to - * The function should have the same semantics as realloc(). + * G_VARIANT_TYPE_INT32: * - * Returns: a pointer to the reallocated memory + * The type of an integer value that can range from -2147483648 to + * 2147483647. */ /** - * g_dbus_error_unregister_error: - * @error_domain: A #GQuark for a error domain. - * @error_code: An error code. - * @dbus_error_name: A D-Bus error name. - * - * Destroys an association previously set up with g_dbus_error_register_error(). + * G_VARIANT_TYPE_INT64: * - * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found. - * Since: 2.26 + * The type of an integer value that can range from + * -9223372036854775808 to 9223372036854775807. */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START: - * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * G_VARIANT_TYPE_MAYBE: * - * Since: 2.22 + * An indefinite type that is a supertype of every maybe type. */ /** - * SECTION:gcancellabl: - * @short_description: Thread-safe Operation Cancellation Stack - * @include: gio/gio.h + * G_VARIANT_TYPE_OBJECT_PATH: * - * GCancellable is a thread-safe operation cancellation stack used - * throughout GIO to allow for cancellation of synchronous and - * asynchronous operations. + * The type of a DBus object reference. These are strings of a + * specific format used to identify objects at a given destination on + * the bus. + * If you are not interacting with DBus, then there is no reason to make + * use of this type. If you are, then the DBus specification contains a + * precise description of valid object paths. */ /** - * g_buffered_input_stream_peek: - * @stream: a #GBufferedInputStream - * @buffer: a pointer to an allocated chunk of memory - * @offset: a #gsize - * @count: a #gsize - * - * Peeks in the buffer, copying data of size @count into @buffer, - * offset @offset bytes. + * G_VARIANT_TYPE_SIGNATURE: * - * Returns: a #gsize of the number of bytes peeked, or -1 on error. + * The type of a DBus type signature. These are strings of a specific + * format used as type signatures for DBus methods and messages. + * If you are not interacting with DBus, then there is no reason to make + * use of this type. If you are, then the DBus specification contains a + * precise description of valid signature strings. */ /** - * g_file_is_native: - * @file: input #GFile. - * - * Checks to see if a file is native to the platform. - * A native file s one expressed in the platform-native filename format, - * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, - * as it might be on a locally mounted remote filesystem. - * On some systems non-native files may be available using - * the native filesystem via a userspace filesystem (FUSE), in - * these cases this call will return %FALSE, but g_file_get_path() - * will still return a native path. - * This call does no blocking i/o. + * G_VARIANT_TYPE_STRING: * - * Returns: %TRUE if file is native. + * The type of a string. "" is a string. %NULL is not a string. */ /** - * g_file_set_attribute_uint64: - * @file: input #GFile. - * @attribute: a string containing the attribute's name. - * @value: a #guint64 containing the attribute's new value. - * @flags: a #GFileQueryInfoFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL - * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. - * If @attribute is of a different type, this operation will fail. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * in the @file, %FALSE otherwise. + * G_VARIANT_TYPE_STRING_ARRAY: * - * Returns: %TRUE if the @attribute was successfully set to @value + * The type of an array of strings. */ /** - * g_output_stream_flush_finish: - * @stream: a #GOutputStream. - * @result: a GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. - * - * Finishes flushing an output stream. + * G_VARIANT_TYPE_TUPLE: * - * Returns: %TRUE if flush operation suceeded, %FALSE otherwise. + * An indefinite type that is a supertype of every tuple type, + * regardless of the number of items in the tuple. */ /** - * g_volume_get_icon: - * @volume: a #GVolume. - * - * Gets the icon for @volume. - * The returned object should be unreffed with g_object_unref() - * when no longer needed. + * G_VARIANT_TYPE_UINT16: * - * Returns: (transfer full): a #GIcon. + * The type of an integer value that can range from 0 to 65535. + * There were about this many people living in Toronto in the 1870s. */ /** - * GMountOperation::aborted: - * - * Emitted by the backend when e.g. a device becomes unavailable - * while a mount operation is in progress. - * Implementations of GMountOperation should handle this signal - * by dismissing open password dialogs. + * G_VARIANT_TYPE_UINT32: * - * Since: 2.20 + * The type of an integer value that can range from 0 to 4294967295. + * That's one number for everyone who was around in the late 1970s. */ /** - * g_charset_converter_get_use_fallback: - * @converter: a #GCharsetConverter - * - * Gets the #GCharsetConverter:use-fallback property. + * G_VARIANT_TYPE_UINT64: * - * Returns: %TRUE if fallbacks are used by @converter - * Since: 2.24 + * The type of an integer value that can range from 0 to + * 18446744073709551616. That's a really big number, but a Rubik's + * cube can have a bit more than twice as many possible positions. */ /** - * g_win32_output_stream_set_close_handle: - * @stream: a #GWin32OutputStream - * @close_handle: %TRUE to close the handle when done - * - * Sets whether the handle of @stream shall be closed when the stream - * is closed. + * G_VARIANT_TYPE_UNIT: * - * Since: 2.26 + * The empty tuple type. Has only one instance. Known also as "triv" + * or "void". */ /** - * g_converter_convert: - * @converter: a #GConverter. - * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer containing the data to convert. - * @inbuf_size: the number of bytes in @inbuf - * @outbuf: a buffer to write converted data in. - * @outbuf_size: the number of bytes in @outbuf, must be at least one - * @flags: a #GConvertFlags controlling the conversion details - * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success - * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success - * @error: location to store the error occuring, or %NULL to ignore - * - * This is the main operation used when converting data. It is to be called - * multiple times in a loop, and each time it will do some work, i.e. - * producing some output (in @outbuf) or consuming some input (from @inbuf) or - * both. If its not possible to do any work an error is returned. - * Note that a single call may not consume all input (or any input at all). - * Also a call may produce output even if given no input, due to state stored - * in the converter producing output. - * If any data was either produced or consumed, and then an error happens, then - * only the successful conversion is reported and the error is returned on the - * next call. - * A full conversion loop involves calling this method repeatedly, each time - * giving it new input and space output space. When there is no more input - * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set. - * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED - * each time until all data is consumed and all output is produced, then - * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED - * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance - * in a decompression converter where the end of data is detectable from the - * data (and there might even be other data after the end of the compressed data). - * When some data has successfully been converted @bytes_read and is set to - * the number of bytes read from @inbuf, and @bytes_written is set to indicate - * how many bytes was written to @outbuf. If there are more data to output - * or consume (i.e. unless the G_CONVERTER_INPUT_AT_END is specified) then - * G_CONVERTER_CONVERTED is returned, and if no more data is to be output - * then G_CONVERTER_FINISHED is returned. - * On error %G_CONVERTER_ERROR is returned and @error is set accordingly. - * Some errors need special handling: - * %G_IO_ERROR_NO_SPACE is returned if there is not enough space - * to write the resulting converted data, the application should - * call the function again with a larger @outbuf to continue. - * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough - * input to fully determine what the conversion should produce, - * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for - * example with an incomplete multibyte sequence when converting text, - * or when a regexp matches up to the end of the input (and may match - * further input). It may also happen when @inbuf_size is zero and - * there is no more data to produce. - * When this happens the application should read more input and then - * call the function again. If further input shows that there is no - * more data call the function again with the same data but with - * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion - * to finish as e.g. in the regexp match case (or, to fail again with - * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the - * input is actually partial). - * After g_converter_convert() has returned %G_CONVERTER_FINISHED the - * converter object is in an invalid state where its not allowed - * to call g_converter_convert() anymore. At this time you can only - * free the object or call g_converter_reset() to reset it to the - * initial state. - * If the flag %G_CONVERTER_FLUSH is set then conversion is modified - * to try to write out all internal state to the output. The application - * has to call the function multiple times with the flag set, and when - * the availible input has been consumed and all internal state has - * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if - * really at the end) is returned instead of %G_CONVERTER_CONVERTED. - * This is somewhat similar to what happens at the end of the input stream, - * but done in the middle of the data. - * This has different meanings for different conversions. For instance - * in a compression converter it would mean that we flush all the - * compression state into output such that if you uncompress the - * compressed data you get back all the input data. Doing this may - * make the final file larger due to padding though. Another example - * is a regexp conversion, where if you at the end of the flushed data - * have a match, but there is also a potential longer match. In the - * non-flushed case we would ask for more input, but when flushing we - * treat this as the end of input and do the match. - * Flushing is not always possible (like if a charset converter flushes - * at a partial multibyte sequence). Converters are supposed to try - * to produce as much output as possible and then return an error - * (typically %G_IO_ERROR_PARTIAL_INPUT). + * G_VARIANT_TYPE_VARIANT: * - * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error. - * Since: 2.24 + * The type of a box that contains any other value (including another + * variant). */ /** - * G_INITIALLY_UNOWNED: - * @object: Object which is subject to casting. + * G_VFS_EXTENSION_POINT_NAME: * - * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) - * pointer. Depending on the current debugging level, this function may invoke - * certain runtime checks to identify invalid casts. + * Extension point for #GVfs functionality. + * See <link linkend="extending-gio">Extending GIO</link>. */ /** - * g_unix_mounts_changed_since: - * @time: guint64 to contain a timestamp. - * - * Checks if the unix mounts have changed since a given unix time. + * G_VOLUME_IDENTIFIER_KIND_HAL_UDI: * - * Returns: %TRUE if the mounts have changed since @time. + * The string used to obtain a Hal UDI with g_volume_get_identifier(). */ /** - * GAction:state: - * - * The state of the action, or %NULL if the action is stateless. + * G_VOLUME_IDENTIFIER_KIND_LABEL: * - * Since: 2.28 + * The string used to obtain a filesystem label with g_volume_get_identifier(). */ /** - * g_file_info_get_attribute_int64: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets a signed 64-bit integer contained within the attribute. If the - * attribute does not contain an signed 64-bit integer, or is invalid, - * 0 will be returned. + * G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT: * - * Returns: a signed 64-bit integer from the attribute. + * The string used to obtain a NFS mount with g_volume_get_identifier(). */ /** - * g_unix_socket_address_get_is_abstract: - * @address: a #GInetSocketAddress - * - * Tests if @address is abstract. + * G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE: * - * Returns: %TRUE if the address is abstract, %FALSE otherwise - * Since: 2.22 - * Deprecated: Use g_unix_socket_address_get_address_type() + * The string used to obtain a Unix device path with g_volume_get_identifier(). */ /** - * g_io_extension_get_name: - * @extension: a #GIOExtension - * - * Gets the name under which @extension was registered. - * Note that the same type may be registered as extension - * for multiple extension points, under different names. + * G_VOLUME_IDENTIFIER_KIND_UUID: * - * Returns: the name of @extension. + * The string used to obtain a UUID with g_volume_get_identifier(). */ /** - * GTcpConnection: - * - * A #GSocketConnection for UNIX domain socket connections. + * G_VOLUME_MONITOR_EXTENSION_POINT_NAME: * - * Since: 2.22 + * Extension point for volume monitor functionality. + * See <link linkend="extending-gio">Extending GIO</link>. */ /** - * g_settings_backend_changed_tree: - * @backend: a #GSettingsBackend implementation - * @tree: a #GTree containing the changes - * @origin_tag: the origin tag + * SECTION: + * @title: GUnixFDMessage + * @short_description: A GSocketControlMessage containing a GUnixFDList + * @include: gio/gunixfdmessage.h + * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage * - * This call is a convenience wrapper. It gets the list of changes from - * g_settings_backend_changed(). + * This #GSocketControlMessage contains a #GUnixFDList. + * It may be sent using g_socket_send_message() and received using + * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied + * between processes by the kernel. + * For an easier way to send and receive file descriptors over + * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and + * g_unix_connection_receive_fd(). + * Note that <filename><gio/gunixfdmessage.h></filename> belongs to + * the UNIX-specific GIO interfaces, thus you have to use the + * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. * - * Since: 2.26 + * G_socket_receive_message() over unix sockets (ie: sockets in the */ /** - * g_socket_client_connect_to_host: - * @client: a #GSocketClient - * @host_and_port: the name and optionally port of the host to connect to - * @default_port: the default port to connect to - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: a pointer to a #GError, or %NULL - * - * This is a helper function for g_socket_client_connect(). - * Attempts to create a TCP connection to the named host. - * address, an IPv4 address, or a domain name (in which case a DNS - * lookup is performed). Quoting with [] is supported for all address - * types. A port override may be specified in the usual way with a - * colon. Ports may be given as decimal numbers or symbolic names (in - * which case an /etc/services lookup is performed). - * If no port override is given in @host_and_port then @default_port will be - * used as the port number to connect to. - * In general, @host_and_port is expected to be provided by the user (allowing - * them to give the hostname, and a port overide if necessary) and - * In the case that an IP address is given, a single connection - * attempt is made. In the case that a name is given, multiple - * connection attempts may be made, in turn and according to the - * number of address records in DNS, until a connection succeeds. - * Upon a successful connection, a new #GSocketConnection is constructed - * and returned. The caller owns this new object and must drop their - * reference to it when finished with it. - * In the event of any failure (DNS error, service not found, no hosts - * connectable) %NULL is returned and @error (if non-%NULL) is set - * accordingly. + * SECTION:extensionpoint: + * @short_description: Extension Points + * @include: gio.h + * @see_also: <link linkend="extending-gio">Extending GIO</link> * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 + * #GIOExtensionPoint provides a mechanism for modules to extend the + * functionality of the library or application that loaded it in an + * organized fashion. + * An extension point is identified by a name, and it may optionally + * require that any implementation must by of a certain type (or derived + * thereof). Use g_io_extension_point_register() to register an + * extension point, and g_io_extension_point_set_required_type() to + * set a required type. + * A module can implement an extension point by specifying the #GType + * that implements the functionality. Additionally, each implementation + * of an extension point has a name, and a priority. Use + * g_io_extension_point_implement() to implement an extension point. + * |[ + * GIOExtensionPoint *ep; + * /* Register an extension point */ + * ep = g_io_extension_point_register ("my-extension-point"); + * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); + * ]| + * |[ + * /* Implement an extension point */ + * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE); + * g_io_extension_point_implement ("my-extension-point", + * my_example_impl_get_type (), + * "my-example", + * 10); + * ]| + * It is up to the code that registered the extension point how + * it uses the implementations that have been associated with it. + * Depending on the use case, it may use all implementations, or + * only the one with the highest priority, or pick a specific + * one by name. + * To avoid opening all modules just to find out what extension + * points they implement, GIO makes use of a caching mechanism, + * see <link linkend="gio-querymodules">gio-querymodules</link>. + * You are expected to run this command after installing a + * GIO module. */ /** - * SECTION:gtl: - * @title: TLS Overview - * @short_description: TLS (aka SSL) support for GSocketConnection - * @include: gio/gio.h + * SECTION:gactio: + * @title: GAction + * @short_description: An action * - * #GTlsConnection and related classes provide TLS (Transport Layer - * Security, previously known as SSL, Secure Sockets Layer) support for - * gio-based network streams. - * In the simplest case, for a client connection, you can just set the - * #GSocketClient:tls flag on a #GSocketClient, and then any - * connections created by that client will have TLS negotiated - * automatically, using appropriate default settings, and rejecting - * any invalid or self-signed certificates (unless you change that - * default by setting the #GSocketClient:tls-validation-flags - * property). The returned object will be a #GTcpWrapperConnection, - * which wraps the underlying #GTlsClientConnection. - * For greater control, you can create your own #GTlsClientConnection, - * wrapping a #GSocketConnection (or an arbitrary #GIOStream with - * pollable input and output streams) and then connect to its signals, - * such as #GTlsConnection::accept-certificate, before starting the - * handshake. - * Server-side TLS is similar, using #GTlsServerConnection. At the - * moment, there is no support for automatically wrapping server-side - * connections in the way #GSocketClient does for client-side - * connections. + * #GAction represents a single named action. + * The main interface to an action is that it can be activated with + * g_action_activate(). This results in the 'activate' signal being + * emitted. An activation has a #GVariant parameter (which may be + * %NULL). The correct type for the parameter is determined by a static + * parameter type (which is given at construction time). + * An action may optionally have a state, in which case the state may be + * set with g_action_set_state(). This call takes a #GVariant. The + * correct type for the state is determined by a static state type + * (which is given at construction time). + * The state may have a hint associated with it, specifying its valid + * range. + * #GAction is merely the interface to the concept of an action, as + * described above. Various implementations of actions exist, including + * #GSimpleAction and #GtkAction. + * In all cases, the implementing class is responsible for storing the + * name of the action, the parameter type, the enabled state, the + * optional state type and the state and emitting the appropriate + * signals when these change. The implementor responsible for filtering + * calls to g_action_activate() and g_action_set_state() for type safety + * and for the state being enabled. + * Probably the only useful thing to do with a #GAction is to put it + * inside of a #GSimpleActionGroup. */ /** - * GDBusSubtreeEnumerateFunc: - * @connection: A #GDBusConnection. - * @sender: The unique bus name of the remote caller. - * @object_path: The object path that was registered with g_dbus_connection_register_subtree(). - * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree(). + * SECTION:gactiongrou: + * @title: GActionGroup + * @short_description: A group of actions * - * The type of the @enumerate function in #GDBusSubtreeVTable. - * This function is called when generating introspection data and also - * when preparing to dispatch incoming messages in the event that the - * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not - * Hierarchies are not supported; the items that you return should not - * contain the '/' character. - * The return value will be freed with g_strfreev(). + * #GActionGroup represents a group of actions. + * Each action in the group has a unique name (which is a string). All + * method calls, except g_action_group_list_actions() take the name of + * an action as an argument. + * The #GActionGroup API is meant to be the 'public' API to the action + * group. The calls here are exactly the interaction that 'external + * the action group implementation) are found on subclasses. This is + * why you will find -- for example -- g_action_group_get_enabled() but + * not an equivalent <function>set()</function> call. + * Signals are emitted on the action group in response to state changes + * on individual actions. * - * Specified (ie: to verify that the object path is valid). - * Returns: A newly allocated array of strings for node names that are children of @object_path. - * Since: 2.26 + * Forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have + * With actions. 'internal' apis (ie: ones meant only to be accessed by */ /** - * g_srv_target_new: - * @hostname: the host that the service is running on - * @port: the port that the service is running on - * @priority: the target's priority - * @weight: the target's weight - * - * Creates a new #GSrvTarget with the given parameters. - * You should not need to use this; normally #GSrvTarget<!-- -->s are - * created by #GResolver. + * SECTION:gappinf: + * @short_description: Application information and launch contexts + * @include: gio/gio.h * - * Returns: a new #GSrvTarget. - * Since: 2.22 + * #GAppInfo and #GAppLaunchContext are used for describing and launching + * applications installed on the system. + * As of GLib 2.20, URIs will always be converted to POSIX paths + * (using g_file_get_path()) when using g_app_info_launch() even if + * the application requested an URI and not a POSIX path. For example + * for an desktop-file based application with Exec key <literal>totem + * %%U</literal> and a single URI, + * <literal>sftp://foo/file.avi</literal>, then + * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> 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 is not the case, the URI will be passed + * unmodified to the application. Some URIs, such as + * <literal>mailto:</literal>, of course cannot be mapped to a POSIX + * path (in gvfs there's no FUSE mount for it); such URIs will be + * passed unmodified to the application. + * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped + * back to the GIO URI in the #GFile constructors (since gvfs + * implements the #GVfs extension point). As such, if the application + * needs to examine the URI, it needs to use g_file_get_uri() or + * similar on #GFile. In other words, an application cannot assume + * that the URI passed to e.g. g_file_new_for_commandline_arg() is + * equal to the result of g_file_get_uri(). The following snippet + * illustrates this: + * <programlisting> + * GFile *f; + * char *uri; + * file = g_file_new_for_commandline_arg (uri_from_commandline); + * uri = g_file_get_uri (file); + * strcmp (uri, uri_from_commandline) == 0; // FALSE + * g_free (uri); + * if (g_file_has_uri_scheme (file, "cdda")) + * { + * // do something special with uri + * } + * g_object_unref (file); + * </programlisting> + * This code will work when both <literal>cdda://sr0/Track + * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track + * 1.wav</literal> is passed to the application. It should be noted + * that it's generally not safe for applications to rely on the format + * of a particular URIs. Different launcher applications (e.g. file + * managers) may have different ideas of what a given URI means. */ /** - * g_simple_async_report_error_in_idle: (skip) - * @object: (allow-none): a #GObject, or %NULL. - * @callback: a #GAsyncReadyCallback. - * @user_data: user data passed to @callback. - * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR). - * @code: a specific error code. - * @format: a formatted error reporting string. - * @...: a list of variables to fill in @format. + * SECTION:gapplicationcommandlin: + * @title: GApplicationCommandLine + * @short_description: A command-line invocation of an application + * @see_also: #GApplication * - * Reports an error in an asynchronous function in an idle function by - * directly setting the contents of the #GAsyncResult with the given error - * information. + * #GApplicationCommandLine represents a command-line invocation of + * an application. It is created by #GApplication and emitted + * in the #GApplication::command-line signal and virtual function. + * The class contains the list of arguments that the program was invoked + * with. It is also possible to query if the commandline invocation was + * commandline to this process). + * The exit status of the originally-invoked process may be set and + * messages can be printed to stdout or stderr of that process. The + * lifecycle of the originally-invoked process is tied to the lifecycle + * dropped). + * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title> + * <programlisting> + * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c"> + * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> + * </xi:include> + * </programlisting> + * </example> + * <example id="gapplication-example-cmdline2"><title>Complicated commandline handling</title> + * <programlisting> + * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c"> + * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> + * </xi:include> + * </programlisting> + * </example> + * + * Local (ie: the current process is running in direct response to the + * Invocation) or remote (ie: some other process forwarded the + * Of this object (ie: the process exits when the last reference is */ /** - * G_ENUM_CLASS_TYPE: - * @class: a #GEnumClass - * - * Get the type identifier from a given #GEnumClass structure. + * SECTION:gasynchelpe: + * @short_description: Asynchronous Helper Functions + * @include: gio/gio.h + * @see_also: #GAsyncReady * - * Returns: the #GType + * Provides helper functions for asynchronous operations. */ /** - * G_TYPE_FLOAT: + * SECTION:gasyncinitabl: + * @short_description: Asynchronously failable object initialization interface + * @include: gio/gio.h + * @see_also: #GInitable * - * The fundamental type corresponding to #gfloat. + * This is the asynchronous version of #GInitable; it behaves the same + * in all ways except that initialization is asynchronous. For more details + * see the descriptions on #GInitable. + * A class may implement both the #GInitable and #GAsyncInitable interfaces. + * Users of objects implementing this are not intended to use the interface + * method directly; instead it will be used automatically in various ways. + * For C applications you generally just call g_async_initable_new_async() + * directly, or indirectly via a foo_thing_new_async() wrapper. This will call + * g_async_initable_init_async() under the cover, calling back with %NULL and + * a set %GError on failure. + * A typical implementation might look something like this: + * |[ + * enum { + * NOT_INITIALIZED, + * INITIALIZING, + * INITIALIZED + * }; + * static void + * _foo_ready_cb (Foo *self) + * { + * GList *l; + * self->priv->state = INITIALIZED; + * for (l = self->priv->init_results; l != NULL; l = l->next) + * { + * GSimpleAsyncResult *simple = l->data; + * if (!self->priv->success) + * g_simple_async_result_set_error (simple, ...); + * g_simple_async_result_complete (simple); + * g_object_unref (simple); + * } + * g_list_free (self->priv->init_results); + * self->priv->init_results = NULL; + * } + * static void + * foo_init_async (GAsyncInitable *initable, + * int io_priority, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * Foo *self = FOO (initable); + * GSimpleAsyncResult *simple; + * simple = g_simple_async_result_new (G_OBJECT (initable) + * callback, + * user_data, + * foo_init_async); + * switch (self->priv->state) + * { + * case NOT_INITIALIZED: + * _foo_get_ready (self); + * self->priv->init_results = g_list_append (self->priv->init_results, + * simple); + * self->priv->state = INITIALIZING; + * break; + * case INITIALIZING: + * self->priv->init_results = g_list_append (self->priv->init_results, + * simple); + * break; + * case INITIALIZED: + * if (!self->priv->success) + * g_simple_async_result_set_error (simple, ...); + * g_simple_async_result_complete_in_idle (simple); + * g_object_unref (simple); + * break; + * } + * } + * static gboolean + * foo_init_finish (GAsyncInitable *initable, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_simple_async_result_is_valid (result, + * G_OBJECT (initable), foo_init_async), FALSE); + * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result), + * error)) + * return FALSE; + * return TRUE; + * } + * static void + * foo_async_initable_iface_init (gpointer g_iface, + * gpointer data) + * { + * GAsyncInitableIface *iface = g_iface; + * iface->init_async = foo_init_async; + * iface->init_finish = foo_init_finish; + * } + * ]| */ /** - * g_async_initable_newv_async: - * @object_type: a #GType supporting #GAsyncInitable. - * @n_parameters: the number of parameters in @parameters - * @parameters: the parameters to use to construct the object - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished - * @user_data: the data to pass to callback function - * - * Helper function for constructing #GAsyncInitiable object. This is - * similar to g_object_newv() but also initializes the object asynchronously. - * When the initialization is finished, @callback will be called. You can - * then call g_async_initable_new_finish() to get the new object and check - * for any errors. + * SECTION:gasyncresul: + * @short_description: Asynchronous Function Results + * @include: gio/gio.h + * @see_also: #GSimpleAsyncResult * - * Since: 2.22 + * Provides a base class for implementing asynchronous function results. + * Asynchronous operations are broken up into two separate operations + * which are chained together by a #GAsyncReadyCallback. To begin + * an asynchronous operation, provide a #GAsyncReadyCallback to the + * asynchronous function. This callback will be triggered when the + * operation has completed, and will be passed a #GAsyncResult instance + * filled with the details of the operation's success or failure, the + * object the asynchronous function was started for and any error codes + * returned. The asynchronous callback function is then expected to call + * the corresponding "_finish()" function, passing the object the + * function was called for, the #GAsyncResult instance, and (optionally) + * an @error to grab any error conditions that may have occurred. + * The "_finish()" function for an operation takes the generic result + * (of type #GAsyncResult) and returns the specific result that the + * operation in question yields (e.g. a #GFileEnumerator for a + * "enumerate children" operation). If the result or error status of the + * operation is not needed, there is no need to call the "_finish()" + * function; GIO will take care of cleaning up the result and error + * information after the #GAsyncReadyCallback returns. Applications may + * also take a reference to the #GAsyncResult and call "_finish()" + * later; however, the "_finish()" function may be called at most once. + * Example of a typical asynchronous operation flow: + * |[ + * void _theoretical_frobnitz_async (Theoretical *t, + * GCancellable *c, + * GAsyncReadyCallback *cb, + * gpointer u); + * gboolean _theoretical_frobnitz_finish (Theoretical *t, + * GAsyncResult *res, + * GError **e); + * static void + * frobnitz_result_func (GObject *source_object, + * GAsyncResult *res, + * gpointer user_data) + * { + * gboolean success = FALSE; + * success = _theoretical_frobnitz_finish (source_object, res, NULL); + * if (success) + * g_printf ("Hurray!\n"); + * else + * g_printf ("Uh oh!\n"); + * /<!-- -->* ... *<!-- -->/ + * } + * int main (int argc, void *argv[]) + * { + * /<!-- -->* ... *<!-- -->/ + * _theoretical_frobnitz_async (theoretical_data, + * NULL, + * frobnitz_result_func, + * NULL); + * /<!-- -->* ... *<!-- -->/ + * } + * ]| + * The callback for an asynchronous operation is called only once, and is + * always called, even in the case of a cancelled operation. On cancellation + * the result is a %G_IO_ERROR_CANCELLED error. + * Some asynchronous operations are implemented using synchronous calls. + * These are run in a separate thread, if #GThread has been initialized, but + * otherwise they are sent to the Main Event Loop and processed in an idle + * function. So, if you truly need asynchronous operations, make sure to + * initialize #GThread. */ /** - * G_VALUE_HOLDS_UCHAR: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. + * SECTION:gbufferedinputstrea: + * @short_description: Buffered Input Stream + * @include: gio/gio.h + * @see_also: #GFilterInputStream, #GInputStream * - * Returns: %TRUE on success. + * Buffered input stream implements #GFilterInputStream and provides + * for buffered reads. + * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes. + * To create a buffered input stream, use g_buffered_input_stream_new(), + * or g_buffered_input_stream_new_sized() to specify the buffer's size at + * construction. + * To get the size of a buffer within a buffered input stream, use + * g_buffered_input_stream_get_buffer_size(). To change the size of a + * buffered input stream's buffer, use + * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size + * cannot be reduced below the size of the data within the buffer. */ @@ -12128,1325 +10524,2087 @@ /** - * G_SETTINGS_BACKEND_EXTENSION_POINT_NAME: - * - * Extension point for #GSettingsBackend functionality. - */ - - -/** - * g_action_group_change_action_state: - * @action_group: a #GActionGroup - * @action_name: the name of the action to request the change on - * @value: the new state - * - * Request for the state of the named action within @action_group to be - * changed to @value. - * The action must be stateful and @value must be of the correct type. - * See g_action_group_get_state_type(). - * This call merely requests a change. The action may refuse to change - * its state or may change its state to something other than @value. - * See g_action_group_get_state_hint(). - * If the @value GVariant is floating, it is consumed. - * - * Since: 2.28 - */ - - -/** - * GMemoryOutputStream: + * SECTION:gcancellabl: + * @short_description: Thread-safe Operation Cancellation Stack + * @include: gio/gio.h * - * Implements #GOutputStream for arbitrary memory chunks. + * GCancellable is a thread-safe operation cancellation stack used + * throughout GIO to allow for cancellation of synchronous and + * asynchronous operations. */ /** - * g_bus_get_sync: - * @bus_type: A #GBusType. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Synchronously connects to the message bus specified by @bus_type. - * Note that the returned object may shared with other callers, - * e.g. if two separate parts of a process calls this function with - * the same @bus_type, they will share the same object. - * This is a synchronous failable function. See g_bus_get() and - * g_bus_get_finish() for the asynchronous version. - * The returned object is a singleton, that is, shared with other - * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the - * event that you need a private message bus connection, use - * g_dbus_address_get_for_bus_sync() and - * g_dbus_connection_new_for_address(). - * Note that the returned #GDBusConnection object will (usually) have - * the #GDBusConnection:exit-on-close property set to %TRUE. + * SECTION:gcharsetconverte: + * @short_description: Convert between charsets + * @include: gio/gio.h * - * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). - * Since: 2.26 + * #GCharsetConverter is an implementation of #GConverter based on + * GIConv. */ /** - * g_file_unmount_mountable: - * @file: input #GFile. - * @flags: flags affecting the operation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. - * @user_data: (closure): the data to pass to callback function - * - * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * When the operation is finished, @callback will be called. You can then call - * g_file_unmount_mountable_finish() to get the result of the operation. + * SECTION:gcontenttyp: + * @short_description: Platform-specific content typing + * @include: gio/gio.h * - * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead. + * A content type is a platform specific string that defines the type + * of a file. On unix it is a mime type, on win32 it is an extension string + * like ".doc", ".txt" or a percieved string like "audio". Such strings + * can be looked up in the registry at HKEY_CLASSES_ROOT. */ /** - * g_network_address_get_port: - * @addr: a #GNetworkAddress + * SECTION:gconverte: + * @short_description: Data conversion interface + * @include: gio/gio.h + * @see_also: #GInputStream, #GOutputStream * - * Gets @addr's port number + * #GConverter is implemented by objects that convert + * binary data in various ways. The conversion can be + * stateful and may fail at any place. + * compression, decompression and regular expression + * replace. * - * Returns: @addr's port (which may be 0) - * Since: 2.22 + * Some example conversions are: character set conversion, + * Since: 2.24 */ /** - * g_dbus_proxy_call: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. - * @cancellable: A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. - * @user_data: The data to pass to @callback. - * - * Asynchronously invokes the @method_name method on @proxy. - * If @method_name contains any dots, then @name is split into interface and - * method name parts. This allows using @proxy for invoking methods on - * other interfaces. - * If the #GDBusConnection associated with @proxy is closed then - * the operation will fail with %G_IO_ERROR_CLOSED. If - * %G_IO_ERROR_CANCELLED. If @parameters contains a value not - * compatible with the D-Bus protocol, the operation fails with - * %G_IO_ERROR_INVALID_ARGUMENT. - * If the @parameters #GVariant is floating, it is consumed. This allows - * convenient 'inline' use of g_variant_new(), e.g.: - * |[ - * g_dbus_proxy_call (proxy, - * "TwoStrings", - * g_variant_new ("(ss)", - * "Thing One", - * "Thing Two"), - * G_DBUS_CALL_FLAGS_NONE, - * -1, - * NULL, - * (GAsyncReadyCallback) two_strings_done, - * &data); - * ]| - * This is an asynchronous method. When the operation is finished, - * <link linkend="g-main-context-push-thread-default">thread-default - * main loop</link> of the thread you are calling this method from. - * You can then call g_dbus_proxy_call_finish() to get the result of - * the operation. See g_dbus_proxy_call_sync() for the synchronous - * version of this method. + * SECTION:gconverterinputstrea: + * @short_description: Converter Input Stream + * @include: gio/gio.h + * @see_also: #GInputStream, #GConverter * - * Since: 2.26 + * Converter input stream implements #GInputStream and allows + * conversion of data of various types during reading. */ /** - * G_TYPE_OBJECT: + * SECTION:gconverteroutputstrea: + * @short_description: Converter Output Stream + * @include: gio/gio.h + * @see_also: #GOutputStream, #GConverter * - * The fundamental type for #GObject. + * Converter output stream implements #GOutputStream and allows + * conversion of data of various types during reading. */ /** - * GApplication::open: - * @application: the application - * @files: (array length=n_files) (element-type GFile): an array of #GFiles - * @n_files: the length of @files - * @hint: a hint provided by the calling instance + * SECTION:gcredential: + * @short_description: An object containing credentials + * @include: gio/gio.h * - * The ::open signal is emitted on the primary instance when there are - * files to open. See g_application_open() for more information. + * The #GCredentials type is a reference-counted wrapper for native + * credentials. This information is typically used for identifying, + * authenticating and authorizing other processes. + * Some operating systems supports looking up the credentials of the + * remote peer of a communication endpoint - see e.g. + * g_socket_get_credentials(). + * Some operating systems supports securely sending and receiving + * credentials over a Unix Domain Socket, see + * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and + * g_unix_connection_receive_credentials() for details. + * On Linux, the native credential type is a <type>struct ucred</type> + * - see the + * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry> + * man page for details. This corresponds to + * %G_CREDENTIALS_TYPE_LINUX_UCRED. + * On FreeBSD, the native credential type is a <type>struct cmsgcred</type>. + * This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. */ /** - * g_tcp_wrapper_connection_new: - * @base_io_stream: the #GIOStream to wrap - * @socket: the #GSocket associated with @base_io_stream - * - * Wraps @base_io_stream and @socket together as a #GSocketConnection. + * SECTION:gdatainputstrea: + * @short_description: Data Input Stream + * @include: gio/gio.h + * @see_also: #GInputStream * - * Returns: the new #GSocketConnection. - * Since: 2.28 + * Data input stream implements #GInputStream and includes functions for + * reading structured data directly from a binary input stream. */ /** - * g_dbus_proxy_new_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new(). - * @error: Return location for error or %NULL. - * - * Finishes creating a #GDBusProxy. + * SECTION:gdataoutputstrea: + * @short_description: Data Output Stream + * @include: gio/gio.h + * @see_also: #GOutputStream * - * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). - * Since: 2.26 + * Data output stream implements #GOutputStream and includes functions for + * writing data directly to an output stream. */ /** - * g_socket_client_set_local_address: - * @client: a #GSocketClient. - * @address: a #GSocketAddress, or %NULL - * - * Sets the local address of the socket client. - * The sockets created by this object will bound to the - * specified address (if not %NULL) before connecting. - * This is useful if you want to ensure the the local - * side of the connection is on a specific port, or on - * a specific interface. + * SECTION:gdbusaddres: + * @title: D-Bus Addresses + * @short_description: D-Bus connection endpoints + * @include: gio/gio.h * - * Since: 2.22 + * Routines for working with D-Bus addresses. A D-Bus address is a string + * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses + * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">D-Bus specification</link>. */ /** - * g_input_stream_has_pending: - * @stream: input stream. - * - * Checks if an input stream has pending actions. + * SECTION:gdbusauthobserve: + * @short_description: Object used for authenticating connections + * @include: gio/gio.h * - * Returns: %TRUE if @stream has pending actions. + * The #GDBusAuthObserver type provides a mechanism for participating + * in how a #GDBusServer (or a #GDBusConnection) authenticates remote + * peers. Simply instantiate a #GDBusAuthObserver and connect to the + * signals you are interested in. Note that new signals may be added + * in the future + * For example, if you only want to allow D-Bus connections from + * processes owned by the same uid as the server, you would use a + * signal handler like the following: + * <example id="auth-observer"><title>Controlling Authentication</title><programlisting> + * static gboolean + * on_authorize_authenticated_peer (GDBusAuthObserver *observer, + * GIOStream *stream, + * GCredentials *credentials, + * gpointer user_data) + * { + * gboolean authorized; + * authorized = FALSE; + * if (credentials != NULL) + * { + * GCredentials *own_credentials; + * own_credentials = g_credentials_new (); + * if (g_credentials_is_same_user (credentials, own_credentials, NULL)) + * authorized = TRUE; + * g_object_unref (own_credentials); + * } + * return authorized; + * } + * </programlisting></example> */ /** - * GDBusMessageHeaderField: - * @G_DBUS_MESSAGE_HEADER_FIELD_INVALID: Not a valid header field. - * @G_DBUS_MESSAGE_HEADER_FIELD_PATH: The object path. - * @G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE: The interface name. - * @G_DBUS_MESSAGE_HEADER_FIELD_MEMBER: The method or signal name. - * @G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME: The name of the error that occurred. - * @G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL: The serial number the message is a reply to. - * @G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION: The name the message is intended for. - * @G_DBUS_MESSAGE_HEADER_FIELD_SENDER: Unique name of the sender of the message (filled in by the bus). - * @G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE: The signature of the message body. - * @G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS: The number of UNIX file descriptors that accompany the message. - * - * Header fields used in #GDBusMessage. + * SECTION:gdbusconnectio: + * @short_description: D-Bus Connections + * @include: gio/gio.h * - * Since: 2.26 + * The #GDBusConnection type is used for D-Bus connections to remote + * peers such as a message buses. It is a low-level API that offers a + * lot of flexibility. For instance, it lets you establish a connection + * over any transport that can by represented as an #GIOStream. + * This class is rarely used directly in D-Bus clients. If you are writing + * an D-Bus client, it is often easier to use the g_bus_own_name(), + * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. + * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> */ /** - * G_PARAM_SPEC_TYPE: - * @pspec: a valid #GParamSpec + * SECTION:gdbuserro: + * @title: GDBusError + * @short_description: Mapping D-Bus errors to and from GError + * @include: gio/gio.h * - * Retrieves the #GType of this @pspec. + * All facilities that return errors from remote methods (such as + * g_dbus_connection_call_sync()) use #GError to represent both D-Bus + * errors (e.g. errors returned from the other peer) and locally + * in-process generated errors. + * To check if a returned #GError is an error from a remote peer, use + * g_dbus_error_is_remote_error(). To get the actual D-Bus error name, + * use g_dbus_error_get_remote_error(). Before presenting an error, + * always use g_dbus_error_strip_remote_error(). + * In addition, facilities used to return errors to a remote peer also + * use #GError. See g_dbus_method_invocation_return_error() for + * discussion about how the D-Bus error name is set. + * Applications can associate a #GError error domain with a set of D-Bus errors in order to + * automatically map from D-Bus errors to #GError and back. This + * is typically done in the function returning the #GQuark for the + * error domain: + * <example id="error-registration"><title>Error Registration</title><programlisting> + * /<!-- -->* foo-bar-error.h: *<!-- -->/ + * #define FOO_BAR_ERROR (foo_bar_error_quark ()) + * GQuark foo_bar_error_quark (void); + * typedef enum + * { + * FOO_BAR_ERROR_FAILED, + * FOO_BAR_ERROR_ANOTHER_ERROR, + * FOO_BAR_ERROR_SOME_THIRD_ERROR, + * } FooBarError; + * /<!-- -->* foo-bar-error.c: *<!-- -->/ + * static const GDBusErrorEntry foo_bar_error_entries[] = + * { + * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"}, + * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"}, + * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, + * }; + * GQuark + * foo_bar_error_quark (void) + * { + * static volatile gsize quark_volatile = 0; + * g_dbus_error_register_error_domain ("foo-bar-error-quark", + * &quark_volatile, + * foo_bar_error_entries, + * G_N_ELEMENTS (foo_bar_error_entries)); + * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) - 1 == FOO_BAR_ERROR_SOME_THIRD_ERROR); + * return (GQuark) quark_volatile; + * } + * </programlisting></example> + * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and + * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>. + * If the other peer is using GDBus, the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead + * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover + * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error(). + * Note that errors in the %G_DBUS_ERROR error domain is intended only + * for returning errors from a remote message bus process. Errors + * generated locally in-process by e.g. #GDBusConnection is from the + * %G_IO_ERROR domain. */ /** - * g_dbus_connection_send_message_with_reply: - * @connection: A #GDBusConnection. - * @message: A #GDBusMessage. - * @flags: Flags affecting how the message is sent. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @out_serial: Return location for serial number assigned to @message when sending it or %NULL. - * @cancellable: A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. - * @user_data: The data to pass to @callback. - * - * Asynchronously sends @message to the peer represented by @connection. - * Unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number - * will be assigned by @connection and set on @message via - * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the - * serial number used will be written to this location prior to - * submitting the message to the underlying transport. - * If @connection is closed then the operation will fail with - * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will - * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, - * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. - * This is an asynchronous method. When the operation is finished, @callback will be invoked - * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> - * of the thread you are calling this method from. You can then call - * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. - * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. - * Note that @message must be unlocked, unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * SECTION:gdbusintrospectio: + * @title: D-Bus Introspection Data + * @short_description: Node and interface description data structures + * @include: gio/gio.h * - * Since: 2.26 + * Various data structures and convenience routines to parse and + * generate D-Bus introspection XML. Introspection information is + * used when registering objects with g_dbus_connection_register_object(). + * The format of D-Bus introspection XML is specified in the + * <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</link>. */ /** - * g_file_info_get_attribute_byte_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a byte string attribute. If the attribute does - * not contain a byte string, %NULL will be returned. - * %NULL otherwise. + * SECTION:gdbusmessag: + * @short_description: D-Bus Message + * @include: gio/gio.h * - * Returns: the contents of the @attribute value as a byte string, or + * A type for representing D-Bus messages that can be sent or received + * on a #GDBusConnection. */ /** - * g_socket_get_credentials: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Returns the credentials of the foreign process connected to this - * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX - * sockets). - * If this operation isn't supported on the OS, the method fails with - * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented - * by reading the %SO_PEERCRED option on the underlying socket. - * Other ways to obtain credentials from a foreign peer includes the - * #GUnixCredentialsMessage type and - * g_unix_connection_send_credentials() / - * g_unix_connection_receive_credentials() functions. - * that must be freed with g_object_unref(). + * SECTION:gdbusmethodinvocatio: + * @short_description: Object for handling remote calls + * @include: gio/gio.h * - * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object - * Since: 2.26 + * Instances of the #GDBusMethodInvocation class are used when + * handling D-Bus method calls. It provides a way to asynchronously + * return results and errors. + * The normal way to obtain a #GDBusMethodInvocation object is to receive + * it as an argument to the handle_method_call() function in a + * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object(). */ /** - * G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE: - * - * A key in the "standard" namespace for getting the amount of disk space - * that is consumed by the file (in bytes). This will generally be larger - * than the file size (due to block size overhead) but can occasionally be - * smaller (for example, for sparse files). - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + * SECTION:gdbusnameownin: + * @title: Owning Bus Names + * @short_description: Simple API for owning bus names + * @include: gio/gio.h * - * Since: 2.20 + * Convenience API for owning bus names. + * <example id="gdbus-owning-names"><title>Simple application owning a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> */ /** - * g_node_prepend_data: - * @parent: the #GNode to place the new #GNode under - * @data: the data for the new #GNode - * - * Inserts a new #GNode as the first child of the given parent. + * SECTION:gdbusnamewatchin: + * @title: Watching Bus Names + * @short_description: Simple API for watching bus names + * @include: gio/gio.h * - * Returns: the new #GNode + * Convenience API for watching bus names. + * <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> */ /** - * GVolumeMonitor::volume-changed: - * @volume_monitor: The volume monitor emitting the signal. - * @volume: a #GVolume that changed. + * SECTION:gdbusprox: + * @short_description: Client-side proxies + * @include: gio/gio.h * - * Emitted when mountable volume is changed. + * #GDBusProxy is a base class used for proxies to access a D-Bus + * interface on a remote object. A #GDBusProxy can be constructed for + * both well-known and unique names. + * By default, #GDBusProxy will cache all properties (and listen to + * changes) of the remote object, and proxy all signals that gets + * emitted. This behaviour can be changed by passing suitable + * #GDBusProxyFlags when the proxy is created. If the proxy is for a + * well-known name, the property cache is flushed when the name owner + * vanishes and reloaded when a name owner appears. + * If a #GDBusProxy is used for a well-known name, the owner of the + * name is tracked and can be read from + * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to + * get notified of changes. Additionally, only signals and property + * changes emitted from the current name owner are considered and + * calls are always sent to the current name owner. This avoids a + * number of race conditions when the name is lost by one owner and + * claimed by another. However, if no name owner currently exists, + * then calls will be sent to the well-known name which may result in + * the message bus launching an owner (unless + * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). + * The generic #GDBusProxy::g-properties-changed and #GDBusProxy::g-signal + * signals are not very convenient to work with. Therefore, the recommended + * way of working with proxies is to subclass #GDBusProxy, and have + * more natural properties and signals in your derived class. + * See <xref linkend="gdbus-example-proxy-subclass"/> for an example. + * <example id="gdbus-wellknown-proxy"><title>GDBusProxy for a well-known-name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> */ /** - * GSignalQuery: - * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown. - * @signal_name: The signal name. - * @itype: The interface/instance type that this signal can be emitted for. - * @signal_flags: The signal flags as passed in to g_signal_new(). - * @return_type: The return type for user callbacks. - * @n_params: The number of parameters that user callbacks take. - * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting> + * SECTION:gdbusserve: + * @short_description: Helper for accepting connections + * @include: gio/gio.h * - * A structure holding in-depth information for a specific signal. It is - * filled in by the g_signal_query() function. + * #GDBusServer is a helper for listening to and accepting D-Bus + * connections. + * <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> */ /** - * G_DEFINE_ABSTRACT_TYPE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * - * A convenience macro for type implementations. - * Similar to G_DEFINE_TYPE(), but defines an abstract type. - * See G_DEFINE_TYPE_EXTENDED() for an example. + * SECTION:gdbusutil: + * @title: D-Bus Utilities + * @short_description: Various utilities related to D-Bus. + * @include: gio/gio.h * - * Since: 2.4 + * Various utility routines related to D-Bus. */ /** - * g_dbus_proxy_new_for_bus_sync: - * @bus_type: A #GBusType. - * @flags: Flags used when constructing the proxy. - * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - * @name: A bus name (well-known or unique). - * @object_path: An object path. - * @interface_name: A D-Bus interface name. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. - * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. + * SECTION:gdesktopappinf: + * @title: GDesktopAppInfo + * @short_description: Application information from desktop files + * @include: gio/gdesktopappinfo.h * - * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). - * Since: 2.26 + * #GDesktopAppInfo is an implementation of #GAppInfo based on + * desktop files. + * Note that <filename><gio/gdesktopappinfo.h></filename> belongs to + * the UNIX-specific GIO interfaces, thus you have to use the + * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. */ /** - * GVolume::changed: + * SECTION:gdriv: + * @short_description: Drive management + * @include: gio/gio.h * - * Emitted when the volume has been changed. + * #GDrive - this represent a piece of hardware connected to the machine. + * It's generally only created for removable hardware or hardware with + * removable media. + * #GDrive is a container class for #GVolume objects that stem from + * the same piece of media. As such, #GDrive abstracts a drive with + * (or without) removable media and provides operations for querying + * whether media is available, determing whether media change is + * automatically detected and ejecting the media. + * If the #GDrive reports that media isn't automatically detected, one + * can poll for media; typically one should not do this periodically + * as a poll for media operation is potententially expensive and may + * spin up the drive creating noise. + * #GDrive supports starting and stopping drives with authentication + * support for the former. This can be used to support a diverse set + * of use cases including connecting/disconnecting iSCSI devices, + * powering down external disk enclosures and starting/stopping + * multi-disk devices such as RAID devices. Note that the actual + * semantics and side-effects of starting/stopping a #GDrive may vary + * according to implementation. To choose the correct verbs in e.g. a + * file manager, use g_drive_get_start_stop_type(). + * For porting from GnomeVFS note that there is no equivalent of + * #GDrive in that API. */ /** - * G_TYPE_CHAR: + * SECTION:gemble: + * @short_description: An object for emblems + * @include: gio/gio.h + * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon * - * The fundamental type corresponding to #gchar. - * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer. - * This may or may not be the same type a the C type "gchar". + * #GEmblem is an implementation of #GIcon that supports + * having an emblem, which is an icon with additional properties. + * It can than be added to a #GEmblemedIcon. + * Currently, only metainformation about the emblem's origin is + * supported. More may be added in the future. */ /** - * g_buffered_output_stream_set_auto_grow: - * @stream: a #GBufferedOutputStream. - * @auto_grow: a #gboolean. + * SECTION:gemblemedico: + * @short_description: Icon with emblems + * @include: gio/gio.h + * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem * - * Sets whether or not the @stream's buffer should automatically grow. - * If @auto_grow is true, then each write will just make the buffer - * larger, and you must manually flush the buffer to actually write out - * the data to the underlying stream. + * #GEmblemedIcon is an implementation of #GIcon that supports + * adding an emblem to an icon. Adding multiple emblems to an + * icon is ensured via g_emblemed_icon_add_emblem(). + * Note that #GEmblemedIcon allows no control over the position + * of the emblems. See also #GEmblem for more information. */ /** - * g_memory_output_stream_get_size: - * @ostream: a #GMemoryOutputStream - * - * Gets the size of the currently allocated data area (available from - * g_memory_output_stream_get_data()). If the stream isn't - * growable (no realloc was passed to g_memory_output_stream_new()) then - * this is the maximum size of the stream and further writes - * will return %G_IO_ERROR_NO_SPACE. - * Note that for growable streams the returned size may become invalid on - * the next write or truncate operation on the stream. - * If you want the number of bytes currently written to the stream, use - * g_memory_output_stream_get_data_size(). + * SECTION:gfil: + * @short_description: File and Directory Handling + * @include: gio/gio.h + * @see_also: #GFileInfo, #GFileEnumerator * - * Returns: the number of bytes allocated for the data buffer - */ - - -/** - * GMount::unmounted: - * @mount: the object on which the signal is emitted + * #GFile is a high level abstraction for manipulating files on a + * virtual file system. #GFile<!-- -->s are lightweight, immutable + * objects that do no I/O upon creation. It is necessary to understand that + * #GFile objects do not represent files, merely an identifier for a file. All + * file content I/O is implemented as streaming operations (see #GInputStream and + * #GOutputStream). + * g_file_new_for_path() if you have a path. + * g_file_new_for_uri() if you have a URI. + * g_file_new_for_commandline_arg() for a command line argument. + * g_file_parse_name() from a utf8 string gotten from g_file_get_parse_name(). + * One way to think of a #GFile is as an abstraction of a pathname. For normal + * files the system pathname is what is stored internally, but as #GFile<!-- -->s + * are extensible it could also be something else that corresponds to a pathname + * in a userspace implementation of a filesystem. + * #GFile<!-- -->s make up hierarchies of directories and files that correspond to the + * files on a filesystem. You can move through the file system with #GFile using + * g_file_get_parent() to get an identifier for the parent directory, g_file_get_child() + * to get a child within a directory, g_file_resolve_relative_path() to resolve a relative + * path between two #GFile<!-- -->s. There can be multiple hierarchies, so you may not + * end up at the same root if you repeatedly call g_file_get_parent() on two different + * files. + * All #GFile<!-- -->s have a basename (get with g_file_get_basename()). These names + * are byte strings that are used to identify the file on the filesystem (relative to + * its parent directory) and there is no guarantees that they have any particular charset + * encoding or even make any sense at all. If you want to use filenames in a user + * interface you should use the display name that you can get by requesting the + * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). + * This is guaranteed to be in utf8 and can be used in a user interface. But always + * store the real basename or the #GFile to use to actually access the file, because + * there is no way to go from a display name to the actual name. + * Using #GFile as an identifier has the same weaknesses as using a path in that + * there may be multiple aliases for the same file. For instance, hard or + * soft links may cause two different #GFile<!-- -->s to refer to the same file. + * and long names on Fat/NTFS, or bind mounts in Linux. If you want to check if + * two #GFile<!-- -->s point to the same file you can query for the + * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial + * canonicalization of pathnames passed in, so that trivial differences in the + * path string used at creation (duplicated slashes, slash at end of path, "." + * or ".." path segments, etc) does not create different #GFile<!-- -->s. + * Many #GFile operations have both synchronous and asynchronous versions + * to suit your application. Asynchronous versions of synchronous functions + * simply have _async() appended to their function names. The asynchronous + * I/O functions call a #GAsyncReadyCallback which is then used to finalize + * the operation, producing a GAsyncResult which is then passed to the + * function's matching _finish() operation. + * Some #GFile operations do not have synchronous analogs, as they may + * take a very long time to finish, and blocking may leave an application + * unusable. Notable cases include: + * g_file_mount_mountable() to mount a mountable file. + * g_file_unmount_mountable_with_operation() to unmount a mountable file. + * g_file_eject_mountable_with_operation() to eject a mountable file. + * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm> + * One notable feature of #GFile<!-- -->s are entity tags, or "etags" for + * short. Entity tags are somewhat like a more abstract version of the + * traditional mtime, and can be used to quickly determine if the file has + * been modified from the version on the file system. See the HTTP 1.1 + * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink> + * for HTTP Etag headers, which are a very similar concept. + * </para> * - * This signal is emitted when the #GMount have been - * unmounted. If the recipient is holding references to the - * object they should release them so the object can be - * finalized. + * To construct a #gfile, you can use: + * Other possible causes for aliases are: case insensitive filesystems, short */ /** - * GBusType: - * @G_BUS_TYPE_STARTER: An alias for the message bus that activated the process, if any. - * @G_BUS_TYPE_NONE: Not a message bus. - * @G_BUS_TYPE_SYSTEM: The system-wide message bus. - * @G_BUS_TYPE_SESSION: The login session message bus. - * - * An enumeration for well-known message buses. + * SECTION:gfileattribut: + * @short_description: Key-Value Paired File Attributes + * @include: gio/gio.h + * @see_also: #GFile, #GFileInfo * - * Since: 2.26 + * File attributes in GIO consist of a list of key-value pairs. + * Keys are strings that contain a key namespace and a key name, separated + * by a colon, e.g. "namespace:keyname". Namespaces are included to sort + * key-value pairs by namespaces for relevance. Keys can be retrived + * using wildcards, e.g. "standard::*" will return all of the keys in the + * "standard" namespace. + * Values are stored within the list in #GFileAttributeValue structures. + * Values can store different types, listed in the enum #GFileAttributeType. + * Upon creation of a #GFileAttributeValue, the type will be set to + * %G_FILE_ATTRIBUTE_TYPE_INVALID. + * The list of possible attributes for a filesystem (pointed to by a #GFile) is + * availible as a #GFileAttributeInfoList. This list is queryable by key names + * as indicated earlier. + * Classes that implement #GFileIface will create a #GFileAttributeInfoList and + * install default keys and values for their given file system, architecture, + * and other possible implementation details (e.g., on a UNIX system, a file + * attribute key will be registered for the user id for a given file). + * <para> + * <table> + * <title>GFileAttributes Default Namespaces</title> + * <tgroup cols='2' align='left'><thead> + * <row><entry>Namspace</entry><entry>Description</entry></row> + * </thead> + * <tbody> + * <row><entry>"standard"</entry><entry>The "Standard" namespace. General file + * information that any application may need should be put in this namespace. + * Examples include the file's name, type, and size.</entry></row> + * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link> + * namespace. Currently, the only key in this namespace is "value", which contains + * the value of the current entity tag.</entry></row> + * <row><entry>"id"</entry><entry>The "Identification" namespace. This + * namespace is used by file managers and applications that list directories + * to check for loops and to uniquely identify files.</entry></row> + * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check + * if a user has the proper privilidges to access files and perform + * file operations. Keys in this namespace are made to be generic + * and easily understood, e.g. the "can_read" key is %TRUE if + * the current user has permission to read the file. UNIX permissions and + * NTFS ACLs in Windows should be mapped to these values.</entry></row> + * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes + * simple boolean keys for checking if a file or path supports mount operations, e.g. + * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row> + * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file + * access, changed, created times. </entry></row> + * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific + * information and may not be available for all files. Examples include + * the UNIX "UID", "GID", etc.</entry></row> + * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific + * information and may not be available for all files. Examples include + * "is_system" for checking if a file is marked as a system file, and "is_archive" + * for checking if a file is marked as an archive file.</entry></row> + * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information + * about who owns a file. May not be available for all file systems. Examples include + * "user" for getting the user name of the file owner. This information is often mapped from + * some backend specific data such as a unix UID.</entry></row> + * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes + * information about file thumbnails and their location within the file system. Exaples of + * keys in this namespace include "path" to get the location of a thumbnail, and "failed" + * to check if thumbnailing of the file failed.</entry></row> + * <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information + * about the file system where a file is located, such as its type, how much + * space is left available, and the overall size of the file system.</entry></row> + * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace + * contain information about the current GVFS backend in use. </entry></row> + * <row><entry>"xattr"</entry><entry>The "xattr" namespace. Gets information + * about extended user attributes. See attr(5). The "user." prefix of the + * extended user attribute name is stripped away when constructing keys in + * this namespace, e.g. "xattr::mime_type" for the extended attribute with + * the name "user.mime_type". Note that this information is only available + * if GLib has been built with extended attribute support.</entry></row> + * <row><entry>"xattr-sys"</entry><entry>The "xattr-sys" namespace. + * Gets information about extended attributes which are not user-specific. + * See attr(5). Note that this information is only available if GLib + * has been built with extended attribute support.</entry></row> + * <row><entry>"selinux"</entry><entry>The "SELinux" namespace. Includes + * information about the SELinux context of files. Note that this information + * is only available if GLib has been built with SELinux support.</entry></row> + * </tbody> + * </tgroup> + * </table> + * </para> + * Please note that these are not all of the possible namespaces. + * More namespaces can be added from GIO modules or by individual applications. + * For more information about writing GIO modules, see #GIOModule. + * <!-- TODO: Implementation note about using extended attributes on supported + * file systems --> + * <para><table> + * <title>GFileAttributes Built-in Keys and Value Types</title> + * <tgroup cols='3' align='left'><thead> + * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row> + * </thead><tbody> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object (#GIcon)</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object (#GIcon)</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row> + * <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row> + * </tbody></tgroup></table></para> + * Note that there are no predefined keys in the "xattr" and "xattr-sys" + * namespaces. Keys for the "xattr" namespace are constructed by stripping + * away the "user." prefix from the extended user attribute, and prepending + * "xattr::". Keys for the "xattr-sys" namespace are constructed by + * concatenating "xattr-sys::" with the extended attribute name. All extended + * attribute values are returned as hex-encoded strings in which bytes outside + * the ASCII range are encoded as hexadecimal escape sequences of the form + * \x<replaceable>nn</replaceable>. */ /** - * GMount::pre-unmount: - * @mount: the object on which the signal is emitted + * SECTION:gfiledescriptorbase: + * @short_description: Interface for file descriptor based IO + * @include: gio/gfiledescriptorbased.h + * @see_also: #GInputStream, #GOutputStream * - * This signal is emitted when the #GMount is about to be - * unmounted. + * #GFileDescriptorBased is implemented by streams (implementations of + * #GInputStream or #GOutputStream) that are based on file descriptors. + * Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to + * the UNIX-specific GIO interfaces, thus you have to use the + * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. * - * Since: 2.22 + * Since: 2.24 */ /** - * g_dbus_connection_get_guid: - * @connection: A #GDBusConnection. - * - * The GUID of the peer performing the role of server when - * authenticating. See #GDBusConnection:guid for more details. + * SECTION:gfileenumerato: + * @short_description: Enumerated Files Routines + * @include: gio/gio.h * - * Returns: The GUID. Do not free this string, it is owned by - * Since: 2.26 + * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s, + * returning a #GFileInfo structure for each file enumerated (e.g. + * g_file_enumerate_children() will return a #GFileEnumerator for each + * of the children within a directory). + * To get the next file's information from a #GFileEnumerator, use + * g_file_enumerator_next_file() or its asynchronous version, + * g_file_enumerator_next_files_async(). Note that the asynchronous + * version will return a list of #GFileInfo<!---->s, whereas the + * synchronous will only return the next file in the enumerator. + * To close a #GFileEnumerator, use g_file_enumerator_close(), or + * its asynchronous version, g_file_enumerator_close_async(). Once + * a #GFileEnumerator is closed, no further actions may be performed + * on it, and it should be freed with g_object_unref(). */ /** - * g_socket_connection_factory_register_type: - * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION - * @family: a #GSocketFamily - * @type: a #GSocketType - * @protocol: a protocol id - * - * Looks up the #GType to be used when creating socket connections on - * sockets with the specified @family,@type and @protocol. - * If no type is registered, the #GSocketConnection base type is returned. + * SECTION:gfileico: + * @short_description: Icons pointing to an image file + * @include: gio/gio.h + * @see_also: #GIcon, #GLoadableIcon * - * Since: 2.22 + * #GFileIcon specifies an icon by pointing to an image file + * to be used as icon. */ /** - * g_volume_mount: - * @volume: a #GVolume. - * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data that gets passed to @callback - * - * Mounts a volume. This is an asynchronous operation, and is - * finished by calling g_volume_mount_finish() with the @volume - * and #GAsyncResult returned in the @callback. + * SECTION:gfileinf: + * @short_description: File Information and Attributes + * @include: gio/gio.h + * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link> * - * Virtual: mount_fn + * Functionality for manipulating basic metadata for files. #GFileInfo + * implements methods for getting information that all files should + * contain, and allows for manipulation of extended attributes. + * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more + * information on how GIO handles file attributes. + * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its + * async variant). To obtain a #GFileInfo for a file input or output + * stream, use g_file_input_stream_query_info() or + * g_file_output_stream_query_info() (or their async variants). + * To change the actual attributes of a file, you should then set the + * attribute in the #GFileInfo and call g_file_set_attributes_from_info() + * or g_file_set_attributes_async() on a GFile. + * However, not all attributes can be changed in the file. For instance, + * the actual size of a file cannot be changed via g_file_info_set_size(). + * You may call g_file_query_settable_attributes() and + * g_file_query_writable_namespaces() to discover the settable attributes + * of a particular file at runtime. + * #GFileAttributeMatcher allows for searching through a #GFileInfo for + * attributes. */ /** - * g_unix_mount_point_get_device_path: - * @mount_point: a #GUnixMountPoint. - * - * Gets the device path for a unix mount point. + * SECTION:gfileinputstrea: + * @short_description: File input streaming operations + * @include: gio/gio.h + * @see_also: #GInputStream, #GDataInputStream, #GSeekable * - * Returns: a string containing the device path. + * GFileInputStream provides input streams that take their + * content from a file. + * GFileInputStream implements #GSeekable, which allows the input + * stream to jump to arbitrary positions in the file, provided the + * filesystem of the file allows it. To find the position of a file + * input stream, use g_seekable_tell(). To find out if a file input + * stream supports seeking, use g_seekable_stream_can_seek(). + * To position a file input stream, use g_seekable_seek(). */ /** - * g_socket_get_family: - * @socket: a #GSocket. + * SECTION:gfileiostrea: + * @short_description: File read and write streaming operations + * @include: gio/gio.h + * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable * - * Gets the socket family of the socket. + * GFileIOStream provides io streams that both read and write to the same + * file handle. + * GFileIOStream implements #GSeekable, which allows the io + * stream to jump to arbitrary positions in the file and to truncate + * the file, provided the filesystem of the file supports these + * operations. + * To find the position of a file io stream, use + * g_seekable_tell(). + * To find out if a file io stream supports seeking, use g_seekable_can_seek(). + * To position a file io stream, use g_seekable_seek(). + * To find out if a file io stream supports truncating, use + * g_seekable_can_truncate(). To truncate a file io + * stream, use g_seekable_truncate(). + * The default implementation of all the #GFileIOStream operations + * and the implementation of #GSeekable just call into the same operations + * on the output stream. * - * Returns: a #GSocketFamily * Since: 2.22 */ /** - * GConverterIface: - * @g_iface: The parent interface. - * @convert: Converts data. - * @reset: Reverts the internal state of the converter to its initial state. - * - * Provides an interface for converting data from one type - * to another type. The conversion can be stateful - * and may fail at any place. - * - * Since: 2.24 - */ - - -/** - * G_FILE_ATTRIBUTE_STANDARD_SIZE: + * SECTION:gfilemonito: + * @short_description: File Monitor + * @include: gio/gio.h * - * A key in the "standard" namespace for getting the file's size (in bytes). - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + * Monitors a file or directory for changes. + * To obtain a #GFileMonitor for a file or directory, use + * g_file_monitor(), g_file_monitor_file(), or + * g_file_monitor_directory(). + * To get informed about changes to the file or directory you are + * monitoring, connect to the #GFileMonitor::changed signal. The + * signal will be emitted in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * context</link> of the thread that the monitor was created in + * (though if the global default main context is blocked, this may + * cause notifications to be blocked even if the thread-default + * context is still running). */ /** - * g_app_info_get_executable: - * @appinfo: a #GAppInfo - * - * Gets the executable's name for the installed application. - * binaries name + * SECTION:gfilenamecomplete: + * @short_description: Filename Completer + * @include: gio/gio.h * - * Returns: a string containing the @appinfo's application + * Completes partial file and directory names given a partial string by + * looking in the file system for clues. Can return a list of possible + * completion strings for widget implementations. */ /** - * GDBusAuthObserver: - * - * The #GDBusAuthObserver structure contains only private data and - * should only be accessed using the provided API. + * SECTION:gfileoutputstrea: + * @short_description: File output streaming operations + * @include: gio/gio.h + * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable * - * Since: 2.26 + * GFileOutputStream provides output streams that write their + * content to a file. + * GFileOutputStream implements #GSeekable, which allows the output + * stream to jump to arbitrary positions in the file and to truncate + * the file, provided the filesystem of the file supports these + * operations. + * To find the position of a file output stream, use g_seekable_tell(). + * To find out if a file output stream supports seeking, use + * g_seekable_can_seek().To position a file output stream, use + * g_seekable_seek(). To find out if a file output stream supports + * truncating, use g_seekable_can_truncate(). To truncate a file output + * stream, use g_seekable_truncate(). */ /** - * g_settings_get_value: - * @settings: a #GSettings object - * @key: the key to get the value for - * @returns: a new #GVariant - * - * Gets the value that is stored in @settings for @key. - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. + * SECTION:gfilterinputstrea: + * @short_description: Filter Input Stream + * @include: gio/gio.h * - * Since: 2.26 + * Base class for input stream implementations that perform some + * kind of filtering operation on a base stream. Typical examples + * of filtering operations are character set conversion, compression + * and byte order flipping. */ /** - * GParamSpecFlags: - * @parent_instance: private #GParamSpec portion - * @flags_class: the #GFlagsClass for the flags - * @default_value: default value for the property specified + * SECTION:gfilteroutputstrea: + * @short_description: Filter Output Stream + * @include: gio/gio.h * - * A #GParamSpec derived structure that contains the meta data for flags - * properties. + * Base class for output stream implementations that perform some + * kind of filtering operation on a base stream. Typical examples + * of filtering operations are character set conversion, compression + * and byte order flipping. */ /** - * GTlsAuthenticationMode: - * @G_TLS_AUTHENTICATION_NONE: client authentication not required - * @G_TLS_AUTHENTICATION_REQUESTED: client authentication is requested - * @G_TLS_AUTHENTICATION_REQUIRED: client authentication is required - * - * The client authentication mode for a #GTlsServerConnection. + * SECTION:gico: + * @short_description: Interface for icons + * @include: gio/gio.h * - * Since: 2.28 + * #GIcon is a very minimal interface for icons. It provides functions + * for checking the equality of two icons, hashing of icons and + * serializing an icon to and from strings. + * #GIcon does not provide the actual pixmap for the icon as this is out + * of GIO's scope, however implementations of #GIcon may contain the name + * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon). + * To obtain a hash of a #GIcon, see g_icon_hash(). + * To check if two #GIcons are equal, see g_icon_equal(). + * For serializing a #GIcon, use g_icon_to_string() and + * g_icon_new_for_string(). + * If your application or library provides one or more #GIcon + * implementations you need to ensure that each #GType is registered + * with the type system prior to calling g_icon_new_for_string(). */ /** - * g_dbus_connection_close_finish: - * @connection: A #GDBusConnection. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close(). - * @error: Return location for error or %NULL. - * - * Finishes an operation started with g_dbus_connection_close(). + * SECTION:ginetaddres: + * @short_description: An IPv4/IPv6 address * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. - * Since: 2.26 + * #GInetAddress represents an IPv4 or IPv6 internet address. Use + * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to + * look up the #GInetAddress for a hostname. Use + * g_resolver_lookup_by_address() or + * g_resolver_lookup_by_address_async() to look up the hostname for a + * #GInetAddress. + * To actually connect to a remote host, you will need a + * #GInetSocketAddress (which includes a #GInetAddress as well as a + * port number). */ /** - * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS: + * SECTION:ginetsocketaddres: + * @short_description: Internet GSocketAddress * - * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". + * An IPv4 or IPv6 socket address; that is, the combination of a + * #GInetAddress and a port number. */ /** - * g_settings_set_value: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: a #GVariant of the correct type - * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable - * - * Sets @key in @settings to @value. - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or for @value to have the incorrect type, per - * the schema. - * If @value is floating then this function consumes the reference. + * SECTION:ginitabl: + * @short_description: Failable object initialization interface + * @include: gio/gio.h + * @see_also: #GAsyncInitable * - * Since: 2.26 + * #GInitable is implemented by objects that can fail during + * initialization. If an object implements this interface the + * g_initable_init() function must be called as the first thing + * after construction. If g_initable_init() is not called, or if + * it returns an error, all further operations on the object + * should fail, generally with a %G_IO_ERROR_NOT_INITIALIZED error. + * Users of objects implementing this are not intended to use + * the interface method directly, instead it will be used automatically + * in various ways. For C applications you generally just call + * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper. + * This will call g_initable_init() under the cover, returning %NULL and + * setting a %GError on failure. + * For bindings in languages where the native constructor supports + * exceptions the binding could check for objects implemention %GInitable + * during normal construction and automatically initialize them, throwing + * an exception on failure. */ /** - * GRegexMatchFlags: - * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. - * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A". - * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z". - * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b". - * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match(). - * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator. - * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator. - * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator. - * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized. - * - * Flags specifying match-time options. + * SECTION:ginputstrea: + * @short_description: Base class for implementing streaming input + * @include: gio/gio.h * - * Since: 2.14 + * GInputStream has functions to read from a stream (g_input_stream_read()), + * to close a stream (g_input_stream_close()) and to skip some content + * (g_input_stream_skip()). + * To copy the content of an input stream to an output stream without + * manually handling the reads and writes, use g_output_stream_splice(). + * All of these functions have async variants too. */ /** - * GSocketFamily: - * @G_SOCKET_FAMILY_INVALID: no address family - * @G_SOCKET_FAMILY_IPV4: the IPv4 family - * @G_SOCKET_FAMILY_IPV6: the IPv6 family - * @G_SOCKET_FAMILY_UNIX: the UNIX domain family - * - * The protocol family of a #GSocketAddress. (These values are - * identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX, - * if available.) + * SECTION:gioerro: + * @short_description: Error helper functions + * @include: gio/gio.h * - * Since: 2.22 + * Contains helper functions for reporting errors to the user. */ /** - * g_input_stream_close_finish: - * @stream: a #GInputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. - * - * Finishes closing a stream asynchronously, started from g_input_stream_close_async(). + * SECTION:giomodul: + * @short_description: Loadable GIO Modules + * @include: gio/gio.h * - * Returns: %TRUE if the stream was closed successfully. + * Provides an interface and default functions for loading and unloading + * modules. This is used internally to make GIO extensible, but can also + * be used by others to implement module loading. */ /** - * G_TYPE_IS_CLASSED: - * @type: A #GType value. - * - * Checks if @type is a classed type. + * SECTION:gioschedule: + * @short_description: I/O Scheduler + * @include: gio/gio.h * - * Returns: %TRUE on success. + * Schedules asynchronous I/O operations. #GIOScheduler integrates + * into the main event loop (#GMainLoop) and may use threads if they + * are available. + * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm> + * Each I/O operation has a priority, and the scheduler uses the priorities + * to determine the order in which operations are executed. They are + * <emphasis>not</emphasis> used to determine system-wide I/O scheduling. + * Priorities are integers, with lower numbers indicating higher priority. + * It is recommended to choose priorities between %G_PRIORITY_LOW and + * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default. + * </para> */ /** - * g_resolver_lookup_by_address_finish: - * @resolver: a #GResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL + * SECTION:giostrea: + * @short_description: Base class for implementing read/write streams + * @include: gio/gio.h + * @see_also: #GInputStream, #GOutputStream * - * Retrieves the result of a previous call to - * g_resolver_lookup_by_address_async(). - * If the DNS resolution failed, @error (if non-%NULL) will be set to - * a value from #GResolverError. If the operation was cancelled, - * form), or %NULL on error. + * GIOStream represents an object that has both read and write streams. + * Generally the two streams acts as separate input and output streams, + * but they share some common resources and state. For instance, for + * seekable streams they may use the same position in both streams. + * Examples of #GIOStream objects are #GSocketConnection which represents + * a two-way network connection, and #GFileIOStream which represent a + * file handle opened in read-write mode. + * To do the actual reading and writing you need to get the substreams + * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream(). + * The #GIOStream object owns the input and the output streams, not the other + * way around, so keeping the substreams alive will not keep the #GIOStream + * object alive. If the #GIOStream object is freed it will be closed, thus + * closing the substream, so even if the substreams stay alive they will + * always just return a %G_IO_ERROR_CLOSED for all operations. + * To close a stream use g_io_stream_close() which will close the common + * stream object and also the individual substreams. You can also close + * the substreams themselves. In most cases this only marks the + * substream as closed, so further I/O on it fails. However, some streams + * may support "half-closed" states where one direction of the stream + * is actually shut down. * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded * Since: 2.22 */ /** - * G_TYPE_PARAM_OVERRIDE: - * - * The #GType of #GParamSpecOverride. + * SECTION:gloadableico: + * @short_description: Loadable Icons + * @include: gio/gio.h + * @see_also: #GIcon, #GThemedIcon * - * Since: 2.4 + * Extends the #GIcon interface and adds the ability to + * load icons from streams. */ /** - * mime_info_cache_reload: - * @dir: directory path which needs reloading. + * SECTION:gmemoryinputstrea: + * @short_description: Streaming input operations on memory chunks + * @include: gio/gio.h + * @see_also: #GMemoryOutputStream * - * Reload the mime information for the @dir. + * #GMemoryInputStream is a class for using arbitrary + * memory chunks as input for GIO streaming input operations. */ /** - * g_socket_get_fd: - * @socket: a #GSocket. - * - * Returns the underlying OS socket object. On unix this - * is a socket file descriptor, and on windows this is - * a Winsock2 SOCKET handle. This may be useful for - * doing platform specific or otherwise unusual operations - * on the socket. + * SECTION:gmemoryoutputstrea: + * @short_description: Streaming output operations on memory chunks + * @include: gio/gio.h + * @see_also: #GMemoryInputStream * - * Returns: the file descriptor of the socket. - * Since: 2.22 + * #GMemoryOutputStream is a class for using arbitrary + * memory chunks as output for GIO streaming output operations. */ /** - * GTypeClass: + * SECTION:gmoun: + * @short_description: Mount management + * @include: gio/gio.h + * @see_also: GVolume, GUnixMount * - * An opaque structure used as the base of all classes. + * The #GMount interface represents user-visible mounts. Note, when + * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume. + * #GMount is a "mounted" filesystem that you can access. Mounted is in + * quotes because it's not the same as a unix mount, it might be a gvfs + * mount, but you can still access the files on it if you use GIO. Might or + * might not be related to a volume object. + * Unmounting a #GMount instance is an asynchronous operation. For + * more information about asynchronous operations, see #GAsyncReady + * and #GSimpleAsyncReady. To unmount a #GMount instance, first call + * g_mount_unmount_with_operation() with (at least) the #GMount instance and a + * #GAsyncReadyCallback. The callback will be fired when the + * operation has resolved (either with success or failure), and a + * #GAsyncReady structure will be passed to the callback. That + * callback should then call g_mount_unmount_with_operation_finish() with the #GMount + * and the #GAsyncReady data to see if the operation was completed + * successfully. If an @error is present when g_mount_unmount_with_operation_finish() + * is called, then it will be filled with any error information. */ /** - * GBindingTransformFunc: - * @binding: a #GBinding - * @source_value: the value of the source property - * @target_value: the value of the target property - * @user_data: data passed to the transform function - * - * A function to be called to transform the source property of @source - * from @source_value into the target property of @target - * using @target_value. - * otherwise + * SECTION:gmountoperatio: + * @short_description: Object used for authentication and user interaction + * @include: gio/gio.h * - * Returns: %TRUE if the transformation was successful, and %FALSE - * Since: 2.26 + * #GMountOperation provides a mechanism for interacting with the user. + * It can be used for authenticating mountable operations, such as loop + * mounting files, hard drive partitions or server locations. It can + * also be used to ask the user questions or show a list of applications + * preventing unmount or eject operations from completing. + * Note that #GMountOperation is used for more than just #GMount + * objects – for example it is also used in g_drive_start() and + * g_drive_stop(). + * Users should instantiate a subclass of this that implements all the + * various callbacks to show the required dialogs, such as + * #GtkMountOperation. If no user interaction is desired (for example + * when automounting filesystems at login time), usually %NULL can be + * passed, see each method taking a #GMountOperation for details. */ /** - * G_PARAM_SPEC_OVERRIDE: - * @pspec: a #GParamSpec - * - * Casts a #GParamSpec into a #GParamSpecOverride. + * SECTION:gnetworkaddres: + * @short_description: A GSocketConnectable for resolving hostnames + * @include: gio/gio.h * - * Since: 2.4 + * #GNetworkAddress provides an easy way to resolve a hostname and + * then attempt to connect to that host, handling the possibility of + * multiple IP addresses and multiple address families. + * See #GSocketConnectable for and example of using the connectable + * interface. */ /** - * GEmblemedIcon: + * SECTION:gnetworkservic: + * @short_description: A GSocketConnectable for resolving SRV records + * @include: gio/gio.h * - * An implementation of #GIcon for icons with emblems. + * Like #GNetworkAddress does with hostnames, #GNetworkService + * provides an easy way to resolve a SRV record, and then attempt to + * connect to one of the hosts that implements that service, handling + * service priority/weighting, multiple IP addresses, and multiple + * address families. + * See #GSrvTarget for more information about SRV records, and see + * #GSocketConnectable for and example of using the connectable + * interface. */ /** - * GDBusConnection:address: - * - * A D-Bus address specifying potential endpoints that can be used - * when establishing the connection. + * SECTION:goutputstrea: + * @short_description: Base class for implementing streaming output + * @include: gio/gio.h * - * Since: 2.26 + * GOutputStream has functions to write to a stream (g_output_stream_write()), + * to close a stream (g_output_stream_close()) and to flush pending writes + * (g_output_stream_flush()). + * To copy the content of an input stream to an output stream without + * manually handling the reads and writes, use g_output_stream_splice(). + * All of these functions have async variants too. */ /** - * g_mount_operation_set_choice: - * @op: a #GMountOperation. - * @choice: an integer. + * SECTION:gpermissio: + * @title: GPermission + * @short_description: An object representing the permission to perform a certain action * - * Sets a default choice for the mount operation. + * A #GPermission represents the status of the caller's permission to + * perform a certain action. + * You can query if the action is currently allowed and if it is + * possible to acquire the permission so that the action will be allowed + * in the future. + * There is also an API to actually acquire the permission and one to + * release it. + * As an example, a #GPermission might represent the ability for the + * user to write to a #GSettings object. This #GPermission object could + * then be used to decide if it is appropriate to show a "Click here to + * unlock" button in a dialog and to provide the mechanism to invoke + * when that button is clicked. */ /** - * g_dbus_message_set_body: - * @message: A #GDBusMessage. - * @body: Either %NULL or a #GVariant that is a tuple. + * SECTION:gpollableinputstrea: + * @short_description: Interface for pollable input streams + * @include: gio/gio.h + * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased * - * Sets the body @message. As a side-effect the - * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the - * type string of @body (or cleared if @body is %NULL). - * If @body is floating, @message assumes ownership of @body. + * #GPollableInputStream is implemented by #GInputStream<!-- -->s that + * can be polled for readiness to read. This can be used when + * interfacing with a non-GIO API that expects + * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. * - * Since: 2.26 + * Since: 2.28 */ /** - * G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT: + * SECTION:gpollableoutputstrea: + * @short_description: Interface for pollable output streams + * @include: gio/gio.h + * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream * - * The string used to obtain a NFS mount with g_volume_get_identifier(). - */ - - -/** - * GFlagsValue: - * @value: the flags value - * @value_name: the name of the value - * @value_nick: the nickname of the value + * #GPollableOutputStream is implemented by #GOutputStream<!-- -->s that + * can be polled for readiness to write. This can be used when + * interfacing with a non-GIO API that expects + * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. * - * A structure which contains a single flags value, its name, and its - * nickname. + * Since: 2.28 */ /** - * g_data_input_stream_read_upto_async: - * @stream: a #GDataInputStream - * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated - * @io_priority: the <link linkend="io-priority">I/O priority</link> 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 + * SECTION:gprox: + * @short_description: Interface for proxy handling * - * The asynchronous version of g_data_input_stream_read_upto(). - * It is an error to have two outstanding calls to this function. - * In contrast to g_data_input_stream_read_until(), this function - * does <emphasis>not</emphasis> consume the stop character. You have - * to use g_data_input_stream_read_byte() to get it before calling - * g_data_input_stream_read_upto() again. - * Note that @stop_chars may contain '\0' if @stop_chars_len is - * specified. - * When the operation is finished, @callback will be called. You - * can then call g_data_input_stream_read_upto_finish() to get - * the result of the operation. + * A #GProxy handles connecting to a remote host via a given type of + * proxy server. It is implemented by the 'gio-proxy' extension point. + * The extensions are named after their proxy protocol name. As an + * example, a SOCKS5 proxy implementation can be retrieved with the + * name 'socks5' using the function + * g_io_extension_point_get_extension_by_name(). * - * Since: 2.24 + * Since: 2.26 */ /** - * g_tls_certificate_verify: - * @cert: a #GTlsCertificate - * @identity: (allow-none): the expected peer identity - * @trusted_ca: (allow-none): the certificate of a trusted authority - * - * This verifies @cert and returns a set of #GTlsCertificateFlags - * indicating any problems found with it. This can be used to verify a - * certificate outside the context of making a connection, or to - * check a certificate against a CA that is not part of the system - * CA database. - * If @identity is not %NULL, @cert's name(s) will be compared against - * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return - * value if it does not match. If @identity is %NULL, that bit will - * never be set in the return value. - * If @trusted_ca is not %NULL, then @cert (or one of the certificates - * in its chain) must be signed by it, or else - * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If - * value. - * (All other #GTlsCertificateFlags values will always be set or unset - * as appropriate.) + * SECTION:gproxyaddres: + * @short_description: An internet address with proxy information * - * Returns: the appropriate #GTlsCertificateFlags - * Since: 2.28 + * Support for proxied #GInetSocketAddress. */ /** - * g_application_set_application_id: - * @application: a #GApplication - * @application_id: the identifier for @application - * - * Sets the unique identifier for @application. - * The application id can only be modified if @application has not yet - * been registered. - * The application id must be valid. See g_application_id_is_valid(). + * SECTION:gproxyresolve: + * @short_description: Asynchronous and cancellable network proxy resolver + * @include: gio/gio.h * - * Since: 2.28 + * #GProxyResolver provides synchronous and asynchronous network proxy + * resolution. #GProxyResolver is used within #GClientSocket through + * the method g_socket_connectable_proxy_enumerate(). */ /** - * GCredentialsType: - * @G_CREDENTIALS_TYPE_INVALID: Indicates an invalid native credential type. - * @G_CREDENTIALS_TYPE_LINUX_UCRED: The native credentials type is a <type>struct ucred</type>. - * @G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED: The native credentials type is a <type>struct cmsgcred</type>. - * - * Enumeration describing different kinds of native credential types. + * SECTION:gresolve: + * @short_description: Asynchronous and cancellable DNS resolver + * @include: gio/gio.h * - * Since: 2.26 + * #GResolver provides cancellable synchronous and asynchronous DNS + * resolution, for hostnames (g_resolver_lookup_by_address(), + * g_resolver_lookup_by_name() and their async variants) and SRV + * (service) records (g_resolver_lookup_service()). + * #GNetworkAddress and #GNetworkService provide wrappers around + * #GResolver functionality that also implement #GSocketConnectable, + * making it easy to connect to a remote host/service. */ /** - * GSocketClient: - * - * A helper class for network servers to listen for and accept connections. + * SECTION:gseekabl: + * @short_description: Stream seeking interface + * @include: gio/gio.h + * @see_also: #GInputStream, #GOutputStream * - * Since: 2.22 + * #GSeekable is implemented by streams (implementations of + * #GInputStream or #GOutputStream) that support seeking. */ /** - * g_dbus_method_invocation_get_object_path: - * @invocation: A #GDBusMethodInvocation. - * - * Gets the object path the method was invoked on. + * SECTION:gsetting: + * @short_description: High-level API for application settings * - * Returns: A string. Do not free, it is owned by @invocation. - * Since: 2.26 + * The #GSettings class provides a convenient API for storing and retrieving + * application settings. + * When creating a GSettings instance, you have to specify a schema + * that describes the keys in your settings and their types and default + * values, as well as some other information. + * Normally, a schema has as fixed path that determines where the settings + * are stored in the conceptual global tree of settings. However, schemas + * can also be 'relocatable', i.e. not equipped with a fixed path. This is + * useful e.g. when the schema describes an 'account', and you want to be + * able to store a arbitrary number of accounts. + * Unlike other configuration systems (like GConf), GSettings does not + * restrict keys to basic types like strings and numbers. GSettings stores + * values as #GVariant, and allows any #GVariantType for keys. Key names + * are restricted to lowercase characters, numbers and '-'. Furthermore, + * the names must begin with a lowercase character, must not end + * with a '-', and must not contain consecutive dashes. Key names can + * be up to 32 characters long. + * 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 + * <tag class="attribute">gettext-domain</tag> attribute of the + * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag> + * elements and the category that is specified in the l10n attribute of the + * <tag class="starttag">key</tag> element. + * GSettings uses schemas in a compact binary form that is created + * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link> + * utility. The input is a schema description in an XML format that can be + * described by the following DTD: + * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/gschema.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]| + * At runtime, schemas are identified by their id (as specified + * in the <tag class="attribute">id</tag> attribute of the + * <tag class="starttag">schema</tag> element). The + * convention for schema ids is to use a dotted name, similar in + * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular, + * if the settings are for a specific service that owns a D-Bus bus name, + * the D-Bus bus name and schema id should match. For schemas which deal + * with settings not associated with one named application, the id should + * not use StudlyCaps, e.g. "org.gnome.font-rendering". + * In addition to #GVariant types, keys can have types that have enumerated + * types. These can be described by a <tag class="starttag">choice</tag>, + * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see + * <xref linkend="schema-enumerated"/>. The underlying type of + * such a key is string, but you can use g_settings_get_enum(), + * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags() + * access the numeric values corresponding to the string value of enum + * and flags keys. + * <example id="schema-default-values"><title>Default values</title> + * <programlisting><![CDATA[ + * <schemalist> + * <schema id="org.gtk.Test" path="/tests/" gettext-domain="test"> + * <key name="greeting" type="s"> + * <default l10n="messages">"Hello, earthlings"</default> + * <summary>A greeting</summary> + * <description> + * Greeting of the invading martians + * </description> + * </key> + * <key name="box" type="(ii)"> + * <default>(20,30)</default> + * </key> + * </schema> + * </schemalist> + * ]]></programlisting></example> + * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title> + * <programlisting><![CDATA[ + * <schemalist> + * <enum id="myenum"> + * <value nick="first" value="1"/> + * <value nick="second" value="2"/> + * </enum> + * <enum id="myflags"> + * <value nick="flag1" value="1"/> + * <value nick="flag2" value="2"/> + * <value nick="flag3" value="4"/> + * </enum> + * <schema id="org.gtk.Test"> + * <key name="key-with-range" type="i"> + * <range min="1" max="100"/> + * <default>10</default> + * </key> + * <key name="key-with-choices" type="s"> + * <choices> + * <choice value='Elisabeth'/> + * <choice value='Annabeth'/> + * <choice value='Joe'/> + * </choices> + * <aliases> + * <alias value='Anna' target='Annabeth'/> + * <alias value='Beth' target='Elisabeth'/> + * </aliases> + * <default>'Joe'</default> + * </key> + * <key name='enumerated-key' enum='myenum'> + * <default>'first'</default> + * </key> + * <key name='flags-key' flags='myflags'> + * <default>["flag1",flag2"]</default> + * </key> + * </schema> + * </schemalist> + * ]]></programlisting></example> + * <refsect2> + * <title>Vendor overrides</title> + * <para> + * Default values are defined in the schemas that get installed by + * an application. Sometimes, it is necessary for a vendor or distributor + * to adjust these defaults. Since patching the XML source for the schema + * is inconvenient and error-prone, + * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads + * so-called 'vendor override' files. These are keyfiles in the same + * directory as the XML schema sources which can override default values. + * The schema id serves as the group name in the key file, and the values + * are expected in serialized GVariant form, as in the following example: + * <informalexample><programlisting> + * [org.gtk.Example] + * key1='string' + * key2=1.5 + * </programlisting></informalexample> + * </para> + * </refsect2> + * <refsect2> + * <title>Binding</title> + * <para> + * A very convenient feature of GSettings lets you bind #GObject properties + * directly to settings, using g_settings_bind(). Once a GObject property + * has been bound to a setting, changes on either side are automatically + * propagated to the other side. GSettings handles details like + * mapping between GObject and GVariant types, and preventing infinite + * cycles. + * </para> + * <para> + * This makes it very easy to hook up a preferences dialog to the + * underlying settings. To make this even more convenient, GSettings + * looks for a boolean property with the name "sensitivity" and + * automatically binds it to the writability of the bound setting. + * If this 'magic' gets in the way, it can be suppressed with the + * #G_SETTINGS_BIND_NO_SENSITIVITY flag. + * </para> + * </refsect2> */ /** - * g_application_open: - * @application: a #GApplication - * @files: (array length=n_files): an array of #GFiles to open - * @n_files: the length of the @files array - * @hint: a hint (or ""), but never %NULL - * - * Opens the given files. - * In essence, this results in the #GApplication::open signal being emitted - * in the primary instance. - * intended to be used by applications that have multiple modes for - * for this functionality, you should use "". - * The application must be registered before calling this function - * and it must have the %G_APPLICATION_HANDLES_OPEN flag set. + * SECTION:gsettingsbacken: + * @title: GSettingsBackend + * @short_description: Interface for settings backend implementations + * @include: gio/gsettingsbackend.h + * @see_also: #GSettings, #GIOExtensionPoint * - * Opening files (eg: "view" vs "edit", etc). Unless you have a need - * Since: 2.28 + * The #GSettingsBackend interface defines a generic interface for + * non-strictly-typed data that is stored in a hierarchy. To implement + * an alternative storage backend for #GSettings, you need to implement + * the #GSettingsBackend interface and then make it implement the + * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME. + * The interface defines methods for reading and writing values, a + * method for determining if writing of certain values will fail + * (lockdown) and a change notification mechanism. + * The semantics of the interface are very precisely defined and + * implementations must carefully adhere to the expectations of + * callers that are documented on each of the interface methods. + * Some of the GSettingsBackend functions accept or return a #GTree. + * These trees always have strings as keys and #GVariant as values. + * g_settings_backend_create_tree() is a convenience function to create + * suitable trees. + * <note><para> + * The #GSettingsBackend API is exported to allow third-party + * implementations, but does not carry the same stability guarantees + * as the public GIO API. For this reason, you have to define the + * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including + * <filename>gio/gsettingsbackend.h</filename> + * </para></note> */ /** - * G_CONVERT_ERROR: + * SECTION:gsimpleactio: + * @title: GSimpleAction + * @short_description: A simple GSimpleAction * - * Error domain for character set conversions. Errors in this domain will - * be from the #GConvertError enumeration. See #GError for information on - * error domains. + * A #GSimpleAction is the obvious simple implementation of the #GSimpleAction + * interface. This is the easiest way to create an action for purposes of + * adding it to a #GSimpleActionGroup. + * See also #GtkAction. */ /** - * g_file_append_to_finish: - * @file: input #GFile. - * @res: #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file append operation started with - * g_file_append_to_async(). - * Free the returned object with g_object_unref(). + * SECTION:gsimpleactiongrou: + * @title: GSimpleActionGroup + * @short_description: A simple GActionGroup implementation * - * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error. + * #GSimpleActionGroup is a hash table filled with #GAction objects, + * implementing the #GActionGroup interface. */ /** - * g_dbus_is_address: - * @string: A string. - * - * Checks if @string is a D-Bus address. - * This doesn't check if @string is actually supported by #GDBusServer - * or #GDBusConnection - use g_dbus_is_supported_address() to do more - * checks. + * SECTION:gsimpleasyncresul: + * @short_description: Simple asynchronous results implementation + * @include: gio/gio.h + * @see_also: #GAsyncResult * - * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise. - * Since: 2.26 + * Implements #GAsyncResult for simple cases. Most of the time, this + * will be all an application needs, and will be used transparently. + * Because of this, #GSimpleAsyncResult is used throughout GIO for + * handling asynchronous functions. + * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error + * reporting, operation cancellation and the final state of an operation, + * completely transparent to the application. Results can be returned + * as a pointer e.g. for functions that return data that is collected + * asynchronously, a boolean value for checking the success or failure + * of an operation, or a #gssize for operations which return the number + * of bytes modified by the operation; all of the simple return cases + * are covered. + * Most of the time, an application will not need to know of the details + * of this API; it is handled transparently, and any necessary operations + * are handled by #GAsyncResult's interface. However, if implementing a + * new GIO module, for writing language bindings, or for complex + * applications that need better control of how asynchronous operations + * are completed, it is important to understand this functionality. + * GSimpleAsyncResults are tagged with the calling function to ensure + * that asynchronous functions and their finishing functions are used + * together correctly. + * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). + * If the result needs to be created for a #GError, use + * g_simple_async_result_new_from_error() or + * g_simple_async_result_new_take_error(). If a #GError is not available + * (e.g. the asynchronous operation's doesn't take a #GError argument), + * but the result still needs to be created for an error condition, use + * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() + * if your application or binding requires passing a variable argument list + * directly), and the error can then be propagated through the use of + * g_simple_async_result_propagate_error(). + * An asynchronous operation can be made to ignore a cancellation event by + * calling g_simple_async_result_set_handle_cancellation() with a + * #GSimpleAsyncResult for the operation and %FALSE. This is useful for + * operations that are dangerous to cancel, such as close (which would + * cause a leak if cancelled before being run). + * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, + * or it can use #GThread<!-- -->s if available. + * g_simple_async_result_complete() will finish an I/O task directly + * from the point where it is called. g_simple_async_result_complete_in_idle() + * will finish it from an idle handler in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * context</link>. g_simple_async_result_run_in_thread() will run the + * job in a separate thread and then deliver the result to the + * thread-default main context. + * To set the results of an asynchronous function, + * g_simple_async_result_set_op_res_gpointer(), + * g_simple_async_result_set_op_res_gboolean(), and + * g_simple_async_result_set_op_res_gssize() + * are provided, setting the operation's result to a gpointer, gboolean, or + * gssize, respectively. + * Likewise, to get the result of an asynchronous function, + * g_simple_async_result_get_op_res_gpointer(), + * g_simple_async_result_get_op_res_gboolean(), and + * g_simple_async_result_get_op_res_gssize() are + * provided, getting the operation's result as a gpointer, gboolean, and + * gssize, respectively. + * For the details of the requirements implementations must respect, see + * #GAsyncResult. A typical implementation of an asynchronous operation + * using GSimpleAsyncResult looks something like this: + * |[ + * static void + * baked_cb (Cake *cake, + * gpointer user_data) + * { + * /* In this example, this callback is not given a reference to the cake, so + * * the GSimpleAsyncResult has to take a reference to it. + * */ + * GSimpleAsyncResult *result = user_data; + * if (cake == NULL) + * g_simple_async_result_set_error (result, + * BAKER_ERRORS, + * BAKER_ERROR_NO_FLOUR, + * "Go to the supermarket"); + * else + * g_simple_async_result_set_op_res_gpointer (result, + * g_object_ref (cake), + * g_object_unref); + * /* In this example, we assume that baked_cb is called as a callback from + * * the mainloop, so it's safe to complete the operation synchronously here. + * * If, however, _baker_prepare_cake () might call its callback without + * * first returning to the mainloop — inadvisable, but some APIs do so — + * * we would need to use g_simple_async_result_complete_in_idle(). + * */ + * g_simple_async_result_complete (result); + * g_object_unref (result); + * } + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * GSimpleAsyncResult *simple; + * Cake *cake; + * if (radius < 3) + * { + * g_simple_async_report_error_in_idle (G_OBJECT (self), + * callback, + * user_data, + * BAKER_ERRORS, + * BAKER_ERROR_TOO_SMALL, + * "%ucm radius cakes are silly", + * radius); + * return; + * } + * simple = g_simple_async_result_new (G_OBJECT (self), + * callback, + * user_data, + * baker_bake_cake_async); + * cake = _baker_get_cached_cake (self, radius); + * if (cake != NULL) + * { + * g_simple_async_result_set_op_res_gpointer (simple, + * g_object_ref (cake), + * g_object_unref); + * g_simple_async_result_complete_in_idle (simple); + * g_object_unref (simple); + * /* Drop the reference returned by _baker_get_cached_cake(); the + * * GSimpleAsyncResult has taken its own reference. + * */ + * g_object_unref (cake); + * return; + * } + * _baker_prepare_cake (self, radius, baked_cb, simple); + * } + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * GSimpleAsyncResult *simple; + * Cake *cake; + * g_return_val_if_fail (g_simple_async_result_is_valid (result, + * G_OBJECT (self), + * baker_bake_cake_async), + * NULL); + * simple = (GSimpleAsyncResult *) result; + * if (g_simple_async_result_propagate_error (simple, error)) + * return NULL; + * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); + * return g_object_ref (cake); + * } + * ]| */ /** - * g_dbus_message_get_flags: - * @message: A #GDBusMessage. - * - * Gets the flags for @message. + * SECTION:gsimplepermissio: + * @title: GSimplePermission + * @short_description: A GPermission that doesn't change value * - * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). - * Since: 2.26 + * #GSimplePermission is a trivial implementation of #GPermission that + * represents a permission that is either always or never allowed. The + * value is given at constuction and doesn't change. + * Calling request or release will result in errors. */ /** - * g_dbus_arg_info_unref: - * @info: A #GDBusArgInfo. + * SECTION:gsocke: + * @short_description: Low-level socket object + * @include: gio/gio.h + * @see_also: #GInitable * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. + * A #GSocket is a low-level networking primitive. It is a more or less + * direct mapping of the BSD socket API in a portable GObject based API. + * It supports both the UNIX socket implementations and winsock2 on Windows. + * #GSocket is the platform independent base upon which the higher level + * network primitives are based. Applications are not typically meant to + * use it directly, but rather through classes like #GSocketClient, + * #GSocketService and #GSocketConnection. However there may be cases where + * direct use of #GSocket is useful. + * #GSocket implements the #GInitable interface, so if it is manually constructed + * by e.g. g_object_new() you must call g_initable_init() and check the + * results before using the object. This is done automatically in + * g_socket_new() and g_socket_new_from_fd(), so these functions can return + * %NULL. + * Sockets operate in two general modes, blocking or non-blocking. When + * in blocking mode all operations block until the requested operation + * is finished or there is an error. In non-blocking mode all calls that + * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error. + * To know when a call would successfully run you can call g_socket_condition_check(), + * or g_socket_condition_wait(). You can also use g_socket_create_source() and + * attach it to a #GMainContext to get callbacks when I/O is possible. + * Note that all sockets are always set to non blocking mode in the system, and + * blocking mode is emulated in GSocket. + * When working in non-blocking mode applications should always be able to + * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other + * function said that I/O was possible. This can easily happen in case + * of a race condition in the application, but it can also happen for other + * reasons. For instance, on Windows a socket is always seen as writable + * until a write returns %G_IO_ERROR_WOULD_BLOCK. + * #GSocket<!-- -->s can be either connection oriented or datagram based. + * For connection oriented types you must first establish a connection by + * either connecting to an address or accepting a connection from another + * address. For connectionless socket types the target/source address is + * specified or received in each I/O operation. + * All socket file descriptors are set to be close-on-exec. + * Note that creating a #GSocket causes the signal %SIGPIPE to be + * ignored for the remainder of the program. If you are writing a + * command-line utility that uses #GSocket, you may need to take into + * account the fact that your program will not automatically be killed + * if it tries to write to %stdout after it has been closed. * - * Since: 2.26 + * Since: 2.22 */ /** - * g_mount_operation_new: - * - * Creates a new mount operation. + * SECTION:gsocketaddres: + * @short_description: Abstract base class representing endpoints for socket communication * - * Returns: a #GMountOperation. + * #GSocketAddress is the equivalent of <type>struct sockaddr</type> + * in the BSD sockets API. This is an abstract class; use + * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress + * for UNIX domain sockets. */ /** - * GSimpleAction:state-type: + * SECTION:gsocketclien: + * @short_description: Helper for connecting to a network service + * @include: gio/gio.h + * @see_also: #GSocketConnection, #GSocketListener * - * The #GVariantType of the state that the action has, or %NULL if the - * action is stateless. + * #GSocketClient is a high-level utility class for connecting to a + * network host using a connection oriented socket type. + * You create a #GSocketClient object, set any options you want, then + * call a sync or async connect operation, which returns a #GSocketConnection + * subclass on success. + * The type of the #GSocketConnection object returned depends on the type of + * the underlying socket that is in use. For instance, for a TCP/IP connection + * it will be a #GTcpConnection. * - * Since: 2.28 + * Since: 2.22 */ /** - * G_TYPE_CHECK_CLASS_TYPE: - * @g_class: Location of a #GTypeClass structure. - * @g_type: The type to be checked. + * SECTION:gsocketconnectabl: + * @short_description: Interface for potential socket endpoints * - * Checks if @g_class is a class structure of the type identified by - * This macro should only be used in type implementations. + * Objects that describe one or more potential socket endpoints + * implement #GSocketConnectable. Callers can then use + * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator + * to try out each socket address in turn until one succeeds, as shown + * in the sample code below. + * |[ + * MyConnectionType * + * connect_to_host (const char *hostname, + * guint16 port, + * GCancellable *cancellable, + * GError **error) + * { + * MyConnection *conn = NULL; + * GSocketConnectable *addr; + * GSocketAddressEnumerator *enumerator; + * GSocketAddress *sockaddr; + * GError *conn_error = NULL; + * addr = g_network_address_new ("www.gnome.org", 80); + * enumerator = g_socket_connectable_enumerate (addr); + * g_object_unref (addr); + * /<!-- -->* Try each sockaddr until we succeed. Record the first + * * connection error, but not any further ones (since they'll probably + * * be basically the same as the first). + * *<!-- -->/ + * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error)) + * { + * g_object_unref (sockaddr); + * } + * g_object_unref (enumerator); + * if (conn) + * { + * if (conn_error) + * { + * /<!-- -->* We couldn't connect to the first address, but we succeeded + * * in connecting to a later address. + * *<!-- -->/ + * g_error_free (conn_error); + * } + * return conn; + * } + * else if (error) + * { + * /<!-- -->* Either the initial lookup failed, or else the caller + * * cancelled us. + * *<!-- -->/ + * if (conn_error) + * g_error_free (conn_error); + * return NULL; + * } + * else + * { + * g_error_propagate (error, conn_error); + * return NULL; + * } + * } + * ]| * - * Returns: %TRUE on success. + * Conn = connect_to_sockaddr (sockaddr, conn_error ? null : &conn_error); */ /** - * g_io_modules_load_all_in_directory: - * @dirname: pathname for a directory containing modules to load. + * SECTION:gsocketconnectio: + * @short_description: A socket connection + * @include: gio/gio.h + * @see_also: #GIOStream, #GSocketClient, #GSocketListener * - * Loads all the modules in the specified directory. - * If don't require all modules to be initialized (and thus registering - * all gtypes) then you can use g_io_modules_scan_all_in_directory() - * which allows delayed/lazy loading of modules. - * from the directory, - * All the modules are loaded into memory, if you want to - * unload them (enabling on-demand loading) you must call - * g_type_module_unuse() on all the modules. Free the list - * with g_list_free(). + * #GSocketConnection is a #GIOStream for a connected socket. They + * can be created either by #GSocketClient when connecting to a host, + * or by #GSocketListener when accepting a new client. + * The type of the #GSocketConnection object returned from these calls + * depends on the type of the underlying socket that is in use. For + * instance, for a TCP/IP connection it will be a #GTcpConnection. + * Chosing what type of object to construct is done with the socket + * connection factory, and it is possible for 3rd parties to register + * custom socket connection types for specific combination of socket + * family/type/protocol using g_socket_connection_factory_register_type(). * - * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded + * Since: 2.22 */ /** - * g_unix_connection_receive_credentials: - * @connection: A #GUnixConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Receives credentials from the sending end of the connection. The - * sending end has to call g_unix_connection_send_credentials() (or - * similar) for this to work. - * As well as reading the credentials this also reads (and discards) a - * single byte from the stream, as this is required for credentials - * passing to work on some implementations. - * Other ways to exchange credentials with a foreign peer includes the - * #GUnixCredentialsMessage type and g_socket_get_credentials() function. - * g_object_unref()), %NULL if @error is set. + * SECTION:gsrvtarge: + * @short_description: DNS SRV record target + * @include: gio/gio.h * - * Returns: (transfer full): Received credentials on success (free with - * Since: 2.26 + * SRV (service) records are used by some network protocols to provide + * service-specific aliasing and load-balancing. For example, XMPP + * (Jabber) uses SRV records to locate the XMPP server for a domain; + * rather than connecting directly to "example.com" or assuming a + * specific server hostname like "xmpp.example.com", an XMPP client + * would look up the "xmpp-client" SRV record for "example.com", and + * then connect to whatever host was pointed to by that record. + * You can use g_resolver_lookup_service() or + * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s + * for a given service. However, if you are simply planning to connect + * to the remote service, you can use #GNetworkService's + * #GSocketConnectable interface and not need to worry about + * #GSrvTarget at all. */ /** - * g_proxy_resolver_lookup_finish: - * @resolver: a #GProxyResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL - * - * Call this function to obtain the array of proxy URIs when - * g_proxy_resolver_lookup_async() is complete. See - * g_proxy_resolver_lookup() for more details. - * NULL-terminated array of proxy URIs. Must be freed - * with g_strfreev(). + * SECTION:gthemedico: + * @short_description: Icon theming support + * @include: gio/gio.h + * @see_also: #GIcon, #GLoadableIcon * - * Returns: (transfer full) (array zero-terminated=1): A - * Since: 2.26 + * #GThemedIcon is an implementation of #GIcon that supports icon themes. + * #GThemedIcon contains a list of all of the icons present in an icon + * theme, so that icons can be looked up quickly. #GThemedIcon does + * not provide actual pixmaps for icons, just the icon names. + * Ideally something like gtk_icon_theme_choose_icon() should be used to + * resolve the list of names so that fallback icons work nicely with + * themes that inherit other themes. */ /** - * g_dbus_message_set_error_name: - * @message: A #GDBusMessage. - * @value: The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. + * SECTION:gtl: + * @title: TLS Overview + * @short_description: TLS (aka SSL) support for GSocketConnection + * @include: gio/gio.h * - * Since: 2.26 + * #GTlsConnection and related classes provide TLS (Transport Layer + * Security, previously known as SSL, Secure Sockets Layer) support for + * gio-based network streams. + * In the simplest case, for a client connection, you can just set the + * #GSocketClient:tls flag on a #GSocketClient, and then any + * connections created by that client will have TLS negotiated + * automatically, using appropriate default settings, and rejecting + * any invalid or self-signed certificates (unless you change that + * default by setting the #GSocketClient:tls-validation-flags + * property). The returned object will be a #GTcpWrapperConnection, + * which wraps the underlying #GTlsClientConnection. + * For greater control, you can create your own #GTlsClientConnection, + * wrapping a #GSocketConnection (or an arbitrary #GIOStream with + * pollable input and output streams) and then connect to its signals, + * such as #GTlsConnection::accept-certificate, before starting the + * handshake. + * Server-side TLS is similar, using #GTlsServerConnection. At the + * moment, there is no support for automatically wrapping server-side + * connections in the way #GSocketClient does for client-side + * connections. */ /** - * g_socket_client_connect_async: - * @client: a #GTcpClient - * @connectable: a #GSocketConnectable specifying the remote address. - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback + * SECTION:gtlsbacken: + * @title: GTlsBackend + * @short_description: TLS backend implementation + * @include: gio/gio.h * - * This is the asynchronous version of g_socket_client_connect(). - * When the operation is finished @callback will be - * called. You can then call g_socket_client_connect_finish() to get - * the result of the operation. * - * Since: 2.22 */ /** - * g_io_module_unload: - * @module: a #GIOModule. + * SECTION:gtlsclientconnectio: + * @short_description: TLS client-side connection + * @include: gio/gio.h * - * Required API for GIO modules to implement. - * This function is ran when the module is being unloaded from GIO, - * to finalize the module. + * #GTlsClientConnection is the client-side subclass of + * #GTlsConnection, representing a client-side TLS connection. */ /** - * GResolver: + * SECTION:gtlsconnectio: + * @short_description: TLS connection type + * @include: gio/gio.h * - * The object that handles DNS resolution. Use g_resolver_get_default() - * to get the default resolver. + * #GTlsConnection is the base TLS connection class type, which wraps + * a #GIOStream and provides TLS encryption on top of it. Its + * subclasses, #GTlsClientConnection and #GTlsServerConnection, + * implement client-side and server-side TLS, respectively. + * + * Since: 2.28 */ /** - * GDBusConnection:guid: + * SECTION:gtlsserverconnectio: + * @short_description: TLS server-side connection + * @include: gio/gio.h * - * The GUID of the peer performing the role of server when - * authenticating. - * If you are constructing a #GDBusConnection and pass - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the - * #GDBusConnection:flags property then you MUST also set this - * property to a valid guid. - * If you are constructing a #GDBusConnection and pass - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the - * #GDBusConnection:flags property you will be able to read the GUID - * of the other peer here after the connection has been successfully - * initialized. + * #GTlsServerConnection is the server-side subclass of #GTlsConnection, + * representing a server-side TLS connection. * - * Since: 2.26 + * Since: 2.28 */ /** - * g_inet_address_new_from_string: - * @string: a string representation of an IP address - * - * Parses @string as an IP address and creates a new #GInetAddress. + * SECTION:gunixinputstrea: + * @short_description: Streaming input operations for UNIX file descriptors + * @include: gio/gunixinputstream.h + * @see_also: #GInputStream * - * Returns: a new #GInetAddress corresponding to @string, or %NULL if - * Since: 2.22 + * #GUnixInputStream implements #GInputStream for reading from a + * UNIX file descriptor, including asynchronous operations. The file + * descriptor must be selectable, so it doesn't work with opened files. + * Note that <filename><gio/gunixinputstream.h></filename> belongs + * to the UNIX-specific GIO interfaces, thus you have to use the + * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. */ /** - * g_app_info_get_id: - * @appinfo: a #GAppInfo. - * - * Gets the ID of an application. An id is a string that - * identifies the application. The exact format of the id is - * platform dependent. For instance, on Unix this is the - * desktop file id from the xdg menu specification. - * Note that the returned ID may be %NULL, depending on how - * the @appinfo has been constructed. + * SECTION:gunixmount: + * @include: gio/gunixmounts.h + * @short_description: UNIX mounts * - * Returns: a string containing the application's ID. + * Routines for managing mounted UNIX mount points and paths. + * Note that <filename><gio/gunixmounts.h></filename> belongs to the + * UNIX-specific GIO interfaces, thus you have to use the + * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. */ /** - * GMountOperation: + * SECTION:gunixoutputstrea: + * @short_description: Streaming output operations for UNIX file descriptors + * @include: gio/gunixoutputstream.h + * @see_also: #GOutputStream * - * Class for providing authentication methods for mounting operations, - * such as mounting a file locally, or authenticating with a server. + * #GUnixOutputStream implements #GOutputStream for writing to a + * UNIX file descriptor, including asynchronous operations. The file + * descriptor must be selectable, so it doesn't work with opened files. + * Note that <filename><gio/gunixoutputstream.h></filename> belongs + * to the UNIX-specific GIO interfaces, thus you have to use the + * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. */ /** - * g_dbus_message_new_method_error_literal: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. - * @error_name: A valid D-Bus error name. - * @error_message: The D-Bus error message. - * - * Creates a new #GDBusMessage that is an error reply to @method_call_message. + * SECTION:gunixsocketaddres: + * @short_description: UNIX GSocketAddress + * @include: gio/gunixsocketaddress.h * - * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * Support for UNIX-domain (also known as local) sockets. + * UNIX domain sockets are generally visible in the filesystem. + * However, some systems support abstract socket names which are not + * visible in the filesystem and not affected by the filesystem + * permissions, visibility, etc. Currently this is only supported + * under Linux. If you attempt to use abstract sockets on other + * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED + * errors. You can use g_unix_socket_address_abstract_names_supported() + * to see if abstract names are supported. + * Note that <filename><gio/gunixsocketaddress.h></filename> belongs to + * the UNIX-specific GIO interfaces, thus you have to use the + * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. */ /** - * GTlsCertificate:certificate: - * - * The DER (binary) encoded representation of the certificate's - * public key. This property and the - * #GTlsCertificate:certificate-pem property represent the same - * data, just in different forms. + * SECTION:gvf: + * @short_description: Virtual File System + * @include: gio/gio.h * - * Since: 2.28 + * Entry point for using GIO functionality. */ /** - * G_VALUE_HOLDS_FLOAT: - * @value: a valid #GValue structure + * SECTION:gvolum: + * @short_description: Volume management + * @include: gio/gio.h * - * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. + * The #GVolume interface represents user-visible objects that can be + * mounted. Note, when porting from GnomeVFS, #GVolume is the moral + * equivalent of #GnomeVFSDrive. + * Mounting a #GVolume instance is an asynchronous operation. For more + * information about asynchronous operations, see #GAsyncReady and + * #GSimpleAsyncReady. To mount a #GVolume, first call + * g_volume_mount() with (at least) the #GVolume instance, optionally + * a #GMountOperation object and a #GAsyncReadyCallback. + * Typically, one will only want to pass %NULL for the + * #GMountOperation if automounting all volumes when a desktop session + * starts since it's not desirable to put up a lot of dialogs asking + * for credentials. + * The callback will be fired when the operation has resolved (either + * with success or failure), and a #GAsyncReady structure will be + * passed to the callback. That callback should then call + * g_volume_mount_finish() with the #GVolume instance and the + * #GAsyncReady data to see if the operation was completed + * successfully. If an @error is present when g_volume_mount_finish() + * is called, then it will be filled with any error information. + * <para id="volume-identifier"> + * It is sometimes necessary to directly access the underlying + * operating system object behind a volume (e.g. for passing a volume + * to an application via the commandline). For this purpose, GIO + * allows to obtain an 'identifier' for the volume. There can be + * different kinds of identifiers, such as Hal UDIs, filesystem labels, + * traditional Unix devices (e.g. <filename>/dev/sda2</filename>), + * uuids. GIO uses predefind strings as names for the different kinds + * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier() + * to obtain an identifier for a volume. + * </para> + * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available + * when the gvfs hal volume monitor is in use. Other volume monitors + * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE + * identifier, which can be used to obtain a hal device by means of + * libhal_manger_find_device_string_match(). * - * Returns: %TRUE on success. + * Of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, */ /** - * g_dbus_node_info_lookup_interface: - * @info: A #GDBusNodeInfo. - * @name: A D-Bus interface name. - * - * Looks up information about an interface. - * This cost of this function is O(n) in number of interfaces. + * SECTION:gvolumemonito: + * @short_description: Volume Monitor + * @include: gio/gio.h + * @see_also: #GFileMonitor * - * Returns: A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. - * Since: 2.26 + * #GVolumeMonitor is for listing the user interesting devices and volumes + * on the computer. In other words, what a file selector or file manager + * would show in a sidebar. + * #GVolumeMonitor is not <link + * linkend="g-main-context-push-thread-default">thread-default-context + * aware</link>, and so should not be used other than from the main + * thread, with no thread-default-context active. */ /** - * g_data_output_stream_put_int64: - * @stream: a #GDataOutputStream. - * @data: a #gint64. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts a signed 64-bit integer into the stream. + * SECTION:gwin32inputstrea: + * @short_description: Streaming input operations for Windows file handles + * @include: gio/gwin32inputstream.h + * @see_also: #GInputStream * - * Returns: %TRUE if @data was successfully added to the @stream. + * #GWin32InputStream implements #GInputStream for reading from a + * Windows file handle. + * Note that <filename><gio/gwin32inputstream.h></filename> belongs + * to the Windows-specific GIO interfaces, thus you have to use the + * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it. */ /** - * g_output_stream_close: - * @stream: A #GOutputStream. - * @cancellable: (allow-none): optional cancellable object - * @error: location to store the error occuring, or %NULL to ignore - * - * Closes the stream, releasing resources related to it. - * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. - * Closing a stream multiple times will not return an error. - * Closing a stream will automatically flush any outstanding buffers in the - * stream. - * Streams will be automatically closed when the last reference - * is dropped, but you might want to call this function to make sure - * resources are released as early as possible. - * Some streams might keep the backing store of the stream (e.g. a file descriptor) - * open after the stream is closed. See the documentation for the individual - * stream for details. - * On failure the first error that happened will be reported, but the close - * operation will finish as much as possible. A stream that failed to - * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it - * is important to check and report the error to the user, otherwise - * there might be a loss of data as all data might not be written. - * If @cancellable is not NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Cancelling a close will still leave the stream closed, but there some streams - * can use a faster close that doesn't block to e.g. check errors. On - * cancellation (as with any error) there is no guarantee that all written - * data will reach the target. + * SECTION:gwin32outputstrea: + * @short_description: Streaming output operations for Windows file handles + * @include: gio/gwin32outputstream.h + * @see_also: #GOutputStream * - * Returns: %TRUE on success, %FALSE on failure + * #GWin32OutputStream implements #GOutputStream for writing to a + * Windows file handle. + * Note that <filename><gio/gwin32outputstream.h></filename> belongs + * to the Windows-specific GIO interfaces, thus you have to use the + * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it. */ /** - * g_win32_output_stream_get_handle: - * @stream: a #GWin32OutputStream - * - * Return the Windows handle that the stream writes to. + * SECTION:gzcompresso: + * @short_description: Zlib compressor + * @include: gio/gio.h * - * Returns: The handle descriptor of @stream - * Since: 2.26 + * #GZlibCompressor is an implementation of #GConverter that + * compresses data using zlib. */ /** - * g_socket_connectable_enumerate: - * @connectable: a #GSocketConnectable - * - * Creates a #GSocketAddressEnumerator for @connectable. + * SECTION:gzdecompresso: + * @short_description: Zlib decompressor + * @include: gio/gio.h * - * Returns: (transfer full): a new #GSocketAddressEnumerator. - * Since: 2.22 + * #GZlibDecompressor is an implementation of #GConverter that + * decompresses data compressed with zlib. */ @@ -13523,598 +12681,710 @@ /** - * g_settings_get_string: - * @settings: a #GSettings object - * @key: the key to get the value for - * @returns: a newly-allocated string + * g_action_activate: + * @action: a #GAction + * @parameter: (allow-none): the parameter to the activation * - * Gets the value that is stored at @key in @settings. - * A convenience variant of g_settings_get() for strings. - * It is a programmer error to give a @key that isn't specified as - * having a string type in the schema for @settings. + * Activates the action. + * the parameter type given at construction time). If the parameter + * type was %NULL then @parameter must also be %NULL. * - * Since: 2.26 + * Since: 2.28 */ /** - * GCClosure: - * @closure: the #GClosure - * @callback: the callback function + * g_action_get_enabled: + * @action: a #GAction * - * A #GCClosure is a specialization of #GClosure for C function callbacks. + * Checks if @action is currently enabled. + * An action must be enabled in order to be activated or in order to + * have its state changed from outside callers. + * + * Returns: whether the action is enabled + * Since: 2.28 */ /** - * GWin32InputStream: + * g_action_get_name: + * @action: a #GAction * - * Implements #GInputStream for reading from selectable Windows file handles + * Queries the name of @action. + * + * Returns: the name of the action + * Since: 2.28 */ /** - * G_MARKUP_ERROR: + * g_action_get_parameter_type: + * @action: a #GAction * - * Error domain for markup parsing. - * Errors in this domain will be from the #GMarkupError enumeration. - * See #GError for information on error domains. + * Queries the type of the parameter that must be given when activating + * When activating the action using g_action_activate(), the #GVariant + * given to that function must be of the type returned by this function. + * In the case that this function returns %NULL, you must not give any + * #GVariant, but %NULL instead. + * + * Returns: (allow-none): the parameter type + * Since: 2.28 */ /** - * g_settings_get_boolean: - * @settings: a #GSettings object - * @key: the key to get the value for - * @returns: a boolean + * g_action_get_state: + * @action: a #GAction * - * Gets the value that is stored at @key in @settings. - * A convenience variant of g_settings_get() for booleans. - * It is a programmer error to give a @key that isn't specified as - * having a boolean type in the schema for @settings. + * Queries the current state of @action. + * If the action is not stateful then %NULL will be returned. If the + * action is stateful then the type of the return value is the type + * given by g_action_get_state_type(). + * The return value (if non-%NULL) should be freed with + * g_variant_unref() when it is no longer required. * - * Since: 2.26 + * Returns: (transfer full): the current state of the action + * Since: 2.28 */ /** - * g_desktop_app_info_launch_uris_as_manager: - * @appinfo: a #GDesktopAppInfo - * @uris: (element-type utf8): List of URIs - * @launch_context: a #GAppLaunchContext - * @spawn_flags: #GSpawnFlags, used for each process - * @user_setup: (scope call): a #GSpawnChildSetupFunc, used once for each process. - * @user_setup_data: (closure user_setup): User data for @user_setup - * @pid_callback: (scope call): Callback for child processes - * @pid_callback_data: (closure pid_callback): User data for @callback - * @error: a #GError + * g_action_get_state_hint: + * @action: a #GAction * - * This function performs the equivalent of g_app_info_launch_uris(), - * but is intended primarily for operating system components that - * launch applications. Ordinary applications should use - * g_app_info_launch_uris(). - * In contrast to g_app_info_launch_uris(), all processes created will - * always be run directly as children as if by the UNIX fork()/exec() - * calls. - * This guarantee allows additional control over the exact environment - * of the child processes, which is provided via a setup function - * semantics of the @setup function. + * Requests a hint about the valid range of values for the state of + * If %NULL is returned it either means that the action is not stateful + * or that there is no hint about the valid range of values for the + * state of the action. + * If a #GVariant array is returned then each item in the array is a + * returned then the tuple specifies the inclusive lower and upper bound + * of valid values for the state. + * In any case, the information is merely a hint. It may be possible to + * have a state value outside of the hinted range and setting a value + * within the range may fail. + * The return value (if non-%NULL) should be freed with + * g_variant_unref() when it is no longer required. + * + * Possible value for the state. if a #gvariant pair (ie: two-tuple) is + * Returns: (transfer full): the state range hint + * Since: 2.28 */ /** - * g_signal_connect_swapped: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. + * g_action_get_state_type: + * @action: a #GAction * - * Connects a #GCallback function to a signal for a particular object. - * The instance on which the signal is emitted and @data will be swapped when - * calling the handler. + * Queries the type of the state of @action. + * g_action_new_stateful()) then this function returns the #GVariantType + * of the state. This is the type of the initial value given as the + * state. All calls to g_action_set_state() must give a #GVariant of + * this type and g_action_get_state() will return a #GVariant of the + * same type. + * this function will return %NULL. In that case, g_action_get_state() + * will return %NULL and you must not call g_action_set_state(). * - * Returns: the handler id + * If the action is stateful (ie: was created with + * If the action is not stateful (ie: created with g_action_new()) then + * Returns: (allow-none): the state type, if the action is stateful + * Since: 2.28 */ /** - * g_dbus_connection_signal_unsubscribe: - * @connection: A #GDBusConnection. - * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe(). + * g_action_group_action_added: + * @action_group: a #GActionGroup + * @action_name: the name of an action in the group * - * Unsubscribes from signals. + * Emits the #GActionGroup::action-added signal on @action_group. + * This function should only be called by #GActionGroup implementations. * - * Since: 2.26 + * Since: 2.28 */ /** - * g_emblemed_icon_clear_emblems: - * @emblemed: a #GEmblemedIcon + * g_action_group_action_enabled_changed: + * @action_group: a #GActionGroup + * @action_name: the name of an action in the group + * @enabled: whether or not the action is now enabled * - * Removes all the emblems from @icon. + * Emits the #GActionGroup::action-enabled-changed signal on @action_group. + * This function should only be called by #GActionGroup implementations. * * Since: 2.28 */ /** - * G_DBUS_ERROR: + * g_action_group_action_removed: + * @action_group: a #GActionGroup + * @action_name: the name of an action in the group * - * Error domain for errors generated by a remote message bus. Errors - * in this domain will be from the #GDBusError enumeration. See - * #GError for more information on error domains. - * Note that errors in this error domain is intended only for - * returning errors from a remote message bus process. Errors - * generated locally in-process by e.g. #GDBusConnection is from the - * %G_IO_ERROR domain. + * Emits the #GActionGroup::action-removed signal on @action_group. + * This function should only be called by #GActionGroup implementations. * - * Since: 2.26 + * Since: 2.28 */ /** - * GSocketControlMessage: + * g_action_group_action_state_changed: + * @action_group: a #GActionGroup + * @action_name: the name of an action in the group + * @state: the new state of the named action * - * Base class for socket-type specific control messages that can be sent and - * received over #GSocket. + * Emits the #GActionGroup::action-state-changed signal on @action_group. + * This function should only be called by #GActionGroup implementations. + * + * Since: 2.28 */ /** - * G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK: + * g_action_group_activate_action: + * @action_group: a #GActionGroup + * @action_name: the name of the action to activate + * @parameter: (allow-none): parameters to the activation * - * A key in the "standard" namespace for checking if the file is a symlink. - * Typically the actual type is something else, if we followed the symlink - * to get the type. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * Activate the named action within @action_group. + * If the action is expecting a parameter, then the correct type of + * parameter must be given as @parameter. If the action is expecting no + * parameters then @parameter must be %NULL. See + * g_action_group_get_parameter_type(). + * + * Since: 2.28 */ /** - * g_dbus_message_set_flags: - * @message: A #GDBusMessage. - * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). + * g_action_group_change_action_state: + * @action_group: a #GActionGroup + * @action_name: the name of the action to request the change on + * @value: the new state * - * Sets the flags to set on @message. + * Request for the state of the named action within @action_group to be + * changed to @value. + * The action must be stateful and @value must be of the correct type. + * See g_action_group_get_state_type(). + * This call merely requests a change. The action may refuse to change + * its state or may change its state to something other than @value. + * See g_action_group_get_state_hint(). + * If the @value GVariant is floating, it is consumed. * - * Since: 2.26 + * Since: 2.28 */ /** - * g_file_append_to_async: - * @file: input #GFile. - * @flags: a set of #GFileCreateFlags. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * g_action_group_get_action_enabled: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * Asynchronously opens @file for appending. - * For more details, see g_file_append_to() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_append_to_finish() to get the result of the operation. + * Checks if the named action within @action_group is currently enabled. + * An action must be enabled in order to be activated or in order to + * have its state changed from outside callers. + * + * Returns: whether or not the action is currently enabled + * Since: 2.28 */ /** - * GUnixMountEntry: + * g_action_group_get_action_parameter_type: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>). - * This corresponds roughly to a mtab entry. + * Queries the type of the parameter that must be given when activating + * the named action within @action_group. + * When activating the action using g_action_group_activate(), the + * #GVariant given to that function must be of the type returned by this + * function. + * In the case that this function returns %NULL, you must not give any + * #GVariant, but %NULL instead. + * The parameter type of a particular action will never change but it is + * possible for an action to be removed and for a new action to be added + * with the same name but a different parameter type. + * + * Returns: the parameter type + * Since: 2.28 */ /** - * g_dbus_message_set_sender: - * @message: A #GDBusMessage. - * @value: The value to set. + * g_action_group_get_action_state: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. + * Queries the current state of the named action within @action_group. + * If the action is not stateful then %NULL will be returned. If the + * action is stateful then the type of the return value is the type + * given by g_action_group_get_state_type(). + * The return value (if non-%NULL) should be freed with + * g_variant_unref() when it is no longer required. * - * Since: 2.26 + * Returns: (allow-none): the current state of the action + * Since: 2.28 */ /** - * SECTION:gtlsserverconnectio: - * @short_description: TLS server-side connection - * @include: gio/gio.h + * g_action_group_get_action_state_hint: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * #GTlsServerConnection is the server-side subclass of #GTlsConnection, - * representing a server-side TLS connection. + * Requests a hint about the valid range of values for the state of the + * named action within @action_group. + * If %NULL is returned it either means that the action is not stateful + * or that there is no hint about the valid range of values for the + * state of the action. + * If a #GVariant array is returned then each item in the array is a + * returned then the tuple specifies the inclusive lower and upper bound + * of valid values for the state. + * In any case, the information is merely a hint. It may be possible to + * have a state value outside of the hinted range and setting a value + * within the range may fail. + * The return value (if non-%NULL) should be freed with + * g_variant_unref() when it is no longer required. * + * Possible value for the state. if a #gvariant pair (ie: two-tuple) is + * Returns: (transfer full): the state range hint * Since: 2.28 */ /** - * g_dbus_proxy_call_sync: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * g_action_group_get_action_state_type: + * @action_group: a #GActionGroup + * @action_name: the name of the action to query * - * Synchronously invokes the @method_name method on @proxy. - * If @method_name contains any dots, then @name is split into interface and - * method name parts. This allows using @proxy for invoking methods on - * other interfaces. - * If the #GDBusConnection associated with @proxy is disconnected then - * the operation will fail with %G_IO_ERROR_CLOSED. If - * %G_IO_ERROR_CANCELLED. If @parameters contains a value not - * compatible with the D-Bus protocol, the operation fails with - * %G_IO_ERROR_INVALID_ARGUMENT. - * If the @parameters #GVariant is floating, it is consumed. This allows - * convenient 'inline' use of g_variant_new(), e.g.: - * |[ - * g_dbus_proxy_call_sync (proxy, - * "TwoStrings", - * g_variant_new ("(ss)", - * "Thing One", - * "Thing Two"), - * G_DBUS_CALL_FLAGS_NONE, - * -1, - * NULL, - * &error); - * ]| - * The calling thread is blocked until a reply is received. See - * g_dbus_proxy_call() for the asynchronous version of this - * method. - * return values. Free with g_variant_unref(). + * Queries the type of the state of the named action within + * If the action is stateful then this function returns the + * #GVariantType of the state. All calls to g_action_group_set_state() + * must give a #GVariant of this type and g_action_group_get_state() + * will return a #GVariant of the same type. + * If the action is not stateful then this function will return %NULL. + * In that case, g_action_group_get_state() will return %NULL and you + * must not call g_action_group_set_state(). + * The state type of a particular action will never change but it is + * possible for an action to be removed and for a new action to be added + * with the same name but a different state type. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * Since: 2.26 + * Returns: (transfer full): the state type, if the action is stateful + * Since: 2.28 */ /** - * GDBusProxy:g-object-path: + * g_action_group_has_action: + * @action_group: a #GActionGroup + * @action_name: the name of the action to check for * - * The object path the proxy is for. + * Checks if the named action exists within @action_group. * - * Since: 2.26 + * Returns: whether the named action exists + * Since: 2.28 */ /** - * G_TYPE_FROM_INSTANCE: - * @instance: Location of a valid #GTypeInstance structure. + * g_action_group_list_actions: + * @action_group: a #GActionGroup * - * Get the type identifier from a given @instance structure. - * This macro should only be used in type implementations. + * Lists the actions contained within @action_group. + * The caller is responsible for freeing the list with g_strfreev() when + * it is no longer required. + * actions in the groupb * - * Returns: the #GType + * Returns: (transfer full): a %NULL-terminated array of the names of the + * Since: 2.28 */ /** - * g_file_info_set_is_symlink: - * @info: a #GFileInfo. - * @is_symlink: a #gboolean. + * g_action_set_state: + * @action: a #GAction + * @value: the new state * - * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. - * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. + * Request for the state of @action to be changed to @value. + * The action must be stateful and @value must be of the correct type. + * See g_action_get_state_type(). + * This call merely requests a change. The action may refuse to change + * its state or may change its state to something other than @value. + * See g_action_get_state_hint(). + * If the @value GVariant is floating, it is consumed. + * + * Since: 2.28 */ /** - * G_IS_PARAM_SPEC_DOUBLE: - * @pspec: a valid #GParamSpec instance + * g_alloca: + * @size: number of bytes to allocate. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. + * Allocates @size bytes on the stack; these bytes will be freed when the current + * stack frame is cleaned up. This macro essentially just wraps the alloca() + * function present on most UNIX variants. + * Thus it provides the same advantages and pitfalls as alloca(): + * <variablelist> + * <varlistentry><term></term><listitem><para> + * + alloca() is very fast, as on most systems it's implemented by just adjusting + * the stack pointer register. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * + It doesn't cause any memory fragmentation, within its scope, separate alloca() + * blocks just build up and are released together at function end. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * - Allocation sizes have to fit into the current stack frame. For instance in a + * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, + * so be sparse with alloca() uses. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * - Allocation failure due to insufficient stack space is not indicated with a %NULL + * return like e.g. with malloc(). Instead, most systems probably handle it the same + * way as out of stack space situations from infinite function recursion, i.e. + * with a segmentation fault. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays. + * Stack space allocated with alloca() in the same scope as a variable sized array + * will be freed together with the variable sized array upon exit of that scope, and + * not upon exit of the enclosing function scope. + * </para></listitem></varlistentry> + * </variablelist> * - * Returns: %TRUE on success. + * Returns: space for @size bytes, allocated on the stack */ /** - * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE: + * g_app_info_add_supports_type: + * @appinfo: a #GAppInfo. + * @content_type: a string. + * @error: a #GError. * - * A key in the "access" namespace for checking deletion privileges. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - * This attribute will be %TRUE if the user is able to delete the file. + * Adds a content type to the application information to indicate the + * application is capable of opening files with the given content type. + * + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_file_info_set_attribute_mask: - * @info: a #GFileInfo. - * @mask: a #GFileAttributeMatcher. + * g_app_info_can_delete: + * @appinfo: a #GAppInfo * - * Sets @mask on @info to match specific attribute types. + * Obtains the information whether the #GAppInfo can be deleted. + * See g_app_info_delete(). + * + * Returns: %TRUE if @appinfo can be deleted + * Since: 2.20 */ /** - * GIOStream: + * g_app_info_can_remove_supports_type: + * @appinfo: a #GAppInfo. * - * Base class for read-write streams. + * Checks if a supported content type can be removed from an application. + * content types from a given @appinfo, %FALSE if not. + * + * Returns: %TRUE if it is possible to remove supported */ /** - * GSocketMsgFlags: - * @G_SOCKET_MSG_NONE: No flags. - * @G_SOCKET_MSG_OOB: Request to send/receive out of band data. - * @G_SOCKET_MSG_PEEK: Read data from the socket without removing it from the queue. - * @G_SOCKET_MSG_DONTROUTE: Don't use a gateway to send out the packet, only send to hosts on directly connected networks. + * g_app_info_create_from_commandline: + * @commandline: the commandline to use + * @application_name: (allow-none): the application name, or %NULL to use @commandline + * @flags: flags that can specify details of the created #GAppInfo + * @error: a #GError location to store the error occuring, %NULL to ignore. * - * Flags used in g_socket_receive_message() and g_socket_send_message(). - * The flags listed in the enum are some commonly available flags, but the - * values used for them are the same as on the platform, and any other flags - * are passed in/out as is. So to use a platform specific flag, just include - * the right system header and pass in the flag. + * Creates a new #GAppInfo from the given information. * - * Since: 2.22 + * Returns: (transfer full): new #GAppInfo for given command. */ /** - * g_dbus_is_member_name: - * @string: The string to check. + * g_app_info_delete: + * @appinfo: a #GAppInfo * - * Checks if @string is a valid D-Bus member (e.g. signal or method) name. + * Tries to delete a #GAppInfo. + * On some platforms, there may be a difference between user-defined + * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which + * cannot. See g_app_info_can_delete(). * - * Returns: %TRUE if valid, %FALSE otherwise. - * Since: 2.26 + * Virtual: do_delete + * Returns: %TRUE if @appinfo has been deleted + * Since: 2.20 */ /** - * G_TYPE_PARAM_ULONG: + * g_app_info_dup: + * @appinfo: a #GAppInfo. * - * The #GType of #GParamSpecULong. + * Creates a duplicate of a #GAppInfo. + * + * Returns: (transfer full): a duplicate of @appinfo. */ /** - * g_file_query_default_handler: - * @file: a #GFile to open. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * g_app_info_equal: + * @appinfo1: the first #GAppInfo. + * @appinfo2: the second #GAppInfo. * - * Returns the #GAppInfo that is registered as the default - * application to handle the file specified by @file. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * When you are done with it, release it with g_object_unref() + * Checks if two #GAppInfo<!-- -->s are equal. * - * Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors. + * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. */ /** - * GDBusProxy:g-bus-type: + * g_app_info_get_all: * - * If this property is not %G_BUS_TYPE_NONE, then - * #GDBusProxy:g-connection must be %NULL and will be set to the - * #GDBusConnection obtained by calling g_bus_get() with the value - * of this property. + * Gets a list of all of the applications currently registered + * on this system. + * For desktop files, this includes applications that have + * <literal>NoDisplay=true</literal> set or are excluded from + * display by means of <literal>OnlyShowIn</literal> or + * <literal>NotShowIn</literal>. See g_app_info_should_show(). + * The returned list does not include applications which have + * the <literal>Hidden</literal> key set. * - * Since: 2.26 + * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s. */ /** - * g_dbus_connection_get_peer_credentials: - * @connection: A #GDBusConnection. + * g_app_info_get_all_for_type: + * @content_type: the content type to find a #GAppInfo for * - * Gets the credentials of the authenticated peer. This will always - * return %NULL unless @connection acted as a server - * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) - * when set up and the client passed credentials as part of the - * authentication process. - * In a message bus setup, the message bus is always the server and - * each application is a client. So this method will always return - * %NULL for message bus clients. - * this object, it is owned by @connection. + * Gets a list of all #GAppInfos for a given content type. + * for given @content_type or %NULL on error. * - * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free - * Since: 2.26 + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos */ /** - * G_FILE_ATTRIBUTE_UNIX_INODE: + * g_app_info_get_commandline: + * @appinfo: a #GAppInfo * - * A key in the "unix" namespace for getting the inode of the file. - * This attribute is only available for UNIX file systems. Corresponding - * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + * Gets the commandline with which the application will be + * started. + * or %NULL if this information is not available + * + * Returns: a string containing the @appinfo's commandline, + * Since: 2.20 */ /** - * g_file_info_set_icon: - * @info: a #GFileInfo. - * @icon: a #GIcon. + * g_app_info_get_default_for_type: + * @content_type: the content type to find a #GAppInfo for + * @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs * - * Sets the icon for a given #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_ICON. + * Gets the #GAppInfo that corresponds to a given content type. + * %NULL on error. + * + * Returns: (transfer full): #GAppInfo for given @content_type or */ /** - * g_socket_new_from_fd: - * @fd: a native socket file descriptor. - * @error: #GError for error reporting, or %NULL to ignore. + * g_app_info_get_default_for_uri_scheme: + * @uri_scheme: a string containing a URI scheme. * - * Creates a new #GSocket from a native file descriptor - * or winsock SOCKET handle. - * This reads all the settings from the file descriptor so that - * all properties should work. Note that the file descriptor - * will be set to non-blocking mode, independent on the blocking - * mode of the #GSocket. - * Free the returned object with g_object_unref(). + * Gets the default application for launching applications + * using this URI scheme. A URI scheme is the initial part + * of the URI, up to but not including the ':', e.g. "http", + * "ftp" or "sip". * - * Returns: a #GSocket or %NULL on error. - * Since: 2.22 + * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. */ /** - * g_app_launch_context_launch_failed: - * @context: a #GAppLaunchContext. - * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). + * g_app_info_get_description: + * @appinfo: a #GAppInfo. * - * Called when an application has failed to launch, so that it can cancel - * the application startup notification started in g_app_launch_context_get_startup_notify_id(). + * Gets a human-readable description of an installed application. + * application @appinfo, or %NULL if none. + * + * Returns: a string containing a description of the */ /** - * G_VARIANT_TYPE_MAYBE: + * g_app_info_get_display_name: + * @appinfo: a #GAppInfo. * - * An indefinite type that is a supertype of every maybe type. + * Gets the display name of the application. The display name is often more + * descriptive to the user than the name itself. + * no display name is available. + * + * Returns: the display name of the application for @appinfo, or the name if + * Since: 2.24 */ /** - * g_socket_get_blocking: - * @socket: a #GSocket. + * g_app_info_get_executable: + * @appinfo: a #GAppInfo * - * Gets the blocking mode of the socket. For details on blocking I/O, - * see g_socket_set_blocking(). + * Gets the executable's name for the installed application. + * binaries name * - * Returns: %TRUE if blocking I/O is used, %FALSE otherwise. - * Since: 2.22 + * Returns: a string containing the @appinfo's application */ /** - * G_FILE_ATTRIBUTE_THUMBNAIL_PATH: + * g_app_info_get_fallback_for_type: + * @content_type: the content type to find a #GAppInfo for * - * A key in the "thumbnail" namespace for getting the path to the thumbnail - * image. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + * Gets a list of fallback #GAppInfos for a given content type, i.e. + * those applications which claim to support the given content type + * by MIME type subclassing and not directly. + * for given @content_type or %NULL on error. + * + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * Since: 2.28 */ /** - * g_buffered_input_stream_set_buffer_size: - * @stream: a #GBufferedInputStream - * @size: a #gsize + * g_app_info_get_icon: + * @appinfo: a #GAppInfo. * - * Sets the size of the internal buffer of @stream to @size, or to the - * size of the contents of the buffer. The buffer can never be resized - * smaller than its current contents. + * Gets the icon for the application. + * + * Returns: (transfer none): the default #GIcon for @appinfo. */ /** - * g_action_group_action_enabled_changed: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group - * @enabled: whether or not the action is now enabled + * g_app_info_get_id: + * @appinfo: a #GAppInfo. * - * Emits the #GActionGroup::action-enabled-changed signal on @action_group. - * This function should only be called by #GActionGroup implementations. + * Gets the ID of an application. An id is a string that + * identifies the application. The exact format of the id is + * platform dependent. For instance, on Unix this is the + * desktop file id from the xdg menu specification. + * Note that the returned ID may be %NULL, depending on how + * the @appinfo has been constructed. * - * Since: 2.28 + * Returns: a string containing the application's ID. */ /** - * g_input_stream_read: - * @stream: a #GInputStream. - * @buffer: 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 - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occuring, or %NULL to ignore + * g_app_info_get_name: + * @appinfo: a #GAppInfo. * - * Tries to read @count bytes from the stream into the buffer starting at - * If count is zero returns zero and does nothing. A value of @count - * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * On success, the number of bytes read into the buffer is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. near the end of a file. Zero is returned on end of file - * (or if @count is zero), but never otherwise. - * If @cancellable is not NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * On error -1 is returned and @error is set accordingly. + * Gets the installed name of the application. * - * Returns: Number of bytes read, or -1 on error + * Returns: the name of the application for @appinfo. */ /** - * g_themed_icon_prepend_name: - * @icon: a #GThemedIcon - * @iconname: name of icon to prepend to list of icons from within @icon. + * g_app_info_get_recommended_for_type: + * @content_type: the content type to find a #GAppInfo for * - * Prepend a name to the list of icons from within @icon. - * <note><para> - * Note that doing so invalidates the hash computed by prior calls - * to g_icon_hash(). - * </para></note> + * Gets a list of recommended #GAppInfos for a given content type, i.e. + * those applications which claim to support the given content type exactly, + * and not by MIME type subclassing. + * Note that the first application of the list is the last used one, i.e. + * the last one for which #g_app_info_set_as_last_used_for_type has been + * called. + * for given @content_type or %NULL on error. * - * Since: 2.18 + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * Since: 2.28 */ /** - * SECTION:gconverte: - * @short_description: Data conversion interface - * @include: gio/gio.h - * @see_also: #GInputStream, #GOutputStream + * g_app_info_launch: + * @appinfo: a #GAppInfo + * @files: (element-type GFile): a #GList of #GFile objects + * @launch_context: (allow-none): a #GAppLaunchContext or %NULL + * @error: a #GError * - * #GConverter is implemented by objects that convert - * binary data in various ways. The conversion can be - * stateful and may fail at any place. - * compression, decompression and regular expression - * replace. + * Launches the application. Passes @files to the launched application + * as arguments, using the optional @launch_context to get information + * about the details of the launcher (like what screen it is on). + * On error, @error will be set accordingly. + * To launch the application without arguments pass a %NULL @files list. + * Note that even if the launch is successful the application launched + * can fail to start if it runs into problems during startup. There is + * no way to detect this. + * Some URIs can be changed when passed through a GFile (for instance + * unsupported uris with strange formats like mailto:), so if you have + * a textual uri you want to pass in as argument, consider using + * g_app_info_launch_uris() instead. + * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar> + * environment variable with the path of the launched desktop file and + * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process + * id of the launched process. This can be used to ignore + * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited + * by further processes. The <envar>DISPLAY</envar> and + * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also + * set, based on information provided in @launch_context. * - * Some example conversions are: character set conversion, - * Since: 2.24 + * Returns: %TRUE on successful launch, %FALSE otherwise. */ /** - * G_TYPE_CHECK_VALUE_TYPE: - * @value: a #GValue - * @g_type: The type to be checked. + * g_app_info_launch_default_for_uri: + * @uri: the uri to show + * @launch_context: (allow-none): an optional #GAppLaunchContext. + * @error: a #GError. * - * Checks if @value has been initialized to hold values - * of type @g_type. - * This macro should only be used in type implementations. + * Utility function that launches the default application + * registered to handle the specified uri. Synchronous I/O + * is done on the uri to detect the type of the file if + * required. * - * Returns: %TRUE on success. + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_settings_get_enum: - * @settings: a #GSettings object - * @key: the key to get the value for - * @returns: the enum value + * g_app_info_launch_uris: + * @appinfo: a #GAppInfo + * @uris: (element-type utf8): a #GList containing URIs to launch. + * @launch_context: (allow-none): a #GAppLaunchContext or %NULL + * @error: a #GError * - * Gets the value that is stored in @settings for @key and converts it - * to the enum value that it represents. - * In order to use this function the type of the value must be a string - * and it must be marked in the schema file as an enumerated type. - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or is not marked as an enumerated type. - * If the value stored in the configuration database is not a valid - * value for the enumerated type then this function will return the - * default value. + * Launches the application. Passes @uris to the launched application + * as arguments, using the optional @launch_context to get information + * about the details of the launcher (like what screen it is on). + * On error, @error will be set accordingly. + * To lauch the application without arguments pass a %NULL @uris list. + * Note that even if the launch is successful the application launched + * can fail to start if it runs into problems during startup. There is + * no way to detect this. * - * Since: 2.26 + * Returns: %TRUE on successful launch, %FALSE otherwise. */ /** - * G_VOLUME_MONITOR_EXTENSION_POINT_NAME: + * g_app_info_remove_supports_type: + * @appinfo: a #GAppInfo. + * @content_type: a string. + * @error: a #GError. * - * Extension point for volume monitor functionality. - * See <link linkend="extending-gio">Extending GIO</link>. + * Removes a supported type from an application, if possible. + * + * Returns: %TRUE on success, %FALSE on error. */ @@ -14132,2414 +13402,2612 @@ /** - * g_dbus_proxy_get_name: - * @proxy: A #GDBusProxy. + * g_app_info_set_as_default_for_extension: + * @appinfo: a #GAppInfo. + * @extension: a string containing the file extension (without the dot). + * @error: a #GError. * - * Gets the name that @proxy was constructed for. + * Sets the application as the default handler for the given file extension. * - * Returns: A string owned by @proxy. Do not free. - * Since: 2.26 + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_file_info_get_name: - * @info: a #GFileInfo. + * g_app_info_set_as_default_for_type: + * @appinfo: a #GAppInfo. + * @content_type: the content type. + * @error: a #GError. * - * Gets the name for a file. + * Sets the application as the default handler for a given type. * - * Returns: a string containing the file name. + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_mount_operation_get_anonymous: - * @op: a #GMountOperation. + * g_app_info_set_as_last_used_for_type: + * @appinfo: a #GAppInfo. + * @content_type: the content type. + * @error: a #GError. * - * Check to see whether the mount operation is being used - * for an anonymous user. + * Sets the application as the last used application for a given type. + * This will make the application appear as first in the list returned by + * #g_app_info_get_recommended_for_type, regardless of the default application + * for that content type. * - * Returns: %TRUE if mount operation is anonymous. + * Returns: %TRUE on success, %FALSE on error. */ /** - * g_socket_is_connected: - * @socket: a #GSocket. + * g_app_info_should_show: + * @appinfo: a #GAppInfo. * - * Check whether the socket is connected. This is only useful for - * connection-oriented sockets. + * Checks if the application info should be shown in menus that + * list available applications. * - * Returns: %TRUE if socket is connected, %FALSE otherwise. - * Since: 2.22 + * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise. */ /** - * g_application_hold: - * @application: a #GApplication + * g_app_info_supports_files: + * @appinfo: a #GAppInfo. * - * Increases the use count of @application. - * Use this function to indicate that the application has a reason to - * continue to run. For example, g_application_hold() is called by GTK+ - * when a toplevel window is on the screen. - * To cancel the hold, call g_application_release(). - */ - - -/** - * GParamSpecClass: - * @g_type_class: the parent class - * @value_type: the #GValue type for this parameter - * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class. - * @value_set_default: Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default(). - * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_set_validate(). - * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp(). + * Checks if the application accepts files as arguments. * - * The class structure for the <structname>GParamSpec</structname> type. - * Normally, <structname>GParamSpec</structname> classes are filled by - * g_param_type_register_static(). + * Returns: %TRUE if the @appinfo supports files. */ /** - * g_socket_get_remote_address: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. + * g_app_info_supports_uris: + * @appinfo: a #GAppInfo. * - * Try to get the remove address of a connected socket. This is only - * useful for connection oriented sockets that have been connected. - * Free the returned object with g_object_unref(). + * Checks if the application supports reading files and directories from URIs. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Since: 2.22 + * Returns: %TRUE if the @appinfo supports URIs. */ /** - * GParamSpecGType: - * @parent_instance: private #GParamSpec portion - * @is_a_type: a #GType whose subtypes can occur as values + * g_app_launch_context_get_display: + * @context: a #GAppLaunchContext + * @info: a #GAppInfo + * @files: (element-type GFile): a #GList of #GFile objects * - * A #GParamSpec derived structure that contains the meta data for #GType properties. + * Gets the display string for the @context. This is used to ensure new + * applications are started on the same display as the launching + * application, by setting the <envar>DISPLAY</envar> environment variable. * - * Since: 2.10 + * Returns: a display string for the display. */ /** - * g_dbus_message_new_method_reply: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * g_app_launch_context_get_startup_notify_id: + * @context: a #GAppLaunchContext + * @info: a #GAppInfo + * @files: (element-type GFile): a #GList of of #GFile objects * - * Creates a new #GDBusMessage that is a reply to @method_call_message. + * Initiates startup notification for the application and returns the + * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation, + * if supported. + * Startup notification IDs are defined in the <ulink + * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"> + * FreeDesktop.Org Startup Notifications standard</ulink>. + * not supported. * - * Returns: (transfer full): #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * Returns: a startup notification ID for the application, or %NULL if */ /** - * g_application_register: - * @application: a #GApplication - * @cancellable: a #GCancellable, or %NULL - * @error: a pointer to a NULL #GError, or %NULL - * @returns: %TRUE if registration succeeded - * - * Attempts registration of the application. - * This is the point at which the application discovers if it is the - * primary instance or merely acting as a remote for an already-existing - * primary instance. - * If the application has already been registered then %TRUE is - * returned with no work performed. - * The #GApplication::startup signal is emitted if registration succeeds - * and @application is the primary instance. - * In the event of an error (such as @cancellable being cancelled, or a - * failure to connect to the session bus), %FALSE is returned and @error - * is set appropriately. - * instance is or is not the primary instance of the application. See - * g_application_get_is_remote() for that. + * g_app_launch_context_launch_failed: + * @context: a #GAppLaunchContext. + * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). * - * Note: the return value of this function is not an indicator that this - * Since: 2.28 + * Called when an application has failed to launch, so that it can cancel + * the application startup notification started in g_app_launch_context_get_startup_notify_id(). */ /** - * g_emblemed_icon_get_icon: - * @emblemed: a #GEmblemedIcon + * g_app_launch_context_new: * - * Gets the main icon for @emblemed. + * Creates a new application launch context. This is not normally used, + * instead you instantiate a subclass of this, such as #GdkAppLaunchContext. * - * Returns: (transfer none): a #GIcon that is owned by @emblemed - * Since: 2.18 + * Returns: a #GAppLaunchContext. */ /** - * g_signal_connect: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. + * g_application_activate: + * @application: a #GApplication * - * Connects a #GCallback function to a signal for a particular object. - * The handler will be called before the default handler of the signal. + * Activates the application. + * In essence, this results in the #GApplication::activate() signal being + * emitted in the primary instance. + * The application must be registered before calling this function. * - * Returns: the handler id + * Since: 2.28 */ /** - * g_file_info_set_attribute_object: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a #GObject. + * g_application_command_line_get_arguments: + * @cmdline: a #GApplicationCommandLine + * @argc: (out): the length of the arguments array, or %NULL * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * GToggleNotify: - * @data: Callback data passed to g_object_add_toggle_ref() - * @object: The object on which g_object_add_toggle_ref() was called. - * @is_last_ref: %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references. + * Gets the list of arguments that was passed on the command line. + * The strings in the array may contain non-utf8 data. + * The return value is %NULL-terminated and should be freed using + * g_strfreev(). + * containing the arguments (the argv) * - * A callback function used for notification when the state - * of a toggle reference changes. See g_object_add_toggle_ref(). + * Returns: (array length=argc) (transfer full): the string array + * Since: 2.28 */ /** - * G_TYPE_PARAM_INT64: + * g_application_command_line_get_cwd: + * @cmdline: a #GApplicationCommandLine * - * The #GType of #GParamSpecInt64. + * Gets the working directory of the command line invocation. The + * string may contain non-utf8 data. + * It is possible that the remote application did not send a working + * directory, so this may be %NULL. + * The return value should not be modified or freed and is valid for as + * long as @cmdline exists. + * + * Returns: the current directory, or %NULL + * Since: 2.28 */ /** - * GDBusServer:authentication-observer: + * g_application_command_line_get_environ: + * @cmdline: a #GApplicationCommandLine * - * A #GDBusAuthObserver object to assist in the authentication process or %NULL. + * Gets the contents of the 'environ' variable of the command line + * invocation, as would be returned by g_get_environ(). The strings may + * contain non-utf8 data. + * The remote application usually does not send an environment. Use + * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag + * set it is possible that the environment is still not available (due + * to invocation messages from other applications). + * The return value should not be modified or freed and is valid for as + * long as @cmdline exists. + * strings, or %NULL if they were not sent * - * Since: 2.26 + * Returns: (array zero-terminated=1) (transfer none): the environment + * Since: 2.28 */ /** - * GTlsConnection:certificate: + * g_application_command_line_get_exit_status: + * @cmdline: a #GApplicationCommandLine * - * The connection's certificate; see - * g_tls_connection_set_certificate(). + * Gets the exit status of @cmdline. See + * g_application_command_line_set_exit_status() for more information. * + * Returns: the exit status * Since: 2.28 */ /** - * g_bus_watch_name_on_connection: - * @connection: A #GDBusConnection. - * @name: The name (well-known or unique) to watch. - * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL. - * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: Function for freeing @user_data or %NULL. + * g_application_command_line_get_is_remote: + * @cmdline: a #GApplicationCommandLine * - * Like g_bus_watch_name() but takes a #GDBusConnection instead of a - * #GBusType. - * g_bus_unwatch_name() to stop watching the name. + * Determines if @cmdline represents a remote invocation. * - * Returns: An identifier (never 0) that an be used with - * Since: 2.26 + * Returns: %TRUE if the invocation was remote + * Since: 2.28 */ /** - * g_tls_client_connection_get_server_identity: - * @conn: the #GTlsClientConnection + * g_application_command_line_get_platform_data: + * @cmdline: #GApplicationCommandLine * - * Gets @conn's expected server identity - * expected server identity, or %NULL if the expected identity is not - * known. + * Gets the platform data associated with the invocation of @cmdline. + * This is a #GVariant dictionary containing information about the + * context in which the invocation occured. It typically contains + * information like the current working directory and the startup + * notification ID. + * For local invocation, it will be %NULL. * - * Returns: a #GSocketConnectable describing the + * Returns: the platform data, or %NULL * Since: 2.28 */ /** - * g_action_group_get_action_enabled: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query + * g_application_command_line_getenv: + * @cmdline: a #GApplicationCommandLine + * @name: the environment variable to get * - * Checks if the named action within @action_group is currently enabled. - * An action must be enabled in order to be activated or in order to - * have its state changed from outside callers. + * Gets the value of a particular environment variable of the command + * line invocation, as would be returned by g_getenv(). The strings may + * contain non-utf8 data. + * The remote application usually does not send an environment. Use + * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag + * set it is possible that the environment is still not available (due + * to invocation messages from other applications). + * The return value should not be modified or freed and is valid for as + * long as @cmdline exists. * - * Returns: whether or not the action is currently enabled + * Returns: the value of the variable, or %NULL if unset or unsent * Since: 2.28 */ /** - * g_app_info_should_show: - * @appinfo: a #GAppInfo. + * g_application_command_line_print: + * @cmdline: a #GApplicationCommandLine + * @format: a printf-style format string + * @...: arguments, as per @format * - * Checks if the application info should be shown in menus that - * list available applications. + * Formats a message and prints it using the stdout print handler in the + * invoking process. + * If @cmdline is a local invocation then this is exactly equivalent to + * g_print(). If @cmdline is remote then this is equivalent to calling + * g_print() in the invoking process. * - * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise. + * Since: 2.28 */ /** - * g_proxy_get_default_for_protocol: - * @protocol: the proxy protocol name (e.g. http, socks, etc) + * g_application_command_line_printerr: + * @cmdline: a #GApplicationCommandLine + * @format: a printf-style format string + * @...: arguments, as per @format * - * Lookup "gio-proxy" extension point for a proxy implementation that supports - * specified protocol. - * is not supported. + * Formats a message and prints it using the stderr print handler in the + * invoking process. + * If @cmdline is a local invocation then this is exactly equivalent to + * g_printerr(). If @cmdline is remote then this is equivalent to + * calling g_printerr() in the invoking process. * - * Returns: (transfer full): return a #GProxy or NULL if protocol - * Since: 2.26 + * Since: 2.28 */ /** - * g_dbus_connection_send_message_with_reply_finish: - * @connection: a #GDBusConnection - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply(). - * @error: Return location for error or %NULL. + * g_application_command_line_set_exit_status: + * @cmdline: a #GApplicationCommandLine + * @exit_status: the exit status * - * Finishes an operation started with g_dbus_connection_send_message_with_reply(). - * Note that @error is only set if a local in-process error - * occured. That is to say that the returned #GDBusMessage object may - * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use - * g_dbus_message_to_gerror() to transcode this to a #GError. - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * Sets the exit status that will be used when the invoking process + * exits. + * The return value of the #GApplication::command-line signal is + * passed to this function when the handler returns. This is the usual + * way of setting the exit status. + * In the event that you want the remote invocation to continue running + * and want to decide on the exit status in the future, you can use this + * call. For the case of a remote invocation, the remote process will + * typically exit when the last reference is dropped on @cmdline. The + * exit status of the remote process will be equal to the last value + * that was set with this function. + * In the case that the commandline invocation is local, the situation + * is slightly more complicated. If the commandline invocation results + * increased to a non-zero value) then the application is considered to + * have been 'successful' in a certain sense, and the exit status is + * always zero. If the application use count is zero, though, the exit + * status of the local #GApplicationCommandLine is used. * - * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set. - * Since: 2.26 + * In the mainloop running (ie: because the use-count of the application + * Since: 2.28 */ /** - * SECTION:gunixinputstrea: - * @short_description: Streaming input operations for UNIX file descriptors - * @include: gio/gunixinputstream.h - * @see_also: #GInputStream + * g_application_get_application_id: + * @application: a #GApplication + * @returns: the identifier for @application, owned by @application * - * #GUnixInputStream implements #GInputStream for reading from a - * UNIX file descriptor, including asynchronous operations. The file - * descriptor must be selectable, so it doesn't work with opened files. - * Note that <filename><gio/gunixinputstream.h></filename> belongs - * to the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Gets the unique identifier for @application. + * + * Since: 2.28 */ /** - * GZlibCompressor: + * g_application_get_flags: + * @application: a #GApplication + * @returns: the flags for @application * - * Zlib decompression + * Gets the flags for @application. + * See #GApplicationFlags. + * + * Since: 2.28 */ /** - * g_dbus_server_get_guid: - * @server: A #GDBusServer. + * g_application_get_inactivity_timeout: + * @application: a #GApplication * - * Gets the GUID for @server. + * Gets the current inactivity timeout for the application. + * This is the amount of time (in milliseconds) after the last call to + * g_application_release() before the application stops running. * - * Returns: A D-Bus GUID. Do not free this string, it is owned by @server. - * Since: 2.26 + * Returns: the timeout, in milliseconds + * Since: 2.28 */ /** - * g_file_get_basename: - * @file: input #GFile. + * g_application_get_is_registered: + * @application: a #GApplication + * @returns: %TRUE if @application is registered * - * Gets the base name (the last component of the path) for a given #GFile. - * If called for the top level of a system (such as the filesystem root - * or a uri like sftp://host/) it will return a single directory separator - * (and on Windows, possibly a drive letter). - * The base name is a byte string (*not* UTF-8). It has no defined encoding - * or rules other than it may not contain zero bytes. If you want to use - * filenames in a user interface you should use the display name that you - * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME - * attribute with g_file_query_info(). - * This call does no blocking i/o. - * if given #GFile is invalid. The returned string should be - * freed with g_free() when no longer needed. + * Checks if @application is registered. + * An application is registered if g_application_register() has been + * successfully called. * - * Returns: string containing the #GFile's base name, or %NULL + * Since: 2.28 */ /** - * g_volume_get_drive: - * @volume: a #GVolume. + * g_application_get_is_remote: + * @application: a #GApplication + * @returns: %TRUE if @application is remote * - * Gets the drive for the @volume. - * The returned object should be unreffed with g_object_unref() - * when no longer needed. + * Checks if @application is remote. + * If @application is remote then it means that another instance of + * application already exists (the 'primary' instance). Calls to + * perform actions on @application will result in the actions being + * performed by the primary instance. + * The value of this property can not be accessed before + * g_application_register() has been called. See + * g_application_get_is_registered(). * - * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive. + * Since: 2.28 */ /** - * GUnixMountMonitor::mountpoints-changed: - * @monitor: the object on which the signal is emitted + * g_application_hold: + * @application: a #GApplication * - * Emitted when the unix mount points have changed. + * Increases the use count of @application. + * Use this function to indicate that the application has a reason to + * continue to run. For example, g_application_hold() is called by GTK+ + * when a toplevel window is on the screen. + * To cancel the hold, call g_application_release(). */ /** - * GFileAttributeInfo: - * @name: the name of the attribute. - * @type: the #GFileAttributeType type of the attribute. - * @flags: a set of #GFileAttributeInfoFlags. + * g_application_id_is_valid: + * @application_id: a potential application identifier + * @returns: %TRUE if @application_id is valid * - * Information about a specific attribute. + * Checks if @application_id is a valid application identifier. + * A valid ID is required for calls to g_application_new() and + * g_application_set_application_id(). + * For convenience, the restrictions on application identifiers are + * reproduced here: + * <itemizedlist> + * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.</listitem> + * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least two elements).</listitem> + * <listitem>Application identifiers must not begin with a '.' (period) character.</listitem> + * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem> + * <listitem>Application identifiers must not exceed 255 characters.</listitem> + * </itemizedlist> */ /** - * GOptionFlags: - * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output. - * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the <option>--help</option> output, even if it is defined in a group. - * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed. - * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8 - * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8 - * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8 - * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution which prefixes long option names with <literal>groupname-</literal> if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8. + * g_application_new: + * @application_id: the application id + * @flags: the application flags + * @returns: a new #GApplication instance * - * Flags which modify individual options. + * Creates a new #GApplication instance. + * This function calls g_type_init() for you. + * The application id must be valid. See g_application_id_is_valid(). */ /** - * GDBusProxy:g-interface-name: + * g_application_open: + * @application: a #GApplication + * @files: (array length=n_files): an array of #GFiles to open + * @n_files: the length of the @files array + * @hint: a hint (or ""), but never %NULL * - * The D-Bus interface name the proxy is for. + * Opens the given files. + * In essence, this results in the #GApplication::open signal being emitted + * in the primary instance. + * intended to be used by applications that have multiple modes for + * for this functionality, you should use "". + * The application must be registered before calling this function + * and it must have the %G_APPLICATION_HANDLES_OPEN flag set. * - * Since: 2.26 + * Opening files (eg: "view" vs "edit", etc). Unless you have a need + * Since: 2.28 */ /** - * g_icon_to_string: - * @icon: a #GIcon. + * g_application_register: + * @application: a #GApplication + * @cancellable: a #GCancellable, or %NULL + * @error: a pointer to a NULL #GError, or %NULL + * @returns: %TRUE if registration succeeded * - * Generates a textual representation of @icon that can be used for - * serialization such as when passing @icon to a different process or - * saving it to persistent storage. Use g_icon_new_for_string() to - * get @icon back from the returned string. - * The encoding of the returned string is proprietary to #GIcon except - * in the following two cases - * <itemizedlist> - * <listitem><para> - * If @icon is a #GFileIcon, the returned string is a native path - * (such as <literal>/path/to/my icon.png</literal>) 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 <literal>sftp://path/to/my%%20icon.png</literal>). - * </para></listitem> - * <listitem><para> - * If @icon is a #GThemedIcon with exactly one name, the encoding is - * simply the name (such as <literal>network-server</literal>). - * </para></listitem> - * </itemizedlist> - * be serialized. Use g_free() to free. + * Attempts registration of the application. + * This is the point at which the application discovers if it is the + * primary instance or merely acting as a remote for an already-existing + * primary instance. This is implemented by attempting to acquire the + * application identifier as a uniue bus name on the session bus using + * GDBus. + * Due to the internal architecture of GDBus, method calls can be + * dispatched at any time (even if a main loop is not running). For + * this reason, you must ensure that any object paths that you wish to + * register are registered before calling this function. + * If the application has already been registered then %TRUE is + * returned with no work performed. + * The #GApplication::startup signal is emitted if registration succeeds + * and @application is the primary instance. + * In the event of an error (such as @cancellable being cancelled, or a + * failure to connect to the session bus), %FALSE is returned and @error + * is set appropriately. + * instance is or is not the primary instance of the application. See + * g_application_get_is_remote() for that. * - * Virtual: to_tokens - * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't - * Since: 2.20 + * Note: the return value of this function is not an indicator that this + * Since: 2.28 */ /** - * g_dbus_connection_unregister_subtree: - * @connection: A #GDBusConnection. - * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree(). - * - * Unregisters a subtree. + * g_application_release: + * @application: a #GApplication * - * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise. - * Since: 2.26 + * Decrease the use count of @application. + * When the use count reaches zero, the application will stop running. + * Never call this function except to cancel the effect of a previous + * call to g_application_hold(). */ /** - * GPollableOutputStream: + * g_application_run: + * @application: a #GApplication + * @argc: the argc from main() + * @argv: (array length=argc): the argv from main() + * @returns: the exit status * - * An interface for a #GOutputStream that can be polled for readability. + * Runs the application. + * This function is intended to be run from main() and its return value + * is intended to be returned by main(). + * First, the local_command_line() virtual function is invoked. This + * function always runs on the local instance. If that function returns + * %FALSE then the application is registered and the #GApplication::command-line + * signal is emitted in the primary instance (which may or may not be + * this instance). + * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE + * flag set then the default implementation of local_command_line() + * always returns %FALSE immediately, resulting in the commandline + * always being handled in the primary instance. + * Otherwise, the default implementation of local_command_line() tries + * to do a couple of things that are probably reasonable for most + * applications. First, g_application_register() is called to attempt + * to register the application. If that works, then the command line + * arguments are inspected. If no commandline arguments are given, then + * g_application_activate() is called. If commandline arguments are + * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they + * are assumed to be filenames and g_application_open() is called. + * If you are interested in doing more complicated local handling of the + * commandline then you should implement your own #GApplication subclass + * and override local_command_line(). See + * <xref linkend="gapplication-example-cmdline2"/> for an example. + * If, after the above is done, the use count of the application is zero + * then the exit status is returned immediately. If the use count is + * non-zero then the mainloop is run until the use count falls to zero, + * at which point 0 is returned. + * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at + * around to provide its <emphasis>service</emphasis> to others). * + * Use count of zero is delayed for a while (ie: the instance stays * Since: 2.28 */ /** - * g_socket_listener_accept_socket_finish: - * @listener: a #GSocketListener - * @result: a #GAsyncResult. - * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_application_set_action_group: + * @application: a #GApplication + * @action_group: (allow-none): a #GActionGroup, or %NULL * - * Finishes an async accept operation. See g_socket_listener_accept_socket_async() + * Sets or unsets the group of actions associated with the application. + * These actions are the actions that can be remotely invoked. + * It is an error to call this function after the application has been + * registered. * - * Returns: (transfer full): a #GSocket on success, %NULL on error. - * Since: 2.22 + * Since: 2.28 */ /** - * G_FILE_ATTRIBUTE_SELINUX_CONTEXT: + * g_application_set_application_id: + * @application: a #GApplication + * @application_id: the identifier for @application * - * A key in the "selinux" namespace for getting the file's SELinux - * context. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only - * available if GLib has been built with SELinux support. + * Sets the unique identifier for @application. + * The application id can only be modified if @application has not yet + * been registered. + * The application id must be valid. See g_application_id_is_valid(). + * + * Since: 2.28 */ /** - * g_io_extension_point_get_required_type: - * @extension_point: a #GIOExtensionPoint + * g_application_set_flags: + * @application: a #GApplication + * @flags: the flags for @application * - * Gets the required type for @extension_point. - * or #G_TYPE_INVALID if the extension point has no required type + * Sets the flags for @application. + * The flags can only be modified if @application has not yet been + * registered. + * See #GApplicationFlags. * - * Returns: the #GType that all implementations must have, + * Since: 2.28 */ /** - * GDBusProxy:g-default-timeout: + * g_application_set_inactivity_timeout: + * @application: a #GApplication + * @inactivity_timeout: the timeout, in milliseconds * - * The timeout to use if -1 (specifying default timeout) is passed - * as @timeout_msec in the g_dbus_proxy_call() and - * g_dbus_proxy_call_sync() functions. - * This allows applications to set a proxy-wide timeout for all - * remote method invocations on the proxy. If this property is -1, - * the default timeout (typically 25 seconds) is used. If set to - * %G_MAXINT, then no timeout is used. + * Sets the current inactivity timeout for the application. + * This is the amount of time (in milliseconds) after the last call to + * g_application_release() before the application stops running. + * This call has no side effects of its own. The value set here is only + * used for next time g_application_release() drops the use count to + * zero. Any timeouts currently in progress are not impacted. * - * Since: 2.26 + * Returns: the timeout, in milliseconds + * Since: 2.28 */ /** - * GConnectFlags: - * @G_CONNECT_AFTER: whether the handler should be called before or after the default handler of the signal. - * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when calling the handler. + * g_async_initable_init_async: + * @initable: a #GAsyncInitable. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function * - * The connection flags are used to specify the behaviour of a signal's - * connection. - */ - - -/** - * g_file_info_set_attribute_uint64: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: an unsigned 64-bit integer. + * Starts asynchronous initialization of the object implementing the + * interface. This must be done before any real use of the object after + * initial construction. If the object also implements #GInitable you can + * optionally call g_initable_init() instead. + * When the initialization is finished, @callback will be called. You can + * then call g_async_initable_init_finish() to get the result of the + * initialization. + * Implementations may also support cancellation. If @cancellable is not + * %NULL, then initialization can be cancelled by triggering the cancellable + * object from another thread. If the operation was cancelled, the error + * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and + * the object doesn't support cancellable initialization, the error + * %G_IO_ERROR_NOT_SUPPORTED will be returned. + * If this function is not called, or returns with an error, then all + * operations on the object should fail, generally returning the + * error %G_IO_ERROR_NOT_INITIALIZED. + * to this function with the same argument should return the same results. + * Only the first call initializes the object; further calls return the result + * of the first call. This is so that it's safe to implement the singleton + * pattern in the GObject constructor function. + * For classes that also support the #GInitable interface, the default + * implementation of this method will run the g_initable_init() function + * in a thread, so if you want to support asynchronous initialization via + * threads, just implement the #GAsyncInitable interface without overriding + * any interface methods. * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * Implementations of this method must be idempotent: i.e. multiple calls + * Since: 2.22 */ /** - * G_VARIANT_TYPE_BYTE: + * g_async_initable_init_finish: + * @initable: a #GAsyncInitable. + * @res: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * The type of an integer value that can range from 0 to 255. + * Finishes asynchronous initialization and returns the result. + * See g_async_initable_init_async(). + * will return %FALSE and set @error appropriately if present. + * + * Returns: %TRUE if successful. If an error has occurred, this function + * Since: 2.22 */ /** - * g_socket_get_timeout: - * @socket: a #GSocket. + * g_async_initable_new_async: + * @object_type: a #GType supporting #GAsyncInitable. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @user_data: the data to pass to callback function + * @first_property_name: the name of the first property, or %NULL if no properties + * @...: the value of the first property, followed by other property value pairs, and ended by %NULL. * - * Gets the timeout setting of the socket. For details on this, see - * g_socket_set_timeout(). + * Helper function for constructing #GAsyncInitiable object. This is + * similar to g_object_new() but also initializes the object asynchronously. + * When the initialization is finished, @callback will be called. You can + * then call g_async_initable_new_finish() to get the new object and check + * for any errors. * - * Returns: the timeout in seconds - * Since: 2.26 + * Since: 2.22 */ /** - * g_dbus_connection_set_exit_on_close: - * @connection: A #GDBusConnection. - * @exit_on_close: Whether the process should be terminated when @connection is closed by the remote peer. + * g_async_initable_new_finish: + * @initable: the #GAsyncInitable from the callback + * @res: the #GAsyncResult.from the callback + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Sets whether the process should be terminated when @connection is - * closed by the remote peer. See #GDBusConnection:exit-on-close for - * more details. + * Finishes the async construction for the various g_async_initable_new calls, + * returning the created object or %NULL on error. + * g_object_unref(). * - * Since: 2.26 + * Returns: (transfer full): a newly created #GObject, or %NULL on error. Free with + * Since: 2.22 */ /** - * GFileDescriptorBasedIface: - * @g_iface: The parent interface. + * g_async_initable_new_valist_async: + * @object_type: a #GType supporting #GAsyncInitable. + * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. + * @var_args: The var args list generated from @first_property_name. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @user_data: the data to pass to callback function * + * Helper function for constructing #GAsyncInitiable object. This is + * similar to g_object_new_valist() but also initializes the object + * asynchronously. + * When the initialization is finished, @callback will be called. You can + * then call g_async_initable_new_finish() to get the new object and check + * for any errors. * + * Since: 2.22 */ /** - * G_IS_PARAM_SPEC_UCHAR: - * @pspec: a valid #GParamSpec instance + * g_async_initable_newv_async: + * @object_type: a #GType supporting #GAsyncInitable. + * @n_parameters: the number of parameters in @parameters + * @parameters: the parameters to use to construct the object + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @user_data: the data to pass to callback function * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. + * Helper function for constructing #GAsyncInitiable object. This is + * similar to g_object_newv() but also initializes the object asynchronously. + * When the initialization is finished, @callback will be called. You can + * then call g_async_initable_new_finish() to get the new object and check + * for any errors. * - * Returns: %TRUE on success. + * Since: 2.22 */ /** - * SECTION:gsimpleasyncresul: - * @short_description: Simple asynchronous results implementation - * @include: gio/gio.h - * @see_also: #GAsyncResult + * g_async_result_get_source_object: + * @res: a #GAsyncResult * - * Implements #GAsyncResult for simple cases. Most of the time, this - * will be all an application needs, and will be used transparently. - * Because of this, #GSimpleAsyncResult is used throughout GIO for - * handling asynchronous functions. - * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error - * reporting, operation cancellation and the final state of an operation, - * completely transparent to the application. Results can be returned - * as a pointer e.g. for functions that return data that is collected - * asynchronously, a boolean value for checking the success or failure - * of an operation, or a #gssize for operations which return the number - * of bytes modified by the operation; all of the simple return cases - * are covered. - * Most of the time, an application will not need to know of the details - * of this API; it is handled transparently, and any necessary operations - * are handled by #GAsyncResult's interface. However, if implementing a - * new GIO module, for writing language bindings, or for complex - * applications that need better control of how asynchronous operations - * are completed, it is important to understand this functionality. - * GSimpleAsyncResults are tagged with the calling function to ensure - * that asynchronous functions and their finishing functions are used - * together correctly. - * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). - * If the result needs to be created for a #GError, use - * g_simple_async_result_new_from_error() or - * g_simple_async_result_new_take_error(). If a #GError is not available - * (e.g. the asynchronous operation's doesn't take a #GError argument), - * but the result still needs to be created for an error condition, use - * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() - * if your application or binding requires passing a variable argument list - * directly), and the error can then be propagated through the use of - * g_simple_async_result_propagate_error(). - * An asynchronous operation can be made to ignore a cancellation event by - * calling g_simple_async_result_set_handle_cancellation() with a - * #GSimpleAsyncResult for the operation and %FALSE. This is useful for - * operations that are dangerous to cancel, such as close (which would - * cause a leak if cancelled before being run). - * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, - * or it can use #GThread<!-- -->s if available. - * g_simple_async_result_complete() will finish an I/O task directly - * from the point where it is called. g_simple_async_result_complete_in_idle() - * will finish it from an idle handler in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * context</link>. g_simple_async_result_run_in_thread() will run the - * job in a separate thread and then deliver the result to the - * thread-default main context. - * To set the results of an asynchronous function, - * g_simple_async_result_set_op_res_gpointer(), - * g_simple_async_result_set_op_res_gboolean(), and - * g_simple_async_result_set_op_res_gssize() - * are provided, setting the operation's result to a gpointer, gboolean, or - * gssize, respectively. - * Likewise, to get the result of an asynchronous function, - * g_simple_async_result_get_op_res_gpointer(), - * g_simple_async_result_get_op_res_gboolean(), and - * g_simple_async_result_get_op_res_gssize() are - * provided, getting the operation's result as a gpointer, gboolean, and - * gssize, respectively. - * For the details of the requirements implementations must respect, see - * #GAsyncResult. A typical implementation of an asynchronous operation - * using GSimpleAsyncResult looks something like this: - * |[ - * static void - * baked_cb (Cake *cake, - * gpointer user_data) - * { - * /* In this example, this callback is not given a reference to the cake, so - * * the GSimpleAsyncResult has to take a reference to it. - * */ - * GSimpleAsyncResult *result = user_data; - * if (cake == NULL) - * g_simple_async_result_set_error (result, - * BAKER_ERRORS, - * BAKER_ERROR_NO_FLOUR, - * "Go to the supermarket"); - * else - * g_simple_async_result_set_op_res_gpointer (result, - * g_object_ref (cake), - * g_object_unref); - * /* In this example, we assume that baked_cb is called as a callback from - * * the mainloop, so it's safe to complete the operation synchronously here. - * * If, however, _baker_prepare_cake () might call its callback without - * * first returning to the mainloop — inadvisable, but some APIs do so — - * * we would need to use g_simple_async_result_complete_in_idle(). - * */ - * g_simple_async_result_complete (result); - * g_object_unref (result); - * } - * void - * baker_bake_cake_async (Baker *self, - * guint radius, - * GAsyncReadyCallback callback, - * gpointer user_data) - * { - * GSimpleAsyncResult *simple; - * Cake *cake; - * if (radius < 3) - * { - * g_simple_async_report_error_in_idle (G_OBJECT (self), - * callback, - * user_data, - * BAKER_ERRORS, - * BAKER_ERROR_TOO_SMALL, - * "%ucm radius cakes are silly", - * radius); - * return; - * } - * simple = g_simple_async_result_new (G_OBJECT (self), - * callback, - * user_data, - * baker_bake_cake_async); - * cake = _baker_get_cached_cake (self, radius); - * if (cake != NULL) - * { - * g_simple_async_result_set_op_res_gpointer (simple, - * g_object_ref (cake), - * g_object_unref); - * g_simple_async_result_complete_in_idle (simple); - * g_object_unref (simple); - * /* Drop the reference returned by _baker_get_cached_cake(); the - * * GSimpleAsyncResult has taken its own reference. - * */ - * g_object_unref (cake); - * return; - * } - * _baker_prepare_cake (self, radius, baked_cb, simple); - * } - * Cake * - * baker_bake_cake_finish (Baker *self, - * GAsyncResult *result, - * GError **error) - * { - * GSimpleAsyncResult *simple; - * Cake *cake; - * g_return_val_if_fail (g_simple_async_result_is_valid (result, - * G_OBJECT (self), - * baker_bake_cake_async), - * NULL); - * simple = (GSimpleAsyncResult *) result; - * if (g_simple_async_result_propagate_error (simple, error)) - * return NULL; - * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); - * return g_object_ref (cake); - * } - * ]| + * Gets the source object from a #GAsyncResult. + * or %NULL if there is none. + * + * Returns: (transfer full): a new reference to the source object for the @res, */ /** - * g_async_initable_init_finish: - * @initable: a #GAsyncInitable. + * g_async_result_get_user_data: * @res: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Finishes asynchronous initialization and returns the result. - * See g_async_initable_init_async(). - * will return %FALSE and set @error appropriately if present. + * Gets the user data from a #GAsyncResult. * - * Returns: %TRUE if successful. If an error has occurred, this function - * Since: 2.22 + * Returns: (transfer full): the user data for @res. */ /** - * g_input_stream_skip_async: - * @stream: A #GInputStream. - * @count: the number of bytes that will be skipped from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> 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 + * g_atomic_int_dec_and_test: + * @atomic: a pointer to an integer * - * Request an asynchronous skip of @count bytes from the stream. - * When the operation is finished @callback will be called. - * You can then call g_input_stream_skip_finish() to get the result - * of the operation. - * During an async request no other sync and async calls are allowed, - * and will result in %G_IO_ERROR_PENDING errors. - * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * On success, the number of bytes skipped will be passed to the callback. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. near the end of a file, but generally we try to skip - * as many bytes as requested. Zero is returned on end of file - * (or if @count is zero), but never otherwise. - * Any outstanding i/o request with higher priority (lower numerical value) - * will be executed before an outstanding request with lower priority. - * Default priority is %G_PRIORITY_DEFAULT. - * The asynchronous methods have a default fallback that uses threads to - * implement asynchronicity, so they are optional for inheriting classes. - * However, if you override one, you must override all. + * Atomically decrements the integer pointed to by @atomic by 1. + * after decrementing it + * + * Returns: %TRUE if the integer pointed to by @atomic is 0 + * Since: 2.4 */ /** - * g_mount_guess_content_type_finish: - * @mount: a #GMount - * @result: a #GAsyncResult - * @error: a #GError location to store the error occuring, or %NULL to ignore + * g_atomic_int_inc: + * @atomic: a pointer to an integer. * - * Finishes guessing content types of @mount. If any errors occured - * during the operation, @error will be set to contain the errors and - * %FALSE will be returned. In particular, you may get an - * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content - * guessing. - * Caller should free this array with g_strfreev() when done with it. + * Atomically increments the integer pointed to by @atomic by 1. * - * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. - * Since: 2.18 + * Since: 2.4 */ /** - * GActionGroupInterface: - * @has_action: the virtual function pointer for g_action_group_has_action() - * @list_actions: the virtual function pointer for g_action_group_list_actions() - * @get_parameter_type: the virtual function pointer for g_action_group_get_parameter_type() - * @get_state_type: the virtual function pointer for g_action_group_get_state_type() - * @get_state_hint: the virtual function pointer for g_action_group_get_state_hint() - * @get_enabled: the virtual function pointer for g_action_group_get_enabled() - * @get_state: the virtual function pointer for g_action_group_get_state() - * @set_state: the virtual function pointer for g_action_group_set_state() - * @activate: the virtual function pointer for g_action_group_activate() - * @action_added: the class closure for the action-added signal - * @action_removed: the class closure for the action-removed signal - * @action_enabled_changed: the class closure for the action-enabled-changed signal - * @action_state_changed: the class closure for the action-enabled-changed signal + * g_buffered_input_stream_fill: + * @stream: a #GBufferedInputStream + * @count: the number of bytes that will be read from the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @error: location to store the error occuring, or %NULL to ignore * - * The virtual function table for #GActionGroup. + * Tries to read @count bytes from the stream into the buffer. + * Will block during this read. + * If @count is zero, returns zero and does nothing. A value of @count + * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. + * On success, the number of bytes read into the buffer is returned. + * It is not an error if this is not the same as the requested size, as it + * can happen e.g. near the end of a file. Zero is returned on end of file + * (or if @count is zero), but never otherwise. + * If @count is -1 then the attempted read size is equal to the number of + * bytes that are required to fill the buffer. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an + * operation was partially finished when the operation was cancelled the + * partial result will be returned, without an error. + * On error -1 is returned and @error is set accordingly. + * For the asynchronous, non-blocking, version of this function, see + * g_buffered_input_stream_fill_async(). + * or -1 on error. * - * Since: 2.26 + * Returns: the number of bytes read into @stream's buffer, up to @count, */ /** - * g_cancellable_push_current: - * @cancellable: a #GCancellable object + * g_buffered_input_stream_fill_async: + * @stream: a #GBufferedInputStream + * @count: the number of bytes that will be read from the stream + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request + * @cancellable: (allow-none): optional #GCancellable object + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): a #gpointer * - * Pushes @cancellable onto the cancellable stack. The current - * cancellable can then be recieved using g_cancellable_get_current(). - * This is useful when implementing cancellable operations in - * code that does not allow you to pass down the cancellable object. - * This is typically called automatically by e.g. #GFile operations, - * so you rarely have to call this yourself. + * Reads data into @stream's buffer asynchronously, up to @count size. + * version of this function, see g_buffered_input_stream_fill(). + * If @count is -1 then the attempted read size is equal to the number + * of bytes that are required to fill the buffer. */ /** - * g_file_query_exists: - * @file: input #GFile. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * g_buffered_input_stream_fill_finish: + * @stream: a #GBufferedInputStream + * @result: a #GAsyncResult + * @error: a #GError * - * Utility function to check if a particular file exists. This is - * implemented using g_file_query_info() and as such does blocking I/O. - * Note that in many cases it is racy to first check for file existence - * and then execute something based on the outcome of that, because the - * file might have been created or removed in between the operations. The - * general approach to handling that is to not check, but just do the - * operation and handle the errors as they come. - * As an example of race-free checking, take the case of reading a file, and - * can both result in two processes creating the file (with perhaps a partially - * written file as the result). The correct approach is to always try to create - * the file with g_file_create() which will either atomically create the file - * or fail with a G_IO_ERROR_EXISTS error. - * However, in many cases an existence check is useful in a user - * interface, for instance to make a menu item sensitive/insensitive, so that - * you don't have to fool users that something is possible and then just show - * and error dialog. If you do this, you should make sure to also handle the - * errors that can happen due to races when you execute the operation. + * Finishes an asynchronous read. * - * If it doesn't exist, creating it. there are two racy versions: read it, and - * On error create it; and: check if it exists, if not create it. These - * Returns: %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). + * Returns: a #gssize of the read stream, or %-1 on an error. */ /** - * g_inet_address_get_is_any: - * @address: a #GInetAddress + * g_buffered_input_stream_get_available: + * @stream: #GBufferedInputStream * - * Tests whether @address is the "any" address for its family. + * Gets the size of the available data within the stream. * - * Returns: %TRUE if @address is the "any" address for its family. - * Since: 2.22 + * Returns: size of the available stream. */ /** - * g_unix_socket_address_get_path: - * @address: a #GInetSocketAddress + * g_buffered_input_stream_get_buffer_size: + * @stream: a #GBufferedInputStream * - * Gets @address's path, or for abstract sockets the "name". - * Guaranteed to be zero-terminated, but an abstract socket - * may contain embedded zeros, and thus you should use - * g_unix_socket_address_get_path_len() to get the true length - * of this string. + * Gets the size of the input buffer. * - * Returns: the path for @address - * Since: 2.22 + * Returns: the current buffer size. */ /** - * SECTION:gdbusserve: - * @short_description: Helper for accepting connections - * @include: gio/gio.h + * g_buffered_input_stream_new: + * @base_stream: a #GInputStream * - * #GDBusServer is a helper for listening to and accepting D-Bus - * connections. - * <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> - */ - - -/** - * G_TYPE_ULONG: + * Creates a new #GInputStream from the given @base_stream, with + * a buffer set to the default size (4 kilobytes). * - * The fundamental type corresponding to #gulong. + * Returns: a #GInputStream for the given @base_stream. */ /** - * SECTION:gdbusmessag: - * @short_description: D-Bus Message - * @include: gio/gio.h + * g_buffered_input_stream_new_sized: + * @base_stream: a #GInputStream + * @size: a #gsize * - * A type for representing D-Bus messages that can be sent or received - * on a #GDBusConnection. - */ - - -/** - * GParamSpecEnum: - * @parent_instance: private #GParamSpec portion - * @enum_class: the #GEnumClass for the enum - * @default_value: default value for the property specified + * Creates a new #GBufferedInputStream from the given @base_stream, + * with a buffer set to @size. * - * A #GParamSpec derived structure that contains the meta data for enum - * properties. + * Returns: a #GInputStream. */ /** - * G_PARAM_USER_SHIFT: + * g_buffered_input_stream_peek: + * @stream: a #GBufferedInputStream + * @buffer: a pointer to an allocated chunk of memory + * @offset: a #gsize + * @count: a #gsize * - * Minimum shift count to be used for user defined flags, to be stored in - * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT. + * Peeks in the buffer, copying data of size @count into @buffer, + * offset @offset bytes. + * + * Returns: a #gsize of the number of bytes peeked, or -1 on error. */ /** - * GStrv: + * g_buffered_input_stream_peek_buffer: + * @stream: a #GBufferedInputStream + * @count: (out): a #gsize to get the number of bytes available in the buffer * - * A C representable type name for #G_TYPE_STRV. + * Returns the buffer with the currently available bytes. The returned + * buffer must not be modified and will become invalid when reading from + * the stream or filling the buffer. + * read-only buffer + * + * Returns: (array length=count) (element-type guint8) (transfer none): */ /** - * G_TYPE_FROM_INTERFACE: - * @g_iface: Location of a valid #GTypeInterface structure. + * g_buffered_input_stream_read_byte: + * @stream: a #GBufferedInputStream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @error: location to store the error occuring, or %NULL to ignore * - * Get the type identifier from a given @interface structure. - * This macro should only be used in type implementations. + * Tries to read a single byte from the stream or the buffer. Will block + * during this read. + * On success, the byte read from the stream is returned. On end of stream + * -1 is returned but it's not an exceptional error and @error is not set. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an + * operation was partially finished when the operation was cancelled the + * partial result will be returned, without an error. + * On error -1 is returned and @error is set accordingly. * - * Returns: the #GType + * Returns: the byte read from the @stream, or -1 on end of stream or error. */ /** - * g_inet_address_get_is_mc_link_local: - * @address: a #GInetAddress - * - * Tests whether @address is a link-local multicast address. + * g_buffered_input_stream_set_buffer_size: + * @stream: a #GBufferedInputStream + * @size: a #gsize * - * Returns: %TRUE if @address is a link-local multicast address. - * Since: 2.22 + * Sets the size of the internal buffer of @stream to @size, or to the + * size of the contents of the buffer. The buffer can never be resized + * smaller than its current contents. */ /** - * GDBusMessage: + * g_buffered_output_stream_get_auto_grow: + * @stream: a #GBufferedOutputStream. * - * The #GDBusMessage structure contains only private data and should - * only be accessed using the provided API. + * Checks if the buffer automatically grows as data is added. + * %FALSE otherwise. * - * Since: 2.26 + * Returns: %TRUE if the @stream's buffer automatically grows, */ /** - * GClosureMarshal: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. - * @n_param_values: the length of the @param_values array - * @param_values: an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() + * g_buffered_output_stream_get_buffer_size: + * @stream: a #GBufferedOutputStream. * - * The type used for marshaller functions. + * Gets the size of the buffer in the @stream. + * + * Returns: the current size of the buffer. */ /** - * g_file_enumerator_close_async: - * @enumerator: a #GFileEnumerator. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * g_buffered_output_stream_new: + * @base_stream: a #GOutputStream. * - * Asynchronously closes the file enumerator. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in - * g_file_enumerator_close_finish(). + * Creates a new buffered output stream for a base stream. + * + * Returns: a #GOutputStream for the given @base_stream. */ /** - * G_IS_PARAM_SPEC_OVERRIDE: - * @pspec: a #GParamSpec + * g_buffered_output_stream_new_sized: + * @base_stream: a #GOutputStream. + * @size: a #gsize. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. + * Creates a new buffered output stream with a given buffer size. * - * Since: 2.4 - * Returns: %TRUE on success. + * Returns: a #GOutputStream with an internal buffer set to @size. */ /** - * SECTION:gactiongrou: - * @title: GActionGroup - * @short_description: A group of actions - * - * #GActionGroup represents a group of actions. - * Each action in the group has a unique name (which is a string). All - * method calls, except g_action_group_list_actions() take the name of - * an action as an argument. - * The #GActionGroup API is meant to be the 'public' API to the action - * group. The calls here are exactly the interaction that 'external - * the action group implementation) are found on subclasses. This is - * why you will find -- for example -- g_action_group_get_enabled() but - * not an equivalent <function>set()</function> call. - * Signals are emitted on the action group in response to state changes - * on individual actions. + * g_buffered_output_stream_set_auto_grow: + * @stream: a #GBufferedOutputStream. + * @auto_grow: a #gboolean. * - * Forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have - * With actions. 'internal' apis (ie: ones meant only to be accessed by + * Sets whether or not the @stream's buffer should automatically grow. + * If @auto_grow is true, then each write will just make the buffer + * larger, and you must manually flush the buffer to actually write out + * the data to the underlying stream. */ /** - * SECTION:gpollableoutputstrea: - * @short_description: Interface for pollable output streams - * @include: gio/gio.h - * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream - * - * #GPollableOutputStream is implemented by #GOutputStream<!-- -->s that - * can be polled for readiness to write. This can be used when - * interfacing with a non-GIO API that expects - * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. + * g_buffered_output_stream_set_buffer_size: + * @stream: a #GBufferedOutputStream. + * @size: a #gsize. * - * Since: 2.28 + * Sets the size of the internal buffer to @size. */ /** - * GUnixOutputStream:close-fd: + * g_bus_get: + * @bus_type: A #GBusType. + * @cancellable: A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: The data to pass to @callback. * - * Whether to close the file descriptor when the stream is closed. + * Asynchronously connects to the message bus specified by @bus_type. + * When the operation is finished, @callback will be invoked. You can + * then call g_bus_get_finish() to get the result of the operation. + * This is a asynchronous failable function. See g_bus_get_sync() for + * the synchronous version. * - * Since: 2.20 + * Since: 2.26 */ /** - * g_app_info_dup: - * @appinfo: a #GAppInfo. + * g_bus_get_finish: + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get(). + * @error: Return location for error or %NULL. * - * Creates a duplicate of a #GAppInfo. + * Finishes an operation started with g_bus_get(). + * The returned object is a singleton, that is, shared with other + * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the + * event that you need a private message bus connection, use + * g_dbus_address_get_for_bus() and + * g_dbus_connection_new_for_address(). + * Note that the returned #GDBusConnection object will (usually) have + * the #GDBusConnection:exit-on-close property set to %TRUE. * - * Returns: (transfer full): a duplicate of @appinfo. + * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Since: 2.26 */ /** - * g_srv_target_copy: - * @target: a #GSrvTarget + * g_bus_get_sync: + * @bus_type: A #GBusType. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Copies @target + * Synchronously connects to the message bus specified by @bus_type. + * Note that the returned object may shared with other callers, + * e.g. if two separate parts of a process calls this function with + * the same @bus_type, they will share the same object. + * This is a synchronous failable function. See g_bus_get() and + * g_bus_get_finish() for the asynchronous version. + * The returned object is a singleton, that is, shared with other + * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the + * event that you need a private message bus connection, use + * g_dbus_address_get_for_bus_sync() and + * g_dbus_connection_new_for_address(). + * Note that the returned #GDBusConnection object will (usually) have + * the #GDBusConnection:exit-on-close property set to %TRUE. * - * Returns: a copy of @target - * Since: 2.22 + * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Since: 2.26 */ /** - * G_OBJECT_CLASS_TYPE: - * @class: a valid #GObjectClass + * g_bus_own_name: + * @bus_type: The type of bus to own a name on. + * @name: The well-known name to own. + * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. + * @bus_acquired_handler: Handler to invoke when connected to the bus of type @bus_type or %NULL. + * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL. + * @name_lost_handler: Handler to invoke when @name is lost or %NULL. + * @user_data: User data to pass to handlers. + * @user_data_free_func: Function for freeing @user_data or %NULL. * - * Get the type id of a class structure. + * Starts acquiring @name on the bus specified by @bus_type and calls + * acquired respectively lost. Callbacks will be invoked in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread you are calling this function from. + * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler + * callbacks will be invoked after calling this function - there are three + * possible cases: + * <itemizedlist> + * <listitem><para> + * </para></listitem> + * <listitem><para> + * </para></listitem> + * <listitem><para> + * </para></listitem> + * </itemizedlist> + * When you are done owning the name, just call g_bus_unown_name() + * with the owner id this function returns. + * If the name is acquired or lost (for example another application + * could acquire the name if you allow replacement or the application + * currently owning the name exits), the handlers are also invoked. If the + * #GDBusConnection that is used for attempting to own the name + * closes, then @name_lost_handler is invoked since it is no + * longer possible for other processes to access the process. + * You cannot use g_bus_own_name() several times for the same name (unless + * interleaved with calls to g_bus_unown_name()) - only the first call + * will work. + * Another guarantee is that invocations of @name_acquired_handler + * and @name_lost_handler are guaranteed to alternate; that + * is, if @name_acquired_handler is invoked then you are + * guaranteed that the next time one of the handlers is invoked, it + * will be @name_lost_handler. The reverse is also true. + * If you plan on exporting objects (using e.g. + * g_dbus_connection_register_object()), note that it is generally too late + * to export the objects in @name_acquired_handler. Instead, you can do this + * in @bus_acquired_handler since you are guaranteed that this will run + * before @name is requested from the bus. + * This behavior makes it very simple to write applications that wants + * to own names and export objects, see <xref linkend="gdbus-owning-names"/>. + * Simply register objects to be exported in @bus_acquired_handler and + * unregister the objects (if any) in @name_lost_handler. + * g_bus_unown_name() to stop owning the name. * - * Returns: Type id of @class. + * Returns: An identifier (never 0) that an be used with + * Since: 2.26 */ /** - * G_PRIORITY_HIGH: + * g_bus_own_name_on_connection: + * @connection: A #GDBusConnection. + * @name: The well-known name to own. + * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. + * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL. + * @name_lost_handler: Handler to invoke when @name is lost or %NULL. + * @user_data: User data to pass to handlers. + * @user_data_free_func: Function for freeing @user_data or %NULL. * - * Use this for high priority event sources. - * It is not used within GLib or GTK+. + * Like g_bus_own_name() but takes a #GDBusConnection instead of a + * #GBusType. + * g_bus_unown_name() to stop owning the name. + * + * Returns: An identifier (never 0) that an be used with + * Since: 2.26 */ /** - * g_app_launch_context_get_display: - * @context: a #GAppLaunchContext - * @info: a #GAppInfo - * @files: (element-type GFile): a #GList of #GFile objects + * g_bus_own_name_on_connection_with_closures: + * @connection: A #GDBusConnection. + * @name: The well-known name to own. + * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. + * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. + * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. * - * Gets the display string for the @context. This is used to ensure new - * applications are started on the same display as the launching - * application, by setting the <envar>DISPLAY</envar> environment variable. + * Version of g_bus_own_name_on_connection() using closures instead of callbacks for + * easier binding in other languages. + * g_bus_unown_name() to stop owning the name. * - * Returns: a display string for the display. + * Returns: An identifier (never 0) that an be used with + * Rename to: g_bus_own_name_on_connection + * Since: 2.26 */ /** - * g_desktop_app_info_get_is_hidden: - * @info: a #GDesktopAppInfo. + * g_bus_own_name_with_closures: + * @bus_type: The type of bus to own a name on. + * @name: The well-known name to own. + * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. + * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to the bus of type @bus_type or %NULL. + * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. + * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. * - * A desktop file is hidden if the Hidden key in it is - * set to True. + * Version of g_bus_own_name() using closures instead of callbacks for + * easier binding in other languages. + * g_bus_unown_name() to stop owning the name. * - * Returns: %TRUE if hidden, %FALSE otherwise. + * Returns: An identifier (never 0) that an be used with + * Rename to: g_bus_own_name + * Since: 2.26 */ /** - * g_pollable_output_stream_is_writable: - * @stream: a #GPollableOutputStream. + * g_bus_unown_name: + * @owner_id: An identifier obtained from g_bus_own_name() * - * Checks if @stream can be written. - * Note that some stream types may not be able to implement this 100% - * reliably, and it is possible that a call to g_output_stream_write() - * after this returns %TRUE would still block. To guarantee - * non-blocking behavior, you should always use - * g_pollable_output_stream_write_nonblocking(), which will return a - * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. - * has occurred on @stream, this will result in - * g_pollable_output_stream_is_writable() returning %TRUE, and the - * next attempt to write will return the error. + * Stops owning a name. * - * Returns: %TRUE if @stream is writable, %FALSE if not. If an error - * Since: 2.28 + * Since: 2.26 */ /** - * g_node_append_data: - * @parent: the #GNode to place the new #GNode under - * @data: the data for the new #GNode + * g_bus_unwatch_name: + * @watcher_id: An identifier obtained from g_bus_watch_name() * - * Inserts a new #GNode as the last child of the given parent. + * Stops watching a name. * - * Returns: the new #GNode + * Since: 2.26 */ /** - * g_socket_send_message: - * @socket: a #GSocket - * @address: a #GSocketAddress, or %NULL - * @vectors: (array length=num_vectors): an array of #GOutputVector structs - * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (allow-none): a pointer to an array of #GSocketControlMessages, or %NULL. - * @num_messages: number of elements in @messages, or -1. - * @flags: an int containing #GSocketMsgFlags flags - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_bus_watch_name: + * @bus_type: The type of bus to watch a name on. + * @name: The name (well-known or unique) to watch. + * @flags: Flags from the #GBusNameWatcherFlags enumeration. + * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL. + * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL. + * @user_data: User data to pass to handlers. + * @user_data_free_func: Function for freeing @user_data or %NULL. * - * Send data to @address on @socket. This is the most complicated and - * fully-featured version of this call. For easier use, see - * g_socket_send() and g_socket_send_to(). - * If @address is %NULL then the message is sent to the default receiver - * (set by g_socket_connect()). - * then @vectors is assumed to be terminated by a #GOutputVector with a - * %NULL buffer pointer.) The #GOutputVector structs describe the buffers - * that the sent data will be gathered from. Using multiple - * #GOutputVector<!-- -->s is more memory-efficient than manually copying - * data from multiple sources into a single buffer, and more - * network-efficient than making multiple calls to g_socket_send(). - * #GSocketControlMessage instances. These correspond to the control - * messages to be sent on the socket. - * If @num_messages is -1 then @messages is treated as a %NULL-terminated - * array. - * for this are available in the #GSocketMsgFlags enum, but the - * values there are the same as the system values, and the flags - * are passed in as-is, so you can pass in system-specific flags too. - * If the socket is in blocking mode the call will block until there is - * space for the data in the socket queue. If there is no space available - * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error - * 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. - * on error + * Starts watching @name on the bus specified by @bus_type and calls + * known to have a owner respectively known to lose its + * owner. Callbacks will be invoked in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread you are calling this function from. + * You are guaranteed that one of the handlers will be invoked after + * calling this function. When you are done watching the name, just + * call g_bus_unwatch_name() with the watcher id this function + * returns. + * If the name vanishes or appears (for example the application owning + * the name could restart), the handlers are also invoked. If the + * #GDBusConnection that is used for watching the name disconnects, then + * possible to access the name. + * Another guarantee is that invocations of @name_appeared_handler + * and @name_vanished_handler are guaranteed to alternate; that + * is, if @name_appeared_handler is invoked then you are + * guaranteed that the next time one of the handlers is invoked, it + * will be @name_vanished_handler. The reverse is also true. + * This behavior makes it very simple to write applications that wants + * to take action when a certain name exists, see <xref + * linkend="gdbus-watching-names"/>. Basically, the application + * should create object proxies in @name_appeared_handler and destroy + * them again (if any) in @name_vanished_handler. + * g_bus_unwatch_name() to stop watching the name. * - * Returns: Number of bytes written (which may be less than @size), or -1 - * Since: 2.22 + * Returns: An identifier (never 0) that an be used with + * Since: 2.26 */ /** - * GDBusInterfaceInfo: - * @ref_count: The reference count or -1 if statically allocated. - * @name: The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties". - * @methods: A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods. - * @signals: A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals. - * @properties: A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties. - * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. + * g_bus_watch_name_on_connection: + * @connection: A #GDBusConnection. + * @name: The name (well-known or unique) to watch. + * @flags: Flags from the #GBusNameWatcherFlags enumeration. + * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL. + * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL. + * @user_data: User data to pass to handlers. + * @user_data_free_func: Function for freeing @user_data or %NULL. * - * Information about a D-Bus interface. + * Like g_bus_watch_name() but takes a #GDBusConnection instead of a + * #GBusType. + * g_bus_unwatch_name() to stop watching the name. * + * Returns: An identifier (never 0) that an be used with * Since: 2.26 */ /** - * g_permission_release: - * @permission: a #GPermission instance - * @cancellable: a #GCancellable, or %NULL - * @error: a pointer to a %NULL #GError, or %NULL - * @returns: %TRUE if the permission was successfully released + * g_bus_watch_name_on_connection_with_closures: + * @connection: A #GDBusConnection. + * @name: The name (well-known or unique) to watch. + * @flags: Flags from the #GBusNameWatcherFlags enumeration. + * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. + * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. * - * Attempts to release the permission represented by @permission. - * The precise method by which this happens depends on the permission - * and the underlying authentication mechanism. In most cases the - * permission will be dropped immediately without further action. - * You should check with g_permission_get_can_release() before calling - * this function. - * If the permission is released then %TRUE is returned. Otherwise, - * %FALSE is returned and @error is set appropriately. - * This call is blocking, likely for a very long time (in the case that - * user interaction is required). See g_permission_release_async() for - * the non-blocking version. + * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for + * easier binding in other languages. + * g_bus_unwatch_name() to stop watching the name. * + * Returns: An identifier (never 0) that an be used with + * Rename to: g_bus_watch_name_on_connection * Since: 2.26 */ /** - * G_VARIANT_TYPE_UINT16: + * g_bus_watch_name_with_closures: + * @bus_type: The type of bus to watch a name on. + * @name: The name (well-known or unique) to watch. + * @flags: Flags from the #GBusNameWatcherFlags enumeration. + * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. + * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. * - * The type of an integer value that can range from 0 to 65535. - * There were about this many people living in Toronto in the 1870s. + * Version of g_bus_watch_name() using closures instead of callbacks for + * easier binding in other languages. + * g_bus_unwatch_name() to stop watching the name. + * + * Returns: An identifier (never 0) that an be used with + * Rename to: g_bus_watch_name + * Since: 2.26 */ /** - * GSettings::change-event: - * @settings: the object on which the signal was emitted - * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL - * @n_keys: the length of the @keys array, or 0 - * @returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. - * - * The "change-event" signal is emitted once per change event that - * affects this settings object. You should connect to this signal - * only if you are interested in viewing groups of changes before they - * are split out into multiple emissions of the "changed" signal. - * For most use cases it is more appropriate to use the "changed" signal. - * In the event that the change event applies to one or more specified - * keys, @keys will be an array of #GQuark of length @n_keys. In the - * event that the change event applies to the #GSettings object as a - * be %NULL and @n_keys will be 0. - * The default handler for this signal invokes the "changed" signal - * for each affected key. If any other connected handler returns - * %TRUE then this default functionality will be supressed. + * g_cancellable_cancel: + * @cancellable: a #GCancellable object. * - * Whole (ie: potentially every key has been changed) then @keys will + * Will set @cancellable to cancelled, and will emit the + * #GCancellable::cancelled signal. (However, see the warning about + * race conditions in the documentation for that signal if you are + * planning to connect to it.) + * This function is thread-safe. In other words, you can safely call + * it from a thread other than the one running the operation that was + * passed the @cancellable. + * The convention within gio is that cancelling an asynchronous + * operation causes it to complete asynchronously. That is, if you + * cancel the operation from the same thread in which it is running, + * then the operation's #GAsyncReadyCallback will not be invoked until + * the application returns to the main loop. */ /** - * GInetAddress:is-mc-org-local: + * g_cancellable_connect: + * @cancellable: A #GCancellable. + * @callback: The #GCallback to connect. + * @data: Data to pass to @callback. + * @data_destroy_func: Free function for @data or %NULL. * - * Whether this is an organization-local multicast address. - * See g_inet_address_get_is_mc_org_local(). + * Convenience function to connect to the #GCancellable::cancelled + * signal. Also handles the race condition that may happen + * if the cancellable is cancelled right before connecting. + * time of the connect if @cancellable is already cancelled, + * or when @cancellable is cancelled in some thread. + * disconnected, or immediately if the cancellable is already + * cancelled. + * See #GCancellable::cancelled for details on how to use this. + * been cancelled. * + * Returns: The id of the signal handler or 0 if @cancellable has already * Since: 2.22 */ /** - * g_file_start_mountable_finish: - * @file: input #GFile. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_cancellable_disconnect: + * @cancellable: A #GCancellable or %NULL. + * @handler_id: Handler id of the handler to be disconnected, or %0. * - * Finishes a start operation. See g_file_start_mountable() for details. - * Finish an asynchronous start operation that was started - * with g_file_start_mountable(). - * otherwise. + * Disconnects a handler from a cancellable instance similar to + * g_signal_handler_disconnect(). Additionally, in the event that a + * signal handler is currently running, this call will block until the + * handler has finished. Calling this function from a + * #GCancellable::cancelled signal handler will therefore result in a + * deadlock. + * This avoids a race condition where a thread cancels at the + * same time as the cancellable operation is finished and the + * signal handler is removed. See #GCancellable::cancelled for + * details on how to use this. + * If @cancellable is %NULL or @handler_id is %0 this function does + * nothing. * - * Returns: %TRUE if the operation finished successfully. %FALSE * Since: 2.22 */ /** - * g_input_stream_read_async: - * @stream: A #GInputStream. - * @buffer: 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 <link linkend="io-priority">I/O priority</link> 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 + * g_cancellable_get_current: * - * Request an asynchronous read of @count bytes from the stream into the buffer - * starting at @buffer. When the operation is finished @callback will be called. - * You can then call g_input_stream_read_finish() to get the result of the - * operation. - * During an async request no other sync and async calls are allowed on @stream, and will - * result in %G_IO_ERROR_PENDING errors. - * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * On success, the number of bytes read into the buffer will be passed to the - * callback. It is not an error if this is not the same as the requested size, as it - * can happen e.g. near the end of a file, but generally we try to read - * as many bytes as requested. Zero is returned on end of file - * (or if @count is zero), but never otherwise. - * Any outstanding i/o request with higher priority (lower numerical value) will - * be executed before an outstanding request with lower priority. Default - * priority is %G_PRIORITY_DEFAULT. - * The asyncronous methods have a default fallback that uses threads to implement - * asynchronicity, so they are optional for inheriting classes. However, if you - * override one you must override all. + * Gets the top cancellable from the stack. + * if the stack is empty. + * + * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL */ /** - * g_data_input_stream_new: - * @base_stream: a #GInputStream. + * g_cancellable_get_fd: + * @cancellable: a #GCancellable. * - * Creates a new data input stream for the @base_stream. + * Gets the file descriptor for a cancellable job. This can be used to + * implement cancellable operations on Unix systems. The returned fd will + * turn readable when @cancellable is cancelled. + * You are not supposed to read from the fd yourself, just check for + * readable status. Reading to unset the readable status is done + * with g_cancellable_reset(). + * After a successful return from this function, you should use + * g_cancellable_release_fd() to free up resources allocated for + * the returned file descriptor. + * See also g_cancellable_make_pollfd(). + * is not supported, or on errors. * - * Returns: a new #GDataInputStream. + * Returns: A valid file descriptor. %-1 if the file descriptor */ /** - * g_file_get_uri: - * @file: input #GFile. + * g_cancellable_is_cancelled: + * @cancellable: a #GCancellable or NULL. * - * Gets the URI for the @file. - * This call does no blocking i/o. - * The returned string should be freed with g_free() when no longer needed. + * Checks if a cancellable job has been cancelled. + * FALSE if called with %NULL or if item is not cancelled. * - * Returns: a string containing the #GFile's URI. + * Returns: %TRUE if @cancellable is cancelled, */ /** - * g_mount_get_volume: - * @mount: a #GMount. + * g_cancellable_make_pollfd: + * @cancellable: a #GCancellable or %NULL + * @pollfd: a pointer to a #GPollFD * - * Gets the volume for the @mount. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. + * Creates a #GPollFD corresponding to @cancellable; this can be passed + * to g_poll() and used to poll for cancellation. This is useful both + * for unix systems without a native poll and for portability to + * windows. + * When this function returns %TRUE, you should use + * g_cancellable_release_fd() to free up resources allocated for the + * If this function returns %FALSE, either no @cancellable was given or + * resource limits prevent this function from allocating the necessary + * structures for polling. (On Linux, you will likely have reached + * the maximum number of file descriptors.) The suggested way to handle + * these cases is to ignore the @cancellable. + * You are not supposed to read from the fd yourself, just check for + * readable status. Reading to unset the readable status is done + * with g_cancellable_reset(). + * failure to prepare the cancellable. * - * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume. + * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on + * Since: 2.22 */ /** - * g_buffered_input_stream_get_available: - * @stream: #GBufferedInputStream + * g_cancellable_new: * - * Gets the size of the available data within the stream. + * Creates a new #GCancellable object. + * Applications that want to start one or more operations + * that should be cancellable should create a #GCancellable + * and pass it to the operations. + * One #GCancellable can be used in multiple consecutive + * operations, but not in multiple concurrent operations. * - * Returns: size of the available stream. + * Returns: a #GCancellable. */ /** - * GDBusSendMessageFlags: - * @G_DBUS_SEND_MESSAGE_FLAGS_NONE: No flags set. - * @G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL: Do not automatically assign a serial number from the #GDBusConnection object when sending a message. - * - * Flags used when sending #GDBusMessage<!-- -->s on a #GDBusConnection. + * g_cancellable_pop_current: + * @cancellable: a #GCancellable object * - * Since: 2.26 + * Pops @cancellable off the cancellable stack (verifying that @cancellable + * is on the top of the stack). */ /** - * g_settings_reset: - * @settings: a #GSettings object - * @key: the name of a key + * g_cancellable_push_current: + * @cancellable: a #GCancellable object * - * Resets @key to its default value. - * This call resets the key, as much as possible, to its default value. - * That might the value specified in the schema or the one set by the - * administrator. + * Pushes @cancellable onto the cancellable stack. The current + * cancellable can then be recieved using g_cancellable_get_current(). + * This is useful when implementing cancellable operations in + * code that does not allow you to pass down the cancellable object. + * This is typically called automatically by e.g. #GFile operations, + * so you rarely have to call this yourself. */ /** - * G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION: + * g_cancellable_release_fd: + * @cancellable: a #GCancellable * - * A key in the "standard" namespace for getting the description of the file. - * The description is a utf8 string that describes the file, generally containing - * the filename, but can also contain furter information. Example descriptions - * could be "filename (on hostname)" for a remote file or "filename (in trash)" - * for a file in the trash. This is useful for instance as the window title - * when displaying a directory or for a bookmarks menu. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * Releases a resources previously allocated by g_cancellable_get_fd() + * or g_cancellable_make_pollfd(). + * For compatibility reasons with older releases, calling this function + * is not strictly required, the resources will be automatically freed + * when the @cancellable is finalized. However, the @cancellable will + * block scarce file descriptors until it is finalized if this function + * is not called. This can cause the application to run out of file + * descriptors when many #GCancellables are used at the same time. + * + * Since: 2.22 */ /** - * SECTION:gdbusaddres: - * @title: D-Bus Addresses - * @short_description: D-Bus connection endpoints - * @include: gio/gio.h + * g_cancellable_reset: + * @cancellable: a #GCancellable object. * - * Routines for working with D-Bus addresses. A D-Bus address is a string - * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses - * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">D-Bus specification</link>. + * Resets @cancellable to its uncancelled state. */ /** - * g_volume_eject_finish: - * @volume: pointer to a #GVolume. - * @result: a #GAsyncResult. - * @error: a #GError location to store an error, or %NULL to ignore + * g_cancellable_set_error_if_cancelled: + * @cancellable: a #GCancellable object. + * @error: #GError to append error state to. * - * Finishes ejecting a volume. If any errors occured during the operation, + * If the @cancellable is cancelled, sets the error to notify + * that the operation was cancelled. * - * Returns: %TRUE, %FALSE if operation failed. - * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead. + * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not. */ /** - * g_file_dup: - * @file: input #GFile. + * g_cancellable_source_new: (skip) + * @cancellable: a #GCancellable, or %NULL * - * Duplicates a #GFile handle. This operation does not duplicate - * the actual file or directory represented by the #GFile; see - * g_file_copy() if attempting to copy a file. - * This call does no blocking i/o. + * Creates a source that triggers if @cancellable is cancelled and + * calls its callback of type #GCancellableSourceFunc. This is + * primarily useful for attaching to another (non-cancellable) source + * with g_source_add_child_source() to add cancellability to it. + * For convenience, you can call this with a %NULL #GCancellable, + * in which case the source will never trigger. * - * Returns: (transfer full): a new #GFile that is a duplicate of the given #GFile. + * Returns: (transfer full): the new #GSource. + * Since: 2.28 */ /** - * g_unix_mount_points_changed_since: - * @time: guint64 to contain a timestamp. + * g_charset_converter_get_num_fallbacks: + * @converter: a #GCharsetConverter * - * Checks if the unix mount points have changed since a given unix time. + * Gets the number of fallbacks that @converter has applied so far. * - * Returns: %TRUE if the mount points have changed since @time. + * Returns: the number of fallbacks that @converter has applied + * Since: 2.24 */ /** - * SECTION:gdbusauthobserve: - * @short_description: Object used for authenticating connections - * @include: gio/gio.h + * g_charset_converter_get_use_fallback: + * @converter: a #GCharsetConverter * - * The #GDBusAuthObserver type provides a mechanism for participating - * in how a #GDBusServer (or a #GDBusConnection) authenticates remote - * peers. Simply instantiate a #GDBusAuthObserver and connect to the - * signals you are interested in. Note that new signals may be added - * in the future - * For example, if you only want to allow D-Bus connections from - * processes owned by the same uid as the server, you would use a - * signal handler like the following: - * <example id="auth-observer"><title>Controlling Authentication</title><programlisting> - * static gboolean - * on_authorize_authenticated_peer (GDBusAuthObserver *observer, - * GIOStream *stream, - * GCredentials *credentials, - * gpointer user_data) - * { - * gboolean authorized; - * authorized = FALSE; - * if (credentials != NULL) - * { - * GCredentials *own_credentials; - * own_credentials = g_credentials_new (); - * if (g_credentials_is_same_user (credentials, own_credentials, NULL)) - * authorized = TRUE; - * g_object_unref (own_credentials); - * } - * return authorized; - * } - * </programlisting></example> + * Gets the #GCharsetConverter:use-fallback property. + * + * Returns: %TRUE if fallbacks are used by @converter + * Since: 2.24 */ /** - * G_TYPE_PARAM_VARIANT: + * g_charset_converter_new: + * @to_charset: destination charset + * @from_charset: source charset + * @error: #GError for error reporting, or %NULL to ignore. * - * The #GType of #GParamSpecVariant. + * Creates a new #GCharsetConverter. * - * Since: 2.26 + * Returns: a new #GCharsetConverter or %NULL on error. + * Since: 2.24 */ /** - * g_settings_set_string: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * g_charset_converter_set_use_fallback: + * @converter: a #GCharsetConverter + * @use_fallback: %TRUE to use fallbacks * - * Sets @key in @settings to @value. - * A convenience variant of g_settings_set() for strings. - * It is a programmer error to give a @key that isn't specified as - * having a string type in the schema for @settings. + * Sets the #GCharsetConverter:use-fallback property. * - * Since: 2.26 + * Since: 2.24 */ /** - * GBusNameAppearedCallback: - * @connection: The #GDBusConnection the name is being watched on. - * @name: The name being watched. - * @name_owner: Unique name of the owner of the name being watched. - * @user_data: User data passed to g_bus_watch_name(). + * g_content_type_can_be_executable: + * @type: a content type string * - * Invoked when the name being watched is known to have to have a owner. + * Checks if a content type can be executable. Note that for instance + * things like text files can be executables (i.e. scripts and batch files). + * can be executable, %FALSE otherwise. * - * Since: 2.26 + * Returns: %TRUE if the file type corresponds to a type that */ /** - * g_mount_unmount_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_content_type_equals: + * @type1: a content type string + * @type2: a content type string * - * Finishes unmounting a mount. If any errors occurred during the operation, + * Compares two content types for equality. + * %FALSE otherwise. * - * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise. - * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead. + * Returns: %TRUE if the two strings are identical or equivalent, */ /** - * g_buffered_output_stream_get_buffer_size: - * @stream: a #GBufferedOutputStream. + * g_content_type_from_mime_type: + * @mime_type: a mime type string * - * Gets the size of the buffer in the @stream. + * Tries to find a content type based on the mime type name. + * or %NULL. Free with g_free() * - * Returns: the current size of the buffer. + * Returns: (allow-none): Newly allocated string with content type + * Since: 2.18 */ /** - * g_action_group_list_actions: - * @action_group: a #GActionGroup + * g_content_type_get_description: + * @type: a content type string * - * Lists the actions contained within @action_group. - * The caller is responsible for freeing the list with g_strfreev() when - * it is no longer required. - * actions in the groupb + * Gets the human readable description of the content type. + * returned string with g_free() * - * Returns: (transfer full): a %NULL-terminated array of the names of the - * Since: 2.28 + * Returns: a short description of the content type @type. Free the */ /** - * GUserDirectory: - * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory - * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory - * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory - * @G_USER_DIRECTORY_MUSIC: the user's Music directory - * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory - * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory - * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory - * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory - * @G_USER_N_DIRECTORIES: the number of enum values + * g_content_type_get_icon: + * @type: a content type string * - * These are logical ids for special directories which are defined - * depending on the platform used. You should use g_get_user_special_dir() - * to retrieve the full path associated to the logical id. - * The #GUserDirectory enumeration can be extended at later date. Not - * every platform has a directory for every logical id in this - * enumeration. + * Gets the icon for a content type. + * object with g_object_unref() * - * Since: 2.14 + * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned */ /** - * g_dbus_method_invocation_return_error_literal: - * @invocation: A #GDBusMethodInvocation. - * @domain: A #GQuark for the #GError error domain. - * @code: The error code. - * @message: The error message. + * g_content_type_get_mime_type: + * @type: a content type string * - * Like g_dbus_method_invocation_return_error() but without printf()-style formatting. - * This method will free @invocation, you cannot use it afterwards. + * Gets the mime type for the content type, if one is registered. + * or %NULL if unknown. * - * Since: 2.26 + * Returns: (allow-none): the registered mime type for the given @type, */ /** - * g_dbus_message_get_serial: - * @message: A #GDBusMessage. + * g_content_type_guess: + * @filename: (allow-none): a string, or %NULL + * @data: (allow-none) (array length=data_size): a stream of data, or %NULL + * @data_size: the size of @data + * @result_uncertain: (allow-none) (out): return location for the certainty of the result, or %NULL * - * Gets the serial for @message. + * Guesses the content type based on example data. If the function is + * uncertain, @result_uncertain will be set to %TRUE. Either @filename + * or @data may be %NULL, in which case the guess will be based solely + * on the other argument. + * given data. Free with g_free() * - * Returns: A #guint32. - * Since: 2.26 + * Returns: a string indicating a guessed content type for the */ /** - * GTlsRehandshakeMode: - * @G_TLS_REHANDSHAKE_NEVER: Never allow rehandshaking - * @G_TLS_REHANDSHAKE_SAFELY: Allow safe rehandshaking only - * @G_TLS_REHANDSHAKE_UNSAFELY: Allow unsafe rehandshaking + * g_content_type_guess_for_tree: + * @root: the root of the tree to guess a type for * - * When to allow rehandshaking. See - * g_tls_connection_set_rehandshake_mode(). + * Tries to guess the type of the tree with root @root, by + * looking at the files it contains. The result is an array + * of content types, with the best guess coming first. + * The types returned all have the form x-content/foo, e.g. + * x-content/audio-cdda (for audio CDs) or x-content/image-dcf + * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> + * specification for more on x-content types. + * This function is useful in the implementation of + * g_mount_guess_content_type(). + * array of zero or more content types, or %NULL. Free with g_strfreev() * - * Since: 2.28 + * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated + * Since: 2.18 */ /** - * g_file_attribute_matcher_ref: - * @matcher: a #GFileAttributeMatcher. + * g_content_type_is_a: + * @type: a content type string + * @supertype: a content type string * - * References a file attribute matcher. + * Determines if @type is a subset of @supertype. + * %FALSE otherwise. * - * Returns: a #GFileAttributeMatcher. + * Returns: %TRUE if @type is a kind of @supertype, */ /** - * GFilenameCompleter: + * g_content_type_is_unknown: + * @type: a content type string * - * Completes filenames based on files that exist within the file system. + * Checks if the content type is the generic "unknown" type. + * On UNIX this is the "application/octet-stream" mimetype, + * while on win32 it is "*". + * + * Returns: %TRUE if the type is the unknown type. */ /** - * GDBusSignalInfo: - * @ref_count: The reference count or -1 if statically allocated. - * @name: The name of the D-Bus signal, e.g. "NameOwnerChanged". - * @args: A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments. - * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. + * g_content_types_get_registered: * - * Information about a signal on a D-Bus interface. + * Gets a list of strings containing all the registered content types + * known to the system. The list and its data should be freed using + * <programlisting> + * g_list_foreach (list, g_free, NULL); + * g_list_free (list); + * </programlisting> * - * Since: 2.26 + * Returns: (element-type utf8) (transfer full): #GList of the registered content types */ /** - * G_SIGNAL_MATCH_MASK: + * g_converter_convert: + * @converter: a #GConverter. + * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer containing the data to convert. + * @inbuf_size: the number of bytes in @inbuf + * @outbuf: a buffer to write converted data in. + * @outbuf_size: the number of bytes in @outbuf, must be at least one + * @flags: a #GConvertFlags controlling the conversion details + * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success + * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success + * @error: location to store the error occuring, or %NULL to ignore * - * A mask for all #GSignalMatchType bits. + * This is the main operation used when converting data. It is to be called + * multiple times in a loop, and each time it will do some work, i.e. + * producing some output (in @outbuf) or consuming some input (from @inbuf) or + * both. If its not possible to do any work an error is returned. + * Note that a single call may not consume all input (or any input at all). + * Also a call may produce output even if given no input, due to state stored + * in the converter producing output. + * If any data was either produced or consumed, and then an error happens, then + * only the successful conversion is reported and the error is returned on the + * next call. + * A full conversion loop involves calling this method repeatedly, each time + * giving it new input and space output space. When there is no more input + * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set. + * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED + * each time until all data is consumed and all output is produced, then + * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED + * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance + * in a decompression converter where the end of data is detectable from the + * data (and there might even be other data after the end of the compressed data). + * When some data has successfully been converted @bytes_read and is set to + * the number of bytes read from @inbuf, and @bytes_written is set to indicate + * how many bytes was written to @outbuf. If there are more data to output + * or consume (i.e. unless the G_CONVERTER_INPUT_AT_END is specified) then + * G_CONVERTER_CONVERTED is returned, and if no more data is to be output + * then G_CONVERTER_FINISHED is returned. + * On error %G_CONVERTER_ERROR is returned and @error is set accordingly. + * Some errors need special handling: + * %G_IO_ERROR_NO_SPACE is returned if there is not enough space + * to write the resulting converted data, the application should + * call the function again with a larger @outbuf to continue. + * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough + * input to fully determine what the conversion should produce, + * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for + * example with an incomplete multibyte sequence when converting text, + * or when a regexp matches up to the end of the input (and may match + * further input). It may also happen when @inbuf_size is zero and + * there is no more data to produce. + * When this happens the application should read more input and then + * call the function again. If further input shows that there is no + * more data call the function again with the same data but with + * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion + * to finish as e.g. in the regexp match case (or, to fail again with + * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the + * input is actually partial). + * After g_converter_convert() has returned %G_CONVERTER_FINISHED the + * converter object is in an invalid state where its not allowed + * to call g_converter_convert() anymore. At this time you can only + * free the object or call g_converter_reset() to reset it to the + * initial state. + * If the flag %G_CONVERTER_FLUSH is set then conversion is modified + * to try to write out all internal state to the output. The application + * has to call the function multiple times with the flag set, and when + * the availible input has been consumed and all internal state has + * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if + * really at the end) is returned instead of %G_CONVERTER_CONVERTED. + * This is somewhat similar to what happens at the end of the input stream, + * but done in the middle of the data. + * This has different meanings for different conversions. For instance + * in a compression converter it would mean that we flush all the + * compression state into output such that if you uncompress the + * compressed data you get back all the input data. Doing this may + * make the final file larger due to padding though. Another example + * is a regexp conversion, where if you at the end of the flushed data + * have a match, but there is also a potential longer match. In the + * non-flushed case we would ask for more input, but when flushing we + * treat this as the end of input and do the match. + * Flushing is not always possible (like if a charset converter flushes + * at a partial multibyte sequence). Converters are supposed to try + * to produce as much output as possible and then return an error + * (typically %G_IO_ERROR_PARTIAL_INPUT). + * + * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error. + * Since: 2.24 */ /** - * g_file_info_new: + * g_converter_input_stream_get_converter: + * @converter_stream: a #GConverterInputStream * - * Creates a new file info structure. + * Gets the #GConverter that is used by @converter_stream. * - * Returns: a #GFileInfo. + * Returns: (transfer none): the converter of the converter input stream + * Since: 2.24 */ /** - * g_unix_output_stream_new: - * @fd: a UNIX file descriptor - * @close_fd: %TRUE to close the file descriptor when done + * g_converter_input_stream_new: + * @base_stream: a #GInputStream + * @converter: a #GConverter * - * Creates a new #GUnixOutputStream for the given @fd. - * If @close_fd, is %TRUE, the file descriptor will be closed when - * the output stream is destroyed. + * Creates a new converter input stream for the @base_stream. * - * Returns: a new #GOutputStream + * Returns: a new #GInputStream. */ /** - * g_input_stream_close: - * @stream: A #GInputStream. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occuring, or %NULL to ignore + * g_converter_output_stream_get_converter: + * @converter_stream: a #GConverterOutputStream * - * Closes the stream, releasing resources related to it. - * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. - * Closing a stream multiple times will not return an error. - * Streams will be automatically closed when the last reference - * is dropped, but you might want to call this function to make sure - * resources are released as early as possible. - * Some streams might keep the backing store of the stream (e.g. a file descriptor) - * open after the stream is closed. See the documentation for the individual - * stream for details. - * On failure the first error that happened will be reported, but the close - * operation will finish as much as possible. A stream that failed to - * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it - * is important to check and report the error to the user. - * If @cancellable is not NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Cancelling a close will still leave the stream closed, but some streams - * can use a faster close that doesn't block to e.g. check errors. + * Gets the #GConverter that is used by @converter_stream. * - * Returns: %TRUE on success, %FALSE on failure + * Returns: (transfer none): the converter of the converter output stream + * Since: 2.24 */ /** - * g_dbus_annotation_info_lookup: - * @annotations: A %NULL-terminated array of annotations or %NULL. - * @name: The name of the annotation to look up. + * g_converter_output_stream_new: + * @base_stream: a #GOutputStream + * @converter: a #GConverter * - * Looks up the value of an annotation. - * This cost of this function is O(n) in number of annotations. + * Creates a new converter output stream for the @base_stream. * - * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations. - * Since: 2.26 + * Returns: a new #GOutputStream. */ /** - * g_file_set_display_name_async: - * @file: input #GFile. - * @display_name: a string. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * g_converter_reset: + * @converter: a #GConverter. * - * Asynchronously sets the display name for a given #GFile. - * For more details, see g_file_set_display_name() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_set_display_name_finish() to get the result of the operation. + * Resets all internal state in the converter, making it behave + * as if it was just created. If the converter has any internal + * state that would produce output then that output is lost. + * + * Since: 2.24 */ /** - * g_socket_listener_accept_finish: - * @listener: a #GSocketListener - * @result: a #GAsyncResult. - * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_credentials_get_native: (skip) + * @credentials: A #GCredentials. + * @native_type: The type of native credentials to get. * - * Finishes an async accept operation. See g_socket_listener_accept_async() + * Gets a pointer to native credentials of type @native_type from + * It is a programming error (which will cause an warning to be + * logged) to use this method if there is no #GCredentials support for + * the OS or if @native_type isn't supported by the OS. + * operation there is no #GCredentials support for the OS or if + * data, it is owned by @credentials. * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 + * Returns: The pointer to native credentials or %NULL if the + * Since: 2.26 */ /** - * GSimpleAction:parameter-type: + * g_credentials_get_unix_user: + * @credentials: A #GCredentials + * @error: Return location for error or %NULL. * - * The type of the parameter that must be given when activating the - * action. + * Tries to get the UNIX user identifier from @credentials. This + * method is only available on UNIX platforms. + * This operation can fail if #GCredentials is not supported on the + * OS or if the native credentials type does not contain information + * about the UNIX user. * - * Since: 2.28 + * Returns: The UNIX user identifier or -1 if @error is set. + * Since: 2.26 */ /** - * g_proxy_supports_hostname: - * @proxy: a #GProxy + * g_credentials_is_same_user: + * @credentials: A #GCredentials. + * @other_credentials: A #GCredentials. + * @error: Return location for error or %NULL. * - * Some proxy protocols expect to be passed a hostname, which they - * will resolve to an IP address themselves. Others, like SOCKS4, do - * not allow this. This function will return %FALSE if @proxy is - * implementing such a protocol. When %FALSE is returned, the caller - * should resolve the destination hostname first, and then pass a - * #GProxyAddress containing the stringified IP address to - * g_proxy_connect() or g_proxy_connect_async(). + * Checks if @credentials and @other_credentials is the same user. + * This operation can fail if #GCredentials is not supported on the + * the OS. + * user, %FALSE otherwise or if @error is set. * - * Returns: %TRUE if hostname resolution is supported. + * Returns: %TRUE if @credentials and @other_credentials has the same * Since: 2.26 */ /** - * g_file_info_get_attribute_uint64: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_credentials_new: * - * Gets a unsigned 64-bit integer contained within the attribute. If the - * attribute does not contain an unsigned 64-bit integer, or is invalid, - * 0 will be returned. + * Creates a new #GCredentials object with credentials matching the + * the current process. * - * Returns: a unsigned 64-bit integer from the attribute. + * Returns: A #GCredentials. Free with g_object_unref(). + * Since: 2.26 */ /** - * g_dbus_message_get_sender: - * @message: A #GDBusMessage. + * g_credentials_set_native: + * @credentials: A #GCredentials. + * @native_type: The type of native credentials to set. + * @native: A pointer to native credentials. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. + * Copies the native credentials of type @native_type from @native + * into @credentials. + * It is a programming error (which will cause an warning to be + * logged) to use this method if there is no #GCredentials support for + * the OS or if @native_type isn't supported by the OS. * - * Returns: The value. * Since: 2.26 */ /** - * g_tls_connection_handshake: - * @conn: a #GTlsConnection - * @cancellable: a #GCancellable, or %NULL - * @error: a #GError, or %NULL + * g_credentials_set_unix_user: + * @credentials: A #GCredentials. + * @uid: The UNIX user identifier to set. + * @error: Return location for error or %NULL. * - * Attempts a TLS handshake on @conn. - * On the client side, it is never necessary to call this method; - * although the connection needs to perform a handshake after - * connecting (or after sending a "STARTTLS"-type command) and may - * need to rehandshake later if the server requests it, - * #GTlsConnection will handle this for you automatically when you try - * to send or receive data on the connection. However, you can call - * g_tls_connection_handshake() manually if you want to know for sure - * whether the initial handshake succeeded or failed (as opposed to - * just immediately trying to write to @conn's output stream, in which - * case if it fails, it may not be possible to tell if it failed - * before or after completing the handshake). - * Likewise, on the server side, although a handshake is necessary at - * the beginning of the communication, you do not need to call this - * function explicitly unless you want clearer error reporting. - * However, you may call g_tls_connection_handshake() later on to - * renegotiate parameters (encryption methods, etc) with the client. - * #GTlsConnection::accept_certificate may be emitted during the - * handshake. + * Tries to set the UNIX user identifier on @credentials. This method + * is only available on UNIX platforms. + * This operation can fail if #GCredentials is not supported on the + * OS or if the native credentials type does not contain information + * about the UNIX user. * - * Returns: success or failure - * Since: 2.28 + * Returns: %TRUE if @uid was set, %FALSE if error is set. + * Since: 2.26 */ /** - * G_TYPE_IS_ENUM: - * @type: a #GType ID. + * g_credentials_to_string: + * @credentials: A #GCredentials object. * - * Checks whether @type "is a" %G_TYPE_ENUM. + * Creates a human-readable textual representation of @credentials + * that can be used in logging and debug messages. The format of the + * returned string may change in future GLib release. * - * Returns: %TRUE if @type "is a" %G_TYPE_ENUM. + * Returns: A string that should be freed with g_free(). + * Since: 2.26 */ /** - * g_mount_operation_set_username: - * @op: a #GMountOperation. - * @username: input username. + * g_data_input_stream_get_byte_order: + * @stream: a given #GDataInputStream. * - * Sets the user name within @op to @username. + * Gets the byte order for the data input stream. + * + * Returns: the @stream's current #GDataStreamByteOrder. */ /** - * GSourceCallbackFuncs: - * @ref: Called when a reference is added to the callback object - * @unref: Called when a reference to the callback object is dropped - * @get: Called to extract the callback function and data from the callback object. + * g_data_input_stream_get_newline_type: + * @stream: a given #GDataInputStream. * - * The <structname>GSourceCallbackFuncs</structname> struct contains - * functions for managing callback objects. + * Gets the current newline type for the @stream. + * + * Returns: #GDataStreamNewlineType for the given @stream. */ /** - * GDBusProxy:g-name: + * g_data_input_stream_new: + * @base_stream: a #GInputStream. * - * The well-known or unique name that the proxy is for. + * Creates a new data input stream for the @base_stream. * - * Since: 2.26 + * Returns: a new #GDataInputStream. */ /** - * g_mount_shadow: - * @mount: A #GMount. + * g_data_input_stream_read_byte: + * @stream: a given #GDataInputStream. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Increments the shadow count on @mount. Usually used by - * #GVolumeMonitor implementations when creating a shadow mount for - * will need to emit the #GMount::changed signal on @mount manually. + * Reads an unsigned 8-bit/1-byte value from @stream. + * if an error occurred. * - * Since: 2.20 + * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 */ /** - * GFileInfo: + * g_data_input_stream_read_int16: + * @stream: a given #GDataInputStream. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Stores information about a file system object referenced by a #GFile. + * Reads a 16-bit/2-byte value from @stream. + * In order to get the correct byte order for this read operation, + * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). + * an error occurred. + * + * Returns: a signed 16-bit/2-byte value read from @stream or %0 if */ /** - * G_OBJECT: - * @object: Object which is subject to casting. + * g_data_input_stream_read_int32: + * @stream: a given #GDataInputStream. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Casts a #GObject or derived pointer into a (GObject*) pointer. - * Depending on the current debugging level, this function may invoke - * certain runtime checks to identify invalid casts. + * Reads a signed 32-bit/4-byte value from @stream. + * In order to get the correct byte order for this read operation, + * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * an error occurred. + * + * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if */ /** - * GMarkupParseFlags: - * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use - * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked sections are not passed literally to the @passthrough function of the parser. Instead, the content of the section (without the <literal><![CDATA[</literal> and <literal>]]></literal>) is passed to the @text function. This flag was added in GLib 2.12 - * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup itself have line/column information prefixed to them to let the caller know the location of the error. When this flag is set the location information is also prefixed to errors generated by the #GMarkupParser implementation functions + * g_data_input_stream_read_int64: + * @stream: a given #GDataInputStream. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Flags that affect the behaviour of the parser. + * Reads a 64-bit/8-byte value from @stream. + * In order to get the correct byte order for this read operation, + * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * an error occurred. + * + * Returns: a signed 64-bit/8-byte value read from @stream or %0 if */ /** - * GTlsConnection:peer-certificate: + * g_data_input_stream_read_line: + * @stream: a given #GDataInputStream. + * @length: (out): a #gsize to get the length of the data read in. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * The connection's peer's certificate, after the TLS handshake has - * completed and the certificate has been accepted. Note in - * particular that this is not yet set during the emission of - * #GTlsConnection::accept-certificate. - * (You can watch for a #GObject::notify signal on this property to - * detect when a handshake has occurred.) + * Reads a line from the data input stream. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * (without the newlines). Set @length to a #gsize to get the + * length of the read line. On an error, it will return %NULL and + * still return %NULL, but @error won't be set. * - * Since: 2.28 + * Returns: (transfer full): a string with the line that was read in */ /** - * g_file_query_filesystem_info_async: - * @file: input #GFile. - * @attributes: an attribute query string. + * g_data_input_stream_read_line_async: + * @stream: a given #GDataInputStream. * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * @callback: (scope async): callback to call when the request is satisfied. + * @user_data: (closure): the data to pass to callback function. * - * Asynchronously gets the requested information about the filesystem - * that the specified @file is on. The result is a #GFileInfo object - * that contains key-value attributes (such as type or size for the - * file). - * For more details, see g_file_query_filesystem_info() which is the - * synchronous version of this call. - * When the operation is finished, @callback will be called. You can - * then call g_file_query_info_finish() to get the result of the - * operation. + * The asynchronous version of g_data_input_stream_read_line(). It is + * an error to have two outstanding calls to this function. + * When the operation is finished, @callback will be called. You + * can then call g_data_input_stream_read_line_finish() to get + * the result of the operation. + * + * Since: 2.20 */ /** - * g_file_attribute_info_list_add: - * @list: a #GFileAttributeInfoList. - * @name: the name of the attribute to add. - * @type: the #GFileAttributeType for the attribute. - * @flags: #GFileAttributeInfoFlags for the attribute. + * g_data_input_stream_read_line_finish: + * @stream: a given #GDataInputStream. + * @result: the #GAsyncResult that was provided to the callback. + * @length: (out): a #gsize to get the length of the data read in. + * @error: #GError for error reporting. * - * Adds a new attribute with @name to the @list, setting - * its @type and @flags. + * Finish an asynchronous call started by + * g_data_input_stream_read_line_async(). + * (without the newlines). Set @length to a #gsize to get the + * length of the read line. On an error, it will return %NULL and + * still return %NULL, but @error won't be set. + * + * Returns: (transfer full): a string with the line that was read in + * Since: 2.20 */ /** - * G_NODE_IS_ROOT: - * @node: a #GNode + * g_data_input_stream_read_uint16: + * @stream: a given #GDataInputStream. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Returns %TRUE if a #GNode is the root of a tree. - * (i.e. it has no parent or siblings) + * Reads an unsigned 16-bit/2-byte value from @stream. + * In order to get the correct byte order for this read operation, + * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). + * an error occurred. * - * Returns: %TRUE if the #GNode is the root of a tree + * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if */ /** - * GUnixInputStream:close-fd: + * g_data_input_stream_read_uint32: + * @stream: a given #GDataInputStream. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Whether to close the file descriptor when the stream is closed. + * Reads an unsigned 32-bit/4-byte value from @stream. + * In order to get the correct byte order for this read operation, + * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * an error occurred. * - * Since: 2.20 + * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if */ /** - * g_content_type_from_mime_type: - * @mime_type: a mime type string + * g_data_input_stream_read_uint64: + * @stream: a given #GDataInputStream. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Tries to find a content type based on the mime type name. - * or %NULL. Free with g_free() + * Reads an unsigned 64-bit/8-byte value from @stream. + * In order to get the correct byte order for this read operation, + * see g_data_input_stream_get_byte_order(). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * an error occurred. * - * Returns: (allow-none): Newly allocated string with content type - * Since: 2.18 + * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if */ /** - * g_srv_target_get_port: - * @target: a #GSrvTarget + * g_data_input_stream_read_until: + * @stream: a given #GDataInputStream. + * @stop_chars: characters to terminate the read. + * @length: (out): a #gsize to get the length of the data read in. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Gets @target's port + * Reads a string from the data input stream, up to the first + * occurrence of any of the stop characters. + * Note that, in contrast to g_data_input_stream_read_until_async(), + * this function consumes the stop character that it finds. + * Don't use this function in new code. Its functionality is + * inconsistent with g_data_input_stream_read_until_async(). Both + * functions will be marked as deprecated in a future release. Use + * g_data_input_stream_read_upto() instead, but note that that function + * does not consume the stop character. + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. * - * Returns: @target's port - * Since: 2.22 + * Returns: (transfer full): a string with the data that was read */ /** - * g_mount_eject: - * @mount: a #GMount. - * @flags: flags affecting the unmount if required for eject + * g_data_input_stream_read_until_async: + * @stream: a given #GDataInputStream. + * @stop_chars: characters to terminate the read. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * @callback: (scope async): callback to call when the request is satisfied. + * @user_data: (closure): the data to pass to callback function. * - * Ejects a mount. This is an asynchronous operation, and is - * finished by calling g_mount_eject_finish() with the @mount - * and #GAsyncResult data returned in the @callback. + * The asynchronous version of g_data_input_stream_read_until(). + * It is an error to have two outstanding calls to this function. + * Note that, in contrast to g_data_input_stream_read_until(), + * this function does not consume the stop character that it finds. You + * must read it for yourself. + * When the operation is finished, @callback will be called. You + * can then call g_data_input_stream_read_until_finish() to get + * the result of the operation. + * Don't use this function in new code. Its functionality is + * inconsistent with g_data_input_stream_read_until(). Both functions + * will be marked as deprecated in a future release. Use + * g_data_input_stream_read_upto_async() instead. * - * Deprecated: 2.22: Use g_mount_eject_with_operation() instead. + * Since: 2.20 */ /** - * G_VALUE_HOLDS_CHAR: - * @value: a valid #GValue structure + * g_data_input_stream_read_until_finish: + * @stream: a given #GDataInputStream. + * @result: the #GAsyncResult that was provided to the callback. + * @length: (out): a #gsize to get the length of the data read in. + * @error: #GError for error reporting. * - * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. + * Finish an asynchronous call started by + * g_data_input_stream_read_until_async(). + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. * - * Returns: %TRUE on success. + * Since: 2.20 + * Returns: (transfer full): a string with the data that was read */ /** - * G_TYPE_IS_FUNDAMENTAL: - * @type: A #GType value. + * g_data_input_stream_read_upto: + * @stream: a #GDataInputStream + * @stop_chars: characters to terminate the read + * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated + * @length: (out): a #gsize to get the length of the data read in + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @error: #GError for error reporting * - * Checks if @type is a fundamental type. + * Reads a string from the data input stream, up to the first + * occurrence of any of the stop characters. + * In contrast to g_data_input_stream_read_until(), this function + * does <emphasis>not</emphasis> consume the stop character. You have + * to use g_data_input_stream_read_byte() to get it before calling + * g_data_input_stream_read_upto() again. + * Note that @stop_chars may contain '\0' if @stop_chars_len is + * specified. + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error * - * Returns: %TRUE on success. + * Returns: (transfer full): a string with the data that was read + * Since: 2.24 */ /** - * g_dbus_error_get_remote_error: - * @error: A #GError. + * g_data_input_stream_read_upto_async: + * @stream: a #GDataInputStream + * @stop_chars: characters to terminate the read + * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated + * @io_priority: the <link linkend="io-priority">I/O priority</link> 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 * - * Gets the D-Bus error name used for @error, if any. - * This function is guaranteed to return a D-Bus error name for all - * #GError<!-- -->s returned from functions handling remote method - * calls (e.g. g_dbus_connection_call_finish()) unless - * g_dbus_error_strip_remote_error() has been used on @error. + * The asynchronous version of g_data_input_stream_read_upto(). + * It is an error to have two outstanding calls to this function. + * In contrast to g_data_input_stream_read_until(), this function + * does <emphasis>not</emphasis> consume the stop character. You have + * to use g_data_input_stream_read_byte() to get it before calling + * g_data_input_stream_read_upto() again. + * Note that @stop_chars may contain '\0' if @stop_chars_len is + * specified. + * When the operation is finished, @callback will be called. You + * can then call g_data_input_stream_read_upto_finish() to get + * the result of the operation. * - * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free(). - * Since: 2.26 + * Since: 2.24 */ /** - * SECTION:gsettingsbacken: - * @title: GSettingsBackend - * @short_description: Interface for settings backend implementations - * @include: gio/gsettingsbackend.h - * @see_also: #GSettings, #GIOExtensionPoint + * g_data_input_stream_read_upto_finish: + * @stream: a #GDataInputStream + * @result: the #GAsyncResult that was provided to the callback + * @length: (out): a #gsize to get the length of the data read in + * @error: #GError for error reporting * - * The #GSettingsBackend interface defines a generic interface for - * non-strictly-typed data that is stored in a hierarchy. To implement - * an alternative storage backend for #GSettings, you need to implement - * the #GSettingsBackend interface and then make it implement the - * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME. - * The interface defines methods for reading and writing values, a - * method for determining if writing of certain values will fail - * (lockdown) and a change notification mechanism. - * The semantics of the interface are very precisely defined and - * implementations must carefully adhere to the expectations of - * callers that are documented on each of the interface methods. - * Some of the GSettingsBackend functions accept or return a #GTree. - * These trees always have strings as keys and #GVariant as values. - * g_settings_backend_create_tree() is a convenience function to create - * suitable trees. - * <note><para> - * The #GSettingsBackend API is exported to allow third-party - * implementations, but does not carry the same stability guarantees - * as the public GIO API. For this reason, you have to define the - * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including - * <filename>gio/gsettingsbackend.h</filename> - * </para></note> + * Finish an asynchronous call started by + * g_data_input_stream_read_upto_async(). + * Note that this function does <emphasis>not</emphasis> consume the + * stop character. You have to use g_data_input_stream_read_byte() to + * get it before calling g_data_input_stream_read_upto_async() again. + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. + * + * Returns: (transfer full): a string with the data that was read + * Since: 2.24 */ /** - * g_dbus_interface_info_lookup_method: - * @info: A #GDBusInterfaceInfo. - * @name: A D-Bus method name (typically in CamelCase) - * - * Looks up information about a method. - * This cost of this function is O(n) in number of methods. + * g_data_input_stream_set_byte_order: + * @stream: a given #GDataInputStream. + * @order: a #GDataStreamByteOrder to set. * - * Returns: A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. - * Since: 2.26 + * This function sets the byte order for the given @stream. All subsequent + * reads from the @stream will be read in the given @order. */ /** - * GDBusConnection:closed: - * - * A boolean specifying whether the connection has been closed. + * g_data_input_stream_set_newline_type: + * @stream: a #GDataInputStream. + * @type: the type of new line return as #GDataStreamNewlineType. * - * Since: 2.26 + * Sets the newline type for the @stream. + * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read + * chunk ends in "CR" we must read an additional byte to know if this is "CR" or + * "CR LF", and this might block if there is no more data availible. */ /** - * GProxyInterface: - * @g_iface: The parent interface. - * @connect: Connect to proxy server and wrap (if required) the #connection to handle payload. - * @connect_async: Same has connect() but asynchronous. - * @connect_finish: Returns the result of connect_async() + * g_data_output_stream_get_byte_order: + * @stream: a #GDataOutputStream. * - * Provides an interface for handling proxy connection and payload. + * Gets the byte order for the stream. * - * Since: 2.26 + * Returns: the #GDataStreamByteOrder for the @stream. */ /** - * g_zlib_compressor_new: - * @format: The format to use for the compressed data - * @level: compression level (0-9), -1 for default + * g_data_output_stream_new: + * @base_stream: a #GOutputStream. * - * Creates a new #GZlibCompressor. + * Creates a new data output stream for @base_stream. * - * Returns: a new #GZlibCompressor - * Since: 2.24 + * Returns: #GDataOutputStream. */ /** - * g_cancellable_disconnect: - * @cancellable: A #GCancellable or %NULL. - * @handler_id: Handler id of the handler to be disconnected, or %0. + * g_data_output_stream_put_byte: + * @stream: a #GDataOutputStream. + * @data: a #guchar. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * Disconnects a handler from a cancellable instance similar to - * g_signal_handler_disconnect(). Additionally, in the event that a - * signal handler is currently running, this call will block until the - * handler has finished. Calling this function from a - * #GCancellable::cancelled signal handler will therefore result in a - * deadlock. - * This avoids a race condition where a thread cancels at the - * same time as the cancellable operation is finished and the - * signal handler is removed. See #GCancellable::cancelled for - * details on how to use this. - * If @cancellable is %NULL or @handler_id is %0 this function does - * nothing. + * Puts a byte into the output stream. * - * Since: 2.22 + * Returns: %TRUE if @data was successfully added to the @stream. */ /** - * GTlsClientConnection:server-identity: + * g_data_output_stream_put_int16: + * @stream: a #GDataOutputStream. + * @data: a #gint16. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * A #GSocketConnectable describing the identity of the server that - * is expected on the other end of the connection. - * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in - * #GTlsClientConnection:validation-flags, this object will be used - * to determine the expected identify of the remote end of the - * connection; if #GTlsClientConnection:server-identity is not set, - * or does not match the identity presented by the server, then the - * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. - * In addition to its use in verifying the server certificate, - * this is also used to give a hint to the server about what - * certificate we expect, which is useful for servers that serve - * virtual hosts. + * Puts a signed 16-bit integer into the output stream. * - * Since: 2.28 + * Returns: %TRUE if @data was successfully added to the @stream. */ /** - * g_input_stream_skip_finish: - * @stream: a #GInputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_data_output_stream_put_int32: + * @stream: a #GDataOutputStream. + * @data: a #gint32. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * Finishes a stream skip operation. + * Puts a signed 32-bit integer into the output stream. * - * Returns: the size of the bytes skipped, or %-1 on error. + * Returns: %TRUE if @data was successfully added to the @stream. */ /** - * GFileEnumerator: + * g_data_output_stream_put_int64: + * @stream: a #GDataOutputStream. + * @data: a #gint64. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * A per matched file iterator. + * Puts a signed 64-bit integer into the stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. */ /** - * g_resolver_set_default: - * @resolver: the new default #GResolver + * g_data_output_stream_put_string: + * @stream: a #GDataOutputStream. + * @str: a string. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * Sets @resolver to be the application's default resolver (reffing - * Future calls to g_resolver_get_default() will return this resolver. - * This can be used if an application wants to perform any sort of DNS - * caching or "pinning"; it can implement its own #GResolver that - * calls the original default resolver for DNS operations, and - * implements its own cache policies on top of that, and then set - * itself as the default resolver for all later code to use. + * Puts a string into the output stream. * - * Since: 2.22 + * Returns: %TRUE if @string was successfully added to the @stream. */ /** - * g_dbus_annotation_info_unref: - * @info: A #GDBusAnnotationInfo. + * g_data_output_stream_put_uint16: + * @stream: a #GDataOutputStream. + * @data: a #guint16. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. + * Puts an unsigned 16-bit integer into the output stream. * - * Since: 2.26 + * Returns: %TRUE if @data was successfully added to the @stream. */ /** - * g_file_info_set_sort_order: - * @info: a #GFileInfo. - * @sort_order: a sort order integer. + * g_data_output_stream_put_uint32: + * @stream: a #GDataOutputStream. + * @data: a #guint32. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * Sets the sort order attribute in the file info structure. See - * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. + * Puts an unsigned 32-bit integer into the stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. */ /** - * SECTION:goutputstrea: - * @short_description: Base class for implementing streaming output - * @include: gio/gio.h + * g_data_output_stream_put_uint64: + * @stream: a #GDataOutputStream. + * @data: a #guint64. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * GOutputStream has functions to write to a stream (g_output_stream_write()), - * to close a stream (g_output_stream_close()) and to flush pending writes - * (g_output_stream_flush()). - * To copy the content of an input stream to an output stream without - * manually handling the reads and writes, use g_output_stream_splice(). - * All of these functions have async variants too. + * Puts an unsigned 64-bit integer into the stream. + * + * Returns: %TRUE if @data was successfully added to the @stream. */ /** - * SECTION:gmemoryinputstrea: - * @short_description: Streaming input operations on memory chunks - * @include: gio/gio.h - * @see_also: #GMemoryOutputStream + * g_data_output_stream_set_byte_order: + * @stream: a #GDataOutputStream. + * @order: a %GDataStreamByteOrder. * - * #GMemoryInputStream is a class for using arbitrary - * memory chunks as input for GIO streaming input operations. + * Sets the byte order of the data output stream to @order. */ /** - * G_VALUE_HOLDS_UINT: - * @value: a valid #GValue structure + * g_dbus_address_get_for_bus_sync: + * @bus_type: A #GBusType. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Checks whether the given #GValue can hold values of type %G_TYPE_UINT. + * Synchronously looks up the D-Bus address for the well-known message + * bus instance specified by @bus_type. This may involve using various + * platform specific mechanisms. * - * Returns: %TRUE on success. + * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set. + * Since: 2.26 */ /** - * g_action_get_name: - * @action: a #GAction + * g_dbus_address_get_stream: + * @address: A valid D-Bus address. + * @cancellable: A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: Data to pass to @callback. * - * Queries the name of @action. + * Asynchronously connects to an endpoint specified by @address and + * sets up the connection so it is in a state to run the client-side + * of the D-Bus authentication conversation. + * When the operation is finished, @callback will be invoked. You can + * then call g_dbus_address_get_stream_finish() to get the result of + * the operation. + * This is an asynchronous failable function. See + * g_dbus_address_get_stream_sync() for the synchronous version. * - * Returns: the name of the action - * Since: 2.28 + * Since: 2.26 */ /** - * SECTION:gvf: - * @short_description: Virtual File System - * @include: gio/gio.h + * g_dbus_address_get_stream_finish: + * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). + * @out_guid: %NULL or return location to store the GUID extracted from @address, if any. + * @error: Return location for error or %NULL. * - * Entry point for using GIO functionality. + * Finishes an operation started with g_dbus_address_get_stream(). + * + * Returns: (transfer full): A #GIOStream or %NULL if @error is set. + * Since: 2.26 */ /** - * g_file_output_stream_query_info_async: - * @stream: a #GFileOutputStream. - * @attributes: a file attribute query string. - * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: callback to call when the request is satisfied - * @user_data: the data to pass to callback function + * g_dbus_address_get_stream_sync: + * @address: A valid D-Bus address. + * @out_guid: %NULL or return location to store the GUID extracted from @address, if any. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Asynchronously queries the @stream for a #GFileInfo. When completed, - * finish the operation with g_file_output_stream_query_info_finish(). - * For the synchronous version of this function, see - * g_file_output_stream_query_info(). + * Synchronously connects to an endpoint specified by @address and + * sets up the connection so it is in a state to run the client-side + * of the D-Bus authentication conversation. + * This is a synchronous failable function. See + * g_dbus_address_get_stream() for the asynchronous version. + * + * Returns: (transfer full): A #GIOStream or %NULL if @error is set. + * Since: 2.26 */ /** - * g_dbus_connection_remove_filter: - * @connection: a #GDBusConnection - * @filter_id: an identifier obtained from g_dbus_connection_add_filter() + * g_dbus_annotation_info_lookup: + * @annotations: A %NULL-terminated array of annotations or %NULL. + * @name: The name of the annotation to look up. * - * Removes a filter. + * Looks up the value of an annotation. + * This cost of this function is O(n) in number of annotations. * + * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations. * Since: 2.26 */ /** - * G_PARAM_SPEC_GTYPE: - * @pspec: a #GParamSpec + * g_dbus_annotation_info_ref: + * @info: A #GDBusNodeInfo * - * Casts a #GParamSpec into a #GParamSpecGType. + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. * - * Since: 2.10 + * Returns: The same @info. + * Since: 2.26 */ /** - * G_TYPE_ERROR: + * g_dbus_annotation_info_unref: + * @info: A #GDBusAnnotationInfo. * - * The #GType for a boxed type holding a #GError. + * If @info is statically allocated, does nothing. Otherwise decreases + * the reference count of @info. When its reference count drops to 0, + * the memory used is freed. * * Since: 2.26 */ /** - * g_resolver_lookup_by_name: - * @resolver: a #GResolver - * @hostname: the hostname to look up - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL + * g_dbus_arg_info_ref: + * @info: A #GDBusArgInfo * - * Synchronously resolves @hostname to determine its associated IP - * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or - * the textual form of an IP address (in which case this just becomes - * a wrapper around g_inet_address_new_from_string()). - * On success, g_resolver_lookup_by_name() will return a #GList of - * #GInetAddress, sorted in order of preference. (That is, you should - * attempt to connect to the first address first, then the second if - * the first fails, etc.) - * If the DNS resolution fails, @error (if non-%NULL) will be set to a - * value from #GResolverError. - * If @cancellable is non-%NULL, it can be used to cancel the - * operation, in which case @error (if non-%NULL) will be set to - * %G_IO_ERROR_CANCELLED. - * If you are planning to connect to a socket on the resolved IP - * address, it may be easier to create a #GNetworkAddress and use its - * #GSocketConnectable interface. - * of #GInetAddress, or %NULL on error. You - * must unref each of the addresses and free the list when you are - * done with it. (You can use g_resolver_free_addresses() to do this.) + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. * - * Returns: (element-type GInetAddress) (transfer full): a #GList - * Since: 2.22 + * Returns: The same @info. + * Since: 2.26 */ /** - * g_socket_listener_accept_async: - * @listener: a #GSocketListener - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback + * g_dbus_arg_info_unref: + * @info: A #GDBusArgInfo. * - * This is the asynchronous version of g_socket_listener_accept(). - * When the operation is finished @callback will be - * called. You can then call g_socket_listener_accept_socket() - * to get the result of the operation. + * If @info is statically allocated, does nothing. Otherwise decreases + * the reference count of @info. When its reference count drops to 0, + * the memory used is freed. * - * Since: 2.22 + * Since: 2.26 */ /** - * g_mount_unshadow: - * @mount: A #GMount. + * g_dbus_auth_observer_authorize_authenticated_peer: + * @observer: A #GDBusAuthObserver. + * @stream: A #GIOStream for the #GDBusConnection. + * @credentials: Credentials received from the peer or %NULL. * - * Decrements the shadow count on @mount. Usually used by - * #GVolumeMonitor implementations when destroying a shadow mount for - * will need to emit the #GMount::changed signal on @mount manually. + * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. * - * Since: 2.20 + * Returns: %TRUE if the peer is authorized, %FALSE if not. + * Since: 2.26 */ /** - * g_file_info_get_is_backup: - * @info: a #GFileInfo. + * g_dbus_auth_observer_new: * - * Checks if a file is a backup file. + * Creates a new #GDBusAuthObserver object. * - * Returns: %TRUE if file is a backup file, %FALSE otherwise. + * Returns: A #GDBusAuthObserver. Free with g_object_unref(). + * Since: 2.26 */ /** - * G_VARIANT_TYPE_BASIC: + * g_dbus_connection_add_filter: + * @connection: A #GDBusConnection. + * @filter_function: A filter function. + * @user_data: User data to pass to @filter_function. + * @user_data_free_func: Function to free @user_data with when filter is removed or %NULL. * - * An indefinite type that is a supertype of every basic (ie: - * non-container) type. + * Adds a message filter. Filters are handlers that are run on all + * incoming and outgoing messages, prior to standard dispatch. Filters + * are run in the order that they were added. The same handler can be + * added as a filter more than once, in which case it will be run more + * than once. Filters added during a filter callback won't be run on + * the message being processed. Filter functions are allowed to modify + * and even drop messages - see the #GDBusMessageFilterResult + * enumeration for details. + * Note that filters are run in a dedicated message handling thread so + * they can't block and, generally, can't do anything but signal a + * worker thread. Also note that filters are rarely needed - use API + * such as g_dbus_connection_send_message_with_reply(), + * g_dbus_connection_signal_subscribe() or + * g_dbus_connection_call() instead. + * If a filter consumes an incoming message the message is not + * dispatched anywhere else - not even the standard dispatch machinery + * (that API such as g_dbus_connection_signal_subscribe() and + * g_dbus_connection_send_message_with_reply() relies on) will see the + * message. Similary, if a filter consumes an outgoing message, the + * message will not be sent to the other peer. + * g_dbus_connection_remove_filter(). + * + * Returns: A filter identifier that can be used with + * Since: 2.26 */ @@ -16597,1003 +16065,1124 @@ /** - * g_unix_fd_message_get_fd_list: - * @message: a #GUnixFDMessage - * - * Gets the #GUnixFDList contained in @message. This function does not - * return a reference to the caller, but the returned list is valid for - * the lifetime of @message. + * g_dbus_connection_call_finish: + * @connection: A #GDBusConnection. + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call(). + * @error: Return location for error or %NULL. * - * Returns: (transfer none): the #GUnixFDList from @message - * Since: 2.24 - */ - - -/** - * GPid: + * Finishes an operation started with g_dbus_connection_call(). + * return values. Free with g_variant_unref(). * - * A type which is used to hold a process identification. - * On UNIX, processes are identified by a process id (an integer), - * while Windows uses process handles (which are pointers). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * Since: 2.26 */ /** - * g_filter_input_stream_get_base_stream: - * @stream: a #GFilterInputStream. + * g_dbus_connection_call_sync: + * @connection: A #GDBusConnection. + * @bus_name: A unique or well-known bus name. + * @object_path: Path of remote object. + * @interface_name: D-Bus interface to invoke method on. + * @method_name: The name of the method to invoke. + * @parameters: A #GVariant tuple with parameters for the method or %NULL if not passing parameters. + * @reply_type: The expected type of the reply, or %NULL. + * @flags: Flags from the #GDBusCallFlags enumeration. + * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Gets the base stream for the filter stream. + * Synchronously invokes the @method_name method on the + * If @connection is closed then the operation will fail with + * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the + * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters + * contains a value not compatible with the D-Bus protocol, the operation + * fails with %G_IO_ERROR_INVALID_ARGUMENT. + * If @reply_type is non-%NULL then the reply will be checked for having + * this type and an error will be raised if it does not match. Said + * another way, if you give a @reply_type then any non-%NULL return + * value will be of this type. + * If the @parameters #GVariant is floating, it is consumed. + * This allows convenient 'inline' use of g_variant_new(), e.g.: + * |[ + * g_dbus_connection_call_sync (connection, + * "org.freedesktop.StringThings", + * "/org/freedesktop/StringThings", + * "org.freedesktop.StringThings", + * "TwoStrings", + * g_variant_new ("(ss)", + * "Thing One", + * "Thing Two"), + * NULL, + * G_DBUS_CALL_FLAGS_NONE, + * -1, + * NULL, + * &error); + * ]| + * The calling thread is blocked until a reply is received. See + * g_dbus_connection_call() for the asynchronous version of + * this method. + * return values. Free with g_variant_unref(). * - * Returns: (transfer none): a #GInputStream. + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * Since: 2.26 */ /** - * g_data_input_stream_get_byte_order: - * @stream: a given #GDataInputStream. + * g_dbus_connection_close: + * @connection: A #GDBusConnection. + * @cancellable: A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. + * @user_data: The data to pass to @callback. * - * Gets the byte order for the data input stream. + * Closes @connection. Note that this never causes the process to + * exit (this might only happen if the other end of a shared message + * bus connection disconnects, see #GDBusConnection:exit-on-close). + * Once the connection is closed, operations such as sending a message + * will return with the error %G_IO_ERROR_CLOSED. Closing a connection + * will not automatically flush the connection so queued messages may + * be lost. Use g_dbus_connection_flush() if you need such guarantees. + * If @connection is already closed, this method fails with + * %G_IO_ERROR_CLOSED. + * When @connection has been closed, the #GDBusConnection::closed + * signal is emitted in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread that @connection was constructed in. + * This is an asynchronous method. When the operation is finished, + * linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread you are calling this method from. You can + * then call g_dbus_connection_close_finish() to get the result of the + * operation. See g_dbus_connection_close_sync() for the synchronous + * version. * - * Returns: the @stream's current #GDataStreamByteOrder. + * Since: 2.26 */ /** - * G_IS_OBJECT_CLASS: - * @class: a #GObjectClass + * g_dbus_connection_close_finish: + * @connection: A #GDBusConnection. + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close(). + * @error: Return location for error or %NULL. * - * Checks whether @class "is a" valid #GObjectClass structure of type - * %G_TYPE_OBJECT or derived. - */ - - -/** - * GProxyResolver: + * Finishes an operation started with g_dbus_connection_close(). * - * Interface that can be used to resolve proxy address. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Since: 2.26 */ /** - * G_TLS_BACKEND_EXTENSION_POINT_NAME: + * g_dbus_connection_close_sync: + * @connection: A #GDBusConnection. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Extension point for TLS functionality via #GTlsBackend. - * See <link linkend="extending-gio">Extending GIO</link>. - */ - - -/** - * SECTION:gdbuserro: - * @title: GDBusError - * @short_description: Mapping D-Bus errors to and from GError - * @include: gio/gio.h + * Synchronously closees @connection. The calling thread is blocked + * until this is done. See g_dbus_connection_close() for the + * asynchronous version of this method and more details about what it + * does. * - * All facilities that return errors from remote methods (such as - * g_dbus_connection_call_sync()) use #GError to represent both D-Bus - * errors (e.g. errors returned from the other peer) and locally - * in-process generated errors. - * To check if a returned #GError is an error from a remote peer, use - * g_dbus_error_is_remote_error(). To get the actual D-Bus error name, - * use g_dbus_error_get_remote_error(). Before presenting an error, - * always use g_dbus_error_strip_remote_error(). - * In addition, facilities used to return errors to a remote peer also - * use #GError. See g_dbus_method_invocation_return_error() for - * discussion about how the D-Bus error name is set. - * Applications can associate a #GError error domain with a set of D-Bus errors in order to - * automatically map from D-Bus errors to #GError and back. This - * is typically done in the function returning the #GQuark for the - * error domain: - * <example id="error-registration"><title>Error Registration</title><programlisting> - * /<!-- -->* foo-bar-error.h: *<!-- -->/ - * #define FOO_BAR_ERROR (foo_bar_error_quark ()) - * GQuark foo_bar_error_quark (void); - * typedef enum - * { - * FOO_BAR_ERROR_FAILED, - * FOO_BAR_ERROR_ANOTHER_ERROR, - * FOO_BAR_ERROR_SOME_THIRD_ERROR, - * } FooBarError; - * /<!-- -->* foo-bar-error.c: *<!-- -->/ - * static const GDBusErrorEntry foo_bar_error_entries[] = - * { - * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"}, - * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"}, - * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, - * }; - * GQuark - * foo_bar_error_quark (void) - * { - * static volatile gsize quark_volatile = 0; - * g_dbus_error_register_error_domain ("foo-bar-error-quark", - * &quark_volatile, - * foo_bar_error_entries, - * G_N_ELEMENTS (foo_bar_error_entries)); - * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) - 1 == FOO_BAR_ERROR_SOME_THIRD_ERROR); - * return (GQuark) quark_volatile; - * } - * </programlisting></example> - * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and - * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>. - * If the other peer is using GDBus, the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead - * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover - * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error(). - * Note that errors in the %G_DBUS_ERROR error domain is intended only - * for returning errors from a remote message bus process. Errors - * generated locally in-process by e.g. #GDBusConnection is from the - * %G_IO_ERROR domain. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Since: 2.26 */ /** - * g_seekable_truncate: - * @seekable: a #GSeekable. - * @offset: a #goffset. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_dbus_connection_emit_signal: + * @connection: A #GDBusConnection. + * @destination_bus_name: The unique bus name for the destination for the signal or %NULL to emit to all listeners. + * @object_path: Path of remote object. + * @interface_name: D-Bus interface to emit a signal on. + * @signal_name: The name of the signal to emit. + * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @error: Return location for error or %NULL. * - * Truncates a stream with a given #offset. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * has occurred, this function will return %FALSE and set @error - * appropriately if present. + * Emits a signal. + * If the parameters GVariant is floating, it is consumed. + * This can only fail if @parameters is not compatible with the D-Bus protocol. * - * Virtual: truncate_fn - * Returns: %TRUE if successful. If an error + * Returns: %TRUE unless @error is set. + * Since: 2.26 */ /** - * g_dbus_message_new_method_error: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. - * @error_name: A valid D-Bus error name. - * @error_message_format: The D-Bus error message in a printf() format. - * @...: Arguments for @error_message_format. + * g_dbus_connection_flush: + * @connection: A #GDBusConnection. + * @cancellable: A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. + * @user_data: The data to pass to @callback. * - * Creates a new #GDBusMessage that is an error reply to @method_call_message. + * Asynchronously flushes @connection, that is, writes all queued + * outgoing message to the transport and then flushes the transport + * (using g_output_stream_flush_async()). This is useful in programs + * that wants to emit a D-Bus signal and then exit + * immediately. Without flushing the connection, there is no guarantee + * that the message has been sent to the networking buffers in the OS + * kernel. + * This is an asynchronous method. When the operation is finished, + * linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread you are calling this method from. You can + * then call g_dbus_connection_flush_finish() to get the result of the + * operation. See g_dbus_connection_flush_sync() for the synchronous + * version. * - * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). * Since: 2.26 */ /** - * g_volume_eject_with_operation: - * @volume: a #GVolume. - * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * g_dbus_connection_flush_finish: + * @connection: A #GDBusConnection. + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush(). + * @error: Return location for error or %NULL. * - * Ejects a volume. This is an asynchronous operation, and is - * finished by calling g_volume_eject_with_operation_finish() with the @volume - * and #GAsyncResult data returned in the @callback. + * Finishes an operation started with g_dbus_connection_flush(). * - * Since: 2.22 + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Since: 2.26 */ /** - * g_settings_bind: - * @settings: a #GSettings object - * @key: the key to bind - * @object: (type GObject.Object): a #GObject - * @property: the name of the property to bind - * @flags: flags for the binding + * g_dbus_connection_flush_sync: + * @connection: A #GDBusConnection. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Create a binding between the @key in the @settings object - * and the property @property of @object. - * The binding uses the default GIO mapping functions to map - * between the settings and property values. These functions - * handle booleans, numeric types and string types in a - * straightforward way. Use g_settings_bind_with_mapping() if - * you need a custom mapping, or map between types that are not - * supported by the default mapping functions. - * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this - * function also establishes a binding between the writability of - * a boolean property by that name). See g_settings_bind_writable() - * for more details about writable bindings. - * Note that the lifecycle of the binding is tied to the object, - * and that you can have only one binding per object property. - * If you bind the same property twice on the same object, the second - * binding overrides the first one. + * Synchronously flushes @connection. The calling thread is blocked + * until this is done. See g_dbus_connection_flush() for the + * asynchronous version of this method and more details about what it + * does. * + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. * Since: 2.26 */ /** - * g_socket_client_connect_to_host_async: - * @client: a #GTcpClient - * @host_and_port: the name and optionally the port of the host to connect to - * @default_port: the default port to connect to - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback + * g_dbus_connection_get_capabilities: + * @connection: A #GDBusConnection. * - * This is the asynchronous version of g_socket_client_connect_to_host(). - * When the operation is finished @callback will be - * called. You can then call g_socket_client_connect_to_host_finish() to get - * the result of the operation. + * Gets the capabilities negotiated with the remote peer * - * Since: 2.22 + * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration. + * Since: 2.26 */ /** - * GInitiallyUnownedClass: + * g_dbus_connection_get_exit_on_close: + * @connection: A #GDBusConnection. * - * The class structure for the <structname>GInitiallyUnowned</structname> type. - */ - - -/** - * g_file_info_set_content_type: - * @info: a #GFileInfo. - * @content_type: a content type. See #GContentType. + * Gets whether the process is terminated when @connection is + * closed by the remote peer. See + * #GDBusConnection:exit-on-close for more details. + * closed by the remote peer. * - * Sets the content type attribute for a given #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. + * Returns: Whether the process is terminated when @connection is + * Since: 2.26 */ /** - * g_dbus_proxy_get_flags: - * @proxy: A #GDBusProxy. + * g_dbus_connection_get_guid: + * @connection: A #GDBusConnection. * - * Gets the flags that @proxy was constructed with. + * The GUID of the peer performing the role of server when + * authenticating. See #GDBusConnection:guid for more details. * - * Returns: Flags from the #GDBusProxyFlags enumeration. + * Returns: The GUID. Do not free this string, it is owned by * Since: 2.26 */ /** - * GAppInfoCreateFlags: - * @G_APP_INFO_CREATE_NONE: No flags. - * @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens in a terminal window. - * @G_APP_INFO_CREATE_SUPPORTS_URIS: Application supports URI arguments. - * @G_APP_INFO_CREATE_SUPPORTS_STARTUP_NOTIFICATION: Application supports startup notification. Since 2.26 - * - * Flags used when creating a #GAppInfo. - */ - - -/** - * g_unix_fd_list_new_from_array: - * @fds: (array length=n_fds): the initial list of file descriptors - * @n_fds: the length of #fds, or -1 - * - * Creates a new #GUnixFDList containing the file descriptors given in - * may no longer be used by the caller. The array itself is owned by - * the caller. - * Each file descriptor in the array should be set to close-on-exec. - * If @n_fds is -1 then @fds must be terminated with -1. + * g_dbus_connection_get_peer_credentials: + * @connection: A #GDBusConnection. * - * Returns: a new #GUnixFDList - * Since: 2.24 - */ - - -/** - * g_loadable_icon_load_async: - * @icon: a #GLoadableIcon. - * @size: an integer. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * Gets the credentials of the authenticated peer. This will always + * return %NULL unless @connection acted as a server + * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) + * when set up and the client passed credentials as part of the + * authentication process. + * In a message bus setup, the message bus is always the server and + * each application is a client. So this method will always return + * %NULL for message bus clients. + * this object, it is owned by @connection. * - * Loads an icon asynchronously. To finish this function, see - * g_loadable_icon_load_finish(). For the synchronous, blocking - * version of this function, see g_loadable_icon_load(). + * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free + * Since: 2.26 */ /** - * g_dbus_message_new_from_blob: - * @blob: A blob represent a binary D-Bus message. - * @blob_len: The length of @blob. - * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported. - * @error: Return location for error or %NULL. + * g_dbus_connection_get_stream: + * @connection: a #GDBusConnection * - * Creates a new #GDBusMessage from the data stored at @blob. The byte - * order that the message was in can be retrieved using - * g_dbus_message_get_byte_order(). - * g_object_unref(). + * Gets the underlying stream used for IO. * - * Returns: A new #GDBusMessage or %NULL if @error is set. Free with + * Returns: (transfer none): the stream used for IO * Since: 2.26 */ /** - * G_TYPE_CLASS_GET_PRIVATE: - * @klass: the class of a type deriving from @private_type. - * @g_type: the type identifying which private data to retrieve. - * @c_type: The C type for the private structure. + * g_dbus_connection_get_unique_name: + * @connection: A #GDBusConnection. * - * Gets the private class structure for a particular type. - * The private structure must have been registered in the - * get_type() function with g_type_add_class_private(). - * This macro should only be used in type implementations. + * Gets the unique name of @connection as assigned by the message + * bus. This can also be used to figure out if @connection is a + * message bus connection. + * bus connection. Do not free this string, it is owned by * - * Since: 2.24 - * Returns: a pointer to the private data structure. + * Returns: The unique name or %NULL if @connection is not a message + * Since: 2.26 */ /** - * g_dbus_error_set_dbus_error: - * @error: A pointer to a #GError or %NULL. - * @dbus_error_name: D-Bus error name. - * @dbus_error_message: D-Bus error message. - * @format: printf()-style format to prepend to @dbus_error_message or %NULL. - * @...: Arguments for @format. + * g_dbus_connection_is_closed: + * @connection: A #GDBusConnection. * - * Does nothing if @error is %NULL. Otherwise sets *@error to - * a new #GError created with g_dbus_error_new_for_dbus_error() - * with @dbus_error_message prepend with @format (unless %NULL). + * Gets whether @connection is closed. * + * Returns: %TRUE if the connection is closed, %FALSE otherwise. * Since: 2.26 */ /** - * g_file_query_info_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @error: a #GError. + * g_dbus_connection_new: + * @stream: A #GIOStream. + * @guid: The GUID to use if a authenticating as a server or %NULL. + * @flags: Flags describing how to make the connection. + * @observer: A #GDBusAuthObserver or %NULL. + * @cancellable: A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: The data to pass to @callback. * - * Finishes an asynchronous file info query. - * See g_file_query_info_async(). - * Free the returned object with g_object_unref(). + * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages + * with the end represented by @stream. + * If @observer is not %NULL it may be used to control the + * authentication process. + * When the operation is finished, @callback will be invoked. You can + * then call g_dbus_connection_new_finish() to get the result of the + * operation. + * This is a asynchronous failable constructor. See + * g_dbus_connection_new_sync() for the synchronous + * version. * - * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. + * Since: 2.26 */ /** - * GDBusConnection:unique-name: + * g_dbus_connection_new_finish: + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). + * @error: Return location for error or %NULL. * - * The unique name as assigned by the message bus or %NULL if the - * connection is not open or not a message bus connection. + * Finishes an operation started with g_dbus_connection_new(). * + * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). * Since: 2.26 */ /** - * g_file_attribute_info_list_lookup: - * @list: a #GFileAttributeInfoList. - * @name: the name of the attribute to lookup. - * - * Gets the file attribute with the name @name from @list. - * attribute isn't found. + * g_dbus_connection_new_for_address: + * @address: A D-Bus address. + * @flags: Flags describing how to make the connection. + * @observer: A #GDBusAuthObserver or %NULL. + * @cancellable: A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied. + * @user_data: The data to pass to @callback. * - * Returns: a #GFileAttributeInfo for the @name, or %NULL if an - */ - - -/** - * G_PARAM_SPEC_POINTER: - * @pspec: a valid #GParamSpec instance + * Asynchronously connects and sets up a D-Bus client connection for + * exchanging D-Bus messages with an endpoint specified by @address + * which must be in the D-Bus address format. + * This constructor can only be used to initiate client-side + * connections - use g_dbus_connection_new() if you need to act as the + * server. In particular, @flags cannot contain the + * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or + * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags. + * When the operation is finished, @callback will be invoked. You can + * then call g_dbus_connection_new_finish() to get the result of the + * operation. + * If @observer is not %NULL it may be used to control the + * authentication process. + * This is a asynchronous failable constructor. See + * g_dbus_connection_new_for_address_sync() for the synchronous + * version. * - * Casts a #GParamSpec instance into a #GParamSpecPointer. + * Since: 2.26 */ /** - * g_file_enumerator_close_finish: - * @enumerator: a #GFileEnumerator. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_dbus_connection_new_for_address_finish: + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). + * @error: Return location for error or %NULL. * - * Finishes closing a file enumerator, started from g_file_enumerator_close_async(). - * If the file enumerator was already closed when g_file_enumerator_close_async() - * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and - * return %FALSE. If the file enumerator had pending operation when the close - * operation was started, then this function will report %G_IO_ERROR_PENDING, and - * return %FALSE. If @cancellable was not %NULL, then the operation may have been - * cancelled by triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be - * returned. + * Finishes an operation started with g_dbus_connection_new_for_address(). * - * Returns: %TRUE if the close operation has finished successfully. + * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Since: 2.26 */ /** - * GSimpleAction:name: + * g_dbus_connection_new_for_address_sync: + * @address: A D-Bus address. + * @flags: Flags describing how to make the connection. + * @observer: A #GDBusAuthObserver or %NULL. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * The name of the action. This is mostly meaningful for identifying - * the action once it has been added to a #GSimpleActionGroup. + * Synchronously connects and sets up a D-Bus client connection for + * exchanging D-Bus messages with an endpoint specified by @address + * which must be in the D-Bus address format. + * This constructor can only be used to initiate client-side + * connections - use g_dbus_connection_new_sync() if you need to act + * as the server. In particular, @flags cannot contain the + * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or + * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags. + * This is a synchronous failable constructor. See + * g_dbus_connection_new_for_address() for the asynchronous version. + * If @observer is not %NULL it may be used to control the + * authentication process. * - * Since: 2.28 + * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Since: 2.26 */ /** - * g_app_info_set_as_default_for_type: - * @appinfo: a #GAppInfo. - * @content_type: the content type. - * @error: a #GError. + * g_dbus_connection_new_sync: + * @stream: A #GIOStream. + * @guid: The GUID to use if a authenticating as a server or %NULL. + * @flags: Flags describing how to make the connection. + * @observer: A #GDBusAuthObserver or %NULL. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Sets the application as the default handler for a given type. + * Synchronously sets up a D-Bus connection for exchanging D-Bus messages + * with the end represented by @stream. + * If @observer is not %NULL it may be used to control the + * authentication process. + * This is a synchronous failable constructor. See + * g_dbus_connection_new() for the asynchronous version. * - * Returns: %TRUE on success, %FALSE on error. + * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Since: 2.26 */ /** - * GSimpleAsyncThreadFunc: - * @res: a #GSimpleAsyncResult. - * @object: a #GObject. - * @cancellable: optional #GCancellable object, %NULL to ignore. + * g_dbus_connection_register_object: + * @connection: A #GDBusConnection. + * @object_path: The object path to register at. + * @interface_info: Introspection data for the interface. + * @vtable: A #GDBusInterfaceVTable to call into or %NULL. + * @user_data: Data to pass to functions in @vtable. + * @user_data_free_func: Function to call when the object path is unregistered. + * @error: Return location for error or %NULL. * - * Simple thread function that runs an asynchronous operation and - * checks for cancellation. + * Registers callbacks for exported objects at @object_path with the + * D-Bus interface that is described in @interface_info. + * Calls to functions in @vtable (and @user_data_free_func) will + * happen in the <link linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread you are calling this method from. + * Note that all #GVariant values passed to functions in @vtable will match + * the signature given in @interface_info - if a remote caller passes + * incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> + * is returned to the remote caller. + * Additionally, if the remote caller attempts to invoke methods or + * access properties not mentioned in @interface_info the + * <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp. + * <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors + * are returned to the caller. + * It is considered a programming error if the + * #GDBusInterfaceGetPropertyFunc function in @vtable returns a + * #GVariant of incorrect type. + * If an existing callback is already registered at @object_path and + * GDBus automatically implements the standard D-Bus interfaces + * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable + * and org.freedesktop.Peer, so you don't have to implement those for + * the objects you export. You <emphasis>can</emphasis> implement + * org.freedesktop.DBus.Properties yourself, e.g. to handle getting + * and setting of properties asynchronously. + * Note that the reference count on @interface_info will be + * incremented by 1 (unless allocated statically, e.g. if the + * reference count is -1, see g_dbus_interface_info_ref()) for as long + * as the object is exported. Also note that @vtable will be copied. + * See <xref linkend="gdbus-server"/> for an example of how to use this method. + * that can be used with g_dbus_connection_unregister_object() . + * + * Returns: 0 if @error is set, otherwise a registration id (never 0) + * Since: 2.26 */ /** - * g_filter_input_stream_get_close_base_stream: - * @stream: a #GFilterInputStream. + * g_dbus_connection_register_subtree: + * @connection: A #GDBusConnection. + * @object_path: The object path to register the subtree at. + * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree. + * @flags: Flags used to fine tune the behavior of the subtree. + * @user_data: Data to pass to functions in @vtable. + * @user_data_free_func: Function to call when the subtree is unregistered. + * @error: Return location for error or %NULL. * - * Returns whether the base stream will be closed when @stream is - * closed. + * Registers a whole subtree of <quote>dynamic</quote> objects. + * The @enumerate and @introspection functions in @vtable are used to + * convey, to remote callers, what nodes exist in the subtree rooted + * by @object_path. + * When handling remote calls into any node in the subtree, first the + * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set + * the @introspection function is used to check if the node supports the + * requested method. If so, the @dispatch function is used to determine + * where to dispatch the call. The collected #GDBusInterfaceVTable and + * #gpointer will be used to call into the interface vtable for processing + * the request. + * All calls into user-provided code will be invoked in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread you are calling this method from. + * If an existing subtree is already registered at @object_path or + * then @error is set to #G_IO_ERROR_EXISTS. + * Note that it is valid to register regular objects (using + * g_dbus_connection_register_object()) in a subtree registered with + * g_dbus_connection_register_subtree() - if so, the subtree handler + * is tried as the last resort. One way to think about a subtree + * handler is to consider it a <quote>fallback handler</quote> + * for object paths not registered via g_dbus_connection_register_object() + * or other bindings. + * Note that @vtable will be copied so you cannot change it after + * registration. + * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method. + * that can be used with g_dbus_connection_unregister_subtree() . * - * Returns: %TRUE if the base stream will be closed. + * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) + * Since: 2.26 */ /** - * GDBusMessageType: - * @G_DBUS_MESSAGE_TYPE_INVALID: Message is of invalid type. - * @G_DBUS_MESSAGE_TYPE_METHOD_CALL: Method call. - * @G_DBUS_MESSAGE_TYPE_METHOD_RETURN: Method reply. - * @G_DBUS_MESSAGE_TYPE_ERROR: Error reply. - * @G_DBUS_MESSAGE_TYPE_SIGNAL: Signal emission. + * g_dbus_connection_remove_filter: + * @connection: a #GDBusConnection + * @filter_id: an identifier obtained from g_dbus_connection_add_filter() * - * Message types used in #GDBusMessage. + * Removes a filter. * * Since: 2.26 */ /** - * GBookmarkFile: + * g_dbus_connection_send_message: + * @connection: A #GDBusConnection. + * @message: A #GDBusMessage + * @flags: Flags affecting how the message is sent. + * @out_serial: Return location for serial number assigned to @message when sending it or %NULL. + * @error: Return location for error or %NULL. * - * The <structname>GBookmarkFile</structname> struct contains only - * private data and should not be directly accessed. - */ - - -/** - * G_VARIANT_TYPE_INT16: + * Asynchronously sends @message to the peer represented by @connection. + * Unless @flags contain the + * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number + * will be assigned by @connection and set on @message via + * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the + * serial number used will be written to this location prior to + * submitting the message to the underlying transport. + * If @connection is closed then the operation will fail with + * %G_IO_ERROR_CLOSED. If @message is not well-formed, + * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. + * See <xref linkend="gdbus-server"/> and <xref + * linkend="gdbus-unix-fd-client"/> for an example of how to use this + * low-level API to send and receive UNIX file descriptors. + * Note that @message must be unlocked, unless @flags contain the + * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. + * transmission, %FALSE if @error is set. * - * The type of an integer value that can range from -32768 to 32767. + * Returns: %TRUE if the message was well-formed and queued for + * Since: 2.26 */ /** - * g_io_stream_clear_pending: - * @stream: a #GIOStream + * g_dbus_connection_send_message_with_reply: + * @connection: A #GDBusConnection. + * @message: A #GDBusMessage. + * @flags: Flags affecting how the message is sent. + * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. + * @out_serial: Return location for serial number assigned to @message when sending it or %NULL. + * @cancellable: A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. + * @user_data: The data to pass to @callback. * - * Clears the pending flag on @stream. + * Asynchronously sends @message to the peer represented by @connection. + * Unless @flags contain the + * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number + * will be assigned by @connection and set on @message via + * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the + * serial number used will be written to this location prior to + * submitting the message to the underlying transport. + * If @connection is closed then the operation will fail with + * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will + * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, + * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. + * This is an asynchronous method. When the operation is finished, @callback will be invoked + * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link> + * of the thread you are calling this method from. You can then call + * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. + * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. + * Note that @message must be unlocked, unless @flags contain the + * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. + * See <xref linkend="gdbus-server"/> and <xref + * linkend="gdbus-unix-fd-client"/> for an example of how to use this + * low-level API to send and receive UNIX file descriptors. * - * Since: 2.22 + * Since: 2.26 */ /** - * g_permission_release_async: - * @permission: a #GPermission instance - * @cancellable: a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback to call when done - * @user_data: the user data to pass to @callback + * g_dbus_connection_send_message_with_reply_finish: + * @connection: a #GDBusConnection + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply(). + * @error: Return location for error or %NULL. * - * Attempts to release the permission represented by @permission. - * This is the first half of the asynchronous version of - * g_permission_release(). + * Finishes an operation started with g_dbus_connection_send_message_with_reply(). + * Note that @error is only set if a local in-process error + * occured. That is to say that the returned #GDBusMessage object may + * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use + * g_dbus_message_to_gerror() to transcode this to a #GError. + * See <xref linkend="gdbus-server"/> and <xref + * linkend="gdbus-unix-fd-client"/> for an example of how to use this + * low-level API to send and receive UNIX file descriptors. * + * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set. * Since: 2.26 */ /** - * g_tls_connection_get_certificate: - * @conn: a #GTlsConnection + * g_dbus_connection_send_message_with_reply_sync: + * @connection: A #GDBusConnection. + * @message: A #GDBusMessage. + * @flags: Flags affecting how the message is sent. + * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. + * @out_serial: Return location for serial number assigned to @message when sending it or %NULL. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Gets @conn's certificate, as set by - * g_tls_connection_set_certificate(). + * Synchronously sends @message to the peer represented by @connection + * and blocks the calling thread until a reply is received or the + * timeout is reached. See g_dbus_connection_send_message_with_reply() + * for the asynchronous version of this method. + * Unless @flags contain the + * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number + * will be assigned by @connection and set on @message via + * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the + * serial number used will be written to this location prior to + * submitting the message to the underlying transport. + * If @connection is closed then the operation will fail with + * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will + * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, + * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. + * Note that @error is only set if a local in-process error + * occured. That is to say that the returned #GDBusMessage object may + * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use + * g_dbus_message_to_gerror() to transcode this to a #GError. + * See <xref linkend="gdbus-server"/> and <xref + * linkend="gdbus-unix-fd-client"/> for an example of how to use this + * low-level API to send and receive UNIX file descriptors. + * Note that @message must be unlocked, unless @flags contain the + * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. * - * Returns: (transfer none): @conn's certificate, or %NULL - * Since: 2.28 + * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set. + * Since: 2.26 */ /** - * g_unix_mount_guess_name: - * @mount_entry: a #GUnixMountEntry + * g_dbus_connection_set_exit_on_close: + * @connection: A #GDBusConnection. + * @exit_on_close: Whether the process should be terminated when @connection is closed by the remote peer. * - * Guesses the name of a Unix mount. - * The result is a translated string. - * be freed with g_free() + * Sets whether the process should be terminated when @connection is + * closed by the remote peer. See #GDBusConnection:exit-on-close for + * more details. * - * Returns: A newly allocated string that must + * Since: 2.26 */ /** - * GDBusConnection:exit-on-close: + * g_dbus_connection_signal_subscribe: + * @connection: A #GDBusConnection. + * @sender: Sender name to match on (unique or well-known name) or %NULL to listen from all senders. + * @interface_name: D-Bus interface name to match on or %NULL to match on all interfaces. + * @member: D-Bus signal name to match on or %NULL to match on all signals. + * @object_path: Object path to match on or %NULL to match on all object paths. + * @arg0: Contents of first string argument to match on or %NULL to match on all kinds of arguments. + * @flags: Flags describing how to subscribe to the signal (currently unused). + * @callback: Callback to invoke when there is a signal matching the requested data. + * @user_data: User data to pass to @callback. + * @user_data_free_func: Function to free @user_data with when subscription is removed or %NULL. * - * A boolean specifying whether the process will be terminated (by - * calling <literal>raise(SIGTERM)</literal>) if the connection - * is closed by the remote peer. + * Subscribes to signals on @connection and invokes @callback with a + * whenever the signal is received. Note that @callback + * will be invoked in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread you are calling this method from. + * If @connection is not a message bus connection, @sender must be + * %NULL. + * If @sender is a well-known name note that @callback is invoked with + * the unique name for the owner of @sender, not the well-known name + * as one would expect. This is because the message bus rewrites the + * name. As such, to avoid certain race conditions, users should be + * tracking the name owner of the well-known name and use that when + * processing the received signal. * + * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe(). * Since: 2.26 */ /** - * g_hash_table_freeze: - * @hash_table: a #GHashTable + * g_dbus_connection_signal_unsubscribe: + * @connection: A #GDBusConnection. + * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe(). * - * This function is deprecated and will be removed in the next major - * release of GLib. It does nothing. - */ - - -/** - * G_VARIANT_TYPE_OBJECT_PATH: + * Unsubscribes from signals. * - * The type of a DBus object reference. These are strings of a - * specific format used to identify objects at a given destination on - * the bus. - * If you are not interacting with DBus, then there is no reason to make - * use of this type. If you are, then the DBus specification contains a - * precise description of valid object paths. + * Since: 2.26 */ /** - * g_simple_async_result_get_source_tag: (skip) - * @simple: a #GSimpleAsyncResult. + * g_dbus_connection_start_message_processing: + * @connection: A #GDBusConnection. * - * Gets the source tag for the #GSimpleAsyncResult. + * If @connection was created with + * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method + * starts processing messages. Does nothing on if @connection wasn't + * created with this flag or if the method has already been called. * - * Returns: a #gpointer to the source object for the #GSimpleAsyncResult. + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_OWNER_USER_REAL: + * g_dbus_connection_unregister_object: + * @connection: A #GDBusConnection. + * @registration_id: A registration id obtained from g_dbus_connection_register_object(). * - * A key in the "owner" namespace for getting the real name of the - * user that owns the file. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. - */ - - -/** - * GObject: + * Unregisters an object. * - * All the fields in the <structname>GObject</structname> structure are private - * to the #GObject implementation and should never be accessed directly. + * Returns: %TRUE if the object was unregistered, %FALSE otherwise. + * Since: 2.26 */ /** - * SECTION:gemble: - * @short_description: An object for emblems - * @include: gio/gio.h - * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon + * g_dbus_connection_unregister_subtree: + * @connection: A #GDBusConnection. + * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree(). * - * #GEmblem is an implementation of #GIcon that supports - * having an emblem, which is an icon with additional properties. - * It can than be added to a #GEmblemedIcon. - * Currently, only metainformation about the emblem's origin is - * supported. More may be added in the future. + * Unregisters a subtree. + * + * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise. + * Since: 2.26 */ /** - * g_threaded_socket_service_new: - * @max_threads: the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit + * g_dbus_error_encode_gerror: + * @error: A #GError. * - * Creates a new #GThreadedSocketService with no listeners. Listeners - * must be added with g_socket_service_add_listeners(). + * Creates a D-Bus error name to use for @error. If @error matches + * a registered error (cf. g_dbus_error_register_error()), the corresponding + * D-Bus error name will be returned. + * Otherwise the a name of the form + * <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal> + * will be used. This allows other GDBus applications to map the error + * on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). + * This function is typically only used in object mappings to put a + * #GError on the wire. Regular applications should not use it. * - * Returns: a new #GSocketService. - * Since: 2.22 + * Returns: A D-Bus error name (never %NULL). Free with g_free(). + * Since: 2.26 */ /** - * g_pollable_source_new: (skip) - * @pollable_stream: the stream associated with the new source + * g_dbus_error_get_remote_error: + * @error: A #GError. * - * Utility method for #GPollableInputStream and #GPollableOutputStream - * implementations. Creates a new #GSource that expects a callback of - * type #GPollableSourceFunc. The new source does not actually do - * anything on its own; use g_source_add_child_source() to add other - * sources to it to cause it to trigger. + * Gets the D-Bus error name used for @error, if any. + * This function is guaranteed to return a D-Bus error name for all + * #GError<!-- -->s returned from functions handling remote method + * calls (e.g. g_dbus_connection_call_finish()) unless + * g_dbus_error_strip_remote_error() has been used on @error. * - * Returns: (transfer full): the new #GSource. - * Since: 2.28 + * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free(). + * Since: 2.26 */ /** - * G_IMPLEMENT_INTERFACE: - * @TYPE_IFACE: The #GType of the interface to add - * @iface_init: The interface init function + * g_dbus_error_is_remote_error: + * @error: A #GError. * - * A convenience macro to ease interface addition in the @_C_ section - * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). - * See G_DEFINE_TYPE_EXTENDED() for an example. - * Note that this macro can only be used together with the G_DEFINE_TYPE_* - * macros, since it depends on variable names from those macros. + * Checks if @error represents an error received via D-Bus from a remote peer. If so, + * use g_dbus_error_get_remote_error() to get the name of the error. + * %FALSE otherwise. * - * Since: 2.4 + * Returns: %TRUE if @error represents an error from a remote peer, + * Since: 2.26 */ /** - * g_file_monitor_cancel: - * @monitor: a #GFileMonitor. + * g_dbus_error_new_for_dbus_error: + * @dbus_error_name: D-Bus error name. + * @dbus_error_message: D-Bus error message. * - * Cancels a file monitor. + * Creates a #GError based on the contents of @dbus_error_name and + * Errors registered with g_dbus_error_register_error() will be looked + * up using @dbus_error_name and if a match is found, the error domain + * and code is used. Applications can use g_dbus_error_get_remote_error() + * to recover @dbus_error_name. + * If a match against a registered error is not found and the D-Bus + * error name is in a form as returned by g_dbus_error_encode_gerror() + * the error domain and code encoded in the name is used to + * create the #GError. Also, @dbus_error_name is added to the error message + * such that it can be recovered with g_dbus_error_get_remote_error(). + * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR + * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is + * added to the error message such that it can be recovered with + * g_dbus_error_get_remote_error(). + * In all three cases, @dbus_error_name can always be recovered from the + * returned #GError using the g_dbus_error_get_remote_error() function + * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error). + * This function is typically only used in object mappings to prepare + * #GError instances for applications. Regular applications should not use + * it. * - * Returns: %TRUE if monitor was cancelled. + * Returns: An allocated #GError. Free with g_error_free(). + * Since: 2.26 */ /** - * SECTION:gfileiostrea: - * @short_description: File read and write streaming operations - * @include: gio/gio.h - * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable + * g_dbus_error_register_error: + * @error_domain: A #GQuark for a error domain. + * @error_code: An error code. + * @dbus_error_name: A D-Bus error name. * - * GFileIOStream provides io streams that both read and write to the same - * file handle. - * GFileIOStream implements #GSeekable, which allows the io - * stream to jump to arbitrary positions in the file and to truncate - * the file, provided the filesystem of the file supports these - * operations. - * To find the position of a file io stream, use - * g_seekable_tell(). - * To find out if a file io stream supports seeking, use g_seekable_can_seek(). - * To position a file io stream, use g_seekable_seek(). - * To find out if a file io stream supports truncating, use - * g_seekable_can_truncate(). To truncate a file io - * stream, use g_seekable_truncate(). - * The default implementation of all the #GFileIOStream operations - * and the implementation of #GSeekable just call into the same operations - * on the output stream. + * Creates an association to map between @dbus_error_name and + * #GError<!-- -->s specified by @error_domain and @error_code. + * This is typically done in the routine that returns the #GQuark for + * an error domain. + * exists. * - * Since: 2.22 + * Returns: %TRUE if the association was created, %FALSE if it already + * Since: 2.26 */ /** - * g_mount_get_root: - * @mount: a #GMount. + * g_dbus_error_register_error_domain: + * @error_domain_quark_name: The error domain name. + * @quark_volatile: A pointer where to store the #GQuark. + * @entries: A pointer to @num_entries #GDBusErrorEntry struct items. + * @num_entries: Number of items to register. * - * Gets the root directory on @mount. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. + * Helper function for associating a #GError error domain with D-Bus error names. * - * Returns: (transfer full): a #GFile. + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE: + * g_dbus_error_set_dbus_error: + * @error: A pointer to a #GError or %NULL. + * @dbus_error_name: D-Bus error name. + * @dbus_error_message: D-Bus error message. + * @format: printf()-style format to prepend to @dbus_error_message or %NULL. + * @...: Arguments for @format. * - * A key in the "standard" namespace for getting the content type of the file. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - * The value for this key should contain a valid content type. - */ - - -/** - * SECTION:gunixmount: - * @include: gio/gunixmounts.h - * @short_description: UNIX mounts + * Does nothing if @error is %NULL. Otherwise sets *@error to + * a new #GError created with g_dbus_error_new_for_dbus_error() + * with @dbus_error_message prepend with @format (unless %NULL). * - * Routines for managing mounted UNIX mount points and paths. - * Note that <filename><gio/gunixmounts.h></filename> belongs to the - * UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Since: 2.26 */ /** - * GParamSpecParam: - * @parent_instance: private #GParamSpec portion + * g_dbus_error_set_dbus_error_valist: + * @error: A pointer to a #GError or %NULL. + * @dbus_error_name: D-Bus error name. + * @dbus_error_message: D-Bus error message. + * @format: printf()-style format to prepend to @dbus_error_message or %NULL. + * @var_args: Arguments for @format. * - * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM - * properties. + * Like g_dbus_error_set_dbus_error() but intended for language bindings. + * + * Since: 2.26 */ /** - * GPollFD: - * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32) - * @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR. - * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred. + * g_dbus_error_strip_remote_error: + * @error: A #GError. * + * Looks for extra information in the error message used to recover + * the D-Bus error name and strips it if found. If stripped, the + * message field in @error will correspond exactly to what was + * received on the wire. + * This is typically used when presenting errors to the end user. * + * Returns: %TRUE if information was stripped, %FALSE otherwise. + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC: + * g_dbus_error_unregister_error: + * @error_domain: A #GQuark for a error domain. + * @error_code: An error code. + * @dbus_error_name: A D-Bus error name. * - * A key in the "time" namespace for getting the microseconds of the time - * the file was last accessed. This should be used in conjunction with - * #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Destroys an association previously set up with g_dbus_error_register_error(). + * + * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found. + * Since: 2.26 */ /** - * g_mount_unmount_with_operation_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_dbus_generate_guid: * - * Finishes unmounting a mount. If any errors occurred during the operation, + * Generate a D-Bus GUID that can be used with + * e.g. g_dbus_connection_new(). + * See the D-Bus specification regarding what strings are valid D-Bus + * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). * - * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise. - * Since: 2.22 + * Returns: A valid D-Bus GUID. Free with g_free(). + * Since: 2.26 */ /** - * GDBusMessageByteOrder: - * @G_DBUS_MESSAGE_BYTE_ORDER_BIG_ENDIAN: The byte order is big endian. - * @G_DBUS_MESSAGE_BYTE_ORDER_LITTLE_ENDIAN: The byte order is little endian. + * g_dbus_interface_info_generate_xml: + * @info: A #GDBusNodeInfo + * @indent: Indentation level. + * @string_builder: A #GString to to append XML data to. * - * Enumeration used to describe the byte order of a D-Bus message. + * Appends an XML representation of @info (and its children) to @string_builder. + * This function is typically used for generating introspection XML + * documents at run-time for handling the + * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> + * method. * * Since: 2.26 */ /** - * g_app_info_launch: - * @appinfo: a #GAppInfo - * @files: (element-type GFile): a #GList of #GFile objects - * @launch_context: (allow-none): a #GAppLaunchContext or %NULL - * @error: a #GError + * g_dbus_interface_info_lookup_method: + * @info: A #GDBusInterfaceInfo. + * @name: A D-Bus method name (typically in CamelCase) * - * Launches the application. Passes @files to the launched application - * as arguments, using the optional @launch_context to get information - * about the details of the launcher (like what screen it is on). - * On error, @error will be set accordingly. - * To launch the application without arguments pass a %NULL @files list. - * Note that even if the launch is successful the application launched - * can fail to start if it runs into problems during startup. There is - * no way to detect this. - * Some URIs can be changed when passed through a GFile (for instance - * unsupported uris with strange formats like mailto:), so if you have - * a textual uri you want to pass in as argument, consider using - * g_app_info_launch_uris() instead. - * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar> - * environment variable with the path of the launched desktop file and - * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process - * id of the launched process. This can be used to ignore - * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited - * by further processes. The <envar>DISPLAY</envar> and - * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also - * set, based on information provided in @launch_context. + * Looks up information about a method. + * This cost of this function is O(n) in number of methods. * - * Returns: %TRUE on successful launch, %FALSE otherwise. + * Returns: A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. + * Since: 2.26 */ /** - * GParamSpecChar: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_dbus_interface_info_lookup_property: + * @info: A #GDBusInterfaceInfo. + * @name: A D-Bus property name (typically in CamelCase). * - * A #GParamSpec derived structure that contains the meta data for character properties. - */ - - -/** - * GVolumeMonitor::drive-disconnected: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: a #GDrive that was disconnected. + * Looks up information about a property. + * This cost of this function is O(n) in number of properties. * - * Emitted when a drive is disconnected from the system. + * Returns: A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. + * Since: 2.26 */ /** - * GDBusSubtreeDispatchFunc: - * @connection: A #GDBusConnection. - * @sender: The unique bus name of the remote caller. - * @object_path: The object path that was registered with g_dbus_connection_register_subtree(). - * @interface_name: The D-Bus interface name that the method call or property access is for. - * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. - * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL). - * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree(). + * g_dbus_interface_info_lookup_signal: + * @info: A #GDBusInterfaceInfo. + * @name: A D-Bus signal name (typically in CamelCase) * - * The type of the @dispatch function in #GDBusSubtreeVTable. - * Subtrees are flat. @node, if non-%NULL, is always exactly one + * Looks up information about a signal. + * This cost of this function is O(n) in number of signals. * - * Segment of the object path (ie: it never contains a slash). - * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods. + * Returns: A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. * Since: 2.26 */ /** - * GFileCopyFlags: - * @G_FILE_COPY_NONE: No flags set. - * @G_FILE_COPY_OVERWRITE: Overwrite any existing files - * @G_FILE_COPY_BACKUP: Make a backup of any existing files. - * @G_FILE_COPY_NOFOLLOW_SYMLINKS: Don't follow symlinks. - * @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set used for copy (see #GFileInfo). - * @G_FILE_COPY_NO_FALLBACK_FOR_MOVE: Don't use copy and delete fallback if native move not supported. - * @G_FILE_COPY_TARGET_DEFAULT_PERMS: Leaves target file with default perms, instead of setting the source file perms. + * g_dbus_interface_info_ref: + * @info: A #GDBusInterfaceInfo * - * Flags used when copying or moving files. + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. + * + * Returns: The same @info. + * Since: 2.26 */ /** - * g_bus_watch_name: - * @bus_type: The type of bus to watch a name on. - * @name: The name (well-known or unique) to watch. - * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL. - * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: Function for freeing @user_data or %NULL. + * g_dbus_interface_info_unref: + * @info: A #GDBusInterfaceInfo. * - * Starts watching @name on the bus specified by @bus_type and calls - * known to have a owner respectively known to lose its - * owner. Callbacks will be invoked in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread you are calling this function from. - * You are guaranteed that one of the handlers will be invoked after - * calling this function. When you are done watching the name, just - * call g_bus_unwatch_name() with the watcher id this function - * returns. - * If the name vanishes or appears (for example the application owning - * the name could restart), the handlers are also invoked. If the - * #GDBusConnection that is used for watching the name disconnects, then - * possible to access the name. - * Another guarantee is that invocations of @name_appeared_handler - * and @name_vanished_handler are guaranteed to alternate; that - * is, if @name_appeared_handler is invoked then you are - * guaranteed that the next time one of the handlers is invoked, it - * will be @name_vanished_handler. The reverse is also true. - * This behavior makes it very simple to write applications that wants - * to take action when a certain name exists, see <xref - * linkend="gdbus-watching-names"/>. Basically, the application - * should create object proxies in @name_appeared_handler and destroy - * them again (if any) in @name_vanished_handler. - * g_bus_unwatch_name() to stop watching the name. + * If @info is statically allocated, does nothing. Otherwise decreases + * the reference count of @info. When its reference count drops to 0, + * the memory used is freed. * - * Returns: An identifier (never 0) that an be used with * Since: 2.26 */ /** - * g_desktop_app_info_new_from_filename: - * @filename: the path of a desktop file, in the GLib filename encoding + * g_dbus_is_address: + * @string: A string. * - * Creates a new #GDesktopAppInfo. + * Checks if @string is a D-Bus address. + * This doesn't check if @string is actually supported by #GDBusServer + * or #GDBusConnection - use g_dbus_is_supported_address() to do more + * checks. * - * Returns: a new #GDesktopAppInfo or %NULL on error. + * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise. + * Since: 2.26 */ /** - * g_io_extension_point_get_extension_by_name: - * @extension_point: a #GIOExtensionPoint - * @name: the name of the extension to get + * g_dbus_is_guid: + * @string: The string to check. * - * Finds a #GIOExtension for an extension point by name. - * given name, or %NULL if there is no extension with that name + * Checks if @string is a D-Bus GUID. + * See the D-Bus specification regarding what strings are valid D-Bus + * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). * - * Returns: (transfer none): the #GIOExtension for @extension_point that has the + * Returns: %TRUE if @string is a guid, %FALSE otherwise. + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_UNIX_NLINK: + * g_dbus_is_interface_name: + * @string: The string to check. * - * A key in the "unix" namespace for getting the number of hard links - * for a file. See lstat() documentation. This attribute is only available - * for UNIX file systems. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Checks if @string is a valid D-Bus interface name. + * + * Returns: %TRUE if valid, %FALSE otherwise. + * Since: 2.26 */ /** - * g_tls_connection_handshake_async: - * @conn: a #GTlsConnection - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: a #GCancellable, or %NULL - * @callback: callback to call when the handshake is complete - * @user_data: the data to pass to the callback function + * g_dbus_is_member_name: + * @string: The string to check. * - * Asynchronously performs a TLS handshake on @conn. See - * g_tls_connection_handshake() for more information. + * Checks if @string is a valid D-Bus member (e.g. signal or method) name. * - * Since: 2.28 + * Returns: %TRUE if valid, %FALSE otherwise. + * Since: 2.26 */ /** - * G_TYPE_INVALID: + * g_dbus_is_name: + * @string: The string to check. * - * An invalid #GType used as error return value in some functions which return - * a #GType. + * Checks if @string is a valid D-Bus bus name (either unique or well-known). + * + * Returns: %TRUE if valid, %FALSE otherwise. + * Since: 2.26 */ /** - * g_volume_can_eject: - * @volume: a #GVolume. + * g_dbus_is_supported_address: + * @string: A string. + * @error: Return location for error or %NULL. * - * Checks if a volume can be ejected. + * Like g_dbus_is_address() but also checks if the library suppors the + * transports in @string and that key/value pairs for each transport + * are valid. + * supported by this library, %FALSE if @error is set. * - * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise. + * Returns: %TRUE if @string is a valid D-Bus address that is + * Since: 2.26 */ /** - * G_IS_PARAM_SPEC_FLOAT: - * @pspec: a valid #GParamSpec instance + * g_dbus_is_unique_name: + * @string: The string to check. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. + * Checks if @string is a valid D-Bus unique bus name. * - * Returns: %TRUE on success. + * Returns: %TRUE if valid, %FALSE otherwise. + * Since: 2.26 */ /** - * g_app_info_create_from_commandline: - * @commandline: the commandline to use - * @application_name: (allow-none): the application name, or %NULL to use @commandline - * @flags: flags that can specify details of the created #GAppInfo - * @error: a #GError location to store the error occuring, %NULL to ignore. + * g_dbus_message_bytes_needed: + * @blob: A blob represent a binary D-Bus message. + * @blob_len: The length of @blob (must be at least 16). + * @error: Return location for error or %NULL. * - * Creates a new #GAppInfo from the given information. + * Utility function to calculate how many bytes are needed to + * completely deserialize the D-Bus message stored at @blob. + * determine the size). * - * Returns: (transfer full): new #GAppInfo for given command. + * Returns: Number of bytes needed or -1 if @error is set (e.g. if + * Since: 2.26 */ /** - * g_socket_client_get_protocol: - * @client: a #GSocketClient + * g_dbus_message_copy: + * @message: A #GDBusMessage. + * @error: Return location for error or %NULL. * - * Gets the protocol name type of the socket client. - * See g_socket_client_set_protocol() for details. + * Copies @message. The copy is a deep copy and the returned + * #GDBusMessage is completely identical except that it is guaranteed + * to not be locked. + * This operation can fail if e.g. @message contains file descriptors + * and the per-process or system-wide open files limit is reached. + * g_object_unref(). * - * Returns: a #GSocketProtocol - * Since: 2.22 + * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. Free with + * Since: 2.26 */ /** - * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO: + * g_dbus_message_get_arg0: + * @message: A #GDBusMessage. * - * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:". + * Convenience to get the first item in the body of @message. + * + * Returns: The string item or %NULL if the first item in the body of + * Since: 2.26 */ @@ -17609,1730 +17198,1234 @@ /** - * g_permission_get_can_acquire: - * @permission: a #GPermission instance - * @returns: the value of the 'can-acquire' property - * - * Gets the value of the 'can-acquire' property. This property is %TRUE - * if it is generally possible to acquire the permission by calling - * g_permission_acquire(). + * g_dbus_message_get_byte_order: + * @message: A #GDBusMessage. * - * Since: 2.26 - */ - - -/** - * G_TYPE_PARAM_INT: + * Gets the byte order of @message. * - * The #GType of #GParamSpecInt. + * Returns: The byte order. */ /** - * g_desktop_app_info_new: - * @desktop_id: the desktop file id + * g_dbus_message_get_destination: + * @message: A #GDBusMessage. * - * Creates a new #GDesktopAppInfo based on a desktop file id. - * A desktop file id is the basename of the desktop file, including the - * .desktop extension. GIO is looking for a desktop file with this name - * in the <filename>applications</filename> subdirectories of the XDG data - * directories (i.e. the directories specified in the - * <envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment - * variables). GIO also supports the prefix-to-subdirectory mapping that is - * described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu Spec</ulink> - * (i.e. a desktop id of kde-foo.desktop will match - * <filename>/usr/share/applications/kde/foo.desktop</filename>). + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. * - * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id + * Returns: The value. + * Since: 2.26 */ /** - * g_io_scheduler_job_send_to_mainloop_async: - * @job: a #GIOSchedulerJob - * @func: a #GSourceFunc callback that will be called in the original thread - * @user_data: data to pass to @func - * @notify: a #GDestroyNotify for @user_data, or %NULL + * g_dbus_message_get_error_name: + * @message: A #GDBusMessage. * - * Used from an I/O job to send a callback to be run asynchronously in - * the thread that the job was started from. The callback will be run - * when the main loop is available, but at that time the I/O job might - * have finished. The return value from the callback is ignored. - * Note that if you are passing the @user_data from g_io_scheduler_push_job() - * on to this function you have to ensure that it is not freed before - * g_io_scheduler_push_job() or by using refcounting for @user_data. - */ - - -/** - * G_IS_INITIALLY_UNOWNED: - * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. * - * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. + * Returns: The value. + * Since: 2.26 */ /** - * G_IS_VALUE: - * @value: A #GValue structure. + * g_dbus_message_get_flags: + * @message: A #GDBusMessage. * - * Checks if @value is a valid and initialized #GValue structure. + * Gets the flags for @message. * - * Returns: %TRUE on success. + * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). + * Since: 2.26 */ /** - * g_application_command_line_getenv: - * @cmdline: a #GApplicationCommandLine - * @name: the environment variable to get + * g_dbus_message_get_header: + * @message: A #GDBusMessage. + * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) * - * Gets the value of a particular environment variable of the command - * line invocation, as would be returned by g_getenv(). The strings may - * contain non-utf8 data. - * The remote application usually does not send an environment. Use - * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag - * set it is possible that the environment is still not available (due - * to invocation messages from other applications). - * The return value should not be modified or freed and is valid for as - * long as @cmdline exists. + * Gets a header field on @message. + * otherwise. Do not free, it is owned by @message. * - * Returns: the value of the variable, or %NULL if unset or unsent - * Since: 2.28 + * Returns: A #GVariant with the value if the header was found, %NULL + * Since: 2.26 */ /** - * g_simple_async_result_set_from_error: - * @simple: a #GSimpleAsyncResult. - * @error: #GError. + * g_dbus_message_get_header_fields: + * @message: A #GDBusMessage. * - * Sets the result from a #GError. - */ - - -/** - * g_file_info_set_attribute_int64: - * @info: a #GFileInfo. - * @attribute: attribute name to set. - * @attr_value: int64 value to set attribute to. + * Gets an array of all header fields on @message that are set. + * %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a + * #guchar. Free with g_free(). * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * Returns: An array of header fields terminated by + * Since: 2.26 */ /** - * g_data_input_stream_read_uint16: - * @stream: a given #GDataInputStream. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * g_dbus_message_get_interface: + * @message: A #GDBusMessage. * - * Reads an unsigned 16-bit/2-byte value from @stream. - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - * an error occurred. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. * - * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if + * Returns: The value. + * Since: 2.26 */ /** - * GDBusSignalCallback: - * @connection: A #GDBusConnection. - * @sender_name: The unique bus name of the sender of the signal. - * @object_path: The object path that the signal was emitted on. - * @interface_name: The name of the interface. - * @signal_name: The name of the signal. - * @parameters: A #GVariant tuple with parameters for the signal. - * @user_data: User data passed when subscribing to the signal. + * g_dbus_message_get_locked: + * @message: A #GDBusMessage. * - * Signature for callback function used in g_dbus_connection_signal_subscribe(). + * Checks whether @message is locked. To monitor changes to this + * value, conncet to the #GObject::notify signal to listen for changes + * on the #GDBusMessage:locked property. * + * Returns: %TRUE if @message is locked, %FALSE otherwise. * Since: 2.26 */ /** - * g_socket_client_set_socket_type: - * @client: a #GSocketClient. - * @type: a #GSocketType + * g_dbus_message_get_member: + * @message: A #GDBusMessage. * - * Sets the socket type of the socket client. - * The sockets created by this object will be of the specified - * type. - * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, - * as GSocketClient is used for connection oriented services. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. * - * Since: 2.22 + * Returns: The value. + * Since: 2.26 */ /** - * GDBusAuthMechanism:credentials: + * g_dbus_message_get_message_type: + * @message: A #GDBusMessage. * - * If authenticating as a server, this property contains the - * received credentials, if any. - * If authenticating as a client, the property contains the - * credentials that were sent, if any. - */ - - -/** - * G_TYPE_PARAM_PARAM: + * Gets the type of @message. * - * The #GType of #GParamSpecParam. + * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). + * Since: 2.26 */ /** - * G_PARAM_SPEC_UCHAR: - * @pspec: a valid #GParamSpec instance + * g_dbus_message_get_num_unix_fds: + * @message: A #GDBusMessage. * - * Cast a #GParamSpec instance into a #GParamSpecUChar. - */ - - -/** - * GWeakNotify: - * @data: data that was provided when the weak reference was established - * @where_the_object_was: the object being finalized + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. * - * A #GWeakNotify function can be added to an object as a callback that gets - * triggered when the object is finalized. Since the object is already being - * finalized when the #GWeakNotify is called, there's not much you could do - * with the object, apart from e.g. using its adress as hash-index or the like. + * Returns: The value. + * Since: 2.26 */ /** - * g_socket_client_set_tls_validation_flags: - * @client: a #GSocketClient. - * @flags: the validation flags - * - * Sets the TLS validation flags used when creating TLS connections - * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. + * g_dbus_message_get_path: + * @message: A #GDBusMessage. * - * Since: 2.28 - */ - - -/** - * GChildWatchFunc: - * @pid: the process id of the child process - * @status: Status information about the child process, see waitpid(2) for more information about this field - * @data: user data passed to g_child_watch_add() + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. * - * The type of functions to be called when a child exists. + * Returns: The value. + * Since: 2.26 */ /** - * g_io_extension_point_set_required_type: - * @extension_point: a #GIOExtensionPoint - * @type: the #GType to require + * g_dbus_message_get_reply_serial: + * @message: A #GDBusMessage. * - * Sets the required type for @extension_point to @type. - * All implementations must henceforth have this type. - */ - - -/** - * GSettingsBackend: + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. * - * An implementation of a settings storage repository. + * Returns: The value. + * Since: 2.26 */ /** - * g_converter_reset: - * @converter: a #GConverter. + * g_dbus_message_get_sender: + * @message: A #GDBusMessage. * - * Resets all internal state in the converter, making it behave - * as if it was just created. If the converter has any internal - * state that would produce output then that output is lost. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. * - * Since: 2.24 + * Returns: The value. + * Since: 2.26 */ /** - * g_buffered_output_stream_new_sized: - * @base_stream: a #GOutputStream. - * @size: a #gsize. + * g_dbus_message_get_serial: + * @message: A #GDBusMessage. * - * Creates a new buffered output stream with a given buffer size. + * Gets the serial for @message. * - * Returns: a #GOutputStream with an internal buffer set to @size. + * Returns: A #guint32. + * Since: 2.26 */ /** - * GDBusServer:active: + * g_dbus_message_get_signature: + * @message: A #GDBusMessage. * - * Whether the server is currently active. + * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. * + * Returns: The value. * Since: 2.26 */ /** - * GDBusPropertyInfo: - * @ref_count: The reference count or -1 if statically allocated. - * @name: The name of the D-Bus property, e.g. "SupportedFilesystems". - * @signature: The D-Bus signature of the property (a single complete type). - * @flags: Access control flags for the property. - * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. + * g_dbus_message_get_unix_fd_list: + * @message: A #GDBusMessage. * - * Information about a D-Bus property on a D-Bus interface. + * Gets the UNIX file descriptors associated with @message, if any. + * This method is only available on UNIX. + * associated. Do not free, this object is owned by @message. * + * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are * Since: 2.26 */ /** - * g_file_set_attribute_byte_string: - * @file: input #GFile. - * @attribute: a string containing the attribute's name. - * @value: a string containing the attribute's new value. - * @flags: a #GFileQueryInfoFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * g_dbus_message_lock: + * @message: A #GDBusMessage. * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. - * If @attribute is of a different type, this operation will fail, - * returning %FALSE. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * in the @file, %FALSE otherwise. + * If @message is locked, does nothing. Otherwise locks the message. * - * Returns: %TRUE if the @attribute was successfully set to @value + * Since: 2.26 */ /** - * g_tls_connection_set_rehandshake_mode: - * @conn: a #GTlsConnection - * @mode: the rehandshaking mode + * g_dbus_message_new: * - * Sets how @conn behaves with respect to rehandshaking requests. - * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to - * rehandshake after the initial handshake is complete. (For a client, - * this means it will refuse rehandshake requests from the server, and - * for a server, this means it will close the connection with an error - * if the client attempts to rehandshake.) - * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a - * rehandshake only if the other end of the connection supports the - * TLS <literal>renegotiation_info</literal> extension. This is the - * default behavior, but means that rehandshaking will not work - * against older implementations that do not support that extension. - * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow - * rehandshaking even without the - * <literal>renegotiation_info</literal> extension. On the server side - * in particular, this is not recommended, since it leaves the server - * open to certain attacks. However, this mode is necessary if you - * need to allow renegotiation with older client software. + * Creates a new empty #GDBusMessage. * - * Since: 2.28 + * Returns: A #GDBusMessage. Free with g_object_unref(). + * Since: 2.26 */ /** - * G_VALUE_HOLDS_ENUM: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. + * g_dbus_message_new_from_blob: + * @blob: A blob represent a binary D-Bus message. + * @blob_len: The length of @blob. + * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported. + * @error: Return location for error or %NULL. * - * Returns: %TRUE on success. - */ - - -/** - * G_PARAM_SPEC_UINT64: - * @pspec: a valid #GParamSpec instance + * Creates a new #GDBusMessage from the data stored at @blob. The byte + * order that the message was in can be retrieved using + * g_dbus_message_get_byte_order(). + * g_object_unref(). * - * Cast a #GParamSpec instance into a #GParamSpecUInt64. + * Returns: A new #GDBusMessage or %NULL if @error is set. Free with + * Since: 2.26 */ /** - * g_socket_listen: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Marks the socket as a server socket, i.e. a socket that is used - * to accept incoming requests using g_socket_accept(). - * Before calling this the socket must be bound to a local address using - * g_socket_bind(). - * To set the maximum amount of outstanding clients, use - * g_socket_set_listen_backlog(). + * g_dbus_message_new_method_call: + * @name: A valid D-Bus name or %NULL. + * @path: A valid object path. + * @interface_: A valid D-Bus interface name or %NULL. + * @method: A valid method name. * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 - */ - - -/** - * g_simple_async_result_complete_in_idle: - * @simple: a #GSimpleAsyncResult. + * Creates a new #GDBusMessage for a method call. * - * Completes an asynchronous function in an idle handler in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread that @simple was initially created in. - * Calling this function takes a reference to @simple for as long as - * is needed to complete the call. + * Returns: A #GDBusMessage. Free with g_object_unref(). + * Since: 2.26 */ /** - * G_VARIANT_TYPE_BOOLEAN: + * g_dbus_message_new_method_error: + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @error_name: A valid D-Bus error name. + * @error_message_format: The D-Bus error message in a printf() format. + * @...: Arguments for @error_message_format. * - * The type of a value that can be either %TRUE or %FALSE. - */ - - -/** - * g_file_info_set_attribute_byte_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a byte string. + * Creates a new #GDBusMessage that is an error reply to @method_call_message. * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). + * Since: 2.26 */ /** - * g_data_output_stream_put_uint64: - * @stream: a #GDataOutputStream. - * @data: a #guint64. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts an unsigned 64-bit integer into the stream. + * g_dbus_message_new_method_error_literal: + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @error_name: A valid D-Bus error name. + * @error_message: The D-Bus error message. * - * Returns: %TRUE if @data was successfully added to the @stream. - */ - - -/** - * SECTION:gdbusprox: - * @short_description: Client-side proxies - * @include: gio/gio.h + * Creates a new #GDBusMessage that is an error reply to @method_call_message. * - * #GDBusProxy is a base class used for proxies to access a D-Bus - * interface on a remote object. A #GDBusProxy can be constructed for - * both well-known and unique names. - * By default, #GDBusProxy will cache all properties (and listen to - * changes) of the remote object, and proxy all signals that gets - * emitted. This behaviour can be changed by passing suitable - * #GDBusProxyFlags when the proxy is created. If the proxy is for a - * well-known name, the property cache is flushed when the name owner - * vanishes and reloaded when a name owner appears. - * If a #GDBusProxy is used for a well-known name, the owner of the - * name is tracked and can be read from - * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to - * get notified of changes. Additionally, only signals and property - * changes emitted from the current name owner are considered and - * calls are always sent to the current name owner. This avoids a - * number of race conditions when the name is lost by one owner and - * claimed by another. However, if no name owner currently exists, - * then calls will be sent to the well-known name which may result in - * the message bus launching an owner (unless - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). - * The generic #GDBusProxy::g-properties-changed and #GDBusProxy::g-signal - * signals are not very convenient to work with. Therefore, the recommended - * way of working with proxies is to subclass #GDBusProxy, and have - * more natural properties and signals in your derived class. - * See <xref linkend="gdbus-example-proxy-subclass"/> for an example. - * <example id="gdbus-wellknown-proxy"><title>GDBusProxy for a well-known-name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). + * Since: 2.26 */ /** - * GSimpleAction: + * g_dbus_message_new_method_error_valist: + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @error_name: A valid D-Bus error name. + * @error_message_format: The D-Bus error message in a printf() format. + * @var_args: Arguments for @error_message_format. * - * The <structname>GSimpleAction</structname> structure contains private - * data and should only be accessed using the provided API + * Like g_dbus_message_new_method_error() but intended for language bindings. * + * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). * Since: 2.26 */ /** - * g_socket_get_local_address: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Try to get the local address of a bound socket. This is only - * useful if the socket has been bound to a local address, - * either explicitly or implicitly when connecting. - * Free the returned object with g_object_unref(). + * g_dbus_message_new_method_reply: + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Since: 2.22 - */ - - -/** - * GDriveIface: - * @g_iface: The parent interface. - * @changed: Signal emitted when the drive is changed. - * @disconnected: The removed signal that is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized. - * @eject_button: Signal emitted when the physical eject button (if any) of a drive have been pressed. - * @get_name: Returns the name for the given #GDrive. - * @get_icon: Returns a #GIcon for the given #GDrive. - * @has_volumes: Returns %TRUE if the #GDrive has mountable volumes. - * @get_volumes: Returns a list #GList of #GVolume for the #GDrive. - * @is_media_removable: Returns %TRUE if the #GDrive supports removal and insertion of media. - * @has_media: Returns %TRUE if the #GDrive has media inserted. - * @is_media_check_automatic: Returns %TRUE if the #GDrive is capabable of automatically detecting media changes. - * @can_poll_for_media: Returns %TRUE if the #GDrive is capable of manually polling for media change. - * @can_eject: Returns %TRUE if the #GDrive can eject media. - * @eject: Ejects a #GDrive. - * @eject_finish: Finishes an eject operation. - * @poll_for_media: Poll for media insertion/removal on a #GDrive. - * @poll_for_media_finish: Finishes a media poll operation. - * @get_identifier: Returns the identifier of the given kind, or %NULL if the #GDrive doesn't have one. - * @enumerate_identifiers: Returns an array strings listing the kinds of identifiers which the #GDrive has. - * @get_start_stop_type: Gets a #GDriveStartStopType with details about starting/stopping the drive. Since 2.22. - * @can_stop: Returns %TRUE if a #GDrive can be stopped. Since 2.22. - * @stop: Stops a #GDrive. Since 2.22. - * @stop_finish: Finishes a stop operation. Since 2.22. - * @can_start: Returns %TRUE if a #GDrive can be started. Since 2.22. - * @can_start_degraded: Returns %TRUE if a #GDrive can be started degraded. Since 2.22. - * @start: Starts a #GDrive. Since 2.22. - * @start_finish: Finishes a start operation. Since 2.22. - * @stop_button: Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22. - * @eject_with_operation: Starts ejecting a #GDrive using a #GMountOperation. Since 2.22. - * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22. + * Creates a new #GDBusMessage that is a reply to @method_call_message. * - * Interface for creating #GDrive implementations. + * Returns: (transfer full): #GDBusMessage. Free with g_object_unref(). + * Since: 2.26 */ /** - * g_unix_output_stream_get_fd: - * @stream: a #GUnixOutputStream + * g_dbus_message_new_signal: + * @path: A valid object path. + * @interface_: A valid D-Bus interface name. + * @signal: A valid signal name. * - * Return the UNIX file descriptor that the stream writes to. + * Creates a new #GDBusMessage for a signal emission. * - * Returns: The file descriptor of @stream - * Since: 2.20 + * Returns: A #GDBusMessage. Free with g_object_unref(). + * Since: 2.26 */ /** - * g_dbus_is_unique_name: - * @string: The string to check. + * g_dbus_message_print: + * @message: A #GDBusMessage. + * @indent: Indentation level. * - * Checks if @string is a valid D-Bus unique bus name. + * Produces a human-readable multi-line description of @message. + * The contents of the description has no ABI guarantees, the contents + * and formatting is subject to change at any time. Typical output + * looks something like this: + * <programlisting> + * Headers: + * path -> objectpath '/org/gtk/GDBus/TestObject' + * interface -> 'org.gtk.GDBus.TestInterface' + * member -> 'GimmeStdout' + * destination -> ':1.146' + * UNIX File Descriptors: + * (none) + * </programlisting> + * or + * <programlisting> + * Headers: + * reply-serial -> uint32 4 + * destination -> ':1.159' + * sender -> ':1.146' + * num-unix-fds -> uint32 1 + * UNIX File Descriptors: + * </programlisting> * - * Returns: %TRUE if valid, %FALSE otherwise. + * Type: method-return + * Flags: no-reply-expected + * Version: 0 + * Serial: 477 + * Body: () + * Fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 + * Returns: A string that should be freed with g_free(). * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_UNIX_UID: - * - * A key in the "unix" namespace for getting the user ID for the file. - * This attribute is only available for UNIX file systems. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - */ - - -/** - * g_inet_address_get_native_size: - * @address: a #GInetAddress + * g_dbus_message_set_body: + * @message: A #GDBusMessage. + * @body: Either %NULL or a #GVariant that is a tuple. * - * Gets the size of the native raw binary address for @address. This - * is the size of the data that you get from g_inet_address_to_bytes(). + * Sets the body @message. As a side-effect the + * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the + * type string of @body (or cleared if @body is %NULL). + * If @body is floating, @message assumes ownership of @body. * - * Returns: the number of bytes used for the native version of @address. - * Since: 2.22 + * Since: 2.26 */ /** - * G_IS_OBJECT: - * @object: Instance to check for being a %G_TYPE_OBJECT. + * g_dbus_message_set_byte_order: + * @message: A #GDBusMessage. + * @byte_order: The byte order. * - * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. + * Sets the byte order of @message. */ /** - * g_file_query_info: - * @file: input #GFile. - * @attributes: an attribute query string. - * @flags: a set of #GFileQueryInfoFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError. - * - * Gets the requested information about specified @file. The result - * is a #GFileInfo object that contains key-value attributes (such as - * the type or size of the file). - * The @attributes value is a string that specifies the file attributes that - * should be gathered. It is not an error if it's not possible to read a particular - * requested attribute from a file - it just won't be set. @attributes should - * be a comma-separated list of attributes or attribute wildcards. The wildcard "*" - * means all attributes, and a wildcard like "standard::*" means all attributes in the standard - * namespace. An example attribute query be "standard::*,owner::user". - * The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * For symlinks, normally the information about the target of the - * symlink is returned, rather than information about the symlink itself. - * However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in @flags the - * information about the symlink itself will be returned. Also, for symlinks - * that point to non-existing files the information about the symlink itself - * will be returned. - * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. - * Other errors are possible too, and depend on what kind of filesystem the file is on. - * Free the returned object with g_object_unref(). + * g_dbus_message_set_destination: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error. - */ - - -/** - * GAsyncResult: + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. * - * Holds results information for an asynchronous operation, - * usually passed directly to a asynchronous _finish() operation. + * Since: 2.26 */ /** - * g_io_extension_point_implement: - * @extension_point_name: the name of the extension point - * @type: the #GType to register as extension - * @extension_name: the name for the extension - * @priority: the priority for the extension + * g_dbus_message_set_error_name: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Registers @type as extension for the extension point with name - * If @type has already been registered as an extension for this - * extension point, the existing #GIOExtension object is returned. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. * - * Returns: a #GIOExtension object for #GType + * Since: 2.26 */ /** - * g_mount_eject_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. - * - * Finishes ejecting a mount. If any errors occurred during the operation, + * g_dbus_message_set_flags: + * @message: A #GDBusMessage. + * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). * - * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. - * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead. - */ - - -/** - * GUnixSocketAddress: + * Sets the flags to set on @message. * - * A UNIX-domain (local) socket address, corresponding to a - * <type>struct sockaddr_un</type>. + * Since: 2.26 */ /** - * g_file_info_get_attribute_status: - * @info: a #GFileInfo - * @attribute: a file attribute key + * g_dbus_message_set_header: + * @message: A #GDBusMessage. + * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) + * @value: A #GVariant to set the header field or %NULL to clear the header field. * - * Gets the attribute status for an attribute key. - * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. + * Sets a header field on @message. + * If @value is floating, @message assumes ownership of @value. * - * Returns: a #GFileAttributeStatus for the given @attribute, or + * Since: 2.26 */ /** - * GMountIface: - * @g_iface: The parent interface. - * @changed: Changed signal that is emitted when the mount's state has changed. - * @unmounted: The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. - * @pre_unmount: The pre_unmout signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file. - * @get_root: Gets a #GFile to the root directory of the #GMount. - * @get_name: Gets a string containing the name of the #GMount. - * @get_icon: Gets a #GIcon for the #GMount. - * @get_uuid: Gets the UUID for the #GMount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available. - * @get_volume: Gets a #GVolume the mount is located on. Returns %NULL if the #GMount is not associated with a #GVolume. - * @get_drive: Gets a #GDrive the volume of the mount is located on. Returns %NULL if the #GMount is not associated with a #GDrive or a #GVolume. This is convenience method for getting the #GVolume and using that to get the #GDrive. - * @can_unmount: Checks if a #GMount can be unmounted. - * @can_eject: Checks if a #GMount can be ejected. - * @unmount: Starts unmounting a #GMount. - * @unmount_finish: Finishes an unmounting operation. - * @eject: Starts ejecting a #GMount. - * @eject_finish: Finishes an eject operation. - * @remount: Starts remounting a #GMount. - * @remount_finish: Finishes a remounting operation. - * @guess_content_type: Starts guessing the type of the content of a #GMount. See g_mount_guess_content_type() for more information on content type guessing. This operation was added in 2.18. - * @guess_content_type_finish: Finishes a contenet type guessing operation. Added in 2.18. - * @guess_content_type_sync: Synchronous variant of @guess_content_type. Added in 2.18 - * @unmount_with_operation: Starts unmounting a #GMount using a #GMountOperation. Since 2.22. - * @unmount_with_operation_finish: Finishes an unmounting operation using a #GMountOperation. Since 2.22. - * @eject_with_operation: Starts ejecting a #GMount using a #GMountOperation. Since 2.22. - * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22. - * @get_default_location: Gets a #GFile indication a start location that can be use as the entry point for this mount. Since 2.24. + * g_dbus_message_set_interface: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Interface for implementing operations for mounts. - */ - - -/** - * GOutputStreamSpliceFlags: - * @G_OUTPUT_STREAM_SPLICE_NONE: Do not close either stream. - * @G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE: Close the source stream after the splice. - * @G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET: Close the target stream after the splice. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. * - * GOutputStreamSpliceFlags determine how streams should be spliced. + * Since: 2.26 */ /** - * g_cancellable_get_fd: - * @cancellable: a #GCancellable. - * - * Gets the file descriptor for a cancellable job. This can be used to - * implement cancellable operations on Unix systems. The returned fd will - * turn readable when @cancellable is cancelled. - * You are not supposed to read from the fd yourself, just check for - * readable status. Reading to unset the readable status is done - * with g_cancellable_reset(). - * After a successful return from this function, you should use - * g_cancellable_release_fd() to free up resources allocated for - * the returned file descriptor. - * See also g_cancellable_make_pollfd(). - * is not supported, or on errors. + * g_dbus_message_set_member: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Returns: A valid file descriptor. %-1 if the file descriptor - */ - - -/** - * GNetworkService: + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. * - * A #GSocketConnectable for resolving a SRV record and connecting to - * that service. + * Since: 2.26 */ /** - * g_dbus_message_get_path: + * g_dbus_message_set_message_type: * @message: A #GDBusMessage. + * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. + * Sets @message to be of @type. * - * Returns: The value. * Since: 2.26 */ /** - * G_VALUE_HOLDS_DOUBLE: - * @value: a valid #GValue structure + * g_dbus_message_set_num_unix_fds: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * g_file_attribute_matcher_matches_only: - * @matcher: a #GFileAttributeMatcher. - * @attribute: a file attribute key. + * g_dbus_message_set_path: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Checks if a attribute matcher only matches a given attribute. Always - * returns %FALSE if "*" was used when creating the matcher. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. * - * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise. + * Since: 2.26 */ /** - * g_drive_can_eject: - * @drive: a #GDrive. + * g_dbus_message_set_reply_serial: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Checks if a drive can be ejected. + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. * - * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise. + * Since: 2.26 */ /** - * SECTION:ginetaddres: - * @short_description: An IPv4/IPv6 address + * g_dbus_message_set_sender: + * @message: A #GDBusMessage. + * @value: The value to set. * - * #GInetAddress represents an IPv4 or IPv6 internet address. Use - * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to - * look up the #GInetAddress for a hostname. Use - * g_resolver_lookup_by_address() or - * g_resolver_lookup_by_address_async() to look up the hostname for a - * #GInetAddress. - * To actually connect to a remote host, you will need a - * #GInetSocketAddress (which includes a #GInetAddress as well as a - * port number). - */ - - -/** - * g_hash_table_thaw: - * @hash_table: a #GHashTable + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. * - * This function is deprecated and will be removed in the next major - * release of GLib. It does nothing. + * Since: 2.26 */ /** - * g_output_stream_close_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_dbus_message_set_serial: + * @message: A #GDBusMessage. + * @serial: A #guint32. * - * Closes an output stream. + * Sets the serial for @message. * - * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. + * Since: 2.26 */ /** - * g_dbus_message_bytes_needed: - * @blob: A blob represent a binary D-Bus message. - * @blob_len: The length of @blob (must be at least 16). - * @error: Return location for error or %NULL. + * g_dbus_message_set_signature: + * @message: A #GDBusMessage. + * @value: The value to set. * - * Utility function to calculate how many bytes are needed to - * completely deserialize the D-Bus message stored at @blob. - * determine the size). + * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. * - * Returns: Number of bytes needed or -1 if @error is set (e.g. if * Since: 2.26 */ /** - * g_socket_listener_accept_socket_async: - * @listener: a #GSocketListener - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback + * g_dbus_message_set_unix_fd_list: + * @message: A #GDBusMessage. + * @fd_list: (allow-none): A #GUnixFDList or %NULL. * - * This is the asynchronous version of g_socket_listener_accept_socket(). - * When the operation is finished @callback will be - * called. You can then call g_socket_listener_accept_socket_finish() - * to get the result of the operation. + * Sets the UNIX file descriptors associated with @message. As a + * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header + * field is set to the number of fds in @fd_list (or cleared if + * This method is only available on UNIX. * - * Since: 2.22 + * Since: 2.26 */ /** - * g_unix_credentials_message_new: + * g_dbus_message_to_blob: + * @message: A #GDBusMessage. + * @out_size: Return location for size of generated blob. + * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported. + * @error: Return location for error. * - * Creates a new #GUnixCredentialsMessage with credentials matching the current processes. + * Serializes @message to a blob. The byte order returned by + * g_dbus_message_get_byte_order() will be used. + * generated by @message or %NULL if @error is set. Free with g_free(). * - * Returns: a new #GUnixCredentialsMessage + * Returns: A pointer to a valid binary D-Bus message of @out_size bytes * Since: 2.26 */ /** - * 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 - * to handle @mime_type. + * g_dbus_message_to_gerror: + * @message: A #GDBusMessage. + * @error: The #GError to set. * - * Returns: a #GList containing the desktop ids which claim - */ - - -/** - * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI: + * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does + * nothing and returns %FALSE. + * Otherwise this method encodes the error in @message as a #GError + * using g_dbus_error_set_dbus_error() using the information in the + * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as + * well as the first string item in @message's body. * - * A key in the "mountable" namespace for getting the HAL UDI for the mountable - * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * Returns: %TRUE if @error was set, %FALSE otherwise. + * Since: 2.26 */ /** - * G_VARIANT_TYPE_BYTESTRING_ARRAY: + * g_dbus_method_info_ref: + * @info: A #GDBusMethodInfo * - * The type of an array of byte strings (an array of arrays of bytes). - */ - - -/** - * GPermission:allowed: + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. * - * %TRUE if the caller currently has permission to perform the action that + * Returns: The same @info. + * Since: 2.26 */ /** - * g_application_command_line_get_platform_data: - * @cmdline: #GApplicationCommandLine + * g_dbus_method_info_unref: + * @info: A #GDBusMethodInfo. * - * Gets the platform data associated with the invocation of @cmdline. - * This is a #GVariant dictionary containing information about the - * context in which the invocation occured. It typically contains - * information like the current working directory and the startup - * notification ID. - * For local invocation, it will be %NULL. + * If @info is statically allocated, does nothing. Otherwise decreases + * the reference count of @info. When its reference count drops to 0, + * the memory used is freed. * - * Returns: the platform data, or %NULL - * Since: 2.28 + * Since: 2.26 */ /** - * g_file_info_set_symlink_target: - * @info: a #GFileInfo. - * @symlink_target: a static string containing a path to a symlink target. + * g_dbus_method_invocation_get_connection: + * @invocation: A #GDBusMethodInvocation. * - * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info - * to the given symlink target. + * Gets the #GDBusConnection the method was invoked on. + * + * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * g_unix_mount_point_compare: - * @mount1: a #GUnixMount. - * @mount2: a #GUnixMount. + * g_dbus_method_invocation_get_interface_name: + * @invocation: A #GDBusMethodInvocation. * - * Compares two unix mount points. - * or less than @mount2, respectively. + * Gets the name of the D-Bus interface the method was invoked on. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * Returns: A string. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * g_file_info_get_attribute_int32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_dbus_method_invocation_get_message: + * @invocation: A #GDBusMethodInvocation. * - * Gets a signed 32-bit integer contained within the attribute. If the - * attribute does not contain a signed 32-bit integer, or is invalid, - * 0 will be returned. + * Gets the #GDBusMessage for the method invocation. This is useful if + * you need to use low-level protocol features, such as UNIX file + * descriptor passing, that cannot be properly expressed in the + * #GVariant API. + * See <xref linkend="gdbus-server"/> and <xref + * linkend="gdbus-unix-fd-client"/> for an example of how to use this + * low-level API to send and receive UNIX file descriptors. * - * Returns: a signed 32-bit integer from the attribute. + * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * g_unix_fd_list_steal_fds: - * @list: a #GUnixFDList - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * g_dbus_method_invocation_get_method_info: + * @invocation: A #GDBusMethodInvocation. * - * Returns the array of file descriptors that is contained in this - * object. - * After this call, the descriptors are no longer contained in - * descriptors have been added). - * The return result of this function must be freed with g_free(). - * The caller is also responsible for closing all of the file - * descriptors. The file descriptors in the array are set to - * close-on-exec. - * If @length is non-%NULL then it is set to the number of file - * descriptors in the returned array. The returned array is also - * terminated with -1. - * This function never returns %NULL. In case there are no file - * descriptors contained in @list, an empty array is returned. - * descriptors + * Gets information about the method call, if any. * - * Returns: (array length=length) (transfer full): an array of file - * Since: 2.24 + * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * GVolumeMonitor: + * g_dbus_method_invocation_get_method_name: + * @invocation: A #GDBusMethodInvocation. * - * A Volume Monitor that watches for volume events. + * Gets the name of the method that was invoked. + * + * Returns: A string. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * G_TIME_SPAN_HOUR: + * g_dbus_method_invocation_get_object_path: + * @invocation: A #GDBusMethodInvocation. * - * Evaluates to a time span of one hour. + * Gets the object path the method was invoked on. * + * Returns: A string. Do not free, it is owned by @invocation. * Since: 2.26 */ /** - * g_dbus_message_set_byte_order: - * @message: A #GDBusMessage. - * @byte_order: The byte order. + * g_dbus_method_invocation_get_parameters: + * @invocation: A #GDBusMethodInvocation. * - * Sets the byte order of @message. + * Gets the parameters of the method invocation. + * + * Returns: A #GVariant. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * G_TYPE_STRV: + * g_dbus_method_invocation_get_sender: + * @invocation: A #GDBusMethodInvocation. * - * The #GType for a boxed type holding a %NULL-terminated array of strings. - * The code fragments in the following example show the use of a property of - * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set() - * and g_object_get(). - * |[ - * g_object_class_install_property (object_class, - * PROP_AUTHORS, - * g_param_spec_boxed ("authors", - * _("Authors"), - * _("List of authors"), - * G_TYPE_STRV, - * G_PARAM_READWRITE)); - * gchar *authors[] = { "Owen", "Tim", NULL }; - * g_object_set (obj, "authors", authors, NULL); - * gchar *writers[]; - * g_object_get (obj, "authors", &writers, NULL); - * // do something with writers - * g_strfreev (writers); - * ]| + * Gets the bus name that invoked the method. * - * Since: 2.4 + * Returns: A string. Do not free, it is owned by @invocation. + * Since: 2.26 */ /** - * GDrive::disconnected: - * @drive: a #GDrive. + * g_dbus_method_invocation_get_user_data: (skip) + * @invocation: A #GDBusMethodInvocation. * - * This signal is emitted when the #GDrive have been - * disconnected. If the recipient is holding references to the - * object they should release them so the object can be - * finalized. + * Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). + * + * Returns: A #gpointer. + * Since: 2.26 */ /** - * g_file_set_attribute_uint32: - * @file: input #GFile. - * @attribute: a string containing the attribute's name. - * @value: a #guint32 containing the attribute's new value. - * @flags: a #GFileQueryInfoFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * g_dbus_method_invocation_return_dbus_error: + * @invocation: A #GDBusMethodInvocation. + * @error_name: A valid D-Bus error name. + * @error_message: A valid D-Bus error message. * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. - * If @attribute is of a different type, this operation will fail. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * in the @file, %FALSE otherwise. + * Finishes handling a D-Bus method call by returning an error. + * This method will free @invocation, you cannot use it afterwards. * - * Returns: %TRUE if the @attribute was successfully set to @value + * Since: 2.26 */ /** - * g_file_has_prefix: - * @file: input #GFile. - * @prefix: input #GFile. + * g_dbus_method_invocation_return_error: + * @invocation: A #GDBusMethodInvocation. + * @domain: A #GQuark for the #GError error domain. + * @code: The error code. + * @format: printf()-style format. + * @...: Parameters for @format. * - * Checks whether @file has the prefix specified by @prefix. In other word, - * if the names of inital elements of @file<!-- -->s pathname match @prefix. - * Only full pathname elements are matched, so a path like /foo is not - * considered a prefix of /foobar, only of /foo/bar. - * This call does no i/o, as it works purely on names. As such it can - * sometimes return %FALSE even if @file is inside a @prefix (from a - * filesystem point of view), because the prefix of @file is an alias - * of @prefix. - * %FALSE otherwise. + * Finishes handling a D-Bus method call by returning an error. + * See g_dbus_error_encode_gerror() for details about what error name + * will be returned on the wire. In a nutshell, if the given error is + * registered using g_dbus_error_register_error() the name given + * during registration is used. Otherwise, a name of the form + * <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is + * used. This provides transparent mapping of #GError between + * applications using GDBus. + * If you are writing an application intended to be portable, + * <emphasis>always</emphasis> register errors with g_dbus_error_register_error() + * or use g_dbus_method_invocation_return_dbus_error(). + * This method will free @invocation, you cannot use it afterwards. * - * Virtual: prefix_matches - * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix. + * Since: 2.26 */ /** - * SECTION:gfileattribut: - * @short_description: Key-Value Paired File Attributes - * @include: gio/gio.h - * @see_also: #GFile, #GFileInfo + * g_dbus_method_invocation_return_error_literal: + * @invocation: A #GDBusMethodInvocation. + * @domain: A #GQuark for the #GError error domain. + * @code: The error code. + * @message: The error message. * - * File attributes in GIO consist of a list of key-value pairs. - * Keys are strings that contain a key namespace and a key name, separated - * by a colon, e.g. "namespace:keyname". Namespaces are included to sort - * key-value pairs by namespaces for relevance. Keys can be retrived - * using wildcards, e.g. "standard::*" will return all of the keys in the - * "standard" namespace. - * Values are stored within the list in #GFileAttributeValue structures. - * Values can store different types, listed in the enum #GFileAttributeType. - * Upon creation of a #GFileAttributeValue, the type will be set to - * %G_FILE_ATTRIBUTE_TYPE_INVALID. - * The list of possible attributes for a filesystem (pointed to by a #GFile) is - * availible as a #GFileAttributeInfoList. This list is queryable by key names - * as indicated earlier. - * Classes that implement #GFileIface will create a #GFileAttributeInfoList and - * install default keys and values for their given file system, architecture, - * and other possible implementation details (e.g., on a UNIX system, a file - * attribute key will be registered for the user id for a given file). - * <para> - * <table> - * <title>GFileAttributes Default Namespaces</title> - * <tgroup cols='2' align='left'><thead> - * <row><entry>Namspace</entry><entry>Description</entry></row> - * </thead> - * <tbody> - * <row><entry>"standard"</entry><entry>The "Standard" namespace. General file - * information that any application may need should be put in this namespace. - * Examples include the file's name, type, and size.</entry></row> - * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link> - * namespace. Currently, the only key in this namespace is "value", which contains - * the value of the current entity tag.</entry></row> - * <row><entry>"id"</entry><entry>The "Identification" namespace. This - * namespace is used by file managers and applications that list directories - * to check for loops and to uniquely identify files.</entry></row> - * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check - * if a user has the proper privilidges to access files and perform - * file operations. Keys in this namespace are made to be generic - * and easily understood, e.g. the "can_read" key is %TRUE if - * the current user has permission to read the file. UNIX permissions and - * NTFS ACLs in Windows should be mapped to these values.</entry></row> - * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes - * simple boolean keys for checking if a file or path supports mount operations, e.g. - * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row> - * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file - * access, changed, created times. </entry></row> - * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific - * information and may not be available for all files. Examples include - * the UNIX "UID", "GID", etc.</entry></row> - * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific - * information and may not be available for all files. Examples include - * "is_system" for checking if a file is marked as a system file, and "is_archive" - * for checking if a file is marked as an archive file.</entry></row> - * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information - * about who owns a file. May not be available for all file systems. Examples include - * "user" for getting the user name of the file owner. This information is often mapped from - * some backend specific data such as a unix UID.</entry></row> - * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes - * information about file thumbnails and their location within the file system. Exaples of - * keys in this namespace include "path" to get the location of a thumbnail, and "failed" - * to check if thumbnailing of the file failed.</entry></row> - * <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information - * about the file system where a file is located, such as its type, how much - * space is left available, and the overall size of the file system.</entry></row> - * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace - * contain information about the current GVFS backend in use. </entry></row> - * <row><entry>"xattr"</entry><entry>The "xattr" namespace. Gets information - * about extended user attributes. See attr(5). The "user." prefix of the - * extended user attribute name is stripped away when constructing keys in - * this namespace, e.g. "xattr::mime_type" for the extended attribute with - * the name "user.mime_type". Note that this information is only available - * if GLib has been built with extended attribute support.</entry></row> - * <row><entry>"xattr-sys"</entry><entry>The "xattr-sys" namespace. - * Gets information about extended attributes which are not user-specific. - * See attr(5). Note that this information is only available if GLib - * has been built with extended attribute support.</entry></row> - * <row><entry>"selinux"</entry><entry>The "SELinux" namespace. Includes - * information about the SELinux context of files. Note that this information - * is only available if GLib has been built with SELinux support.</entry></row> - * </tbody> - * </tgroup> - * </table> - * </para> - * Please note that these are not all of the possible namespaces. - * More namespaces can be added from GIO modules or by individual applications. - * For more information about writing GIO modules, see #GIOModule. - * <!-- TODO: Implementation note about using extended attributes on supported - * file systems --> - * <para><table> - * <title>GFileAttributes Built-in Keys and Value Types</title> - * <tgroup cols='3' align='left'><thead> - * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row> - * </thead><tbody> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object (#GIcon)</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object (#GIcon)</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row> - * </tbody></tgroup></table></para> - * Note that there are no predefined keys in the "xattr" and "xattr-sys" - * namespaces. Keys for the "xattr" namespace are constructed by stripping - * away the "user." prefix from the extended user attribute, and prepending - * "xattr::". Keys for the "xattr-sys" namespace are constructed by - * concatenating "xattr-sys::" with the extended attribute name. All extended - * attribute values are returned as hex-encoded strings in which bytes outside - * the ASCII range are encoded as hexadecimal escape sequences of the form - * \x<replaceable>nn</replaceable>. - */ - - -/** - * GUnixMountMonitor: + * Like g_dbus_method_invocation_return_error() but without printf()-style formatting. + * This method will free @invocation, you cannot use it afterwards. * - * Watches #GUnixMount<!-- -->s for changes. + * Since: 2.26 */ /** - * g_drive_eject: - * @drive: a #GDrive. - * @flags: flags affecting the unmount if required for eject - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback + * g_dbus_method_invocation_return_error_valist: + * @invocation: A #GDBusMethodInvocation. + * @domain: A #GQuark for the #GError error domain. + * @code: The error code. + * @format: printf()-style format. + * @var_args: #va_list of parameters for @format. * - * Asynchronously ejects a drive. - * When the operation is finished, @callback will be called. - * You can then call g_drive_eject_finish() to obtain the - * result of the operation. + * Like g_dbus_method_invocation_return_error() but intended for + * language bindings. + * This method will free @invocation, you cannot use it afterwards. * - * Deprecated: 2.22: Use g_drive_eject_with_operation() instead. + * Since: 2.26 */ /** - * G_TYPE_CLOSURE: + * g_dbus_method_invocation_return_gerror: + * @invocation: A #GDBusMethodInvocation. + * @error: A #GError. * - * The #GType for #GClosure. + * Like g_dbus_method_invocation_return_error() but takes a #GError + * instead of the error domain, error code and message. + * This method will free @invocation, you cannot use it afterwards. + * + * Since: 2.26 */ /** - * GVolumeMonitor::drive-stop-button: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: the drive where the stop button was pressed + * g_dbus_method_invocation_return_value: + * @invocation: A #GDBusMethodInvocation. + * @parameters: A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. * - * Emitted when the stop button is pressed on @drive. + * Finishes handling a D-Bus method call by returning @parameters. + * If the @parameters GVariant is floating, it is consumed. + * It is an error if @parameters is not of the right format. + * This method will free @invocation, you cannot use it afterwards. * - * Since: 2.22 + * Since: 2.26 */ /** - * SECTION:gasynchelpe: - * @short_description: Asynchronous Helper Functions - * @include: gio/gio.h - * @see_also: #GAsyncReady + * g_dbus_node_info_generate_xml: + * @info: A #GDBusNodeInfo. + * @indent: Indentation level. + * @string_builder: A #GString to to append XML data to. * - * Provides helper functions for asynchronous operations. + * Appends an XML representation of @info (and its children) to @string_builder. + * This function is typically used for generating introspection XML documents at run-time for + * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method. + * + * Since: 2.26 */ /** - * g_drive_get_start_stop_type: - * @drive: a #GDrive. + * g_dbus_node_info_lookup_interface: + * @info: A #GDBusNodeInfo. + * @name: A D-Bus interface name. * - * Gets a hint about how a drive can be started/stopped. + * Looks up information about an interface. + * This cost of this function is O(n) in number of interfaces. * - * Returns: A value from the #GDriveStartStopType enumeration. - * Since: 2.22 + * Returns: A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. + * Since: 2.26 */ /** - * g_dbus_connection_new_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). - * @error: Return location for error or %NULL. + * g_dbus_node_info_new_for_xml: + * @xml_data: Valid D-Bus introspection XML. + * @error: Return location for error. * - * Finishes an operation started with g_dbus_connection_new(). + * Parses @xml_data and returns a #GDBusNodeInfo representing the data. + * with g_dbus_node_info_unref(). * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free * Since: 2.26 */ /** - * g_bus_own_name: - * @bus_type: The type of bus to own a name on. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @bus_acquired_handler: Handler to invoke when connected to the bus of type @bus_type or %NULL. - * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL. - * @name_lost_handler: Handler to invoke when @name is lost or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: Function for freeing @user_data or %NULL. + * g_dbus_node_info_ref: + * @info: A #GDBusNodeInfo * - * Starts acquiring @name on the bus specified by @bus_type and calls - * acquired respectively lost. Callbacks will be invoked in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread you are calling this function from. - * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler - * callbacks will be invoked after calling this function - there are three - * possible cases: - * <itemizedlist> - * <listitem><para> - * </para></listitem> - * <listitem><para> - * </para></listitem> - * <listitem><para> - * </para></listitem> - * </itemizedlist> - * When you are done owning the name, just call g_bus_unown_name() - * with the owner id this function returns. - * If the name is acquired or lost (for example another application - * could acquire the name if you allow replacement or the application - * currently owning the name exits), the handlers are also invoked. If the - * #GDBusConnection that is used for attempting to own the name - * closes, then @name_lost_handler is invoked since it is no - * longer possible for other processes to access the process. - * You cannot use g_bus_own_name() several times for the same name (unless - * interleaved with calls to g_bus_unown_name()) - only the first call - * will work. - * Another guarantee is that invocations of @name_acquired_handler - * and @name_lost_handler are guaranteed to alternate; that - * is, if @name_acquired_handler is invoked then you are - * guaranteed that the next time one of the handlers is invoked, it - * will be @name_lost_handler. The reverse is also true. - * If you plan on exporting objects (using e.g. - * g_dbus_connection_register_object()), note that it is generally too late - * to export the objects in @name_acquired_handler. Instead, you can do this - * in @bus_acquired_handler since you are guaranteed that this will run - * before @name is requested from the bus. - * This behavior makes it very simple to write applications that wants - * to own names and export objects, see <xref linkend="gdbus-owning-names"/>. - * Simply register objects to be exported in @bus_acquired_handler and - * unregister the objects (if any) in @name_lost_handler. - * g_bus_unown_name() to stop owning the name. + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. * - * Returns: An identifier (never 0) that an be used with + * Returns: The same @info. * Since: 2.26 */ /** - * g_dbus_message_get_error_name: - * @message: A #GDBusMessage. + * g_dbus_node_info_unref: + * @info: A #GDBusNodeInfo. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. + * If @info is statically allocated, does nothing. Otherwise decreases + * the reference count of @info. When its reference count drops to 0, + * the memory used is freed. * - * Returns: The value. * Since: 2.26 */ /** - * GDBusProxy:g-name-owner: + * g_dbus_property_info_ref: + * @info: A #GDBusPropertyInfo * - * The unique name that owns #GDBusProxy:name or %NULL if no-one - * currently owns that name. You may connect to #GObject::notify signal to - * track changes to this property. + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. * + * Returns: The same @info. * Since: 2.26 */ /** - * g_socket_close: - * @socket: a #GSocket - * @error: #GError for error reporting, or %NULL to ignore. + * g_dbus_property_info_unref: + * @info: A #GDBusPropertyInfo. * - * Closes the socket, shutting down any active connection. - * Closing a socket does not wait for all outstanding I/O operations - * to finish, so the caller should not rely on them to be guaranteed - * to complete even if the close returns with no error. - * Once the socket is closed, all other operations will return - * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not - * return an error. - * Sockets will be automatically closed when the last reference - * is dropped, but you might want to call this function to make sure - * resources are released as early as possible. - * Beware that due to the way that TCP works, it is possible for - * recently-sent data to be lost if either you close a socket while the - * %G_IO_IN condition is set, or else if the remote connection tries to - * send something to you after you close the socket but before it has - * finished reading all of the data you sent. There is no easy generic - * way to avoid this problem; the easiest fix is to design the network - * protocol such that the client will never send data "out of turn". - * Another solution is for the server to half-close the connection by - * calling g_socket_shutdown() with only the @shutdown_write flag set, - * and then wait for the client to notice this and close its side of the - * connection, after which the server can safely call g_socket_close(). - * (This is what #GTcpConnection does if you call - * g_tcp_connection_set_graceful_disconnect(). But of course, this - * only works if the client will close its connection after the server - * does.) + * If @info is statically allocated, does nothing. Otherwise decreases + * the reference count of @info. When its reference count drops to 0, + * the memory used is freed. * - * Returns: %TRUE on success, %FALSE on error - * Since: 2.22 + * Since: 2.26 */ /** - * G_DEFINE_DYNAMIC_TYPE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. + * g_dbus_proxy_call: + * @proxy: A #GDBusProxy. + * @method_name: Name of method to invoke. + * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @flags: Flags from the #GDBusCallFlags enumeration. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @cancellable: A #GCancellable or %NULL. + * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. + * @user_data: The data to pass to @callback. * - * A convenience macro for dynamic type implementations, which declares a - * class initialization function, an instance initialization function (see - * #GTypeInfo for information about these) and a static variable named - * it defines a <function>*_get_type()</function> and a static - * <function>*_register_type()</function> function for use in your - * <function>module_init()</function>. - * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. + * Asynchronously invokes the @method_name method on @proxy. + * If @method_name contains any dots, then @name is split into interface and + * method name parts. This allows using @proxy for invoking methods on + * other interfaces. + * If the #GDBusConnection associated with @proxy is closed then + * the operation will fail with %G_IO_ERROR_CLOSED. If + * %G_IO_ERROR_CANCELLED. If @parameters contains a value not + * compatible with the D-Bus protocol, the operation fails with + * %G_IO_ERROR_INVALID_ARGUMENT. + * If the @parameters #GVariant is floating, it is consumed. This allows + * convenient 'inline' use of g_variant_new(), e.g.: + * |[ + * g_dbus_proxy_call (proxy, + * "TwoStrings", + * g_variant_new ("(ss)", + * "Thing One", + * "Thing Two"), + * G_DBUS_CALL_FLAGS_NONE, + * -1, + * NULL, + * (GAsyncReadyCallback) two_strings_done, + * &data); + * ]| + * This is an asynchronous method. When the operation is finished, + * <link linkend="g-main-context-push-thread-default">thread-default + * main loop</link> of the thread you are calling this method from. + * You can then call g_dbus_proxy_call_finish() to get the result of + * the operation. See g_dbus_proxy_call_sync() for the synchronous + * version of this method. * - * Since: 2.14 + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM: + * g_dbus_proxy_call_finish: + * @proxy: A #GDBusProxy. + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call(). + * @error: Return location for error or %NULL. * - * A key in the "dos" namespace for checking if the file's backup flag - * is set. This attribute is %TRUE if the backup flag is set. This attribute - * is only available for DOS file systems. Corresponding #GFileAttributeType - * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - */ - - -/** - * GOptionGroup: + * Finishes an operation started with g_dbus_proxy_call(). + * return values. Free with g_variant_unref(). * - * A <structname>GOptionGroup</structname> struct defines the options in a single - * group. The struct has only private fields and should not be directly accessed. - * All options in a group share the same translation function. Libraries which - * need to parse commandline options are expected to provide a function for - * getting a <structname>GOptionGroup</structname> holding their options, which - * the application can then add to its #GOptionContext. + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * Since: 2.26 */ /** - * g_dbus_proxy_new_for_bus: - * @bus_type: A #GBusType. - * @flags: Flags used when constructing the proxy. - * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - * @name: A bus name (well-known or unique). - * @object_path: An object path. - * @interface_name: A D-Bus interface name. + * g_dbus_proxy_call_sync: + * @proxy: A #GDBusProxy. + * @method_name: Name of method to invoke. + * @parameters: A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @flags: Flags from the #GDBusCallFlags enumeration. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. * @cancellable: A #GCancellable or %NULL. - * @callback: Callback function to invoke when the proxy is ready. - * @user_data: User data to pass to @callback. + * @error: Return location for error or %NULL. * - * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. - * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. + * Synchronously invokes the @method_name method on @proxy. + * If @method_name contains any dots, then @name is split into interface and + * method name parts. This allows using @proxy for invoking methods on + * other interfaces. + * If the #GDBusConnection associated with @proxy is disconnected then + * the operation will fail with %G_IO_ERROR_CLOSED. If + * %G_IO_ERROR_CANCELLED. If @parameters contains a value not + * compatible with the D-Bus protocol, the operation fails with + * %G_IO_ERROR_INVALID_ARGUMENT. + * If the @parameters #GVariant is floating, it is consumed. This allows + * convenient 'inline' use of g_variant_new(), e.g.: + * |[ + * g_dbus_proxy_call_sync (proxy, + * "TwoStrings", + * g_variant_new ("(ss)", + * "Thing One", + * "Thing Two"), + * G_DBUS_CALL_FLAGS_NONE, + * -1, + * NULL, + * &error); + * ]| + * The calling thread is blocked until a reply is received. See + * g_dbus_proxy_call() for the asynchronous version of this + * method. + * return values. Free with g_variant_unref(). * + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with * Since: 2.26 */ /** - * g_dbus_message_print: - * @message: A #GDBusMessage. - * @indent: Indentation level. + * g_dbus_proxy_get_cached_property: + * @proxy: A #GDBusProxy. + * @property_name: Property name. * - * Produces a human-readable multi-line description of @message. - * The contents of the description has no ABI guarantees, the contents - * and formatting is subject to change at any time. Typical output - * looks something like this: - * <programlisting> - * Headers: - * path -> objectpath '/org/gtk/GDBus/TestObject' - * interface -> 'org.gtk.GDBus.TestInterface' - * member -> 'GimmeStdout' - * destination -> ':1.146' - * UNIX File Descriptors: - * (none) - * </programlisting> - * or - * <programlisting> - * Headers: - * reply-serial -> uint32 4 - * destination -> ':1.159' - * sender -> ':1.146' - * num-unix-fds -> uint32 1 - * UNIX File Descriptors: - * </programlisting> + * Looks up the value for a property from the cache. This call does no + * blocking IO. + * If @proxy has an expected interface (see + * #GDBusProxy:g-interface-info), then @property_name (for existence) + * is checked against it. + * for @property_name or %NULL if the value is not in the cache. The + * returned reference must be freed with g_variant_unref(). * - * Type: method-return - * Flags: no-reply-expected - * Version: 0 - * Serial: 477 - * Body: () - * Fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 - * Returns: A string that should be freed with g_free(). + * Returns: A reference to the #GVariant instance that holds the value * Since: 2.26 */ /** - * g_simple_async_result_set_error_va: (skip) - * @simple: a #GSimpleAsyncResult. - * @domain: a #GQuark (usually #G_IO_ERROR). - * @code: an error code. - * @format: a formatted error reporting string. - * @args: va_list of arguments. + * g_dbus_proxy_get_cached_property_names: + * @proxy: A #GDBusProxy. * - * Sets an error within the asynchronous result without a #GError. - * Unless writing a binding, see g_simple_async_result_set_error(). + * Gets the names of all cached properties on @proxy. + * no cached properties. Free the returned array with g_strfreev(). + * + * Returns: A %NULL-terminated array of strings or %NULL if @proxy has + * Since: 2.26 */ /** - * GBusAcquiredCallback: - * @connection: The #GDBusConnection to a message bus. - * @name: The name that is requested to be owned. - * @user_data: User data passed to g_bus_own_name(). + * g_dbus_proxy_get_connection: + * @proxy: A #GDBusProxy. * - * Invoked when a connection to a message bus has been obtained. + * Gets the connection @proxy is for. * + * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free. * Since: 2.26 */ /** - * g_permission_get_allowed: - * @permission: a #GPermission instance - * @returns: the value of the 'allowed' property + * g_dbus_proxy_get_default_timeout: + * @proxy: A #GDBusProxy. * - * Gets the value of the 'allowed' property. This property is %TRUE if - * the caller currently has permission to perform the action that + * Gets the timeout to use if -1 (specifying default timeout) is + * passed as @timeout_msec in the g_dbus_proxy_call() and + * g_dbus_proxy_call_sync() functions. + * See the #GDBusProxy:g-default-timeout property for more details. * + * Returns: Timeout to use for @proxy. * Since: 2.26 */ /** - * G_VALUE_HOLDS_STRING: - * @value: a valid #GValue structure + * g_dbus_proxy_get_flags: + * @proxy: A #GDBusProxy. * - * Checks whether the given #GValue can hold values of type %G_TYPE_STRING. + * Gets the flags that @proxy was constructed with. * - * Returns: %TRUE on success. + * Returns: Flags from the #GDBusProxyFlags enumeration. + * Since: 2.26 */ /** - * g_app_info_get_fallback_for_type: - * @content_type: the content type to find a #GAppInfo for + * g_dbus_proxy_get_interface_info: + * @proxy: A #GDBusProxy * - * Gets a list of fallback #GAppInfos for a given content type, i.e. - * those applications which claim to support the given content type - * by MIME type subclassing and not directly. - * for given @content_type or %NULL on error. + * Returns the #GDBusInterfaceInfo, if any, specifying the minimal + * interface that @proxy conforms to. + * See the #GDBusProxy:g-interface-info property for more details. + * object, it is owned by @proxy. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos - * Since: 2.28 + * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned + * Since: 2.26 */ /** - * G_VARIANT_TYPE_STRING: + * g_dbus_proxy_get_interface_name: + * @proxy: A #GDBusProxy. * - * The type of a string. "" is a string. %NULL is not a string. + * Gets the D-Bus interface name @proxy is for. + * + * Returns: A string owned by @proxy. Do not free. + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_UNIX_RDEV: + * g_dbus_proxy_get_name: + * @proxy: A #GDBusProxy. * - * A key in the "unix" namespace for getting the device ID for the file - * (if it is a special file). See lstat() documentation. This attribute - * is only available for UNIX file systems. Corresponding #GFileAttributeType - * is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Gets the name that @proxy was constructed for. + * + * Returns: A string owned by @proxy. Do not free. + * Since: 2.26 */ /** - * g_settings_get_mapped: - * @settings: a #GSettings object - * @key: the key to get the value for - * @mapping: (scope call): the function to map the value in the settings database to the value used by the application - * @user_data: user data for @mapping - * @returns: (transfer full): the result, which may be %NULL + * g_dbus_proxy_get_name_owner: + * @proxy: A #GDBusProxy. * - * Gets the value that is stored at @key in @settings, subject to - * application-level validation/mapping. - * You should use this function when the application needs to perform - * some processing on the value of the key (for example, parsing). The - * indicates that the processing was unsuccessful (due to a parse error, - * for example) then the mapping is tried again with another value. - * This allows a robust 'fall back to defaults' behaviour to be - * implemented somewhat automatically. - * The first value that is tried is the user's setting for the key. If - * the mapping function fails to map this value, other values may be - * tried in an unspecified order (system or site defaults, translated - * schema default values, untranslated schema default values, etc). - * If the mapping function fails for all possible values, one additional - * If the mapping function still indicates failure at this point then - * the application will be aborted. - * The result parameter for the @mapping function is pointed to a - * #gpointer which is initially set to %NULL. The same pointer is given - * to each invocation of @mapping. The final value of that #gpointer is - * what is returned by this function. %NULL is valid; it is returned - * just as any other value would be. + * The unique name that owns the name that @proxy is for or %NULL if + * no-one currently owns that name. You may connect to the + * #GObject::notify signal to track changes to the + * #GDBusProxy:g-name-owner property. * - * Attempt is made: the mapping function is called with a %NULL value. + * Returns: The name owner or %NULL if no name owner exists. Free with g_free(). + * Since: 2.26 */ /** - * g_srv_target_get_priority: - * @target: a #GSrvTarget + * g_dbus_proxy_get_object_path: + * @proxy: A #GDBusProxy. * - * Gets @target's priority. You should not need to look at this; - * #GResolver already sorts the targets according to the algorithm in - * RFC 2782. + * Gets the object path @proxy is for. * - * Returns: @target's priority - * Since: 2.22 + * Returns: A string owned by @proxy. Do not free. + * Since: 2.26 */ /** - * GActionGroup::action-state-changed: - * @action_group: the #GActionGroup that changed - * @action_name: the name of the action in @action_group - * @value: the new value of the state + * g_dbus_proxy_new: + * @connection: A #GDBusConnection. + * @flags: Flags used when constructing the proxy. + * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + * @name: A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. + * @object_path: An object path. + * @interface_name: A D-Bus interface name. + * @cancellable: A #GCancellable or %NULL. + * @callback: Callback function to invoke when the proxy is ready. + * @user_data: User data to pass to @callback. * - * Signals that the state of the named action has changed. + * Creates a proxy for accessing @interface_name on the remote object + * at @object_path owned by @name at @connection and asynchronously + * loads D-Bus properties unless the + * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to + * the #GDBusProxy::g-properties-changed signal to get notified about + * property changes. + * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up + * match rules for signals. Connect to the #GDBusProxy::g-signal signal + * to handle signals from the remote object. + * If @name is a well-known name and the + * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name + * owner currently exists, the message bus will be requested to launch + * a name owner for the name. + * This is a failable asynchronous constructor - when the proxy is + * ready, @callback will be invoked and you can use + * g_dbus_proxy_new_finish() to get the result. + * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. + * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. * - * Since: 2.28 + * Since: 2.26 */ /** - * GAppInfoIface: - * @g_iface: The parent interface. - * @dup: Copies a #GAppInfo. - * @equal: Checks two #GAppInfo<!-- -->s for equality. - * @get_id: Gets a string identifier for a #GAppInfo. - * @get_name: Gets the name of the application for a #GAppInfo. - * @get_description: Gets a short description for the application described by the #GAppInfo. - * @get_executable: Gets the executable name for the #GAppInfo. - * @get_icon: Gets the #GIcon for the #GAppInfo. - * @launch: Launches an application specified by the #GAppInfo. - * @supports_uris: Indicates whether the application specified supports launching URIs. - * @supports_files: Indicates whether the application specified accepts filename arguments. - * @launch_uris: Launches an application with a list of URIs. - * @should_show: Returns whether an application should be shown (e.g. when getting a list of installed applications). <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"> <citetitle>FreeDesktop.Org Startup Notification Specification</citetitle></ulink>. - * @set_as_default_for_type: Sets an application as default for a given content type. - * @set_as_default_for_extension: Sets an application as default for a given file extension. - * @add_supports_type: Adds to the #GAppInfo information about supported file types. - * @can_remove_supports_type: Checks for support for removing supported file types from a #GAppInfo. - * @remove_supports_type: Removes a supported application type from a #GAppInfo. - * @can_delete: Checks if a #GAppInfo can be deleted. Since 2.20 - * @do_delete: Deletes a #GAppInfo. Since 2.20 - * @get_commandline: Gets the commandline for the #GAppInfo. Since 2.20 - * @get_display_name: Gets the display name for the #GAppInfo. Since 2.24 + * g_dbus_proxy_new_finish: + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new(). + * @error: Return location for error or %NULL. * - * Application Information interface, for operating system portability. + * Finishes creating a #GDBusProxy. + * + * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). + * Since: 2.26 */ /** - * g_mount_operation_get_choice: - * @op: a #GMountOperation. + * g_dbus_proxy_new_for_bus: + * @bus_type: A #GBusType. + * @flags: Flags used when constructing the proxy. + * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + * @name: A bus name (well-known or unique). + * @object_path: An object path. + * @interface_name: A D-Bus interface name. + * @cancellable: A #GCancellable or %NULL. + * @callback: Callback function to invoke when the proxy is ready. + * @user_data: User data to pass to @callback. * - * Gets a choice from the mount operation. - * the choice's list, or %0. + * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. + * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. * - * Returns: an integer containing an index of the user's choice from + * Since: 2.26 */ /** - * g_zlib_decompressor_new: - * @format: The format to use for the compressed data + * g_dbus_proxy_new_for_bus_finish: + * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus(). + * @error: Return location for error or %NULL. * - * Creates a new #GZlibDecompressor. + * Finishes creating a #GDBusProxy. * - * Returns: a new #GZlibDecompressor - * Since: 2.24 + * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref(). + * Since: 2.26 */ /** - * g_network_service_get_scheme: - * @srv: a #GNetworkService + * g_dbus_proxy_new_for_bus_sync: + * @bus_type: A #GBusType. + * @flags: Flags used when constructing the proxy. + * @info: A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + * @name: A bus name (well-known or unique). + * @object_path: An object path. + * @interface_name: A D-Bus interface name. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Get's the URI scheme used to resolve proxies. By default, the service name - * is used as scheme. + * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. + * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. * - * Returns: @srv's scheme name + * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * Since: 2.26 */ /** - * g_tls_certificate_get_issuer: - * @cert: a #GTlsCertificate + * g_dbus_proxy_new_sync: + * @connection: A #GDBusConnection. + * @flags: Flags used when constructing the proxy. + * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. + * @object_path: An object path. + * @interface_name: A D-Bus interface name. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: (allow-none): Return location for error or %NULL. * - * Gets the #GTlsCertificate representing @cert's issuer, if known - * or %NULL if @cert is self-signed or signed with an unknown - * certificate. + * Creates a proxy for accessing @interface_name on the remote object + * at @object_path owned by @name at @connection and synchronously + * loads D-Bus properties unless the + * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. + * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up + * match rules for signals. Connect to the #GDBusProxy::g-signal signal + * to handle signals from the remote object. + * If @name is a well-known name and the + * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name + * owner currently exists, the message bus will be requested to launch + * a name owner for the name. + * This is a synchronous failable constructor. See g_dbus_proxy_new() + * and g_dbus_proxy_new_finish() for the asynchronous version. + * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used. * - * Returns: (transfer none): The certificate of @cert's issuer, - * Since: 2.28 + * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). + * Since: 2.26 */ @@ -19377,3140 +18470,3025 @@ /** - * g_simple_async_result_set_handle_cancellation: - * @simple: a #GSimpleAsyncResult. - * @handle_cancellation: a #gboolean. - * - * Sets whether to handle cancellation within the asynchronous operation. - */ - - -/** - * g_file_unmount_mountable_with_operation_finish: - * @file: input #GFile. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_dbus_proxy_set_default_timeout: + * @proxy: A #GDBusProxy. + * @timeout_msec: Timeout in milliseconds. * - * Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details. - * Finish an asynchronous unmount operation that was started - * with g_file_unmount_mountable_with_operation(). - * otherwise. + * Sets the timeout to use if -1 (specifying default timeout) is + * passed as @timeout_msec in the g_dbus_proxy_call() and + * g_dbus_proxy_call_sync() functions. + * See the #GDBusProxy:g-default-timeout property for more details. * - * Returns: %TRUE if the operation finished successfully. %FALSE - * Since: 2.22 + * Since: 2.26 */ /** - * g_unix_fd_message_append_fd: - * @message: a #GUnixFDMessage - * @fd: a valid open file descriptor - * @error: a #GError pointer + * g_dbus_proxy_set_interface_info: + * @proxy: A #GDBusProxy + * @info: Minimum interface this proxy conforms to or %NULL to unset. * - * Adds a file descriptor to @message. - * The file descriptor is duplicated using dup(). You keep your copy - * of the descriptor and the copy contained in @message will be closed - * when @message is finalized. - * A possible cause of failure is exceeding the per-process or - * system-wide file descriptor limit. + * Ensure that interactions with @proxy conform to the given + * interface. For example, when completing a method call, if the type + * signature of the message isn't what's expected, the given #GError + * is set. Signals that have a type signature mismatch are simply + * dropped. + * See the #GDBusProxy:g-interface-info property for more details. * - * Returns: %TRUE in case of success, else %FALSE (and @error is set) - * Since: 2.22 + * Since: 2.26 */ /** - * g_dbus_method_invocation_return_value: - * @invocation: A #GDBusMethodInvocation. - * @parameters: A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. + * g_dbus_server_get_client_address: + * @server: A #GDBusServer. * - * Finishes handling a D-Bus method call by returning @parameters. - * If the @parameters GVariant is floating, it is consumed. - * It is an error if @parameters is not of the right format. - * This method will free @invocation, you cannot use it afterwards. + * Gets a D-Bus address string that can be used by clients to connect + * to @server. + * by @server. * + * Returns: A D-Bus address string. Do not free, the string is owned * Since: 2.26 */ /** - * GSocketAddress: - * - * A socket endpoint address, corresponding to <type>struct sockaddr</type> - * or one of its subtypes. - */ - - -/** - * g_io_stream_close_finish: - * @stream: a #GIOStream - * @result: a #GAsyncResult - * @error: a #GError location to store the error occuring, or %NULL to ignore + * g_dbus_server_get_flags: + * @server: A #GDBusServer. * - * Closes a stream. + * Gets the flags for @server. * - * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. - * Since: 2.22 + * Returns: A set of flags from the #GDBusServerFlags enumeration. + * Since: 2.26 */ /** - * g_socket_connection_factory_lookup_type: - * @family: a #GSocketFamily - * @type: a #GSocketType - * @protocol_id: a protocol id + * g_dbus_server_get_guid: + * @server: A #GDBusServer. * - * Looks up the #GType to be used when creating socket connections on - * sockets with the specified @family,@type and @protocol_id. - * If no type is registered, the #GSocketConnection base type is returned. + * Gets the GUID for @server. * - * Returns: a #GType - * Since: 2.22 + * Returns: A D-Bus GUID. Do not free this string, it is owned by @server. + * Since: 2.26 */ /** - * g_tls_connection_get_peer_certificate_errors: - * @conn: a #GTlsConnection - * - * Gets the errors associated with validating @conn's peer's - * certificate, after the handshake has completed. (It is not set - * during the emission of #GTlsConnection::accept-certificate.) + * g_dbus_server_is_active: + * @server: A #GDBusServer. * - * Returns: @conn's peer's certificate errors - * Since: 2.28 - */ - - -/** - * g_file_load_partial_contents_async: (skip) - * @file: input #GFile. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @read_more_callback: a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to the callback functions. + * Gets whether @server is active. * - * Reads the partial contents of a file. A #GFileReadMoreCallback should be - * used to stop reading from the file when appropriate, else this function - * will behave exactly as g_file_load_contents_async(). This operation - * can be finished by g_file_load_partial_contents_finish(). - * Users of this function should be aware that @user_data is passed to - * both the @read_more_callback and the @callback. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Returns: %TRUE if server is active, %FALSE otherwise. + * Since: 2.26 */ /** - * g_io_stream_is_closed: - * @stream: a #GIOStream + * g_dbus_server_new_sync: + * @address: A D-Bus address. + * @flags: Flags from the #GDBusServerFlags enumeration. + * @guid: A D-Bus GUID. + * @observer: A #GDBusAuthObserver or %NULL. + * @cancellable: A #GCancellable or %NULL. + * @error: Return location for server or %NULL. * - * Checks if a stream is closed. + * Creates a new D-Bus server that listens on the first address in + * Once constructed, you can use g_dbus_server_get_client_address() to + * get a D-Bus address string that clients can use to connect. + * Connect to the #GDBusServer::new-connection signal to handle + * incoming connections. + * The returned #GDBusServer isn't active - you have to start it with + * g_dbus_server_start(). + * See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can + * be used. + * This is a synchronous failable constructor. See + * g_dbus_server_new() for the asynchronous version. + * g_object_unref(). * - * Returns: %TRUE if the stream is closed. - * Since: 2.22 + * Returns: A #GDBusServer or %NULL if @error is set. Free with + * Since: 2.26 */ /** - * g_inet_address_get_is_loopback: - * @address: a #GInetAddress + * g_dbus_server_start: + * @server: A #GDBusServer. * - * Tests whether @address is the loopback address for its family. + * Starts @server. * - * Returns: %TRUE if @address is the loopback address for its family. - * Since: 2.22 + * Since: 2.26 */ /** - * g_file_get_parent: - * @file: input #GFile. + * g_dbus_server_stop: + * @server: A #GDBusServer. * - * Gets the parent directory for the @file. - * If the @file represents the root directory of the - * file system, then %NULL will be returned. - * This call does no blocking i/o. - * #GFile or %NULL if there is no parent. - * Free the returned object with g_object_unref(). + * Stops @server. * - * Returns: (transfer full): a #GFile structure to the parent of the given + * Since: 2.26 */ /** - * g_application_get_is_registered: - * @application: a #GApplication - * @returns: %TRUE if @application is registered + * g_dbus_signal_info_ref: + * @info: A #GDBusSignalInfo * - * Checks if @application is registered. - * An application is registered if g_application_register() has been - * successfully called. + * If @info is statically allocated does nothing. Otherwise increases + * the reference count. * - * Since: 2.28 + * Returns: The same @info. + * Since: 2.26 */ /** - * G_TYPE_MAKE_FUNDAMENTAL: - * @x: the fundamental type number. + * g_dbus_signal_info_unref: + * @info: A #GDBusSignalInfo. * - * Get the type ID for the fundamental type number @x. - * Use g_type_fundamental_next() instead of this macro to create new fundamental - * types. + * If @info is statically allocated, does nothing. Otherwise decreases + * the reference count of @info. When its reference count drops to 0, + * the memory used is freed. * - * Returns: the GType + * Since: 2.26 */ /** - * GSocketSourceFunc: - * @socket: the #GSocket - * @condition: the current condition at the source fired. - * @user_data: data passed in by the user. + * g_desktop_app_info_get_filename: + * @info: a #GDesktopAppInfo * - * This is the function type of the callback used for the #GSource - * returned by g_socket_create_source(). + * When @info was created from a known filename, return it. In some + * situations such as the #GDesktopAppInfo returned from + * g_desktop_app_info_new_from_keyfile(), this function will return %NULL. * - * Returns: it should return %FALSE if the source should be removed. - * Since: 2.22 + * Returns: The full path to the file for @info, or %NULL if not known. + * Since: 2.24 */ /** - * G_DEFINE_DYNAMIC_TYPE_EXTENDED: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @TYPE_PARENT: The #GType of the parent type. - * @flags: #GTypeFlags to pass to g_type_module_register_type() - * @CODE: Custom code that gets inserted in the *_get_type() function. + * g_desktop_app_info_get_is_hidden: + * @info: a #GDesktopAppInfo. * - * A more general version of G_DEFINE_DYNAMIC_TYPE() which - * allows to specify #GTypeFlags and custom code. - * |[ - * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, - * gtk_gadget, - * GTK_TYPE_THING, - * 0, - * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, - * gtk_gadget_gizmo_init)); - * ]| - * expands to - * |[ - * static void gtk_gadget_init (GtkGadget *self); - * static void gtk_gadget_class_init (GtkGadgetClass *klass); - * static void gtk_gadget_class_finalize (GtkGadgetClass *klass); - * static gpointer gtk_gadget_parent_class = NULL; - * static GType gtk_gadget_type_id = 0; - * static void gtk_gadget_class_intern_init (gpointer klass) - * { - * gtk_gadget_parent_class = g_type_class_peek_parent (klass); - * gtk_gadget_class_init ((GtkGadgetClass*) klass); - * } - * GType - * gtk_gadget_get_type (void) - * { - * return gtk_gadget_type_id; - * } - * static void - * gtk_gadget_register_type (GTypeModule *type_module) - * { - * const GTypeInfo g_define_type_info = { - * sizeof (GtkGadgetClass), - * (GBaseInitFunc) NULL, - * (GBaseFinalizeFunc) NULL, - * (GClassInitFunc) gtk_gadget_class_intern_init, - * (GClassFinalizeFunc) gtk_gadget_class_finalize, - * NULL, // class_data - * sizeof (GtkGadget), - * 0, // n_preallocs - * (GInstanceInitFunc) gtk_gadget_init, - * NULL // value_table - * }; - * gtk_gadget_type_id = g_type_module_register_type (type_module, - * GTK_TYPE_THING, - * GtkGadget, - * &g_define_type_info, - * (GTypeFlags) flags); - * { - * const GInterfaceInfo g_implement_interface_info = { - * (GInterfaceInitFunc) gtk_gadget_gizmo_init - * }; - * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); - * } - * } - * ]| + * A desktop file is hidden if the Hidden key in it is + * set to True. * - * Since: 2.14 + * Returns: %TRUE if hidden, %FALSE otherwise. */ /** - * g_file_parse_name: - * @parse_name: a file name or path to be parsed. - * - * Constructs a #GFile with the given @parse_name (i.e. something given by g_file_get_parse_name()). - * This operation never fails, but the returned object might not support any I/O - * operation if the @parse_name cannot be parsed. + * g_desktop_app_info_launch_uris_as_manager: + * @appinfo: a #GDesktopAppInfo + * @uris: (element-type utf8): List of URIs + * @launch_context: a #GAppLaunchContext + * @spawn_flags: #GSpawnFlags, used for each process + * @user_setup: (scope call): a #GSpawnChildSetupFunc, used once for each process. + * @user_setup_data: (closure user_setup): User data for @user_setup + * @pid_callback: (scope call): Callback for child processes + * @pid_callback_data: (closure pid_callback): User data for @callback + * @error: a #GError * - * Returns: (transfer full): a new #GFile. + * This function performs the equivalent of g_app_info_launch_uris(), + * but is intended primarily for operating system components that + * launch applications. Ordinary applications should use + * g_app_info_launch_uris(). + * In contrast to g_app_info_launch_uris(), all processes created will + * always be run directly as children as if by the UNIX fork()/exec() + * calls. + * This guarantee allows additional control over the exact environment + * of the child processes, which is provided via a setup function + * semantics of the @setup function. */ /** - * g_simple_async_result_is_valid: - * @result: the #GAsyncResult passed to the _finish function. - * @source: the #GObject passed to the _finish function. - * @source_tag: the asynchronous function. + * g_desktop_app_info_lookup_get_default_for_uri_scheme: + * @lookup: a #GDesktopAppInfoLookup + * @uri_scheme: a string containing a URI scheme. * - * Ensures that the data passed to the _finish function of an async - * operation is consistent. Three checks are performed. - * First, @result is checked to ensure that it is really a - * #GSimpleAsyncResult. Second, @source is checked to ensure that it - * matches the source object of @result. Third, @source_tag is - * checked to ensure that it is either %NULL (as it is when the result was - * created by g_simple_async_report_error_in_idle() or - * g_simple_async_report_gerror_in_idle()) or equal to the - * convention, is a pointer to the _async function corresponding to the - * _finish function from which this function is called). + * Gets the default application for launching applications + * using this URI scheme for a particular GDesktopAppInfoLookup + * implementation. + * The GDesktopAppInfoLookup interface and this function is used + * to implement g_app_info_get_default_for_uri_scheme() backends + * in a GIO module. There is no reason for applications to use it + * directly. Applications should use g_app_info_get_default_for_uri_scheme(). * - * Returns: #TRUE if all checks passed or #FALSE if any failed. - * Since: 2.20 + * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. + * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio. */ /** - * GTlsClientConnection: + * g_desktop_app_info_new: + * @desktop_id: the desktop file id * - * TLS client-side connection; the client-side implementation of a - * #GTlsConnection + * Creates a new #GDesktopAppInfo based on a desktop file id. + * A desktop file id is the basename of the desktop file, including the + * .desktop extension. GIO is looking for a desktop file with this name + * in the <filename>applications</filename> subdirectories of the XDG data + * directories (i.e. the directories specified in the + * <envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment + * variables). GIO also supports the prefix-to-subdirectory mapping that is + * described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu Spec</ulink> + * (i.e. a desktop id of kde-foo.desktop will match + * <filename>/usr/share/applications/kde/foo.desktop</filename>). * - * Since: 2.28 + * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id */ /** - * GDBusInterfaceGetPropertyFunc: - * @connection: A #GDBusConnection. - * @sender: The unique bus name of the remote caller. - * @object_path: The object path that the method was invoked on. - * @interface_name: The D-Bus interface name for the property. - * @property_name: The name of the property to get the value of. - * @error: Return location for error. - * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object(). + * g_desktop_app_info_new_from_filename: + * @filename: the path of a desktop file, in the GLib filename encoding * - * The type of the @get_property function in #GDBusInterfaceVTable. - * consumed - otherwise its reference count is decreased by one. + * Creates a new #GDesktopAppInfo. * - * Returns: A #GVariant with the value for @property_name or %NULL if - * Since: 2.26 + * Returns: a new #GDesktopAppInfo or %NULL on error. */ /** - * g_action_get_parameter_type: - * @action: a #GAction + * g_desktop_app_info_new_from_keyfile: + * @key_file: an opened #GKeyFile * - * Queries the type of the parameter that must be given when activating - * When activating the action using g_action_activate(), the #GVariant - * given to that function must be of the type returned by this function. - * In the case that this function returns %NULL, you must not give any - * #GVariant, but %NULL instead. + * Creates a new #GDesktopAppInfo. * - * Returns: (allow-none): the parameter type - * Since: 2.28 + * Returns: a new #GDesktopAppInfo or %NULL on error. + * Since: 2.18 */ /** - * g_dbus_connection_get_exit_on_close: - * @connection: A #GDBusConnection. - * - * Gets whether the process is terminated when @connection is - * closed by the remote peer. See - * #GDBusConnection:exit-on-close for more details. - * closed by the remote peer. + * g_desktop_app_info_set_desktop_env: + * @desktop_env: a string specifying what desktop this is * - * Returns: Whether the process is terminated when @connection is - * Since: 2.26 + * Sets the name of the desktop that the application is running in. + * This is used by g_app_info_should_show() to evaluate the + * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> + * desktop entry fields. + * The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop + * Menu specification</ulink> recognizes the following: + * <simplelist> + * <member>GNOME</member> + * <member>KDE</member> + * <member>ROX</member> + * <member>XFCE</member> + * <member>Old</member> + * </simplelist> + * Should be called only once; subsequent calls are ignored. */ /** - * GTlsCertificateFlags: - * @G_TLS_CERTIFICATE_UNKNOWN_CA: The signing certificate authority is not known. - * @G_TLS_CERTIFICATE_BAD_IDENTITY: The certificate does not match the expected identity of the site that it was retrieved from. - * @G_TLS_CERTIFICATE_NOT_ACTIVATED: The certificate's activation time is still in the future - * @G_TLS_CERTIFICATE_EXPIRED: The certificate has expired - * @G_TLS_CERTIFICATE_REVOKED: The certificate has been revoked according to the #GTlsContext's certificate revocation list. - * @G_TLS_CERTIFICATE_INSECURE: The certificate's algorithm is considered insecure. - * @G_TLS_CERTIFICATE_GENERIC_ERROR: Some other error occurred validating the certificate - * @G_TLS_CERTIFICATE_VALIDATE_ALL: the combination of all of the above flags + * g_drive_can_eject: + * @drive: a #GDrive. * - * A set of flags describing TLS certification validation. This can be - * used to set which validation steps to perform (eg, with - * g_tls_client_connection_set_validation_flags()), or to describe why - * a particular certificate was rejected (eg, in - * #GTlsConnection::accept-certificate). + * Checks if a drive can be ejected. * - * Since: 2.28 + * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise. */ /** - * GActionInterface: - * @get_name: the virtual function pointer for g_action_get_name() - * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type() - * @get_state_type: the virtual function pointer for g_action_get_state_type() - * @get_state_hint: the virtual function pointer for g_action_get_state_hint() - * @get_enabled: the virtual function pointer for g_action_get_enabled() - * @get_state: the virtual function pointer for g_action_get_state() - * @set_state: the virtual function pointer for g_action_set_state() - * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an 'activate' signal but that implementations of it may have one. - * + * g_drive_can_poll_for_media: + * @drive: a #GDrive. * + * Checks if a drive can be polled for media changes. + * %FALSE otherwise. * - * Since: 2.26 + * Returns: %TRUE if the @drive can be polled for media changes, */ /** - * g_vfs_get_local: + * g_drive_can_start: + * @drive: a #GDrive. * - * Gets the local #GVfs for the system. + * Checks if a drive can be started. * - * Returns: (transfer none): a #GVfs. + * Returns: %TRUE if the @drive can be started, %FALSE otherwise. + * Since: 2.22 */ /** - * GParamSpecBoxed: - * @parent_instance: private #GParamSpec portion + * g_drive_can_start_degraded: + * @drive: a #GDrive. * - * A #GParamSpec derived structure that contains the meta data for boxed properties. + * Checks if a drive can be started degraded. + * + * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise. + * Since: 2.22 */ /** - * g_atomic_int_dec_and_test: - * @atomic: a pointer to an integer + * g_drive_can_stop: + * @drive: a #GDrive. * - * Atomically decrements the integer pointed to by @atomic by 1. - * after decrementing it + * Checks if a drive can be stopped. * - * Returns: %TRUE if the integer pointed to by @atomic is 0 - * Since: 2.4 + * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise. + * Since: 2.22 */ /** - * g_dbus_message_get_signature: - * @message: A #GDBusMessage. + * g_drive_eject: + * @drive: a #GDrive. + * @flags: flags affecting the unmount if required for eject + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data to pass to @callback * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. + * Asynchronously ejects a drive. + * When the operation is finished, @callback will be called. + * You can then call g_drive_eject_finish() to obtain the + * result of the operation. * - * Returns: The value. - * Since: 2.26 + * Deprecated: 2.22: Use g_drive_eject_with_operation() instead. */ /** - * g_file_info_get_attribute_data: - * @info: a #GFileInfo - * @attribute: a file attribute key - * @type: (out) (allow-none): return location for the attribute type, or %NULL - * @value_pp: (out) (allow-none): return location for the attribute value, or %NULL - * @status: (out) (allow-none): return location for the attribute status, or %NULL + * g_drive_eject_finish: + * @drive: a #GDrive. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Gets the attribute type, value and status for an attribute key. + * Finishes ejecting a drive. * %FALSE otherwise. * - * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, - */ - - -/** - * SECTION:gsrvtarge: - * @short_description: DNS SRV record target - * @include: gio/gio.h - * - * SRV (service) records are used by some network protocols to provide - * service-specific aliasing and load-balancing. For example, XMPP - * (Jabber) uses SRV records to locate the XMPP server for a domain; - * rather than connecting directly to "example.com" or assuming a - * specific server hostname like "xmpp.example.com", an XMPP client - * would look up the "xmpp-client" SRV record for "example.com", and - * then connect to whatever host was pointed to by that record. - * You can use g_resolver_lookup_service() or - * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s - * for a given service. However, if you are simply planning to connect - * to the remote service, you can use #GNetworkService's - * #GSocketConnectable interface and not need to worry about - * #GSrvTarget at all. + * Returns: %TRUE if the drive has been ejected successfully, + * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead. */ /** - * g_proxy_resolver_is_supported: - * @resolver: a #GProxyResolver + * g_drive_eject_with_operation: + * @drive: a #GDrive. + * @flags: flags affecting the unmount if required for eject + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * Checks if @resolver can be used on this system. (This is used - * internally; g_proxy_resolver_get_default() will only return a proxy - * resolver that returns %TRUE for this method.) + * Ejects a drive. This is an asynchronous operation, and is + * finished by calling g_drive_eject_with_operation_finish() with the @drive + * and #GAsyncResult data returned in the @callback. * - * Returns: %TRUE if @resolver is supported. - * Since: 2.26 + * Since: 2.22 */ /** - * GSettings::writable-change-event: - * @settings: the object on which the signal was emitted - * @key: the quark of the key, or 0 - * @returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. + * g_drive_eject_with_operation_finish: + * @drive: a #GDrive. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * The "writable-change-event" signal is emitted once per writability - * change event that affects this settings object. You should connect - * to this signal if you are interested in viewing groups of changes - * before they are split out into multiple emissions of the - * "writable-changed" signal. For most use cases it is more - * appropriate to use the "writable-changed" signal. - * In the event that the writability change applies only to a single - * key, @key will be set to the #GQuark for that key. In the event - * that the writability change affects the entire settings object, - * The default handler for this signal invokes the "writable-changed" - * and "changed" signals for each affected key. This is done because - * changes in writability might also imply changes in value (if for - * example, a new mandatory setting is introduced). If any other - * connected handler returns %TRUE then this default functionality - * will be supressed. + * Finishes ejecting a drive. If any errors occurred during the operation, + * + * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise. + * Since: 2.22 */ /** - * GDBusError: + * g_drive_enumerate_identifiers: + * @drive: a #GDrive * - * A generic error; "something went wrong" - see the error message for - * more. - * There was not enough memory to complete an operation. - * The bus doesn't know how to launch a service to supply the bus name - * you wanted. - * The bus name you referenced doesn't exist (i.e. no application owns - * it). - * No reply to a message expecting one, usually means a timeout occurred. - * Something went wrong reading or writing to a socket, for example. - * A D-Bus bus address was malformed. - * Requested operation isn't supported (like ENOSYS on UNIX). - * Some limited resource is exhausted. - * Security restrictions don't allow doing what you're trying to do. - * Authentication didn't work. - * Unable to connect to server (probably caused by ECONNREFUSED on a - * socket). - * Certain timeout errors, possibly ETIMEDOUT on a socket. Note that - * %G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning: - * this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also - * exists. We can't fix it for compatibility reasons so just be - * careful. - * No network access (probably ENETUNREACH on a socket). - * Can't bind a socket since its address is in use (i.e. EADDRINUSE). - * The connection is disconnected and you're trying to use it. - * Invalid arguments passed to a method call. - * Missing file. - * Existing file and the operation you're using does not silently overwrite. - * Method name you invoked isn't known by the object you invoked it on. - * confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We - * can't fix it for compatibility reasons so just be careful. - * Tried to remove or modify a match rule that didn't exist. - * The match rule isn't syntactically valid. - * While starting a new process, the exec() call failed. - * While starting a new process, the fork() call failed. - * While starting a new process, the child exited with a status code. - * While starting a new process, the child exited on a signal. - * While starting a new process, something went wrong. - * We failed to setup the environment correctly. - * We failed to setup the config parser correctly. - * Bus name was not valid. - * Service file not found in system-services directory. - * Permissions are incorrect on the setuid helper. - * Service file invalid (Name, User or Exec missing). - * Tried to get a UNIX process ID and it wasn't available. - * Tried to get a UNIX process ID and it wasn't available. - * A type signature is not valid. - * A file contains invalid syntax or is otherwise broken. - * Asked for SELinux security context and it wasn't available. - * Asked for ADT audit data and it wasn't available. - * There's already an object with the requested object path. - * Error codes for the %G_DBUS_ERROR error domain. + * Gets the kinds of identifiers that @drive has. + * Use g_drive_get_identifer() to obtain the identifiers + * themselves. + * array of strings containing kinds of identifiers. Use g_strfreev() + * to free. * - * Certain timeout errors, e.g. while starting a service. warning: this is - * Since: 2.26 + * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated */ /** - * g_socket_get_keepalive: - * @socket: a #GSocket. + * g_drive_get_icon: + * @drive: a #GDrive. * - * Gets the keepalive mode of the socket. For details on this, - * see g_socket_set_keepalive(). + * Gets the icon for @drive. + * Free the returned object with g_object_unref(). * - * Returns: %TRUE if keepalive is active, %FALSE otherwise. - * Since: 2.22 + * Returns: (transfer full): #GIcon for the @drive. */ /** - * g_dbus_generate_guid: + * g_drive_get_identifier: + * @drive: a #GDrive + * @kind: the kind of identifier to return * - * Generate a D-Bus GUID that can be used with - * e.g. g_dbus_connection_new(). - * See the D-Bus specification regarding what strings are valid D-Bus - * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). + * Gets the identifier of the given kind for @drive. + * requested identfier, or %NULL if the #GDrive + * doesn't have this kind of identifier. * - * Returns: A valid D-Bus GUID. Free with g_free(). - * Since: 2.26 + * Returns: a newly allocated string containing the */ /** - * SECTION:gico: - * @short_description: Interface for icons - * @include: gio/gio.h + * g_drive_get_name: + * @drive: a #GDrive. * - * #GIcon is a very minimal interface for icons. It provides functions - * for checking the equality of two icons, hashing of icons and - * serializing an icon to and from strings. - * #GIcon does not provide the actual pixmap for the icon as this is out - * of GIO's scope, however implementations of #GIcon may contain the name - * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon). - * To obtain a hash of a #GIcon, see g_icon_hash(). - * To check if two #GIcons are equal, see g_icon_equal(). - * For serializing a #GIcon, use g_icon_to_string() and - * g_icon_new_for_string(). - * If your application or library provides one or more #GIcon - * implementations you need to ensure that each #GType is registered - * with the type system prior to calling g_icon_new_for_string(). - */ - - -/** - * GSignalFlags: - * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage. - * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage. - * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage. - * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted. - * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions. - * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code. - * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. + * Gets the name of @drive. + * string should be freed when no longer needed. * - * The signal flags are used to specify a signal's behaviour, the overall - * signal description outlines how especially the RUN flags control the - * stages of a signal emission. + * Returns: a string containing @drive's name. The returned */ /** - * g_socket_receive: - * @socket: a #GSocket - * @buffer: a buffer to read data into (which should be at least @size bytes long). - * @size: the number of bytes you want to read from the socket - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_drive_get_start_stop_type: + * @drive: a #GDrive. * - * Receive data (up to @size bytes) from a socket. This is mainly used by - * connection-oriented sockets; it is identical to g_socket_receive_from() - * with @address set to %NULL. - * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets, - * g_socket_receive() will always read either 0 or 1 complete messages from - * the socket. If the received message is too large to fit in @buffer, then - * the data beyond @size bytes will be discarded, without any explicit - * indication that this has occurred. - * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any - * number of bytes, up to @size. If more than @size bytes have been - * received, the additional data will be returned in future calls to - * g_socket_receive(). - * If the socket is in blocking mode the call will block until there is - * some data to receive or there is an error. If there is no data available - * and the socket is in non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error - * will be returned. To be notified when data is available, wait for the - * %G_IO_IN condition. - * On error -1 is returned and @error is set accordingly. + * Gets a hint about how a drive can be started/stopped. * - * Returns: Number of bytes read, or -1 on error + * Returns: A value from the #GDriveStartStopType enumeration. * Since: 2.22 */ /** - * g_dbus_message_set_unix_fd_list: - * @message: A #GDBusMessage. - * @fd_list: (allow-none): A #GUnixFDList or %NULL. + * g_drive_get_volumes: + * @drive: a #GDrive. * - * Sets the UNIX file descriptors associated with @message. As a - * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header - * field is set to the number of fds in @fd_list (or cleared if - * This method is only available on UNIX. + * Get a list of mountable volumes for @drive. + * The returned list should be freed with g_list_free(), after + * its elements have been unreffed with g_object_unref(). * - * Since: 2.26 + * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive. */ /** - * g_socket_connect: - * @socket: a #GSocket. - * @address: a #GSocketAddress specifying the remote address. - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_drive_has_media: + * @drive: a #GDrive. * - * Connect the socket to the specified remote address. - * For connection oriented socket this generally means we attempt to make - * a connection to the @address. For a connection-less socket it sets - * the default address for g_socket_send() and discards all incoming datagrams - * from other sources. - * Generally connection oriented sockets can only connect once, but - * connection-less sockets can connect multiple times to change the - * default address. - * If the connect call needs to do network I/O it will block, unless - * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned - * and the user can be notified of the connection finishing by waiting - * for the G_IO_OUT condition. The result of the connection can then be - * checked with g_socket_check_connect_result(). + * Checks if the @drive has media. Note that the OS may not be polling + * the drive for media changes; see g_drive_is_media_check_automatic() + * for more details. * - * Returns: %TRUE if connected, %FALSE on error. - * Since: 2.22 + * Returns: %TRUE if @drive has media, %FALSE otherwise. */ /** - * GDBusProxy: + * g_drive_has_volumes: + * @drive: a #GDrive. * - * The #GDBusProxy structure contains only private data and - * should only be accessed using the provided API. + * Check if @drive has any mountable volumes. * - * Since: 2.26 + * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise. */ /** - * g_file_read_async: - * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * g_drive_is_media_check_automatic: + * @drive: a #GDrive. * - * Asynchronously opens @file for reading. - * For more details, see g_file_read() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_read_finish() to get the result of the operation. + * Checks if @drive is capabable of automatically detecting media changes. + * media changes, %FALSE otherwise. + * + * Returns: %TRUE if the @drive is capabable of automatically detecting */ /** - * g_dbus_server_get_flags: - * @server: A #GDBusServer. + * g_drive_is_media_removable: + * @drive: a #GDrive. * - * Gets the flags for @server. + * Checks if the @drive supports removable media. * - * Returns: A set of flags from the #GDBusServerFlags enumeration. - * Since: 2.26 + * Returns: %TRUE if @drive supports removable media, %FALSE otherwise. */ /** - * GMemoryOutputStream:data: - * - * Pointer to buffer where data will be written. + * g_drive_poll_for_media: + * @drive: a #GDrive. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data to pass to @callback * - * Since: 2.24 + * Asynchronously polls @drive to see if media has been inserted or removed. + * When the operation is finished, @callback will be called. + * You can then call g_drive_poll_for_media_finish() to obtain the + * result of the operation. */ /** - * g_settings_list_relocatable_schemas: + * g_drive_poll_for_media_finish: + * @drive: a #GDrive. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Gets a list of the relocatable #GSettings schemas installed on the - * system. These are schemas that do not provide their own path. It is - * usual to instantiate these schemas directly, but if you want to you - * can use g_settings_new_with_path() to specify the path. - * The output of this function, tTaken together with the output of - * g_settings_list_schemas() represents the complete list of all - * installed schemas. - * #GSettings schemas that are available. The list must not be - * modified or freed. + * Finishes an operation started with g_drive_poll_for_media() on a drive. + * %FALSE otherwise. * - * Returns: (element-type utf8) (transfer none): a list of relocatable - * Since: 2.28 + * Returns: %TRUE if the drive has been poll_for_mediaed successfully, */ /** - * G_VARIANT_TYPE_UINT32: + * g_drive_start: + * @drive: a #GDrive. + * @flags: flags affecting the start operation. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data to pass to @callback * - * The type of an integer value that can range from 0 to 4294967295. - * That's one number for everyone who was around in the late 1970s. + * Asynchronously starts a drive. + * When the operation is finished, @callback will be called. + * You can then call g_drive_start_finish() to obtain the + * result of the operation. + * + * Since: 2.22 */ /** - * SECTION:gmoun: - * @short_description: Mount management - * @include: gio/gio.h - * @see_also: GVolume, GUnixMount + * g_drive_start_finish: + * @drive: a #GDrive. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * The #GMount interface represents user-visible mounts. Note, when - * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume. - * #GMount is a "mounted" filesystem that you can access. Mounted is in - * quotes because it's not the same as a unix mount, it might be a gvfs - * mount, but you can still access the files on it if you use GIO. Might or - * might not be related to a volume object. - * Unmounting a #GMount instance is an asynchronous operation. For - * more information about asynchronous operations, see #GAsyncReady - * and #GSimpleAsyncReady. To unmount a #GMount instance, first call - * g_mount_unmount_with_operation() with (at least) the #GMount instance and a - * #GAsyncReadyCallback. The callback will be fired when the - * operation has resolved (either with success or failure), and a - * #GAsyncReady structure will be passed to the callback. That - * callback should then call g_mount_unmount_with_operation_finish() with the #GMount - * and the #GAsyncReady data to see if the operation was completed - * successfully. If an @error is present when g_mount_unmount_with_operation_finish() - * is called, then it will be filled with any error information. + * Finishes starting a drive. + * %FALSE otherwise. + * + * Returns: %TRUE if the drive has been started successfully, + * Since: 2.22 */ /** - * g_drive_eject_with_operation: + * g_drive_stop: * @drive: a #GDrive. - * @flags: flags affecting the unmount if required for eject + * @flags: flags affecting the unmount if required for stopping. * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * @user_data: user data to pass to @callback * - * Ejects a drive. This is an asynchronous operation, and is - * finished by calling g_drive_eject_with_operation_finish() with the @drive - * and #GAsyncResult data returned in the @callback. + * Asynchronously stops a drive. + * When the operation is finished, @callback will be called. + * You can then call g_drive_stop_finish() to obtain the + * result of the operation. * * Since: 2.22 */ /** - * g_renew: - * @struct_type: the type of the elements to allocate - * @mem: the currently allocated memory - * @n_structs: the number of elements to allocate + * g_drive_stop_finish: + * @drive: a #GDrive. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Reallocates the memory pointed to by @mem, so that it now has space for - * the memory, which may have been moved. - * Care is taken to avoid overflow when calculating the size of the allocated block. + * Finishes stopping a drive. + * %FALSE otherwise. * - * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type + * Returns: %TRUE if the drive has been stopped successfully, + * Since: 2.22 */ /** - * g_mount_can_unmount: - * @mount: a #GMount. + * g_emblem_get_icon: + * @emblem: a #GEmblem from which the icon should be extracted. * - * Checks if @mount can be mounted. + * Gives back the icon from @emblem. + * the emblem and should not be modified or freed. * - * Returns: %TRUE if the @mount can be unmounted. + * Returns: (transfer none): a #GIcon. The returned object belongs to + * Since: 2.18 */ /** - * GParamSpecValueArray: - * @parent_instance: private #GParamSpec portion - * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL - * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements + * g_emblem_get_origin: + * @emblem: a #GEmblem * - * A #GParamSpec derived structure that contains the meta data for #GValueArray properties. + * Gets the origin of the emblem. + * + * Returns: (transfer none): the origin of the emblem + * Since: 2.18 */ /** - * GCopyFunc: - * @src: A pointer to the data which should be copied - * @data: Additional data + * g_emblem_new: + * @icon: a GIcon containing the icon. * - * A function of this signature is used to copy the node data - * when doing a deep-copy of a tree. + * Creates a new emblem for @icon. * - * Returns: A pointer to the copy - * Since: 2.4 + * Returns: a new #GEmblem. + * Since: 2.18 */ /** - * g_dbus_connection_register_object: - * @connection: A #GDBusConnection. - * @object_path: The object path to register at. - * @interface_info: Introspection data for the interface. - * @vtable: A #GDBusInterfaceVTable to call into or %NULL. - * @user_data: Data to pass to functions in @vtable. - * @user_data_free_func: Function to call when the object path is unregistered. - * @error: Return location for error or %NULL. + * g_emblem_new_with_origin: + * @icon: a GIcon containing the icon. + * @origin: a GEmblemOrigin enum defining the emblem's origin * - * Registers callbacks for exported objects at @object_path with the - * D-Bus interface that is described in @interface_info. - * Calls to functions in @vtable (and @user_data_free_func) will - * happen in the <link linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread you are calling this method from. - * Note that all #GVariant values passed to functions in @vtable will match - * the signature given in @interface_info - if a remote caller passes - * incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> - * is returned to the remote caller. - * Additionally, if the remote caller attempts to invoke methods or - * access properties not mentioned in @interface_info the - * <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp. - * <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors - * are returned to the caller. - * It is considered a programming error if the - * #GDBusInterfaceGetPropertyFunc function in @vtable returns a - * #GVariant of incorrect type. - * If an existing callback is already registered at @object_path and - * GDBus automatically implements the standard D-Bus interfaces - * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable - * and org.freedesktop.Peer, so you don't have to implement those for - * the objects you export. You <emphasis>can</emphasis> implement - * org.freedesktop.DBus.Properties yourself, e.g. to handle getting - * and setting of properties asynchronously. - * Note that the reference count on @interface_info will be - * incremented by 1 (unless allocated statically, e.g. if the - * reference count is -1, see g_dbus_interface_info_ref()) for as long - * as the object is exported. Also note that @vtable will be copied. - * See <xref linkend="gdbus-server"/> for an example of how to use this method. - * that can be used with g_dbus_connection_unregister_object() . + * Creates a new emblem for @icon. * - * Returns: 0 if @error is set, otherwise a registration id (never 0) - * Since: 2.26 + * Returns: a new #GEmblem. + * Since: 2.18 */ /** - * GAskPasswordFlags: - * @G_ASK_PASSWORD_NEED_PASSWORD: operation requires a password. - * @G_ASK_PASSWORD_NEED_USERNAME: operation requires a username. - * @G_ASK_PASSWORD_NEED_DOMAIN: operation requires a domain. - * @G_ASK_PASSWORD_SAVING_SUPPORTED: operation supports saving settings. - * @G_ASK_PASSWORD_ANONYMOUS_SUPPORTED: operation supports anonymous users. + * g_emblemed_icon_add_emblem: + * @emblemed: a #GEmblemedIcon + * @emblem: a #GEmblem * - * #GAskPasswordFlags are used to request specific information from the - * user, or to notify the user of their choices in an authentication - * situation. + * Adds @emblem to the #GList of #GEmblem <!-- -->s. + * + * Since: 2.18 */ /** - * g_icon_hash: - * @icon: #gconstpointer to an icon object. + * g_emblemed_icon_clear_emblems: + * @emblemed: a #GEmblemedIcon * - * Gets a hash for an icon. - * use in a #GHashTable or similar data structure. + * Removes all the emblems from @icon. * - * Virtual: hash - * Returns: a #guint containing a hash for the @icon, suitable for + * Since: 2.28 */ /** - * g_application_command_line_get_exit_status: - * @cmdline: a #GApplicationCommandLine + * g_emblemed_icon_get_emblems: + * @emblemed: a #GEmblemedIcon * - * Gets the exit status of @cmdline. See - * g_application_command_line_set_exit_status() for more information. + * Gets the list of emblems for the @icon. + * #GEmblem <!-- -->s that is owned by @emblemed * - * Returns: the exit status - * Since: 2.28 + * Returns: (element-type Gio.Emblem) (transfer none): a #GList of + * Since: 2.18 */ /** - * g_socket_get_listen_backlog: - * @socket: a #GSocket. + * g_emblemed_icon_get_icon: + * @emblemed: a #GEmblemedIcon * - * Gets the listen backlog setting of the socket. For details on this, - * see g_socket_set_listen_backlog(). + * Gets the main icon for @emblemed. * - * Returns: the maximum number of pending connections. - * Since: 2.22 + * Returns: (transfer none): a #GIcon that is owned by @emblemed + * Since: 2.18 */ /** - * g_async_initable_new_valist_async: - * @object_type: a #GType supporting #GAsyncInitable. - * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. - * @var_args: The var args list generated from @first_property_name. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished - * @user_data: the data to pass to callback function + * g_emblemed_icon_new: + * @icon: a #GIcon + * @emblem: (allow-none): a #GEmblem, or %NULL * - * Helper function for constructing #GAsyncInitiable object. This is - * similar to g_object_new_valist() but also initializes the object - * asynchronously. - * When the initialization is finished, @callback will be called. You can - * then call g_async_initable_new_finish() to get the new object and check - * for any errors. + * Creates a new emblemed icon for @icon with the emblem @emblem. * - * Since: 2.22 + * Returns: (transfer full): a new #GIcon + * Since: 2.18 */ /** - * g_network_service_get_protocol: - * @srv: a #GNetworkService + * g_file_append_to: + * @file: input #GFile. + * @flags: a set of #GFileCreateFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Gets @srv's protocol name (eg, "tcp"). + * Gets an output stream for appending data to the file. If + * the file doesn't already exist it is created. + * By default files created are generally readable by everyone, + * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file + * will be made readable only to the current user, to the level that + * is supported on the target filesystem. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Some file systems don't allow all file names, and may + * return an %G_IO_ERROR_INVALID_FILENAME error. + * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be + * returned. Other errors are possible too, and depend on what kind of + * filesystem the file is on. + * Free the returned object with g_object_unref(). * - * Returns: @srv's protocol name - * Since: 2.22 + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. */ /** - * g_unix_fd_message_new: - * - * Creates a new #GUnixFDMessage containing an empty file descriptor - * list. + * g_file_append_to_async: + * @file: input #GFile. + * @flags: a set of #GFileCreateFlags. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Returns: a new #GUnixFDMessage - * Since: 2.22 + * Asynchronously opens @file for appending. + * For more details, see g_file_append_to() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_append_to_finish() to get the result of the operation. */ /** - * GIOSchedulerJob: + * g_file_append_to_finish: + * @file: input #GFile. + * @res: #GAsyncResult + * @error: a #GError, or %NULL * - * Opaque class for definining and scheduling IO jobs. + * Finishes an asynchronous file append operation started with + * g_file_append_to_async(). + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error. */ /** - * G_VARIANT_TYPE_DOUBLE: + * g_file_attribute_info_list_add: + * @list: a #GFileAttributeInfoList. + * @name: the name of the attribute to add. + * @type: the #GFileAttributeType for the attribute. + * @flags: #GFileAttributeInfoFlags for the attribute. * - * The type of a double precision IEEE754 floating point number. - * These guys go up to about 1.80e308 (plus and minus) but miss out on - * some numbers in between. In any case, that's far greater than the - * estimated number of fundamental particles in the observable - * universe. + * Adds a new attribute with @name to the @list, setting + * its @type and @flags. */ /** - * GTypeInterfaceCheckFunc: - * @check_data: data passed to g_type_add_interface_check(). - * @g_iface: the interface that has been initialized + * g_file_attribute_info_list_dup: + * @list: a #GFileAttributeInfoList to duplicate. * - * A callback called after an interface vtable is initialized. - * See g_type_add_interface_check(). + * Makes a duplicate of a file attribute info list. * - * Since: 2.4 + * Returns: a copy of the given @list. */ /** - * G_TYPE_FLAGS: + * g_file_attribute_info_list_lookup: + * @list: a #GFileAttributeInfoList. + * @name: the name of the attribute to lookup. * - * The fundamental type from which all flags types are derived. + * Gets the file attribute with the name @name from @list. + * attribute isn't found. + * + * Returns: a #GFileAttributeInfo for the @name, or %NULL if an */ /** - * g_settings_get_child: - * @settings: a #GSettings object - * @name: the name of the 'child' schema - * @returns: (transfer full): a 'child' settings object + * g_file_attribute_info_list_new: * - * Creates a 'child' settings object which has a base path of - * <replaceable>base-path</replaceable>/@name, where - * <replaceable>base-path</replaceable> is the base path of @settings. - * The schema for the child settings object must have been declared - * in the schema of @settings using a <tag class="starttag">child</tag> element. + * Creates a new file attribute info list. * - * Since: 2.26 + * Returns: a #GFileAttributeInfoList. */ /** - * GFlagsClass: - * @g_type_class: the parent class - * @mask: a mask covering all possible values. - * @n_values: the number of possible values. - * @values: an array of #GFlagsValue structs describing the individual values. + * g_file_attribute_info_list_ref: + * @list: a #GFileAttributeInfoList to reference. * - * The class of a flags type holds information about its - * possible values. + * References a file attribute info list. + * + * Returns: #GFileAttributeInfoList or %NULL on error. */ /** - * g_simple_action_group_new: - * - * Creates a new, empty, #GSimpleActionGroup. + * g_file_attribute_info_list_unref: + * @list: The #GFileAttributeInfoList to unreference. * - * Returns: a new #GSimpleActionGroup - * Since: 2.28 + * Removes a reference from the given @list. If the reference count + * falls to zero, the @list is deleted. */ /** - * g_resolver_lookup_by_address_async: - * @resolver: a #GResolver - * @address: the address to reverse-resolve - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback + * g_file_attribute_matcher_enumerate_namespace: + * @matcher: a #GFileAttributeMatcher. + * @ns: a string containing a file attribute namespace. * - * Begins asynchronously reverse-resolving @address to determine its - * associated hostname, and eventually calls @callback, which must - * call g_resolver_lookup_by_address_finish() to get the final result. + * Checks if the matcher will match all of the keys in a given namespace. + * This will always return %TRUE if a wildcard character is in use (e.g. if + * matcher was created with "standard::*" and @ns is "standard", or if matcher was created + * using "*" and namespace is anything.) + * in the given @ns, %FALSE otherwise. * - * Since: 2.22 + * Todo: this is awkwardly worded. + * Returns: %TRUE if the matcher matches all of the entries */ /** - * g_dbus_method_info_ref: - * @info: A #GDBusMethodInfo + * g_file_attribute_matcher_enumerate_next: + * @matcher: a #GFileAttributeMatcher. * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * Gets the next matched attribute from a #GFileAttributeMatcher. + * no more attribute exist. * - * Returns: The same @info. - * Since: 2.26 + * Returns: a string containing the next attribute or %NULL if */ /** - * G_TYPE_DBUS_SIGNAL_INFO: + * g_file_attribute_matcher_matches: + * @matcher: a #GFileAttributeMatcher. + * @attribute: a file attribute key. * - * The #GType for a boxed type holding a #GDBusSignalInfo. + * Checks if an attribute will be matched by an attribute matcher. If + * the matcher was created with the "*" matching string, this function + * will always return %TRUE. * - * Since: 2.26 + * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise. */ /** - * g_dbus_connection_signal_subscribe: - * @connection: A #GDBusConnection. - * @sender: Sender name to match on (unique or well-known name) or %NULL to listen from all senders. - * @interface_name: D-Bus interface name to match on or %NULL to match on all interfaces. - * @member: D-Bus signal name to match on or %NULL to match on all signals. - * @object_path: Object path to match on or %NULL to match on all object paths. - * @arg0: Contents of first string argument to match on or %NULL to match on all kinds of arguments. - * @flags: Flags describing how to subscribe to the signal (currently unused). - * @callback: Callback to invoke when there is a signal matching the requested data. - * @user_data: User data to pass to @callback. - * @user_data_free_func: Function to free @user_data with when subscription is removed or %NULL. + * g_file_attribute_matcher_matches_only: + * @matcher: a #GFileAttributeMatcher. + * @attribute: a file attribute key. * - * Subscribes to signals on @connection and invokes @callback with a - * whenever the signal is received. Note that @callback - * will be invoked in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * loop</link> of the thread you are calling this method from. - * If @connection is not a message bus connection, @sender must be - * %NULL. - * If @sender is a well-known name note that @callback is invoked with - * the unique name for the owner of @sender, not the well-known name - * as one would expect. This is because the message bus rewrites the - * name. As such, to avoid certain race conditions, users should be - * tracking the name owner of the well-known name and use that when - * processing the received signal. + * Checks if a attribute matcher only matches a given attribute. Always + * returns %FALSE if "*" was used when creating the matcher. * - * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe(). - * Since: 2.26 + * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise. */ /** - * g_themed_icon_append_name: - * @icon: a #GThemedIcon - * @iconname: name of icon to append to list of icons from within @icon. + * g_file_attribute_matcher_new: + * @attributes: an attribute string to match. * - * Append a name to the list of icons from within @icon. - * <note><para> - * Note that doing so invalidates the hash computed by prior calls - * to g_icon_hash(). - * </para></note> + * Creates a new file attribute matcher, which matches attributes + * against a given string. #GFileAttributeMatcher<!-- -->s are reference + * counted structures, and are created with a reference count of 1. If + * the number of references falls to 0, the #GFileAttributeMatcher is + * automatically destroyed. + * The @attribute string should be formatted with specific keys separated + * from namespaces with a double colon. Several "namespace::key" strings may be + * concatenated with a single comma (e.g. "standard::type,standard::is-hidden"). + * The wildcard "*" may be used to match all keys and namespaces, or + * "namespace::*" will match all keys in a given namespace. + * Examples of strings to use: + * <table> + * <title>File Attribute Matcher strings and results</title> + * <tgroup cols='2' align='left'><thead> + * <row><entry> Matcher String </entry><entry> Matches </entry></row></thead> + * <tbody> + * <row><entry>"*"</entry><entry>matches all attributes.</entry></row> + * <row><entry>"standard::is-hidden"</entry><entry>matches only the key is-hidden in the standard namespace.</entry></row> + * <row><entry>"standard::type,unix::*"</entry><entry>matches the type key in the standard namespace and + * all keys in the unix namespace.</entry></row> + * </tbody></tgroup> + * </table> + * + * Returns: a #GFileAttributeMatcher. */ /** - * g_socket_listener_add_socket: - * @listener: a #GSocketListener - * @socket: a listening #GSocket - * @source_object: (allow-none): Optional #GObject identifying this source - * @error: #GError for error reporting, or %NULL to ignore. + * g_file_attribute_matcher_ref: + * @matcher: a #GFileAttributeMatcher. * - * Adds @socket to the set of sockets that we try to accept - * new clients from. The socket must be bound to a local - * address and listened to. - * to accept to identify this particular source, which is - * useful if you're listening on multiple addresses and do - * different things depending on what address is connected to. + * References a file attribute matcher. * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 + * Returns: a #GFileAttributeMatcher. */ /** - * g_file_info_set_is_hidden: - * @info: a #GFileInfo. - * @is_hidden: a #gboolean. + * g_file_attribute_matcher_unref: + * @matcher: a #GFileAttributeMatcher. * - * Sets the "is_hidden" attribute in a #GFileInfo according to @is_symlink. - * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. + * Unreferences @matcher. If the reference count falls below 1, + * the @matcher is automatically freed. */ /** - * g_main_new: - * @is_running: set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_run() will set this to %TRUE anyway. + * g_file_copy: + * @source: input #GFile. + * @destination: destination #GFile + * @flags: set of #GFileCopyFlags + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @progress_callback: (scope call): function to callback with progress information + * @progress_callback_data: (closure): user data to pass to @progress_callback + * @error: #GError to set on error, or %NULL * - * Creates a new #GMainLoop for th default main context. + * Copies the file @source to the location specified by @destination. + * Can not handle recursive copies of directories. + * If the flag #G_FILE_COPY_OVERWRITE is specified an already + * existing @destination file is overwritten. + * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks + * will be copied as symlinks, otherwise the target of the + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If @progress_callback is not %NULL, then the operation can be monitored by + * setting this to a #GFileProgressCallback function. @progress_callback_data + * will be passed to this function. It is guaranteed that this callback will + * be called after all data has been transferred with the total number of bytes + * copied during the operation. + * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND + * error is returned, independent on the status of the @destination. + * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the + * error G_IO_ERROR_EXISTS is returned. + * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY + * error is returned. If trying to overwrite a directory with a directory the + * G_IO_ERROR_WOULD_MERGE error is returned. + * If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is + * specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error + * is returned. + * If you are interested in copying the #GFile object itself (not the on-disk + * file), see g_file_dup(). * - * Returns: a new #GMainLoop - * Deprecated: 2.2: Use g_main_loop_new() instead + * Returns: %TRUE on success, %FALSE otherwise. */ /** - * G_VARIANT_TYPE_VARIANT: + * g_file_copy_async: (skip) + * @source: input #GFile. + * @destination: destination #GFile + * @flags: set of #GFileCopyFlags + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @progress_callback: function to callback with progress information + * @progress_callback_data: user data to pass to @progress_callback + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function * - * The type of a box that contains any other value (including another - * variant). + * Copies the file @source to the location specified by @destination + * asynchronously. For details of the behaviour, see g_file_copy(). + * If @progress_callback is not %NULL, then that function that will be called + * just like in g_file_copy(), however the callback will run in the main loop, + * not in the thread that is doing the I/O operation. + * When the operation is finished, @callback will be called. You can then call + * g_file_copy_finish() to get the result of the operation. */ /** - * GUnixSocketAddress:abstract: + * g_file_copy_attributes: + * @source: a #GFile with attributes. + * @destination: a #GFile to copy attributes to. + * @flags: a set of #GFileCopyFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * Whether or not this is an abstract address - * distinguishes between zero-padded and non-zero-padded - * abstract addresses. + * Copies the file attributes from @source to @destination. + * Normally only a subset of the file attributes are copied, + * those that are copies in a normal file copy operation + * (which for instance does not include e.g. owner). However + * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then + * all the metadata that is possible to copy is copied. This + * is useful when implementing move by copy + delete source. * - * Deprecated: Use #GUnixSocketAddress:address-type, which + * Returns: %TRUE if the attributes were copied successfully, %FALSE otherwise. */ /** - * G_TIME_SPAN_DAY: + * g_file_copy_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Evaluates to a time span of one day. + * Finishes copying the file started with + * g_file_copy_async(). * - * Since: 2.26 + * Returns: a %TRUE on success, %FALSE on error. */ /** - * g_io_extension_get_type: - * @extension: a #GIOExtension + * g_file_create: + * @file: input #GFile. + * @flags: a set of #GFileCreateFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Gets the type associated with @extension. + * Creates a new file and returns an output stream for writing to it. + * The file must not already exist. + * By default files created are generally readable by everyone, + * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file + * will be made readable only to the current user, to the level that + * is supported on the target filesystem. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If a file or directory with this name already exists the G_IO_ERROR_EXISTS + * error will be returned. + * Some file systems don't allow all file names, and may + * return an G_IO_ERROR_INVALID_FILENAME error, and if the name + * is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned. + * Other errors are possible too, and depend on what kind of + * filesystem the file is on. + * %NULL on error. + * Free the returned object with g_object_unref(). * - * Returns: the type of @extension + * Returns: (transfer full): a #GFileOutputStream for the newly created file, or */ /** - * GFile: + * g_file_create_async: + * @file: input #GFile. + * @flags: a set of #GFileCreateFlags. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * A handle to an object implementing the #GFileIface interface. - * Generally stores a location within the file system. Handles do not - * necessarily represent files or directories that currently exist. + * Asynchronously creates a new file and returns an output stream for writing to it. + * The file must not already exist. + * For more details, see g_file_create() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_create_finish() to get the result of the operation. */ /** - * G_TYPE_CHECK_INSTANCE: - * @instance: Location of a #GTypeInstance structure. + * g_file_create_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Checks if @instance is a valid #GTypeInstance structure, - * otherwise issues a warning and returns %FALSE. - * This macro should only be used in type implementations. + * Finishes an asynchronous file create operation started with + * g_file_create_async(). + * Free the returned object with g_object_unref(). * - * Returns: %TRUE on success. + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. */ /** - * g_data_output_stream_put_int32: - * @stream: a #GDataOutputStream. - * @data: a #gint32. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_file_create_readwrite: + * @file: a #GFile + * @flags: a set of #GFileCreateFlags + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @error: return location for a #GError, or %NULL * - * Puts a signed 32-bit integer into the output stream. + * Creates a new file and returns a stream for reading and writing to it. + * The file must not already exist. + * By default files created are generally readable by everyone, + * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file + * will be made readable only to the current user, to the level that + * is supported on the target filesystem. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If a file or directory with this name already exists the %G_IO_ERROR_EXISTS + * error will be returned. Some file systems don't allow all file names, + * and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name + * is too long, %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors + * are possible too, and depend on what kind of filesystem the file is on. + * Note that in many non-local file cases read and write streams are not + * supported, so make sure you really need to do read and write streaming, + * rather than just opening for reading or writing. + * Free the returned object with g_object_unref(). * - * Returns: %TRUE if @data was successfully added to the @stream. + * Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error. + * Since: 2.22 */ /** - * GConverterInputStream: + * g_file_create_readwrite_async: + * @file: input #GFile + * @flags: a set of #GFileCreateFlags + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * An implementation of #GFilterInputStream that allows data - * conversion. + * Asynchronously creates a new file and returns a stream for reading and + * writing to it. The file must not already exist. + * For more details, see g_file_create_readwrite() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then + * call g_file_create_readwrite_finish() to get the result of the operation. + * + * Since: 2.22 */ /** - * GTestLogFatalFunc: - * @log_domain: the log domain of the message - * @log_level: the log level of the message (including the fatal and recursion flags) - * @message: the message to process - * @user_data: user data, set in g_test_log_set_fatal_handler() + * g_file_create_readwrite_finish: + * @file: input #GFile + * @res: a #GAsyncResult + * @error: a #GError, or %NULL * - * Specifies the prototype of fatal log handler functions. + * Finishes an asynchronous file create operation started with + * g_file_create_readwrite_async(). + * Free the returned object with g_object_unref(). * - * Returns: %TRUE if the program should abort, %FALSE otherwise + * Returns: (transfer full): a #GFileIOStream or %NULL on error. * Since: 2.22 */ /** - * g_buffered_input_stream_new_sized: - * @base_stream: a #GInputStream - * @size: a #gsize + * g_file_delete: + * @file: input #GFile. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Creates a new #GBufferedInputStream from the given @base_stream, - * with a buffer set to @size. + * Deletes a file. If the @file is a directory, it will only be deleted if it + * is empty. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GInputStream. + * Virtual: delete_file + * Returns: %TRUE if the file was deleted. %FALSE otherwise. */ /** - * g_socket_is_closed: - * @socket: a #GSocket + * g_file_descriptor_based_get_fd: + * @fd_based: a #GFileDescriptorBased. * - * Checks whether a socket is closed. + * Gets the underlying file descriptor. * - * Returns: %TRUE if socket is closed, %FALSE otherwise - * Since: 2.22 + * Returns: The file descriptor + * Since: 2.24 */ /** - * g_filter_output_stream_get_close_base_stream: - * @stream: a #GFilterOutputStream. + * g_file_dup: + * @file: input #GFile. * - * Returns whether the base stream will be closed when @stream is - * closed. + * Duplicates a #GFile handle. This operation does not duplicate + * the actual file or directory represented by the #GFile; see + * g_file_copy() if attempting to copy a file. + * This call does no blocking i/o. * - * Returns: %TRUE if the base stream will be closed. + * Returns: (transfer full): a new #GFile that is a duplicate of the given #GFile. */ /** - * GDBusMessageClass: + * g_file_eject_mountable: + * @file: input #GFile. + * @flags: flags affecting the operation + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. + * @user_data: (closure): the data to pass to callback function * - * Class structure for #GDBusMessage. + * Starts an asynchronous eject on a mountable. + * When this operation has completed, @callback will be called with + * g_file_eject_mountable_finish(). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Since: 2.26 + * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead. */ /** - * GSourceFuncs: - * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the - * @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here. - * @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source. - * @finalize: Called when the source is finalized. + * g_file_eject_mountable_finish: + * @file: input #GFile. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * The <structname>GSourceFuncs</structname> struct contains a table of - * functions used to handle event sources in a generic manner. - * For idle sources, the prepare and check functions always return %TRUE - * to indicate that the source is always ready to be processed. The prepare - * function also returns a timeout value of 0 to ensure that the poll() call - * doesn't block (since that would be time wasted which could have been spent - * running the idle function). - * For timeout sources, the prepare and check functions both return %TRUE - * if the timeout interval has expired. The prepare function also returns - * a timeout value to ensure that the poll() call doesn't block too long - * and miss the next timeout. - * For file descriptor sources, the prepare function typically returns %FALSE, - * since it must wait until poll() has been called before it knows whether - * any events need to be processed. It sets the returned timeout to -1 to - * indicate that it doesn't mind how long the poll() call blocks. In the - * check function, it tests the results of the poll() call to see if the - * required condition has been met, and returns %TRUE if so. + * Finishes an asynchronous eject operation started by + * g_file_eject_mountable(). + * otherwise. + * + * Returns: %TRUE if the @file was ejected successfully. %FALSE + * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead. */ /** - * g_dbus_auth_observer_new: + * g_file_eject_mountable_with_operation: + * @file: input #GFile. + * @flags: flags affecting the operation + * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. + * @user_data: (closure): the data to pass to callback function * - * Creates a new #GDBusAuthObserver object. + * Starts an asynchronous eject on a mountable. + * When this operation has completed, @callback will be called with + * g_file_eject_mountable_with_operation_finish(). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: A #GDBusAuthObserver. Free with g_object_unref(). - * Since: 2.26 + * Since: 2.22 */ /** - * g_file_info_copy_into: - * @src_info: source to copy attributes from. - * @dest_info: destination to copy attributes to. + * g_file_eject_mountable_with_operation_finish: + * @file: input #GFile. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Copies all of the #GFileAttribute<!-- -->s from @src_info to @dest_info. - */ - - -/** - * GFileAttributeMatcher: + * Finishes an asynchronous eject operation started by + * g_file_eject_mountable_with_operation(). + * otherwise. * - * Determines if a string matches a file attribute. + * Returns: %TRUE if the @file was ejected successfully. %FALSE + * Since: 2.22 */ /** - * G_IO_ERROR: + * g_file_enumerate_children: + * @file: input #GFile. + * @attributes: an attribute query string. + * @flags: a set of #GFileQueryInfoFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting. * - * Error domain for GIO. Errors in this domain will be from the #GIOErrorEnum enumeration. - * See #GError for more information on error domains. + * Gets the requested information about the files in a directory. The result + * is a #GFileEnumerator object that will give out #GFileInfo objects for + * all the files in the directory. + * The @attributes value is a string that specifies the file attributes that + * should be gathered. It is not an error if it's not possible to read a particular + * requested attribute from a file - it just won't be set. @attributes should + * be a comma-separated list of attributes or attribute wildcards. The wildcard "*" + * means all attributes, and a wildcard like "standard::*" means all attributes in the standard + * namespace. An example attribute query be "standard::*,owner::user". + * The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. + * If the file is not a directory, the G_FILE_ERROR_NOTDIR error will be returned. + * Other errors are possible too. + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error. */ /** - * GVolumeMonitor::drive-connected: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: a #GDrive that was connected. + * g_file_enumerate_children_async: + * @file: input #GFile. + * @attributes: an attribute query string. + * @flags: a set of #GFileQueryInfoFlags. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Emitted when a drive is connected to the system. + * Asynchronously gets the requested information about the files in a directory. The result + * is a #GFileEnumerator object that will give out #GFileInfo objects for + * all the files in the directory. + * For more details, see g_file_enumerate_children() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_enumerate_children_finish() to get the result of the operation. */ /** - * g_settings_bind_with_mapping: (skip) - * @settings: a #GSettings object - * @key: the key to bind - * @object: (type GObject.Object): a #GObject - * @property: the name of the property to bind - * @flags: flags for the binding - * @get_mapping: a function that gets called to convert values from @settings to @object, or %NULL to use the default GIO mapping - * @set_mapping: a function that gets called to convert values from @object to @settings, or %NULL to use the default GIO mapping - * @user_data: data that gets passed to @get_mapping and @set_mapping - * @destroy: #GDestroyNotify function for @user_data + * g_file_enumerate_children_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError. * - * Create a binding between the @key in the @settings object - * and the property @property of @object. - * The binding uses the provided mapping functions to map between - * settings and property values. - * Note that the lifecycle of the binding is tied to the object, - * and that you can have only one binding per object property. - * If you bind the same property twice on the same object, the second - * binding overrides the first one. + * Finishes an async enumerate children operation. + * See g_file_enumerate_children_async(). + * Free the returned object with g_object_unref(). * - * Since: 2.26 + * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred. */ /** - * g_socket_client_get_socket_type: - * @client: a #GSocketClient. + * g_file_enumerator_close: + * @enumerator: a #GFileEnumerator. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occuring, or %NULL to ignore * - * Gets the socket type of the socket client. - * See g_socket_client_set_socket_type() for details. + * Releases all resources used by this enumerator, making the + * enumerator return %G_IO_ERROR_CLOSED on all calls. + * This will be automatically called when the last reference + * is dropped, but you might want to call this function to make + * sure resources are released as early as possible. * - * Returns: a #GSocketFamily - * Since: 2.22 + * Returns: #TRUE on success or #FALSE on error. */ /** - * SECTION:gfil: - * @short_description: File and Directory Handling - * @include: gio/gio.h - * @see_also: #GFileInfo, #GFileEnumerator - * - * #GFile is a high level abstraction for manipulating files on a - * virtual file system. #GFile<!-- -->s are lightweight, immutable - * objects that do no I/O upon creation. It is necessary to understand that - * #GFile objects do not represent files, merely an identifier for a file. All - * file content I/O is implemented as streaming operations (see #GInputStream and - * #GOutputStream). - * g_file_new_for_path() if you have a path. - * g_file_new_for_uri() if you have a URI. - * g_file_new_for_commandline_arg() for a command line argument. - * g_file_parse_name() from a utf8 string gotten from g_file_get_parse_name(). - * One way to think of a #GFile is as an abstraction of a pathname. For normal - * files the system pathname is what is stored internally, but as #GFile<!-- -->s - * are extensible it could also be something else that corresponds to a pathname - * in a userspace implementation of a filesystem. - * #GFile<!-- -->s make up hierarchies of directories and files that correspond to the - * files on a filesystem. You can move through the file system with #GFile using - * g_file_get_parent() to get an identifier for the parent directory, g_file_get_child() - * to get a child within a directory, g_file_resolve_relative_path() to resolve a relative - * path between two #GFile<!-- -->s. There can be multiple hierarchies, so you may not - * end up at the same root if you repeatedly call g_file_get_parent() on two different - * files. - * All #GFile<!-- -->s have a basename (get with g_file_get_basename()). These names - * are byte strings that are used to identify the file on the filesystem (relative to - * its parent directory) and there is no guarantees that they have any particular charset - * encoding or even make any sense at all. If you want to use filenames in a user - * interface you should use the display name that you can get by requesting the - * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). - * This is guaranteed to be in utf8 and can be used in a user interface. But always - * store the real basename or the #GFile to use to actually access the file, because - * there is no way to go from a display name to the actual name. - * Using #GFile as an identifier has the same weaknesses as using a path in that - * there may be multiple aliases for the same file. For instance, hard or - * soft links may cause two different #GFile<!-- -->s to refer to the same file. - * and long names on Fat/NTFS, or bind mounts in Linux. If you want to check if - * two #GFile<!-- -->s point to the same file you can query for the - * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial - * canonicalization of pathnames passed in, so that trivial differences in the - * path string used at creation (duplicated slashes, slash at end of path, "." - * or ".." path segments, etc) does not create different #GFile<!-- -->s. - * Many #GFile operations have both synchronous and asynchronous versions - * to suit your application. Asynchronous versions of synchronous functions - * simply have _async() appended to their function names. The asynchronous - * I/O functions call a #GAsyncReadyCallback which is then used to finalize - * the operation, producing a GAsyncResult which is then passed to the - * function's matching _finish() operation. - * Some #GFile operations do not have synchronous analogs, as they may - * take a very long time to finish, and blocking may leave an application - * unusable. Notable cases include: - * g_file_mount_mountable() to mount a mountable file. - * g_file_unmount_mountable_with_operation() to unmount a mountable file. - * g_file_eject_mountable_with_operation() to eject a mountable file. - * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm> - * One notable feature of #GFile<!-- -->s are entity tags, or "etags" for - * short. Entity tags are somewhat like a more abstract version of the - * traditional mtime, and can be used to quickly determine if the file has - * been modified from the version on the file system. See the HTTP 1.1 - * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink> - * for HTTP Etag headers, which are a very similar concept. - * </para> + * g_file_enumerator_close_async: + * @enumerator: a #GFileEnumerator. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * To construct a #gfile, you can use: - * Other possible causes for aliases are: case insensitive filesystems, short + * Asynchronously closes the file enumerator. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in + * g_file_enumerator_close_finish(). */ /** - * GBufferedOutputStream: + * g_file_enumerator_close_finish: + * @enumerator: a #GFileEnumerator. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * An implementation of #GFilterOutputStream with a sized buffer. + * Finishes closing a file enumerator, started from g_file_enumerator_close_async(). + * If the file enumerator was already closed when g_file_enumerator_close_async() + * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and + * return %FALSE. If the file enumerator had pending operation when the close + * operation was started, then this function will report %G_IO_ERROR_PENDING, and + * return %FALSE. If @cancellable was not %NULL, then the operation may have been + * cancelled by triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be + * returned. + * + * Returns: %TRUE if the close operation has finished successfully. */ /** - * G_FILE_ATTRIBUTE_STANDARD_COPY_NAME: + * g_file_enumerator_get_container: + * @enumerator: a #GFileEnumerator * - * A key in the "standard" namespace for getting the copy name of the file. - * The copy name is an optional version of the name. If available it's always - * in UTF8, and corresponds directly to the original filename (only transcoded to - * UTF8). This is useful if you want to copy the file to another filesystem that - * might have a different encoding. If the filename is not a valid string in the - * encoding selected for the filesystem it is in then the copy name will not be set. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * Get the #GFile container which is being enumerated. + * + * Returns: (transfer full): the #GFile which is being enumerated. + * Since: 2.18 */ /** - * g_desktop_app_info_get_filename: - * @info: a #GDesktopAppInfo + * g_file_enumerator_has_pending: + * @enumerator: a #GFileEnumerator. * - * When @info was created from a known filename, return it. In some - * situations such as the #GDesktopAppInfo returned from - * g_desktop_app_info_new_from_keyfile(), this function will return %NULL. + * Checks if the file enumerator has pending operations. * - * Returns: The full path to the file for @info, or %NULL if not known. - * Since: 2.24 + * Returns: %TRUE if the @enumerator has pending operations. */ /** - * g_settings_backend_path_writable_changed: - * @backend: a #GSettingsBackend implementation - * @path: the name of the path + * g_file_enumerator_is_closed: + * @enumerator: a #GFileEnumerator. * - * Signals that the writability of all keys below a given path may have - * changed. - * Since GSettings performs no locking operations for itself, this call - * will always be made in response to external events. + * Checks if the file enumerator has been closed. * - * Since: 2.26 + * Returns: %TRUE if the @enumerator is closed. */ /** - * GActionGroup::action-removed: - * @action_group: the #GActionGroup that changed - * @action_name: the name of the action in @action_group + * g_file_enumerator_next_file: + * @enumerator: a #GFileEnumerator. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occuring, or %NULL to ignore * - * Signals that an action is just about to be removed from the group. - * This signal is emitted before the action is removed, so the action - * is still visible and can be queried from the signal handler. + * Returns information for the next file in the enumerated object. + * Will block until the information is available. The #GFileInfo + * returned from this function will contain attributes that match the + * attribute string that was passed when the #GFileEnumerator was created. + * On error, returns %NULL and sets @error to the error. If the + * enumerator is at the end, %NULL will be returned and @error will + * be unset. + * Free the returned object with g_object_unref() when no longer needed. * - * Since: 2.28 + * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator. */ /** - * GFileIcon: + * g_file_enumerator_next_files_async: + * @enumerator: a #GFileEnumerator. + * @num_files: the number of file info objects to request + * @io_priority: the <link linkend="gioscheduler">io priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Gets an icon for a #GFile. Implements #GLoadableIcon. + * Request information for a number of files from the enumerator asynchronously. + * When all i/o for the operation is finished the @callback will be called with + * the requested information. + * The callback can be called with less than @num_files files in case of error + * or at the end of the enumerator. In case of a partial error the callback will + * be called with any succeeding items and no error, and on the next request the + * error will be reported. If a request is cancelled the callback will be called + * with %G_IO_ERROR_CANCELLED. + * During an async request no other sync and async calls are allowed, and will + * result in %G_IO_ERROR_PENDING errors. + * Any outstanding i/o request with higher priority (lower numerical value) will + * be executed before an outstanding request with lower priority. Default + * priority is %G_PRIORITY_DEFAULT. */ /** - * g_socket_set_timeout: - * @socket: a #GSocket. - * @timeout: the timeout for @socket, in seconds, or 0 for none + * g_file_enumerator_next_files_finish: + * @enumerator: a #GFileEnumerator. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Sets the time in seconds after which I/O operations on @socket will - * time out if they have not yet completed. - * On a blocking socket, this means that any blocking #GSocket - * operation will time out after @timeout seconds of inactivity, - * returning %G_IO_ERROR_TIMED_OUT. - * On a non-blocking socket, calls to g_socket_condition_wait() will - * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources - * created with g_socket_create_source() will trigger after - * set, at which point calling g_socket_receive(), g_socket_send(), - * g_socket_check_connect_result(), etc, will fail with - * %G_IO_ERROR_TIMED_OUT. - * If @timeout is 0 (the default), operations will never time out - * on their own. - * Note that if an I/O operation is interrupted by a signal, this may - * cause the timeout to be reset. + * Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). + * g_list_free() and unref the infos with g_object_unref() when you're + * done with them. * - * Since: 2.26 + * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with */ /** - * g_app_info_set_as_default_for_extension: - * @appinfo: a #GAppInfo. - * @extension: a string containing the file extension (without the dot). - * @error: a #GError. - * - * Sets the application as the default handler for the given file extension. + * g_file_enumerator_set_pending: + * @enumerator: a #GFileEnumerator. + * @pending: a boolean value. * - * Returns: %TRUE on success, %FALSE on error. + * Sets the file enumerator as having pending operations. */ /** - * G_CLOSURE_NEEDS_MARSHAL: - * @closure: a #GClosure + * g_file_equal: + * @file1: the first #GFile. + * @file2: the second #GFile. * - * Check if the closure still needs a marshaller. See g_closure_set_marshal(). + * Checks equality of two given #GFile<!-- -->s. Note that two + * #GFile<!-- -->s that differ can still refer to the same + * file on the filesystem due to various forms of filename + * aliasing. + * This call does no blocking i/o. + * %FALSE if either is not a #GFile. * - * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on + * Returns: %TRUE if @file1 and @file2 are equal. */ /** - * g_unix_connection_send_fd: - * @connection: a #GUnixConnection - * @fd: a file descriptor + * g_file_find_enclosing_mount: + * @file: input #GFile. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: (allow-none): #GError for error reporting, or %NULL to ignore. + * @error: a #GError. * - * Passes a file descriptor to the recieving side of the - * connection. The recieving end has to call g_unix_connection_receive_fd() - * to accept the file descriptor. - * As well as sending the fd this also writes a single byte to the - * stream, as this is required for fd passing to work on some - * implementations. + * Gets a #GMount for the #GFile. + * If the #GFileIface for @file does not have a mount (e.g. possibly a + * remote share), @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL + * will be returned. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Free the returned object with g_object_unref(). * - * Returns: a %TRUE on success, %NULL on error. - * Since: 2.22 + * Returns: (transfer full): a #GMount where the @file is located or %NULL on error. */ /** - * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE: - * - * A key in the "trash" namespace. When requested against - * items in "trash:///", will return the date and time when the file - * was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * g_file_find_enclosing_mount_async: + * @file: a #GFile + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Since: 2.24. + * Asynchronously gets the mount for the file. + * For more details, see g_file_find_enclosing_mount() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_find_enclosing_mount_finish() to get the result of the operation. */ /** - * GProxy: + * g_file_find_enclosing_mount_finish: + * @file: a #GFile + * @res: a #GAsyncResult + * @error: a #GError * - * Interface that handles proxy connection and payload. + * Finishes an asynchronous find mount request. + * See g_file_find_enclosing_mount_async(). + * Free the returned object with g_object_unref(). * - * Since: 2.26 + * Returns: (transfer full): #GMount for given @file or %NULL on error. */ /** - * g_content_type_is_unknown: - * @type: a content type string + * g_file_get_basename: + * @file: input #GFile. * - * Checks if the content type is the generic "unknown" type. - * On UNIX this is the "application/octet-stream" mimetype, - * while on win32 it is "*". + * Gets the base name (the last component of the path) for a given #GFile. + * If called for the top level of a system (such as the filesystem root + * or a uri like sftp://host/) it will return a single directory separator + * (and on Windows, possibly a drive letter). + * The base name is a byte string (*not* UTF-8). It has no defined encoding + * or rules other than it may not contain zero bytes. If you want to use + * filenames in a user interface you should use the display name that you + * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME + * attribute with g_file_query_info(). + * This call does no blocking i/o. + * if given #GFile is invalid. The returned string should be + * freed with g_free() when no longer needed. * - * Returns: %TRUE if the type is the unknown type. + * Returns: string containing the #GFile's base name, or %NULL */ /** - * GMountMountFlags: - * @G_MOUNT_MOUNT_NONE: No flags set. + * g_file_get_child: + * @file: input #GFile. + * @name: string containing the child's basename. * - * Flags used when mounting a mount. + * Gets a child of @file with basename equal to @name. + * Note that the file with that specific name might not exist, but + * you can still have a #GFile that points to it. You can use this + * for instance to create that file. + * This call does no blocking i/o. + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): a #GFile to a child specified by @name. */ /** - * GZlibCompressor:file-info: + * g_file_get_child_for_display_name: + * @file: input #GFile. + * @display_name: string to a possible child. + * @error: #GError. * - * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is - * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name - * and modification time from the file info to the the GZIP header. + * Gets the child of @file for a given @display_name (i.e. a UTF8 + * version of the name). If this function fails, it returns %NULL and @error will be + * set. This is very useful when constructing a GFile for a new file + * and the user entered the filename in the user interface, for instance + * when you select a directory and type a filename in the file selector. + * This call does no blocking i/o. + * %NULL if the display name couldn't be converted. + * Free the returned object with g_object_unref(). * - * Since: 2.26 + * Returns: (transfer full): a #GFile to the specified child, or */ /** - * g_async_result_get_source_object: - * @res: a #GAsyncResult + * g_file_get_parent: + * @file: input #GFile. * - * Gets the source object from a #GAsyncResult. - * or %NULL if there is none. + * Gets the parent directory for the @file. + * If the @file represents the root directory of the + * file system, then %NULL will be returned. + * This call does no blocking i/o. + * #GFile or %NULL if there is no parent. + * Free the returned object with g_object_unref(). * - * Returns: (transfer full): a new reference to the source object for the @res, + * Returns: (transfer full): a #GFile structure to the parent of the given */ /** - * g_file_replace_async: + * g_file_get_parse_name: * @file: input #GFile. - * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore. - * @make_backup: %TRUE if a backup should be created. - * @flags: a set of #GFileCreateFlags. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function * - * Asynchronously overwrites the file, replacing the contents, possibly - * creating a backup copy of the file first. - * For more details, see g_file_replace() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_replace_finish() to get the result of the operation. + * Gets the parse name of the @file. + * A parse name is a UTF-8 string that describes the + * file such that one can get the #GFile back using + * g_file_parse_name(). + * This is generally used to show the #GFile as a nice + * full-pathname kind of string in a user interface, + * like in a location entry. + * For local files with names that can safely be converted + * to UTF8 the pathname is used, otherwise the IRI is used + * (a form of URI that allows UTF8 characters unescaped). + * This call does no blocking i/o. + * string should be freed with g_free() when no longer needed. + * + * Returns: a string containing the #GFile's parse name. The returned */ /** - * g_file_set_display_name_finish: + * g_file_get_path: * @file: input #GFile. - * @res: a #GAsyncResult. - * @error: a #GError, or %NULL * - * Finishes setting a display name started with - * g_file_set_display_name_async(). - * Free the returned object with g_object_unref(). + * Gets the local pathname for #GFile, if one exists. + * This call does no blocking i/o. + * no such path exists. The returned string should be + * freed with g_free() when no longer needed. * - * Returns: (transfer full): a #GFile or %NULL on error. + * Returns: string containing the #GFile's path, or %NULL if */ /** - * GBusNameLostCallback: - * @connection: The #GDBusConnection on which to acquire the name or %NULL if the connection was disconnected. - * @name: The name being owned. - * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection(). + * g_file_get_relative_path: + * @parent: input #GFile. + * @descendant: input #GFile. * - * Invoked when the name is lost or @connection has been closed. + * Gets the path for @descendant relative to @parent. + * This call does no blocking i/o. + * to @parent, or %NULL if @descendant doesn't have @parent as prefix. + * The returned string should be freed with g_free() when no longer needed. * - * Since: 2.26 + * Returns: string with the relative path from @descendant */ /** - * g_unix_mount_point_get_mount_path: - * @mount_point: a #GUnixMountPoint. + * g_file_get_uri: + * @file: input #GFile. * - * Gets the mount path for a unix mount point. + * Gets the URI for the @file. + * This call does no blocking i/o. + * The returned string should be freed with g_free() when no longer needed. * - * Returns: a string containing the mount path. + * Returns: a string containing the #GFile's URI. */ /** - * g_mount_get_uuid: - * @mount: a #GMount. + * g_file_get_uri_scheme: + * @file: input #GFile. * - * Gets the UUID for the @mount. The reference is typically based on - * the file system UUID for the mount in question and should be - * considered an opaque string. Returns %NULL if there is no UUID - * available. - * The returned string should be freed with g_free() + * Gets the URI scheme for a #GFile. + * RFC 3986 decodes the scheme as: + * <programlisting> + * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] + * </programlisting> + * Common schemes include "file", "http", "ftp", etc. + * This call does no blocking i/o. + * #GFile. The returned string should be freed with g_free() * when no longer needed. * - * Returns: the UUID for @mount or %NULL if no UUID can be computed. - */ - - -/** - * g_settings_revert: - * @settings: a #GSettings instance - * - * Reverts all non-applied changes to the settings. This function - * does nothing unless @settings is in 'delay-apply' mode; see - * g_settings_delay(). In the normal case settings are always applied - * immediately. - * Change notifications will be emitted for affected keys. + * Returns: a string containing the URI scheme for the given */ /** - * GBusNameOwnerFlags: - * @G_BUS_NAME_OWNER_FLAGS_NONE: No flags set. - * @G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT: Allow another message bus connection to claim the the name. - * @G_BUS_NAME_OWNER_FLAGS_REPLACE: If another message bus connection owns the name and have specified #G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection. + * g_file_has_parent: + * @file: input #GFile + * @parent: the parent to check for, or %NULL * - * Flags used in g_bus_own_name(). + * Checks if @file has a parent, and optionally, if it is @parent. + * If @parent is %NULL then this function returns %TRUE if @file has any + * parent at all. If @parent is non-%NULL then %TRUE is only returned + * if @file is a child of @parent. + * case that @parent is %NULL). * - * Since: 2.26 + * Returns: %TRUE if @file is a child of @parent (or any parent in the + * Since: 2.24 */ /** - * G_IS_PARAM_SPEC_ULONG: - * @pspec: a valid #GParamSpec instance + * g_file_has_prefix: + * @file: input #GFile. + * @prefix: input #GFile. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. + * Checks whether @file has the prefix specified by @prefix. In other word, + * if the names of inital elements of @file<!-- -->s pathname match @prefix. + * Only full pathname elements are matched, so a path like /foo is not + * considered a prefix of /foobar, only of /foo/bar. + * This call does no i/o, as it works purely on names. As such it can + * sometimes return %FALSE even if @file is inside a @prefix (from a + * filesystem point of view), because the prefix of @file is an alias + * of @prefix. + * %FALSE otherwise. * - * Returns: %TRUE on success. + * Virtual: prefix_matches + * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix. */ /** - * g_file_resolve_relative_path: + * g_file_has_uri_scheme: * @file: input #GFile. - * @relative_path: a given relative path string. + * @uri_scheme: a string containing a URI scheme. * - * Resolves a relative path for @file to an absolute path. + * Checks to see if a #GFile has a given URI scheme. * This call does no blocking i/o. - * is %NULL or if @file is invalid. - * Free the returned object with g_object_unref(). + * given URI scheme, %FALSE if URI scheme is %NULL, + * not supported, or #GFile is invalid. * - * Returns: (transfer full): #GFile to the resolved path. %NULL if @relative_path + * Returns: %TRUE if #GFile's backend supports the */ /** - * g_application_get_flags: - * @application: a #GApplication - * @returns: the flags for @application + * g_file_hash: + * @file: #gconstpointer to a #GFile. * - * Gets the flags for @application. - * See #GApplicationFlags. + * Creates a hash value for a #GFile. + * This call does no blocking i/o. + * integer that can be used as hash value for the #GFile. + * This function is intended for easily hashing a #GFile to + * add to a #GHashTable or similar data structure. * - * Since: 2.28 + * Virtual: hash + * Returns: 0 if @file is not a valid #GFile, otherwise an */ /** - * G_VARIANT_TYPE_ANY: + * g_file_icon_get_file: + * @icon: a #GIcon. * - * An indefinite type that is a supertype of every type (including - * itself). + * Gets the #GFile associated with the given @icon. + * + * Returns: (transfer none): a #GFile, or %NULL. */ /** - * GPollableSourceFunc: - * @pollable_stream: the #GPollableInputStream or #GPollableOutputStream - * @user_data: data passed in by the user. + * g_file_icon_new: + * @file: a #GFile. * - * This is the function type of the callback used for the #GSource - * returned by g_pollable_input_stream_create_source() and - * g_pollable_output_stream_create_source(). + * Creates a new icon for a file. * - * Returns: it should return %FALSE if the source should be removed. - * Since: 2.28 + * Returns: (transfer full): a #GIcon for the given @file, or %NULL on error. */ /** - * g_file_info_set_display_name: + * g_file_info_clear_status: * @info: a #GFileInfo. - * @display_name: a string containing a display name. * - * Sets the display name for the current #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. + * Clears the status information from @info. */ /** - * SECTION:gloadableico: - * @short_description: Loadable Icons - * @include: gio/gio.h - * @see_also: #GIcon, #GThemedIcon + * g_file_info_copy_into: + * @src_info: source to copy attributes from. + * @dest_info: destination to copy attributes to. * - * Extends the #GIcon interface and adds the ability to - * load icons from streams. + * Copies all of the #GFileAttribute<!-- -->s from @src_info to @dest_info. */ /** - * GDateTime: + * g_file_info_dup: + * @other: a #GFileInfo. * - * <structname>GDateTime</structname> is an opaque structure whose members - * cannot be accessed directly. + * Duplicates a file info structure. * - * Since: 2.26 + * Returns: (transfer full): a duplicate #GFileInfo of @other. */ /** - * g_file_replace: - * @file: input #GFile. - * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore. - * @make_backup: %TRUE if a backup should be created. - * @flags: a set of #GFileCreateFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * g_file_info_get_attribute_as_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Returns an output stream for overwriting the file, possibly - * creating a backup copy of the file first. If the file doesn't exist, - * it will be created. - * This will try to replace the file in the safest way possible so - * that any errors during the writing will not affect an already - * existing copy of the file. For instance, for local files it - * may write to a temporary file and then atomically rename over - * the destination when the stream is closed. - * By default files created are generally readable by everyone, - * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file - * will be made readable only to the current user, to the level that - * is supported on the target filesystem. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If you pass in a non-#NULL @etag value, then this value is - * compared to the current entity tag of the file, and if they differ - * an G_IO_ERROR_WRONG_ETAG error is returned. This generally means - * 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 a G_IO_ERROR_CANT_CREATE_BACKUP - * error will be returned. If you want to replace anyway, try again with - * If the file is a directory the G_IO_ERROR_IS_DIRECTORY error will be returned, - * and if the file is some other form of non-regular file then a - * G_IO_ERROR_NOT_REGULAR_FILE error will be returned. - * Some file systems don't allow all file names, and may - * return an G_IO_ERROR_INVALID_FILENAME error, and if the name - * is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned. - * Other errors are possible too, and depend on what kind of - * filesystem the file is on. - * Free the returned object with g_object_unref(). + * Gets the value of a attribute, formated as a string. + * This escapes things as needed to make the string valid + * utf8. + * When you're done with the string it must be freed with g_free(). * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Returns: a UTF-8 string associated with the given @attribute. */ /** - * G_FILE_ATTRIBUTE_OWNER_USER: + * g_file_info_get_attribute_boolean: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * A key in the "owner" namespace for getting the user name of the - * file's owner. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. + * Gets the value of a boolean attribute. If the attribute does not + * contain a boolean value, %FALSE will be returned. + * + * Returns: the boolean value contained within the attribute. */ /** - * g_dbus_message_copy: - * @message: A #GDBusMessage. - * @error: Return location for error or %NULL. + * g_file_info_get_attribute_byte_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Copies @message. The copy is a deep copy and the returned - * #GDBusMessage is completely identical except that it is guaranteed - * to not be locked. - * This operation can fail if e.g. @message contains file descriptors - * and the per-process or system-wide open files limit is reached. - * g_object_unref(). + * Gets the value of a byte string attribute. If the attribute does + * not contain a byte string, %NULL will be returned. + * %NULL otherwise. * - * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. Free with - * Since: 2.26 + * Returns: the contents of the @attribute value as a byte string, or */ /** - * g_alloca: - * @size: number of bytes to allocate. + * g_file_info_get_attribute_data: + * @info: a #GFileInfo + * @attribute: a file attribute key + * @type: (out) (allow-none): return location for the attribute type, or %NULL + * @value_pp: (out) (allow-none): return location for the attribute value, or %NULL + * @status: (out) (allow-none): return location for the attribute status, or %NULL * - * Allocates @size bytes on the stack; these bytes will be freed when the current - * stack frame is cleaned up. This macro essentially just wraps the alloca() - * function present on most UNIX variants. - * Thus it provides the same advantages and pitfalls as alloca(): - * <variablelist> - * <varlistentry><term></term><listitem><para> - * + alloca() is very fast, as on most systems it's implemented by just adjusting - * the stack pointer register. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * + It doesn't cause any memory fragmentation, within its scope, separate alloca() - * blocks just build up and are released together at function end. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * - Allocation sizes have to fit into the current stack frame. For instance in a - * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, - * so be sparse with alloca() uses. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * - Allocation failure due to insufficient stack space is not indicated with a %NULL - * return like e.g. with malloc(). Instead, most systems probably handle it the same - * way as out of stack space situations from infinite function recursion, i.e. - * with a segmentation fault. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays. - * Stack space allocated with alloca() in the same scope as a variable sized array - * will be freed together with the variable sized array upon exit of that scope, and - * not upon exit of the enclosing function scope. - * </para></listitem></varlistentry> - * </variablelist> + * Gets the attribute type, value and status for an attribute key. + * %FALSE otherwise. * - * Returns: space for @size bytes, allocated on the stack + * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, */ /** - * G_DEFINE_TYPE_WITH_CODE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * @_C_: Custom code that gets inserted in the *_get_type() function. + * g_file_info_get_attribute_int32: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * A convenience macro for type implementations. - * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the - * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). - * See G_DEFINE_TYPE_EXTENDED() for an example. + * Gets a signed 32-bit integer contained within the attribute. If the + * attribute does not contain a signed 32-bit integer, or is invalid, + * 0 will be returned. * - * Since: 2.4 + * Returns: a signed 32-bit integer from the attribute. */ /** - * G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET: + * g_file_info_get_attribute_int64: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * A key in the "standard" namespace for getting the symlink target, if the file - * is a symlink. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + * Gets a signed 64-bit integer contained within the attribute. If the + * attribute does not contain an signed 64-bit integer, or is invalid, + * 0 will be returned. + * + * Returns: a signed 64-bit integer from the attribute. */ /** - * g_dbus_connection_new_for_address_sync: - * @address: A D-Bus address. - * @flags: Flags describing how to make the connection. - * @observer: A #GDBusAuthObserver or %NULL. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * g_file_info_get_attribute_object: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Synchronously connects and sets up a D-Bus client connection for - * exchanging D-Bus messages with an endpoint specified by @address - * which must be in the D-Bus address format. - * This constructor can only be used to initiate client-side - * connections - use g_dbus_connection_new_sync() if you need to act - * as the server. In particular, @flags cannot contain the - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags. - * This is a synchronous failable constructor. See - * g_dbus_connection_new_for_address() for the asynchronous version. - * If @observer is not %NULL it may be used to control the - * authentication process. + * Gets the value of a #GObject attribute. If the attribute does + * not contain a #GObject, %NULL will be returned. + * %NULL otherwise. * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). - * Since: 2.26 + * Returns: (transfer none): a #GObject associated with the given @attribute, or */ /** - * g_resolver_free_addresses: (skip) - * @addresses: a #GList of #GInetAddress + * g_file_info_get_attribute_status: + * @info: a #GFileInfo + * @attribute: a file attribute key * - * Frees @addresses (which should be the return value from - * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()). - * (This is a convenience method; you can also simply free the results - * by hand.) + * Gets the attribute status for an attribute key. + * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. * - * Since: 2.22 + * Returns: a #GFileAttributeStatus for the given @attribute, or */ /** - * GMountOperation:anonymous: + * g_file_info_get_attribute_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Whether to use an anonymous user when authenticating. + * Gets the value of a string attribute. If the attribute does + * not contain a string, %NULL will be returned. + * %NULL otherwise. + * + * Returns: the contents of the @attribute value as a string, or */ /** - * g_socket_condition_check: - * @socket: a #GSocket - * @condition: a #GIOCondition mask to check + * g_file_info_get_attribute_stringv: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Checks on the readiness of @socket to perform operations. - * The operations specified in @condition are checked for and masked - * against the currently-satisfied conditions on @socket. The result - * is returned. - * Note that on Windows, it is possible for an operation to return - * %G_IO_ERROR_WOULD_BLOCK even immediately after - * g_socket_condition_check() has claimed that the socket is ready for - * writing. Rather than calling g_socket_condition_check() and then - * writing to the socket if it succeeds, it is generally better to - * simply try writing to the socket right away, and try again later if - * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK. - * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition; - * these conditions will always be set in the output if they are true. - * This call never blocks. + * Gets the value of a stringv attribute. If the attribute does + * not contain a stringv, %NULL will be returned. + * %NULL otherwise. Do not free. * - * Returns: the @GIOCondition mask of the current state + * Returns: (transfer none): the contents of the @attribute value as a stringv, or * Since: 2.22 */ /** - * g_bus_unown_name: - * @owner_id: An identifier obtained from g_bus_own_name() + * g_file_info_get_attribute_type: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Stops owning a name. + * Gets the attribute type for an attribute key. + * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. * - * Since: 2.26 + * Returns: a #GFileAttributeType for the given @attribute, or */ /** - * g_dbus_proxy_get_interface_info: - * @proxy: A #GDBusProxy + * g_file_info_get_attribute_uint32: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Returns the #GDBusInterfaceInfo, if any, specifying the minimal - * interface that @proxy conforms to. - * See the #GDBusProxy:g-interface-info property for more details. - * object, it is owned by @proxy. + * Gets an unsigned 32-bit integer contained within the attribute. If the + * attribute does not contain an unsigned 32-bit integer, or is invalid, + * 0 will be returned. * - * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned - * Since: 2.26 + * Returns: an unsigned 32-bit integer from the attribute. */ /** - * g_proxy_address_get_destination_hostnam: - * @proxy: a #GProxyAddress + * g_file_info_get_attribute_uint64: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Gets @proxy's destination hostname. + * Gets a unsigned 64-bit integer contained within the attribute. If the + * attribute does not contain an unsigned 64-bit integer, or is invalid, + * 0 will be returned. * - * Returns: the @proxy's destination hostname - * Since: 2.26 + * Returns: a unsigned 64-bit integer from the attribute. */ /** - * g_dbus_method_invocation_get_connection: - * @invocation: A #GDBusMethodInvocation. + * g_file_info_get_content_type: + * @info: a #GFileInfo. * - * Gets the #GDBusConnection the method was invoked on. + * Gets the file's content type. * - * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation. - * Since: 2.26 + * Returns: a string containing the file's content type. */ /** - * g_srv_target_get_hostname: - * @target: a #GSrvTarget + * g_file_info_get_display_name: + * @info: a #GFileInfo. * - * Gets @target's hostname (in ASCII form; if you are going to present - * this to the user, you should use g_hostname_is_ascii_encoded() to - * check if it contains encoded Unicode segments, and use - * g_hostname_to_unicode() to convert it if it does.) + * Gets a display name for a file. * - * Returns: @target's hostname - * Since: 2.22 + * Returns: a string containing the display name. */ /** - * g_io_extension_point_get_extensions: - * @extension_point: a #GIOExtensionPoint - * - * Gets a list of all extensions that implement this extension point. - * The list is sorted by priority, beginning with the highest priority. - * #GIOExtension<!-- -->s. The list is owned by GIO and should not be - * modified. + * g_file_info_get_edit_name: + * @info: a #GFileInfo. * - * Returns: (element-type GIOExtension) (transfer none): a #GList of - */ - - -/** - * GSettings:has-unapplied: + * Gets the edit name for a file. * - * If this property is %TRUE, the #GSettings object has outstanding - * changes that will be applied when g_settings_apply() is called. + * Returns: a string containing the edit name. */ /** - * g_dbus_proxy_set_interface_info: - * @proxy: A #GDBusProxy - * @info: Minimum interface this proxy conforms to or %NULL to unset. + * g_file_info_get_etag: + * @info: a #GFileInfo. * - * Ensure that interactions with @proxy conform to the given - * interface. For example, when completing a method call, if the type - * signature of the message isn't what's expected, the given #GError - * is set. Signals that have a type signature mismatch are simply - * dropped. - * See the #GDBusProxy:g-interface-info property for more details. + * Gets the <link linkend="gfile-etag">entity tag</link> for a given + * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. * - * Since: 2.26 + * Returns: a string containing the value of the "etag:value" attribute. */ /** - * g_node_append: - * @parent: the #GNode to place the new #GNode under - * @node: the #GNode to insert + * g_file_info_get_file_type: + * @info: a #GFileInfo. * - * Inserts a #GNode as the last child of the given parent. + * Gets a file's type (whether it is a regular file, symlink, etc). + * This is different from the file's content type, see g_file_info_get_content_type(). * - * Returns: the inserted #GNode + * Returns: a #GFileType for the given file. */ /** - * g_memory_input_stream_add_data: - * @stream: a #GMemoryInputStream - * @data: (array length=len) (element-type guint8): input data - * @len: length of the data, may be -1 if @data is a nul-terminated string - * @destroy: (allow-none): function that is called to free @data, or %NULL + * g_file_info_get_icon: + * @info: a #GFileInfo. * - * Appends @data to data that can be read from the input stream + * Gets the icon for a file. + * + * Returns: (transfer none): #GIcon for the given @info. */ /** - * g_content_type_get_description: - * @type: a content type string + * g_file_info_get_is_backup: + * @info: a #GFileInfo. * - * Gets the human readable description of the content type. - * returned string with g_free() + * Checks if a file is a backup file. * - * Returns: a short description of the content type @type. Free the + * Returns: %TRUE if file is a backup file, %FALSE otherwise. */ /** - * G_PARAM_SPEC_INT64: - * @pspec: a valid #GParamSpec instance + * g_file_info_get_is_hidden: + * @info: a #GFileInfo. * - * Cast a #GParamSpec instance into a #GParamSpecInt64. + * Checks if a file is hidden. + * + * Returns: %TRUE if the file is a hidden file, %FALSE otherwise. */ /** - * g_permission_release_finish: - * @permission: a #GPermission instance - * @result: the #GAsyncResult given to the #GAsyncReadyCallback - * @error: a pointer to a %NULL #GError, or %NULL - * @returns: %TRUE if the permission was successfully released + * g_file_info_get_is_symlink: + * @info: a #GFileInfo. * - * Collects the result of attempting to release the permission - * represented by @permission. - * This is the second half of the asynchronous version of - * g_permission_release(). + * Checks if a file is a symlink. * - * Since: 2.26 + * Returns: %TRUE if the given @info is a symlink. */ /** - * G_TYPE_RESERVED_BSE_LAST: + * g_file_info_get_modification_time: + * @info: a #GFileInfo. + * @result: a #GTimeVal. * - * Last fundamental type number reserved for BSE. + * Gets the modification time of the current @info and sets it + * in @result. */ /** - * g_dbus_message_get_num_unix_fds: - * @message: A #GDBusMessage. + * g_file_info_get_name: + * @info: a #GFileInfo. * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. + * Gets the name for a file. * - * Returns: The value. - * Since: 2.26 + * Returns: a string containing the file name. */ /** - * GDBusSubtreeFlags: - * @G_DBUS_SUBTREE_FLAGS_NONE: No flags set. - * @G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES: Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree. + * g_file_info_get_size: + * @info: a #GFileInfo. * - * Flags passed to g_dbus_connection_register_subtree(). + * Gets the file's size. * - * Since: 2.26 + * Returns: a #goffset containing the file's size. */ /** - * g_dbus_connection_unregister_object: - * @connection: A #GDBusConnection. - * @registration_id: A registration id obtained from g_dbus_connection_register_object(). + * g_file_info_get_sort_order: + * @info: a #GFileInfo. * - * Unregisters an object. + * Gets the value of the sort_order attribute from the #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. * - * Returns: %TRUE if the object was unregistered, %FALSE otherwise. - * Since: 2.26 + * Returns: a #gint32 containing the value of the "standard::sort_order" attribute. */ /** - * G_FILE_ATTRIBUTE_STANDARD_TARGET_URI: + * g_file_info_get_symlink_target: + * @info: a #GFileInfo. * - * A key in the "standard" namespace for getting the target URI for the file, in - * the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * Gets the symlink target for a given #GFileInfo. + * + * Returns: a string containing the symlink target. */ /** - * SECTION:gmemoryoutputstrea: - * @short_description: Streaming output operations on memory chunks - * @include: gio/gio.h - * @see_also: #GMemoryInputStream + * g_file_info_has_attribute: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * #GMemoryOutputStream is a class for using arbitrary - * memory chunks as output for GIO streaming output operations. + * Checks if a file info structure has an attribute named @attribute. + * %FALSE otherwise. + * + * Returns: %TRUE if @Ginfo has an attribute named @attribute, */ /** - * g_tls_client_connection_new: - * @base_io_stream: the #GIOStream to wrap - * @server_identity: (allow-none): the expected identity of the server - * @error: #GError for error reporting, or %NULL to ignore. + * g_file_info_has_namespace: + * @info: a #GFileInfo. + * @name_space: a file attribute namespace. * - * Creates a new #GTlsClientConnection wrapping @base_io_stream (which - * must have pollable input and output streams) which is assumed to - * communicate with the server identified by @server_identity. + * Checks if a file info structure has an attribute in the + * specified @name_space. + * %FALSE otherwise. * - * Returns: the new #GTlsClientConnection, or %NULL on error - * Since: 2.28 + * Returns: %TRUE if @Ginfo has an attribute in @name_space, + * Since: 2.22 */ /** - * g_network_address_get_scheme: - * @addr: a #GNetworkAddress + * g_file_info_list_attributes: + * @info: a #GFileInfo. + * @name_space: a file attribute key's namespace. * - * Gets @addr's scheme + * Lists the file info structure's attributes. + * possible attribute types for the given @name_space, or + * %NULL on error. * - * Returns: @addr's scheme (%NULL if not built from URI) - * Since: 2.26 + * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the */ /** - * G_FILE_ATTRIBUTE_TIME_ACCESS: + * g_file_info_new: * - * A key in the "time" namespace for getting the time the file was last - * accessed. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the - * file was last accessed. + * Creates a new file info structure. + * + * Returns: a #GFileInfo. */ /** - * g_unix_mount_guess_icon: - * @mount_entry: a #GUnixMountEntry - * - * Guesses the icon of a Unix mount. + * g_file_info_remove_attribute: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Returns: (transfer full): a #GIcon + * Removes all cases of @attribute from @info if it exists. */ /** - * GDrive::changed: - * @drive: a #GDrive. + * g_file_info_set_attribute: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @type: a #GFileAttributeType + * @value_p: pointer to the value * - * Emitted when the drive's state has changed. + * Sets the @attribute to contain the given value, if possible. */ /** - * g_file_info_unset_attribute_mask: - * @info: #GFileInfo. + * g_file_info_set_attribute_boolean: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a boolean value. * - * Unsets a mask set by g_file_info_set_attribute_mask(), if one - * is set. + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * GAction:parameter-type: - * - * The type of the parameter that must be given when activating the - * action. + * g_file_info_set_attribute_byte_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a byte string. * - * Since: 2.28 + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_file_monitor: - * @file: input #GFile - * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: a #GError, or %NULL - * - * Obtains a file or directory monitor for the given file, depending - * on the type of the file. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Free the returned object with g_object_unref(). + * g_file_info_set_attribute_int32: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a signed 32-bit integer * - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. - * Since: 2.18 + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * GTlsConnection:peer-certificate-errors: - * - * The errors noticed-and-ignored while verifying - * #GTlsConnection:peer-certificate. Normally this should be %0, but - * it may not be if #GTlsClientConnection::validation-flags is not - * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if - * #GTlsConnection::accept-certificate overrode the default - * behavior. + * g_file_info_set_attribute_int64: + * @info: a #GFileInfo. + * @attribute: attribute name to set. + * @attr_value: int64 value to set attribute to. * - * Since: 2.28 + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_credentials_set_unix_user: - * @credentials: A #GCredentials. - * @uid: The UNIX user identifier to set. - * @error: Return location for error or %NULL. - * - * Tries to set the UNIX user identifier on @credentials. This method - * is only available on UNIX platforms. - * This operation can fail if #GCredentials is not supported on the - * OS or if the native credentials type does not contain information - * about the UNIX user. + * g_file_info_set_attribute_mask: + * @info: a #GFileInfo. + * @mask: a #GFileAttributeMatcher. * - * Returns: %TRUE if @uid was set, %FALSE if error is set. - * Since: 2.26 + * Sets @mask on @info to match specific attribute types. */ /** - * GClosure: - * @in_marshal: Indicates whether the closure is currently being invoked with g_closure_invoke() - * @is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate() + * g_file_info_set_attribute_object: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a #GObject. * - * A #GClosure represents a callback supplied by the programmer. + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * SECTION:gsocketaddres: - * @short_description: Abstract base class representing endpoints for socket communication + * g_file_info_set_attribute_status: + * @info: a #GFileInfo + * @attribute: a file attribute key + * @status: a #GFileAttributeStatus * - * #GSocketAddress is the equivalent of <type>struct sockaddr</type> - * in the BSD sockets API. This is an abstract class; use - * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress - * for UNIX domain sockets. + * Sets the attribute status for an attribute key. This is only + * needed by external code that implement g_file_set_attributes_from_info() + * or similar functions. + * The attribute must exist in @info for this to work. Otherwise %FALSE + * is returned and @info is unchanged. + * + * Returns: %TRUE if the status was changed, %FALSE if the key was not set. + * Since: 2.22 */ /** - * G_TIME_SPAN_MINUTE: - * - * Evaluates to a time span of one minute. + * g_file_info_set_attribute_string: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a string. * - * Since: 2.26 + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * g_drive_can_start_degraded: - * @drive: a #GDrive. + * g_file_info_set_attribute_stringv: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a %NULL terminated string array * - * Checks if a drive can be started degraded. + * Sets the @attribute to contain the given @attr_value, + * if possible. * - * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise. - * Since: 2.22 + * Sinze: 2.22 */ /** - * g_content_type_can_be_executable: - * @type: a content type string - * - * Checks if a content type can be executable. Note that for instance - * things like text files can be executables (i.e. scripts and batch files). - * can be executable, %FALSE otherwise. + * g_file_info_set_attribute_uint32: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: an unsigned 32-bit integer. * - * Returns: %TRUE if the file type corresponds to a type that + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * GSimpleActionClass: - * @activate: the class closure for the activate signal - * - * + * g_file_info_set_attribute_uint64: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: an unsigned 64-bit integer. * - * Since: 2.26 + * Sets the @attribute to contain the given @attr_value, + * if possible. */ /** - * G_TYPE_INSTANCE_GET_INTERFACE: - * @instance: Location of the #GTypeInstance structure. - * @g_type: The #GType of the interface to be returned. - * @c_type: The C type of the interface structure. - * - * Get the interface structure for interface @g_type of a given @instance. - * This macro should only be used in type implementations. + * g_file_info_set_content_type: + * @info: a #GFileInfo. + * @content_type: a content type. See #GContentType. * - * Returns: a pointer to the interface structure + * Sets the content type attribute for a given #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. */ /** - * g_file_info_get_attribute_as_string: + * g_file_info_set_display_name: * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a attribute, formated as a string. - * This escapes things as needed to make the string valid - * utf8. - * When you're done with the string it must be freed with g_free(). + * @display_name: a string containing a display name. * - * Returns: a UTF-8 string associated with the given @attribute. + * Sets the display name for the current #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. */ /** - * GResolver::reload: - * @resolver: a #GResolver + * g_file_info_set_edit_name: + * @info: a #GFileInfo. + * @edit_name: a string containing an edit name. * - * Emitted when the resolver notices that the system resolver - * configuration has changed. + * Sets the edit name for the current file. + * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. */ /** - * g_settings_get_range: - * @settings: a #GSettings - * @key: the key to query the range of - * @returns: a #GVariant describing the range - * - * Queries the range of a key. - * This function will return a #GVariant that fully describes the range - * of values that are valid for @key. - * The type of #GVariant returned is <literal>(sv)</literal>. The - * string describes the type of range restriction in effect. The type - * and meaning of the value contained in the variant depends on the - * string. - * If the string is <literal>'type'</literal> then the variant contains - * an empty array. The element type of that empty array is the expected - * type of value and all values of that type are valid. - * If the string is <literal>'enum'</literal> then the variant contains - * an array enumerating the possible values. Each item in the array is - * a possible valid value and no other values are valid. - * If the string is <literal>'flags'</literal> then the variant contains - * an array. Each item in the array is a value that may appear zero or - * one times in an array to be used as the value for this key. For - * example, if the variant contained the array <literal>['x', - * 'y']</literal> then the valid values for the key would be - * <literal>[]</literal>, <literal>['x']</literal>, - * <literal>['y']</literal>, <literal>['x', 'y']</literal> and - * <literal>['y', 'x']</literal>. - * Finally, if the string is <literal>'range'</literal> then the variant - * contains a pair of like-typed values -- the minimum and maximum - * permissible values for this key. - * This information should not be used by normal programs. It is - * considered to be a hint for introspection purposes. Normal programs - * should already know what is permitted by their own schema. The - * format may change in any way in the future -- but particularly, new - * forms may be added to the possibilities described above. - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. - * You should free the returned value with g_variant_unref() when it is - * no longer needed. + * g_file_info_set_file_type: + * @info: a #GFileInfo. + * @type: a #GFileType. * - * Since: 2.28 + * Sets the file type in a #GFileInfo to @type. + * See %G_FILE_ATTRIBUTE_STANDARD_TYPE. */ /** - * g_socket_client_set_protocol: - * @client: a #GSocketClient. - * @protocol: a #GSocketProtocol - * - * Sets the protocol of the socket client. - * The sockets created by this object will use of the specified - * protocol. - * If @protocol is %0 that means to use the default - * protocol for the socket family and type. + * g_file_info_set_icon: + * @info: a #GFileInfo. + * @icon: a #GIcon. * - * Since: 2.22 + * Sets the icon for a given #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_ICON. */ /** - * G_TYPE_IO_CONDITION: + * g_file_info_set_is_hidden: + * @info: a #GFileInfo. + * @is_hidden: a #gboolean. * - * The #GType for #GIOCondition. + * Sets the "is_hidden" attribute in a #GFileInfo according to @is_symlink. + * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. */ /** - * g_mount_unmount: - * @mount: a #GMount. - * @flags: flags affecting the operation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. - * - * Unmounts a mount. This is an asynchronous operation, and is - * finished by calling g_mount_unmount_finish() with the @mount - * and #GAsyncResult data returned in the @callback. + * g_file_info_set_is_symlink: + * @info: a #GFileInfo. + * @is_symlink: a #gboolean. * - * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead. + * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. + * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. */ /** - * g_io_module_load: - * @module: a #GIOModule. + * g_file_info_set_modification_tim: + * @info: a #GFileInfo. + * @mtime: a #GTimeVal. * - * Required API for GIO modules to implement. - * This function is ran after the module has been loaded into GIO, - * to initialize the module. + * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file + * info to the given time value. */ /** - * g_unix_mount_point_is_user_mountable: - * @mount_point: a #GUnixMountPoint. - * - * Checks if a unix mount point is mountable by the user. + * g_file_info_set_name: + * @info: a #GFileInfo. + * @name: a string containing a name. * - * Returns: %TRUE if the mount point is user mountable. + * Sets the name attribute for the current #GFileInfo. + * See %G_FILE_ATTRIBUTE_STANDARD_NAME. */ /** - * g_app_info_supports_uris: - * @appinfo: a #GAppInfo. - * - * Checks if the application supports reading files and directories from URIs. + * g_file_info_set_size: + * @info: a #GFileInfo. + * @size: a #goffset containing the file's size. * - * Returns: %TRUE if the @appinfo supports URIs. + * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info + * to the given size. */ /** - * g_seekable_can_truncate: - * @seekable: a #GSeekable. - * - * Tests if the stream can be truncated. + * g_file_info_set_sort_order: + * @info: a #GFileInfo. + * @sort_order: a sort order integer. * - * Returns: %TRUE if the stream can be truncated, %FALSE otherwise. + * Sets the sort order attribute in the file info structure. See + * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. */ /** - * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH: + * g_file_info_set_symlink_target: + * @info: a #GFileInfo. + * @symlink_target: a static string containing a path to a symlink target. * - * Allowed characters in a path. Includes "!$&'()*+,;=:@/". + * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info + * to the given symlink target. */ /** - * GDesktopAppInfoLookup: + * g_file_info_unset_attribute_mask: + * @info: #GFileInfo. * - * Interface that is used by backends to associate default - * handlers with URI schemes. + * Unsets a mask set by g_file_info_set_attribute_mask(), if one + * is set. */ /** - * GTlsClientConnection:use-ssl3: + * g_file_input_stream_query_info: + * @stream: a #GFileInputStream. + * @attributes: a file attribute query string. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * 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. + * Queries a file input stream the given @attributes. This function blocks + * while querying the stream. For the asynchronous (non-blocking) version + * of this function, see g_file_input_stream_query_info_async(). While the + * stream is blocked, the stream will set the pending flag internally, and + * any other operations on the stream will fail with %G_IO_ERROR_PENDING. * - * Since: 2.28 + * Returns: (transfer full): a #GFileInfo, or %NULL on error. */ /** - * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE: + * g_file_input_stream_query_info_async: + * @stream: a #GFileInputStream. + * @attributes: a file attribute query string. + * @io_priority: the <link linkend="io-priority">I/O priority</link> 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 * - * A key in the "unix" namespace for getting the block size for the file - * system. This attribute is only available for UNIX file systems. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Queries the stream information asynchronously. + * When the operation is finished @callback will be called. + * You can then call g_file_input_stream_query_info_finish() + * to get the result of the operation. + * For the synchronous version of this function, + * see g_file_input_stream_query_info(). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be set */ /** - * g_dbus_interface_info_lookup_property: - * @info: A #GDBusInterfaceInfo. - * @name: A D-Bus property name (typically in CamelCase). + * g_file_input_stream_query_info_finish: + * @stream: a #GFileInputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Looks up information about a property. - * This cost of this function is O(n) in number of properties. + * Finishes an asynchronous info query operation. * - * Returns: A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. - * Since: 2.26 + * Returns: (transfer full): #GFileInfo. */ /** - * G_TYPE_PARAM_UINT64: + * g_file_io_stream_get_etag: + * @stream: a #GFileIOStream. * - * The #GType of #GParamSpecUInt64. + * Gets the entity tag for the file when it has been written. + * This must be called after the stream has been written + * and closed, as the etag can change while writing. + * + * Returns: the entity tag for the stream. + * Since: 2.22 */ /** - * GBusNameAcquiredCallback: - * @connection: The #GDBusConnection on which to acquired the name. - * @name: The name being owned. - * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection(). + * g_file_io_stream_query_info: + * @stream: a #GFileIOStream. + * @attributes: a file attribute query string. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * Invoked when the name is acquired. + * Queries a file io stream for the given @attributes. + * This function blocks while querying the stream. For the asynchronous + * version of this function, see g_file_io_stream_query_info_async(). + * While the stream is blocked, the stream will set the pending flag + * internally, and any other operations on the stream will fail with + * %G_IO_ERROR_PENDING. + * Can fail if the stream was already closed (with @error being set to + * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being + * set to %G_IO_ERROR_PENDING), or if querying info is not supported for + * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I + * all cases of failure, %NULL will be returned. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will + * be returned. * - * Since: 2.26 + * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error. + * Since: 2.22 */ /** - * GMountOperationResult: - * @G_MOUNT_OPERATION_HANDLED: The request was fulfilled and the user specified data is now available - * @G_MOUNT_OPERATION_ABORTED: The user requested the mount operation to be aborted - * @G_MOUNT_OPERATION_UNHANDLED: The request was unhandled (i.e. not implemented) + * g_file_io_stream_query_info_async: + * @stream: a #GFileIOStream. + * @attributes: a file attribute query string. + * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 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 * - * #GMountOperationResult is returned as a result when a request for - * information is send by the mounting operation. + * Asynchronously queries the @stream for a #GFileInfo. When completed, + * finish the operation with g_file_io_stream_query_info_finish(). + * For the synchronous version of this function, see + * g_file_io_stream_query_info(). + * + * Since: 2.22 */ /** - * g_mount_can_eject: - * @mount: a #GMount. + * g_file_io_stream_query_info_finish: + * @stream: a #GFileIOStream. + * @result: a #GAsyncResult. + * @error: a #GError, %NULL to ignore. * - * Checks if @mount can be eject. + * Finalizes the asynchronous query started + * by g_file_io_stream_query_info_async(). * - * Returns: %TRUE if the @mount can be ejected. + * Returns: (transfer full): A #GFileInfo for the finished query. + * Since: 2.22 */ /** - * SECTION:gmountoperatio: - * @short_description: Object used for authentication and user interaction - * @include: gio/gio.h + * g_file_is_native: + * @file: input #GFile. * - * #GMountOperation provides a mechanism for interacting with the user. - * It can be used for authenticating mountable operations, such as loop - * mounting files, hard drive partitions or server locations. It can - * also be used to ask the user questions or show a list of applications - * preventing unmount or eject operations from completing. - * Note that #GMountOperation is used for more than just #GMount - * objects – for example it is also used in g_drive_start() and - * g_drive_stop(). - * Users should instantiate a subclass of this that implements all the - * various callbacks to show the required dialogs, such as - * #GtkMountOperation. If no user interaction is desired (for example - * when automounting filesystems at login time), usually %NULL can be - * passed, see each method taking a #GMountOperation for details. + * Checks to see if a file is native to the platform. + * A native file s one expressed in the platform-native filename format, + * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, + * as it might be on a locally mounted remote filesystem. + * On some systems non-native files may be available using + * the native filesystem via a userspace filesystem (FUSE), in + * these cases this call will return %FALSE, but g_file_get_path() + * will still return a native path. + * This call does no blocking i/o. + * + * Returns: %TRUE if file is native. */ /** - * g_data_input_stream_read_int64: - * @stream: a given #GDataInputStream. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * g_file_load_contents: + * @file: input #GFile. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @contents: (out) (transfer full): a location to place the contents of the file. + * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @error: a #GError, or %NULL * - * Reads a 64-bit/8-byte value from @stream. - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). + * Loads the content of the file into memory. The data is always + * zero-terminated, but this is not included in the resultant @length. + * The returned @content should be freed with g_free() when no longer + * needed. * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * an error occurred. + * %FALSE if there were errors. * - * Returns: a signed 64-bit/8-byte value read from @stream or %0 if + * Returns: %TRUE if the @file's contents were successfully loaded. */ /** - * SECTION:gunixoutputstrea: - * @short_description: Streaming output operations for UNIX file descriptors - * @include: gio/gunixoutputstream.h - * @see_also: #GOutputStream + * g_file_load_contents_async: + * @file: input #GFile. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function * - * #GUnixOutputStream implements #GOutputStream for writing to a - * UNIX file descriptor, including asynchronous operations. The file - * descriptor must be selectable, so it doesn't work with opened files. - * Note that <filename><gio/gunixoutputstream.h></filename> belongs - * to the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Starts an asynchronous load of the @file's contents. + * For more details, see g_file_load_contents() which is + * the synchronous version of this call. + * When the load operation has completed, @callback will be called + * with @user data. To finish the operation, call + * g_file_load_contents_finish() with the #GAsyncResult returned by + * the @callback. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. */ /** - * g_simple_async_result_get_op_res_gpointer: (skip) - * @simple: a #GSimpleAsyncResult. + * g_file_load_contents_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @contents: (out) (transfer full): a location to place the contents of the file. + * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @error: a #GError, or %NULL * - * Gets a pointer result as returned by the asynchronous function. + * Finishes an asynchronous load of the @file's contents. + * The contents are placed in @contents, and @length is set to the + * size of the @contents string. The @content should be freed with + * g_free() when no longer needed. If @etag_out is present, it will be + * set to the new entity tag for the @file. + * present, it will be set appropriately. * - * Returns: a pointer from the result. + * Returns: %TRUE if the load was successful. If %FALSE and @error is */ /** - * g_memory_output_stream_steal_data: - * @ostream: a #GMemoryOutputStream - * - * Gets any loaded data from the @ostream. Ownership of the data - * is transferred to the caller; when no longer needed it must be - * freed using the free function set in @ostream's - * #GMemoryOutputStream:destroy-function property. + * g_file_load_partial_contents_async: (skip) + * @file: input #GFile. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @read_more_callback: a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to the callback functions. * - * Returns: (transfer full): the stream's data - * Since: 2.26 + * Reads the partial contents of a file. A #GFileReadMoreCallback should be + * used to stop reading from the file when appropriate, else this function + * will behave exactly as g_file_load_contents_async(). This operation + * can be finished by g_file_load_partial_contents_finish(). + * Users of this function should be aware that @user_data is passed to + * both the @read_more_callback and the @callback. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. */ /** - * G_PARAM_SPEC_VARIANT: - * @pspec: a #GParamSpec + * g_file_load_partial_contents_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @contents: (out) (transfer full): a location to place the contents of the file. + * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @error: a #GError, or %NULL * - * Casts a #GParamSpec into a #GParamSpecVariant. + * Finishes an asynchronous partial load operation that was started + * with g_file_load_partial_contents_async(). The data is always + * zero-terminated, but this is not included in the resultant @length. + * The returned @content should be freed with g_free() when no longer + * needed. + * present, it will be set appropriately. * - * Since: 2.26 + * Returns: %TRUE if the load was successful. If %FALSE and @error is */ /** - * SECTION:gactio: - * @title: GAction - * @short_description: An action + * g_file_make_director: + * @file: input #GFile. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * #GAction represents a single named action. - * The main interface to an action is that it can be activated with - * g_action_activate(). This results in the 'activate' signal being - * emitted. An activation has a #GVariant parameter (which may be - * %NULL). The correct type for the parameter is determined by a static - * parameter type (which is given at construction time). - * An action may optionally have a state, in which case the state may be - * set with g_action_set_state(). This call takes a #GVariant. The - * correct type for the state is determined by a static state type - * (which is given at construction time). - * The state may have a hint associated with it, specifying its valid - * range. - * #GAction is merely the interface to the concept of an action, as - * described above. Various implementations of actions exist, including - * #GSimpleAction and #GtkAction. - * In all cases, the implementing class is responsible for storing the - * name of the action, the parameter type, the enabled state, the - * optional state type and the state and emitting the appropriate - * signals when these change. The implementor responsible for filtering - * calls to g_action_activate() and g_action_set_state() for type safety - * and for the state being enabled. - * Probably the only useful thing to do with a #GAction is to put it - * inside of a #GSimpleActionGroup. + * Creates a directory. Note that this will only create a child directory of + * the immediate parent directory of the path or URI given by the #GFile. To + * recursively create directories, see g_file_make_directory_with_parents(). + * This function will fail if the parent directory does not exist, setting + * directories, this function will fail, setting @error to + * %G_IO_ERROR_NOT_SUPPORTED. + * For a local #GFile the newly created directory will have the default + * (current) ownership and permissions of the current process. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * Returns: %TRUE on successful creation, %FALSE otherwise. */ /** - * GTlsConnection:use-system-certdb: + * g_file_make_directory_with_parents: + * @file: input #GFile. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Whether or not the system certificate database will be used to - * verify peer certificates. See - * g_tls_connection_set_use_system_certdb(). + * Creates a directory and any parent directories that may not exist similar to + * 'mkdir -p'. If the file system does not support creating directories, this + * function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. + * For a local #GFile the newly created directories will have the default + * (current) ownership and permissions of the current process. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * otherwise. * - * Since: 2.28 + * Returns: %TRUE if all directories have been successfully created, %FALSE + * Since: 2.18 */ /** - * g_data_input_stream_read_uint32: - * @stream: a given #GDataInputStream. + * g_file_make_symbolic_link: + * @file: a #GFile with the name of the symlink to create + * @symlink_value: a string with the path for the target of the new symlink * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * @error: a #GError. * - * Reads an unsigned 32-bit/4-byte value from @stream. - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). + * Creates a symbolic link named @file which contains the string * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * an error occurred. * - * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if + * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise. */ /** - * GInetAddress:is-any: + * g_file_monitor: + * @file: input #GFile + * @flags: a set of #GFileMonitorFlags + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @error: a #GError, or %NULL * - * Whether this is the "any" address for its family. - * See g_inet_address_get_is_any(). + * Obtains a file or directory monitor for the given file, depending + * on the type of the file. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Free the returned object with g_object_unref(). * - * Since: 2.22 + * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. + * Since: 2.18 */ /** - * g_volume_get_uuid: - * @volume: a #GVolume. + * g_file_monitor_cancel: + * @monitor: a #GFileMonitor. * - * Gets the UUID for the @volume. The reference is typically based on - * the file system UUID for the volume in question and should be - * considered an opaque string. Returns %NULL if there is no UUID - * available. - * The returned string should be freed with g_free() - * when no longer needed. + * Cancels a file monitor. * - * Returns: the UUID for @volume or %NULL if no UUID can be computed. + * Returns: %TRUE if monitor was cancelled. */ /** - * GDataStream:byte-order: + * g_file_monitor_directory: + * @file: input #GFile. + * @flags: a set of #GFileMonitorFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL. * - * The ::byte-order property determines the byte ordering that - * is used when reading multi-byte entities (such as integers) - * from the stream. + * Obtains a directory monitor for the given file. + * This may fail if directory monitoring is not supported. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Free the returned object with g_object_unref(). + * + * Virtual: monitor_dir + * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. */ /** - * g_resolver_error_quark: - * - * Gets the #GResolver Error Quark. + * g_file_monitor_emit_event: + * @monitor: a #GFileMonitor. + * @child: a #GFile. + * @other_file: a #GFile. + * @event_type: a set of #GFileMonitorEvent flags. * - * Returns: a #GQuark. - * Since: 2.22 + * Emits the #GFileMonitor::changed signal if a change + * has taken place. Should be called from file monitor + * implementations only. + * The signal will be emitted from an idle handler (in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * context</link>). */ /** - * g_input_stream_clear_pending: - * @stream: input stream + * g_file_monitor_file: + * @file: input #GFile. + * @flags: a set of #GFileMonitorFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL. * - * Clears the pending flag on @stream. + * Obtains a file monitor for the given file. If no file notification + * mechanism exists, then regular polling of the file is used. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. */ /** - * g_file_copy_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_file_monitor_is_cancelled: + * @monitor: a #GFileMonitor * - * Finishes copying the file started with - * g_file_copy_async(). + * Returns whether the monitor is canceled. * - * Returns: a %TRUE on success, %FALSE on error. + * Returns: %TRUE if monitor is canceled. %FALSE otherwise. */ /** - * G_TYPE_CHECK_INSTANCE_CAST: - * @instance: Location of a #GTypeInstance structure. - * @g_type: The type to be returned. - * @c_type: The corresponding C type of @g_type. + * g_file_monitor_set_rate_limit: + * @monitor: a #GFileMonitor. + * @limit_msecs: a non-negative integer with the limit in milliseconds to poll for changes * - * Checks that @instance is an instance of the type identified by @g_type - * and issues a warning if this is not the case. Returns @instance casted - * to a pointer to @c_type. - * This macro should only be used in type implementations. + * Sets the rate limit to which the @monitor will report + * consecutive change events to the same file. */ /** - * G_IS_PARAM_SPEC_PARAM: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. + * g_file_mount_enclosing_volume: + * @location: input #GFile. + * @flags: flags affecting the operation + * @mount_operation: a #GMountOperation or %NULL to avoid user interaction. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. + * @user_data: the data to pass to callback function * - * Returns: %TRUE on success. + * Starts a @mount_operation, mounting the volume that contains the file @location. + * When this operation has completed, @callback will be called with + * g_file_mount_enclosing_volume_finish(). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. */ /** - * g_file_get_uri_scheme: - * @file: input #GFile. + * g_file_mount_enclosing_volume_finish: + * @location: input #GFile. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Gets the URI scheme for a #GFile. - * RFC 3986 decodes the scheme as: - * <programlisting> - * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * </programlisting> - * Common schemes include "file", "http", "ftp", etc. - * This call does no blocking i/o. - * #GFile. The returned string should be freed with g_free() - * when no longer needed. + * Finishes a mount operation started by g_file_mount_enclosing_volume(). + * has occurred, this function will return %FALSE and set @error + * appropriately if present. * - * Returns: a string containing the URI scheme for the given + * Returns: %TRUE if successful. If an error */ /** - * GAsyncInitable: - * - * Interface for asynchronously initializable objects. + * g_file_mount_mountable: + * @file: input #GFile. + * @flags: flags affecting the operation + * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. + * @user_data: (closure): the data to pass to callback function * - * Since: 2.22 + * Mounts a file of type G_FILE_TYPE_MOUNTABLE. + * Using @mount_operation, you can request callbacks when, for instance, + * passwords are needed during authentication. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * When the operation is finished, @callback will be called. You can then call + * g_file_mount_mountable_finish() to get the result of the operation. */ /** - * g_settings_set_boolean: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * g_file_mount_mountable_finish: + * @file: input #GFile. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Sets @key in @settings to @value. - * A convenience variant of g_settings_set() for booleans. - * It is a programmer error to give a @key that isn't specified as - * having a boolean type in the schema for @settings. + * Finishes a mount operation. See g_file_mount_mountable() for details. + * Finish an asynchronous mount operation that was started + * with g_file_mount_mountable(). + * Free the returned object with g_object_unref(). * - * Since: 2.26 + * Returns: (transfer full): a #GFile or %NULL on error. */ /** - * SECTION:gsocketclien: - * @short_description: Helper for connecting to a network service - * @include: gio/gio.h - * @see_also: #GSocketConnection, #GSocketListener + * g_file_move: + * @source: #GFile pointing to the source location. + * @destination: #GFile pointing to the destination location. + * @flags: set of #GFileCopyFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @progress_callback: (scope call): #GFileProgressCallback function for updates. + * @progress_callback_data: (closure): gpointer to user data for the callback function. + * @error: #GError for returning error conditions, or %NULL * - * #GSocketClient is a high-level utility class for connecting to a - * network host using a connection oriented socket type. - * You create a #GSocketClient object, set any options you want, then - * call a sync or async connect operation, which returns a #GSocketConnection - * subclass on success. - * The type of the #GSocketConnection object returned depends on the type of - * the underlying socket that is in use. For instance, for a TCP/IP connection - * it will be a #GTcpConnection. + * Tries to move the file or directory @source to the location specified by @destination. + * If native move operations are supported then this is used, otherwise a copy + delete + * fallback is used. The native implementation may support moving directories (for instance + * on moves inside the same filesystem), but the fallback code does not. + * If the flag #G_FILE_COPY_OVERWRITE is specified an already + * existing @destination file is overwritten. + * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks + * will be copied as symlinks, otherwise the target of the + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If @progress_callback is not %NULL, then the operation can be monitored by + * setting this to a #GFileProgressCallback function. @progress_callback_data + * will be passed to this function. It is guaranteed that this callback will + * be called after all data has been transferred with the total number of bytes + * copied during the operation. + * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND + * error is returned, independent on the status of the @destination. + * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the + * error G_IO_ERROR_EXISTS is returned. + * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY + * error is returned. If trying to overwrite a directory with a directory the + * G_IO_ERROR_WOULD_MERGE error is returned. + * If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is + * specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error + * may be returned (if the native move operation isn't available). * - * Since: 2.22 + * Returns: %TRUE on successful move, %FALSE otherwise. */ /** - * G_TYPE_FUNDAMENTAL_SHIFT: + * g_file_new_for_commandline_arg: + * @arg: a command line string. * - * Shift value used in converting numbers to type IDs. + * Creates a #GFile with the given argument from the command line. The value of + * relative to the current working directory. + * This operation never fails, but the returned object might not support any + * I/O operation if @arg points to a malformed path. + * + * Returns: (transfer full): a new #GFile. */ /** - * g_app_info_get_all: + * g_file_new_for_path: + * @path: a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. * - * Gets a list of all of the applications currently registered - * on this system. - * For desktop files, this includes applications that have - * <literal>NoDisplay=true</literal> set or are excluded from - * display by means of <literal>OnlyShowIn</literal> or - * <literal>NotShowIn</literal>. See g_app_info_should_show(). - * The returned list does not include applications which have - * the <literal>Hidden</literal> key set. + * Constructs a #GFile for a given path. This operation never + * fails, but the returned object might not support any I/O + * operation if @path is malformed. * - * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s. + * Returns: (transfer full): a new #GFile for the given @path. */ /** - * g_socket_send: - * @socket: a #GSocket - * @buffer: (array length=size): the buffer containing the data to send. - * @size: the number of bytes to send - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_file_new_for_uri: + * @uri: a UTF8 string containing a URI. * - * Tries to send @size bytes from @buffer on the socket. This is - * mainly used by connection-oriented sockets; it is identical to - * g_socket_send_to() with @address set to %NULL. - * If the socket is in blocking mode the call will block until there is - * space for the data in the socket queue. If there is no space available - * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error - * 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. - * on error + * Constructs a #GFile for a given URI. This operation never + * fails, but the returned object might not support any I/O + * operation if @uri is malformed or if the uri type is + * not supported. * - * Returns: Number of bytes written (which may be less than @size), or -1 - * Since: 2.22 + * Returns: (transfer full): a #GFile for the given @uri. */ /** - * g_socket_client_set_timeout: - * @client: a #GSocketClient. - * @timeout: the timeout + * g_file_open_readwrite: + * @file: #GFile to open + * @cancellable: (allow-none): a #GCancellable + * @error: a #GError, or %NULL * - * Sets the I/O timeout for sockets created by @client. @timeout is a - * time in seconds, or 0 for no timeout (the default). - * The timeout value affects the initial connection attempt as well, - * so setting this may cause calls to g_socket_client_connect(), etc, - * to fail with %G_IO_ERROR_TIMED_OUT. + * Opens an existing file for reading and writing. The result is + * a #GFileIOStream that can be used to read and write the contents of the file. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. + * If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned. + * Other errors are possible too, and depend on what kind of filesystem the file is on. + * Note that in many non-local file cases read and write streams are not supported, + * so make sure you really need to do read and write streaming, rather than + * just opening for reading or writing. + * Free the returned object with g_object_unref(). * - * Since: 2.26 + * Returns: (transfer full): #GFileIOStream or %NULL on error. + * Since: 2.22 */ /** - * g_new0: - * @struct_type: the type of the elements to allocate. - * @n_structs: the number of elements to allocate. + * g_file_open_readwrite_async: + * @file: input #GFile. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Allocates @n_structs elements of type @struct_type, initialized to 0's. - * The returned pointer is cast to a pointer to the given type. - * If @n_structs is 0 it returns %NULL. - * Care is taken to avoid overflow when calculating the size of the allocated block. - * Since the returned pointer is already casted to the right type, - * it is normally unnecessary to cast it explicitly, and doing - * so might hide memory allocation errors. + * Asynchronously opens @file for reading and writing. + * For more details, see g_file_open_readwrite() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_open_readwrite_finish() to get the result of the operation. * - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. + * Since: 2.22 */ @@ -22530,1156 +21508,1538 @@ /** - * GMountOperation:choice: - * - * The index of the user's choice when a question is asked during the - * mount operation. See the #GMountOperation::ask-question signal. - */ - - -/** - * g_buffered_output_stream_get_auto_grow: - * @stream: a #GBufferedOutputStream. + * g_file_output_stream_get_etag: + * @stream: a #GFileOutputStream. * - * Checks if the buffer automatically grows as data is added. - * %FALSE otherwise. + * Gets the entity tag for the file when it has been written. + * This must be called after the stream has been written + * and closed, as the etag can change while writing. * - * Returns: %TRUE if the @stream's buffer automatically grows, + * Returns: the entity tag for the stream. */ /** - * g_socket_new: - * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4. - * @type: the socket type to use. - * @protocol: the id of the protocol to use, or 0 for default. - * @error: #GError for error reporting, or %NULL to ignore. + * g_file_output_stream_query_info: + * @stream: a #GFileOutputStream. + * @attributes: a file attribute query string. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @error: a #GError, %NULL to ignore. * - * Creates a new #GSocket with the defined family, type and protocol. - * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type - * for the family and type is used. - * The @protocol is a family and type specific int that specifies what - * kind of protocol to use. #GSocketProtocol lists several common ones. - * Many families only support one protocol, and use 0 for this, others - * support several and using 0 means to use the default protocol for - * the family and type. - * The protocol id is passed directly to the operating - * system, so you can use protocols not listed in #GSocketProtocol if you - * know the protocol number used for it. - * Free the returned object with g_object_unref(). + * Queries a file output stream for the given @attributes. + * This function blocks while querying the stream. For the asynchronous + * version of this function, see g_file_output_stream_query_info_async(). + * While the stream is blocked, the stream will set the pending flag + * internally, and any other operations on the stream will fail with + * %G_IO_ERROR_PENDING. + * Can fail if the stream was already closed (with @error being set to + * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being + * set to %G_IO_ERROR_PENDING), or if querying info is not supported for + * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In + * all cases of failure, %NULL will be returned. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will + * be returned. * - * Returns: a #GSocket or %NULL on error. - * Since: 2.22 + * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error. */ /** - * g_converter_input_stream_get_converter: - * @converter_stream: a #GConverterInputStream - * - * Gets the #GConverter that is used by @converter_stream. + * g_file_output_stream_query_info_async: + * @stream: a #GFileOutputStream. + * @attributes: a file attribute query string. + * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: callback to call when the request is satisfied + * @user_data: the data to pass to callback function * - * Returns: (transfer none): the converter of the converter input stream - * Since: 2.24 + * Asynchronously queries the @stream for a #GFileInfo. When completed, + * finish the operation with g_file_output_stream_query_info_finish(). + * For the synchronous version of this function, see + * g_file_output_stream_query_info(). */ /** - * g_file_info_set_attribute_stringv: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a %NULL terminated string array + * g_file_output_stream_query_info_finish: + * @stream: a #GFileOutputStream. + * @result: a #GAsyncResult. + * @error: a #GError, %NULL to ignore. * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * Finalizes the asynchronous query started + * by g_file_output_stream_query_info_async(). * - * Sinze: 2.22 + * Returns: (transfer full): A #GFileInfo for the finished query. */ /** - * g_themed_icon_get_names: - * @icon: a #GThemedIcon. + * g_file_parse_name: + * @parse_name: a file name or path to be parsed. * - * Gets the names of icons from within @icon. + * Constructs a #GFile with the given @parse_name (i.e. something given by g_file_get_parse_name()). + * This operation never fails, but the returned object might not support any I/O + * operation if the @parse_name cannot be parsed. * - * Returns: (transfer none): a list of icon names. + * Returns: (transfer full): a new #GFile. */ /** - * g_file_mount_mountable: + * g_file_poll_mountable: * @file: input #GFile. - * @flags: flags affecting the operation - * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. - * @user_data: (closure): the data to pass to callback function + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. + * @user_data: the data to pass to callback function * - * Mounts a file of type G_FILE_TYPE_MOUNTABLE. - * Using @mount_operation, you can request callbacks when, for instance, - * passwords are needed during authentication. + * Polls a file of type G_FILE_TYPE_MOUNTABLE. * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * When the operation is finished, @callback will be called. You can then call * g_file_mount_mountable_finish() to get the result of the operation. + * + * Since: 2.22 */ /** - * GCredentials: + * g_file_poll_mountable_finish: + * @file: input #GFile. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * The #GCredentials structure contains only private data and - * should only be accessed using the provided API. + * Finishes a poll operation. See g_file_poll_mountable() for details. + * Finish an asynchronous poll operation that was polled + * with g_file_poll_mountable(). + * otherwise. * - * Since: 2.26 + * Returns: %TRUE if the operation finished successfully. %FALSE + * Since: 2.22 */ /** - * g_desktop_app_info_lookup_get_default_for_uri_scheme: - * @lookup: a #GDesktopAppInfoLookup - * @uri_scheme: a string containing a URI scheme. + * g_file_query_default_handler: + * @file: a #GFile to open. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Gets the default application for launching applications - * using this URI scheme for a particular GDesktopAppInfoLookup - * implementation. - * The GDesktopAppInfoLookup interface and this function is used - * to implement g_app_info_get_default_for_uri_scheme() backends - * in a GIO module. There is no reason for applications to use it - * directly. Applications should use g_app_info_get_default_for_uri_scheme(). + * Returns the #GAppInfo that is registered as the default + * application to handle the file specified by @file. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * When you are done with it, release it with g_object_unref() * - * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error. - * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio. + * Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors. */ /** - * G_TYPE_PARAM: + * g_file_query_exists: + * @file: input #GFile. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * - * The fundamental type from which all #GParamSpec types are derived. + * Utility function to check if a particular file exists. This is + * implemented using g_file_query_info() and as such does blocking I/O. + * Note that in many cases it is racy to first check for file existence + * and then execute something based on the outcome of that, because the + * file might have been created or removed in between the operations. The + * general approach to handling that is to not check, but just do the + * operation and handle the errors as they come. + * As an example of race-free checking, take the case of reading a file, and + * can both result in two processes creating the file (with perhaps a partially + * written file as the result). The correct approach is to always try to create + * the file with g_file_create() which will either atomically create the file + * or fail with a G_IO_ERROR_EXISTS error. + * However, in many cases an existence check is useful in a user + * interface, for instance to make a menu item sensitive/insensitive, so that + * you don't have to fool users that something is possible and then just show + * and error dialog. If you do this, you should make sure to also handle the + * errors that can happen due to races when you execute the operation. + * + * If it doesn't exist, creating it. there are two racy versions: read it, and + * On error create it; and: check if it exists, if not create it. These + * Returns: %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). */ /** - * GTypePlugin: + * g_file_query_file_type: + * @file: input #GFile. + * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info(). + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * - * The <structname>GTypePlugin</structname> typedef is used as a placeholder - * for objects that implement the <structname>GTypePlugin</structname> - * interface. + * Utility function to inspect the #GFileType of a file. This is + * implemented using g_file_query_info() and as such does blocking I/O. + * The primary use case of this method is to check if a file is a regular file, + * directory, or symlink. + * does not exist + * + * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file + * Since: 2.18 */ /** - * G_FILE_ATTRIBUTE_STANDARD_ICON: + * g_file_query_filesystem_info: + * @file: input #GFile. + * @attributes: an attribute query string. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError. * - * A key in the "standard" namespace for getting the icon for the file. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. - * The value for this key should contain a #GIcon. + * Similar to g_file_query_info(), but obtains information + * about the filesystem the @file is on, rather than the file itself. + * For instance the amount of space available and the type of + * the filesystem. + * The @attributes value is a string that specifies the file attributes that + * should be gathered. It is not an error if it's not possible to read a particular + * requested attribute from a file - it just won't be set. @attributes should + * be a comma-separated list of attributes or attribute wildcards. The wildcard "*" + * means all attributes, and a wildcard like "fs:*" means all attributes in the fs + * namespace. The standard namespace for filesystem attributes is "fs". + * Common attributes of interest are #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE + * (the total size of the filesystem in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of + * bytes available), and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. + * Other errors are possible too, and depend on what kind of filesystem the file is on. + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. */ /** - * g_application_get_inactivity_timeout: - * @application: a #GApplication - * - * Gets the current inactivity timeout for the application. - * This is the amount of time (in milliseconds) after the last call to - * g_application_release() before the application stops running. + * g_file_query_filesystem_info_async: + * @file: input #GFile. + * @attributes: an attribute query string. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Returns: the timeout, in milliseconds - * Since: 2.28 + * Asynchronously gets the requested information about the filesystem + * that the specified @file is on. The result is a #GFileInfo object + * that contains key-value attributes (such as type or size for the + * file). + * For more details, see g_file_query_filesystem_info() which is the + * synchronous version of this call. + * When the operation is finished, @callback will be called. You can + * then call g_file_query_info_finish() to get the result of the + * operation. */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL: + * g_file_query_filesystem_info_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError. * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * Finishes an asynchronous filesystem info query. See + * g_file_query_filesystem_info_async(). + * Free the returned object with g_object_unref(). * - * Since: 2.22 + * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. */ /** - * g_unix_mount_get_mount_path: - * @mount_entry: input #GUnixMountEntry to get the mount path for. + * g_file_query_info: + * @file: input #GFile. + * @attributes: an attribute query string. + * @flags: a set of #GFileQueryInfoFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError. * - * Gets the mount path for a unix mount. + * Gets the requested information about specified @file. The result + * is a #GFileInfo object that contains key-value attributes (such as + * the type or size of the file). + * The @attributes value is a string that specifies the file attributes that + * should be gathered. It is not an error if it's not possible to read a particular + * requested attribute from a file - it just won't be set. @attributes should + * be a comma-separated list of attributes or attribute wildcards. The wildcard "*" + * means all attributes, and a wildcard like "standard::*" means all attributes in the standard + * namespace. An example attribute query be "standard::*,owner::user". + * The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * For symlinks, normally the information about the target of the + * symlink is returned, rather than information about the symlink itself. + * However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in @flags the + * information about the symlink itself will be returned. Also, for symlinks + * that point to non-existing files the information about the symlink itself + * will be returned. + * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. + * Other errors are possible too, and depend on what kind of filesystem the file is on. + * Free the returned object with g_object_unref(). * - * Returns: the mount path for @mount_entry. + * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error. */ /** - * g_app_info_get_all_for_type: - * @content_type: the content type to find a #GAppInfo for - * - * Gets a list of all #GAppInfos for a given content type. - * for given @content_type or %NULL on error. + * g_file_query_info_async: + * @file: input #GFile. + * @attributes: an attribute query string. + * @flags: a set of #GFileQueryInfoFlags. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * Asynchronously gets the requested information about specified @file. The result + * is a #GFileInfo object that contains key-value attributes (such as type or size + * for the file). + * For more details, see g_file_query_info() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_query_info_finish() to get the result of the operation. */ /** - * g_win32_input_stream_get_handle: - * @stream: a #GWin32InputStream + * g_file_query_info_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError. * - * Return the Windows file handle that the stream reads from. + * Finishes an asynchronous file info query. + * See g_file_query_info_async(). + * Free the returned object with g_object_unref(). * - * Returns: The file handle of @stream - * Since: 2.26 + * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. */ /** - * G_TYPE_PARAM_BOOLEAN: + * g_file_query_settable_attributes: + * @file: input #GFile. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * The #GType of #GParamSpecBoolean. + * Obtain the list of settable attributes for the file. + * Returns the type and full attribute name of all the attributes + * that can be set on this file. This doesn't mean setting it will always + * succeed though, you might get an access failure, or some specific + * file may not support a specific attribute. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * When you are done with it, release it with g_file_attribute_info_list_unref() + * + * Returns: a #GFileAttributeInfoList describing the settable attributes. */ /** - * GDataOutputStream:byte-order: + * g_file_query_writable_namespaces: + * @file: input #GFile. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Determines the byte ordering that is used when writing - * multi-byte entities (such as integers) to the stream. + * Obtain the list of attribute namespaces where new attributes + * can be created by a user. An example of this is extended + * attributes (in the "xattr" namespace). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * When you are done with it, release it with g_file_attribute_info_list_unref() + * + * Returns: a #GFileAttributeInfoList describing the writable namespaces. */ /** - * g_dbus_method_invocation_get_method_info: - * @invocation: A #GDBusMethodInvocation. + * g_file_read: + * @file: #GFile to read. + * @cancellable: (allow-none): a #GCancellable + * @error: a #GError, or %NULL * - * Gets information about the method call, if any. + * Opens a file for reading. The result is a #GFileInputStream that + * can be used to read the contents of the file. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. + * If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned. + * Other errors are possible too, and depend on what kind of filesystem the file is on. + * Free the returned object with g_object_unref(). * - * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. - * Since: 2.26 + * Virtual: read_fn + * Returns: (transfer full): #GFileInputStream or %NULL on error. */ /** - * g_tls_certificate_list_new_from_file: - * @file: file containing PEM-encoded certificates to import - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded - * data in @file. If @file cannot be read or parsed, the function will - * return %NULL and set @error. If @file does not contain any - * PEM-encoded certificates, this will return an empty list and not - * set @error. - * #GList containing #GTlsCertificate objects. You must free the list - * and its contents when you are done with it. + * g_file_read_async: + * @file: input #GFile + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Returns: (element-type Gio.TlsCertificate) (transfer full): a - * Since: 2.28 + * Asynchronously opens @file for reading. + * For more details, see g_file_read() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_read_finish() to get the result of the operation. */ /** - * g_inet_address_new_from_bytes: - * @bytes: raw address data - * @family: the address family of @bytes + * g_file_read_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Creates a new #GInetAddress from the given @family and @bytes. - * %G_INET_ADDRESS_IPV6. + * Finishes an asynchronous file read operation started with + * g_file_read_async(). + * Free the returned object with g_object_unref(). * - * Returns: a new #GInetAddress corresponding to @family and @bytes. - * Since: 2.22 + * Returns: (transfer full): a #GFileInputStream or %NULL on error. */ /** - * g_io_stream_splice_finish: - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_file_replace: + * @file: input #GFile. + * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore. + * @make_backup: %TRUE if a backup should be created. + * @flags: a set of #GFileCreateFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Finishes an asynchronous io stream splice operation. + * Returns an output stream for overwriting the file, possibly + * creating a backup copy of the file first. If the file doesn't exist, + * it will be created. + * This will try to replace the file in the safest way possible so + * that any errors during the writing will not affect an already + * existing copy of the file. For instance, for local files it + * may write to a temporary file and then atomically rename over + * the destination when the stream is closed. + * By default files created are generally readable by everyone, + * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file + * will be made readable only to the current user, to the level that + * is supported on the target filesystem. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If you pass in a non-#NULL @etag value, then this value is + * compared to the current entity tag of the file, and if they differ + * an G_IO_ERROR_WRONG_ETAG error is returned. This generally means + * 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 a G_IO_ERROR_CANT_CREATE_BACKUP + * error will be returned. If you want to replace anyway, try again with + * If the file is a directory the G_IO_ERROR_IS_DIRECTORY error will be returned, + * and if the file is some other form of non-regular file then a + * G_IO_ERROR_NOT_REGULAR_FILE error will be returned. + * Some file systems don't allow all file names, and may + * return an G_IO_ERROR_INVALID_FILENAME error, and if the name + * is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned. + * Other errors are possible too, and depend on what kind of + * filesystem the file is on. + * Free the returned object with g_object_unref(). * - * Returns: %TRUE on success, %FALSE otherwise. - * Since: 2.28 + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. */ /** - * g_file_attribute_info_list_unref: - * @list: The #GFileAttributeInfoList to unreference. + * g_file_replace_async: + * @file: input #GFile. + * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore. + * @make_backup: %TRUE if a backup should be created. + * @flags: a set of #GFileCreateFlags. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Removes a reference from the given @list. If the reference count - * falls to zero, the @list is deleted. + * Asynchronously overwrites the file, replacing the contents, possibly + * creating a backup copy of the file first. + * For more details, see g_file_replace() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_replace_finish() to get the result of the operation. */ /** - * G_VALUE_HOLDS_OBJECT: - * @value: a valid #GValue structure + * g_file_replace_contents: + * @file: input #GFile. + * @contents: a string containing the new contents for @file. + * @length: the length of @contents in bytes. + * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link> for the document, or %NULL + * @make_backup: %TRUE if a backup should be created. + * @flags: a set of #GFileCreateFlags. + * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when no longer needed, or %NULL + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. + * Replaces the contents of @file with @contents of @length bytes. + * If @etag is specified (not %NULL) any existing file must have that etag, or + * the error %G_IO_ERROR_WRONG_ETAG will be returned. + * If @make_backup is %TRUE, this function will attempt to make a backup of @file. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * The returned @new_etag can be used to verify that the file hasn't changed the + * next time it is saved over. + * has occurred, this function will return %FALSE and set @error + * appropriately if present. * - * Returns: %TRUE on success. + * Returns: %TRUE if successful. If an error */ /** - * GTypeQuery: - * @type: the #GType value of the type. - * @type_name: the name of the type. - * @class_size: the size of the class structure. - * @instance_size: the size of the instance structure. + * g_file_replace_contents_async: + * @file: input #GFile. + * @contents: string of contents to replace the file with. + * @length: the length of @contents in bytes. + * @etag: (allow-none): a new <link linkend="gfile-etag">entity tag</link> for the @file, or %NULL + * @make_backup: %TRUE if a backup should be created. + * @flags: a set of #GFileCreateFlags. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function * - * A structure holding information for a specific type. It is - * filled in by the g_type_query() function. + * Starts an asynchronous replacement of @file with the given + * current entity tag. + * When this operation has completed, @callback will be called with + * g_file_replace_contents_finish(). + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * If @make_backup is %TRUE, this function will attempt to + * make a backup of @file. */ /** - * GTlsBackend: + * g_file_replace_contents_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @new_etag: (out) (allow-none): a location of a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when it is no longer needed, or %NULL + * @error: a #GError, or %NULL * - * TLS (Transport Layer Security, aka SSL) backend. This is an - * internal type used to coordinate the different classes implemented - * by a TLS backend. + * Finishes an asynchronous replace of the given @file. See + * g_file_replace_contents_async(). Sets @new_etag to the new entity + * tag for the document, if present. * - * Since: 2.28 + * Returns: %TRUE on success, %FALSE on failure. */ /** - * g_bus_own_name_on_connection: - * @connection: A #GDBusConnection. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL. - * @name_lost_handler: Handler to invoke when @name is lost or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: Function for freeing @user_data or %NULL. + * g_file_replace_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Like g_bus_own_name() but takes a #GDBusConnection instead of a - * #GBusType. - * g_bus_unown_name() to stop owning the name. + * Finishes an asynchronous file replace operation started with + * g_file_replace_async(). + * Free the returned object with g_object_unref(). * - * Returns: An identifier (never 0) that an be used with - * Since: 2.26 + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. */ /** - * g_unix_input_stream_set_close_fd: - * @stream: a #GUnixInputStream - * @close_fd: %TRUE to close the file descriptor when done + * g_file_replace_readwrite: + * @file: a #GFile + * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore + * @make_backup: %TRUE if a backup should be created + * @flags: a set of #GFileCreateFlags + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @error: return location for a #GError, or %NULL * - * Sets whether the file descriptor of @stream shall be closed - * when the stream is closed. + * Returns an output stream for overwriting the file in readwrite mode, + * possibly creating a backup copy of the file first. If the file doesn't + * exist, it will be created. + * For details about the behaviour, see g_file_replace() which does the same + * thing but returns an output stream only. + * Note that in many non-local file cases read and write streams are not + * supported, so make sure you really need to do read and write streaming, + * rather than just opening for reading or writing. + * Free the returned object with g_object_unref(). * - * Since: 2.20 + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Since: 2.22 */ /** - * GMountOperation::ask-password: - * @op: a #GMountOperation requesting a password. - * @message: string containing a message to display to the user. - * @default_user: string containing the default user name. - * @default_domain: string containing the default domain. - * @flags: a set of #GAskPasswordFlags. + * g_file_replace_readwrite_async: + * @file: input #GFile. + * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore. + * @make_backup: %TRUE if a backup should be created. + * @flags: a set of #GFileCreateFlags. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Emitted when a mount operation asks the user for a password. - * If the message contains a line break, the first line should be - * presented as a heading. For example, it may be used as the - * primary text in a #GtkMessageDialog. + * Asynchronously overwrites the file in read-write mode, replacing the + * contents, possibly creating a backup copy of the file first. + * For more details, see g_file_replace_readwrite() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then + * call g_file_replace_readwrite_finish() to get the result of the operation. + * + * Since: 2.22 */ /** - * G_TYPE_STRING: + * g_file_replace_readwrite_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError, or %NULL * - * The fundamental type corresponding to nul-terminated C strings. + * Finishes an asynchronous file replace operation started with + * g_file_replace_readwrite_async(). + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): a #GFileIOStream, or %NULL on error. + * Since: 2.22 */ /** - * g_file_query_filesystem_info: + * g_file_resolve_relative_path: * @file: input #GFile. - * @attributes: an attribute query string. + * @relative_path: a given relative path string. + * + * Resolves a relative path for @file to an absolute path. + * This call does no blocking i/o. + * is %NULL or if @file is invalid. + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): #GFile to the resolved path. %NULL if @relative_path + */ + + +/** + * g_file_set_attribute: + * @file: input #GFile. + * @attribute: a string containing the attribute's name. + * @type: The type of the attribute + * @value_p: a pointer to the value (or the pointer itself if the type is a pointer type) + * @flags: a set of #GFileQueryInfoFlags. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, or %NULL * - * Similar to g_file_query_info(), but obtains information - * about the filesystem the @file is on, rather than the file itself. - * For instance the amount of space available and the type of - * the filesystem. - * The @attributes value is a string that specifies the file attributes that - * should be gathered. It is not an error if it's not possible to read a particular - * requested attribute from a file - it just won't be set. @attributes should - * be a comma-separated list of attributes or attribute wildcards. The wildcard "*" - * means all attributes, and a wildcard like "fs:*" means all attributes in the fs - * namespace. The standard namespace for filesystem attributes is "fs". - * Common attributes of interest are #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE - * (the total size of the filesystem in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of - * bytes available), and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem). + * Sets an attribute in the file with attribute name @attribute to @value. * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. - * Other errors are possible too, and depend on what kind of filesystem the file is on. - * Free the returned object with g_object_unref(). * - * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. + * Returns: %TRUE if the attribute was set, %FALSE otherwise. */ /** - * g_socket_control_message_serialize: - * @message: a #GSocketControlMessage - * @data: A buffer to write data to + * g_file_set_attribute_byte_string: + * @file: input #GFile. + * @attribute: a string containing the attribute's name. + * @value: a string containing the attribute's new value. + * @flags: a #GFileQueryInfoFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Converts the data in the message to bytes placed in the - * message. - * returned by g_socket_control_message_get_size() on this - * object. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. + * If @attribute is of a different type, this operation will fail, + * returning %FALSE. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * in the @file, %FALSE otherwise. * - * Since: 2.22 + * Returns: %TRUE if the @attribute was successfully set to @value */ /** - * g_dbus_connection_get_unique_name: - * @connection: A #GDBusConnection. + * g_file_set_attribute_int32: + * @file: input #GFile. + * @attribute: a string containing the attribute's name. + * @value: a #gint32 containing the attribute's new value. + * @flags: a #GFileQueryInfoFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Gets the unique name of @connection as assigned by the message - * bus. This can also be used to figure out if @connection is a - * message bus connection. - * bus connection. Do not free this string, it is owned by + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. + * If @attribute is of a different type, this operation will fail. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * in the @file, %FALSE otherwise. * - * Returns: The unique name or %NULL if @connection is not a message - * Since: 2.26 + * Returns: %TRUE if the @attribute was successfully set to @value */ /** - * g_unix_input_stream_new: - * @fd: a UNIX file descriptor - * @close_fd: %TRUE to close the file descriptor when done + * g_file_set_attribute_int64: + * @file: input #GFile. + * @attribute: a string containing the attribute's name. + * @value: a #guint64 containing the attribute's new value. + * @flags: a #GFileQueryInfoFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Creates a new #GUnixInputStream for the given @fd. - * If @close_fd is %TRUE, the file descriptor will be closed - * when the stream is closed. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. + * If @attribute is of a different type, this operation will fail. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a new #GUnixInputStream + * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise. */ /** - * g_simple_async_result_run_in_thread: (skip) - * @simple: a #GSimpleAsyncResult. - * @func: a #GSimpleAsyncThreadFunc. - * @io_priority: the io priority of the request. + * g_file_set_attribute_string: + * @file: input #GFile. + * @attribute: a string containing the attribute's name. + * @value: a string containing the attribute's value. + * @flags: #GFileQueryInfoFlags. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Runs the asynchronous job in a separate thread and then calls - * g_simple_async_result_complete_in_idle() on @simple to return - * the result to the appropriate main loop. - * Calling this function takes a reference to @simple for as long as - * is needed to run the job and report its completion. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. + * If @attribute is of a different type, this operation will fail. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise. */ /** - * g_dbus_proxy_get_cached_property: - * @proxy: A #GDBusProxy. - * @property_name: Property name. + * g_file_set_attribute_uint32: + * @file: input #GFile. + * @attribute: a string containing the attribute's name. + * @value: a #guint32 containing the attribute's new value. + * @flags: a #GFileQueryInfoFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Looks up the value for a property from the cache. This call does no - * blocking IO. - * If @proxy has an expected interface (see - * #GDBusProxy:g-interface-info), then @property_name (for existence) - * is checked against it. - * for @property_name or %NULL if the value is not in the cache. The - * returned reference must be freed with g_variant_unref(). + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. + * If @attribute is of a different type, this operation will fail. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * in the @file, %FALSE otherwise. * - * Returns: A reference to the #GVariant instance that holds the value - * Since: 2.26 + * Returns: %TRUE if the @attribute was successfully set to @value */ /** - * g_file_io_stream_query_info: - * @stream: a #GFileIOStream. - * @attributes: a file attribute query string. + * g_file_set_attribute_uint64: + * @file: input #GFile. + * @attribute: a string containing the attribute's name. + * @value: a #guint64 containing the attribute's new value. + * @flags: a #GFileQueryInfoFlags. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * @error: a #GError, or %NULL * - * Queries a file io stream for the given @attributes. - * This function blocks while querying the stream. For the asynchronous - * version of this function, see g_file_io_stream_query_info_async(). - * While the stream is blocked, the stream will set the pending flag - * internally, and any other operations on the stream will fail with - * %G_IO_ERROR_PENDING. - * Can fail if the stream was already closed (with @error being set to - * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being - * set to %G_IO_ERROR_PENDING), or if querying info is not supported for - * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I - * all cases of failure, %NULL will be returned. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. + * If @attribute is of a different type, this operation will fail. * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will - * be returned. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * in the @file, %FALSE otherwise. * - * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error. - * Since: 2.22 + * Returns: %TRUE if the @attribute was successfully set to @value */ /** - * G_PARAM_SPEC_OBJECT: - * @pspec: a valid #GParamSpec instance + * g_file_set_attributes_async: + * @file: input #GFile. + * @info: a #GFileInfo. + * @flags: a #GFileQueryInfoFlags. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): a #gpointer. * - * Casts a #GParamSpec instance into a #GParamSpecObject. + * Asynchronously sets the attributes of @file with @info. + * For more details, see g_file_set_attributes_from_info() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_set_attributes_finish() to get the result of the operation. */ /** - * GSocketAddressEnumerator: + * g_file_set_attributes_finish: + * @file: input #GFile. + * @result: a #GAsyncResult. + * @info: (out) (transfer full): a #GFileInfo. + * @error: a #GError, or %NULL * - * Enumerator type for objects that contain or generate - * #GSocketAddress<!-- -->es. + * Finishes setting an attribute started in g_file_set_attributes_async(). + * + * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise. */ /** - * GMarkupError: - * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8 - * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace - * @G_MARKUP_ERROR_PARSE: document was ill-formed - * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known - * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known - * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid - * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing + * g_file_set_attributes_from_info: + * @file: input #GFile. + * @info: a #GFileInfo. + * @flags: #GFileQueryInfoFlags + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Error codes returned by markup parsing. + * Tries to set all attributes in the #GFileInfo on the target values, + * not stopping on the first error. + * If there is any error during this operation then @error will be set to + * the first error. Error on particular fields are flagged by setting + * the "status" field in the attribute value to + * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect + * further errors. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * Returns: %TRUE if there was any error, %FALSE otherwise. */ /** - * g_mount_operation_get_usernam: - * @op: a #GMountOperation. + * g_file_set_display_name: + * @file: input #GFile. + * @display_name: a string. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * Get the user name from the mount operation. + * Renames @file to the specified display name. + * The display name is converted from UTF8 to the correct encoding for the target + * filesystem if possible and the @file is renamed to this. + * If you want to implement a rename operation in the user interface the edit name + * (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename + * widget, and then the result after editing should be passed to g_file_set_display_name(). + * On success the resulting converted filename is returned. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * if there was an error. + * Free the returned object with g_object_unref(). * - * Returns: a string containing the user name. + * Returns: (transfer full): a #GFile specifying what @file was renamed to, or %NULL */ /** - * GParamSpecInt64: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_file_set_display_name_async: + * @file: input #GFile. + * @display_name: a string. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * A #GParamSpec derived structure that contains the meta data for 64bit integer properties. + * Asynchronously sets the display name for a given #GFile. + * For more details, see g_file_set_display_name() which is + * the synchronous version of this call. + * When the operation is finished, @callback will be called. You can then call + * g_file_set_display_name_finish() to get the result of the operation. */ /** - * SECTION:gproxyaddres: - * @short_description: An internet address with proxy information + * g_file_set_display_name_finish: + * @file: input #GFile. + * @res: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Support for proxied #GInetSocketAddress. + * Finishes setting a display name started with + * g_file_set_display_name_async(). + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): a #GFile or %NULL on error. */ /** - * GDBusMessageFlags: - * @G_DBUS_MESSAGE_FLAGS_NONE: No flags set. - * @G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED: A reply is not expected. - * @G_DBUS_MESSAGE_FLAGS_NO_AUTO_START: The bus must not launch an owner for the destination name in response to this message. + * g_file_start_mountable: + * @file: input #GFile. + * @flags: flags affecting the operation + * @start_operation: a #GMountOperation, or %NULL to avoid user interaction. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. + * @user_data: the data to pass to callback function * - * Message flags used in #GDBusMessage. + * Starts a file of type G_FILE_TYPE_MOUNTABLE. + * Using @start_operation, you can request callbacks when, for instance, + * passwords are needed during authentication. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * When the operation is finished, @callback will be called. You can then call + * g_file_mount_mountable_finish() to get the result of the operation. * - * Since: 2.26 + * Since: 2.22 */ /** - * G_PROXY_RESOLVER_EXTENSION_POINT_NAME: + * g_file_start_mountable_finish: + * @file: input #GFile. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * Extension point for proxy resolving functionality. - * See <link linkend="extending-gio">Extending GIO</link>. + * Finishes a start operation. See g_file_start_mountable() for details. + * Finish an asynchronous start operation that was started + * with g_file_start_mountable(). + * otherwise. + * + * Returns: %TRUE if the operation finished successfully. %FALSE + * Since: 2.22 */ /** - * G_VALUE_HOLDS_FLAGS: - * @value: a valid #GValue structure + * g_file_stop_mountable: + * @file: input #GFile. + * @flags: flags affecting the operation + * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. + * @user_data: the data to pass to callback function * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. + * Stops a file of type G_FILE_TYPE_MOUNTABLE. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * When the operation is finished, @callback will be called. You can then call + * g_file_stop_mountable_finish() to get the result of the operation. * - * Returns: %TRUE on success. + * Since: 2.22 */ /** - * GClassFinalizeFunc: - * @g_class: The #GTypeClass structure to finalize. - * @class_data: The @class_data member supplied via the #GTypeInfo structure. + * g_file_stop_mountable_finish: + * @file: input #GFile. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * A callback function used by the type system to finalize a class. - * This function is rarely needed, as dynamically allocated class resources - * should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). - * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo - * structure of a static type is invalid, because classes of static types - * will never be finalized (they are artificially kept alive when their - * reference count drops to zero). + * Finishes an stop operation, see g_file_stop_mountable() for details. + * Finish an asynchronous stop operation that was started + * with g_file_stop_mountable(). + * otherwise. + * + * Returns: %TRUE if the operation finished successfully. %FALSE + * Since: 2.22 */ /** - * GDBusInterfaceSetPropertyFunc: - * @connection: A #GDBusConnection. - * @sender: The unique bus name of the remote caller. - * @object_path: The object path that the method was invoked on. - * @interface_name: The D-Bus interface name for the property. - * @property_name: The name of the property to get the value of. - * @value: The value to set the property to. - * @error: Return location for error. - * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object(). + * g_file_supports_thread_contexts: + * @file: a #GFile. * - * The type of the @set_property function in #GDBusInterfaceVTable. + * Checks if @file supports <link + * linkend="g-main-context-push-thread-default-context">thread-default + * contexts</link>. If this returns %FALSE, you cannot perform + * asynchronous operations on @file in a thread that has a + * thread-default context. * - * Returns: %TRUE if the property was set to @value, %FALSE if @error is set. - * Since: 2.26 + * Returns: Whether or not @file supports thread-default contexts. + * Since: 2.22 */ /** - * GWin32InputStream:handle: + * g_file_trash: + * @file: #GFile to send to trash. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError, or %NULL * - * The handle that the stream reads from. + * Sends @file to the "Trashcan", if possible. This is similar to + * deleting it, but the user can recover it before emptying the trashcan. + * Not all file systems support trashing, so this call can return the + * %G_IO_ERROR_NOT_SUPPORTED error. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Since: 2.26 + * Returns: %TRUE on successful trash, %FALSE otherwise. */ /** - * GDriveStartStopType: - * @G_DRIVE_START_STOP_TYPE_UNKNOWN: Unknown or drive doesn't support start/stop. - * @G_DRIVE_START_STOP_TYPE_SHUTDOWN: The stop method will physically shut down the drive and e.g. power down the port the drive is attached to. - * @G_DRIVE_START_STOP_TYPE_NETWORK: The start/stop methods are used for connecting/disconnect to the drive over the network. - * @G_DRIVE_START_STOP_TYPE_MULTIDISK: The start/stop methods will assemble/disassemble a virtual drive from several physical drives. - * @G_DRIVE_START_STOP_TYPE_PASSWORD: The start/stop methods will unlock/lock the disk (for example using the ATA <quote>SECURITY UNLOCK DEVICE</quote> command) + * g_file_unmount_mountable: + * @file: input #GFile. + * @flags: flags affecting the operation + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. + * @user_data: (closure): the data to pass to callback function * - * Enumeration describing how a drive can be started/stopped. + * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * When the operation is finished, @callback will be called. You can then call + * g_file_unmount_mountable_finish() to get the result of the operation. * - * Since: 2.22 + * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead. */ /** - * GDBusServer: + * g_file_unmount_mountable_finish: + * @file: input #GFile. + * @result: a #GAsyncResult. + * @error: a #GError, or %NULL * - * The #GDBusServer structure contains only private data and - * should only be accessed using the provided API. + * Finishes an unmount operation, see g_file_unmount_mountable() for details. + * Finish an asynchronous unmount operation that was started + * with g_file_unmount_mountable(). + * otherwise. * - * Since: 2.26 + * Returns: %TRUE if the operation finished successfully. %FALSE + * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead. */ /** - * g_win32_output_stream_get_close_handle: - * @stream: a #GWin32OutputStream + * g_file_unmount_mountable_with_operation: + * @file: input #GFile. + * @flags: flags affecting the operation + * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. + * @user_data: (closure): the data to pass to callback function * - * Returns whether the handle of @stream will be closed when the - * stream is closed. + * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * When the operation is finished, @callback will be called. You can then call + * g_file_unmount_mountable_finish() to get the result of the operation. * - * Returns: %TRUE if the handle is closed when done - * Since: 2.26 + * Since: 2.22 */ /** - * g_file_eject_mountable_with_operation_finish: + * g_file_unmount_mountable_with_operation_finish: * @file: input #GFile. * @result: a #GAsyncResult. * @error: a #GError, or %NULL * - * Finishes an asynchronous eject operation started by - * g_file_eject_mountable_with_operation(). + * Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details. + * Finish an asynchronous unmount operation that was started + * with g_file_unmount_mountable_with_operation(). * otherwise. * - * Returns: %TRUE if the @file was ejected successfully. %FALSE + * Returns: %TRUE if the operation finished successfully. %FALSE * Since: 2.22 */ /** - * g_socket_client_set_family: - * @client: a #GSocketClient. - * @family: a #GSocketFamily + * g_filename_completer_get_completion_suffix: + * @completer: the filename completer. + * @initial_text: text to be completed. * - * Sets the socket family of the socket client. - * If this is set to something other than %G_SOCKET_FAMILY_INVALID - * then the sockets created by this object will be of the specified - * family. - * This might be useful for instance if you want to force the local - * connection to be an ipv4 socket, even though the address might - * be an ipv6 mapped to ipv4 address. + * Obtains a completion for @initial_text from @completer. + * This string is not owned by GIO, so remember to g_free() it + * when finished. * - * Since: 2.22 + * Returns: a completed string, or %NULL if no completion exists. */ /** - * g_vfs_parse_name: - * @vfs: a #GVfs. - * @parse_name: a string to be parsed by the VFS module. + * g_filename_completer_get_completions: + * @completer: the filename completer. + * @initial_text: text to be completed. * - * This operation never fails, but the returned object might - * not support any I/O operations if the @parse_name cannot - * be parsed by the #GVfs module. - * Free the returned object with g_object_unref(). + * Gets an array of completion strings for a given initial text. + * This array must be freed by g_strfreev() when finished. * - * Returns: (transfer full): a #GFile for the given @parse_name. + * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. */ /** - * g_application_command_line_get_environ: - * @cmdline: a #GApplicationCommandLine + * g_filename_completer_new: * - * Gets the contents of the 'environ' variable of the command line - * invocation, as would be returned by g_get_environ(). The strings may - * contain non-utf8 data. - * The remote application usually does not send an environment. Use - * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag - * set it is possible that the environment is still not available (due - * to invocation messages from other applications). - * The return value should not be modified or freed and is valid for as - * long as @cmdline exists. - * strings, or %NULL if they were not sent + * Creates a new filename completer. * - * Returns: (array zero-terminated=1) (transfer none): the environment - * Since: 2.28 + * Returns: a #GFilenameCompleter. */ /** - * GSocketServiceClass: - * @incomming: signal emitted when new connections are accepted + * g_filename_completer_set_dirs_only: + * @completer: the filename completer. + * @dirs_only: a #gboolean. * + * If @dirs_only is %TRUE, @completer will only + * complete directory names, and not file names. + */ + + +/** + * g_filter_input_stream_get_base_stream: + * @stream: a #GFilterInputStream. * + * Gets the base stream for the filter stream. + * + * Returns: (transfer none): a #GInputStream. */ /** - * g_srv_target_free: - * @target: a #GSrvTarget + * g_filter_input_stream_get_close_base_stream: + * @stream: a #GFilterInputStream. * - * Frees @target + * Returns whether the base stream will be closed when @stream is + * closed. * - * Since: 2.22 + * Returns: %TRUE if the base stream will be closed. */ /** - * GThemedIcon: + * g_filter_input_stream_set_close_base_stream: + * @stream: a #GFilterInputStream. + * @close_base: %TRUE to close the base stream. * - * An implementation of #GIcon for themed icons. + * Sets whether the base stream will be closed when @stream is closed. */ /** - * GConverterResult: - * @G_CONVERTER_ERROR: There was an error during conversion. - * @G_CONVERTER_CONVERTED: Some data was consumed or produced - * @G_CONVERTER_FINISHED: The conversion is finished - * @G_CONVERTER_FLUSHED: Flushing is finished + * g_filter_output_stream_get_base_stream: + * @stream: a #GFilterOutputStream. * - * Results returned from g_converter_convert(). + * Gets the base stream for the filter stream. * - * Since: 2.24 + * Returns: (transfer none): a #GOutputStream. */ /** - * g_content_type_guess_for_tree: - * @root: the root of the tree to guess a type for + * g_filter_output_stream_get_close_base_stream: + * @stream: a #GFilterOutputStream. * - * Tries to guess the type of the tree with root @root, by - * looking at the files it contains. The result is an array - * of content types, with the best guess coming first. - * The types returned all have the form x-content/foo, e.g. - * x-content/audio-cdda (for audio CDs) or x-content/image-dcf - * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> - * specification for more on x-content types. - * This function is useful in the implementation of - * g_mount_guess_content_type(). - * array of zero or more content types, or %NULL. Free with g_strfreev() + * Returns whether the base stream will be closed when @stream is + * closed. * - * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated - * Since: 2.18 + * Returns: %TRUE if the base stream will be closed. */ /** - * g_drive_eject_with_operation_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_filter_output_stream_set_close_base_stream: + * @stream: a #GFilterOutputStream. + * @close_base: %TRUE to close the base stream. * - * Finishes ejecting a drive. If any errors occurred during the operation, + * Sets whether the base stream will be closed when @stream is closed. + */ + + +/** + * g_hash_table_freeze: + * @hash_table: a #GHashTable * - * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise. - * Since: 2.22 + * This function is deprecated and will be removed in the next major + * release of GLib. It does nothing. */ /** - * g_file_load_contents_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @contents: (out) (transfer full): a location to place the contents of the file. - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed - * @error: a #GError, or %NULL + * g_hash_table_thaw: + * @hash_table: a #GHashTable * - * Finishes an asynchronous load of the @file's contents. - * The contents are placed in @contents, and @length is set to the - * size of the @contents string. The @content should be freed with - * g_free() when no longer needed. If @etag_out is present, it will be - * set to the new entity tag for the @file. - * present, it will be set appropriately. + * This function is deprecated and will be removed in the next major + * release of GLib. It does nothing. + */ + + +/** + * g_icon_equal: + * @icon1: pointer to the first #GIcon. + * @icon2: pointer to the second #GIcon. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is + * Checks if two icons are equal. + * + * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. */ /** - * g_tls_backend_get_client_connection_type: - * @backend: the #GTlsBackend + * g_icon_hash: + * @icon: #gconstpointer to an icon object. * - * Gets the #GType of @backend's #GTlsClientConnection implementation. - * implementation. + * Gets a hash for an icon. + * use in a #GHashTable or similar data structure. * - * Returns: the #GType of @backend's #GTlsClientConnection - * Since: 2.28 + * Virtual: hash + * Returns: a #guint containing a hash for the @icon, suitable for */ /** - * G_DATALIST_FLAGS_MASK: + * g_icon_new_for_string: + * @str: A string obtained via g_icon_to_string(). + * @error: Return location for error. * - * A bitmask that restricts the possible flags passed to - * g_datalist_set_flags(). Passing a flags value where - * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. + * Generate a #GIcon instance from @str. This function can fail if + * If your application or library provides one or more #GIcon + * implementations you need to ensure that each #GType is registered + * with the type system prior to calling g_icon_new_for_string(). + * interface or %NULL if @error is set. + * + * Returns: (transfer full): An object implementing the #GIcon + * Since: 2.20 */ /** - * g_dbus_address_get_stream_sync: - * @address: A valid D-Bus address. - * @out_guid: %NULL or return location to store the GUID extracted from @address, if any. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * g_icon_to_string: + * @icon: a #GIcon. * - * Synchronously connects to an endpoint specified by @address and - * sets up the connection so it is in a state to run the client-side - * of the D-Bus authentication conversation. - * This is a synchronous failable function. See - * g_dbus_address_get_stream() for the asynchronous version. + * Generates a textual representation of @icon that can be used for + * serialization such as when passing @icon to a different process or + * saving it to persistent storage. Use g_icon_new_for_string() to + * get @icon back from the returned string. + * The encoding of the returned string is proprietary to #GIcon except + * in the following two cases + * <itemizedlist> + * <listitem><para> + * If @icon is a #GFileIcon, the returned string is a native path + * (such as <literal>/path/to/my icon.png</literal>) 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 <literal>sftp://path/to/my%%20icon.png</literal>). + * </para></listitem> + * <listitem><para> + * If @icon is a #GThemedIcon with exactly one name, the encoding is + * simply the name (such as <literal>network-server</literal>). + * </para></listitem> + * </itemizedlist> + * be serialized. Use g_free() to free. * - * Returns: (transfer full): A #GIOStream or %NULL if @error is set. - * Since: 2.26 + * Virtual: to_tokens + * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't + * Since: 2.20 */ /** - * g_application_command_line_set_exit_status: - * @cmdline: a #GApplicationCommandLine - * @exit_status: the exit status + * g_inet_address_get_family: + * @address: a #GInetAddress * - * Sets the exit status that will be used when the invoking process - * exits. - * The return value of the #GApplication::command-line signal is - * passed to this function when the handler returns. This is the usual - * way of setting the exit status. - * In the event that you want the remote invocation to continue running - * and want to decide on the exit status in the future, you can use this - * call. For the case of a remote invocation, the remote process will - * typically exit when the last reference is dropped on @cmdline. The - * exit status of the remote process will be equal to the last value - * that was set with this function. - * In the case that the commandline invocation is local, the situation - * is slightly more complicated. If the commandline invocation results - * increased to a non-zero value) then the application is considered to - * have been 'successful' in a certain sense, and the exit status is - * always zero. If the application use count is zero, though, the exit - * status of the local #GApplicationCommandLine is used. + * Gets @address's family * - * In the mainloop running (ie: because the use-count of the application - * Since: 2.28 + * Returns: @address's family + * Since: 2.22 */ /** - * G_INITIALLY_UNOWNED_CLASS: - * @class: a valid #GInitiallyUnownedClass + * g_inet_address_get_is_any: + * @address: a #GInetAddress * - * Casts a derived #GInitiallyUnownedClass structure into a - * #GInitiallyUnownedClass structure. + * Tests whether @address is the "any" address for its family. + * + * Returns: %TRUE if @address is the "any" address for its family. + * Since: 2.22 */ /** - * GDBusConnection:authentication-observer: + * g_inet_address_get_is_link_local: + * @address: a #GInetAddress * - * A #GDBusAuthObserver object to assist in the authentication process or %NULL. + * Tests whether @address is a link-local address (that is, if it + * identifies a host on a local network that is not connected to the + * Internet). * - * Since: 2.26 + * Returns: %TRUE if @address is a link-local address. + * Since: 2.22 */ /** - * g_zlib_compressor_get_file_info: - * @compressor: a #GZlibCompressor + * g_inet_address_get_is_loopback: + * @address: a #GInetAddress * - * Returns the #GZlibCompressor:file-info property. + * Tests whether @address is the loopback address for its family. * - * Returns: (transfer none): a #GFileInfo, or %NULL - * Since: 2.26 + * Returns: %TRUE if @address is the loopback address for its family. + * Since: 2.22 */ /** - * GMemoryOutputStream:size: + * g_inet_address_get_is_mc_global: + * @address: a #GInetAddress * - * Current size of the data buffer. + * Tests whether @address is a global multicast address. * - * Since: 2.24 + * Returns: %TRUE if @address is a global multicast address. + * Since: 2.22 */ /** - * G_VALUE_HOLDS_LONG: - * @value: a valid #GValue structure + * g_inet_address_get_is_mc_link_local: + * @address: a #GInetAddress * - * Checks whether the given #GValue can hold values of type %G_TYPE_LONG. + * Tests whether @address is a link-local multicast address. * - * Returns: %TRUE on success. + * Returns: %TRUE if @address is a link-local multicast address. + * Since: 2.22 */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE: + * g_inet_address_get_is_mc_node_local: + * @address: a #GInetAddress * - * A key in the "mountable" namespace for getting the unix device file. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * Tests whether @address is a node-local multicast address. * + * Returns: %TRUE if @address is a node-local multicast address. * Since: 2.22 */ /** - * GParamSpec: - * @g_type_instance: private #GTypeInstance portion - * @name: name of this parameter - * @flags: #GParamFlags flags for this parameter - * @value_type: the #GValue type for this parameter - * @owner_type: #GType type that uses (introduces) this parameter + * g_inet_address_get_is_mc_org_local: + * @address: a #GInetAddress * - * All other fields of the <structname>GParamSpec</structname> struct are private and - * should not be used directly. + * Tests whether @address is an organization-local multicast address. + * + * Returns: %TRUE if @address is an organization-local multicast address. + * Since: 2.22 */ /** - * GApplication::command-line: - * @application: the application - * @command_line: a #GApplicationCommandLine representing the passed commandline + * g_inet_address_get_is_mc_site_local: + * @address: a #GInetAddress * - * The ::command-line signal is emitted on the primary instance when - * a commandline is not handled locally. See g_application_run() for - * more information. + * Tests whether @address is a site-local multicast address. + * + * Returns: %TRUE if @address is a site-local multicast address. + * Since: 2.22 */ /** - * GObjectFinalizeFunc: - * @object: the #GObject being finalized + * g_inet_address_get_is_multicast: + * @address: a #GInetAddress * - * The type of the @finalize function of #GObjectClass. + * Tests whether @address is a multicast address. + * + * Returns: %TRUE if @address is a multicast address. + * Since: 2.22 */ /** - * g_socket_client_connect_finish: - * @client: a #GSocketClient. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_inet_address_get_is_site_local: + * @address: a #GInetAddress * - * Finishes an async connect operation. See g_socket_client_connect_async() + * Tests whether @address is a site-local address such as 10.0.0.1 + * (that is, the address identifies a host on a local network that can + * not be reached directly from the Internet, but which may have + * outgoing Internet connectivity via a NAT or firewall). * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Returns: %TRUE if @address is a site-local address. * Since: 2.22 */ /** - * g_file_query_file_type: - * @file: input #GFile. - * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info(). - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * g_inet_address_get_native_size: + * @address: a #GInetAddress * - * Utility function to inspect the #GFileType of a file. This is - * implemented using g_file_query_info() and as such does blocking I/O. - * The primary use case of this method is to check if a file is a regular file, - * directory, or symlink. - * does not exist + * Gets the size of the native raw binary address for @address. This + * is the size of the data that you get from g_inet_address_to_bytes(). * - * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file - * Since: 2.18 + * Returns: the number of bytes used for the native version of @address. + * Since: 2.22 */ /** - * g_app_info_launch_uris: - * @appinfo: a #GAppInfo - * @uris: (element-type utf8): a #GList containing URIs to launch. - * @launch_context: (allow-none): a #GAppLaunchContext or %NULL - * @error: a #GError + * g_inet_address_new_any: + * @family: the address family * - * Launches the application. Passes @uris to the launched application - * as arguments, using the optional @launch_context to get information - * about the details of the launcher (like what screen it is on). - * On error, @error will be set accordingly. - * To lauch the application without arguments pass a %NULL @uris list. - * Note that even if the launch is successful the application launched - * can fail to start if it runs into problems during startup. There is - * no way to detect this. + * Creates a #GInetAddress for the "any" address (unassigned/"don't + * care") for @family. + * for @family. * - * Returns: %TRUE on successful launch, %FALSE otherwise. + * Returns: a new #GInetAddress corresponding to the "any" address + * Since: 2.22 */ /** - * GDBusProxy:g-interface-info: + * g_inet_address_new_from_bytes: + * @bytes: raw address data + * @family: the address family of @bytes * - * Ensure that interactions with this proxy conform to the given - * interface. For example, when completing a method call, if the - * type signature of the message isn't what's expected, the given - * #GError is set. Signals that have a type signature mismatch are - * simply dropped. + * Creates a new #GInetAddress from the given @family and @bytes. + * %G_INET_ADDRESS_IPV6. * - * Since: 2.26 + * Returns: a new #GInetAddress corresponding to @family and @bytes. + * Since: 2.22 */ /** - * GApplicationCommandLine: + * g_inet_address_new_from_string: + * @string: a string representation of an IP address * - * The <structname>GApplicationCommandLine</structname> structure contains private - * data and should only be accessed using the provided API + * Parses @string as an IP address and creates a new #GInetAddress. * - * Since: 2.26 + * Returns: a new #GInetAddress corresponding to @string, or %NULL if + * Since: 2.22 */ /** - * GTlsServerConnection:authentication-mode: + * g_inet_address_new_loopback: + * @family: the address family * - * The #GTlsAuthenticationMode for the server. This can be changed - * before calling g_tls_connection_handshake() if you want to - * rehandshake with a different mode from the initial handshake. + * Creates a #GInetAddress for the loopback address for @family. + * for @family. * - * Since: 2.28 + * Returns: a new #GInetAddress corresponding to the loopback address + * Since: 2.22 */ /** - * G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW: + * g_inet_address_to_bytes: (skip) + * @address: a #GInetAddress * - * A key in the "filesystem" namespace for hinting a file manager - * application whether it should preview (e.g. thumbnail) files on the - * file system. The value for this key contain a - * #GFilesystemPreviewType. + * Gets the raw binary address data from @address. + * which should not be modified, stored, or freed. The size of this + * array can be gotten with g_inet_address_get_native_size(). + * + * Returns: a pointer to an internal array of the bytes in @address, + * Since: 2.22 */ /** - * g_app_info_set_as_last_used_for_type: - * @appinfo: a #GAppInfo. - * @content_type: the content type. - * @error: a #GError. + * g_inet_address_to_string: + * @address: a #GInetAddress * - * Sets the application as the last used application for a given type. - * This will make the application appear as first in the list returned by - * #g_app_info_get_recommended_for_type, regardless of the default application - * for that content type. + * Converts @address to string form. + * freed after use. * - * Returns: %TRUE on success, %FALSE on error. + * Returns: a representation of @address as a string, which should be + * Since: 2.22 */ /** - * g_win32_input_stream_new: - * @handle: a Win32 file handle - * @close_fd: %TRUE to close the handle when done + * g_inet_socket_address_get_address: + * @address: a #GInetSocketAddress * - * Creates a new #GWin32InputStream for the given @fd. - * If @close_handle is %TRUE, the handle will be closed - * when the stream is closed. - * Note that "handle" here means a Win32 HANDLE, not a "file descriptor" - * as used in the Windows C libraries. + * Gets @address's #GInetAddress. + * g_object_ref()'d if it will be stored * - * Returns: a new #GWin32InputStream + * Returns: (transfer none): the #GInetAddress for @address, which must be + * Since: 2.22 */ /** - * g_themed_icon_new_from_names: - * @iconnames: (array length=len): an array of strings containing icon names. - * @len: the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated + * g_inet_socket_address_get_port: + * @address: a #GInetSocketAddress * - * Creates a new themed icon for @iconnames. + * Gets @address's port. * - * Returns: (transfer full): a new #GThemedIcon + * Returns: the port for @address + * Since: 2.22 */ /** - * GFileType: - * @G_FILE_TYPE_UNKNOWN: File's type is unknown. - * @G_FILE_TYPE_REGULAR: File handle represents a regular file. - * @G_FILE_TYPE_DIRECTORY: File handle represents a directory. - * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link (Unix systems). - * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, block device, or character device. - * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems). - * @G_FILE_TYPE_MOUNTABLE: File is a mountable location. + * g_inet_socket_address_new: + * @address: a #GInetAddress + * @port: a port number * - * Indicates the file's on-disk type. + * Creates a new #GInetSocketAddress for @address and @port. + * + * Returns: a new #GInetSocketAddress + * Since: 2.22 */ /** - * GMountOperation::reply: - * @op: a #GMountOperation. - * @result: a #GMountOperationResult indicating how the request was handled + * g_initable_init: + * @initable: a #GInitable. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Emitted when the user has replied to the mount operation. + * Initializes the object implementing the interface. This must be + * done before any real use of the object after initial construction. + * Implementations may also support cancellation. If @cancellable is not %NULL, + * then initialization can be cancelled by triggering the cancellable object + * from another thread. If the operation was cancelled, the error + * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and + * the object doesn't support cancellable initialization the error + * %G_IO_ERROR_NOT_SUPPORTED will be returned. + * If this function is not called, or returns with an error then all + * operations on the object should fail, generally returning the + * error %G_IO_ERROR_NOT_INITIALIZED. + * Implementations of this method must be idempotent, i.e. multiple calls + * to this function with the same argument should return the same results. + * Only the first call initializes the object, further calls return the result + * of the first call. This is so that its safe to implement the singleton + * pattern in the GObject constructor function. + * return %FALSE and set @error appropriately if present. + * + * Returns: %TRUE if successful. If an error has occurred, this function will + * Since: 2.22 */ /** - * g_dbus_method_info_unref: - * @info: A #GDBusMethodInfo. + * g_initable_new: + * @object_type: a #GType supporting #GInitable. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @error: a #GError location to store the error occuring, or %NULL to ignore. + * @first_property_name: the name of the first property, or %NULL if no properties + * @...: the value if the first property, followed by and other property value pairs, and ended by %NULL. * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. + * Helper function for constructing #GInitiable object. This is + * similar to g_object_new() but also initializes the object + * and returns %NULL, setting an error on failure. * - * Since: 2.26 + * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Since: 2.22 */ @@ -23701,1414 +23061,1451 @@ /** - * g_socket_accept: - * @socket: a #GSocket. - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_initable_newv: + * @object_type: a #GType supporting #GInitable. + * @n_parameters: the number of parameters in @parameters + * @parameters: the parameters to use to construct the object + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Accept incoming connections on a connection-based socket. This removes - * the first outstanding connection request from the listening socket and - * creates a #GSocket object for it. - * The @socket must be bound to a local address with g_socket_bind() and - * must be listening for incoming connections (g_socket_listen()). - * If there are no outstanding connections then the operation will block - * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. - * To be notified of an incoming connection, wait for the %G_IO_IN condition. - * Free the returned object with g_object_unref(). + * Helper function for constructing #GInitiable object. This is + * similar to g_object_newv() but also initializes the object + * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a new #GSocket, or %NULL on error. + * Returns: (transfer full): a newly allocated #GObject, or %NULL on error * Since: 2.22 */ /** - * g_socket_address_get_native_size: - * @address: a #GSocketAddress - * - * Gets the size of @address's native <type>struct sockaddr</type>. - * You can use this to allocate memory to pass to - * g_socket_address_to_native(). + * g_input_stream_clear_pending: + * @stream: input stream * - * Returns: the size of the native <type>struct sockaddr</type> that - * Since: 2.22 + * Clears the pending flag on @stream. */ /** - * g_file_stop_mountable: - * @file: input #GFile. - * @flags: flags affecting the operation - * @mount_operation: a #GMountOperation, or %NULL to avoid user interaction. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. - * @user_data: the data to pass to callback function + * g_input_stream_close: + * @stream: A #GInputStream. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occuring, or %NULL to ignore * - * Stops a file of type G_FILE_TYPE_MOUNTABLE. - * If @cancellable is not %NULL, then the operation can be cancelled by + * Closes the stream, releasing resources related to it. + * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. + * Closing a stream multiple times will not return an error. + * Streams will be automatically closed when the last reference + * is dropped, but you might want to call this function to make sure + * resources are released as early as possible. + * Some streams might keep the backing store of the stream (e.g. a file descriptor) + * open after the stream is closed. See the documentation for the individual + * stream for details. + * On failure the first error that happened will be reported, but the close + * operation will finish as much as possible. A stream that failed to + * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it + * is important to check and report the error to the user. + * If @cancellable is not NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * When the operation is finished, @callback will be called. You can then call - * g_file_stop_mountable_finish() to get the result of the operation. + * Cancelling a close will still leave the stream closed, but some streams + * can use a faster close that doesn't block to e.g. check errors. * - * Since: 2.22 + * Returns: %TRUE on success, %FALSE on failure */ /** - * GParamSpecOverride: - * - * This is a type of #GParamSpec type that simply redirects operations to - * another paramspec. All operations other than getting or - * setting the value are redirected, including accessing the nick and - * blurb, validating a value, and so forth. See - * g_param_spec_get_redirect_target() for retrieving the overidden - * property. #GParamSpecOverride is used in implementing - * g_object_class_override_property(), and will not be directly useful - * unless you are implementing a new base type similar to GObject. + * g_input_stream_close_async: + * @stream: A #GInputStream. + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: (allow-none): optional cancellable object + * @callback: (scope async): callback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Since: 2.4 + * Requests an asynchronous closes of the stream, releasing resources related to it. + * When the operation is finished @callback will be called. + * You can then call g_input_stream_close_finish() to get the result of the + * operation. + * For behaviour details see g_input_stream_close(). + * The asyncronous methods have a default fallback that uses threads to implement + * asynchronicity, so they are optional for inheriting classes. However, if you + * override one you must override all. */ /** - * g_dbus_signal_info_unref: - * @info: A #GDBusSignalInfo. + * g_input_stream_close_finish: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. + * Finishes closing a stream asynchronously, started from g_input_stream_close_async(). * - * Since: 2.26 + * Returns: %TRUE if the stream was closed successfully. */ /** - * GSettingsGetMapping: - * @value: the #GVariant to map, or %NULL - * @result: (out): the result of the mapping - * @user_data: (closure): the user data that was passed to g_settings_get_mapped() - * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error + * g_input_stream_has_pending: + * @stream: input stream. * - * The type of the function that is used to convert from a value stored - * in a #GSettings to a value that is useful to the application. - * If the value is successfully mapped, the result should be stored at - * is not in the right format) then %FALSE should be returned. - * If @value is %NULL then it means that the mapping function is being - * given a "last chance" to successfully return a valid value. %TRUE - * must be returned in this case. + * Checks if an input stream has pending actions. + * + * Returns: %TRUE if @stream has pending actions. */ /** - * g_file_info_get_modification_time: - * @info: a #GFileInfo. - * @result: a #GTimeVal. + * g_input_stream_is_closed: + * @stream: input stream. * - * Gets the modification time of the current @info and sets it - * in @result. + * Checks if an input stream is closed. + * + * Returns: %TRUE if the stream is closed. */ /** - * g_dbus_proxy_get_name_owner: - * @proxy: A #GDBusProxy. + * g_input_stream_read: + * @stream: a #GInputStream. + * @buffer: 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 + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occuring, or %NULL to ignore * - * The unique name that owns the name that @proxy is for or %NULL if - * no-one currently owns that name. You may connect to the - * #GObject::notify signal to track changes to the - * #GDBusProxy:g-name-owner property. + * Tries to read @count bytes from the stream into the buffer starting at + * If count is zero returns zero and does nothing. A value of @count + * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. + * On success, the number of bytes read into the buffer is returned. + * It is not an error if this is not the same as the requested size, as it + * can happen e.g. near the end of a file. Zero is returned on end of file + * (or if @count is zero), but never otherwise. + * If @cancellable is not NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an + * operation was partially finished when the operation was cancelled the + * partial result will be returned, without an error. + * On error -1 is returned and @error is set accordingly. * - * Returns: The name owner or %NULL if no name owner exists. Free with g_free(). - * Since: 2.26 + * Returns: Number of bytes read, or -1 on error */ /** - * GInetAddress:is-link-local: + * g_input_stream_read_all: + * @stream: a #GInputStream. + * @buffer: 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 + * @bytes_read: (out): location to store the number of bytes that was read from the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occuring, or %NULL to ignore * - * Whether this is a link-local address. - * See g_inet_address_get_is_link_local(). + * Tries to read @count bytes from the stream into the buffer starting at + * This function is similar to g_input_stream_read(), except it tries to + * read as many bytes as requested, only stopping on an error or end of stream. + * On a successful read of @count bytes, or if we reached the end of the + * stream, %TRUE is returned, and @bytes_read is set to the number of bytes + * read into @buffer. + * If there is an error during the operation %FALSE is returned and @error + * is set to indicate the error status, @bytes_read is updated to contain + * the number of bytes read into @buffer before the error occurred. * - * Since: 2.22 + * Returns: %TRUE on success, %FALSE if there was an error */ /** - * g_io_stream_close_async: - * @stream: a #GIOStream - * @io_priority: the io priority of the request - * @cancellable: (allow-none): optional cancellable object + * g_input_stream_read_async: + * @stream: A #GInputStream. + * @buffer: 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 <link linkend="io-priority">I/O priority</link> 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 * - * Requests an asynchronous close of the stream, releasing resources - * related to it. When the operation is finished @callback will be - * called. You can then call g_io_stream_close_finish() to get - * the result of the operation. - * For behaviour details see g_io_stream_close(). - * The asynchronous methods have a default fallback that uses threads - * to implement asynchronicity, so they are optional for inheriting - * classes. However, if you override one you must override all. - * - * Since: 2.22 + * Request an asynchronous read of @count bytes from the stream into the buffer + * starting at @buffer. When the operation is finished @callback will be called. + * You can then call g_input_stream_read_finish() to get the result of the + * operation. + * During an async request no other sync and async calls are allowed on @stream, and will + * result in %G_IO_ERROR_PENDING errors. + * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. + * On success, the number of bytes read into the buffer will be passed to the + * callback. It is not an error if this is not the same as the requested size, as it + * can happen e.g. near the end of a file, but generally we try to read + * as many bytes as requested. Zero is returned on end of file + * (or if @count is zero), but never otherwise. + * Any outstanding i/o request with higher priority (lower numerical value) will + * be executed before an outstanding request with lower priority. Default + * priority is %G_PRIORITY_DEFAULT. + * The asyncronous methods have a default fallback that uses threads to implement + * asynchronicity, so they are optional for inheriting classes. However, if you + * override one you must override all. */ /** - * GVolumeMonitor::drive-eject-button: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: the drive where the eject button was pressed + * g_input_stream_read_finish: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Emitted when the eject button is pressed on @drive. + * Finishes an asynchronous stream read operation. * - * Since: 2.18 + * Returns: number of bytes read in, or -1 on error. */ /** - * G_PARAM_SPEC_GET_CLASS: - * @pspec: a valid #GParamSpec + * g_input_stream_set_pending: + * @stream: input stream + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Retrieves the #GParamSpecClass of a #GParamSpec. - */ - - -/** - * SECTION:gresolve: - * @short_description: Asynchronous and cancellable DNS resolver - * @include: gio/gio.h + * Sets @stream to have actions pending. If the pending flag is + * already set or @stream is closed, it will return %FALSE and set * - * #GResolver provides cancellable synchronous and asynchronous DNS - * resolution, for hostnames (g_resolver_lookup_by_address(), - * g_resolver_lookup_by_name() and their async variants) and SRV - * (service) records (g_resolver_lookup_service()). - * #GNetworkAddress and #GNetworkService provide wrappers around - * #GResolver functionality that also implement #GSocketConnectable, - * making it easy to connect to a remote host/service. + * Returns: %TRUE if pending was previously unset and is now set. */ /** - * g_action_activate: - * @action: a #GAction - * @parameter: (allow-none): the parameter to the activation + * g_input_stream_skip: + * @stream: a #GInputStream. + * @count: the number of bytes that will be skipped from the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occuring, or %NULL to ignore * - * Activates the action. - * the parameter type given at construction time). If the parameter - * type was %NULL then @parameter must also be %NULL. + * Tries to skip @count bytes from the stream. Will block during the operation. + * This is identical to g_input_stream_read(), from a behaviour standpoint, + * but the bytes that are skipped are not returned to the user. Some + * streams have an implementation that is more efficient than reading the data. + * This function is optional for inherited classes, as the default implementation + * emulates it using read. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an + * operation was partially finished when the operation was cancelled the + * partial result will be returned, without an error. * - * Since: 2.28 + * Returns: Number of bytes skipped, or -1 on error */ /** - * g_dbus_proxy_get_interface_name: - * @proxy: A #GDBusProxy. - * - * Gets the D-Bus interface name @proxy is for. + * g_input_stream_skip_async: + * @stream: A #GInputStream. + * @count: the number of bytes that will be skipped from the stream + * @io_priority: the <link linkend="io-priority">I/O priority</link> 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 * - * Returns: A string owned by @proxy. Do not free. - * Since: 2.26 + * Request an asynchronous skip of @count bytes from the stream. + * When the operation is finished @callback will be called. + * You can then call g_input_stream_skip_finish() to get the result + * of the operation. + * During an async request no other sync and async calls are allowed, + * and will result in %G_IO_ERROR_PENDING errors. + * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. + * On success, the number of bytes skipped will be passed to the callback. + * It is not an error if this is not the same as the requested size, as it + * can happen e.g. near the end of a file, but generally we try to skip + * as many bytes as requested. Zero is returned on end of file + * (or if @count is zero), but never otherwise. + * Any outstanding i/o request with higher priority (lower numerical value) + * will be executed before an outstanding request with lower priority. + * Default priority is %G_PRIORITY_DEFAULT. + * The asynchronous methods have a default fallback that uses threads to + * implement asynchronicity, so they are optional for inheriting classes. + * However, if you override one, you must override all. */ /** - * g_file_info_set_attribute_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a string. + * g_input_stream_skip_finish: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * Finishes a stream skip operation. + * + * Returns: the size of the bytes skipped, or %-1 on error. */ /** - * g_main_run: - * @loop: a #GMainLoop + * g_io_error_from_errno: + * @err_no: Error number as defined in errno.h. * - * Runs a main loop until it stops running. + * Converts errno.h error codes into GIO error codes. * - * Deprecated: 2.2: Use g_main_loop_run() instead + * Returns: #GIOErrorEnum value for the given errno.h error number. */ /** - * g_dbus_proxy_set_default_timeout: - * @proxy: A #GDBusProxy. - * @timeout_msec: Timeout in milliseconds. + * g_io_error_from_win32_error: + * @error_code: Windows error number. * - * Sets the timeout to use if -1 (specifying default timeout) is - * passed as @timeout_msec in the g_dbus_proxy_call() and - * g_dbus_proxy_call_sync() functions. - * See the #GDBusProxy:g-default-timeout property for more details. + * Converts some common error codes into GIO error codes. The + * fallback value G_IO_ERROR_FAILED is returned for error codes not + * handled. * + * Returns: #GIOErrorEnum value for the given error number. * Since: 2.26 */ /** - * GSettings::writable-changed: - * @settings: the object on which the signal was emitted - * @key: the key + * g_io_error_quark: * - * The "writable-changed" signal is emitted when the writability of a - * key has potentially changed. You should call - * g_settings_is_writable() in order to determine the new status. - * This signal supports detailed connections. You can connect to the - * detailed signal "writable-changed::x" in order to only receive - * callbacks when the writability of "x" changes. + * Gets the GIO Error Quark. + * + * Returns: a #GQuark. */ /** - * g_cancellable_reset: - * @cancellable: a #GCancellable object. + * g_io_extension_get_name: + * @extension: a #GIOExtension * - * Resets @cancellable to its uncancelled state. + * Gets the name under which @extension was registered. + * Note that the same type may be registered as extension + * for multiple extension points, under different names. + * + * Returns: the name of @extension. */ /** - * G_TYPE_PARAM_FLOAT: + * g_io_extension_get_priority: + * @extension: a #GIOExtension * - * The #GType of #GParamSpecFloat. + * Gets the priority with which @extension was registered. + * + * Returns: the priority of @extension */ /** - * g_unix_mount_monitor_new: + * g_io_extension_get_type: + * @extension: a #GIOExtension * - * 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. + * Gets the type associated with @extension. * - * Returns: a #GUnixMountMonitor. + * Returns: the type of @extension */ /** - * g_socket_client_set_tls: - * @client: a #GSocketClient. - * @tls: whether to use TLS + * g_io_extension_point_get_extension_by_name: + * @extension_point: a #GIOExtensionPoint + * @name: the name of the extension to get * - * Sets whether @client creates TLS (aka SSL) connections. If @tls is - * %TRUE, @client will wrap its connections in a #GTlsClientConnection - * and perform a TLS handshake when connecting. - * Note that since #GSocketClient must return a #GSocketConnection, - * but #GTlsClientConnection is not a #GSocketConnection, this - * actually wraps the resulting #GTlsClientConnection in a - * #GTcpWrapperConnection when returning it. You can use - * g_tcp_wrapper_connection_get_base_io_stream() on the return value - * to extract the #GTlsClientConnection. + * Finds a #GIOExtension for an extension point by name. + * given name, or %NULL if there is no extension with that name * - * Since: 2.28 + * Returns: (transfer none): the #GIOExtension for @extension_point that has the */ /** - * GMountOperation:username: + * g_io_extension_point_get_extensions: + * @extension_point: a #GIOExtensionPoint * - * The user name that is used for authentication when carrying out - * the mount operation. + * Gets a list of all extensions that implement this extension point. + * The list is sorted by priority, beginning with the highest priority. + * #GIOExtension<!-- -->s. The list is owned by GIO and should not be + * modified. + * + * Returns: (element-type GIOExtension) (transfer none): a #GList of */ /** - * G_IS_PARAM_SPEC_CLASS: - * @pclass: a #GParamSpecClass + * g_io_extension_point_get_required_type: + * @extension_point: a #GIOExtensionPoint * - * Checks whether @pclass "is a" valid #GParamSpecClass structure of type - * %G_TYPE_PARAM or derived. + * Gets the required type for @extension_point. + * or #G_TYPE_INVALID if the extension point has no required type + * + * Returns: the #GType that all implementations must have, */ /** - * g_dbus_annotation_info_ref: - * @info: A #GDBusNodeInfo + * g_io_extension_point_implement: + * @extension_point_name: the name of the extension point + * @type: the #GType to register as extension + * @extension_name: the name for the extension + * @priority: the priority for the extension * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. + * Registers @type as extension for the extension point with name + * If @type has already been registered as an extension for this + * extension point, the existing #GIOExtension object is returned. * - * Returns: The same @info. - * Since: 2.26 + * Returns: a #GIOExtension object for #GType */ /** - * GMarkupParser: - * @start_element: Callback to invoke when the opening tag of an element is seen. - * @end_element: Callback to invoke when the closing tag of an element is seen. Note that this is also called for empty tags like <literal><empty/></literal>. - * @text: Callback to invoke when some text is seen (text is always inside an element). Note that the text of an element may be spread over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also called for the content of CDATA marked sections. - * @passthrough: Callback to invoke for comments, processing instructions and doctype declarations; if you're re-writing the parsed document, write the passthrough text back out in the same position. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also called for CDATA marked sections. - * @error: Callback to invoke when an error occurs. + * g_io_extension_point_lookup: + * @name: the name of the extension point * - * Any of the fields in #GMarkupParser can be %NULL, in which case they - * will be ignored. Except for the @error function, any of these callbacks - * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT, - * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT - * errors are intended to be set from these callbacks. If you set an error - * from a callback, g_markup_parse_context_parse() will report that error - * back to its caller. + * Looks up an existing extension point. + * registered extension point with the given name + * + * Returns: the #GIOExtensionPoint, or %NULL if there is no */ /** - * g_pollable_output_stream_create_source: (skip) - * @stream: a #GPollableOutputStream. - * @cancellable: (allow-none): a #GCancellable, or %NULL + * g_io_extension_point_register: + * @name: The name of the extension point * - * Creates a #GSource that triggers when @stream can be written, or - * source is of the #GPollableSourceFunc type. - * As with g_pollable_output_stream_is_writable(), it is possible that - * the stream may not actually be writable even after the source - * triggers, so you should use g_pollable_output_stream_write_nonblocking() - * rather than g_output_stream_write() from the callback. + * Registers an extension point. + * and should not be freed * - * Returns: (transfer full): a new #GSource - * Since: 2.28 + * Returns: the new #GIOExtensionPoint. This object is owned by GIO */ /** - * g_file_info_set_attribute: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @type: a #GFileAttributeType - * @value_p: pointer to the value + * g_io_extension_point_set_required_type: + * @extension_point: a #GIOExtensionPoint + * @type: the #GType to require * - * Sets the @attribute to contain the given value, if possible. + * Sets the required type for @extension_point to @type. + * All implementations must henceforth have this type. */ /** - * GTypeFlags: - * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type. - * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init(). + * g_io_extension_ref_class: + * @extension: a #GIOExtension * - * Bit masks used to check or determine characteristics of a type. + * Gets a reference to the class for the type that is + * associated with @extension. + * + * Returns: (transfer full): the #GTypeClass for the type of @extension */ /** - * G_FILE_ATTRIBUTE_UNIX_MODE: + * g_io_module_load: + * @module: a #GIOModule. * - * A key in the "unix" namespace for getting the mode of the file - * (e.g. whether the file is a regular file, symlink, etc). See lstat() - * documentation. This attribute is only available for UNIX file systems. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Required API for GIO modules to implement. + * This function is ran after the module has been loaded into GIO, + * to initialize the module. */ /** - * G_TYPE_UINT64: + * g_io_module_new: + * @filename: filename of the shared library module. * - * The fundamental type corresponding to #guint64. + * Creates a new GIOModule that will load the specific + * shared library when in use. + * or %NULL on error. + * + * Returns: a #GIOModule from given @filename, */ /** - * G_FILE_ATTRIBUTE_TIME_MODIFIED: + * g_io_module_query: * - * A key in the "time" namespace for getting the time the file was last - * modified. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the - * file was modified. + * Optional API for GIO modules to implement. + * Should return a list of all the extension points that may be + * implemented in this module. + * This method will not be called in normal use, however it may be + * called when probing existing modules and recording which extension + * points that this modle is used for. This means we won't have to + * load and initialze this module unless its needed. + * If this function is not implemented by the module the module will + * always be loaded, initialized and then unloaded on application startup + * so that it can register its extension points during init. + * Note that a module need not actually implement all the extension points + * that g_io_module_query returns, since the exact list of extension may + * depend on runtime issues. However all extension points actually implemented + * must be returned by g_io_module_query() (if defined). + * When installing a module that implements g_io_module_query you must + * run gio-querymodules in order to build the cache files required for + * lazy loading. + * extension points of the module. The array must be suitable for + * freeing with g_strfreev(). + * + * Returns: (transfer full): A %NULL-terminated array of strings, listing the supported + * Since: 2.24 */ /** - * GTypePluginCompleteInterfaceInfo: - * @plugin: the #GTypePlugin - * @instance_type: the #GType of an instantiable type to which the interface is added - * @interface_type: the #GType of the interface whose info is completed - * @info: the #GInterfaceInfo to fill in + * g_io_module_unload: + * @module: a #GIOModule. * - * The type of the @complete_interface_info function of #GTypePluginClass. + * Required API for GIO modules to implement. + * This function is ran when the module is being unloaded from GIO, + * to finalize the module. */ /** - * SECTION:gpermissio: - * @title: GPermission - * @short_description: An object representing the permission to perform a certain action + * g_io_modules_load_all_in_directory: + * @dirname: pathname for a directory containing modules to load. * - * A #GPermission represents the status of the caller's permission to - * perform a certain action. - * You can query if the action is currently allowed and if it is - * possible to acquire the permission so that the action will be allowed - * in the future. - * There is also an API to actually acquire the permission and one to - * release it. - * As an example, a #GPermission might represent the ability for the - * user to write to a #GSettings object. This #GPermission object could - * then be used to decide if it is appropriate to show a "Click here to - * unlock" button in a dialog and to provide the mechanism to invoke - * when that button is clicked. + * Loads all the modules in the specified directory. + * If don't require all modules to be initialized (and thus registering + * all gtypes) then you can use g_io_modules_scan_all_in_directory() + * which allows delayed/lazy loading of modules. + * from the directory, + * All the modules are loaded into memory, if you want to + * unload them (enabling on-demand loading) you must call + * g_type_module_unuse() on all the modules. Free the list + * with g_list_free(). + * + * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded */ /** - * GTlsConnection: + * g_io_modules_scan_all_in_directory: + * @dirname: pathname for a directory containing modules to scan. * - * TLS connection. This is an abstract type that will be subclassed by - * a TLS-library-specific subtype. + * Scans all the modules in the specified directory, ensuring that + * any extension point implemented by a module is registered. + * This may not actually load and initialize all the types in each + * module, some modules may be lazily loaded and initialized when + * an extension point it implementes is used with e.g. + * g_io_extension_point_get_extensions() or + * g_io_extension_point_get_extension_by_name(). + * If you need to guarantee that all types are loaded in all the modules, + * use g_io_modules_load_all_in_directory(). * - * Since: 2.28 + * Since: 2.24 */ /** - * g_permission_acquire: - * @permission: a #GPermission instance - * @cancellable: a #GCancellable, or %NULL - * @error: a pointer to a %NULL #GError, or %NULL - * @returns: %TRUE if the permission was successfully acquired - * - * Attempts to acquire the permission represented by @permission. - * The precise method by which this happens depends on the permission - * and the underlying authentication mechanism. A simple example is - * that a dialog may appear asking the user to enter their password. - * You should check with g_permission_get_can_acquire() before calling - * this function. - * If the permission is acquired then %TRUE is returned. Otherwise, - * %FALSE is returned and @error is set appropriately. - * This call is blocking, likely for a very long time (in the case that - * user interaction is required). See g_permission_acquire_async() for - * the non-blocking version. + * g_io_scheduler_cancel_all_jobs: * - * Since: 2.26 + * Cancels all cancellable I/O jobs. + * A job is cancellable if a #GCancellable was passed into + * g_io_scheduler_push_job(). */ /** - * g_file_enumerator_next_files_async: - * @enumerator: a #GFileEnumerator. - * @num_files: the number of file info objects to request - * @io_priority: the <link linkend="gioscheduler">io priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * g_io_scheduler_job_send_to_mainloop: + * @job: a #GIOSchedulerJob + * @func: a #GSourceFunc callback that will be called in the original thread + * @user_data: data to pass to @func + * @notify: a #GDestroyNotify for @user_data, or %NULL * - * Request information for a number of files from the enumerator asynchronously. - * When all i/o for the operation is finished the @callback will be called with - * the requested information. - * The callback can be called with less than @num_files files in case of error - * or at the end of the enumerator. In case of a partial error the callback will - * be called with any succeeding items and no error, and on the next request the - * error will be reported. If a request is cancelled the callback will be called - * with %G_IO_ERROR_CANCELLED. - * During an async request no other sync and async calls are allowed, and will - * result in %G_IO_ERROR_PENDING errors. - * Any outstanding i/o request with higher priority (lower numerical value) will - * be executed before an outstanding request with lower priority. Default - * priority is %G_PRIORITY_DEFAULT. + * Used from an I/O job to send a callback to be run in the thread + * that the job was started from, waiting for the result (and thus + * blocking the I/O job). + * + * Returns: The return value of @func */ /** - * g_file_enumerate_children_async: - * @file: input #GFile. - * @attributes: an attribute query string. - * @flags: a set of #GFileQueryInfoFlags. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function + * g_io_scheduler_job_send_to_mainloop_async: + * @job: a #GIOSchedulerJob + * @func: a #GSourceFunc callback that will be called in the original thread + * @user_data: data to pass to @func + * @notify: a #GDestroyNotify for @user_data, or %NULL * - * Asynchronously gets the requested information about the files in a directory. The result - * is a #GFileEnumerator object that will give out #GFileInfo objects for - * all the files in the directory. - * For more details, see g_file_enumerate_children() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_enumerate_children_finish() to get the result of the operation. + * Used from an I/O job to send a callback to be run asynchronously in + * the thread that the job was started from. The callback will be run + * when the main loop is available, but at that time the I/O job might + * have finished. The return value from the callback is ignored. + * Note that if you are passing the @user_data from g_io_scheduler_push_job() + * on to this function you have to ensure that it is not freed before + * g_io_scheduler_push_job() or by using refcounting for @user_data. */ /** - * g_action_group_action_removed: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group - * - * Emits the #GActionGroup::action-removed signal on @action_group. - * This function should only be called by #GActionGroup implementations. + * g_io_scheduler_push_job: + * @job_func: a #GIOSchedulerJobFunc. + * @user_data: data to pass to @job_func + * @notify: a #GDestroyNotify for @user_data, or %NULL + * @io_priority: the <link linkend="gioscheduler">I/O priority</link> of the request. + * @cancellable: optional #GCancellable object, %NULL to ignore. * - * Since: 2.28 + * Schedules the I/O job to run. + * regardless whether the job was cancelled or has run to completion. + * If @cancellable is not %NULL, it can be used to cancel the I/O job + * by calling g_cancellable_cancel() or by calling + * g_io_scheduler_cancel_all_jobs(). */ /** - * g_file_info_set_file_type: - * @info: a #GFileInfo. - * @type: a #GFileType. + * g_io_stream_clear_pending: + * @stream: a #GIOStream * - * Sets the file type in a #GFileInfo to @type. - * See %G_FILE_ATTRIBUTE_STANDARD_TYPE. + * Clears the pending flag on @stream. + * + * Since: 2.22 */ /** - * g_data_input_stream_read_int16: - * @stream: a given #GDataInputStream. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * g_io_stream_close: + * @stream: a #GIOStream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @error: location to store the error occuring, or %NULL to ignore * - * Reads a 16-bit/2-byte value from @stream. - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - * an error occurred. + * Closes the stream, releasing resources related to it. This will also + * closes the individual input and output streams, if they are not already + * closed. + * Once the stream is closed, all other operations will return + * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not + * return an error. + * Closing a stream will automatically flush any outstanding buffers + * in the stream. + * Streams will be automatically closed when the last reference + * is dropped, but you might want to call this function to make sure + * resources are released as early as possible. + * Some streams might keep the backing store of the stream (e.g. a file + * descriptor) open after the stream is closed. See the documentation for + * the individual stream for details. + * On failure the first error that happened will be reported, but the + * close operation will finish as much as possible. A stream that failed + * to close will still return %G_IO_ERROR_CLOSED for all operations. + * Still, it is important to check and report the error to the user, + * otherwise there might be a loss of data as all data might not be written. + * If @cancellable is not NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Cancelling a close will still leave the stream closed, but some streams + * can use a faster close that doesn't block to e.g. check errors. + * The default implementation of this method just calls close on the + * individual input/output streams. * - * Returns: a signed 16-bit/2-byte value read from @stream or %0 if + * Returns: %TRUE on success, %FALSE on failure + * Since: 2.22 */ /** - * G_TYPE_IS_FLAGS: - * @type: a #GType ID. + * g_io_stream_close_async: + * @stream: a #GIOStream + * @io_priority: the io priority of the request + * @cancellable: (allow-none): optional cancellable object + * @callback: (scope async): callback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Checks whether @type "is a" %G_TYPE_FLAGS. + * Requests an asynchronous close of the stream, releasing resources + * related to it. When the operation is finished @callback will be + * called. You can then call g_io_stream_close_finish() to get + * the result of the operation. + * For behaviour details see g_io_stream_close(). + * The asynchronous methods have a default fallback that uses threads + * to implement asynchronicity, so they are optional for inheriting + * classes. However, if you override one you must override all. * - * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS. + * Since: 2.22 */ /** - * SECTION:gdbusintrospectio: - * @title: D-Bus Introspection Data - * @short_description: Node and interface description data structures - * @include: gio/gio.h + * g_io_stream_close_finish: + * @stream: a #GIOStream + * @result: a #GAsyncResult + * @error: a #GError location to store the error occuring, or %NULL to ignore * - * Various data structures and convenience routines to parse and - * generate D-Bus introspection XML. Introspection information is - * used when registering objects with g_dbus_connection_register_object(). - * The format of D-Bus introspection XML is specified in the - * <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</link>. + * Closes a stream. + * + * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. + * Since: 2.22 */ /** - * G_FILE_ATTRIBUTE_UNIX_BLOCKS: + * g_io_stream_get_input_stream: + * @stream: a #GIOStream * - * A key in the "unix" namespace for getting the number of blocks allocated - * for the file. This attribute is only available for UNIX file systems. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + * Gets the input stream for this object. This is used + * for reading. + * Do not free. + * + * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. + * Since: 2.22 */ /** - * g_srv_target_list_sort: (skip) - * @targets: a #GList of #GSrvTarget + * g_io_stream_get_output_stream: + * @stream: a #GIOStream * - * Sorts @targets in place according to the algorithm in RFC 2782. + * Gets the output stream for this object. This is used for + * writing. + * Do not free. * - * Returns: (transfer full): the head of the sorted list. + * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. * Since: 2.22 */ /** - * G_DEFINE_TYPE_EXTENDED: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * @_f_: #GTypeFlags to pass to g_type_register_static() - * @_C_: Custom code that gets inserted in the *_get_type() function. + * g_io_stream_has_pending: + * @stream: a #GIOStream * - * The most general convenience macro for type implementations, on which - * G_DEFINE_TYPE(), etc are based. - * |[ - * G_DEFINE_TYPE_EXTENDED (GtkGadget, - * gtk_gadget, - * GTK_TYPE_WIDGET, - * 0, - * G_IMPLEMENT_INTERFACE (TYPE_GIZMO, - * gtk_gadget_gizmo_init)); - * ]| - * expands to - * |[ - * static void gtk_gadget_init (GtkGadget *self); - * static void gtk_gadget_class_init (GtkGadgetClass *klass); - * static gpointer gtk_gadget_parent_class = NULL; - * static void gtk_gadget_class_intern_init (gpointer klass) - * { - * gtk_gadget_parent_class = g_type_class_peek_parent (klass); - * gtk_gadget_class_init ((GtkGadgetClass*) klass); - * } - * GType - * gtk_gadget_get_type (void) - * { - * static volatile gsize g_define_type_id__volatile = 0; - * if (g_once_init_enter (&g_define_type_id__volatile)) - * { - * GType g_define_type_id = - * g_type_register_static_simple (GTK_TYPE_WIDGET, - * g_intern_static_string ("GtkGadget"), - * sizeof (GtkGadgetClass), - * (GClassInitFunc) gtk_gadget_class_intern_init, - * sizeof (GtkGadget), - * (GInstanceInitFunc) gtk_gadget_init, - * (GTypeFlags) flags); - * { - * static const GInterfaceInfo g_implement_interface_info = { - * (GInterfaceInitFunc) gtk_gadget_gizmo_init - * }; - * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); - * } - * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); - * } - * return g_define_type_id__volatile; - * } - * ]| - * The only pieces which have to be manually provided are the definitions of - * the instance and class structure and the definitions of the instance and - * class init functions. + * Checks if a stream has pending actions. * - * Since: 2.4 + * Returns: %TRUE if @stream has pending actions. + * Since: 2.22 */ /** - * g_credentials_set_native: - * @credentials: A #GCredentials. - * @native_type: The type of native credentials to set. - * @native: A pointer to native credentials. + * g_io_stream_is_closed: + * @stream: a #GIOStream * - * Copies the native credentials of type @native_type from @native - * into @credentials. - * It is a programming error (which will cause an warning to be - * logged) to use this method if there is no #GCredentials support for - * the OS or if @native_type isn't supported by the OS. + * Checks if a stream is closed. * - * Since: 2.26 + * Returns: %TRUE if the stream is closed. + * Since: 2.22 */ /** - * G_TYPE_PARAM_DOUBLE: + * g_io_stream_set_pending: + * @stream: a #GIOStream + * @error: a #GError location to store the error occuring, or %NULL to ignore * - * The #GType of #GParamSpecDouble. + * Sets @stream to have actions pending. If the pending flag is + * already set or @stream is closed, it will return %FALSE and set + * + * Returns: %TRUE if pending was previously unset and is now set. + * Since: 2.22 */ /** - * GSocketType: - * @G_SOCKET_TYPE_INVALID: Type unknown or wrong - * @G_SOCKET_TYPE_STREAM: Reliable connection-based byte streams (e.g. TCP). - * @G_SOCKET_TYPE_DATAGRAM: Connectionless, unreliable datagram passing. (e.g. UDP) - * @G_SOCKET_TYPE_SEQPACKET: Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP). + * g_io_stream_splice_async: + * @stream1: a #GIOStream. + * @stream2: a #GIOStream. + * @flags: a set of #GIOStreamSpliceFlags. + * @io_priority: the io priority of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. * - * Flags used when creating a #GSocket. Some protocols may not implement - * all the socket types. + * Asyncronously splice the output stream of @stream1 to the input stream of + * When the operation is finished @callback will be called. + * You can then call g_io_stream_splice_finish() to get the + * result of the operation. * - * Since: 2.22 + * Since: 2.28 */ /** - * g_dbus_connection_get_stream: - * @connection: a #GDBusConnection + * g_io_stream_splice_finish: + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Gets the underlying stream used for IO. + * Finishes an asynchronous io stream splice operation. * - * Returns: (transfer none): the stream used for IO - * Since: 2.26 + * Returns: %TRUE on success, %FALSE otherwise. + * Since: 2.28 */ /** - * g_network_service_new: - * @service: the service type to look up (eg, "ldap") - * @protocol: the networking protocol to use for @service (eg, "tcp") - * @domain: the DNS domain to look up the service in + * g_keyfile_settings_backend_new: + * @filename: the filename of the keyfile + * @root_path: the path under which all settings keys appear + * @root_group: (allow-none): the group name corresponding to + * @returns: (transfer full): a keyfile-backed #GSettingsBackend * - * Creates a new #GNetworkService representing the given @service, - * #GSocketConnectable interface to resolve it. + * Creates a keyfile-backed #GSettingsBackend. + * The filename of the keyfile to use is given by @filename. + * All settings read to or written from the backend must fall under the + * path given in @root_path (which must start and end with a slash and + * not contain two consecutive slashes). @root_path may be "/". + * If @root_group is non-%NULL then it specifies the name of the keyfile + * group used for keys that are written directly below @root_path. For + * example, if @root_path is "/apps/example/" and @root_group is + * "toplevel", then settings the key "/apps/example/enabled" to a value + * of %TRUE will cause the following to appear in the keyfile: + * |[ + * [toplevel] + * enabled=true + * ]| + * If @root_group is %NULL then it is not permitted to store keys + * directly below the @root_path. + * the name of the subpath (with the final slash stripped) is used as + * the name of the keyfile group. To continue the example, if + * "/apps/example/profiles/default/font-size" were set to + * 12 then the following would appear in the keyfile: + * |[ + * [profiles/default] + * font-size=12 + * ]| + * The backend will refuse writes (and return writability as being + * %FALSE) for keys outside of @root_path and, in the event that + * Writes will also be refused if the backend detects that it has the + * writable). + * There is no checking done for your key namespace clashing with the + * syntax of the key file format. For example, if you have '[' or ']' + * characters in your path names or '=' in your key names you may be in + * trouble. * - * Returns: (transfer full): a new #GNetworkService - * Since: 2.22 + * For keys not stored directly below @root_path (ie: in a sub-path), + * Inability to rewrite the keyfile (ie: the containing directory is not */ /** - * GApplicationClass: - * @startup: invoked on the primary instance immediately after registration - * @activate: invoked on the primary instance when an activation occurs - * @open: invoked on the primary instance when there are files to open - * @command_line: invoked on the primary instance when a command-line is not handled locally - * @local_command_line: invoked (locally) when the process has been invoked via commandline execution. The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information. - * @before_emit: invoked on the primary instance before 'activate', 'open' or any action invocation - * @after_emit: invoked on the primary instance after 'activate', 'open' or any action invocation - * @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions - * @quit_mainloop: invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested) - * @run_mainloop: invoked on the primary instance from g_application_run() if the use-count is non-zero - * + * 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 occuring, or %NULL to ignore. * + * Loads a loadable icon. For the asynchronous version of this function, + * see g_loadable_icon_load_async(). * - * Since: 2.26 + * Returns: (transfer full): a #GInputStream to read the icon from. */ /** - * GSignalAccumulator: - * @ihint: Signal invocation hint, see #GSignalInvocationHint. - * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission. - * @handler_return: A #GValue holding the return value of the signal handler. - * @data: Callback data that was specified when creating the signal. - * - * The signal accumulator is a special callback function that can be used - * to collect return values of the various callbacks that are called - * during a signal emission. The signal accumulator is specified at signal - * creation time, if it is left %NULL, no accumulation of callback return - * values is performed. The return value of signal emissions is then the - * value returned by the last callback. - * should be aborted. Returning %FALSE means to abort the - * current emission and %TRUE is returned for continuation. + * g_loadable_icon_load_async: + * @icon: a #GLoadableIcon. + * @size: an integer. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Returns: The accumulator function returns whether the signal emission + * Loads an icon asynchronously. To finish this function, see + * g_loadable_icon_load_finish(). For the synchronous, blocking + * version of this function, see g_loadable_icon_load(). */ /** - * g_credentials_new: + * g_loadable_icon_load_finish: + * @icon: a #GLoadableIcon. + * @res: a #GAsyncResult. + * @type: a location to store the type of the loaded icon, %NULL to ignore. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Creates a new #GCredentials object with credentials matching the - * the current process. + * Finishes an asynchronous icon load started in g_loadable_icon_load_async(). * - * Returns: A #GCredentials. Free with g_object_unref(). - * Since: 2.26 + * Returns: (transfer full): a #GInputStream to read the icon from. */ /** - * SECTION:ginitabl: - * @short_description: Failable object initialization interface - * @include: gio/gio.h - * @see_also: #GAsyncInitable + * g_local_vfs_new: * - * #GInitable is implemented by objects that can fail during - * initialization. If an object implements this interface the - * g_initable_init() function must be called as the first thing - * after construction. If g_initable_init() is not called, or if - * it returns an error, all further operations on the object - * should fail, generally with a %G_IO_ERROR_NOT_INITIALIZED error. - * Users of objects implementing this are not intended to use - * the interface method directly, instead it will be used automatically - * in various ways. For C applications you generally just call - * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper. - * This will call g_initable_init() under the cover, returning %NULL and - * setting a %GError on failure. - * For bindings in languages where the native constructor supports - * exceptions the binding could check for objects implemention %GInitable - * during normal construction and automatically initialize them, throwing - * an exception on failure. + * Returns a new #GVfs handle for a local vfs. + * + * Returns: a new #GVfs handle. */ /** - * G_DEFINE_TYPE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. + * g_main_destroy: + * @loop: a #GMainLoop * - * A convenience macro for type implementations, which declares a - * class initialization function, an instance initialization function (see #GTypeInfo for information about - * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines - * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example. + * Frees the memory allocated for the #GMainLoop. * - * Since: 2.4 + * Deprecated: 2.2: Use g_main_loop_unref() instead */ /** - * g_file_info_get_file_type: - * @info: a #GFileInfo. + * g_main_is_running: + * @loop: a #GMainLoop * - * Gets a file's type (whether it is a regular file, symlink, etc). - * This is different from the file's content type, see g_file_info_get_content_type(). + * Checks if the main loop is running. * - * Returns: a #GFileType for the given file. + * Returns: %TRUE if the main loop is running + * Deprecated: 2.2: Use g_main_loop_is_running() instead */ /** - * GFilterInputStream: + * g_main_iteration: + * @may_block: set to %TRUE if it should block (i.e. wait) until an event source becomes ready. It will return after an event source has been processed. If set to %FALSE it will return immediately if no event source is ready to be processed. * - * A base class for all input streams that work on an underlying stream. + * Runs a single iteration for the default #GMainContext. + * + * Returns: %TRUE if more events are pending. + * Deprecated: 2.2: Use g_main_context_iteration() instead. */ /** - * g_dbus_node_info_generate_xml: - * @info: A #GDBusNodeInfo. - * @indent: Indentation level. - * @string_builder: A #GString to to append XML data to. + * g_main_new: + * @is_running: set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_run() will set this to %TRUE anyway. * - * Appends an XML representation of @info (and its children) to @string_builder. - * This function is typically used for generating introspection XML documents at run-time for - * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method. + * Creates a new #GMainLoop for th default main context. * - * Since: 2.26 + * Returns: a new #GMainLoop + * Deprecated: 2.2: Use g_main_loop_new() instead */ /** - * g_dbus_is_interface_name: - * @string: The string to check. + * g_main_pending: * - * Checks if @string is a valid D-Bus interface name. + * Checks if any events are pending for the default #GMainContext + * (i.e. ready to be processed). * - * Returns: %TRUE if valid, %FALSE otherwise. - * Since: 2.26 + * Returns: %TRUE if any events are pending. + * Deprected: 2.2: Use g_main_context_pending() instead. */ /** - * GUnixMountMonitor::mounts-changed: - * @monitor: the object on which the signal is emitted + * g_main_quit: + * @loop: a #GMainLoop * - * Emitted when the unix mounts have changed. + * Stops the #GMainLoop. + * If g_main_run() was called to run the #GMainLoop, it will now return. + * + * Deprecated: 2.2: Use g_main_loop_quit() instead */ /** - * g_dbus_address_get_for_bus_sync: - * @bus_type: A #GBusType. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * g_main_run: + * @loop: a #GMainLoop * - * Synchronously looks up the D-Bus address for the well-known message - * bus instance specified by @bus_type. This may involve using various - * platform specific mechanisms. + * Runs a main loop until it stops running. * - * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set. - * Since: 2.26 + * Deprecated: 2.2: Use g_main_loop_run() instead */ /** - * G_VALUE_HOLDS_PARAM: - * @value: a valid #GValue structure + * g_main_set_poll_func: + * @func: the function to call to poll all file descriptors * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. + * Sets the function to use for the handle polling of file descriptors + * for the default main context. * - * Returns: %TRUE on success. + * Deprecated: 2.2: Use g_main_context_set_poll_func() again */ /** - * G_PARAM_SPEC_STRING: - * @pspec: a valid #GParamSpec instance + * g_memory_input_stream_add_data: + * @stream: a #GMemoryInputStream + * @data: (array length=len) (element-type guint8): input data + * @len: length of the data, may be -1 if @data is a nul-terminated string + * @destroy: (allow-none): function that is called to free @data, or %NULL * - * Casts a #GParamSpec instance into a #GParamSpecString. + * Appends @data to data that can be read from the input stream */ /** - * GInetAddress:is-multicast: + * g_memory_input_stream_new: * - * Whether this is a multicast address. - * See g_inet_address_get_is_multicast(). + * Creates a new empty #GMemoryInputStream. * - * Since: 2.22 + * Returns: a new #GInputStream */ /** - * GPermission: + * g_memory_input_stream_new_from_data: + * @data: (array length=len) (element-type guint8): input data + * @len: length of the data, may be -1 if @data is a nul-terminated string + * @destroy: (allow-none): function that is called to free @data, or %NULL * - * #GPermission is an opaque data structure and can only be accessed - * using the following functions. + * Creates a new #GMemoryInputStream with data in memory of a given size. + * + * Returns: new #GInputStream read from @data of @len bytes. */ /** - * g_filename_completer_new: + * g_memory_output_stream_get_data: + * @ostream: a #GMemoryOutputStream * - * Creates a new filename completer. + * Gets any loaded data from the @ostream. + * Note that the returned pointer may become invalid on the next + * write or truncate operation on the stream. * - * Returns: a #GFilenameCompleter. + * Returns: (transfer none): pointer to the stream's data */ /** - * g_data_output_stream_put_int16: - * @stream: a #GDataOutputStream. - * @data: a #gint16. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_memory_output_stream_get_data_size: + * @ostream: a #GMemoryOutputStream * - * Puts a signed 16-bit integer into the output stream. + * Returns the number of bytes from the start up + * to including the last byte written in the stream + * that has not been truncated away. * - * Returns: %TRUE if @data was successfully added to the @stream. + * Returns: the number of bytes written to the stream + * Since: 2.18 */ /** - * g_io_extension_point_lookup: - * @name: the name of the extension point + * g_memory_output_stream_get_size: + * @ostream: a #GMemoryOutputStream * - * Looks up an existing extension point. - * registered extension point with the given name + * Gets the size of the currently allocated data area (available from + * g_memory_output_stream_get_data()). If the stream isn't + * growable (no realloc was passed to g_memory_output_stream_new()) then + * this is the maximum size of the stream and further writes + * will return %G_IO_ERROR_NO_SPACE. + * Note that for growable streams the returned size may become invalid on + * the next write or truncate operation on the stream. + * If you want the number of bytes currently written to the stream, use + * g_memory_output_stream_get_data_size(). * - * Returns: the #GIOExtensionPoint, or %NULL if there is no + * Returns: the number of bytes allocated for the data buffer */ /** - * g_dbus_connection_send_message_with_reply_sync: - * @connection: A #GDBusConnection. - * @message: A #GDBusMessage. - * @flags: Flags affecting how the message is sent. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @out_serial: Return location for serial number assigned to @message when sending it or %NULL. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * g_memory_output_stream_new: (skip) + * @data: pointer to a chunk of memory to use, or %NULL + * @size: the size of @data + * @realloc_function: a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL + * @destroy_function: a function to be called on @data when the stream is finalized, or %NULL * - * Synchronously sends @message to the peer represented by @connection - * and blocks the calling thread until a reply is received or the - * timeout is reached. See g_dbus_connection_send_message_with_reply() - * for the asynchronous version of this method. - * Unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number - * will be assigned by @connection and set on @message via - * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the - * serial number used will be written to this location prior to - * submitting the message to the underlying transport. - * If @connection is closed then the operation will fail with - * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will - * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, - * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. - * Note that @error is only set if a local in-process error - * occured. That is to say that the returned #GDBusMessage object may - * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use - * g_dbus_message_to_gerror() to transcode this to a #GError. - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. - * Note that @message must be unlocked, unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. + * Creates a new #GMemoryOutputStream. + * If @data is non-%NULL, the stream will use that for its internal storage. + * If @realloc_fn is non-%NULL, it will be used for resizing the internal + * storage when necessary. To construct a fixed-size output stream, + * pass %NULL as @realloc_fn. + * |[ + * /* a stream that can grow */ + * stream = g_memory_output_stream_new (NULL, 0, realloc, free); + * /* another stream that can grow */ + * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); + * /* a fixed-size stream */ + * data = malloc (200); + * stream3 = g_memory_output_stream_new (data, 200, NULL, free); + * ]| * - * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set. - * Since: 2.26 + * Returns: A newly created #GMemoryOutputStream object. */ /** - * GConvertError: - * @G_CONVERT_ERROR_NO_CONVERSION: Conversion between the requested character sets is not supported. - * @G_CONVERT_ERROR_ILLEGAL_SEQUENCE: Invalid byte sequence in conversion input. - * @G_CONVERT_ERROR_FAILED: Conversion failed for some reason. - * @G_CONVERT_ERROR_PARTIAL_INPUT: Partial character sequence at end of input. - * @G_CONVERT_ERROR_BAD_URI: URI is invalid. - * @G_CONVERT_ERROR_NOT_ABSOLUTE_PATH: Pathname is not an absolute path. + * g_memory_output_stream_steal_data: + * @ostream: a #GMemoryOutputStream * - * Error codes returned by character set conversion routines. + * Gets any loaded data from the @ostream. Ownership of the data + * is transferred to the caller; when no longer needed it must be + * freed using the free function set in @ostream's + * #GMemoryOutputStream:destroy-function property. + * + * Returns: (transfer full): the stream's data + * Since: 2.26 */ /** - * GDesktopAppInfo: + * g_mount_can_eject: + * @mount: a #GMount. * - * Information about an installed application from a desktop file. + * Checks if @mount can be eject. + * + * Returns: %TRUE if the @mount can be ejected. */ /** - * GObjectConstructParam: - * @pspec: the #GParamSpec of the construct parameter - * @value: the value to set the parameter to + * g_mount_can_unmount: + * @mount: a #GMount. * - * The <structname>GObjectConstructParam</structname> struct is an auxiliary - * structure used to hand #GParamSpec/#GValue pairs to the @constructor of - * a #GObjectClass. + * Checks if @mount can be mounted. + * + * Returns: %TRUE if the @mount can be unmounted. */ /** - * g_credentials_to_string: - * @credentials: A #GCredentials object. + * g_mount_eject: + * @mount: a #GMount. + * @flags: flags affecting the unmount if required for eject + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * Creates a human-readable textual representation of @credentials - * that can be used in logging and debug messages. The format of the - * returned string may change in future GLib release. + * Ejects a mount. This is an asynchronous operation, and is + * finished by calling g_mount_eject_finish() with the @mount + * and #GAsyncResult data returned in the @callback. * - * Returns: A string that should be freed with g_free(). - * Since: 2.26 + * Deprecated: 2.22: Use g_mount_eject_with_operation() instead. */ /** - * GApplicationFlags: - * @G_APPLICATION_FLAGS_NONE: Default - * @G_APPLICATION_IS_SERVICE: Run as a service. In this mode, registration fails if the service is already running, and the application will stay around for a while when the use count falls to zero. - * @G_APPLICATION_IS_LAUNCHER: Don't try to become the primary instance. - * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in the primary instance) - * @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command line arguments (in the primary instance) - * @G_APPLICATION_SEND_ENVIRONMENT: Send the environment of the launching process to the primary instance + * g_mount_eject_finish: + * @mount: a #GMount. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Flags used to define the behaviour of a #GApplication. + * Finishes ejecting a mount. If any errors occurred during the operation, * - * Since: 2.26 + * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. + * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead. */ /** - * g_data_input_stream_set_byte_order: - * @stream: a given #GDataInputStream. - * @order: a #GDataStreamByteOrder to set. + * g_mount_eject_with_operation: + * @mount: a #GMount. + * @flags: flags affecting the unmount if required for eject + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * This function sets the byte order for the given @stream. All subsequent - * reads from the @stream will be read in the given @order. + * Ejects a mount. This is an asynchronous operation, and is + * finished by calling g_mount_eject_with_operation_finish() with the @mount + * and #GAsyncResult data returned in the @callback. + * + * Since: 2.22 */ /** - * G_CALLBACK: - * @f: a function pointer. + * g_mount_eject_with_operation_finish: + * @mount: a #GMount. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Cast a function pointer to a #GCallback. + * Finishes ejecting a mount. If any errors occurred during the operation, + * + * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. + * Since: 2.22 */ /** - * g_dbus_message_get_locked: - * @message: A #GDBusMessage. + * g_mount_get_default_location: + * @mount: a #GMount. * - * Checks whether @message is locked. To monitor changes to this - * value, conncet to the #GObject::notify signal to listen for changes - * on the #GDBusMessage:locked property. + * Gets the default location of @mount. The default location of the given + * the home directory, or the root of the volume). + * The returned object should be unreffed with + * g_object_unref() when no longer needed. * - * Returns: %TRUE if @message is locked, %FALSE otherwise. - * Since: 2.26 + * Returns: (transfer full): a #GFile. */ /** - * G_FILE_ATTRIBUTE_GVFS_BACKEND: + * g_mount_get_drive: + * @mount: a #GMount. * - * A key in the "gvfs" namespace that gets the name of the current - * GVFS backend in use. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. + * Gets the drive for the @mount. + * This is a convenience method for getting the #GVolume and then + * using that object to get the #GDrive. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. + * + * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive. */ /** - * GOptionParseFunc: - * @context: The active #GOptionContext - * @group: The group to which the function belongs - * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() - * @error: A return location for error details + * g_mount_get_icon: + * @mount: a #GMount. * - * The type of function that can be called before and after parsing. - * occurred, in which case @error should be set with g_set_error() + * Gets the icon for @mount. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. * - * Returns: %TRUE if the function completed successfully, %FALSE if an error + * Returns: (transfer full): a #GIcon. */ /** - * G_ENUM_CLASS: - * @class: a valid #GEnumClass + * g_mount_get_name: + * @mount: a #GMount. * - * Casts a derived #GEnumClass structure into a #GEnumClass structure. + * Gets the name of @mount. + * The returned string should be freed with g_free() + * when no longer needed. + * + * Returns: the name for the given @mount. */ /** - * GAction:state-type: + * g_mount_get_root: + * @mount: a #GMount. * - * The #GVariantType of the state that the action has, or %NULL if the - * action is stateless. + * Gets the root directory on @mount. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. * - * Since: 2.28 + * Returns: (transfer full): a #GFile. */ /** - * G_VALUE_TYPE: - * @value: A #GValue structure. + * g_mount_get_uuid: + * @mount: a #GMount. * - * Get the type identifier of @value. + * Gets the UUID for the @mount. The reference is typically based on + * the file system UUID for the mount in question and should be + * considered an opaque string. Returns %NULL if there is no UUID + * available. + * The returned string should be freed with g_free() + * when no longer needed. * - * Returns: the #GType. + * Returns: the UUID for @mount or %NULL if no UUID can be computed. */ /** - * g_socket_send_with_blocking: - * @socket: a #GSocket - * @buffer: (array length=size): the buffer containing the data to send. - * @size: the number of bytes to send - * @blocking: whether to do blocking or non-blocking I/O - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_mount_get_volume: + * @mount: a #GMount. * - * This behaves exactly the same as g_socket_send(), except that - * the choice of blocking or non-blocking behavior is determined by - * the @blocking argument rather than by @socket's properties. - * on error + * Gets the volume for the @mount. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. * - * Returns: Number of bytes written (which may be less than @size), or -1 - * Since: 2.26 + * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume. */ /** - * GDBusCapabilityFlags: - * @G_DBUS_CAPABILITY_FLAGS_NONE: No flags set. - * @G_DBUS_CAPABILITY_FLAGS_UNIX_FD_PASSING: The connection supports exchanging UNIX file descriptors with the remote peer. + * g_mount_guess_content_type: + * @mount: a #GMount + * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: a #GAsyncReadyCallback + * @user_data: user data passed to @callback * - * Capabilities negotiated with the remote peer. + * Tries to guess the type of content stored on @mount. Returns one or + * more textual identifiers of well-known content types (typically + * prefixed with "x-content/"), e.g. x-content/image-dcf for camera + * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> + * specification for more on x-content types. + * This is an asynchronous operation (see + * g_mount_guess_content_type_sync() for the synchronous version), and + * is finished by calling g_mount_guess_content_type_finish() with the * - * Since: 2.26 + * Since: 2.18 */ /** - * g_unix_socket_address_abstract_names_supported: + * g_mount_guess_content_type_finish: + * @mount: a #GMount + * @result: a #GAsyncResult + * @error: a #GError location to store the error occuring, or %NULL to ignore * - * Checks if abstract unix domain socket names are supported. + * Finishes guessing content types of @mount. If any errors occured + * during the operation, @error will be set to contain the errors and + * %FALSE will be returned. In particular, you may get an + * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content + * guessing. + * Caller should free this array with g_strfreev() when done with it. * - * Returns: %TRUE if supported, %FALSE otherwise - * Since: 2.22 + * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. + * Since: 2.18 */ /** - * G_VARIANT_TYPE_BYTESTRING: + * g_mount_guess_content_type_sync: + * @mount: a #GMount + * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @error: a #GError location to store the error occuring, or %NULL to ignore * - * The type of an array of bytes. This type is commonly used to pass - * around strings that may not be valid utf8. In that case, the - * convention is that the nul terminator character should be included as - * the last character in the array. + * Tries to guess the type of content stored on @mount. Returns one or + * more textual identifiers of well-known content types (typically + * prefixed with "x-content/"), e.g. x-content/image-dcf for camera + * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> + * specification for more on x-content types. + * This is an synchronous operation and as such may block doing IO; + * see g_mount_guess_content_type() for the asynchronous version. + * Caller should free this array with g_strfreev() when done with it. + * + * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. + * Since: 2.18 */ /** - * g_bus_unwatch_name: - * @watcher_id: An identifier obtained from g_bus_watch_name() + * g_mount_is_shadowed: + * @mount: A #GMount. * - * Stops watching a name. + * Determines if @mount is shadowed. Applications or libraries should + * avoid displaying @mount in the user interface if it is shadowed. + * A mount is said to be shadowed if there exists one or more user + * visible objects (currently #GMount objects) with a root that is + * inside the root of @mount. + * One application of shadow mounts is when exposing a single file + * system that is used to address several logical volumes. In this + * situation, a #GVolumeMonitor implementation would create two + * #GVolume objects (for example, one for the camera functionality of + * the device and one for a SD card reader on the device) with + * activation URIs <literal>gphoto2://[usb:001,002]/store1/</literal> + * and <literal>gphoto2://[usb:001,002]/store2/</literal>. When the + * underlying mount (with root + * <literal>gphoto2://[usb:001,002]/</literal>) is mounted, said + * #GVolumeMonitor implementation would create two #GMount objects + * (each with their root matching the corresponding volume activation + * root) that would shadow the original mount. + * The proxy monitor in GVfs 2.26 and later, automatically creates and + * manage shadow mounts (and shadows the underlying mount) if the + * activation root on a #GVolume is set. * - * Since: 2.26 + * Returns: %TRUE if @mount is shadowed. + * Since: 2.20 */ /** - * g_socket_connectable_proxy_enumerate: - * @connectable: a #GSocketConnectable + * g_mount_operation_get_anonymous: + * @op: a #GMountOperation. * - * Creates a #GSocketAddressEnumerator for @connectable that will - * return #GProxyAddress<!-- -->es for addresses that you must connect - * to via a proxy. - * If @connectable does not implement - * g_socket_connectable_proxy_enumerate(), this will fall back to - * calling g_socket_connectable_enumerate(). + * Check to see whether the mount operation is being used + * for an anonymous user. * - * Returns: (transfer full): a new #GSocketAddressEnumerator. - * Since: 2.26 + * Returns: %TRUE if mount operation is anonymous. */ /** - * g_dbus_method_invocation_get_interface_name: - * @invocation: A #GDBusMethodInvocation. + * g_mount_operation_get_choice: + * @op: a #GMountOperation. * - * Gets the name of the D-Bus interface the method was invoked on. + * Gets a choice from the mount operation. + * the choice's list, or %0. * - * Returns: A string. Do not free, it is owned by @invocation. - * Since: 2.26 + * Returns: an integer containing an index of the user's choice from */ /** - * g_memory_input_stream_new: + * g_mount_operation_get_domain: + * @op: a #GMountOperation. * - * Creates a new empty #GMemoryInputStream. + * Gets the domain of the mount operation. * - * Returns: a new #GInputStream + * Returns: a string set to the domain. */ /** - * g_resolver_free_targets: (skip) - * @targets: a #GList of #GSrvTarget + * g_mount_operation_get_password: + * @op: a #GMountOperation. * - * Frees @targets (which should be the return value from - * g_resolver_lookup_service() or g_resolver_lookup_service_finish()). - * (This is a convenience method; you can also simply free the - * results by hand.) + * Gets a password from the mount operation. * - * Since: 2.22 + * Returns: a string containing the password within @op. */ /** - * g_cancellable_is_cancelled: - * @cancellable: a #GCancellable or NULL. + * g_mount_operation_get_password_save: + * @op: a #GMountOperation. * - * Checks if a cancellable job has been cancelled. - * FALSE if called with %NULL or if item is not cancelled. + * Gets the state of saving passwords for the mount operation. * - * Returns: %TRUE if @cancellable is cancelled, + * Returns: a #GPasswordSave flag. */ /** - * GParamSpecVariant: - * @parent_instance: private #GParamSpec portion - * @type: a #GVariantType, or %NULL - * @default_value: a #GVariant, or %NULL + * g_mount_operation_get_usernam: + * @op: a #GMountOperation. * - * A #GParamSpec derived structure that contains the meta data for #GVariant properties. + * Get the user name from the mount operation. * - * Since: 2.26 + * Returns: a string containing the user name. */ /** - * g_file_info_get_is_hidden: - * @info: a #GFileInfo. + * g_mount_operation_new: * - * Checks if a file is hidden. + * Creates a new mount operation. * - * Returns: %TRUE if the file is a hidden file, %FALSE otherwise. + * Returns: a #GMountOperation. */ /** - * g_dbus_server_start: - * @server: A #GDBusServer. - * - * Starts @server. + * g_mount_operation_reply: + * @op: a #GMountOperation + * @result: a #GMountOperationResult * - * Since: 2.26 + * Emits the #GMountOperation::reply signal. */ /** - * G_VOLUME_IDENTIFIER_KIND_LABEL: + * g_mount_operation_set_anonymous: + * @op: a #GMountOperation. + * @anonymous: boolean value. * - * The string used to obtain a filesystem label with g_volume_get_identifier(). + * Sets the mount operation to use an anonymous user if @anonymous is %TRUE. */ /** - * SECTION:gsocketconnectabl: - * @short_description: Interface for potential socket endpoints - * - * Objects that describe one or more potential socket endpoints - * implement #GSocketConnectable. Callers can then use - * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator - * to try out each socket address in turn until one succeeds, as shown - * in the sample code below. - * |[ - * MyConnectionType * - * connect_to_host (const char *hostname, - * guint16 port, - * GCancellable *cancellable, - * GError **error) - * { - * MyConnection *conn = NULL; - * GSocketConnectable *addr; - * GSocketAddressEnumerator *enumerator; - * GSocketAddress *sockaddr; - * GError *conn_error = NULL; - * addr = g_network_address_new ("www.gnome.org", 80); - * enumerator = g_socket_connectable_enumerate (addr); - * g_object_unref (addr); - * /<!-- -->* Try each sockaddr until we succeed. Record the first - * * connection error, but not any further ones (since they'll probably - * * be basically the same as the first). - * *<!-- -->/ - * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error)) - * { - * g_object_unref (sockaddr); - * } - * g_object_unref (enumerator); - * if (conn) - * { - * if (conn_error) - * { - * /<!-- -->* We couldn't connect to the first address, but we succeeded - * * in connecting to a later address. - * *<!-- -->/ - * g_error_free (conn_error); - * } - * return conn; - * } - * else if (error) - * { - * /<!-- -->* Either the initial lookup failed, or else the caller - * * cancelled us. - * *<!-- -->/ - * if (conn_error) - * g_error_free (conn_error); - * return NULL; - * } - * else - * { - * g_error_propagate (error, conn_error); - * return NULL; - * } - * } - * ]| + * g_mount_operation_set_choice: + * @op: a #GMountOperation. + * @choice: an integer. * - * Conn = connect_to_sockaddr (sockaddr, conn_error ? null : &conn_error); + * Sets a default choice for the mount operation. */ /** - * g_dbus_connection_close_sync: - * @connection: A #GDBusConnection. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Synchronously closees @connection. The calling thread is blocked - * until this is done. See g_dbus_connection_close() for the - * asynchronous version of this method and more details about what it - * does. + * g_mount_operation_set_domain: + * @op: a #GMountOperation. + * @domain: the domain to set. * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. - * Since: 2.26 + * Sets the mount operation's domain. */ /** - * g_settings_get_double: - * @settings: a #GSettings object - * @key: the key to get the value for - * @returns: a double - * - * Gets the value that is stored at @key in @settings. - * A convenience variant of g_settings_get() for doubles. - * It is a programmer error to give a @key that isn't specified as - * having a 'double' type in the schema for @settings. + * g_mount_operation_set_password: + * @op: a #GMountOperation. + * @password: password to set. * - * Since: 2.26 + * Sets the mount operation's password to @password. */ /** - * G_IS_PARAM_SPEC_UINT64: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. + * g_mount_operation_set_password_save: + * @op: a #GMountOperation. + * @save: a set of #GPasswordSave flags. * - * Returns: %TRUE on success. + * Sets the state of saving passwords for the mount operation. */ /** - * g_app_info_equal: - * @appinfo1: the first #GAppInfo. - * @appinfo2: the second #GAppInfo. - * - * Checks if two #GAppInfo<!-- -->s are equal. + * g_mount_operation_set_username: + * @op: a #GMountOperation. + * @username: input username. * - * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. + * Sets the user name within @op to @username. */ @@ -25133,6038 +24530,6575 @@ /** - * g_volume_can_mount: - * @volume: a #GVolume. + * g_mount_remount_finish: + * @mount: a #GMount. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Checks if a volume can be mounted. + * Finishes remounting a mount. If any errors occurred during the operation, * - * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise. + * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise. */ /** - * G_TYPE_LONG: + * g_mount_shadow: + * @mount: A #GMount. * - * The fundamental type corresponding to #glong. + * Increments the shadow count on @mount. Usually used by + * #GVolumeMonitor implementations when creating a shadow mount for + * will need to emit the #GMount::changed signal on @mount manually. + * + * Since: 2.20 */ /** - * g_volume_monitor_get: + * g_mount_unmount: + * @mount: a #GMount. + * @flags: flags affecting the operation + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * Gets the volume monitor used by gio. - * g_object_unref() when done with it. + * Unmounts a mount. This is an asynchronous operation, and is + * finished by calling g_mount_unmount_finish() with the @mount + * and #GAsyncResult data returned in the @callback. * - * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call + * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead. */ /** - * g_file_make_directory_with_parents: - * @file: input #GFile. + * g_mount_unmount_finish: + * @mount: a #GMount. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. + * + * Finishes unmounting a mount. If any errors occurred during the operation, + * + * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise. + * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead. + */ + + +/** + * g_mount_unmount_with_operation: + * @mount: a #GMount. + * @flags: flags affecting the operation + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * Creates a directory and any parent directories that may not exist similar to - * 'mkdir -p'. If the file system does not support creating directories, this - * function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. - * For a local #GFile the newly created directories will have the default - * (current) ownership and permissions of the current process. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * otherwise. + * Unmounts a mount. This is an asynchronous operation, and is + * finished by calling g_mount_unmount_with_operation_finish() with the @mount + * and #GAsyncResult data returned in the @callback. * - * Returns: %TRUE if all directories have been successfully created, %FALSE - * Since: 2.18 + * Since: 2.22 */ /** - * g_buffered_input_stream_peek_buffer: - * @stream: a #GBufferedInputStream - * @count: (out): a #gsize to get the number of bytes available in the buffer + * g_mount_unmount_with_operation_finish: + * @mount: a #GMount. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Returns the buffer with the currently available bytes. The returned - * buffer must not be modified and will become invalid when reading from - * the stream or filling the buffer. - * read-only buffer + * Finishes unmounting a mount. If any errors occurred during the operation, * - * Returns: (array length=count) (element-type guint8) (transfer none): + * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise. + * Since: 2.22 */ /** - * g_socket_address_enumerator_next: - * @enumerator: a #GSocketAddressEnumerator - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * g_mount_unshadow: + * @mount: A #GMount. * - * Retrieves the next #GSocketAddress from @enumerator. Note that this - * may block for some amount of time. (Eg, a #GNetworkAddress may need - * to do a DNS lookup before it can return an address.) Use - * g_socket_address_enumerator_next_async() if you need to avoid - * blocking. - * If @enumerator is expected to yield addresses, but for some reason - * is unable to (eg, because of a DNS error), then the first call to - * g_socket_address_enumerator_next() will return an appropriate error - * in *@error. However, if the first call to - * g_socket_address_enumerator_next() succeeds, then any further - * internal errors (other than @cancellable being triggered) will be - * ignored. - * error (in which case *@error will be set) or if there are no - * more addresses. + * Decrements the shadow count on @mount. Usually used by + * #GVolumeMonitor implementations when destroying a shadow mount for + * will need to emit the #GMount::changed signal on @mount manually. * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on + * Since: 2.20 */ /** - * G_PARAM_SPEC_UNICHAR: - * @pspec: a valid #GParamSpec instance + * g_network_address_get_hostname: + * @addr: a #GNetworkAddress * - * Cast a #GParamSpec instance into a #GParamSpecUnichar. + * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, + * depending on what @addr was created with. + * + * Returns: @addr's hostname + * Since: 2.22 */ /** - * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH: + * g_network_address_get_port: + * @addr: a #GNetworkAddress * - * A key in the "access" namespace for checking trashing privileges. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - * This attribute will be %TRUE if the user is able to move the file to - * the trash. + * Gets @addr's port number + * + * Returns: @addr's port (which may be 0) + * Since: 2.22 */ /** - * GTlsCertificate: + * g_network_address_get_scheme: + * @addr: a #GNetworkAddress * - * Abstract base class for TLS certificate types. + * Gets @addr's scheme * - * Since: 2.28 + * Returns: @addr's scheme (%NULL if not built from URI) + * Since: 2.26 */ /** - * SECTION:gasyncinitabl: - * @short_description: Asynchronously failable object initialization interface - * @include: gio/gio.h - * @see_also: #GInitable + * g_network_address_new: + * @hostname: the hostname + * @port: the port * - * This is the asynchronous version of #GInitable; it behaves the same - * in all ways except that initialization is asynchronous. For more details - * see the descriptions on #GInitable. - * A class may implement both the #GInitable and #GAsyncInitable interfaces. - * Users of objects implementing this are not intended to use the interface - * method directly; instead it will be used automatically in various ways. - * For C applications you generally just call g_async_initable_new_async() - * directly, or indirectly via a foo_thing_new_async() wrapper. This will call - * g_async_initable_init_async() under the cover, calling back with %NULL and - * a set %GError on failure. - * A typical implementation might look something like this: - * |[ - * enum { - * NOT_INITIALIZED, - * INITIALIZING, - * INITIALIZED - * }; - * static void - * _foo_ready_cb (Foo *self) - * { - * GList *l; - * self->priv->state = INITIALIZED; - * for (l = self->priv->init_results; l != NULL; l = l->next) - * { - * GSimpleAsyncResult *simple = l->data; - * if (!self->priv->success) - * g_simple_async_result_set_error (simple, ...); - * g_simple_async_result_complete (simple); - * g_object_unref (simple); - * } - * g_list_free (self->priv->init_results); - * self->priv->init_results = NULL; - * } - * static void - * foo_init_async (GAsyncInitable *initable, - * int io_priority, - * GCancellable *cancellable, - * GAsyncReadyCallback callback, - * gpointer user_data) - * { - * Foo *self = FOO (initable); - * GSimpleAsyncResult *simple; - * simple = g_simple_async_result_new (G_OBJECT (initable) - * callback, - * user_data, - * foo_init_async); - * switch (self->priv->state) - * { - * case NOT_INITIALIZED: - * _foo_get_ready (self); - * self->priv->init_results = g_list_append (self->priv->init_results, - * simple); - * self->priv->state = INITIALIZING; - * break; - * case INITIALIZING: - * self->priv->init_results = g_list_append (self->priv->init_results, - * simple); - * break; - * case INITIALIZED: - * if (!self->priv->success) - * g_simple_async_result_set_error (simple, ...); - * g_simple_async_result_complete_in_idle (simple); - * g_object_unref (simple); - * break; - * } - * } - * static gboolean - * foo_init_finish (GAsyncInitable *initable, - * GAsyncResult *result, - * GError **error) - * { - * g_return_val_if_fail (g_simple_async_result_is_valid (result, - * G_OBJECT (initable), foo_init_async), FALSE); - * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result), - * error)) - * return FALSE; - * return TRUE; - * } - * static void - * foo_async_initable_iface_init (gpointer g_iface, - * gpointer data) - * { - * GAsyncInitableIface *iface = g_iface; - * iface->init_async = foo_init_async; - * iface->init_finish = foo_init_finish; - * } - * ]| + * Creates a new #GSocketConnectable for connecting to the given + * + * Returns: (transfer full): the new #GNetworkAddress + * Since: 2.22 */ /** - * g_file_attribute_info_list_new: + * g_network_address_parse: + * @host_and_port: the hostname and optionally a port + * @default_port: the default port if not in @host_and_port + * @error: a pointer to a #GError, or %NULL * - * Creates a new file attribute info list. + * Creates a new #GSocketConnectable for connecting to the given + * parsing @host_and_port fails. + * address, an IPv4 address, or a domain name (in which case a DNS + * lookup is performed). Quoting with [] is supported for all address + * types. A port override may be specified in the usual way with a + * colon. Ports may be given as decimal numbers or symbolic names (in + * which case an /etc/services lookup is performed). + * If no port is specified in @host_and_port then @default_port will be + * used as the port number to connect to. + * In general, @host_and_port is expected to be provided by the user + * (allowing them to give the hostname, and a port overide if necessary) + * and @default_port is expected to be provided by the application. * - * Returns: a #GFileAttributeInfoList. + * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error + * Since: 2.22 */ /** - * G_FILE_ATTRIBUTE_STANDARD_NAME: + * g_network_address_parse_uri: + * @uri: the hostname and optionally a port + * @default_port: The default port if none is found in the URI + * @error: a pointer to a #GError, or %NULL * - * A key in the "standard" namespace for getting the name of the file. - * The name is the on-disk filename which may not be in any known encoding, - * and can thus not be generally displayed as is. - * Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the - * name in a user interface. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + * Creates a new #GSocketConnectable for connecting to the given + * Using this rather than g_network_address_new() or + * g_network_address_parse_host() allows #GSocketClient to determine + * when to use application-specific proxy protocols. + * + * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error + * Since: 2.26 */ /** - * g_resolver_lookup_by_name_finish: - * @resolver: a #GResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL + * g_network_service_get_domain: + * @srv: a #GNetworkService * - * Retrieves the result of a call to - * g_resolver_lookup_by_name_async(). - * If the DNS resolution failed, @error (if non-%NULL) will be set to - * a value from #GResolverError. If the operation was cancelled, - * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() - * for more details. + * Gets the domain that @srv serves. This might be either UTF-8 or + * ASCII-encoded, depending on what @srv was created with. * - * Returns: (element-type GInetAddress) (transfer full): a #GList + * Returns: @srv's domain name * Since: 2.22 */ /** - * G_TYPE_NONE: + * g_network_service_get_protocol: + * @srv: a #GNetworkService * - * A fundamental type which is used as a replacement for the C - * <literal>void</literal> return type. + * Gets @srv's protocol name (eg, "tcp"). + * + * Returns: @srv's protocol name + * Since: 2.22 */ /** - * g_data_input_stream_get_newline_type: - * @stream: a given #GDataInputStream. + * g_network_service_get_scheme: + * @srv: a #GNetworkService * - * Gets the current newline type for the @stream. + * Get's the URI scheme used to resolve proxies. By default, the service name + * is used as scheme. * - * Returns: #GDataStreamNewlineType for the given @stream. + * Returns: @srv's scheme name + * Since: 2.26 */ /** - * g_volume_eject_with_operation_finish: - * @volume: a #GVolume. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_network_service_get_service: + * @srv: a #GNetworkService * - * Finishes ejecting a volume. If any errors occurred during the operation, + * Gets @srv's service name (eg, "ldap"). * - * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise. + * Returns: @srv's service name * Since: 2.22 */ /** - * g_drive_can_poll_for_media: - * @drive: a #GDrive. + * g_network_service_new: + * @service: the service type to look up (eg, "ldap") + * @protocol: the networking protocol to use for @service (eg, "tcp") + * @domain: the DNS domain to look up the service in * - * Checks if a drive can be polled for media changes. - * %FALSE otherwise. + * Creates a new #GNetworkService representing the given @service, + * #GSocketConnectable interface to resolve it. * - * Returns: %TRUE if the @drive can be polled for media changes, + * Returns: (transfer full): a new #GNetworkService + * Since: 2.22 */ /** - * gchararray: + * g_network_service_set_scheme: + * @srv: a #GNetworkService + * @scheme: a URI scheme * - * A C representable type name for #G_TYPE_STRING. + * Set's the URI scheme used to resolve proxies. By default, the service name + * is used as scheme. + * + * Since: 2.26 */ /** - * g_dbus_error_register_error_domain: - * @error_domain_quark_name: The error domain name. - * @quark_volatile: A pointer where to store the #GQuark. - * @entries: A pointer to @num_entries #GDBusErrorEntry struct items. - * @num_entries: Number of items to register. + * g_new: + * @struct_type: the type of the elements to allocate + * @n_structs: the number of elements to allocate * - * Helper function for associating a #GError error domain with D-Bus error names. + * Allocates @n_structs elements of type @struct_type. + * The returned pointer is cast to a pointer to the given type. + * If @n_structs is 0 it returns %NULL. + * Care is taken to avoid overflow when calculating the size of the allocated block. + * Since the returned pointer is already casted to the right type, + * it is normally unnecessary to cast it explicitly, and doing + * so might hide memory allocation errors. * - * Since: 2.26 + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type */ /** - * G_FILE_ATTRIBUTE_ID_FILE: + * g_new0: + * @struct_type: the type of the elements to allocate. + * @n_structs: the number of elements to allocate. * - * A key in the "id" namespace for getting a file identifier. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - * An example use would be during listing files, to avoid recursive - * directory scanning. + * Allocates @n_structs elements of type @struct_type, initialized to 0's. + * The returned pointer is cast to a pointer to the given type. + * If @n_structs is 0 it returns %NULL. + * Care is taken to avoid overflow when calculating the size of the allocated block. + * Since the returned pointer is already casted to the right type, + * it is normally unnecessary to cast it explicitly, and doing + * so might hide memory allocation errors. + * + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. */ /** - * g_cancellable_release_fd: - * @cancellable: a #GCancellable + * g_newa: + * @struct_type: Type of memory chunks to be allocated + * @n_structs: Number of chunks to be allocated * - * Releases a resources previously allocated by g_cancellable_get_fd() - * or g_cancellable_make_pollfd(). - * For compatibility reasons with older releases, calling this function - * is not strictly required, the resources will be automatically freed - * when the @cancellable is finalized. However, the @cancellable will - * block scarce file descriptors until it is finalized if this function - * is not called. This can cause the application to run out of file - * descriptors when many #GCancellables are used at the same time. + * Wraps g_alloca() in a more typesafe manner. * - * Since: 2.22 + * Returns: Pointer to stack space for @n_structs chunks of type @struct_type */ /** - * g_data_input_stream_read_upto: - * @stream: a #GDataInputStream - * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated - * @length: (out): a #gsize to get the length of the data read in - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: #GError for error reporting + * g_node_append: + * @parent: the #GNode to place the new #GNode under + * @node: the #GNode to insert * - * Reads a string from the data input stream, up to the first - * occurrence of any of the stop characters. - * In contrast to g_data_input_stream_read_until(), this function - * does <emphasis>not</emphasis> consume the stop character. You have - * to use g_data_input_stream_read_byte() to get it before calling - * g_data_input_stream_read_upto() again. - * Note that @stop_chars may contain '\0' if @stop_chars_len is - * specified. - * before encountering any of the stop characters. Set @length to - * a #gsize to get the length of the string. This function will - * return %NULL on an error + * Inserts a #GNode as the last child of the given parent. * - * Returns: (transfer full): a string with the data that was read - * Since: 2.24 + * Returns: the inserted #GNode */ /** - * G_PARAM_SPEC_FLOAT: - * @pspec: a valid #GParamSpec instance + * g_node_append_data: + * @parent: the #GNode to place the new #GNode under + * @data: the data for the new #GNode * - * Cast a #GParamSpec instance into a #GParamSpecFloat. + * Inserts a new #GNode as the last child of the given parent. + * + * Returns: the new #GNode */ /** - * g_inet_address_get_family: - * @address: a #GInetAddress + * g_node_first_child: + * @node: a #GNode * - * Gets @address's family + * Gets the first child of a #GNode. + * or has no children * - * Returns: @address's family - * Since: 2.22 + * Returns: the first child of @node, or %NULL if @node is %NULL */ /** - * g_filename_completer_get_completions: - * @completer: the filename completer. - * @initial_text: text to be completed. + * g_node_insert_data: + * @parent: the #GNode to place the new #GNode under + * @position: the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent + * @data: the data for the new #GNode * - * Gets an array of completion strings for a given initial text. - * This array must be freed by g_strfreev() when finished. + * Inserts a new #GNode at the given position. * - * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. + * Returns: the new #GNode */ /** - * g_data_output_stream_get_byte_order: - * @stream: a #GDataOutputStream. + * g_node_insert_data_before: + * @parent: the #GNode to place the new #GNode under + * @sibling: the sibling #GNode to place the new #GNode before + * @data: the data for the new #GNode * - * Gets the byte order for the stream. + * Inserts a new #GNode before the given sibling. * - * Returns: the #GDataStreamByteOrder for the @stream. + * Returns: the new #GNode */ /** - * GIconIface: - * @g_iface: The parent interface. - * @hash: A hash for a given #GIcon. - * @equal: Checks if two #GIcon<!-- -->s are equal. - * @to_tokens: Serializes a #GIcon into tokens. The tokens must not contain any whitespace. Don't implement if the #GIcon can't be serialized (Since 2.20). - * @from_tokens: Constructs a #GIcon from tokens. Set the #GError if the tokens are malformed. Don't implement if the #GIcon can't be serialized (Since 2.20). + * g_node_next_sibling: + * @node: a #GNode * - * GIconIface is used to implement GIcon types for various - * different systems. See #GThemedIcon and #GLoadableIcon for - * examples of how to implement this interface. + * Gets the next sibling of a #GNode. + * or %NULL + * + * Returns: the next sibling of @node, or %NULL if @node is the last node */ /** - * g_file_info_get_icon: - * @info: a #GFileInfo. + * g_node_prepend_data: + * @parent: the #GNode to place the new #GNode under + * @data: the data for the new #GNode * - * Gets the icon for a file. + * Inserts a new #GNode as the first child of the given parent. * - * Returns: (transfer none): #GIcon for the given @info. + * Returns: the new #GNode */ /** - * g_filter_output_stream_set_close_base_stream: - * @stream: a #GFilterOutputStream. - * @close_base: %TRUE to close the base stream. + * g_node_prev_sibling: + * @node: a #GNode * - * Sets whether the base stream will be closed when @stream is closed. + * Gets the previous sibling of a #GNode. + * node or %NULL + * + * Returns: the previous sibling of @node, or %NULL if @node is the first */ /** - * g_file_set_display_name: - * @file: input #GFile. - * @display_name: a string. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * g_output_stream_clear_pending: + * @stream: output stream * - * Renames @file to the specified display name. - * The display name is converted from UTF8 to the correct encoding for the target - * filesystem if possible and the @file is renamed to this. - * If you want to implement a rename operation in the user interface the edit name - * (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename - * widget, and then the result after editing should be passed to g_file_set_display_name(). - * On success the resulting converted filename is returned. - * If @cancellable is not %NULL, then the operation can be cancelled by + * Clears the pending flag on @stream. + */ + + +/** + * g_output_stream_close: + * @stream: A #GOutputStream. + * @cancellable: (allow-none): optional cancellable object + * @error: location to store the error occuring, or %NULL to ignore + * + * Closes the stream, releasing resources related to it. + * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. + * Closing a stream multiple times will not return an error. + * Closing a stream will automatically flush any outstanding buffers in the + * stream. + * Streams will be automatically closed when the last reference + * is dropped, but you might want to call this function to make sure + * resources are released as early as possible. + * Some streams might keep the backing store of the stream (e.g. a file descriptor) + * open after the stream is closed. See the documentation for the individual + * stream for details. + * On failure the first error that happened will be reported, but the close + * operation will finish as much as possible. A stream that failed to + * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it + * is important to check and report the error to the user, otherwise + * there might be a loss of data as all data might not be written. + * If @cancellable is not NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * if there was an error. - * Free the returned object with g_object_unref(). + * Cancelling a close will still leave the stream closed, but there some streams + * can use a faster close that doesn't block to e.g. check errors. On + * cancellation (as with any error) there is no guarantee that all written + * data will reach the target. * - * Returns: (transfer full): a #GFile specifying what @file was renamed to, or %NULL + * Returns: %TRUE on success, %FALSE on failure */ /** - * G_TYPE_DATE_TIME: + * g_output_stream_close_async: + * @stream: A #GOutputStream. + * @io_priority: the io priority of the request. + * @cancellable: (allow-none): optional cancellable object + * @callback: (scope async): callback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * The #GType for a boxed type holding a #GDateTime. + * Requests an asynchronous close of the stream, releasing resources + * related to it. When the operation is finished @callback will be + * called. You can then call g_output_stream_close_finish() to get + * the result of the operation. + * For behaviour details see g_output_stream_close(). + * The asyncronous methods have a default fallback that uses threads + * to implement asynchronicity, so they are optional for inheriting + * classes. However, if you override one you must override all. + */ + + +/** + * g_output_stream_close_finish: + * @stream: a #GOutputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Since: 2.26 + * Closes an output stream. + * + * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. */ /** - * g_settings_get_has_unapplied: - * @settings: a #GSettings object - * @returns: %TRUE if @settings has unapplied changes + * g_output_stream_flush: + * @stream: a #GOutputStream. + * @cancellable: (allow-none): optional cancellable object + * @error: location to store the error occuring, or %NULL to ignore * - * Returns whether the #GSettings object has any unapplied - * changes. This can only be the case if it is in 'delayed-apply' mode. + * Flushed any outstanding buffers in the stream. Will block during + * the operation. Closing the stream will implicitly cause a flush. + * This function is optional for inherited classes. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Since: 2.26 + * Returns: %TRUE on success, %FALSE on error */ /** - * SECTION:gconverteroutputstrea: - * @short_description: Converter Output Stream - * @include: gio/gio.h - * @see_also: #GOutputStream, #GConverter + * g_output_stream_flush_async: + * @stream: a #GOutputStream. + * @io_priority: the io priority of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Converter output stream implements #GOutputStream and allows - * conversion of data of various types during reading. + * Flushes a stream asynchronously. + * For behaviour details see g_output_stream_flush(). + * When the operation is finished @callback will be + * called. You can then call g_output_stream_flush_finish() to get the + * result of the operation. */ /** - * g_file_poll_mountable_finish: - * @file: input #GFile. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_output_stream_flush_finish: + * @stream: a #GOutputStream. + * @result: a GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Finishes a poll operation. See g_file_poll_mountable() for details. - * Finish an asynchronous poll operation that was polled - * with g_file_poll_mountable(). - * otherwise. + * Finishes flushing an output stream. * - * Returns: %TRUE if the operation finished successfully. %FALSE - * Since: 2.22 + * Returns: %TRUE if flush operation suceeded, %FALSE otherwise. */ /** - * G_FILE_ATTRIBUTE_TRASH_ORIG_PATH: + * g_output_stream_has_pending: + * @stream: a #GOutputStream. * - * A key in the "trash" namespace. When requested against - * items in "trash:///", will return the original path to the file before it - * was trashed. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_STRING. + * Checks if an ouput stream has pending actions. * - * Since: 2.24. + * Returns: %TRUE if @stream has pending actions. */ /** - * g_io_error_quark: + * g_output_stream_is_closed: + * @stream: a #GOutputStream. * - * Gets the GIO Error Quark. + * Checks if an output stream has already been closed. * - * Returns: a #GQuark. + * Returns: %TRUE if @stream is closed. %FALSE otherwise. */ /** - * g_network_service_get_domain: - * @srv: a #GNetworkService + * g_output_stream_is_closing: + * @stream: a #GOutputStream. * - * Gets the domain that @srv serves. This might be either UTF-8 or - * ASCII-encoded, depending on what @srv was created with. + * Checks if an output stream is being closed. This can be + * used inside e.g. a flush implementation to see if the + * flush (or other i/o operation) is called from within + * the closing operation. * - * Returns: @srv's domain name - * Since: 2.22 + * Returns: %TRUE if @stream is being closed. %FALSE otherwise. + * Since: 2.24 */ /** - * g_drive_get_name: - * @drive: a #GDrive. + * g_output_stream_set_pending: + * @stream: a #GOutputStream. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Gets the name of @drive. - * string should be freed when no longer needed. + * Sets @stream to have actions pending. If the pending flag is + * already set or @stream is closed, it will return %FALSE and set * - * Returns: a string containing @drive's name. The returned + * Returns: %TRUE if pending was previously unset and is now set. */ /** - * g_file_get_child_for_display_name: - * @file: input #GFile. - * @display_name: string to a possible child. - * @error: #GError. + * g_output_stream_splice: + * @stream: a #GOutputStream. + * @source: a #GInputStream. + * @flags: a set of #GOutputStreamSpliceFlags. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Gets the child of @file for a given @display_name (i.e. a UTF8 - * version of the name). If this function fails, it returns %NULL and @error will be - * set. This is very useful when constructing a GFile for a new file - * and the user entered the filename in the user interface, for instance - * when you select a directory and type a filename in the file selector. - * This call does no blocking i/o. - * %NULL if the display name couldn't be converted. - * Free the returned object with g_object_unref(). + * Splices an input stream into an output stream. + * -1 if an error occurred. * - * Returns: (transfer full): a #GFile to the specified child, or + * Returns: a #gssize containing the size of the data spliced, or */ /** - * g_file_info_set_modification_tim: - * @info: a #GFileInfo. - * @mtime: a #GTimeVal. + * g_output_stream_splice_async: + * @stream: a #GOutputStream. + * @source: a #GInputStream. + * @flags: a set of #GOutputStreamSpliceFlags. + * @io_priority: the io priority of the request. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. * - * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file - * info to the given time value. + * Splices a stream asynchronously. + * When the operation is finished @callback will be called. + * You can then call g_output_stream_splice_finish() to get the + * result of the operation. + * For the synchronous, blocking version of this function, see + * g_output_stream_splice(). */ /** - * GCancellableSourceFunc: - * @cancellable: the #GCancellable - * @user_data: data passed in by the user. + * g_output_stream_splice_finish: + * @stream: a #GOutputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * This is the function type of the callback used for the #GSource - * returned by g_cancellable_source_new(). + * Finishes an asynchronous stream splice operation. * - * Returns: it should return %FALSE if the source should be removed. - * Since: 2.28 + * Returns: a #gssize of the number of bytes spliced. */ /** - * g_socket_get_protocol: - * @socket: a #GSocket. + * g_output_stream_write: + * @stream: a #GOutputStream. + * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. + * @count: the number of bytes to write + * @cancellable: (allow-none): optional cancellable object + * @error: location to store the error occuring, or %NULL to ignore * - * Gets the socket protocol id the socket was created with. - * In case the protocol is unknown, -1 is returned. + * Tries to write @count bytes from @buffer into the stream. Will block + * during the operation. + * If count is 0, returns 0 and does nothing. A value of @count + * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. + * On success, the number of bytes written to the stream is returned. + * It is not an error if this is not the same as the requested size, as it + * can happen e.g. on a partial I/O error, or if there is not enough + * storage in the stream. All writes block until at least one byte + * is written or an error occurs; 0 is never returned (unless + * If @cancellable is not NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an + * operation was partially finished when the operation was cancelled the + * partial result will be returned, without an error. + * On error -1 is returned and @error is set accordingly. * - * Returns: a protocol id, or -1 if unknown - * Since: 2.22 + * Returns: Number of bytes written, or -1 on error */ /** - * GPollableInputStream: + * g_output_stream_write_all: + * @stream: a #GOutputStream. + * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. + * @count: the number of bytes to write + * @bytes_written: (out): location to store the number of bytes that was written to the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occuring, or %NULL to ignore * - * An interface for a #GInputStream that can be polled for readability. + * Tries to write @count bytes from @buffer into the stream. Will block + * during the operation. + * This function is similar to g_output_stream_write(), except it tries to + * write as many bytes as requested, only stopping on an error. + * On a successful write of @count bytes, %TRUE is returned, and @bytes_written + * is set to @count. + * If there is an error during the operation FALSE is returned and @error + * is set to indicate the error status, @bytes_written is updated to contain + * the number of bytes written into the stream before the error occurred. * - * Since: 2.28 + * Returns: %TRUE on success, %FALSE if there was an error */ /** - * g_file_query_info_async: - * @file: input #GFile. - * @attributes: an attribute query string. - * @flags: a set of #GFileQueryInfoFlags. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * g_output_stream_write_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): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * - * Asynchronously gets the requested information about specified @file. The result - * is a #GFileInfo object that contains key-value attributes (such as type or size - * for the file). - * For more details, see g_file_query_info() which is - * the synchronous version of this call. - * When the operation is finished, @callback will be called. You can then call - * g_file_query_info_finish() to get the result of the operation. + * 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_finish() to get the result of the + * operation. + * During an async request no other sync and async calls are allowed, + * and will result in %G_IO_ERROR_PENDING errors. + * A value of @count larger than %G_MAXSSIZE will cause a + * %G_IO_ERROR_INVALID_ARGUMENT error. + * On success, the number of bytes written will be passed to the + * requested size, as it can happen e.g. on a partial I/O error, + * but generally we try to write as many bytes as requested. + * You are guaranteed that this method will never fail with + * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the + * method will just wait until this changes. + * Any outstanding I/O request with higher priority (lower numerical + * value) will be executed before an outstanding request with lower + * priority. Default priority is %G_PRIORITY_DEFAULT. + * The asyncronous methods have a default fallback that uses threads + * to implement asynchronicity, so they are optional for inheriting + * classes. However, if you override one you must override all. + * For the synchronous, blocking version of this function, see + * g_output_stream_write(). */ /** - * g_app_info_remove_supports_type: - * @appinfo: a #GAppInfo. - * @content_type: a string. - * @error: a #GError. + * g_output_stream_write_finish: + * @stream: a #GOutputStream. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Removes a supported type from an application, if possible. + * Finishes a stream write operation. * - * Returns: %TRUE on success, %FALSE on error. + * Returns: a #gssize containing the number of bytes written to the stream. */ /** - * G_FLAGS_CLASS_TYPE_NAME: - * @class: a #GFlagsClass + * g_permission_acquire: + * @permission: a #GPermission instance + * @cancellable: a #GCancellable, or %NULL + * @error: a pointer to a %NULL #GError, or %NULL + * @returns: %TRUE if the permission was successfully acquired * - * Get the static type name from a given #GFlagsClass structure. + * Attempts to acquire the permission represented by @permission. + * The precise method by which this happens depends on the permission + * and the underlying authentication mechanism. A simple example is + * that a dialog may appear asking the user to enter their password. + * You should check with g_permission_get_can_acquire() before calling + * this function. + * If the permission is acquired then %TRUE is returned. Otherwise, + * %FALSE is returned and @error is set appropriately. + * This call is blocking, likely for a very long time (in the case that + * user interaction is required). See g_permission_acquire_async() for + * the non-blocking version. * - * Returns: the type name. + * Since: 2.26 */ /** - * g_initable_newv: - * @object_type: a #GType supporting #GInitable. - * @n_parameters: the number of parameters in @parameters - * @parameters: the parameters to use to construct the object - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_permission_acquire_async: + * @permission: a #GPermission instance + * @cancellable: a #GCancellable, or %NULL + * @callback: the #GAsyncReadyCallback to call when done + * @user_data: the user data to pass to @callback * - * Helper function for constructing #GInitiable object. This is - * similar to g_object_newv() but also initializes the object - * and returns %NULL, setting an error on failure. + * Attempts to acquire the permission represented by @permission. + * This is the first half of the asynchronous version of + * g_permission_acquire(). * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error - * Since: 2.22 + * Since: 2.26 */ /** - * GSocketConnectable: + * g_permission_acquire_finish: + * @permission: a #GPermission instance + * @result: the #GAsyncResult given to the #GAsyncReadyCallback + * @error: a pointer to a %NULL #GError, or %NULL + * @returns: %TRUE if the permission was successfully acquired * - * Interface for objects that contain or generate #GSocketAddress<!-- -->es. + * Collects the result of attempting to acquire the permission + * represented by @permission. + * This is the second half of the asynchronous version of + * g_permission_acquire(). + * + * Since: 2.26 */ /** - * g_unix_output_stream_get_close_fd: - * @stream: a #GUnixOutputStream + * g_permission_get_allowed: + * @permission: a #GPermission instance + * @returns: the value of the 'allowed' property * - * Returns whether the file descriptor of @stream will be - * closed when the stream is closed. + * Gets the value of the 'allowed' property. This property is %TRUE if + * the caller currently has permission to perform the action that * - * Returns: %TRUE if the file descriptor is closed when done - * Since: 2.20 + * Since: 2.26 */ /** - * g_settings_get_int: - * @settings: a #GSettings object - * @key: the key to get the value for - * @returns: an integer + * g_permission_get_can_acquire: + * @permission: a #GPermission instance + * @returns: the value of the 'can-acquire' property * - * Gets the value that is stored at @key in @settings. - * A convenience variant of g_settings_get() for 32-bit integers. - * It is a programmer error to give a @key that isn't specified as - * having a int32 type in the schema for @settings. + * Gets the value of the 'can-acquire' property. This property is %TRUE + * if it is generally possible to acquire the permission by calling + * g_permission_acquire(). * * Since: 2.26 */ /** - * g_data_input_stream_set_newline_type: - * @stream: a #GDataInputStream. - * @type: the type of new line return as #GDataStreamNewlineType. + * g_permission_get_can_release: + * @permission: a #GPermission instance + * @returns: the value of the 'can-release' property * - * Sets the newline type for the @stream. - * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read - * chunk ends in "CR" we must read an additional byte to know if this is "CR" or - * "CR LF", and this might block if there is no more data availible. + * Gets the value of the 'can-release' property. This property is %TRUE + * if it is generally possible to release the permission by calling + * g_permission_release(). + * + * Since: 2.26 */ /** - * g_inet_socket_address_new: - * @address: a #GInetAddress - * @port: a port number + * g_permission_impl_update: + * @permission: a #GPermission instance + * @allowed: the new value for the 'allowed' property + * @can_acquire: the new value for the 'can-acquire' property + * @can_release: the new value for the 'can-release' property * - * Creates a new #GInetSocketAddress for @address and @port. + * This function is called by the #GPermission implementation to update + * the properties of the permission. You should never call this + * function except from a #GPermission implementation. + * GObject notify signals are generated, as appropriate. * - * Returns: a new #GInetSocketAddress - * Since: 2.22 + * Since: 2.26 */ /** - * g_dbus_connection_new_for_address_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). - * @error: Return location for error or %NULL. + * g_permission_release: + * @permission: a #GPermission instance + * @cancellable: a #GCancellable, or %NULL + * @error: a pointer to a %NULL #GError, or %NULL + * @returns: %TRUE if the permission was successfully released * - * Finishes an operation started with g_dbus_connection_new_for_address(). + * Attempts to release the permission represented by @permission. + * The precise method by which this happens depends on the permission + * and the underlying authentication mechanism. In most cases the + * permission will be dropped immediately without further action. + * You should check with g_permission_get_can_release() before calling + * this function. + * If the permission is released then %TRUE is returned. Otherwise, + * %FALSE is returned and @error is set appropriately. + * This call is blocking, likely for a very long time (in the case that + * user interaction is required). See g_permission_release_async() for + * the non-blocking version. * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). * Since: 2.26 */ /** - * g_srv_target_get_weight: - * @target: a #GSrvTarget + * g_permission_release_async: + * @permission: a #GPermission instance + * @cancellable: a #GCancellable, or %NULL + * @callback: the #GAsyncReadyCallback to call when done + * @user_data: the user data to pass to @callback * - * Gets @target's weight. You should not need to look at this; - * #GResolver already sorts the targets according to the algorithm in - * RFC 2782. + * Attempts to release the permission represented by @permission. + * This is the first half of the asynchronous version of + * g_permission_release(). * - * Returns: @target's weight - * Since: 2.22 + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_ACCESS_CAN_READ: + * g_permission_release_finish: + * @permission: a #GPermission instance + * @result: the #GAsyncResult given to the #GAsyncReadyCallback + * @error: a pointer to a %NULL #GError, or %NULL + * @returns: %TRUE if the permission was successfully released * - * A key in the "access" namespace for getting read privileges. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - * This attribute will be %TRUE if the user is able to read the file. + * Collects the result of attempting to release the permission + * represented by @permission. + * This is the second half of the asynchronous version of + * g_permission_release(). + * + * Since: 2.26 */ /** - * g_application_command_line_get_cwd: - * @cmdline: a #GApplicationCommandLine + * g_poll_file_monitor_new: + * @file: a #GFile. * - * Gets the working directory of the command line invocation. The - * string may contain non-utf8 data. - * It is possible that the remote application did not send a working - * directory, so this may be %NULL. - * The return value should not be modified or freed and is valid for as - * long as @cmdline exists. + * Polls @file for changes. * - * Returns: the current directory, or %NULL - * Since: 2.28 + * Returns: a new #GFileMonitor for the given #GFile. */ /** - * g_mount_operation_set_password: - * @op: a #GMountOperation. - * @password: password to set. + * g_pollable_input_stream_can_poll: + * @stream: a #GPollableInputStream. * - * Sets the mount operation's password to @password. + * Checks if @stream is actually pollable. Some classes may implement + * #GPollableInputStream but have only certain instances of that class + * be pollable. If this method returns %FALSE, then the behavior of + * other #GPollableInputStream methods is undefined. + * For any given stream, the value returned by this method is constant; + * a stream cannot switch from pollable to non-pollable or vice versa. + * + * Returns: %TRUE if @stream is pollable, %FALSE if not. + * Since: 2.28 */ /** - * GUnixSocketAddressType: - * @G_UNIX_SOCKET_ADDRESS_INVALID: invalid - * @G_UNIX_SOCKET_ADDRESS_ANONYMOUS: anonymous - * @G_UNIX_SOCKET_ADDRESS_PATH: a filesystem path - * @G_UNIX_SOCKET_ADDRESS_ABSTRACT: an abstract name - * @G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED: an abstract name, 0-padded to the full length of a unix socket name + * g_pollable_input_stream_create_source: (skip) + * @stream: a #GPollableInputStream. + * @cancellable: (allow-none): a #GCancellable, or %NULL * - * The type of name used by a #GUnixSocketAddress. - * %G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain - * socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS - * indicates a socket not bound to any name (eg, a client-side socket, - * or a socket created with socketpair()). - * For abstract sockets, there are two incompatible ways of naming - * sockaddr_un</literal> as the name, padding the unused parts of the - * %sun_path field with zeroes; this corresponds to - * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs - * instead just use a portion of %sun_path, and pass an appropriate - * smaller length to bind() or connect(). This is - * %G_UNIX_SOCKET_ADDRESS_ABSTRACT. + * Creates a #GSource that triggers when @stream can be read, or + * source is of the #GPollableSourceFunc type. + * As with g_pollable_input_stream_is_readable(), it is possible that + * the stream may not actually be readable even after the source + * triggers, so you should use g_pollable_input_stream_read_nonblocking() + * rather than g_input_stream_read() from the callback. * - * Them: the man pages suggest using the entire <literal>struct - * Since: 2.26 + * Returns: (transfer full): a new #GSource + * Since: 2.28 */ /** - * g_initable_new: - * @object_type: a #GType supporting #GInitable. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to ignore. - * @first_property_name: the name of the first property, or %NULL if no properties - * @...: the value if the first property, followed by and other property value pairs, and ended by %NULL. + * g_pollable_input_stream_is_readable: + * @stream: a #GPollableInputStream. * - * Helper function for constructing #GInitiable object. This is - * similar to g_object_new() but also initializes the object - * and returns %NULL, setting an error on failure. + * Checks if @stream can be read. + * Note that some stream types may not be able to implement this 100% + * reliably, and it is possible that a call to g_input_stream_read() + * after this returns %TRUE would still block. To guarantee + * non-blocking behavior, you should always use + * g_pollable_input_stream_read_nonblocking(), which will return a + * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. + * has occurred on @stream, this will result in + * g_pollable_input_stream_is_readable() returning %TRUE, and the + * next attempt to read will return the error. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error - * Since: 2.22 + * Returns: %TRUE if @stream is readable, %FALSE if not. If an error + * Since: 2.28 */ /** - * g_file_info_set_attribute_uint32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: an unsigned 32-bit integer. + * g_pollable_input_stream_read_nonblocking: + * @stream: a #GPollableInputStream + * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @size: the number of bytes you want to read + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * Attempts to read up to @size bytes from @stream into @buffer, as + * with g_input_stream_read(). If @stream is not currently readable, + * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can + * use g_pollable_input_stream_create_source() to create a #GSource + * that will be triggered when @stream is readable. + * Note that since this method never blocks, you cannot actually + * use @cancellable to cancel it. However, it will return an error + * if @cancellable has already been cancelled when you call, which + * may happen if you call this method after a source triggers due + * to having been cancelled. + * %G_IO_ERROR_WOULD_BLOCK). + * + * Virtual: read_nonblocking + * Returns: the number of bytes read, or -1 on error (including */ /** - * g_volume_get_name: - * @volume: a #GVolume. + * g_pollable_output_stream_can_poll: + * @stream: a #GPollableOutputStream. * - * Gets the name of @volume. - * be freed with g_free() when no longer needed. + * Checks if @stream is actually pollable. Some classes may implement + * #GPollableOutputStream but have only certain instances of that + * class be pollable. If this method returns %FALSE, then the behavior + * of other #GPollableOutputStream methods is undefined. + * For any given stream, the value returned by this method is constant; + * a stream cannot switch from pollable to non-pollable or vice versa. * - * Returns: the name for the given @volume. The returned string should + * Returns: %TRUE if @stream is pollable, %FALSE if not. + * Since: 2.28 */ /** - * g_converter_input_stream_new: - * @base_stream: a #GInputStream - * @converter: a #GConverter + * g_pollable_output_stream_create_source: (skip) + * @stream: a #GPollableOutputStream. + * @cancellable: (allow-none): a #GCancellable, or %NULL * - * Creates a new converter input stream for the @base_stream. + * Creates a #GSource that triggers when @stream can be written, or + * source is of the #GPollableSourceFunc type. + * As with g_pollable_output_stream_is_writable(), it is possible that + * the stream may not actually be writable even after the source + * triggers, so you should use g_pollable_output_stream_write_nonblocking() + * rather than g_output_stream_write() from the callback. * - * Returns: a new #GInputStream. + * Returns: (transfer full): a new #GSource + * Since: 2.28 */ /** - * SECTION:gsocke: - * @short_description: Low-level socket object - * @include: gio/gio.h - * @see_also: #GInitable + * g_pollable_output_stream_is_writable: + * @stream: a #GPollableOutputStream. * - * A #GSocket is a low-level networking primitive. It is a more or less - * direct mapping of the BSD socket API in a portable GObject based API. - * It supports both the UNIX socket implementations and winsock2 on Windows. - * #GSocket is the platform independent base upon which the higher level - * network primitives are based. Applications are not typically meant to - * use it directly, but rather through classes like #GSocketClient, - * #GSocketService and #GSocketConnection. However there may be cases where - * direct use of #GSocket is useful. - * #GSocket implements the #GInitable interface, so if it is manually constructed - * by e.g. g_object_new() you must call g_initable_init() and check the - * results before using the object. This is done automatically in - * g_socket_new() and g_socket_new_from_fd(), so these functions can return - * %NULL. - * Sockets operate in two general modes, blocking or non-blocking. When - * in blocking mode all operations block until the requested operation - * is finished or there is an error. In non-blocking mode all calls that - * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error. - * To know when a call would successfully run you can call g_socket_condition_check(), - * or g_socket_condition_wait(). You can also use g_socket_create_source() and - * attach it to a #GMainContext to get callbacks when I/O is possible. - * Note that all sockets are always set to non blocking mode in the system, and - * blocking mode is emulated in GSocket. - * When working in non-blocking mode applications should always be able to - * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other - * function said that I/O was possible. This can easily happen in case - * of a race condition in the application, but it can also happen for other - * reasons. For instance, on Windows a socket is always seen as writable - * until a write returns %G_IO_ERROR_WOULD_BLOCK. - * #GSocket<!-- -->s can be either connection oriented or datagram based. - * For connection oriented types you must first establish a connection by - * either connecting to an address or accepting a connection from another - * address. For connectionless socket types the target/source address is - * specified or received in each I/O operation. - * All socket file descriptors are set to be close-on-exec. - * Note that creating a #GSocket causes the signal %SIGPIPE to be - * ignored for the remainder of the program. If you are writing a - * command-line utility that uses #GSocket, you may need to take into - * account the fact that your program will not automatically be killed - * if it tries to write to %stdout after it has been closed. + * Checks if @stream can be written. + * Note that some stream types may not be able to implement this 100% + * reliably, and it is possible that a call to g_output_stream_write() + * after this returns %TRUE would still block. To guarantee + * non-blocking behavior, you should always use + * g_pollable_output_stream_write_nonblocking(), which will return a + * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. + * has occurred on @stream, this will result in + * g_pollable_output_stream_is_writable() returning %TRUE, and the + * next attempt to write will return the error. * - * Since: 2.22 + * Returns: %TRUE if @stream is writable, %FALSE if not. If an error + * Since: 2.28 */ /** - * GFileIcon:file: + * g_pollable_output_stream_write_nonblocking: + * @stream: a #GPollableOutputStream + * @buffer: (array length=size) (element-type guint8): a buffer to write data from + * @size: the number of bytes you want to write + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * The file containing the icon. + * Attempts to write up to @size bytes from @buffer to @stream, as + * with g_output_stream_write(). If @stream is not currently writable, + * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can + * use g_pollable_output_stream_create_source() to create a #GSource + * that will be triggered when @stream is writable. + * Note that since this method never blocks, you cannot actually + * use @cancellable to cancel it. However, it will return an error + * if @cancellable has already been cancelled when you call, which + * may happen if you call this method after a source triggers due + * to having been cancelled. + * %G_IO_ERROR_WOULD_BLOCK). + * + * Virtual: write_nonblocking + * Returns: the number of bytes written, or -1 on error (including */ /** - * g_emblem_new_with_origin: - * @icon: a GIcon containing the icon. - * @origin: a GEmblemOrigin enum defining the emblem's origin + * g_pollable_source_new: (skip) + * @pollable_stream: the stream associated with the new source * - * Creates a new emblem for @icon. + * Utility method for #GPollableInputStream and #GPollableOutputStream + * implementations. Creates a new #GSource that expects a callback of + * type #GPollableSourceFunc. The new source does not actually do + * anything on its own; use g_source_add_child_source() to add other + * sources to it to cause it to trigger. * - * Returns: a new #GEmblem. - * Since: 2.18 + * Returns: (transfer full): the new #GSource. + * Since: 2.28 */ /** - * GDBusServer:client-address: + * g_proxy_address_get_destination_hostnam: + * @proxy: a #GProxyAddress * - * The D-Bus address that clients can use. + * Gets @proxy's destination hostname. * + * Returns: the @proxy's destination hostname * Since: 2.26 */ /** - * GEnumClass: - * @g_type_class: the parent class - * @minimum: the smallest possible value. - * @maximum: the largest possible value. - * @n_values: the number of possible values. - * @values: an array of #GEnumValue structs describing the individual values. + * g_proxy_address_get_destination_por: + * @proxy: a #GProxyAddress * - * The class of an enumeration type holds information about its - * possible values. + * Gets @proxy's destination port. + * + * Returns: the @proxy's destination port + * Since: 2.26 */ /** - * g_file_output_stream_get_etag: - * @stream: a #GFileOutputStream. + * g_proxy_address_get_passwor: + * @proxy: a #GProxyAddress * - * Gets the entity tag for the file when it has been written. - * This must be called after the stream has been written - * and closed, as the etag can change while writing. + * Gets @proxy's password. * - * Returns: the entity tag for the stream. + * Returns: the @proxy's password + * Since: 2.26 */ /** - * G_TYPE_FUNDAMENTAL_MAX: + * g_proxy_address_get_protocol: + * @proxy: a #GProxyAddress * - * An integer constant that represents the number of identifiers reserved - * for types that are assigned at compile-time. + * Gets @proxy's protocol. + * + * Returns: the @proxy's protocol + * Since: 2.26 */ /** - * GBoxedCopyFunc: - * @boxed: The boxed structure to be copied. + * g_proxy_address_get_usernam: + * @proxy: a #GProxyAddress * - * This function is provided by the user and should produce a copy of the passed - * in boxed structure. + * Gets @proxy's username. * - * Returns: The newly created copy of the boxed structure. + * Returns: the @proxy's username + * Since: 2.26 */ /** - * GParamSpecLong: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_proxy_address_new: + * @inetaddr: The proxy server #GInetAddress. + * @port: The proxy server port. + * @protocol: The proxy protocol to support, in lower case (e.g. socks, http). + * @dest_hostname: The destination hostname the the proxy should tunnel to. + * @dest_port: The destination port to tunnel to. + * @username: (allow-none): The username to authenticate to the proxy server (or %NULL). + * @password: (allow-none): The password to authenticate to the proxy server (or %NULL). * - * A #GParamSpec derived structure that contains the meta data for long integer properties. + * Creates a new #GProxyAddress for @inetaddr with @protocol that should + * tunnel through @dest_hostname and @dest_port. + * + * Returns: a new #GProxyAddress + * Since: 2.26 */ /** - * g_tls_certificate_new_from_files: - * @cert_file: file containing a PEM-encoded certificate to import - * @key_file: file containing a PEM-encoded private key to import - * @error: #GError for error reporting, or %NULL to ignore. + * g_proxy_connect: + * @proxy: a #GProxy + * @connection: a #GIOStream + * @proxy_address: a #GProxyAddress + * @cancellable: (allow-none): a #GCancellable + * @error: return #GError * - * 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(). + * Given @connection to communicate with a proxy (eg, a + * #GSocketConnection that is connected to the proxy server), this + * does the necessary handshake to connect to @proxy_address, and if + * required, wraps the #GIOStream to handle proxy payload. + * be the same as @connection, in which case a reference + * will be added. * - * Returns: the new certificate, or %NULL on error - * Since: 2.28 + * Returns: (transfer full): a #GIOStream that will replace @connection. This might + * Since: 2.26 */ /** - * GMemoryOutputStream:data-size: + * g_proxy_connect_async: + * @proxy: a #GProxy + * @connection: a #GIOStream + * @proxy_address: a #GProxyAddress + * @cancellable: (allow-none): a #GCancellable + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): callback data * - * Size of data written to the buffer. + * Asynchronous version of g_proxy_connect(). * - * Since: 2.24 + * Since: 2.26 */ /** - * G_TYPE_BOOLEAN: + * g_proxy_connect_finish: + * @proxy: a #GProxy + * @result: a #GAsyncRetult + * @error: return #GError * - * The fundamental type corresponding to #gboolean. + * See g_proxy_connect(). + * + * Returns: (transfer full): a #GIOStream. + * Since: 2.26 */ /** - * GDBusConnection:stream: + * g_proxy_get_default_for_protocol: + * @protocol: the proxy protocol name (e.g. http, socks, etc) * - * The underlying #GIOStream used for I/O. + * Lookup "gio-proxy" extension point for a proxy implementation that supports + * specified protocol. + * is not supported. * + * Returns: (transfer full): return a #GProxy or NULL if protocol * Since: 2.26 */ /** - * GOptionError: - * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options(). - * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed. - * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed. + * g_proxy_resolver_get_default: * - * Error codes returned by option parsing. + * Gets the default #GProxyResolver for the system. + * + * Returns: (transfer none): the default #GProxyResolver. + * Since: 2.26 */ /** - * g_output_stream_set_pending: - * @stream: a #GOutputStream. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_proxy_resolver_is_supported: + * @resolver: a #GProxyResolver * - * Sets @stream to have actions pending. If the pending flag is - * already set or @stream is closed, it will return %FALSE and set + * Checks if @resolver can be used on this system. (This is used + * internally; g_proxy_resolver_get_default() will only return a proxy + * resolver that returns %TRUE for this method.) * - * Returns: %TRUE if pending was previously unset and is now set. + * Returns: %TRUE if @resolver is supported. + * Since: 2.26 */ /** - * SECTION:gconverterinputstrea: - * @short_description: Converter Input Stream - * @include: gio/gio.h - * @see_also: #GInputStream, #GConverter + * g_proxy_resolver_lookup: + * @resolver: a #GProxyResolver + * @uri: a URI representing the destination to connect to + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: return location for a #GError, or %NULL * - * Converter input stream implements #GInputStream and allows - * conversion of data of various types during reading. + * Looks into the system proxy configuration to determine what proxy, + * if any, to use to connect to @uri. The returned proxy URIs are of the + * form <literal><protocol>://[user[:password]@]host:port</literal> + * or <literal>direct://</literal>, where <protocol> could be + * http, rtsp, socks or other proxying protocol. + * If you don't know what network protocol is being used on the + * socket, you should use <literal>none</literal> as the URI protocol. + * In this case, the resolver might still return a generic proxy type + * (such as SOCKS), but would not return protocol-specific proxy types + * (such as http). + * <literal>direct://</literal> is used when no proxy is needed. + * Direct connection should not be attempted unless it is part of the + * returned array of proxies. + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). + * + * Returns: (transfer full) (array zero-terminated=1): A + * Since: 2.26 */ /** - * g_input_stream_skip: - * @stream: a #GInputStream. - * @count: the number of bytes that will be skipped from the stream - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occuring, or %NULL to ignore + * g_proxy_resolver_lookup_async: + * @resolver: a #GProxyResolver + * @uri: a URI representing the destination to connect to + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): callback to call after resolution completes + * @user_data: (closure): data for @callback * - * Tries to skip @count bytes from the stream. Will block during the operation. - * This is identical to g_input_stream_read(), from a behaviour standpoint, - * but the bytes that are skipped are not returned to the user. Some - * streams have an implementation that is more efficient than reading the data. - * This function is optional for inherited classes, as the default implementation - * emulates it using read. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more + * details. * - * Returns: Number of bytes skipped, or -1 on error + * Since: 2.26 */ /** - * g_mount_operation_set_password_save: - * @op: a #GMountOperation. - * @save: a set of #GPasswordSave flags. + * g_proxy_resolver_lookup_finish: + * @resolver: a #GProxyResolver + * @result: the result passed to your #GAsyncReadyCallback + * @error: return location for a #GError, or %NULL * - * Sets the state of saving passwords for the mount operation. + * Call this function to obtain the array of proxy URIs when + * g_proxy_resolver_lookup_async() is complete. See + * g_proxy_resolver_lookup() for more details. + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). + * + * Returns: (transfer full) (array zero-terminated=1): A + * Since: 2.26 */ /** - * g_app_info_launch_default_for_uri: - * @uri: the uri to show - * @launch_context: (allow-none): an optional #GAppLaunchContext. - * @error: a #GError. + * g_proxy_supports_hostname: + * @proxy: a #GProxy * - * Utility function that launches the default application - * registered to handle the specified uri. Synchronous I/O - * is done on the uri to detect the type of the file if - * required. + * Some proxy protocols expect to be passed a hostname, which they + * will resolve to an IP address themselves. Others, like SOCKS4, do + * not allow this. This function will return %FALSE if @proxy is + * implementing such a protocol. When %FALSE is returned, the caller + * should resolve the destination hostname first, and then pass a + * #GProxyAddress containing the stringified IP address to + * g_proxy_connect() or g_proxy_connect_async(). * - * Returns: %TRUE on success, %FALSE on error. + * Returns: %TRUE if hostname resolution is supported. + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME: + * g_renew: + * @struct_type: the type of the elements to allocate + * @mem: the currently allocated memory + * @n_structs: the number of elements to allocate * - * A key in the "standard" namespace for edit name of the file. - * An edit name is similar to the display name, but it is meant to be - * used when you want to rename the file in the UI. The display name - * might contain information you don't want in the new filename (such as - * "(invalid unicode)" if the filename was in an invalid encoding). - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * Reallocates the memory pointed to by @mem, so that it now has space for + * the memory, which may have been moved. + * Care is taken to avoid overflow when calculating the size of the allocated block. + * + * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type */ /** - * GZlibCompressorFormat: - * @G_ZLIB_COMPRESSOR_FORMAT_ZLIB: deflate compression with zlib header - * @G_ZLIB_COMPRESSOR_FORMAT_GZIP: gzip file format - * @G_ZLIB_COMPRESSOR_FORMAT_RAW: deflate compression with no header + * g_resolver_error_quark: * - * Used to select the type of data format to use for #GZlibDecompressor - * and #GZlibCompressor. + * Gets the #GResolver Error Quark. * - * Since: 2.24 + * Returns: a #GQuark. + * Since: 2.22 */ /** - * G_TYPE_PARAM_VALUE_ARRAY: + * g_resolver_free_addresses: (skip) + * @addresses: a #GList of #GInetAddress * - * The #GType of #GParamSpecValueArray. + * Frees @addresses (which should be the return value from + * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()). + * (This is a convenience method; you can also simply free the results + * by hand.) + * + * Since: 2.22 */ /** - * g_buffered_input_stream_fill_finish: - * @stream: a #GBufferedInputStream - * @result: a #GAsyncResult - * @error: a #GError + * g_resolver_free_targets: (skip) + * @targets: a #GList of #GSrvTarget * - * Finishes an asynchronous read. + * Frees @targets (which should be the return value from + * g_resolver_lookup_service() or g_resolver_lookup_service_finish()). + * (This is a convenience method; you can also simply free the + * results by hand.) * - * Returns: a #gssize of the read stream, or %-1 on an error. + * Since: 2.22 */ /** - * G_DEFINE_INTERFACE_WITH_CODE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. - * @_C_: Custom code that gets inserted in the *_get_type() function. + * g_resolver_get_default: * - * A convenience macro for #GTypeInterface definitions. Similar to - * G_DEFINE_INTERFACE(), but allows you to insert custom code into the - * *_get_type() function, e.g. additional interface implementations - * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See - * G_DEFINE_TYPE_EXTENDED() for a similar example using - * G_DEFINE_TYPE_WITH_CODE(). + * Gets the default #GResolver. You should unref it when you are done + * with it. #GResolver may use its reference count as a hint about how + * many threads/processes, etc it should allocate for concurrent DNS + * resolutions. * - * Since: 2.24 + * Returns: (transfer full): the default #GResolver. + * Since: 2.22 */ /** - * g_file_info_set_name: - * @info: a #GFileInfo. - * @name: a string containing a name. + * g_resolver_lookup_by_address: + * @resolver: a #GResolver + * @address: the address to reverse-resolve + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: return location for a #GError, or %NULL * - * Sets the name attribute for the current #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_NAME. - */ - - -/** - * GMainContext: + * Synchronously reverse-resolves @address to determine its + * associated hostname. + * If the DNS resolution fails, @error (if non-%NULL) will be set to + * a value from #GResolverError. + * If @cancellable is non-%NULL, it can be used to cancel the + * operation, in which case @error (if non-%NULL) will be set to + * %G_IO_ERROR_CANCELLED. + * form), or %NULL on error. * - * The <structname>GMainContext</structname> struct is an opaque data - * type representing a set of sources to be handled in a main loop. + * Returns: a hostname (either ASCII-only, or in ASCII-encoded + * Since: 2.22 */ /** - * g_socket_address_new_from_native: - * @native: a pointer to a <type>struct sockaddr</type> - * @len: the size of the memory location pointed to by @native + * g_resolver_lookup_by_address_async: + * @resolver: a #GResolver + * @address: the address to reverse-resolve + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): callback to call after resolution completes + * @user_data: (closure): data for @callback * - * Creates a #GSocketAddress subclass corresponding to the native - * <type>struct sockaddr</type> @native. - * otherwise %NULL. + * Begins asynchronously reverse-resolving @address to determine its + * associated hostname, and eventually calls @callback, which must + * call g_resolver_lookup_by_address_finish() to get the final result. * - * Returns: a new #GSocketAddress if @native could successfully be converted, * Since: 2.22 */ /** - * GResolverError: - * @G_RESOLVER_ERROR_NOT_FOUND: the requested name/address/service was not found - * @G_RESOLVER_ERROR_TEMPORARY_FAILURE: the requested information could not be looked up due to a network error or similar problem - * @G_RESOLVER_ERROR_INTERNAL: unknown error + * g_resolver_lookup_by_address_finish: + * @resolver: a #GResolver + * @result: the result passed to your #GAsyncReadyCallback + * @error: return location for a #GError, or %NULL * - * An error code used with %G_RESOLVER_ERROR in a #GError returned - * from a #GResolver routine. + * Retrieves the result of a previous call to + * g_resolver_lookup_by_address_async(). + * If the DNS resolution failed, @error (if non-%NULL) will be set to + * a value from #GResolverError. If the operation was cancelled, + * form), or %NULL on error. * + * Returns: a hostname (either ASCII-only, or in ASCII-encoded * Since: 2.22 */ /** - * g_drive_start_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_resolver_lookup_by_name: + * @resolver: a #GResolver + * @hostname: the hostname to look up + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: return location for a #GError, or %NULL * - * Finishes starting a drive. - * %FALSE otherwise. + * Synchronously resolves @hostname to determine its associated IP + * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or + * the textual form of an IP address (in which case this just becomes + * a wrapper around g_inet_address_new_from_string()). + * On success, g_resolver_lookup_by_name() will return a #GList of + * #GInetAddress, sorted in order of preference. (That is, you should + * attempt to connect to the first address first, then the second if + * the first fails, etc.) + * If the DNS resolution fails, @error (if non-%NULL) will be set to a + * value from #GResolverError. + * If @cancellable is non-%NULL, it can be used to cancel the + * operation, in which case @error (if non-%NULL) will be set to + * %G_IO_ERROR_CANCELLED. + * If you are planning to connect to a socket on the resolved IP + * address, it may be easier to create a #GNetworkAddress and use its + * #GSocketConnectable interface. + * of #GInetAddress, or %NULL on error. You + * must unref each of the addresses and free the list when you are + * done with it. (You can use g_resolver_free_addresses() to do this.) * - * Returns: %TRUE if the drive has been started successfully, + * Returns: (element-type GInetAddress) (transfer full): a #GList * Since: 2.22 */ /** - * GTypeDebugFlags: - * @G_TYPE_DEBUG_NONE: Print no messages. - * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping. - * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions. - * @G_TYPE_DEBUG_MASK: Mask covering all debug flags. + * g_resolver_lookup_by_name_async: + * @resolver: a #GResolver + * @hostname: the hostname to look up the address of + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): callback to call after resolution completes + * @user_data: (closure): data for @callback * - * The <type>GTypeDebugFlags</type> enumeration values can be passed to - * g_type_init_with_debug_flags() to trigger debugging messages during runtime. - * Note that the messages can also be triggered by setting the - * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of - * "objects" and "signals". + * Begins asynchronously resolving @hostname to determine its + * associated IP address(es), and eventually calls @callback, which + * must call g_resolver_lookup_by_name_finish() to get the result. + * See g_resolver_lookup_by_name() for more details. + * + * Since: 2.22 */ /** - * g_settings_range_check: - * @settings: a #GSettings - * @key: the key to check - * @value: the value to check - * @returns: %TRUE if @value is valid for @key + * g_resolver_lookup_by_name_finish: + * @resolver: a #GResolver + * @result: the result passed to your #GAsyncReadyCallback + * @error: return location for a #GError, or %NULL * - * Checks if the given @value is of the correct type and within the - * permitted range for @key. - * This API is not intended to be used by normal programs -- they should - * already know what is permitted by their own schemas. This API is - * meant to be used by programs such as editors or commandline tools. - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. + * Retrieves the result of a call to + * g_resolver_lookup_by_name_async(). + * If the DNS resolution failed, @error (if non-%NULL) will be set to + * a value from #GResolverError. If the operation was cancelled, + * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() + * for more details. * - * Since: 2.28 + * Returns: (element-type GInetAddress) (transfer full): a #GList + * Since: 2.22 */ /** - * g_socket_set_keepalive: - * @socket: a #GSocket. - * @keepalive: Value for the keepalive flag + * g_resolver_lookup_service: + * @resolver: a #GResolver + * @service: the service type to look up (eg, "ldap") + * @protocol: the networking protocol to use for @service (eg, "tcp") + * @domain: the DNS domain to look up the service in + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: return location for a #GError, or %NULL * - * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When - * this flag is set on a socket, the system will attempt to verify that the - * remote socket endpoint is still present if a sufficiently long period of - * time passes with no data being exchanged. If the system is unable to - * verify the presence of the remote endpoint, it will automatically close - * the connection. - * This option is only functional on certain kinds of sockets. (Notably, - * %G_SOCKET_PROTOCOL_TCP sockets.) - * The exact time between pings is system- and protocol-dependent, but will - * normally be at least two hours. Most commonly, you would set this flag - * on a server socket if you want to allow clients to remain idle for long - * periods of time, but also want to ensure that connections are eventually - * garbage-collected if clients crash or become unreachable. + * Synchronously performs a DNS SRV lookup for the given @service and + * include the leading underscore that appears in the actual DNS + * entry. + * On success, g_resolver_lookup_service() will return a #GList of + * #GSrvTarget, sorted in order of preference. (That is, you should + * attempt to connect to the first target first, then the second if + * the first fails, etc.) + * If the DNS resolution fails, @error (if non-%NULL) will be set to + * a value from #GResolverError. + * If @cancellable is non-%NULL, it can be used to cancel the + * operation, in which case @error (if non-%NULL) will be set to + * %G_IO_ERROR_CANCELLED. + * If you are planning to connect to the service, it is usually easier + * to create a #GNetworkService and use its #GSocketConnectable + * interface. + * or %NULL on error. You must free each of the targets and the list when you are + * done with it. (You can use g_resolver_free_targets() to do this.) * + * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, * Since: 2.22 */ /** - * SECTION:gprox: - * @short_description: Interface for proxy handling + * g_resolver_lookup_service_async: + * @resolver: a #GResolver + * @service: the service type to look up (eg, "ldap") + * @protocol: the networking protocol to use for @service (eg, "tcp") + * @domain: the DNS domain to look up the service in + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): callback to call after resolution completes + * @user_data: (closure): data for @callback * - * A #GProxy handles connecting to a remote host via a given type of - * proxy server. It is implemented by the 'gio-proxy' extension point. - * The extensions are named after their proxy protocol name. As an - * example, a SOCKS5 proxy implementation can be retrieved with the - * name 'socks5' using the function - * g_io_extension_point_get_extension_by_name(). + * Begins asynchronously performing a DNS SRV lookup for the given + * get the final result. See g_resolver_lookup_service() for more + * details. * - * Since: 2.26 + * Since: 2.22 */ /** - * G_IS_PARAM_SPEC_STRING: - * @pspec: a valid #GParamSpec instance + * g_resolver_lookup_service_finish: + * @resolver: a #GResolver + * @result: the result passed to your #GAsyncReadyCallback + * @error: return location for a #GError, or %NULL * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. + * Retrieves the result of a previous call to + * g_resolver_lookup_service_async(). + * If the DNS resolution failed, @error (if non-%NULL) will be set to + * a value from #GResolverError. If the operation was cancelled, + * or %NULL on error. See g_resolver_lookup_service() for more details. * - * Returns: %TRUE on success. + * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, + * Since: 2.22 */ /** - * g_unix_fd_message_steal_fds: - * @message: a #GUnixFDMessage - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * g_resolver_set_default: + * @resolver: the new default #GResolver * - * Returns the array of file descriptors that is contained in this - * object. - * After this call, the descriptors are no longer contained in - * descriptors have been added). - * The return result of this function must be freed with g_free(). - * The caller is also responsible for closing all of the file - * descriptors. - * If @length is non-%NULL then it is set to the number of file - * descriptors in the returned array. The returned array is also - * terminated with -1. - * This function never returns %NULL. In case there are no file - * descriptors contained in @message, an empty array is returned. - * descriptors + * Sets @resolver to be the application's default resolver (reffing + * Future calls to g_resolver_get_default() will return this resolver. + * This can be used if an application wants to perform any sort of DNS + * caching or "pinning"; it can implement its own #GResolver that + * calls the original default resolver for DNS operations, and + * implements its own cache policies on top of that, and then set + * itself as the default resolver for all later code to use. * - * Returns: (array length=length) (transfer full): an array of file * Since: 2.22 */ /** - * G_TYPE_POINTER: + * g_seekable_can_seek: + * @seekable: a #GSeekable. * - * The fundamental type corresponding to #gpointer. + * Tests if the stream supports the #GSeekableIface. + * + * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise. */ /** - * G_VOLUME_IDENTIFIER_KIND_UUID: + * g_seekable_can_truncate: + * @seekable: a #GSeekable. * - * The string used to obtain a UUID with g_volume_get_identifier(). + * Tests if the stream can be truncated. + * + * Returns: %TRUE if the stream can be truncated, %FALSE otherwise. */ /** - * G_VARIANT_TYPE_UNIT: + * g_seekable_seek: + * @seekable: a #GSeekable. + * @offset: a #goffset. + * @type: a #GSeekType. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * The empty tuple type. Has only one instance. Known also as "triv" - * or "void". + * Seeks in the stream by the given @offset, modified by @type. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * has occurred, this function will return %FALSE and set @error + * appropriately if present. + * + * Returns: %TRUE if successful. If an error */ /** - * g_file_enumerator_next_file: - * @enumerator: a #GFileEnumerator. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occuring, or %NULL to ignore + * g_seekable_tell: + * @seekable: a #GSeekable. * - * Returns information for the next file in the enumerated object. - * Will block until the information is available. The #GFileInfo - * returned from this function will contain attributes that match the - * attribute string that was passed when the #GFileEnumerator was created. - * On error, returns %NULL and sets @error to the error. If the - * enumerator is at the end, %NULL will be returned and @error will - * be unset. - * Free the returned object with g_object_unref() when no longer needed. + * Tells the current position within the stream. * - * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator. + * Returns: the offset from the beginning of the buffer. */ /** - * g_unix_fd_list_get_length: - * @list: a #GUnixFDList + * g_seekable_truncate: + * @seekable: a #GSeekable. + * @offset: a #goffset. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * contained within). + * Truncates a stream with a given #offset. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an + * operation was partially finished when the operation was cancelled the + * partial result will be returned, without an error. + * has occurred, this function will return %FALSE and set @error + * appropriately if present. * - * Gets the length of @list (ie: the number of file descriptors - * Returns: the length of @list - * Since: 2.24 + * Virtual: truncate_fn + * Returns: %TRUE if successful. If an error */ /** - * GTypePluginClass: - * @use_plugin: Increases the use count of the plugin. - * @unuse_plugin: Decreases the use count of the plugin. - * @complete_type_info: Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. - * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. + * g_settings_apply: + * @settings: a #GSettings instance * - * The #GTypePlugin interface is used by the type system in order to handle - * the lifecycle of dynamically loaded types. + * Applies any changes that have been made to the settings. This + * function does nothing unless @settings is in 'delay-apply' mode; + * see g_settings_delay(). In the normal case settings are always + * applied immediately. */ /** - * GDBusServerClass: - * @new_connection: Signal class handler for the #GDBusServer::new-connection signal. + * g_settings_backend_changed: + * @backend: a #GSettingsBackend implementation + * @key: the name of the key + * @origin_tag: the origin tag * - * Class structure for #GDBusServer. + * Signals that a single key has possibly changed. Backend + * implementations should call this if a key has possibly changed its + * value. + * '//', and not ending with a slash). + * The implementation must call this function during any call to + * g_settings_backend_write(), before the call returns (except in the + * case that no keys are actually changed and it cares to detect this + * fact). It may not rely on the existence of a mainloop for + * dispatching the signal later. + * The implementation may call this function at any other time it likes + * in response to other events (such as changes occuring outside of the + * program). These calls may originate from a mainloop or may originate + * in response to any other action (including from calls to + * g_settings_backend_write()). + * In the case that this call is in response to a call to + * g_settings_backend_write() then @origin_tag must be set to the same + * value that was passed to that call. * * Since: 2.26 */ /** - * g_socket_speaks_ipv4: - * @socket: a #GSocket + * g_settings_backend_changed_tree: + * @backend: a #GSettingsBackend implementation + * @tree: a #GTree containing the changes + * @origin_tag: the origin tag * - * Checks if a socket is capable of speaking IPv4. - * IPv4 sockets are capable of speaking IPv4. On some operating systems - * and under some combinations of circumstances IPv6 sockets are also - * capable of speaking IPv4. See RFC 3493 section 3.7 for more - * information. - * No other types of sockets are currently considered as being capable - * of speaking IPv4. + * This call is a convenience wrapper. It gets the list of changes from + * g_settings_backend_changed(). * - * Returns: %TRUE if this socket can be used with IPv4. - * Since: 2.22 + * Since: 2.26 */ /** - * g_dbus_message_set_message_type: - * @message: A #GDBusMessage. - * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). + * g_settings_backend_flatten_tree: + * @tree: a #GTree containing the changes + * @path: (out): the location to save the path + * @keys: (out) (transfer container) (array zero-terminated=1): the location to save the relative keys + * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): the location to save the values, or %NULL * - * Sets @message to be of @type. + * Calculate the longest common prefix of all keys in a tree and write + * out an array of the key names relative to that prefix and, + * optionally, the value to store at each of those keys. + * You must free the value returned in @path, @keys and @values using + * g_free(). You should not attempt to free or unref the contents of * * Since: 2.26 */ /** - * G_TYPE_GTYPE: + * g_settings_backend_get_default: + * @returns: (transfer full): the default #GSettingsBackend * - * The type for #GType. - */ - - -/** - * G_VARIANT_TYPE: - * @type_string: a well-formed #GVariantType type string + * Returns the default #GSettingsBackend. It is possible to override + * the default by setting the <envar>GSETTINGS_BACKEND</envar> + * environment variable to the name of a settings backend. + * The user gets a reference to the backend. * - * Converts a string to a const #GVariantType. Depending on the - * current debugging level, this function may perform a runtime check - * to ensure that @string is a valid GVariant type string. - * It is always a programmer error to use this macro with an invalid - * type string. - * Since 2.24 + * Since: 2.28 */ /** - * G_TYPE_REGEX: + * g_settings_backend_keys_changed: + * @backend: a #GSettingsBackend implementation + * @path: the path containing the changes + * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys + * @origin_tag: the origin tag * - * The #GType for a boxed type holding a #GRegex reference. + * Signals that a list of keys have possibly changed. Backend + * implementations should call this if keys have possibly changed their + * values. + * not containing '//'). Each string in @items must form a valid key + * end with '/' and must not contain '//'). + * The meaning of this signal is that any of the key names resulting + * from the contatenation of @path with each item in @items may have + * changed. + * The same rules for when notifications must occur apply as per + * g_settings_backend_changed(). These two calls can be used + * interchangeably if exactly one item has changed (although in that + * case g_settings_backend_changed() is definitely preferred). + * For efficiency reasons, the implementation should strive for @path to + * keys that were changed) but this is not strictly required. * - * Since: 2.14 + * Name when @path is prefixed to it (ie: each item must not start or + * Be as long as possible (ie: the longest common prefix of all of the + * Since: 2.26 */ /** - * GAction:enabled: + * g_settings_backend_path_changed: + * @backend: a #GSettingsBackend implementation + * @path: the path containing the changes + * @origin_tag: the origin tag * - * If @action is currently enabled. - * If the action is disabled then calls to g_action_activate() and - * g_action_set_state() have no effect. + * Signals that all keys below a given path may have possibly changed. + * Backend implementations should call this if an entire path of keys + * have possibly changed their values. + * not containing '//'). + * The meaning of this signal is that any of the key which has a name + * starting with @path may have changed. + * The same rules for when notifications must occur apply as per + * g_settings_backend_changed(). This call might be an appropriate + * reasponse to a 'reset' call but implementations are also free to + * explicitly list the keys that were affected by that call if they can + * easily do so. + * For efficiency reasons, the implementation should strive for @path to + * keys that were changed) but this is not strictly required. As an + * example, if this function is called with the path of "/" then every + * single key in the application will be notified of a possible change. * - * Since: 2.28 + * Be as long as possible (ie: the longest common prefix of all of the + * Since: 2.26 */ /** - * G_TYPE_INT64: + * g_settings_backend_path_writable_changed: + * @backend: a #GSettingsBackend implementation + * @path: the name of the path * - * The fundamental type corresponding to #gint64. + * Signals that the writability of all keys below a given path may have + * changed. + * Since GSettings performs no locking operations for itself, this call + * will always be made in response to external events. + * + * Since: 2.26 */ /** - * G_TIME_SPAN_MILLISECOND: + * g_settings_backend_writable_changed: + * @backend: a #GSettingsBackend implementation + * @key: the name of the key * - * Evaluates to a time span of one millisecond. + * Signals that the writability of a single key has possibly changed. + * Since GSettings performs no locking operations for itself, this call + * will always be made in response to external events. * * Since: 2.26 */ /** - * GAction:name: + * g_settings_bind: + * @settings: a #GSettings object + * @key: the key to bind + * @object: (type GObject.Object): a #GObject + * @property: the name of the property to bind + * @flags: flags for the binding * - * The name of the action. This is mostly meaningful for identifying - * the action once it has been added to a #GActionGroup. + * Create a binding between the @key in the @settings object + * and the property @property of @object. + * The binding uses the default GIO mapping functions to map + * between the settings and property values. These functions + * handle booleans, numeric types and string types in a + * straightforward way. Use g_settings_bind_with_mapping() if + * you need a custom mapping, or map between types that are not + * supported by the default mapping functions. + * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this + * function also establishes a binding between the writability of + * a boolean property by that name). See g_settings_bind_writable() + * for more details about writable bindings. + * Note that the lifecycle of the binding is tied to the object, + * and that you can have only one binding per object property. + * If you bind the same property twice on the same object, the second + * binding overrides the first one. * - * Since: 2.28 + * Since: 2.26 */ /** - * g_io_stream_splice_async: - * @stream1: a #GIOStream. - * @stream2: a #GIOStream. - * @flags: a set of #GIOStreamSpliceFlags. - * @io_priority: the io priority of the request. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. + * g_settings_bind_with_mapping: (skip) + * @settings: a #GSettings object + * @key: the key to bind + * @object: (type GObject.Object): a #GObject + * @property: the name of the property to bind + * @flags: flags for the binding + * @get_mapping: a function that gets called to convert values from @settings to @object, or %NULL to use the default GIO mapping + * @set_mapping: a function that gets called to convert values from @object to @settings, or %NULL to use the default GIO mapping + * @user_data: data that gets passed to @get_mapping and @set_mapping + * @destroy: #GDestroyNotify function for @user_data * - * Asyncronously splice the output stream of @stream1 to the input stream of - * When the operation is finished @callback will be called. - * You can then call g_io_stream_splice_finish() to get the - * result of the operation. + * Create a binding between the @key in the @settings object + * and the property @property of @object. + * The binding uses the provided mapping functions to map between + * settings and property values. + * Note that the lifecycle of the binding is tied to the object, + * and that you can have only one binding per object property. + * If you bind the same property twice on the same object, the second + * binding overrides the first one. * - * Since: 2.28 + * Since: 2.26 */ /** - * g_unix_mount_guess_should_display: - * @mount_entry: a #GUnixMountEntry + * g_settings_bind_writable: + * @settings: a #GSettings object + * @key: the key to bind + * @object: (type GObject.Object): a #GObject + * @property: the name of a boolean property to bind + * @inverted: whether to 'invert' the value * - * Guesses whether a Unix mount should be displayed in the UI. + * Create a binding between the writability of @key in the + * The property must be boolean; "sensitive" or "visible" + * properties of widgets are the most likely candidates. + * Writable bindings are always uni-directional; changes of the + * writability of the setting will be propagated to the object + * property, not the other way. + * When the @inverted argument is %TRUE, the binding inverts the + * value as it passes from the setting to the object, i.e. @property + * will be set to %TRUE if the key is <emphasis>not</emphasis> + * writable. + * Note that the lifecycle of the binding is tied to the object, + * and that you can have only one binding per object property. + * If you bind the same property twice on the same object, the second + * binding overrides the first one. * - * Returns: %TRUE if @mount_entry is deemed to be displayable. + * Since: 2.26 */ /** - * g_volume_monitor_get_mount_for_uuid: - * @volume_monitor: a #GVolumeMonitor. - * @uuid: the UUID to look for + * g_settings_delay: + * @settings: a #GSettings object * - * Finds a #GMount object by its UUID (see g_mount_get_uuid()) - * Free the returned object with g_object_unref(). + * Changes the #GSettings object into 'delay-apply' mode. In this + * mode, changes to @settings are not immediately propagated to the + * backend, but kept locally until g_settings_apply() is called. * - * Returns: (transfer full): a #GMount or %NULL if no such mount is available. + * Since: 2.26 */ /** - * G_VALUE_HOLDS_INT64: - * @value: a valid #GValue structure + * g_settings_get: + * @settings: a #GSettings object + * @key: the key to get the value for + * @format: a #GVariant format string + * @...: arguments as per @format * - * Checks whether the given #GValue can hold values of type %G_TYPE_INT64. + * Gets the value that is stored at @key in @settings. + * A convenience function that combines g_settings_get_value() with + * g_variant_get(). + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings or for the #GVariantType of @format to mismatch + * the type given in the schema. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * GFileMonitor::changed: - * @monitor: a #GFileMonitor. - * @file: a #GFile. - * @other_file: a #GFile or #NULL. - * @event_type: a #GFileMonitorEvent. + * g_settings_get_boolean: + * @settings: a #GSettings object + * @key: the key to get the value for + * @returns: a boolean * - * Emitted when @file has been changed. - * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is - * #G_FILE_MONITOR_SEND_MOVED, @file will be set to a #GFile containing the - * old path, and @other_file will be set to a #GFile containing the new path. - * In all the other cases, @other_file will be set to #NULL. + * Gets the value that is stored at @key in @settings. + * A convenience variant of g_settings_get() for booleans. + * It is a programmer error to give a @key that isn't specified as + * having a boolean type in the schema for @settings. + * + * Since: 2.26 */ /** - * G_IS_PARAM_SPEC_FLAGS: - * @pspec: a valid #GParamSpec instance + * g_settings_get_child: + * @settings: a #GSettings object + * @name: the name of the 'child' schema + * @returns: (transfer full): a 'child' settings object * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. + * Creates a 'child' settings object which has a base path of + * <replaceable>base-path</replaceable>/@name, where + * <replaceable>base-path</replaceable> is the base path of @settings. + * The schema for the child settings object must have been declared + * in the schema of @settings using a <tag class="starttag">child</tag> element. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * g_file_create_readwrite_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL + * g_settings_get_double: + * @settings: a #GSettings object + * @key: the key to get the value for + * @returns: a double * - * Finishes an asynchronous file create operation started with - * g_file_create_readwrite_async(). - * Free the returned object with g_object_unref(). + * Gets the value that is stored at @key in @settings. + * A convenience variant of g_settings_get() for doubles. + * It is a programmer error to give a @key that isn't specified as + * having a 'double' type in the schema for @settings. * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. - * Since: 2.22 + * Since: 2.26 */ /** - * g_converter_output_stream_get_converter: - * @converter_stream: a #GConverterOutputStream + * g_settings_get_enum: + * @settings: a #GSettings object + * @key: the key to get the value for + * @returns: the enum value * - * Gets the #GConverter that is used by @converter_stream. + * Gets the value that is stored in @settings for @key and converts it + * to the enum value that it represents. + * In order to use this function the type of the value must be a string + * and it must be marked in the schema file as an enumerated type. + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings or is not marked as an enumerated type. + * If the value stored in the configuration database is not a valid + * value for the enumerated type then this function will return the + * default value. * - * Returns: (transfer none): the converter of the converter output stream - * Since: 2.24 + * Since: 2.26 */ /** - * G_DEFINE_POINTER_TYPE_WITH_CODE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @_C_: Custom code that gets inserted in the *_get_type() function. + * g_settings_get_flags: + * @settings: a #GSettings object + * @key: the key to get the value for + * @returns: the flags value * - * A convenience macro for pointer type implementations. - * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the - * type_name_get_type() function. + * Gets the value that is stored in @settings for @key and converts it + * to the flags value that it represents. + * In order to use this function the type of the value must be an array + * of strings and it must be marked in the schema file as an flags type. + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings or is not marked as a flags type. + * If the value stored in the configuration database is not a valid + * value for the flags type then this function will return the default + * value. * * Since: 2.26 */ /** - * g_file_monitor_set_rate_limit: - * @monitor: a #GFileMonitor. - * @limit_msecs: a non-negative integer with the limit in milliseconds to poll for changes + * g_settings_get_has_unapplied: + * @settings: a #GSettings object + * @returns: %TRUE if @settings has unapplied changes * - * Sets the rate limit to which the @monitor will report - * consecutive change events to the same file. + * Returns whether the #GSettings object has any unapplied + * changes. This can only be the case if it is in 'delayed-apply' mode. + * + * Since: 2.26 */ /** - * g_cancellable_set_error_if_cancelled: - * @cancellable: a #GCancellable object. - * @error: #GError to append error state to. + * g_settings_get_int: + * @settings: a #GSettings object + * @key: the key to get the value for + * @returns: an integer * - * If the @cancellable is cancelled, sets the error to notify - * that the operation was cancelled. + * Gets the value that is stored at @key in @settings. + * A convenience variant of g_settings_get() for 32-bit integers. + * It is a programmer error to give a @key that isn't specified as + * having a int32 type in the schema for @settings. * - * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not. + * Since: 2.26 */ /** - * g_file_create_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_settings_get_mapped: + * @settings: a #GSettings object + * @key: the key to get the value for + * @mapping: (scope call): the function to map the value in the settings database to the value used by the application + * @user_data: user data for @mapping + * @returns: (transfer full): the result, which may be %NULL * - * Finishes an asynchronous file create operation started with - * g_file_create_async(). - * Free the returned object with g_object_unref(). + * Gets the value that is stored at @key in @settings, subject to + * application-level validation/mapping. + * You should use this function when the application needs to perform + * some processing on the value of the key (for example, parsing). The + * indicates that the processing was unsuccessful (due to a parse error, + * for example) then the mapping is tried again with another value. + * This allows a robust 'fall back to defaults' behaviour to be + * implemented somewhat automatically. + * The first value that is tried is the user's setting for the key. If + * the mapping function fails to map this value, other values may be + * tried in an unspecified order (system or site defaults, translated + * schema default values, untranslated schema default values, etc). + * If the mapping function fails for all possible values, one additional + * If the mapping function still indicates failure at this point then + * the application will be aborted. + * The result parameter for the @mapping function is pointed to a + * #gpointer which is initially set to %NULL. The same pointer is given + * to each invocation of @mapping. The final value of that #gpointer is + * what is returned by this function. %NULL is valid; it is returned + * just as any other value would be. * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Attempt is made: the mapping function is called with a %NULL value. */ /** - * g_tls_connection_set_use_system_certdb: - * @conn: a #GTlsConnection - * @use_system_certdb: whether to use the system certificate database + * g_settings_get_range: + * @settings: a #GSettings + * @key: the key to query the range of + * @returns: a #GVariant describing the range * - * Sets whether @conn uses the system certificate database to verify - * peer certificates. This is %TRUE by default. If set to %FALSE, then - * peer certificate validation will always set the - * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning - * #GTlsConnection::accept-certificate will always be emitted on - * client-side connections, unless that bit is not set in - * #GTlsClientConnection:validation-flags). + * Queries the range of a key. + * This function will return a #GVariant that fully describes the range + * of values that are valid for @key. + * The type of #GVariant returned is <literal>(sv)</literal>. The + * string describes the type of range restriction in effect. The type + * and meaning of the value contained in the variant depends on the + * string. + * If the string is <literal>'type'</literal> then the variant contains + * an empty array. The element type of that empty array is the expected + * type of value and all values of that type are valid. + * If the string is <literal>'enum'</literal> then the variant contains + * an array enumerating the possible values. Each item in the array is + * a possible valid value and no other values are valid. + * If the string is <literal>'flags'</literal> then the variant contains + * an array. Each item in the array is a value that may appear zero or + * one times in an array to be used as the value for this key. For + * example, if the variant contained the array <literal>['x', + * 'y']</literal> then the valid values for the key would be + * <literal>[]</literal>, <literal>['x']</literal>, + * <literal>['y']</literal>, <literal>['x', 'y']</literal> and + * <literal>['y', 'x']</literal>. + * Finally, if the string is <literal>'range'</literal> then the variant + * contains a pair of like-typed values -- the minimum and maximum + * permissible values for this key. + * This information should not be used by normal programs. It is + * considered to be a hint for introspection purposes. Normal programs + * should already know what is permitted by their own schema. The + * format may change in any way in the future -- but particularly, new + * forms may be added to the possibilities described above. + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings. + * You should free the returned value with g_variant_unref() when it is + * no longer needed. * * Since: 2.28 */ /** - * g_mount_operation_get_password_save: - * @op: a #GMountOperation. + * g_settings_get_string: + * @settings: a #GSettings object + * @key: the key to get the value for + * @returns: a newly-allocated string * - * Gets the state of saving passwords for the mount operation. + * Gets the value that is stored at @key in @settings. + * A convenience variant of g_settings_get() for strings. + * It is a programmer error to give a @key that isn't specified as + * having a string type in the schema for @settings. * - * Returns: a #GPasswordSave flag. + * Since: 2.26 */ /** - * G_PROXY_EXTENSION_POINT_NAME: + * g_settings_get_strv: + * @settings: a #GSettings object + * @key: the key to get the value for + * @returns: (array zero-terminated=1) (transfer full): a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings. * - * Extension point for proxy functionality. - * See <link linkend="extending-gio">Extending GIO</link>. + * A convenience variant of g_settings_get() for string arrays. + * It is a programmer error to give a @key that isn't specified as + * having an array of strings type in the schema for @settings. * * Since: 2.26 */ /** - * g_tls_client_connection_get_validation_flags: - * @conn: the #GTlsClientConnection + * g_settings_get_value: + * @settings: a #GSettings object + * @key: the key to get the value for + * @returns: a new #GVariant * - * Gets @conn's validation flags + * Gets the value that is stored in @settings for @key. + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings. * - * Returns: the validation flags - * Since: 2.28 + * Since: 2.26 */ /** - * SECTION:gzcompresso: - * @short_description: Zlib compressor - * @include: gio/gio.h + * g_settings_is_writable: + * @settings: a #GSettings object + * @name: the name of a key + * @returns: %TRUE if the key @name is writable * - * #GZlibCompressor is an implementation of #GConverter that - * compresses data using zlib. + * Finds out if a key can be written or not + * + * Since: 2.26 */ /** - * g_buffered_input_stream_new: - * @base_stream: a #GInputStream + * g_settings_list_children: + * @settings: a #GSettings object + * @returns: (transfer full) (element-type utf8): a list of the children on @settings * - * Creates a new #GInputStream from the given @base_stream, with - * a buffer set to the default size (4 kilobytes). + * Gets the list of children on @settings. + * The list is exactly the list of strings for which it is not an error + * to call g_settings_get_child(). + * For GSettings objects that are lists, this value can change at any + * time and you should connect to the "children-changed" signal to watch + * request a child after listing it only for it to have been destroyed + * in the meantime. For this reason, g_settings_get_child() may return + * %NULL even for a child that was listed by this function. + * For GSettings objects that are not lists, you should probably not be + * calling this function from "normal" code (since you should already + * know what children are in your schema). This function may still be + * useful there for introspection reasons, however. + * You should free the return value with g_strfreev() when you are done + * with it. * - * Returns: a #GInputStream for the given @base_stream. + * For those changes. note that there is a race condition here: you may */ /** - * G_PARAM_SPEC_UINT: - * @pspec: a valid #GParamSpec instance + * g_settings_list_keys: + * @settings: a #GSettings object + * @returns: (transfer full) (element-type utf8): a list of the keys on @settings * - * Cast a #GParamSpec instance into a #GParamSpecUInt. + * Introspects the list of keys on @settings. + * You should probably not be calling this function from "normal" code + * (since you should already know what keys are in your schema). This + * function is intended for introspection reasons. + * You should free the return value with g_strfreev() when you are done + * with it. */ /** - * GParamFlags: - * @G_PARAM_READABLE: the parameter is readable - * @G_PARAM_WRITABLE: the parameter is writable - * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction - * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction - * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required - * @G_PARAM_STATIC_NAME: the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 - * @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8 - * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 - * @G_PARAM_PRIVATE: internal - * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26 + * g_settings_list_relocatable_schemas: * - * Through the #GParamFlags flag values, certain aspects of parameters - * can be configured. + * Gets a list of the relocatable #GSettings schemas installed on the + * system. These are schemas that do not provide their own path. It is + * usual to instantiate these schemas directly, but if you want to you + * can use g_settings_new_with_path() to specify the path. + * The output of this function, tTaken together with the output of + * g_settings_list_schemas() represents the complete list of all + * installed schemas. + * #GSettings schemas that are available. The list must not be + * modified or freed. + * + * Returns: (element-type utf8) (transfer none): a list of relocatable + * Since: 2.28 */ /** - * g_unix_connection_send_credentials: - * @connection: A #GUnixConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * g_settings_list_schemas: * - * Passes the credentials of the current user the receiving side - * of the connection. The recieving end has to call - * g_unix_connection_receive_credentials() (or similar) to accept the - * credentials. - * As well as sending the credentials this also writes a single NUL - * byte to the stream, as this is required for credentials passing to - * work on some implementations. - * Other ways to exchange credentials with a foreign peer includes the - * #GUnixCredentialsMessage type and g_socket_get_credentials() function. + * Gets a list of the #GSettings schemas installed on the system. The + * returned list is exactly the list of schemas for which you may call + * g_settings_new() without adverse effects. + * This function does not list the schemas that do not provide their own + * g_settings_new_with_path()). See + * g_settings_list_relocatable_schemas() for that. + * schemas that are available. The list must not be modified or + * freed. * - * Returns: %TRUE on success, %FALSE if @error is set. + * Paths (ie: schemas for which you must use + * Returns: (element-type utf8) (transfer none): a list of #GSettings * Since: 2.26 */ /** - * G_IS_PARAM_SPEC_VARIANT: - * @pspec: a #GParamSpec + * g_settings_new: + * @schema: the name of the schema + * @returns: a new #GSettings object * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. + * Creates a new #GSettings object with a given schema. + * Signals on the newly created #GSettings object will be dispatched + * via the thread-default #GMainContext in effect at the time of the + * call to g_settings_new(). The new #GSettings will hold a reference + * on the context. See g_main_context_push_thread_default(). * - * Returns: %TRUE on success * Since: 2.26 */ /** - * g_tls_error_quark: + * g_settings_new_with_backend: + * @schema: the name of the schema + * @backend: the #GSettingsBackend to use + * @returns: a new #GSettings object * - * Gets the TLS error quark. + * Creates a new #GSettings object with a given schema and backend. + * Creating settings objects with an different backend allows accessing settings + * from a database other than the usual one. For example, it may make + * sense to pass a backend corresponding to the "defaults" settings database on + * the system to get a settings object that modifies the system default + * settings instead of the settings for this user. * - * Returns: a #GQuark. - * Since: 2.28 + * Since: 2.26 */ /** - * g_settings_backend_changed: - * @backend: a #GSettingsBackend implementation - * @key: the name of the key - * @origin_tag: the origin tag + * g_settings_new_with_backend_and_path: + * @schema: the name of the schema + * @backend: the #GSettingsBackend to use + * @path: the path to use + * @returns: a new #GSettings object * - * Signals that a single key has possibly changed. Backend - * implementations should call this if a key has possibly changed its - * value. - * '//', and not ending with a slash). - * The implementation must call this function during any call to - * g_settings_backend_write(), before the call returns (except in the - * case that no keys are actually changed and it cares to detect this - * fact). It may not rely on the existence of a mainloop for - * dispatching the signal later. - * The implementation may call this function at any other time it likes - * in response to other events (such as changes occuring outside of the - * program). These calls may originate from a mainloop or may originate - * in response to any other action (including from calls to - * g_settings_backend_write()). - * In the case that this call is in response to a call to - * g_settings_backend_write() then @origin_tag must be set to the same - * value that was passed to that call. + * Creates a new #GSettings object with a given schema, backend and + * path. + * This is a mix of g_settings_new_with_backend() and + * g_settings_new_with_path(). * * Since: 2.26 */ /** - * g_data_input_stream_read_line_finish: - * @stream: a given #GDataInputStream. - * @result: the #GAsyncResult that was provided to the callback. - * @length: (out): a #gsize to get the length of the data read in. - * @error: #GError for error reporting. + * g_settings_new_with_path: + * @schema: the name of the schema + * @path: the path to use + * @returns: a new #GSettings object * - * Finish an asynchronous call started by - * g_data_input_stream_read_line_async(). - * (without the newlines). Set @length to a #gsize to get the - * length of the read line. On an error, it will return %NULL and - * still return %NULL, but @error won't be set. + * Creates a new #GSettings object with a given schema and path. + * You only need to do this if you want to directly create a settings + * object with a schema that doesn't have a specified path of its own. + * That's quite rare. + * It is a programmer error to call this function for a schema that + * has an explicitly specified path. * - * Returns: (transfer full): a string with the line that was read in - * Since: 2.20 + * Since: 2.26 */ /** - * g_content_type_get_icon: - * @type: a content type string + * g_settings_range_check: + * @settings: a #GSettings + * @key: the key to check + * @value: the value to check + * @returns: %TRUE if @value is valid for @key * - * Gets the icon for a content type. - * object with g_object_unref() + * Checks if the given @value is of the correct type and within the + * permitted range for @key. + * This API is not intended to be used by normal programs -- they should + * already know what is permitted by their own schemas. This API is + * meant to be used by programs such as editors or commandline tools. + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings. * - * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned + * Since: 2.28 */ /** - * G_TYPE_IO_CHANNEL: + * g_settings_reset: + * @settings: a #GSettings object + * @key: the name of a key * - * The #GType for #GIOChannel. + * Resets @key to its default value. + * This call resets the key, as much as possible, to its default value. + * That might the value specified in the schema or the one set by the + * administrator. */ /** - * g_tls_connection_handshake_finish: - * @conn: a #GTlsConnection - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous TLS handshake operation. See - * g_tls_connection_handshake() for more information. - * case @error will be set. + * g_settings_revert: + * @settings: a #GSettings instance * - * Returns: %TRUE on success, %FALSE on failure, in which - * Since: 2.28 + * Reverts all non-applied changes to the settings. This function + * does nothing unless @settings is in 'delay-apply' mode; see + * g_settings_delay(). In the normal case settings are always applied + * immediately. + * Change notifications will be emitted for affected keys. */ /** - * GInetAddress:is-mc-node-local: + * g_settings_set: + * @settings: a #GSettings object + * @key: the name of the key to set + * @format: a #GVariant format string + * @...: arguments as per @format + * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable * - * Whether this is a node-local multicast address. - * See g_inet_address_get_is_mc_node_local(). + * Sets @key in @settings to @value. + * A convenience function that combines g_settings_set_value() with + * g_variant_new(). + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings or for the #GVariantType of @format to mismatch + * the type given in the schema. * - * Since: 2.22 + * Since: 2.26 */ /** - * GInetAddress:is-site-local: + * g_settings_set_boolean: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to + * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable * - * Whether this is a site-local address. - * See g_inet_address_get_is_loopback(). + * Sets @key in @settings to @value. + * A convenience variant of g_settings_set() for booleans. + * It is a programmer error to give a @key that isn't specified as + * having a boolean type in the schema for @settings. * - * Since: 2.22 + * Since: 2.26 */ /** - * G_OPTION_REMAINING: + * g_settings_set_double: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to + * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable * - * If a long option in the main group has this name, it is not treated as a - * regular option. Instead it collects all non-option arguments which would - * otherwise be left in <literal>argv</literal>. The option must be of type - * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY - * or %G_OPTION_ARG_FILENAME_ARRAY. - * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal> - * for leftover arguments has the advantage that GOption takes care of - * necessary encoding conversions for strings or filenames. + * Sets @key in @settings to @value. + * A convenience variant of g_settings_set() for doubles. + * It is a programmer error to give a @key that isn't specified as + * having a 'double' type in the schema for @settings. * - * Since: 2.6 + * Since: 2.26 */ /** - * G_OBJECT_TYPE_NAME: - * @object: Object to return the type name for. - * - * Get the name of an object's type. - * should not be freed. + * g_settings_set_enum: + * @settings: a #GSettings object + * @key: a key, within @settings + * @value: an enumerated value + * @returns: %TRUE, if the set succeeds * - * Returns: Type name of @object. The string is owned by the type system and + * Looks up the enumerated type nick for @value and writes it to @key, + * within @settings. + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings or is not marked as an enumerated type, or for + * After performing the write, accessing @key directly with + * g_settings_get_string() will return the 'nick' associated with */ /** - * g_io_scheduler_cancel_all_jobs: + * g_settings_set_flags: + * @settings: a #GSettings object + * @key: a key, within @settings + * @value: a flags value + * @returns: %TRUE, if the set succeeds * - * Cancels all cancellable I/O jobs. - * A job is cancellable if a #GCancellable was passed into - * g_io_scheduler_push_job(). + * Looks up the flags type nicks for the bits specified by @value, puts + * them in an array of strings and writes the array to @key, withing + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings or is not marked as a flags type, or for @value + * to contain any bits that are not value for the named type. + * After performing the write, accessing @key directly with + * g_settings_get_strv() will return an array of 'nicks'; one for each + * bit in @value. */ /** - * g_unix_fd_list_new: + * g_settings_set_int: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to + * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable * - * Creates a new #GUnixFDList containing no file descriptors. + * Sets @key in @settings to @value. + * A convenience variant of g_settings_set() for 32-bit integers. + * It is a programmer error to give a @key that isn't specified as + * having a int32 type in the schema for @settings. * - * Returns: a new #GUnixFDList - * Since: 2.24 + * Since: 2.26 */ /** - * g_network_address_get_hostname: - * @addr: a #GNetworkAddress + * g_settings_set_string: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: the value to set it to + * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable * - * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, - * depending on what @addr was created with. + * Sets @key in @settings to @value. + * A convenience variant of g_settings_set() for strings. + * It is a programmer error to give a @key that isn't specified as + * having a string type in the schema for @settings. * - * Returns: @addr's hostname - * Since: 2.22 + * Since: 2.26 */ /** - * G_TYPE_PARAM_LONG: + * g_settings_set_strv: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL + * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable * - * The #GType of #GParamSpecLong. + * Sets @key in @settings to @value. + * A convenience variant of g_settings_set() for string arrays. If + * It is a programmer error to give a @key that isn't specified as + * having an array of strings type in the schema for @settings. + * + * Since: 2.26 */ /** - * GOutputStream: + * g_settings_set_value: + * @settings: a #GSettings object + * @key: the name of the key to set + * @value: a #GVariant of the correct type + * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable * - * Base class for writing output. - * All classes derived from GOutputStream should implement synchronous - * writing, splicing, flushing and closing streams, but may implement - * asynchronous versions. + * Sets @key in @settings to @value. + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings or for @value to have the incorrect type, per + * the schema. + * If @value is floating then this function consumes the reference. + * + * Since: 2.26 */ /** - * GFileOutputStream: + * g_settings_sync: * - * A subclass of GOutputStream for opened files. This adds - * a few file-specific operations and seeking and truncating. - * #GFileOutputStream implements GSeekable. + * Ensures that all pending operations for the given are complete for + * the default backend. + * Writes made to a #GSettings are handled asynchronously. For this + * reason, it is very unlikely that the changes have it to disk by the + * time g_settings_set() returns. + * This call will block until all of the writes have made it to the + * backend. Since the mainloop is not running, no change notifications + * will be dispatched during this call (but some may be queued by the + * time the call is done). */ /** - * SECTION:ginetsocketaddres: - * @short_description: Internet GSocketAddress + * g_settings_unbind: + * @object: the object + * @property: the property whose binding is removed * - * An IPv4 or IPv6 socket address; that is, the combination of a - * #GInetAddress and a port number. + * Removes an existing binding for @property on @object. + * Note that bindings are automatically removed when the + * object is finalized, so it is rarely necessary to call this + * function. + * + * Since: 2.26 */ /** - * GDBusArgInfo: - * @ref_count: The reference count or -1 if statically allocated. - * @name: Name of the argument, e.g. @unix_user_id. - * @signature: D-Bus signature of the argument (a single complete type). - * @annotations: A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations. + * g_signal_connect: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. * - * Information about an argument for a method or a signal. + * Connects a #GCallback function to a signal for a particular object. + * The handler will be called before the default handler of the signal. * - * Since: 2.26 + * Returns: the handler id */ /** - * GDrive::stop-button: - * @drive: a #GDrive. + * g_signal_connect_after: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. * - * Emitted when the physical stop button (if any) of a drive has - * been pressed. + * Connects a #GCallback function to a signal for a particular object. + * The handler will be called after the default handler of the signal. * - * Since: 2.22 + * Returns: the handler id */ /** - * SECTION:gsimplepermissio: - * @title: GSimplePermission - * @short_description: A GPermission that doesn't change value + * g_signal_connect_swapped: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. * - * #GSimplePermission is a trivial implementation of #GPermission that - * represents a permission that is either always or never allowed. The - * value is given at constuction and doesn't change. - * Calling request or release will result in errors. + * Connects a #GCallback function to a signal for a particular object. + * The instance on which the signal is emitted and @data will be swapped when + * calling the handler. + * + * Returns: the handler id */ /** - * g_bus_get_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get(). - * @error: Return location for error or %NULL. + * g_signal_handlers_block_by_func: + * @instance: The instance to block handlers from. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * Finishes an operation started with g_bus_get(). - * The returned object is a singleton, that is, shared with other - * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the - * event that you need a private message bus connection, use - * g_dbus_address_get_for_bus() and - * g_dbus_connection_new_for_address(). - * Note that the returned #GDBusConnection object will (usually) have - * the #GDBusConnection:exit-on-close property set to %TRUE. + * Blocks all handlers on an instance that match @func and @data. * - * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). - * Since: 2.26 + * Returns: The number of handlers that matched. */ /** - * g_action_group_get_action_state_hint: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query + * g_signal_handlers_disconnect_by_func: + * @instance: The instance to remove handlers from. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * Requests a hint about the valid range of values for the state of the - * named action within @action_group. - * If %NULL is returned it either means that the action is not stateful - * or that there is no hint about the valid range of values for the - * state of the action. - * If a #GVariant array is returned then each item in the array is a - * returned then the tuple specifies the inclusive lower and upper bound - * of valid values for the state. - * In any case, the information is merely a hint. It may be possible to - * have a state value outside of the hinted range and setting a value - * within the range may fail. - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. + * Disconnects all handlers on an instance that match @func and @data. * - * Possible value for the state. if a #gvariant pair (ie: two-tuple) is - * Returns: (transfer full): the state range hint - * Since: 2.28 + * Returns: The number of handlers that matched. */ /** - * g_app_info_get_name: - * @appinfo: a #GAppInfo. + * g_signal_handlers_unblock_by_func: + * @instance: The instance to unblock handlers from. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * Gets the installed name of the application. + * Unblocks all handlers on an instance that match @func and @data. * - * Returns: the name of the application for @appinfo. + * Returns: The number of handlers that matched. */ /** - * G_TYPE_HAS_VALUE_TABLE: - * @type: A #GType value. + * g_simple_action_group_insert: + * @simple: a #GSimpleActionGroup + * @action: a #GAction * - * Checks if @type has a #GTypeValueTable. + * Adds an action to the action group. + * If the action group already contains an action with the same name as + * The action group takes its own reference on @action. * - * Returns: %TRUE on success. + * Since: 2.28 */ /** - * GFileAttributeType: - * @G_FILE_ATTRIBUTE_TYPE_INVALID: indicates an invalid or uninitalized type. - * @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated UTF8 string. - * @G_FILE_ATTRIBUTE_TYPE_BYTE_STRING: a zero terminated string of non-zero bytes. - * @G_FILE_ATTRIBUTE_TYPE_BOOLEAN: a boolean value. - * @G_FILE_ATTRIBUTE_TYPE_UINT32: an unsigned 4-byte/32-bit integer. - * @G_FILE_ATTRIBUTE_TYPE_INT32: a signed 4-byte/32-bit integer. - * @G_FILE_ATTRIBUTE_TYPE_UINT64: an unsigned 8-byte/64-bit integer. - * @G_FILE_ATTRIBUTE_TYPE_INT64: a signed 8-byte/64-bit integer. - * @G_FILE_ATTRIBUTE_TYPE_OBJECT: a #GObject. - * @G_FILE_ATTRIBUTE_TYPE_STRINGV: a %NULL terminated char **. Since 2.22 + * g_simple_action_group_lookup: + * @simple: a #GSimpleActionGroup + * @action_name: the name of an action * - * The data types for file attributes. + * Looks up the action with the name @action_name in the group. + * If no such action exists, returns %NULL. + * + * Returns: (transfer none): a #GAction, or %NULL + * Since: 2.28 */ /** - * g_file_info_set_attribute_status: - * @info: a #GFileInfo - * @attribute: a file attribute key - * @status: a #GFileAttributeStatus + * g_simple_action_group_new: * - * Sets the attribute status for an attribute key. This is only - * needed by external code that implement g_file_set_attributes_from_info() - * or similar functions. - * The attribute must exist in @info for this to work. Otherwise %FALSE - * is returned and @info is unchanged. + * Creates a new, empty, #GSimpleActionGroup. * - * Returns: %TRUE if the status was changed, %FALSE if the key was not set. - * Since: 2.22 + * Returns: a new #GSimpleActionGroup + * Since: 2.28 */ /** - * g_file_info_get_etag: - * @info: a #GFileInfo. + * g_simple_action_group_remove: + * @simple: a #GSimpleActionGroup + * @action_name: the name of the action * - * Gets the <link linkend="gfile-etag">entity tag</link> for a given - * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. + * Removes the named action from the action group. + * If no action of this name is in the group then nothing happens. * - * Returns: a string containing the value of the "etag:value" attribute. + * Since: 2.28 */ /** - * G_TYPE_DBUS_METHOD_INFO: + * g_simple_action_new: + * @name: the name of the action + * @parameter_type: (allow-none): the type of parameter to the activate function * - * The #GType for a boxed type holding a #GDBusMethodInfo. + * Creates a new action. + * The created action is stateless. See g_simple_action_new_stateful(). * - * Since: 2.26 + * Returns: a new #GSimpleAction + * Since: 2.28 */ /** - * g_app_info_get_icon: - * @appinfo: a #GAppInfo. + * g_simple_action_new_stateful: + * @name: the name of the action + * @parameter_type: (allow-none): the type of the parameter to the activate function + * @state: the initial state of the action * - * Gets the icon for the application. + * Creates a new stateful action. + * must have the same #GVariantType as the initial state. + * If the @state GVariant is floating, it is consumed. * - * Returns: (transfer none): the default #GIcon for @appinfo. + * Returns: a new #GSimpleAction + * Since: 2.28 */ /** - * g_volume_get_activation_root: - * @volume: a #GVolume + * g_simple_action_set_enabled: + * @simple: a #GSimpleAction + * @enabled: whether the action is enabled * - * Gets the activation root for a #GVolume if it is known ahead of - * mount time. Returns %NULL otherwise. If not %NULL and if @volume - * is mounted, then the result of g_mount_get_root() on the - * #GMount object obtained from g_volume_get_mount() will always - * either be equal or a prefix of what this function returns. In - * other words, in code - * <programlisting> - * GMount *mount; - * GFile *mount_root - * GFile *volume_activation_root; - * mount = g_volume_get_mount (volume); /* mounted, so never NULL */ - * mount_root = g_mount_get_root (mount); - * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */ - * </programlisting> - * then the expression - * <programlisting> - * (g_file_has_prefix (volume_activation_root, mount_root) || - * </programlisting> - * will always be %TRUE. - * Activation roots are typically used in #GVolumeMonitor - * implementations to find the underlying mount to shadow, see - * g_mount_is_shadowed() for more details. - * g_object_unref() to free. + * Sets the action as enabled or not. + * An action must be enabled in order to be activated or in order to + * have its state changed from outside callers. * - * Returns: (transfer full): the activation root of @volume or %NULL. Use - * Since: 2.18 + * Since: 2.28 */ /** - * g_dbus_message_set_destination: - * @message: A #GDBusMessage. - * @value: The value to set. + * g_simple_async_report_error_in_idle: (skip) + * @object: (allow-none): a #GObject, or %NULL. + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. + * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR). + * @code: a specific error code. + * @format: a formatted error reporting string. + * @...: a list of variables to fill in @format. * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. + * Reports an error in an asynchronous function in an idle function by + * directly setting the contents of the #GAsyncResult with the given error + * information. + */ + + +/** + * g_simple_async_report_gerror_in_idle: + * @object: (allow-none): a #GObject, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. + * @error: the #GError to report * - * Since: 2.26 + * Reports an error in an idle function. Similar to + * g_simple_async_report_error_in_idle(), but takes a #GError rather + * than building a new one. */ /** - * G_TYPE_VARIANT: + * g_simple_async_report_take_gerror_in_idle: (skip) + * @object: (allow-none): a #GObject, or %NULL + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. + * @error: the #GError to report * - * The fundamental type corresponding to #GVariant. - * All floating #GVariant instances passed through the #GType system are - * consumed. - * Note that callbacks in closures, and signal handlers - * for signals of return type %G_TYPE_VARIANT, must never return floating - * variants. - * with this fundamental type in 2.26. + * Reports an error in an idle function. Similar to + * g_simple_async_report_gerror_in_idle(), but takes over the caller's + * ownership of @error, so the caller does not have to free it any more. * - * Note: GLib 2.24 did include a boxed type with this name. It was replaced - * Since: 2.26 + * Since: 2.28 */ /** - * g_volume_eject: - * @volume: a #GVolume. - * @flags: flags affecting the unmount if required for eject - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data that gets passed to @callback - * - * Ejects a volume. This is an asynchronous operation, and is - * finished by calling g_volume_eject_finish() with the @volume - * and #GAsyncResult returned in the @callback. + * g_simple_async_result_complete: + * @simple: a #GSimpleAsyncResult. * - * Deprecated: 2.22: Use g_volume_eject_with_operation() instead. + * Completes an asynchronous I/O job immediately. Must be called in + * the thread where the asynchronous result was to be delivered, as it + * invokes the callback directly. If you are in a different thread use + * g_simple_async_result_complete_in_idle(). + * Calling this function takes a reference to @simple for as long as + * is needed to complete the call. */ /** - * G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE: + * g_simple_async_result_complete_in_idle: + * @simple: a #GSimpleAsyncResult. * - * The string used to obtain a Unix device path with g_volume_get_identifier(). + * Completes an asynchronous function in an idle handler in the <link + * linkend="g-main-context-push-thread-default">thread-default main + * loop</link> of the thread that @simple was initially created in. + * Calling this function takes a reference to @simple for as long as + * is needed to complete the call. */ /** - * g_signal_handlers_unblock_by_func: - * @instance: The instance to unblock handlers from. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * g_simple_async_result_get_op_res_gboolean: + * @simple: a #GSimpleAsyncResult. * - * Unblocks all handlers on an instance that match @func and @data. + * Gets the operation result boolean from within the asynchronous result. + * if the operation's result was %FALSE. * - * Returns: The number of handlers that matched. + * Returns: %TRUE if the operation's result was %TRUE, %FALSE */ /** - * g_tls_backend_get_default: + * g_simple_async_result_get_op_res_gpointer: (skip) + * @simple: a #GSimpleAsyncResult. * - * Gets the default #GTlsBackend for the system. + * Gets a pointer result as returned by the asynchronous function. * - * Returns: a #GTlsBackend - * Since: 2.28 + * Returns: a pointer from the result. */ /** - * g_dbus_message_new: + * g_simple_async_result_get_op_res_gssize: + * @simple: a #GSimpleAsyncResult. * - * Creates a new empty #GDBusMessage. + * Gets a gssize from the asynchronous result. * - * Returns: A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 + * Returns: a gssize returned from the asynchronous function. */ /** - * g_dbus_message_get_arg0: - * @message: A #GDBusMessage. + * g_simple_async_result_get_source_tag: (skip) + * @simple: a #GSimpleAsyncResult. * - * Convenience to get the first item in the body of @message. + * Gets the source tag for the #GSimpleAsyncResult. * - * Returns: The string item or %NULL if the first item in the body of - * Since: 2.26 + * Returns: a #gpointer to the source object for the #GSimpleAsyncResult. */ /** - * g_drive_is_media_removable: - * @drive: a #GDrive. + * g_simple_async_result_is_valid: + * @result: the #GAsyncResult passed to the _finish function. + * @source: the #GObject passed to the _finish function. + * @source_tag: the asynchronous function. * - * Checks if the @drive supports removable media. + * Ensures that the data passed to the _finish function of an async + * operation is consistent. Three checks are performed. + * First, @result is checked to ensure that it is really a + * #GSimpleAsyncResult. Second, @source is checked to ensure that it + * matches the source object of @result. Third, @source_tag is + * checked to ensure that it is either %NULL (as it is when the result was + * created by g_simple_async_report_error_in_idle() or + * g_simple_async_report_gerror_in_idle()) or equal to the + * convention, is a pointer to the _async function corresponding to the + * _finish function from which this function is called). * - * Returns: %TRUE if @drive supports removable media, %FALSE otherwise. + * Returns: #TRUE if all checks passed or #FALSE if any failed. + * Since: 2.20 */ /** - * g_unix_socket_address_get_address_type: - * @address: a #GInetSocketAddress + * g_simple_async_result_new: + * @source_object: (allow-none): a #GObject, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. + * @source_tag: the asynchronous function. * - * Gets @address's type. + * Creates a #GSimpleAsyncResult. * - * Returns: a #GUnixSocketAddressType - * Since: 2.26 + * Returns: a #GSimpleAsyncResult. */ /** - * SECTION:gtlsconnectio: - * @short_description: TLS connection type - * @include: gio/gio.h + * g_simple_async_result_new_error: + * @source_object: (allow-none): a #GObject, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. + * @domain: a #GQuark. + * @code: an error code. + * @format: a string with format characters. + * @...: a list of values to insert into @format. * - * #GTlsConnection is the base TLS connection class type, which wraps - * a #GIOStream and provides TLS encryption on top of it. Its - * subclasses, #GTlsClientConnection and #GTlsServerConnection, - * implement client-side and server-side TLS, respectively. + * Creates a new #GSimpleAsyncResult with a set error. * - * Since: 2.28 + * Returns: a #GSimpleAsyncResult. */ /** - * G_PARAM_SPEC_FLAGS: - * @pspec: a valid #GParamSpec instance + * g_simple_async_result_new_from_error: + * @source_object: (allow-none): a #GObject, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @user_data: (closure): user data passed to @callback. + * @error: a #GError * - * Cast a #GParamSpec instance into a #GParamSpecFlags. + * Creates a #GSimpleAsyncResult from an error condition. + * + * Returns: a #GSimpleAsyncResult. */ /** - * g_tls_backend_get_server_connection_type: - * @backend: the #GTlsBackend + * g_simple_async_result_new_take_error: (skip) + * @source_object: (allow-none): a #GObject, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data passed to @callback + * @error: a #GError * - * Gets the #GType of @backend's #GTlsServerConnection implementation. - * implementation. + * Creates a #GSimpleAsyncResult from an error condition, and takes over the + * caller's ownership of @error, so the caller does not need to free it anymore. * - * Returns: the #GType of @backend's #GTlsServerConnection + * Returns: a #GSimpleAsyncResult * Since: 2.28 */ /** - * GTlsError: - * @G_TLS_ERROR_UNAVAILABLE: No TLS provider is available - * @G_TLS_ERROR_MISC: Miscellaneous TLS error - * @G_TLS_ERROR_BAD_CERTIFICATE: A certificate could not be parsed - * @G_TLS_ERROR_NOT_TLS: The TLS handshake failed because the peer does not seem to be a TLS server. - * @G_TLS_ERROR_HANDSHAKE: The TLS handshake failed because the peer's certificate was not acceptable. - * @G_TLS_ERROR_CERTIFICATE_REQUIRED: The TLS handshake failed because the server requested a client-side certificate, but none was provided. See g_tls_connection_set_certificate(). - * @G_TLS_ERROR_EOF: The TLS connection was closed without proper notice, which may indicate an attack. See g_tls_connection_set_require_close_notify(). + * g_simple_async_result_propagate_error: + * @simple: a #GSimpleAsyncResult. + * @dest: (out): a location to propagate the error to. * - * An error code used with %G_TLS_ERROR in a #GError returned from a - * TLS-related routine. + * Propagates an error from within the simple asynchronous result to + * a given destination. * - * Since: 2.28 + * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise. */ /** - * g_data_output_stream_put_byte: - * @stream: a #GDataOutputStream. - * @data: a #guchar. + * g_simple_async_result_run_in_thread: (skip) + * @simple: a #GSimpleAsyncResult. + * @func: a #GSimpleAsyncThreadFunc. + * @io_priority: the io priority of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. * - * Puts a byte into the output stream. - * - * Returns: %TRUE if @data was successfully added to the @stream. + * Runs the asynchronous job in a separate thread and then calls + * g_simple_async_result_complete_in_idle() on @simple to return + * the result to the appropriate main loop. + * Calling this function takes a reference to @simple for as long as + * is needed to run the job and report its completion. */ /** - * G_PRIORITY_HIGH_IDLE: + * g_simple_async_result_set_error: (skip) + * @simple: a #GSimpleAsyncResult. + * @domain: a #GQuark (usually #G_IO_ERROR). + * @code: an error code. + * @format: a formatted error reporting string. + * @...: a list of variables to fill in @format. * - * Use this for high priority idle functions. - * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, - * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is - * done to ensure that any pending resizes are processed before any - * pending redraws, so that widgets are not redrawn twice unnecessarily.) + * Sets an error within the asynchronous result without a #GError. */ /** - * G_TLS_ERROR: + * g_simple_async_result_set_error_va: (skip) + * @simple: a #GSimpleAsyncResult. + * @domain: a #GQuark (usually #G_IO_ERROR). + * @code: an error code. + * @format: a formatted error reporting string. + * @args: va_list of arguments. * - * Error domain for TLS. Errors in this domain will be from the - * #GTlsError enumeration. See #GError for more information on error - * domains. + * Sets an error within the asynchronous result without a #GError. + * Unless writing a binding, see g_simple_async_result_set_error(). */ /** - * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC: + * g_simple_async_result_set_from_error: + * @simple: a #GSimpleAsyncResult. + * @error: #GError. * - * A key in the "time" namespace for getting the miliseconds of the time - * the file was last modified. This should be used in conjunction with - * #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Sets the result from a #GError. */ /** - * g_drive_eject_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes ejecting a drive. - * %FALSE otherwise. + * g_simple_async_result_set_handle_cancellation: + * @simple: a #GSimpleAsyncResult. + * @handle_cancellation: a #gboolean. * - * Returns: %TRUE if the drive has been ejected successfully, - * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead. + * Sets whether to handle cancellation within the asynchronous operation. */ /** - * GParamSpecFloat: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30. + * g_simple_async_result_set_op_res_gboolean: + * @simple: a #GSimpleAsyncResult. + * @op_res: a #gboolean. * - * A #GParamSpec derived structure that contains the meta data for float properties. + * Sets the operation result to a boolean within the asynchronous result. */ /** - * g_app_info_can_delete: - * @appinfo: a #GAppInfo - * - * Obtains the information whether the #GAppInfo can be deleted. - * See g_app_info_delete(). + * g_simple_async_result_set_op_res_gpointer: (skip) + * @simple: a #GSimpleAsyncResult. + * @op_res: a pointer result from an asynchronous function. + * @destroy_op_res: a #GDestroyNotify function. * - * Returns: %TRUE if @appinfo can be deleted - * Since: 2.20 + * Sets the operation result within the asynchronous result to a pointer. */ /** - * GApplicationCommandLineClass: - * - * The <structname>GApplicationCommandLineClass</structname> structure contains - * private data only + * g_simple_async_result_set_op_res_gssize: + * @simple: a #GSimpleAsyncResult. + * @op_res: a #gssize. * - * Since: 2.26 + * Sets the operation result within the asynchronous result to + * the given @op_res. */ /** - * g_dbus_interface_info_generate_xml: - * @info: A #GDBusNodeInfo - * @indent: Indentation level. - * @string_builder: A #GString to to append XML data to. + * g_simple_async_result_take_error: (skip) + * @simple: a #GSimpleAsyncResult + * @error: a #GError * - * Appends an XML representation of @info (and its children) to @string_builder. - * This function is typically used for generating introspection XML - * documents at run-time for handling the - * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> - * method. + * Sets the result from @error, and takes over the caller's ownership + * of @error, so the caller does not need to free it any more. * - * Since: 2.26 + * Since: 2.28 */ /** - * GTlsConnection:base-io-stream: + * g_simple_permission_new: + * @allowed: %TRUE if the action is allowed + * @returns: the #GSimplePermission, as a #GPermission * - * The #GIOStream that the connection wraps + * Creates a new #GPermission instance that represents an action that is + * either always or never allowed. * - * Since: 2.28 + * Since: 2.26 */ /** - * g_network_service_get_service: - * @srv: a #GNetworkService + * g_socket_accept: + * @socket: a #GSocket. + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Gets @srv's service name (eg, "ldap"). + * Accept incoming connections on a connection-based socket. This removes + * the first outstanding connection request from the listening socket and + * creates a #GSocket object for it. + * The @socket must be bound to a local address with g_socket_bind() and + * must be listening for incoming connections (g_socket_listen()). + * If there are no outstanding connections then the operation will block + * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. + * To be notified of an incoming connection, wait for the %G_IO_IN condition. + * Free the returned object with g_object_unref(). * - * Returns: @srv's service name + * Returns: (transfer full): a new #GSocket, or %NULL on error. * Since: 2.22 */ /** - * G_TYPE_IS_INSTANTIATABLE: - * @type: A #GType value. + * g_socket_address_enumerator_next: + * @enumerator: a #GSocketAddressEnumerator + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: a #GError. * - * Checks if @type can be instantiated. Instantiation is the - * process of creating an instance (object) of this type. + * Retrieves the next #GSocketAddress from @enumerator. Note that this + * may block for some amount of time. (Eg, a #GNetworkAddress may need + * to do a DNS lookup before it can return an address.) Use + * g_socket_address_enumerator_next_async() if you need to avoid + * blocking. + * If @enumerator is expected to yield addresses, but for some reason + * is unable to (eg, because of a DNS error), then the first call to + * g_socket_address_enumerator_next() will return an appropriate error + * in *@error. However, if the first call to + * g_socket_address_enumerator_next() succeeds, then any further + * internal errors (other than @cancellable being triggered) will be + * ignored. + * error (in which case *@error will be set) or if there are no + * more addresses. * - * Returns: %TRUE on success. + * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on */ /** - * GThreadedSocketService::run: - * @service: the #GThreadedSocketService. - * @connection: a new #GSocketConnection object. - * @source_object: the source_object passed to g_socket_listener_add_address(). - * - * The ::run signal is emitted in a worker thread in response to an - * incoming connection. This thread is dedicated to handling - * not return until the connection is closed. + * g_socket_address_enumerator_next_async: + * @enumerator: a #GSocketAddressEnumerator + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: (closure): the data to pass to callback function * - * Returns: %TRUE to stope further signal handlers from being called + * Asynchronously retrieves the next #GSocketAddress from @enumerator + * and then calls @callback, which must call + * g_socket_address_enumerator_next_finish() to get the result. */ /** - * g_vfs_get_file_for_path: - * @vfs: a #GVfs. - * @path: a string containing a VFS path. + * g_socket_address_enumerator_next_finish: + * @enumerator: a #GSocketAddressEnumerator + * @result: a #GAsyncResult + * @error: a #GError * - * Gets a #GFile for @path. - * Free the returned object with g_object_unref(). + * Retrieves the result of a completed call to + * g_socket_address_enumerator_next_async(). See + * g_socket_address_enumerator_next() for more information about + * error handling. + * error (in which case *@error will be set) or if there are no + * more addresses. * - * Returns: (transfer full): a #GFile. + * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on */ /** - * G_TYPE_INSTANCE_GET_CLASS: - * @instance: Location of the #GTypeInstance structure. - * @g_type: The #GType of the class to be returned. - * @c_type: The C type of the class structure. + * g_socket_address_get_family: + * @address: a #GSocketAddress * - * Get the class structure of a given @instance, casted - * to a specified ancestor type @g_type of the instance. - * Note that while calling a GInstanceInitFunc(), the class pointer gets - * modified, so it might not always return the expected pointer. - * This macro should only be used in type implementations. + * Gets the socket family type of @address. * - * Returns: a pointer to the class structure + * Returns: the socket family type of @address. + * Since: 2.22 */ /** - * GInetAddress:is-mc-global: + * g_socket_address_get_native_size: + * @address: a #GSocketAddress * - * Whether this is a global multicast address. - * See g_inet_address_get_is_mc_global(). + * Gets the size of @address's native <type>struct sockaddr</type>. + * You can use this to allocate memory to pass to + * g_socket_address_to_native(). * + * Returns: the size of the native <type>struct sockaddr</type> that * Since: 2.22 */ /** - * g_unix_fd_list_append: - * @list: a #GUnixFDList - * @fd: a valid open file descriptor - * @error: a #GError pointer + * g_socket_address_new_from_native: + * @native: a pointer to a <type>struct sockaddr</type> + * @len: the size of the memory location pointed to by @native * - * Adds a file descriptor to @list. - * The file descriptor is duplicated using dup(). You keep your copy - * of the descriptor and the copy contained in @list will be closed - * when @list is finalized. - * A possible cause of failure is exceeding the per-process or - * system-wide file descriptor limit. - * The index of the file descriptor in the list is returned. If you use - * this index with g_unix_fd_list_get() then you will receive back a - * duplicated copy of the same file descriptor. - * (and @error is set) + * Creates a #GSocketAddress subclass corresponding to the native + * <type>struct sockaddr</type> @native. + * otherwise %NULL. * - * Returns: the index of the appended fd in case of success, else -1 - * Since: 2.24 + * Returns: a new #GSocketAddress if @native could successfully be converted, + * Since: 2.22 */ /** - * g_unix_mount_point_guess_name: - * @mount_point: a #GUnixMountPoint + * g_socket_address_to_native: + * @address: a #GSocketAddress + * @dest: a pointer to a memory location that will contain the native <type>struct sockaddr</type>. + * @destlen: the size of @dest. Must be at least as large as g_socket_address_get_native_size(). + * @error: #GError for error reporting, or %NULL to ignore. * - * Guesses the name of a Unix mount point. - * The result is a translated string. - * be freed with g_free() + * Converts a #GSocketAddress to a native <type>struct + * sockaddr</type>, which can be passed to low-level functions like + * connect() or bind(). + * If not enough space is availible, a %G_IO_ERROR_NO_SPACE error is + * returned. If the address type is not known on the system + * then a %G_IO_ERROR_NOT_SUPPORTED error is returned. * - * Returns: A newly allocated string that must + * Returns: %TRUE if @dest was filled in, %FALSE on error + * Since: 2.22 */ /** - * g_dbus_message_lock: - * @message: A #GDBusMessage. + * g_socket_bind: + * @socket: a #GSocket. + * @address: a #GSocketAddress specifying the local address. + * @allow_reuse: whether to allow reusing this address + * @error: #GError for error reporting, or %NULL to ignore. * - * If @message is locked, does nothing. Otherwise locks the message. + * When a socket is created it is attached to an address family, but it + * doesn't have an address in this family. g_socket_bind() assigns the + * address (sometimes called name) of the socket. + * It is generally required to bind to a local address before you can + * receive connections. (See g_socket_listen() and g_socket_accept() ). + * In certain situations, you may also want to bind a socket that will be + * used to initiate connections, though this is not normally required. + * eventually call g_socket_accept() on), and %FALSE for client sockets. + * (Specifically, if it is %TRUE, then g_socket_bind() will set the + * %SO_REUSEADDR flag on the socket, allowing it to bind @address even if + * that address was previously used by another socket that has not yet been + * fully cleaned-up by the kernel. Failing to set this flag on a server + * socket may cause the bind call to return %G_IO_ERROR_ADDRESS_IN_USE if + * the server program is stopped and then immediately restarted.) * - * Since: 2.26 + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.22 */ /** - * g_filter_input_stream_set_close_base_stream: - * @stream: a #GFilterInputStream. - * @close_base: %TRUE to close the base stream. + * g_socket_check_connect_result: + * @socket: a #GSocket + * @error: #GError for error reporting, or %NULL to ignore. * - * Sets whether the base stream will be closed when @stream is closed. + * Checks and resets the pending connect error for the socket. + * This is used to check for errors when g_socket_connect() is + * used in non-blocking mode. + * + * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error + * Since: 2.22 */ /** - * g_simple_async_result_complete: - * @simple: a #GSimpleAsyncResult. + * g_socket_client_add_application_proxy: + * @client: a #GSocketClient + * @protocol: The proxy protocol * - * Completes an asynchronous I/O job immediately. Must be called in - * the thread where the asynchronous result was to be delivered, as it - * invokes the callback directly. If you are in a different thread use - * g_simple_async_result_complete_in_idle(). - * Calling this function takes a reference to @simple for as long as - * is needed to complete the call. + * Enable proxy protocols to be handled by the application. When the + * indicated proxy protocol is returned by the #GProxyResolver, + * #GSocketClient will consider this protocol as supported but will + * not try find a #GProxy instance to handle handshaking. The + * application must check for this case by calling + * g_socket_connection_get_remote_address() on the returned + * #GSocketConnection, and seeing if it's a #GProxyAddress of the + * appropriate type, to determine whether or not it needs to handle + * the proxy handshaking itself. + * This should be used for proxy protocols that are dialects of + * another protocol such as HTTP proxy. It also allows cohabitation of + * proxy protocols that are reused between protocols. A good example + * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also + * be use as generic socket proxy through the HTTP CONNECT method. */ /** - * g_drive_get_icon: - * @drive: a #GDrive. + * g_socket_client_connect: + * @client: a #GSocketClient. + * @connectable: a #GSocketConnectable specifying the remote address. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: #GError for error reporting, or %NULL to ignore. * - * Gets the icon for @drive. - * Free the returned object with g_object_unref(). + * Tries to resolve the @connectable and make a network connection to it.. + * Upon a successful connection, a new #GSocketConnection is constructed + * and returned. The caller owns this new object and must drop their + * reference to it when finished with it. + * The type of the #GSocketConnection object returned depends on the type of + * the underlying socket that is used. For instance, for a TCP/IP connection + * it will be a #GTcpConnection. + * The socket created will be the same family as the the address that the + * or indirectly via g_socket_client_set_local_address(). The socket type + * defaults to %G_SOCKET_TYPE_STREAM but can be set with + * g_socket_client_set_socket_type(). + * If a local address is specified with g_socket_client_set_local_address() the + * socket will be bound to this address before connecting. * - * Returns: (transfer full): #GIcon for the @drive. + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * g_unix_mount_free: - * @mount_entry: a #GUnixMount. + * g_socket_client_connect_async: + * @client: a #GTcpClient + * @connectable: a #GSocketConnectable specifying the remote address. + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * Frees a unix mount. + * This is the asynchronous version of g_socket_client_connect(). + * When the operation is finished @callback will be + * called. You can then call g_socket_client_connect_finish() to get + * the result of the operation. + * + * Since: 2.22 */ /** - * g_socket_listener_add_any_inet_port: - * @listener: a #GSocketListener - * @source_object: (allow-none): Optional #GObject identifying this source + * g_socket_client_connect_finish: + * @client: a #GSocketClient. + * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Listens for TCP connections on any available port number for both - * IPv6 and IPv4 (if each are available). - * This is useful if you need to have a socket for incoming connections - * but don't care about the specific port number. - * to accept to identify this particular source, which is - * useful if you're listening on multiple addresses and do - * different things depending on what address is connected to. + * Finishes an async connect operation. See g_socket_client_connect_async() * - * Returns: the port number, or 0 in case of failure. - * Since: 2.24 + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * g_unix_mount_point_get_fs_type: - * @mount_point: a #GUnixMountPoint. + * g_socket_client_connect_to_host: + * @client: a #GSocketClient + * @host_and_port: the name and optionally port of the host to connect to + * @default_port: the default port to connect to + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: a pointer to a #GError, or %NULL * - * Gets the file system type for the mount point. + * This is a helper function for g_socket_client_connect(). + * Attempts to create a TCP connection to the named host. + * address, an IPv4 address, or a domain name (in which case a DNS + * lookup is performed). Quoting with [] is supported for all address + * types. A port override may be specified in the usual way with a + * colon. Ports may be given as decimal numbers or symbolic names (in + * which case an /etc/services lookup is performed). + * If no port override is given in @host_and_port then @default_port will be + * used as the port number to connect to. + * In general, @host_and_port is expected to be provided by the user (allowing + * them to give the hostname, and a port overide if necessary) and + * In the case that an IP address is given, a single connection + * attempt is made. In the case that a name is given, multiple + * connection attempts may be made, in turn and according to the + * number of address records in DNS, until a connection succeeds. + * Upon a successful connection, a new #GSocketConnection is constructed + * and returned. The caller owns this new object and must drop their + * reference to it when finished with it. + * In the event of any failure (DNS error, service not found, no hosts + * connectable) %NULL is returned and @error (if non-%NULL) is set + * accordingly. * - * Returns: a string containing the file system type. + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * G_TYPE_INT: + * g_socket_client_connect_to_host_async: + * @client: a #GTcpClient + * @host_and_port: the name and optionally the port of the host to connect to + * @default_port: the default port to connect to + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * The fundamental type corresponding to #gint. + * This is the asynchronous version of g_socket_client_connect_to_host(). + * When the operation is finished @callback will be + * called. You can then call g_socket_client_connect_to_host_finish() to get + * the result of the operation. + * + * Since: 2.22 */ /** - * g_file_output_stream_query_info: - * @stream: a #GFileOutputStream. - * @attributes: a file attribute query string. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_socket_client_connect_to_host_finish: + * @client: a #GSocketClient. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Queries a file output stream for the given @attributes. - * This function blocks while querying the stream. For the asynchronous - * version of this function, see g_file_output_stream_query_info_async(). - * While the stream is blocked, the stream will set the pending flag - * internally, and any other operations on the stream will fail with - * %G_IO_ERROR_PENDING. - * Can fail if the stream was already closed (with @error being set to - * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being - * set to %G_IO_ERROR_PENDING), or if querying info is not supported for - * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In - * all cases of failure, %NULL will be returned. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will - * be returned. + * Finishes an async connect operation. See g_socket_client_connect_to_host_async() * - * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error. + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * GDBusSubtreeIntrospectFunc: - * @connection: A #GDBusConnection. - * @sender: The unique bus name of the remote caller. - * @object_path: The object path that was registered with g_dbus_connection_register_subtree(). - * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree. - * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree(). + * g_socket_client_connect_to_service: + * @client: a #GSocketConnection + * @domain: a domain name + * @service: the name of the service to connect to + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: a pointer to a #GError, or %NULL + * @returns: (transfer full): a #GSocketConnection if successful, or %NULL on error * - * The type of the @introspect function in #GDBusSubtreeVTable. - * Subtrees are flat. @node, if non-%NULL, is always exactly one - * This function should return %NULL to indicate that there is no object - * at this node. - * If this function returns non-%NULL, the return value is expected to - * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo - * structures describing the interfaces implemented by @node. This - * array will have g_dbus_interface_info_unref() called on each item - * before being freed with g_free(). - * The difference between returning %NULL and an array containing zero - * items is that the standard DBus interfaces will returned to the - * remote introspector in the empty array case, but not in the %NULL - * case. + * Attempts to create a TCP connection to a service. + * This call looks up the SRV record for @service at @domain for the + * "tcp" protocol. It then attempts to connect, in turn, to each of + * the hosts providing the service until either a connection succeeds + * or there are no hosts remaining. + * Upon a successful connection, a new #GSocketConnection is constructed + * and returned. The caller owns this new object and must drop their + * reference to it when finished with it. + * In the event of any failure (DNS error, service not found, no hosts + * connectable) %NULL is returned and @error (if non-%NULL) is set + * accordingly. + */ + + +/** + * g_socket_client_connect_to_service_async: + * @client: a #GSocketClient + * @domain: a domain name + * @service: the name of the service to connect to + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * Segment of the object path (ie: it never contains a slash). - * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL. - * Since: 2.26 + * This is the asynchronous version of + * g_socket_client_connect_to_service(). + * + * Since: 2.22 */ /** - * g_data_input_stream_read_until_async: - * @stream: a given #GDataInputStream. - * @stop_chars: characters to terminate the read. - * @io_priority: the <link linkend="io-priority">I/O priority</link> 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. + * g_socket_client_connect_to_service_finish: + * @client: a #GSocketClient. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * The asynchronous version of g_data_input_stream_read_until(). - * It is an error to have two outstanding calls to this function. - * Note that, in contrast to g_data_input_stream_read_until(), - * this function does not consume the stop character that it finds. You - * must read it for yourself. - * When the operation is finished, @callback will be called. You - * can then call g_data_input_stream_read_until_finish() to get - * the result of the operation. - * Don't use this function in new code. Its functionality is - * inconsistent with g_data_input_stream_read_until(). Both functions - * will be marked as deprecated in a future release. Use - * g_data_input_stream_read_upto_async() instead. + * Finishes an async connect operation. See g_socket_client_connect_to_service_async() * - * Since: 2.20 + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * GFileAttributeStatus: - * @G_FILE_ATTRIBUTE_STATUS_UNSET: Attribute value is unset (empty). - * @G_FILE_ATTRIBUTE_STATUS_SET: Attribute value is set. - * @G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING: Indicates an error in setting the value. + * g_socket_client_connect_to_uri: + * @client: a #GSocketClient + * @uri: A network URI + * @default_port: the default port to connect to + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: a pointer to a #GError, or %NULL * - * Used by g_file_set_attributes_from_info() when setting file attributes. + * This is a helper function for g_socket_client_connect(). + * Attempts to create a TCP connection with a network URI. + * component. If a port is not specified in the URI, @default_port + * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE. + * (#GSocketClient does not know to automatically assume TLS for + * certain URI schemes.) + * Using this rather than g_socket_client_connect() or + * g_socket_client_connect_to_host() allows #GSocketClient to + * determine when to use application-specific proxy protocols. + * Upon a successful connection, a new #GSocketConnection is constructed + * and returned. The caller owns this new object and must drop their + * reference to it when finished with it. + * In the event of any failure (DNS error, service not found, no hosts + * connectable) %NULL is returned and @error (if non-%NULL) is set + * accordingly. + * + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.26 */ /** - * g_dbus_error_register_error: - * @error_domain: A #GQuark for a error domain. - * @error_code: An error code. - * @dbus_error_name: A D-Bus error name. + * g_socket_client_connect_to_uri_async: + * @client: a #GSocketClient + * @uri: a network uri + * @default_port: the default port to connect to + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * Creates an association to map between @dbus_error_name and - * #GError<!-- -->s specified by @error_domain and @error_code. - * This is typically done in the routine that returns the #GQuark for - * an error domain. - * exists. + * This is the asynchronous version of g_socket_client_connect_to_uri(). + * When the operation is finished @callback will be + * called. You can then call g_socket_client_connect_to_uri_finish() to get + * the result of the operation. * - * Returns: %TRUE if the association was created, %FALSE if it already * Since: 2.26 */ /** - * GDBusProxy::g-signal: - * @proxy: The #GDBusProxy emitting the signal. - * @sender_name: The sender of the signal or %NULL if the connection is not a bus connection. - * @signal_name: The name of the signal. - * @parameters: A #GVariant tuple with parameters for the signal. + * g_socket_client_connect_to_uri_finish: + * @client: a #GSocketClient. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * Emitted when a signal from the remote object and interface that @proxy is for, has been received. + * Finishes an async connect operation. See g_socket_client_connect_to_uri_async() * + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. * Since: 2.26 */ /** - * g_filename_completer_set_dirs_only: - * @completer: the filename completer. - * @dirs_only: a #gboolean. + * g_socket_client_get_enable_proxy: + * @client: a #GSocketClient. * - * If @dirs_only is %TRUE, @completer will only - * complete directory names, and not file names. + * Gets the proxy enable state; see g_socket_client_set_enable_proxy() + * + * Returns: whether proxying is enabled + * Since: 2.26 */ /** - * g_simple_async_report_gerror_in_idle: - * @object: (allow-none): a #GObject, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * @error: the #GError to report + * g_socket_client_get_family: + * @client: a #GSocketClient. * - * Reports an error in an idle function. Similar to - * g_simple_async_report_error_in_idle(), but takes a #GError rather - * than building a new one. + * Gets the socket family of the socket client. + * See g_socket_client_set_family() for details. + * + * Returns: a #GSocketFamily + * Since: 2.22 */ /** - * g_volume_monitor_get_mounts: - * @volume_monitor: a #GVolumeMonitor. + * g_socket_client_get_local_address: + * @client: a #GSocketClient. * - * Gets a list of the mounts on the system. - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). + * Gets the local address of the socket client. + * See g_socket_client_set_local_address() for details. * - * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects. + * Returns: (transfer none): a #GSocketAddres or %NULL. don't free + * Since: 2.22 */ /** - * g_signal_handlers_disconnect_by_func: - * @instance: The instance to remove handlers from. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * g_socket_client_get_protocol: + * @client: a #GSocketClient * - * Disconnects all handlers on an instance that match @func and @data. + * Gets the protocol name type of the socket client. + * See g_socket_client_set_protocol() for details. * - * Returns: The number of handlers that matched. + * Returns: a #GSocketProtocol + * Since: 2.22 */ /** - * g_dbus_proxy_get_connection: - * @proxy: A #GDBusProxy. + * g_socket_client_get_socket_type: + * @client: a #GSocketClient. * - * Gets the connection @proxy is for. + * Gets the socket type of the socket client. + * See g_socket_client_set_socket_type() for details. * - * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free. - * Since: 2.26 + * Returns: a #GSocketFamily + * Since: 2.22 */ /** - * g_win32_input_stream_get_close_handle: - * @stream: a #GWin32InputStream + * g_socket_client_get_timeout: + * @client: a #GSocketClient * - * Returns whether the handle of @stream will be - * closed when the stream is closed. + * Gets the I/O timeout time for sockets created by @client. + * See g_socket_client_set_timeout() for details. * - * Returns: %TRUE if the handle is closed when done + * Returns: the timeout in seconds * Since: 2.26 */ /** - * g_unix_mount_is_system_internal: - * @mount_entry: a #GUnixMount. + * g_socket_client_get_tls: + * @client: a #GSocketClient. * - * Checks if a unix mount is a system path. + * Gets whether @client creates TLS connections. See + * g_socket_client_set_tls() for details. * - * Returns: %TRUE if the unix mount is for a system path. + * Returns: whether @client uses TLS + * Since: 2.28 */ /** - * g_settings_list_keys: - * @settings: a #GSettings object - * @returns: (transfer full) (element-type utf8): a list of the keys on @settings + * g_socket_client_get_tls_validation_flags: + * @client: a #GSocketClient. * - * Introspects the list of keys on @settings. - * You should probably not be calling this function from "normal" code - * (since you should already know what keys are in your schema). This - * function is intended for introspection reasons. - * You should free the return value with g_strfreev() when you are done - * with it. + * Gets the TLS validation flags used creating TLS connections via + * + * Returns: the TLS validation flags + * Since: 2.28 */ /** - * g_file_info_get_content_type: - * @info: a #GFileInfo. + * g_socket_client_new: * - * Gets the file's content type. + * Creates a new #GSocketClient with the default options. + * Free the returned object with g_object_unref(). * - * Returns: a string containing the file's content type. + * Returns: a #GSocketClient. + * Since: 2.22 */ /** - * g_tls_client_connection_set_validation_flags: - * @conn: the #GTlsClientConnection - * @flags: the #GTlsCertificateFlags to use + * g_socket_client_set_enable_proxy: + * @client: a #GSocketClient. + * @enable: whether to enable proxies * - * Sets @conn's validation flags, to override the default set of - * checks performed when validating a server certificate. By default, - * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. + * Sets whether or not @client attempts to make connections via a + * proxy server. When enabled (the default), #GSocketClient will use a + * #GProxyResolver to determine if a proxy protocol such as SOCKS is + * needed, and automatically do the necessary proxy negotiation. * - * Since: 2.28 + * Since: 2.26 */ /** - * g_socket_address_enumerator_next_finish: - * @enumerator: a #GSocketAddressEnumerator - * @result: a #GAsyncResult - * @error: a #GError + * g_socket_client_set_family: + * @client: a #GSocketClient. + * @family: a #GSocketFamily * - * Retrieves the result of a completed call to - * g_socket_address_enumerator_next_async(). See - * g_socket_address_enumerator_next() for more information about - * error handling. - * error (in which case *@error will be set) or if there are no - * more addresses. + * Sets the socket family of the socket client. + * If this is set to something other than %G_SOCKET_FAMILY_INVALID + * then the sockets created by this object will be of the specified + * family. + * This might be useful for instance if you want to force the local + * connection to be an ipv4 socket, even though the address might + * be an ipv6 mapped to ipv4 address. * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on + * Since: 2.22 */ /** - * GTypeModule: - * @name: the name of the module + * g_socket_client_set_local_address: + * @client: a #GSocketClient. + * @address: a #GSocketAddress, or %NULL * - * The members of the <structname>GTypeModule</structname> structure should not - * be accessed directly, except for the @name field. + * Sets the local address of the socket client. + * The sockets created by this object will bound to the + * specified address (if not %NULL) before connecting. + * This is useful if you want to ensure the the local + * side of the connection is on a specific port, or on + * a specific interface. + * + * Since: 2.22 */ /** - * g_unix_socket_address_new_abstract: - * @path: (array length=path_len) (element-type gchar): the abstract name - * @path_len: the length of @path, or -1 + * g_socket_client_set_protocol: + * @client: a #GSocketClient. + * @protocol: a #GSocketProtocol * - * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED - * #GUnixSocketAddress for @path. + * Sets the protocol of the socket client. + * The sockets created by this object will use of the specified + * protocol. + * If @protocol is %0 that means to use the default + * protocol for the socket family and type. * - * Returns: a new #GUnixSocketAddress - * Deprecated: Use g_unix_socket_address_new_with_type(). + * Since: 2.22 */ /** - * GInputStream: + * g_socket_client_set_socket_type: + * @client: a #GSocketClient. + * @type: a #GSocketType * - * Base class for streaming input operations. + * Sets the socket type of the socket client. + * The sockets created by this object will be of the specified + * type. + * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, + * as GSocketClient is used for connection oriented services. + * + * Since: 2.22 */ /** - * g_file_get_child: - * @file: input #GFile. - * @name: string containing the child's basename. + * g_socket_client_set_timeout: + * @client: a #GSocketClient. + * @timeout: the timeout * - * Gets a child of @file with basename equal to @name. - * Note that the file with that specific name might not exist, but - * you can still have a #GFile that points to it. You can use this - * for instance to create that file. - * This call does no blocking i/o. - * Free the returned object with g_object_unref(). + * Sets the I/O timeout for sockets created by @client. @timeout is a + * time in seconds, or 0 for no timeout (the default). + * The timeout value affects the initial connection attempt as well, + * so setting this may cause calls to g_socket_client_connect(), etc, + * to fail with %G_IO_ERROR_TIMED_OUT. * - * Returns: (transfer full): a #GFile to a child specified by @name. + * Since: 2.26 */ /** - * g_settings_set: - * @settings: a #GSettings object - * @key: the name of the key to set - * @format: a #GVariant format string - * @...: arguments as per @format - * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * g_socket_client_set_tls: + * @client: a #GSocketClient. + * @tls: whether to use TLS * - * Sets @key in @settings to @value. - * A convenience function that combines g_settings_set_value() with - * g_variant_new(). - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or for the #GVariantType of @format to mismatch - * the type given in the schema. + * Sets whether @client creates TLS (aka SSL) connections. If @tls is + * %TRUE, @client will wrap its connections in a #GTlsClientConnection + * and perform a TLS handshake when connecting. + * Note that since #GSocketClient must return a #GSocketConnection, + * but #GTlsClientConnection is not a #GSocketConnection, this + * actually wraps the resulting #GTlsClientConnection in a + * #GTcpWrapperConnection when returning it. You can use + * g_tcp_wrapper_connection_get_base_io_stream() on the return value + * to extract the #GTlsClientConnection. * - * Since: 2.26 + * Since: 2.28 */ /** - * GFileAttributeInfoFlags: - * @G_FILE_ATTRIBUTE_INFO_NONE: no flags set. - * @G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE: copy the attribute values when the file is copied. - * @G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED: copy the attribute values when the file is moved. + * g_socket_client_set_tls_validation_flags: + * @client: a #GSocketClient. + * @flags: the validation flags * - * Flags specifying the behaviour of an attribute. + * Sets the TLS validation flags used when creating TLS connections + * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. + * + * Since: 2.28 */ /** - * G_VALUE_HOLDS_ULONG: - * @value: a valid #GValue structure + * g_socket_close: + * @socket: a #GSocket + * @error: #GError for error reporting, or %NULL to ignore. * - * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. + * Closes the socket, shutting down any active connection. + * Closing a socket does not wait for all outstanding I/O operations + * to finish, so the caller should not rely on them to be guaranteed + * to complete even if the close returns with no error. + * Once the socket is closed, all other operations will return + * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not + * return an error. + * Sockets will be automatically closed when the last reference + * is dropped, but you might want to call this function to make sure + * resources are released as early as possible. + * Beware that due to the way that TCP works, it is possible for + * recently-sent data to be lost if either you close a socket while the + * %G_IO_IN condition is set, or else if the remote connection tries to + * send something to you after you close the socket but before it has + * finished reading all of the data you sent. There is no easy generic + * way to avoid this problem; the easiest fix is to design the network + * protocol such that the client will never send data "out of turn". + * Another solution is for the server to half-close the connection by + * calling g_socket_shutdown() with only the @shutdown_write flag set, + * and then wait for the client to notice this and close its side of the + * connection, after which the server can safely call g_socket_close(). + * (This is what #GTcpConnection does if you call + * g_tcp_connection_set_graceful_disconnect(). But of course, this + * only works if the client will close its connection after the server + * does.) * - * Returns: %TRUE on success. + * Returns: %TRUE on success, %FALSE on error + * Since: 2.22 */ /** - * GUnixInputStream: + * g_socket_condition_check: + * @socket: a #GSocket + * @condition: a #GIOCondition mask to check * - * Implements #GInputStream for reading from selectable unix file descriptors + * Checks on the readiness of @socket to perform operations. + * The operations specified in @condition are checked for and masked + * against the currently-satisfied conditions on @socket. The result + * is returned. + * Note that on Windows, it is possible for an operation to return + * %G_IO_ERROR_WOULD_BLOCK even immediately after + * g_socket_condition_check() has claimed that the socket is ready for + * writing. Rather than calling g_socket_condition_check() and then + * writing to the socket if it succeeds, it is generally better to + * simply try writing to the socket right away, and try again later if + * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK. + * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition; + * these conditions will always be set in the output if they are true. + * This call never blocks. + * + * Returns: the @GIOCondition mask of the current state + * Since: 2.22 */ /** - * g_application_set_action_group: - * @application: a #GApplication - * @action_group: (allow-none): a #GActionGroup, or %NULL + * g_socket_condition_wait: + * @socket: a #GSocket + * @condition: a #GIOCondition mask to wait for + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @error: a #GError pointer, or %NULL * - * Sets or unsets the group of actions associated with the application. - * These actions are the actions that can be remotely invoked. - * It is an error to call this function after the application has been - * registered. + * Waits for @condition to become true on @socket. When the condition + * is met, %TRUE is returned. + * If @cancellable is cancelled before the condition is met, or if the + * socket has a timeout set and it is reached before the condition is + * met, then %FALSE is returned and @error, if non-%NULL, is set to + * the appropriate value (%G_IO_ERROR_CANCELLED or + * %G_IO_ERROR_TIMED_OUT). * - * Since: 2.28 + * Returns: %TRUE if the condition was met, %FALSE otherwise + * Since: 2.22 */ /** - * g_volume_mount_finish: - * @volume: a #GVolume - * @result: a #GAsyncResult - * @error: a #GError location to store an error, or %NULL to ignore + * g_socket_connect: + * @socket: a #GSocket. + * @address: a #GSocketAddress specifying the remote address. + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Finishes mounting a volume. If any errors occured during the operation, - * If the mount operation succeeded, g_volume_get_mount() on @volume - * is guaranteed to return the mount right after calling this - * function; there's no need to listen for the 'mount-added' signal on - * #GVolumeMonitor. + * Connect the socket to the specified remote address. + * For connection oriented socket this generally means we attempt to make + * a connection to the @address. For a connection-less socket it sets + * the default address for g_socket_send() and discards all incoming datagrams + * from other sources. + * Generally connection oriented sockets can only connect once, but + * connection-less sockets can connect multiple times to change the + * default address. + * If the connect call needs to do network I/O it will block, unless + * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned + * and the user can be notified of the connection finishing by waiting + * for the G_IO_OUT condition. The result of the connection can then be + * checked with g_socket_check_connect_result(). * - * Returns: %TRUE, %FALSE if operation failed. + * Returns: %TRUE if connected, %FALSE on error. + * Since: 2.22 */ /** - * g_file_find_enclosing_mount: - * @file: input #GFile. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * g_socket_connectable_enumerate: + * @connectable: a #GSocketConnectable * - * Gets a #GMount for the #GFile. - * If the #GFileIface for @file does not have a mount (e.g. possibly a - * remote share), @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL - * will be returned. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Free the returned object with g_object_unref(). + * Creates a #GSocketAddressEnumerator for @connectable. * - * Returns: (transfer full): a #GMount where the @file is located or %NULL on error. + * Returns: (transfer full): a new #GSocketAddressEnumerator. + * Since: 2.22 */ /** - * GConverterFlags: - * @G_CONVERTER_NO_FLAGS: No flags. - * @G_CONVERTER_INPUT_AT_END: At end of input data - * @G_CONVERTER_FLUSH: Flush data + * g_socket_connectable_proxy_enumerate: + * @connectable: a #GSocketConnectable * - * Flags used when calling a g_converter_convert(). + * Creates a #GSocketAddressEnumerator for @connectable that will + * return #GProxyAddress<!-- -->es for addresses that you must connect + * to via a proxy. + * If @connectable does not implement + * g_socket_connectable_proxy_enumerate(), this will fall back to + * calling g_socket_connectable_enumerate(). * - * Since: 2.24 + * Returns: (transfer full): a new #GSocketAddressEnumerator. + * Since: 2.26 */ /** - * GClassInitFunc: - * @g_class: The #GTypeClass structure to initialize. - * @class_data: The @class_data member supplied via the #GTypeInfo structure. + * g_socket_connection_factory_create_connection: + * @socket: a #GSocket * - * A callback function used by the type system to initialize the class - * of a specific type. This function should initialize all static class - * members. - * The initialization process of a class involves: - * <itemizedlist> - * <listitem><para> - * 1 - Copying common members from the parent class over to the - * derived class structure. - * </para></listitem> - * <listitem><para> - * 2 - Zero initialization of the remaining members not copied - * over from the parent class. - * </para></listitem> - * <listitem><para> - * 3 - Invocation of the GBaseInitFunc() initializers of all parent - * types and the class' type. - * </para></listitem> - * <listitem><para> - * 4 - Invocation of the class' GClassInitFunc() initializer. - * </para></listitem> - * </itemizedlist> - * Since derived classes are partially initialized through a memory copy - * of the parent class, the general rule is that GBaseInitFunc() and - * GBaseFinalizeFunc() should take care of necessary reinitialization - * and release of those class members that were introduced by the type - * that specified these GBaseInitFunc()/GBaseFinalizeFunc(). - * GClassInitFunc() should only care about initializing static - * class members, while dynamic class members (such as allocated strings - * or reference counted resources) are better handled by a GBaseInitFunc() - * for this type, so proper initialization of the dynamic class members - * is performed for class initialization of derived types as well. - * An example may help to correspond the intend of the different class - * initializers: - * |[ - * typedef struct { - * GObjectClass parent_class; - * gint static_integer; - * gchar *dynamic_string; - * } TypeAClass; - * static void - * type_a_base_class_init (TypeAClass *class) - * { - * class->dynamic_string = g_strdup ("some string"); - * } - * static void - * type_a_base_class_finalize (TypeAClass *class) - * { - * g_free (class->dynamic_string); - * } - * static void - * type_a_class_init (TypeAClass *class) - * { - * class->static_integer = 42; - * } - * typedef struct { - * TypeAClass parent_class; - * gfloat static_float; - * GString *dynamic_gstring; - * } TypeBClass; - * static void - * type_b_base_class_init (TypeBClass *class) - * { - * class->dynamic_gstring = g_string_new ("some other string"); - * } - * static void - * type_b_base_class_finalize (TypeBClass *class) - * { - * g_string_free (class->dynamic_gstring); - * } - * static void - * type_b_class_init (TypeBClass *class) - * { - * class->static_float = 3.14159265358979323846; - * } - * ]| - * Initialization of TypeBClass will first cause initialization of - * TypeAClass (derived classes reference their parent classes, see - * g_type_class_ref() on this). - * Initialization of TypeAClass roughly involves zero-initializing its fields, - * then calling its GBaseInitFunc() type_a_base_class_init() to allocate - * its dynamic members (dynamic_string), and finally calling its GClassInitFunc() - * type_a_class_init() to initialize its static members (static_integer). - * The first step in the initialization process of TypeBClass is then - * a plain memory copy of the contents of TypeAClass into TypeBClass and - * zero-initialization of the remaining fields in TypeBClass. - * The dynamic members of TypeAClass within TypeBClass now need - * reinitialization which is performed by calling type_a_base_class_init() - * with an argument of TypeBClass. - * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() - * is called to allocate the dynamic members of TypeBClass (dynamic_gstring), - * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), - * is called to complete the initialization process with the static members - * (static_float). - * Corresponding finalization counter parts to the GBaseInitFunc() functions - * have to be provided to release allocated resources at class finalization - * time. + * Creates a #GSocketConnection subclass of the right type for + * + * Returns: (transfer full): a #GSocketConnection + * Since: 2.22 */ /** - * GSocketConnection: + * g_socket_connection_factory_lookup_type: + * @family: a #GSocketFamily + * @type: a #GSocketType + * @protocol_id: a protocol id * - * A socket connection GIOStream object for connection-oriented sockets. + * Looks up the #GType to be used when creating socket connections on + * sockets with the specified @family,@type and @protocol_id. + * If no type is registered, the #GSocketConnection base type is returned. * + * Returns: a #GType * Since: 2.22 */ /** - * g_settings_set_double: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * g_socket_connection_factory_register_type: + * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION + * @family: a #GSocketFamily + * @type: a #GSocketType + * @protocol: a protocol id * - * Sets @key in @settings to @value. - * A convenience variant of g_settings_set() for doubles. - * It is a programmer error to give a @key that isn't specified as - * having a 'double' type in the schema for @settings. + * Looks up the #GType to be used when creating socket connections on + * sockets with the specified @family,@type and @protocol. + * If no type is registered, the #GSocketConnection base type is returned. * - * Since: 2.26 + * Since: 2.22 */ /** - * GOptionContext: + * g_socket_connection_get_local_address: + * @connection: a #GSocketConnection + * @error: #GError for error reporting, or %NULL to ignore. * - * A <structname>GOptionContext</structname> struct defines which options - * are accepted by the commandline option parser. The struct has only private - * fields and should not be directly accessed. + * Try to get the local address of a socket connection. + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Since: 2.22 */ /** - * GThemedIcon:name: + * g_socket_connection_get_remote_address: + * @connection: a #GSocketConnection + * @error: #GError for error reporting, or %NULL to ignore. * - * The icon name. + * Try to get the remote address of a socket connection. + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Since: 2.22 */ /** - * GTlsClientConnection:accepted-cas: + * g_socket_connection_get_socket: + * @connection: a #GSocketConnection * - * A list of the distinguished names of the Certificate Authorities - * that the server will accept client certificates signed by. If the - * server requests a client certificate during the handshake, then - * this property will be set after the handshake completes. - * Each item in the list is a #GByteArray which contains the complete - * subject DN of the certificate authority. + * Gets the underlying #GSocket object of the connection. + * This can be useful if you want to do something unusual on it + * not supported by the #GSocketConnection APIs. * - * Since: 2.28 + * Returns: (transfer none): a #GSocketAddress or %NULL on error. + * Since: 2.22 */ /** - * g_data_output_stream_set_byte_order: - * @stream: a #GDataOutputStream. - * @order: a %GDataStreamByteOrder. + * g_socket_control_message_deserialize: + * @level: a socket level + * @type: a socket control message type for the given @level + * @size: the size of the data in bytes + * @data: (array length=size) (element-type guint8): pointer to the message data * - * Sets the byte order of the data output stream to @order. + * Tries to deserialize a socket control message of a given + * of #GSocketControlMessage if they can understand this kind + * of message and if so deserialize it into a #GSocketControlMessage. + * If there is no implementation for this kind of control message, %NULL + * will be returned. + * + * Returns: (transfer full): the deserialized message or %NULL + * Since: 2.22 */ /** - * G_VALUE_TYPE_NAME: - * @value: A #GValue structure. + * g_socket_control_message_get_level: + * @message: a #GSocketControlMessage * - * Gets the the type name of @value. + * Returns the "level" (i.e. the originating protocol) of the control message. + * This is often SOL_SOCKET. * - * Returns: the type name. + * Returns: an integer describing the level + * Since: 2.22 */ /** - * g_inet_address_to_string: - * @address: a #GInetAddress + * g_socket_control_message_get_msg_type: + * @message: a #GSocketControlMessage * - * Converts @address to string form. - * freed after use. + * Returns the protocol specific type of the control message. + * For instance, for UNIX fd passing this would be SCM_RIGHTS. * - * Returns: a representation of @address as a string, which should be + * Returns: an integer describing the type of control message * Since: 2.22 */ /** - * g_settings_set_strv: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL - * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * g_socket_control_message_get_size: + * @message: a #GSocketControlMessage * - * Sets @key in @settings to @value. - * A convenience variant of g_settings_set() for string arrays. If - * It is a programmer error to give a @key that isn't specified as - * having an array of strings type in the schema for @settings. + * Returns the space required for the control message, not including + * headers or alignment. * - * Since: 2.26 + * Returns: The number of bytes required. + * Since: 2.22 */ /** - * g_dbus_method_invocation_return_error_valist: - * @invocation: A #GDBusMethodInvocation. - * @domain: A #GQuark for the #GError error domain. - * @code: The error code. - * @format: printf()-style format. - * @var_args: #va_list of parameters for @format. + * g_socket_control_message_serialize: + * @message: a #GSocketControlMessage + * @data: A buffer to write data to * - * Like g_dbus_method_invocation_return_error() but intended for - * language bindings. - * This method will free @invocation, you cannot use it afterwards. + * Converts the data in the message to bytes placed in the + * message. + * returned by g_socket_control_message_get_size() on this + * object. * - * Since: 2.26 + * Since: 2.22 */ /** - * g_action_group_action_state_changed: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group - * @state: the new state of the named action + * g_socket_create_source: (skip) + * @socket: a #GSocket + * @condition: a #GIOCondition mask to monitor + * @cancellable: (allow-none): a %GCancellable or %NULL * - * Emits the #GActionGroup::action-state-changed signal on @action_group. - * This function should only be called by #GActionGroup implementations. + * Creates a %GSource that can be attached to a %GMainContext to monitor + * for the availibility of the specified @condition on the socket. + * The callback on the source is of the #GSocketSourceFunc type. + * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; + * these conditions will always be reported output if they are true. + * cause the source to trigger, reporting the current condition (which + * is likely 0 unless cancellation happened at the same time as a + * condition change). You can check for this in the callback using + * g_cancellable_is_cancelled(). + * If @socket has a timeout set, and it is reached before @condition + * occurs, the source will then trigger anyway, reporting %G_IO_IN or + * %G_IO_OUT depending on @condition. However, @socket will have been + * marked as having had a timeout, and so the next #GSocket I/O method + * you call will then fail with a %G_IO_ERROR_TIMED_OUT. * - * Since: 2.28 + * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref(). + * Since: 2.22 */ /** - * SECTION:gfileoutputstrea: - * @short_description: File output streaming operations - * @include: gio/gio.h - * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable + * g_socket_get_blocking: + * @socket: a #GSocket. * - * GFileOutputStream provides output streams that write their - * content to a file. - * GFileOutputStream implements #GSeekable, which allows the output - * stream to jump to arbitrary positions in the file and to truncate - * the file, provided the filesystem of the file supports these - * operations. - * To find the position of a file output stream, use g_seekable_tell(). - * To find out if a file output stream supports seeking, use - * g_seekable_can_seek().To position a file output stream, use - * g_seekable_seek(). To find out if a file output stream supports - * truncating, use g_seekable_can_truncate(). To truncate a file output - * stream, use g_seekable_truncate(). + * Gets the blocking mode of the socket. For details on blocking I/O, + * see g_socket_set_blocking(). + * + * Returns: %TRUE if blocking I/O is used, %FALSE otherwise. + * Since: 2.22 */ /** - * GFileIface: - * @g_iface: The parent interface. - * @dup: Duplicates a #GFile. - * @hash: Creates a hash of a #GFile. - * @equal: Checks equality of two given #GFile<!-- -->s. - * @is_native: Checks to see if a file is native to the system. - * @has_uri_scheme: Checks to see if a #GFile has a given URI scheme. - * @get_uri_scheme: Gets the URI scheme for a #GFile. - * @get_basename: Gets the basename for a given #GFile. - * @get_path: Gets the current path within a #GFile. - * @get_uri: Gets a URI for the path within a #GFile. - * @get_parse_name: Gets the parsed name for the #GFile. - * @get_parent: Gets the parent directory for the #GFile. - * @prefix_matches: Checks whether a #GFile contains a specified file. - * @get_relative_path: Gets the path for a #GFile relative to a given path. - * @resolve_relative_path: Resolves a relative path for a #GFile to an absolute path. - * @get_child_for_display_name: Gets the child #GFile for a given display name. - * @enumerate_children: Gets a #GFileEnumerator with the children of a #GFile. - * @enumerate_children_async: Asynchronously gets a #GFileEnumerator with the children of a #GFile. - * @enumerate_children_finish: Finishes asynchronously enumerating the children. - * @query_info: Gets the #GFileInfo for a #GFile. - * @query_info_async: Asynchronously gets the #GFileInfo for a #GFile. - * @query_info_finish: Finishes an asynchronous query info operation. - * @query_filesystem_info: Gets a #GFileInfo for the file system #GFile is on. - * @query_filesystem_info_async: Asynchronously gets a #GFileInfo for the file system #GFile is on. - * @query_filesystem_info_finish: Finishes asynchronously getting the file system info. - * @find_enclosing_mount: Gets a #GMount for the #GFile. - * @find_enclosing_mount_async: Asynchronously gets the #GMount for a #GFile. - * @find_enclosing_mount_finish: Finishes asynchronously getting the volume. - * @set_display_name: Sets the display name for a #GFile. - * @set_display_name_async: Asynchronously sets a #GFile's display name. - * @set_display_name_finish: Finishes asynchronously setting a #GFile's display name. - * @query_settable_attributes: Returns a list of #GFileAttribute<!-- -->s that can be set. - * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttribute<!-- -->s that can be set. - * @_query_settable_attributes_finish: Finishes asynchronously querying settable attributes. - * @query_writable_namespaces: Returns a list of #GFileAttribute namespaces that are writable. - * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttribute namespaces that are writable. - * @_query_writable_namespaces_finish: Finishes asynchronously querying the writable namespaces. - * @set_attribute: Sets a #GFileAttribute. - * @set_attributes_from_info: Sets a #GFileAttribute with information from a #GFileInfo. - * @set_attributes_async: Asynchronously sets a file's attributes. - * @set_attributes_finish: Finishes setting a file's attributes asynchronously. - * @read_fn: Reads a file asynchronously. - * @read_async: Asynchronously reads a file. - * @read_finish: Finishes asynchronously reading a file. - * @append_to: Writes to the end of a file. - * @append_to_async: Asynchronously writes to the end of a file. - * @append_to_finish: Finishes an asynchronous file append operation. - * @create: Creates a new file. - * @create_async: Asynchronously creates a file. - * @create_finish: Finishes asynchronously creating a file. - * @replace: Replaces the contents of a file. - * @replace_async: Asynchronously replaces the contents of a file. - * @replace_finish: Finishes asynchronously replacing a file. - * @delete_file: Deletes a file. - * @_delete_file_async: Asynchronously deletes a file. - * @_delete_file_finish: Finishes an asynchronous delete. - * @trash: Sends a #GFile to the Trash location. - * @_trash_async: Asynchronously sends a #GFile to the Trash location. - * @_trash_finish: Finishes an asynchronous file trashing operation. - * @make_directory: Makes a directory. - * @_make_directory_async: Asynchronously makes a directory. - * @_make_directory_finish: Finishes making a directory asynchronously. - * @make_symbolic_link: Makes a symbolic link. - * @_make_symbolic_link_async: Asynchronously makes a symbolic link - * @_make_symbolic_link_finish: Finishes making a symbolic link asynchronously. - * @copy: Copies a file. - * @copy_async: Asynchronously copies a file. - * @copy_finish: Finishes an asynchronous copy operation. - * @move: Moves a file. - * @_move_async: Asynchronously moves a file. - * @_move_finish: Finishes an asynchronous move operation. - * @mount_mountable: Mounts a mountable object. - * @mount_mountable_finish: Finishes a mounting operation. - * @unmount_mountable: Unmounts a mountable object. - * @unmount_mountable_finish: Finishes an unmount operation. - * @eject_mountable: Ejects a mountable. - * @eject_mountable_finish: Finishes an eject operation. - * @mount_enclosing_volume: Mounts a specified location. - * @mount_enclosing_volume_finish: Finishes mounting a specified location. - * @monitor_dir: Creates a #GFileMonitor for the location. - * @monitor_file: Creates a #GFileMonitor for the location. - * @open_readwrite: Open file read/write. Since 2.22. - * @open_readwrite_async: Asynchronously opens file read/write. Since 2.22. - * @open_readwrite_finish: Finishes an asynchronous open read/write. Since 2.22. - * @create_readwrite: Creates file read/write. Since 2.22. - * @create_readwrite_async: Asynchronously creates file read/write. Since 2.22. - * @create_readwrite_finish: Finishes an asynchronous creates read/write. Since 2.22. - * @replace_readwrite: Replaces file read/write. Since 2.22. - * @replace_readwrite_async: Asynchronously replaces file read/write. Since 2.22. - * @replace_readwrite_finish: Finishes an asynchronous replace read/write. Since 2.22. - * @start_mountable: Starts a mountable object. Since 2.22. - * @start_mountable_finish: Finishes an start operation. Since 2.22. - * @stop_mountable: Stops a mountable. Since 2.22. - * @stop_mountable_finish: Finishes an stop operation. Since 2.22. - * @supports_thread_contexts: a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22. - * @unmount_mountable_with_operation: Unmounts a mountable object using a #GMountOperation. Since 2.22. - * @unmount_mountable_with_operation_finish: Finishes an unmount operation using a #GMountOperation. Since 2.22. - * @eject_mountable_with_operation: Ejects a mountable object using a #GMountOperation. Since 2.22. - * @eject_mountable_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22. - * @poll_mountable: Polls a mountable object for media changes. Since 2.22. - * @poll_mountable_finish: Finishes an poll operation for media changes. Since 2.22. + * g_socket_get_credentials: + * @socket: a #GSocket. + * @error: #GError for error reporting, or %NULL to ignore. * - * An interface for writing VFS file handles. + * Returns the credentials of the foreign process connected to this + * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX + * sockets). + * If this operation isn't supported on the OS, the method fails with + * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented + * by reading the %SO_PEERCRED option on the underlying socket. + * Other ways to obtain credentials from a foreign peer includes the + * #GUnixCredentialsMessage type and + * g_unix_connection_send_credentials() / + * g_unix_connection_receive_credentials() functions. + * that must be freed with g_object_unref(). + * + * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object + * Since: 2.26 */ /** - * G_IS_PARAM_SPEC: - * @pspec: a #GParamSpec + * g_socket_get_family: + * @socket: a #GSocket. * - * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM - * or derived. + * Gets the socket family of the socket. + * + * Returns: a #GSocketFamily + * Since: 2.22 */ /** - * g_file_output_stream_query_info_finish: - * @stream: a #GFileOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError, %NULL to ignore. + * g_socket_get_fd: + * @socket: a #GSocket. * - * Finalizes the asynchronous query started - * by g_file_output_stream_query_info_async(). + * Returns the underlying OS socket object. On unix this + * is a socket file descriptor, and on windows this is + * a Winsock2 SOCKET handle. This may be useful for + * doing platform specific or otherwise unusual operations + * on the socket. * - * Returns: (transfer full): A #GFileInfo for the finished query. + * Returns: the file descriptor of the socket. + * Since: 2.22 */ /** - * G_PARAM_SPEC_LONG: - * @pspec: a valid #GParamSpec instance + * g_socket_get_keepalive: + * @socket: a #GSocket. * - * Cast a #GParamSpec instance into a #GParamSpecLong. + * Gets the keepalive mode of the socket. For details on this, + * see g_socket_set_keepalive(). + * + * Returns: %TRUE if keepalive is active, %FALSE otherwise. + * Since: 2.22 */ /** - * GInterfaceFinalizeFunc: - * @g_iface: The interface structure to finalize. - * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. + * g_socket_get_listen_backlog: + * @socket: a #GSocket. * - * A callback function used by the type system to finalize an interface. - * This function should destroy any internal data and release any resources - * allocated by the corresponding GInterfaceInitFunc() function. + * Gets the listen backlog setting of the socket. For details on this, + * see g_socket_set_listen_backlog(). + * + * Returns: the maximum number of pending connections. + * Since: 2.22 */ /** - * g_simple_action_group_insert: - * @simple: a #GSimpleActionGroup - * @action: a #GAction + * g_socket_get_local_address: + * @socket: a #GSocket. + * @error: #GError for error reporting, or %NULL to ignore. * - * Adds an action to the action group. - * If the action group already contains an action with the same name as - * The action group takes its own reference on @action. + * Try to get the local address of a bound socket. This is only + * useful if the socket has been bound to a local address, + * either explicitly or implicitly when connecting. + * Free the returned object with g_object_unref(). * - * Since: 2.28 + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Since: 2.22 */ /** - * G_VARIANT_TYPE_DICT_ENTRY: + * g_socket_get_protocol: + * @socket: a #GSocket. * - * An indefinite type that is a supertype of every dictionary entry - * type. + * Gets the socket protocol id the socket was created with. + * In case the protocol is unknown, -1 is returned. + * + * Returns: a protocol id, or -1 if unknown + * Since: 2.22 */ /** - * GUnixOutputStream:fd: + * g_socket_get_remote_address: + * @socket: a #GSocket. + * @error: #GError for error reporting, or %NULL to ignore. * - * The file descriptor that the stream writes to. + * Try to get the remove address of a connected socket. This is only + * useful for connection oriented sockets that have been connected. + * Free the returned object with g_object_unref(). * - * Since: 2.20 + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Since: 2.22 */ /** - * GDBusAuthObserverClass: - * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal. + * g_socket_get_socket_type: + * @socket: a #GSocket. * - * Class structure for #GDBusAuthObserverClass. + * Gets the socket type of the socket. * - * Since: 2.26 + * Returns: a #GSocketType + * Since: 2.22 */ /** - * G_TYPE_PARAM_UINT: + * g_socket_get_timeout: + * @socket: a #GSocket. * - * The #GType of #GParamSpecUInt. + * Gets the timeout setting of the socket. For details on this, see + * g_socket_set_timeout(). + * + * Returns: the timeout in seconds + * Since: 2.26 */ /** - * g_application_command_line_printerr: - * @cmdline: a #GApplicationCommandLine - * @format: a printf-style format string - * @...: arguments, as per @format + * g_socket_is_closed: + * @socket: a #GSocket * - * Formats a message and prints it using the stderr print handler in the - * invoking process. - * If @cmdline is a local invocation then this is exactly equivalent to - * g_printerr(). If @cmdline is remote then this is equivalent to - * calling g_printerr() in the invoking process. + * Checks whether a socket is closed. * - * Since: 2.28 + * Returns: %TRUE if socket is closed, %FALSE otherwise + * Since: 2.22 */ /** - * GInstanceInitFunc: - * @instance: The instance to initialize. - * @g_class: The class of the type the instance is created for. + * g_socket_is_connected: + * @socket: a #GSocket. * - * A callback function used by the type system to initialize a new - * instance of a type. This function initializes all instance members and - * allocates any resources required by it. - * Initialization of a derived instance involves calling all its parent - * types instance initializers, so the class member of the instance - * is altered during its initialization to always point to the class that - * belongs to the type the current initializer was introduced for. + * Check whether the socket is connected. This is only useful for + * connection-oriented sockets. + * + * Returns: %TRUE if socket is connected, %FALSE otherwise. + * Since: 2.22 */ /** - * g_tls_server_connection_new: - * @base_io_stream: the #GIOStream to wrap - * @certificate: (allow-none): the default server certificate, or %NULL + * g_socket_listen: + * @socket: a #GSocket. * @error: #GError for error reporting, or %NULL to ignore. * - * Creates a new #GTlsServerConnection wrapping @base_io_stream (which - * must have pollable input and output streams). + * Marks the socket as a server socket, i.e. a socket that is used + * to accept incoming requests using g_socket_accept(). + * Before calling this the socket must be bound to a local address using + * g_socket_bind(). + * To set the maximum amount of outstanding clients, use + * g_socket_set_listen_backlog(). * - * Returns: the new #GTlsServerConnection, or %NULL on error - * Since: 2.28 + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.22 */ /** - * g_data_input_stream_read_int32: - * @stream: a given #GDataInputStream. + * g_socket_listener_accept: + * @listener: a #GSocketListener + * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * @error: #GError for error reporting, or %NULL to ignore. * - * Reads a signed 32-bit/4-byte value from @stream. - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). + * Blocks waiting for a client to connect to any of the sockets added + * to the listener. Returns a #GSocketConnection for the socket that was + * accepted. + * If @source_object is not %NULL it will be filled out with the source + * object specified when the corresponding socket or address was added + * to the listener. * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * an error occurred. * - * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * GRegexError: - * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed. - * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed. - * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string. - * @G_REGEX_ERROR_MATCH: The match process failed. - * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16 - * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16 - * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16 - * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16 - * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16 - * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16 - * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16 - * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16 - * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16 - * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16 - * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16 - * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16 - * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16 - * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16 - * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16 - * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16 - * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16 - * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16 - * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16 - * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16 - * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16 - * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16 - * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16 - * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16 - * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16 - * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16 - * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16 - * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16 - * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16 - * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16 - * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16 - * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16 - * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16 - * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16 - * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16 - * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16 - * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16 - * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16 + * g_socket_listener_accept_async: + * @listener: a #GSocketListener + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * Error codes returned by regular expressions functions. + * This is the asynchronous version of g_socket_listener_accept(). + * When the operation is finished @callback will be + * called. You can then call g_socket_listener_accept_socket() + * to get the result of the operation. * - * Since: 2.14 + * Since: 2.22 */ /** - * GFileReadMoreCallback: - * @file_contents: the data as currently read. - * @file_size: the size of the data currently read. - * @callback_data: data passed to the callback. + * g_socket_listener_accept_finish: + * @listener: a #GSocketListener + * @result: a #GAsyncResult. + * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * When loading the partial contents of a file with g_file_load_partial_contents_async(), - * it may become necessary to determine if any more data from the file should be loaded. - * A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data - * should be read, or %FALSE otherwise. + * Finishes an async accept operation. See g_socket_listener_accept_async() * - * Returns: %TRUE if more data should be read back. %FALSE otherwise. + * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. + * Since: 2.22 */ /** - * g_pollable_input_stream_read_nonblocking: - * @stream: a #GPollableInputStream - * @buffer: a buffer to read data into (which should be at least @size bytes long). - * @size: the number of bytes you want to read - * @cancellable: (allow-none): a #GCancellable, or %NULL + * g_socket_listener_accept_socket: + * @listener: a #GSocketListener + * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: #GError for error reporting, or %NULL to ignore. * - * Attempts to read up to @size bytes from @stream into @buffer, as - * with g_input_stream_read(). If @stream is not currently readable, - * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can - * use g_pollable_input_stream_create_source() to create a #GSource - * that will be triggered when @stream is readable. - * Note that since this method never blocks, you cannot actually - * use @cancellable to cancel it. However, it will return an error - * if @cancellable has already been cancelled when you call, which - * may happen if you call this method after a source triggers due - * to having been cancelled. - * %G_IO_ERROR_WOULD_BLOCK). + * Blocks waiting for a client to connect to any of the sockets added + * to the listener. Returns the #GSocket that was accepted. + * If you want to accept the high-level #GSocketConnection, not a #GSocket, + * which is often the case, then you should use g_socket_listener_accept() + * instead. + * If @source_object is not %NULL it will be filled out with the source + * object specified when the corresponding socket or address was added + * to the listener. + * If @cancellable is not %NULL, then the operation can be cancelled by + * triggering the cancellable object from another thread. If the operation + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Virtual: read_nonblocking - * Returns: the number of bytes read, or -1 on error (including + * Returns: (transfer full): a #GSocket on success, %NULL on error. + * Since: 2.22 */ /** - * SECTION:gioschedule: - * @short_description: I/O Scheduler - * @include: gio/gio.h + * g_socket_listener_accept_socket_async: + * @listener: a #GSocketListener + * @cancellable: (allow-none): a #GCancellable, or %NULL + * @callback: (scope async): a #GAsyncReadyCallback + * @user_data: (closure): user data for the callback * - * Schedules asynchronous I/O operations. #GIOScheduler integrates - * into the main event loop (#GMainLoop) and may use threads if they - * are available. - * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm> - * Each I/O operation has a priority, and the scheduler uses the priorities - * to determine the order in which operations are executed. They are - * <emphasis>not</emphasis> used to determine system-wide I/O scheduling. - * Priorities are integers, with lower numbers indicating higher priority. - * It is recommended to choose priorities between %G_PRIORITY_LOW and - * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default. - * </para> + * This is the asynchronous version of g_socket_listener_accept_socket(). + * When the operation is finished @callback will be + * called. You can then call g_socket_listener_accept_socket_finish() + * to get the result of the operation. + * + * Since: 2.22 */ /** - * SECTION:gsocketconnectio: - * @short_description: A socket connection - * @include: gio/gio.h - * @see_also: #GIOStream, #GSocketClient, #GSocketListener + * g_socket_listener_accept_socket_finish: + * @listener: a #GSocketListener + * @result: a #GAsyncResult. + * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * #GSocketConnection is a #GIOStream for a connected socket. They - * can be created either by #GSocketClient when connecting to a host, - * or by #GSocketListener when accepting a new client. - * The type of the #GSocketConnection object returned from these calls - * depends on the type of the underlying socket that is in use. For - * instance, for a TCP/IP connection it will be a #GTcpConnection. - * Chosing what type of object to construct is done with the socket - * connection factory, and it is possible for 3rd parties to register - * custom socket connection types for specific combination of socket - * family/type/protocol using g_socket_connection_factory_register_type(). + * Finishes an async accept operation. See g_socket_listener_accept_socket_async() * + * Returns: (transfer full): a #GSocket on success, %NULL on error. * Since: 2.22 */ /** - * G_TIME_SPAN_SECOND: + * g_socket_listener_add_address: + * @listener: a #GSocketListener + * @address: a #GSocketAddress + * @type: a #GSocketType + * @protocol: a #GSocketProtocol + * @source_object: (allow-none): Optional #GObject identifying this source + * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL. + * @error: #GError for error reporting, or %NULL to ignore. * - * Evaluates to a time span of one second. + * Creates a socket of type @type and protocol @protocol, binds + * it to @address and adds it to the set of sockets we're accepting + * sockets from. + * Note that adding an IPv6 address, depending on the platform, + * may or may not result in a listener that also accepts IPv4 + * connections. For more determinstic behaviour, see + * g_socket_listener_add_inet_port(). + * to accept to identify this particular source, which is + * useful if you're listening on multiple addresses and do + * different things depending on what address is connected to. + * If successful and @effective_address is non-%NULL then it will + * be set to the address that the binding actually occured at. This + * is helpful for determining the port number that was used for when + * requested, belongs to the caller and must be freed. * - * Since: 2.26 + * Requesting a binding to port 0 (ie: "any port"). This address, if + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.22 */ /** - * G_TYPE_UINT: + * g_socket_listener_add_any_inet_port: + * @listener: a #GSocketListener + * @source_object: (allow-none): Optional #GObject identifying this source + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * The fundamental type corresponding to #guint. + * Listens for TCP connections on any available port number for both + * IPv6 and IPv4 (if each are available). + * This is useful if you need to have a socket for incoming connections + * but don't care about the specific port number. + * to accept to identify this particular source, which is + * useful if you're listening on multiple addresses and do + * different things depending on what address is connected to. + * + * Returns: the port number, or 0 in case of failure. + * Since: 2.24 */ /** - * g_file_monitor_directory: - * @file: input #GFile. - * @flags: a set of #GFileMonitorFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL. + * g_socket_listener_add_inet_port: + * @listener: a #GSocketListener + * @port: an IP port number (non-zero) + * @source_object: (allow-none): Optional #GObject identifying this source + * @error: #GError for error reporting, or %NULL to ignore. * - * Obtains a directory monitor for the given file. - * This may fail if directory monitoring is not supported. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Free the returned object with g_object_unref(). + * Helper function for g_socket_listener_add_address() that + * creates a TCP/IP socket listening on IPv4 and IPv6 (if + * supported) on the specified port on all interfaces. + * to accept to identify this particular source, which is + * useful if you're listening on multiple addresses and do + * different things depending on what address is connected to. * - * Virtual: monitor_dir - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.22 */ /** - * GCharsetConverter: + * g_socket_listener_add_socket: + * @listener: a #GSocketListener + * @socket: a listening #GSocket + * @source_object: (allow-none): Optional #GObject identifying this source + * @error: #GError for error reporting, or %NULL to ignore. * - * Conversions between character sets. + * Adds @socket to the set of sockets that we try to accept + * new clients from. The socket must be bound to a local + * address and listened to. + * to accept to identify this particular source, which is + * useful if you're listening on multiple addresses and do + * different things depending on what address is connected to. + * + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.22 */ /** - * G_FILE_ATTRIBUTE_TIME_CHANGED: + * g_socket_listener_close: + * @listener: a #GSocketListener * - * A key in the "time" namespace for getting the time the file was last - * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, - * and contains the UNIX time since the file was last changed. - * This corresponds to the traditional UNIX ctime. + * Closes all the sockets in the listener. + * + * Since: 2.22 */ /** - * G_PRIORITY_DEFAULT: + * g_socket_listener_new: * - * Use this for default priority event sources. - * In GLib this priority is used when adding timeout functions - * with g_timeout_add(). In GDK this priority is used for events - * from the X server. + * Creates a new #GSocketListener with no sockets to listen for. + * New listeners can be added with e.g. g_socket_listener_add_address() + * or g_socket_listener_add_inet_port(). + * + * Returns: a new #GSocketListener. + * Since: 2.22 */ /** - * g_settings_new_with_backend: - * @schema: the name of the schema - * @backend: the #GSettingsBackend to use - * @returns: a new #GSettings object + * g_socket_listener_set_backlog: + * @listener: a #GSocketListener + * @listen_backlog: an integer * - * Creates a new #GSettings object with a given schema and backend. - * Creating settings objects with an different backend allows accessing settings - * from a database other than the usual one. For example, it may make - * sense to pass a backend corresponding to the "defaults" settings database on - * the system to get a settings object that modifies the system default - * settings instead of the settings for this user. + * Sets the listen backlog on the sockets in the listener. + * See g_socket_set_listen_backlog() for details * - * Since: 2.26 + * Since: 2.22 */ /** - * G_TYPE_IS_PARAM: - * @type: a #GType ID + * g_socket_new: + * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4. + * @type: the socket type to use. + * @protocol: the id of the protocol to use, or 0 for default. + * @error: #GError for error reporting, or %NULL to ignore. * - * Checks whether @type "is a" %G_TYPE_PARAM. + * Creates a new #GSocket with the defined family, type and protocol. + * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type + * for the family and type is used. + * The @protocol is a family and type specific int that specifies what + * kind of protocol to use. #GSocketProtocol lists several common ones. + * Many families only support one protocol, and use 0 for this, others + * support several and using 0 means to use the default protocol for + * the family and type. + * The protocol id is passed directly to the operating + * system, so you can use protocols not listed in #GSocketProtocol if you + * know the protocol number used for it. + * Free the returned object with g_object_unref(). + * + * Returns: a #GSocket or %NULL on error. + * Since: 2.22 */ /** - * g_dbus_error_is_remote_error: - * @error: A #GError. + * g_socket_new_from_fd: + * @fd: a native socket file descriptor. + * @error: #GError for error reporting, or %NULL to ignore. * - * Checks if @error represents an error received via D-Bus from a remote peer. If so, - * use g_dbus_error_get_remote_error() to get the name of the error. - * %FALSE otherwise. + * Creates a new #GSocket from a native file descriptor + * or winsock SOCKET handle. + * This reads all the settings from the file descriptor so that + * all properties should work. Note that the file descriptor + * will be set to non-blocking mode, independent on the blocking + * mode of the #GSocket. + * Free the returned object with g_object_unref(). * - * Returns: %TRUE if @error represents an error from a remote peer, - * Since: 2.26 + * Returns: a #GSocket or %NULL on error. + * Since: 2.22 */ /** - * G_TYPE_CHECK_CLASS_CAST: - * @g_class: Location of a #GTypeClass structure. - * @g_type: The type to be returned. - * @c_type: The corresponding C type of class structure of @g_type. + * g_socket_receive: + * @socket: a #GSocket + * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @size: the number of bytes you want to read from the socket + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Checks that @g_class is a class structure of the type identified by @g_type - * and issues a warning if this is not the case. Returns @g_class casted - * to a pointer to @c_type. - * This macro should only be used in type implementations. + * Receive data (up to @size bytes) from a socket. This is mainly used by + * connection-oriented sockets; it is identical to g_socket_receive_from() + * with @address set to %NULL. + * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets, + * g_socket_receive() will always read either 0 or 1 complete messages from + * the socket. If the received message is too large to fit in @buffer, then + * the data beyond @size bytes will be discarded, without any explicit + * indication that this has occurred. + * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any + * number of bytes, up to @size. If more than @size bytes have been + * received, the additional data will be returned in future calls to + * g_socket_receive(). + * If the socket is in blocking mode the call will block until there is + * some data to receive or there is an error. If there is no data available + * and the socket is in non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error + * will be returned. To be notified when data is available, wait for the + * %G_IO_IN condition. + * On error -1 is returned and @error is set accordingly. + * + * Returns: Number of bytes read, or -1 on error + * Since: 2.22 */ /** - * G_IS_ENUM_CLASS: - * @class: a #GEnumClass + * g_socket_receive_from: + * @socket: a #GSocket + * @address: a pointer to a #GSocketAddress pointer, or %NULL + * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @size: the number of bytes you want to read from the socket + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM - * or derived. + * Receive data (up to @size bytes) from a socket. + * If @address is non-%NULL then @address will be set equal to the + * source address of the received packet. + * See g_socket_receive() for additional information. + * + * Returns: Number of bytes read, or -1 on error + * Since: 2.22 */ /** - * G_FILE_ATTRIBUTE_PREVIEW_ICON: + * g_socket_receive_message: + * @socket: a #GSocket + * @address: a pointer to a #GSocketAddress pointer, or %NULL + * @vectors: (array length=num_vectors): an array of #GInputVector structs + * @num_vectors: the number of elements in @vectors, or -1 + * @messages: (array length=num_messages) (allow-none): a pointer which may be filled with an array of #GSocketControlMessages, or %NULL + * @num_messages: a pointer which will be filled with the number of elements in @messages, or %NULL + * @flags: a pointer to an int containing #GSocketMsgFlags flags + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: a #GError pointer, or %NULL * - * A key in the "preview" namespace for getting a #GIcon that can be - * used to get preview of the file. For example, it may be a low - * resolution thumbnail without metadata. Corresponding - * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value - * for this key should contain a #GIcon. + * Receive data from a socket. This is the most complicated and + * fully-featured version of this call. For easier use, see + * g_socket_receive() and g_socket_receive_from(). + * If @address is non-%NULL then @address will be set equal to the + * source address of the received packet. + * describe the buffers that received data will be scattered into. + * If @num_vectors is -1, then @vectors is assumed to be terminated + * by a #GInputVector with a %NULL buffer pointer. + * As a special case, if @num_vectors is 0 (in which case, @vectors + * may of course be %NULL), then a single byte is received and + * discarded. This is to facilitate the common practice of sending a + * single '\0' byte for the purposes of transferring ancillary data. + * array of #GSocketControlMessage instances or %NULL if no such + * messages was received. These correspond to the control messages + * received from the kernel, one #GSocketControlMessage per message + * from the kernel. This array is %NULL-terminated and must be freed + * by the caller using g_free() after calling g_object_unref() on each + * element. If @messages is %NULL, any control messages received will + * be discarded. + * messages received. + * If both @messages and @num_messages are non-%NULL, then + * for this are available in the #GSocketMsgFlags enum, but the + * values there are the same as the system values, and the flags + * are passed in as-is, so you can pass in system-specific flags too + * (and g_socket_receive_message() may pass system-specific flags out). + * As with g_socket_receive(), data may be discarded if @socket is + * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not + * provide enough buffer space to read a complete message. You can pass + * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without + * removing it from the receive queue, but there is no portable way to find + * out the length of the message other than by reading it into a + * sufficiently-large buffer. + * If the socket is in blocking mode the call will block until there + * is some data to receive or there is an error. If there is no data + * available and the socket is in non-blocking mode, a + * %G_IO_ERROR_WOULD_BLOCK error will be returned. To be notified when + * data is available, wait for the %G_IO_IN condition. + * On error -1 is returned and @error is set accordingly. * - * Since: 2.20 + * In @messages (ie: not including the %NULL terminator). + * Returns: Number of bytes read, or -1 on error + * Since: 2.22 */ /** - * g_unix_mount_is_readonly: - * @mount_entry: a #GUnixMount. + * g_socket_receive_with_blocking: + * @socket: a #GSocket + * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @size: the number of bytes you want to read from the socket + * @blocking: whether to do blocking or non-blocking I/O + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Checks if a unix mount is mounted read only. + * This behaves exactly the same as g_socket_receive(), except that + * the choice of blocking or non-blocking behavior is determined by + * the @blocking argument rather than by @socket's properties. * - * Returns: %TRUE if @mount_entry is read only. + * Returns: Number of bytes read, or -1 on error + * Since: 2.26 */ /** - * GChecksumType: - * @G_CHECKSUM_MD5: Use the MD5 hashing algorithm - * @G_CHECKSUM_SHA1: Use the SHA-1 hashing algorithm - * @G_CHECKSUM_SHA256: Use the SHA-256 hashing algorithm + * g_socket_send: + * @socket: a #GSocket + * @buffer: (array length=size): the buffer containing the data to send. + * @size: the number of bytes to send + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * The hashing algorithm to be used by #GChecksum when performing the - * digest of some data. - * Note that the #GChecksumType enumeration may be extended at a later - * date to include new hashing algorithm types. + * Tries to send @size bytes from @buffer on the socket. This is + * mainly used by connection-oriented sockets; it is identical to + * g_socket_send_to() with @address set to %NULL. + * If the socket is in blocking mode the call will block until there is + * space for the data in the socket queue. If there is no space available + * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error + * 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. + * on error * - * Since: 2.16 + * Returns: Number of bytes written (which may be less than @size), or -1 + * Since: 2.22 */ /** - * g_dbus_method_invocation_return_error: - * @invocation: A #GDBusMethodInvocation. - * @domain: A #GQuark for the #GError error domain. - * @code: The error code. - * @format: printf()-style format. - * @...: Parameters for @format. + * g_socket_send_message: + * @socket: a #GSocket + * @address: a #GSocketAddress, or %NULL + * @vectors: (array length=num_vectors): an array of #GOutputVector structs + * @num_vectors: the number of elements in @vectors, or -1 + * @messages: (array length=num_messages) (allow-none): a pointer to an array of #GSocketControlMessages, or %NULL. + * @num_messages: number of elements in @messages, or -1. + * @flags: an int containing #GSocketMsgFlags flags + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Finishes handling a D-Bus method call by returning an error. - * See g_dbus_error_encode_gerror() for details about what error name - * will be returned on the wire. In a nutshell, if the given error is - * registered using g_dbus_error_register_error() the name given - * during registration is used. Otherwise, a name of the form - * <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is - * used. This provides transparent mapping of #GError between - * applications using GDBus. - * If you are writing an application intended to be portable, - * <emphasis>always</emphasis> register errors with g_dbus_error_register_error() - * or use g_dbus_method_invocation_return_dbus_error(). - * This method will free @invocation, you cannot use it afterwards. + * Send data to @address on @socket. This is the most complicated and + * fully-featured version of this call. For easier use, see + * g_socket_send() and g_socket_send_to(). + * If @address is %NULL then the message is sent to the default receiver + * (set by g_socket_connect()). + * then @vectors is assumed to be terminated by a #GOutputVector with a + * %NULL buffer pointer.) The #GOutputVector structs describe the buffers + * that the sent data will be gathered from. Using multiple + * #GOutputVector<!-- -->s is more memory-efficient than manually copying + * data from multiple sources into a single buffer, and more + * network-efficient than making multiple calls to g_socket_send(). + * #GSocketControlMessage instances. These correspond to the control + * messages to be sent on the socket. + * If @num_messages is -1 then @messages is treated as a %NULL-terminated + * array. + * for this are available in the #GSocketMsgFlags enum, but the + * values there are the same as the system values, and the flags + * are passed in as-is, so you can pass in system-specific flags too. + * If the socket is in blocking mode the call will block until there is + * space for the data in the socket queue. If there is no space available + * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error + * 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. + * on error * - * Since: 2.26 + * Returns: Number of bytes written (which may be less than @size), or -1 + * Since: 2.22 */ /** - * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT: + * g_socket_send_to: + * @socket: a #GSocket + * @address: a #GSocketAddress, or %NULL + * @buffer: (array length=size): the buffer containing the data to send. + * @size: the number of bytes to send + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Allowed characters in path elements. Includes "!$&'()*+,;=:@". + * Tries to send @size bytes from @buffer to @address. If @address is + * %NULL then the message is sent to the default receiver (set by + * g_socket_connect()). + * See g_socket_send() for additional information. + * on error + * + * Returns: Number of bytes written (which may be less than @size), or -1 + * Since: 2.22 */ /** - * GSimpleAction:state: + * g_socket_send_with_blocking: + * @socket: a #GSocket + * @buffer: (array length=size): the buffer containing the data to send. + * @size: the number of bytes to send + * @blocking: whether to do blocking or non-blocking I/O + * @cancellable: (allow-none): a %GCancellable or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * The state of the action, or %NULL if the action is stateless. + * This behaves exactly the same as g_socket_send(), except that + * the choice of blocking or non-blocking behavior is determined by + * the @blocking argument rather than by @socket's properties. + * on error * - * Since: 2.28 + * Returns: Number of bytes written (which may be less than @size), or -1 + * Since: 2.26 */ /** - * g_mount_eject_with_operation: - * @mount: a #GMount. - * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * g_socket_service_is_active: + * @service: a #GSocketService * - * Ejects a mount. This is an asynchronous operation, and is - * finished by calling g_mount_eject_with_operation_finish() with the @mount - * and #GAsyncResult data returned in the @callback. + * Check whether the service is active or not. An active + * service will accept new clients that connect, while + * a non-active service will let connecting clients queue + * up until the service is started. * + * Returns: %TRUE if the service is active, %FALSE otherwise * Since: 2.22 */ /** - * g_simple_action_set_enabled: - * @simple: a #GSimpleAction - * @enabled: whether the action is enabled + * g_socket_service_new: * - * Sets the action as enabled or not. - * An action must be enabled in order to be activated or in order to - * have its state changed from outside callers. + * Creates a new #GSocketService with no sockets to listen for. + * New listeners can be added with e.g. g_socket_listener_add_address() + * or g_socket_listener_add_inet_port(). * - * Since: 2.28 + * Returns: a new #GSocketService. + * Since: 2.22 */ /** - * GDBusInterfaceMethodCallFunc: - * @connection: A #GDBusConnection. - * @sender: The unique bus name of the remote caller. - * @object_path: The object path that the method was invoked on. - * @interface_name: The D-Bus interface name the method was invoked on. - * @method_name: The name of the method that was invoked. - * @parameters: A #GVariant tuple with parameters. - * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error. - * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object(). + * g_socket_service_start: + * @service: a #GSocketService * - * The type of the @method_call function in #GDBusInterfaceVTable. + * Starts the service, i.e. start accepting connections + * from the added sockets when the mainloop runs. + * This call is threadsafe, so it may be called from a thread + * handling an incomming client request. * - * Since: 2.26 + * Since: 2.22 */ /** - * GDBusConnection::closed: - * @connection: The #GDBusConnection emitting the signal. - * @remote_peer_vanished: %TRUE if @connection is closed because the remote peer closed its end of the connection. - * @error: A #GError with more details about the event or %NULL. + * g_socket_service_stop: + * @service: a #GSocketService * - * Emitted when the connection is closed. - * The cause of this event can be - * <itemizedlist> - * <listitem><para> - * If g_dbus_connection_close() is called. In this case - * </para></listitem> - * <listitem><para> - * If the remote peer closes the connection. In this case - * </para></listitem> - * <listitem><para> - * If the remote peer sends invalid or malformed data. In this - * case @remote_peer_vanished is set to %FALSE and @error - * is set. - * </para></listitem> - * </itemizedlist> - * Upon receiving this signal, you should give up your reference to - * once. + * Stops the service, i.e. stops accepting connections + * from the added sockets when the mainloop runs. + * This call is threadsafe, so it may be called from a thread + * handling an incomming client request. * - * Since: 2.26 + * Since: 2.22 */ /** - * G_FILE_ATTRIBUTE_ID_FILESYSTEM: + * g_socket_set_blocking: + * @socket: a #GSocket. + * @blocking: Whether to use blocking I/O or not. * - * A key in the "id" namespace for getting the file system identifier. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - * An example use would be during drag and drop to see if the source - * and target are on the same filesystem (default to move) or not (default - * to copy). + * Sets the blocking mode of the socket. In blocking mode + * all operations block until they succeed or there is an error. In + * non-blocking mode all functions return results immediately or + * with a %G_IO_ERROR_WOULD_BLOCK error. + * All sockets are created in blocking mode. However, note that the + * platform level socket is always non-blocking, and blocking mode + * is a GSocket level feature. + * + * Since: 2.22 */ /** - * g_inet_socket_address_get_address: - * @address: a #GInetSocketAddress + * g_socket_set_keepalive: + * @socket: a #GSocket. + * @keepalive: Value for the keepalive flag * - * Gets @address's #GInetAddress. - * g_object_ref()'d if it will be stored + * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When + * this flag is set on a socket, the system will attempt to verify that the + * remote socket endpoint is still present if a sufficiently long period of + * time passes with no data being exchanged. If the system is unable to + * verify the presence of the remote endpoint, it will automatically close + * the connection. + * This option is only functional on certain kinds of sockets. (Notably, + * %G_SOCKET_PROTOCOL_TCP sockets.) + * The exact time between pings is system- and protocol-dependent, but will + * normally be at least two hours. Most commonly, you would set this flag + * on a server socket if you want to allow clients to remain idle for long + * periods of time, but also want to ensure that connections are eventually + * garbage-collected if clients crash or become unreachable. * - * Returns: (transfer none): the #GInetAddress for @address, which must be * Since: 2.22 */ /** - * SECTION:gcredential: - * @short_description: An object containing credentials - * @include: gio/gio.h + * g_socket_set_listen_backlog: + * @socket: a #GSocket. + * @backlog: the maximum number of pending connections. * - * The #GCredentials type is a reference-counted wrapper for native - * credentials. This information is typically used for identifying, - * authenticating and authorizing other processes. - * Some operating systems supports looking up the credentials of the - * remote peer of a communication endpoint - see e.g. - * g_socket_get_credentials(). - * Some operating systems supports securely sending and receiving - * credentials over a Unix Domain Socket, see - * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and - * g_unix_connection_receive_credentials() for details. - * On Linux, the native credential type is a <type>struct ucred</type> - * - see the - * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry> - * man page for details. This corresponds to - * %G_CREDENTIALS_TYPE_LINUX_UCRED. - * On FreeBSD, the native credential type is a <type>struct cmsgcred</type>. - * This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. + * Sets the maximum number of outstanding connections allowed + * when listening on this socket. If more clients than this are + * connecting to the socket and the application is not handling them + * on time then the new connections will be refused. + * Note that this must be called before g_socket_listen() and has no + * effect if called after that. + * + * Since: 2.22 */ /** - * SECTION:gtlsclientconnectio: - * @short_description: TLS client-side connection - * @include: gio/gio.h + * g_socket_set_timeout: + * @socket: a #GSocket. + * @timeout: the timeout for @socket, in seconds, or 0 for none * - * #GTlsClientConnection is the client-side subclass of - * #GTlsConnection, representing a client-side TLS connection. + * Sets the time in seconds after which I/O operations on @socket will + * time out if they have not yet completed. + * On a blocking socket, this means that any blocking #GSocket + * operation will time out after @timeout seconds of inactivity, + * returning %G_IO_ERROR_TIMED_OUT. + * On a non-blocking socket, calls to g_socket_condition_wait() will + * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources + * created with g_socket_create_source() will trigger after + * set, at which point calling g_socket_receive(), g_socket_send(), + * g_socket_check_connect_result(), etc, will fail with + * %G_IO_ERROR_TIMED_OUT. + * If @timeout is 0 (the default), operations will never time out + * on their own. + * Note that if an I/O operation is interrupted by a signal, this may + * cause the timeout to be reset. + * + * Since: 2.26 */ /** - * GWin32OutputStream:close-handle: + * g_socket_shutdown: + * @socket: a #GSocket + * @shutdown_read: whether to shut down the read side + * @shutdown_write: whether to shut down the write side + * @error: #GError for error reporting, or %NULL to ignore. * - * Whether to close the file handle when the stream is closed. + * Shut down part of a full-duplex connection. + * If @shutdown_read is %TRUE then the recieving side of the connection + * is shut down, and further reading is disallowed. + * If @shutdown_write is %TRUE then the sending side of the connection + * is shut down, and further writing is disallowed. + * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE. + * One example where this is used is graceful disconnect for TCP connections + * where you close the sending side, then wait for the other side to close + * the connection, thus ensuring that the other side saw all sent data. * - * Since: 2.26 + * Returns: %TRUE on success, %FALSE on error + * Since: 2.22 */ /** - * g_file_open_readwrite: - * @file: #GFile to open - * @cancellable: (allow-none): a #GCancellable - * @error: a #GError, or %NULL + * g_socket_speaks_ipv4: + * @socket: a #GSocket * - * Opens an existing file for reading and writing. The result is - * a #GFileIOStream that can be used to read and write the contents of the file. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. - * If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned. - * Other errors are possible too, and depend on what kind of filesystem the file is on. - * Note that in many non-local file cases read and write streams are not supported, - * so make sure you really need to do read and write streaming, rather than - * just opening for reading or writing. - * Free the returned object with g_object_unref(). + * Checks if a socket is capable of speaking IPv4. + * IPv4 sockets are capable of speaking IPv4. On some operating systems + * and under some combinations of circumstances IPv6 sockets are also + * capable of speaking IPv4. See RFC 3493 section 3.7 for more + * information. + * No other types of sockets are currently considered as being capable + * of speaking IPv4. * - * Returns: (transfer full): #GFileIOStream or %NULL on error. + * Returns: %TRUE if this socket can be used with IPv4. * Since: 2.22 */ /** - * GVolumeMonitor::volume-removed: - * @volume_monitor: The volume monitor emitting the signal. - * @volume: a #GVolume that was removed. + * g_srv_target_copy: + * @target: a #GSrvTarget * - * Emitted when a mountable volume is removed from the system. + * Copies @target + * + * Returns: a copy of @target + * Since: 2.22 */ /** - * g_dbus_error_encode_gerror: - * @error: A #GError. + * g_srv_target_free: + * @target: a #GSrvTarget * - * Creates a D-Bus error name to use for @error. If @error matches - * a registered error (cf. g_dbus_error_register_error()), the corresponding - * D-Bus error name will be returned. - * Otherwise the a name of the form - * <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal> - * will be used. This allows other GDBus applications to map the error - * on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). - * This function is typically only used in object mappings to put a - * #GError on the wire. Regular applications should not use it. + * Frees @target * - * Returns: A D-Bus error name (never %NULL). Free with g_free(). - * Since: 2.26 + * Since: 2.22 */ /** - * g_file_set_attribute_int32: - * @file: input #GFile. - * @attribute: a string containing the attribute's name. - * @value: a #gint32 containing the attribute's new value. - * @flags: a #GFileQueryInfoFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * g_srv_target_get_hostname: + * @target: a #GSrvTarget * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. - * If @attribute is of a different type, this operation will fail. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * in the @file, %FALSE otherwise. + * Gets @target's hostname (in ASCII form; if you are going to present + * this to the user, you should use g_hostname_is_ascii_encoded() to + * check if it contains encoded Unicode segments, and use + * g_hostname_to_unicode() to convert it if it does.) * - * Returns: %TRUE if the @attribute was successfully set to @value + * Returns: @target's hostname + * Since: 2.22 */ /** - * GDBusServer:guid: + * g_srv_target_get_port: + * @target: a #GSrvTarget * - * The guid of the server. + * Gets @target's port * - * Since: 2.26 + * Returns: @target's port + * Since: 2.22 */ /** - * GProxyAddressEnumerator: + * g_srv_target_get_priority: + * @target: a #GSrvTarget * - * A subclass of #GSocketAddressEnumerator that takes another address - * enumerator and wraps its results in #GProxyAddress<!-- -->es as - * directed by the default #GProxyResolver. + * Gets @target's priority. You should not need to look at this; + * #GResolver already sorts the targets according to the algorithm in + * RFC 2782. + * + * Returns: @target's priority + * Since: 2.22 */ /** - * SECTION:gdesktopappinf: - * @title: GDesktopAppInfo - * @short_description: Application information from desktop files - * @include: gio/gdesktopappinfo.h + * g_srv_target_get_weight: + * @target: a #GSrvTarget * - * #GDesktopAppInfo is an implementation of #GAppInfo based on - * desktop files. - * Note that <filename><gio/gdesktopappinfo.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Gets @target's weight. You should not need to look at this; + * #GResolver already sorts the targets according to the algorithm in + * RFC 2782. + * + * Returns: @target's weight + * Since: 2.22 */ /** - * GDBusErrorEntry: - * @error_code: An error code. - * @dbus_error_name: The D-Bus error name to associate with @error_code. + * g_srv_target_list_sort: (skip) + * @targets: a #GList of #GSrvTarget * - * Struct used in g_dbus_error_register_error_domain(). + * Sorts @targets in place according to the algorithm in RFC 2782. * - * Since: 2.26 + * Returns: (transfer full): the head of the sorted list. + * Since: 2.22 */ /** - * g_unix_socket_address_new_with_type: - * @path: (array length=path_len) (element-type gchar): the name - * @path_len: the length of @path, or -1 - * @type: a #GUnixSocketAddressType + * g_srv_target_new: + * @hostname: the host that the service is running on + * @port: the port that the service is running on + * @priority: the target's priority + * @weight: the target's weight * - * Creates a new #GUnixSocketAddress of type @type with name @path. - * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to - * calling g_unix_socket_address_new(). - * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len - * bytes of @path will be copied to the socket's path, and only those - * bytes will be considered part of the name. (If @path_len is -1, - * then @path is assumed to be NUL-terminated.) For example, if @path - * was "test", then calling g_socket_address_get_native_size() on the - * returned socket would return 7 (2 bytes of overhead, 1 byte for the - * abstract-socket indicator byte, and 4 bytes for the name "test"). - * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then - * rest of the path will be padded with 0 bytes, and the entire - * zero-padded buffer will be considered the name. (As above, if - * this case, g_socket_address_get_native_size() will always return - * the full size of a <literal>struct sockaddr_un</literal>, although - * g_unix_socket_address_get_path_len() will still return just the - * length of @path. - * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over - * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course, - * when connecting to a server created by another process, you must - * use the appropriate type corresponding to how that process created - * its listening socket. + * Creates a new #GSrvTarget with the given parameters. + * You should not need to use this; normally #GSrvTarget<!-- -->s are + * created by #GResolver. * - * Returns: a new #GUnixSocketAddress - * Since: 2.26 + * Returns: a new #GSrvTarget. + * Since: 2.22 */ /** - * G_DEFINE_BOXED_TYPE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @copy_func: the #GBoxedCopyFunc for the new type - * @free_func: the #GBoxedFreeFunc for the new type + * g_tcp_connection_get_graceful_disconnect: + * @connection: a #GTcpConnection * - * A convenience macro for boxed type implementations, which defines a - * type_name_get_type() function registering the boxed type. + * Checks if graceful disconnects are used. See + * g_tcp_connection_set_graceful_disconnect(). * - * Since: 2.26 + * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise + * Since: 2.22 */ /** - * G_TYPE_VALUE_ARRAY: + * g_tcp_connection_set_graceful_disconnect: + * @connection: a #GTcpConnection + * @graceful_disconnect: Whether to do graceful disconnects or not * - * The type ID of the "GValueArray" type which is a boxed type, - * used to pass around pointers to GValueArrays. + * This enabled graceful disconnects on close. A graceful disconnect + * means that we signal the recieving end that the connection is terminated + * and wait for it to close the connection before closing the connection. + * A graceful disconnect means that we can be sure that we successfully sent + * all the outstanding data to the other end, or get an error reported. + * However, it also means we have to wait for all the data to reach the + * other side and for it to acknowledge this by closing the socket, which may + * take a while. For this reason it is disabled by default. + * + * Since: 2.22 */ /** - * G_IS_PARAM_SPEC_UINT: - * @pspec: a valid #GParamSpec instance + * g_tcp_wrapper_connection_get_base_io_stream: + * @conn: a #GTcpWrapperConnection * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. + * Get's @conn's base #GIOStream * - * Returns: %TRUE on success. + * Returns: (transfer none): @conn's base #GIOStream */ /** - * g_application_command_line_get_arguments: - * @cmdline: a #GApplicationCommandLine - * @argc: (out): the length of the arguments array, or %NULL + * g_tcp_wrapper_connection_new: + * @base_io_stream: the #GIOStream to wrap + * @socket: the #GSocket associated with @base_io_stream * - * Gets the list of arguments that was passed on the command line. - * The strings in the array may contain non-utf8 data. - * The return value is %NULL-terminated and should be freed using - * g_strfreev(). - * containing the arguments (the argv) + * Wraps @base_io_stream and @socket together as a #GSocketConnection. * - * Returns: (array length=argc) (transfer full): the string array + * Returns: the new #GSocketConnection. * Since: 2.28 */ /** - * g_io_stream_get_input_stream: - * @stream: a #GIOStream + * g_themed_icon_append_name: + * @icon: a #GThemedIcon + * @iconname: name of icon to append to list of icons from within @icon. * - * Gets the input stream for this object. This is used - * for reading. - * Do not free. + * Append a name to the list of icons from within @icon. + * <note><para> + * Note that doing so invalidates the hash computed by prior calls + * to g_icon_hash(). + * </para></note> + */ + + +/** + * g_themed_icon_get_names: + * @icon: a #GThemedIcon. * - * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. - * Since: 2.22 + * Gets the names of icons from within @icon. + * + * Returns: (transfer none): a list of icon names. */ /** - * GDBusServer:address: + * g_themed_icon_new: + * @iconname: a string containing an icon name. * - * The D-Bus address to listen on. + * Creates a new themed icon for @iconname. * - * Since: 2.26 + * Returns: (transfer full): a new #GThemedIcon. */ /** - * G_INITIALLY_UNOWNED_GET_CLASS: - * @object: a #GInitiallyUnowned instance. + * g_themed_icon_new_from_names: + * @iconnames: (array length=len): an array of strings containing icon names. + * @len: the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated * - * Get the class structure associated to a #GInitiallyUnowned instance. + * Creates a new themed icon for @iconnames. * - * Returns: pointer to object class structure. + * Returns: (transfer full): a new #GThemedIcon */ /** - * g_unix_socket_address_get_path_len: - * @address: a #GInetSocketAddress + * g_themed_icon_new_with_default_fallbacks: + * @iconname: a string containing an icon name * - * Gets the length of @address's path. - * For details, see g_unix_socket_address_get_path(). + * Creates a new themed icon for @iconname, and all the names + * that can be created by shortening @iconname at '-' characters. + * In the following example, @icon1 and @icon2 are equivalent: + * |[ + * const char *names[] = { + * "gnome-dev-cdrom-audio", + * "gnome-dev-cdrom", + * "gnome-dev", + * "gnome" + * }; + * icon1 = g_themed_icon_new_from_names (names, 4); + * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio"); + * ]| * - * Returns: the length of the path - * Since: 2.22 + * Returns: (transfer full): a new #GThemedIcon. */ /** - * SECTION:gfileico: - * @short_description: Icons pointing to an image file - * @include: gio/gio.h - * @see_also: #GIcon, #GLoadableIcon + * g_themed_icon_prepend_name: + * @icon: a #GThemedIcon + * @iconname: name of icon to prepend to list of icons from within @icon. * - * #GFileIcon specifies an icon by pointing to an image file - * to be used as icon. + * Prepend a name to the list of icons from within @icon. + * <note><para> + * Note that doing so invalidates the hash computed by prior calls + * to g_icon_hash(). + * </para></note> + * + * Since: 2.18 */ /** - * g_socket_listener_close: - * @listener: a #GSocketListener + * g_threaded_socket_service_new: + * @max_threads: the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit * - * Closes all the sockets in the listener. + * Creates a new #GThreadedSocketService with no listeners. Listeners + * must be added with g_socket_service_add_listeners(). * + * Returns: a new #GSocketService. * Since: 2.22 */ /** - * g_data_input_stream_read_line: - * @stream: a given #GDataInputStream. - * @length: (out): a #gsize to get the length of the data read in. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. + * g_tls_backend_get_certificate_type: + * @backend: the #GTlsBackend * - * Reads a line from the data input stream. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * (without the newlines). Set @length to a #gsize to get the - * length of the read line. On an error, it will return %NULL and - * still return %NULL, but @error won't be set. + * Gets the #GType of @backend's #GTlsCertificate implementation. + * implementation. * - * Returns: (transfer full): a string with the line that was read in + * Returns: the #GType of @backend's #GTlsCertificate + * Since: 2.28 */ /** - * G_TYPE_CHECK_INSTANCE_TYPE: - * @instance: Location of a #GTypeInstance structure. - * @g_type: The type to be checked + * g_tls_backend_get_client_connection_type: + * @backend: the #GTlsBackend * - * Checks if @instance is an instance of the type identified by @g_type. - * This macro should only be used in type implementations. + * Gets the #GType of @backend's #GTlsClientConnection implementation. + * implementation. * - * Returns: %TRUE on success. + * Returns: the #GType of @backend's #GTlsClientConnection + * Since: 2.28 */ /** - * SECTION:gvolumemonito: - * @short_description: Volume Monitor - * @include: gio/gio.h - * @see_also: #GFileMonitor + * g_tls_backend_get_default: * - * #GVolumeMonitor is for listing the user interesting devices and volumes - * on the computer. In other words, what a file selector or file manager - * would show in a sidebar. - * #GVolumeMonitor is not <link - * linkend="g-main-context-push-thread-default">thread-default-context - * aware</link>, and so should not be used other than from the main - * thread, with no thread-default-context active. + * Gets the default #GTlsBackend for the system. + * + * Returns: a #GTlsBackend + * Since: 2.28 */ /** - * g_dbus_connection_is_closed: - * @connection: A #GDBusConnection. + * g_tls_backend_get_server_connection_type: + * @backend: the #GTlsBackend * - * Gets whether @connection is closed. + * Gets the #GType of @backend's #GTlsServerConnection implementation. + * implementation. * - * Returns: %TRUE if the connection is closed, %FALSE otherwise. - * Since: 2.26 + * Returns: the #GType of @backend's #GTlsServerConnection + * Since: 2.28 */ /** - * g_atomic_int_inc: - * @atomic: a pointer to an integer. + * g_tls_backend_supports_tls: + * @backend: the #GTlsBackend * - * Atomically increments the integer pointed to by @atomic by 1. + * Checks if TLS is supported; if this returns %FALSE for the default + * #GTlsBackend, it means no "real" TLS backend is available. * - * Since: 2.4 + * Returns: whether or not TLS is supported + * Since: 2.28 */ /** - * GCancellable::cancelled: - * @cancellable: a #GCancellable. + * g_tls_certificate_get_issuer: + * @cert: a #GTlsCertificate * - * Emitted when the operation has been cancelled. - * Can be used by implementations of cancellable operations. If the - * operation is cancelled from another thread, the signal will be - * emitted in the thread that cancelled the operation, not the - * thread that is running the operation. - * Note that disconnecting from this signal (or any signal) in a - * multi-threaded program is prone to race conditions. For instance - * it is possible that a signal handler may be invoked even - * <emphasis>after</emphasis> a call to - * g_signal_handler_disconnect() for that handler has already - * returned. - * There is also a problem when cancellation happen - * right before connecting to the signal. If this happens the - * signal will unexpectedly not be emitted, and checking before - * connecting to the signal leaves a race condition where this is - * still happening. - * In order to make it safe and easy to connect handlers there - * g_cancellable_disconnect() which protect against problems - * like this. - * An example of how to us this: - * |[ - * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/ - * if (g_cancellable_set_error_if_cancelled (cancellable)) - * return; - * /<!-- -->* Set up all the data needed to be able to - * * handle cancellation of the operation *<!-- -->/ - * my_data = my_data_new (...); - * id = 0; - * if (cancellable) - * id = g_cancellable_connect (cancellable, - * G_CALLBACK (cancelled_handler) - * data, NULL); - * /<!-- -->* cancellable operation here... *<!-- -->/ - * g_cancellable_disconnect (cancellable, id); - * /<!-- -->* cancelled_handler is never called after this, it - * * is now safe to free the data *<!-- -->/ - * my_data_free (my_data); - * ]| - * Note that the cancelled signal is emitted in the thread that - * the user cancelled from, which may be the main thread. So, the - * cancellable signal should not do something that can block. + * Gets the #GTlsCertificate representing @cert's issuer, if known + * or %NULL if @cert is self-signed or signed with an unknown + * certificate. * - * Are two helper functions: g_cancellable_connect() and + * Returns: (transfer none): The certificate of @cert's issuer, + * Since: 2.28 */ /** - * G_PARAM_STATIC_STRINGS: + * g_tls_certificate_list_new_from_file: + * @file: file containing PEM-encoded certificates to import + * @error: #GError for error reporting, or %NULL to ignore. * - * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. - * Since 2.13.0 + * Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded + * data in @file. If @file cannot be read or parsed, the function will + * return %NULL and set @error. If @file does not contain any + * PEM-encoded certificates, this will return an empty list and not + * set @error. + * #GList containing #GTlsCertificate objects. You must free the list + * and its contents when you are done with it. + * + * Returns: (element-type Gio.TlsCertificate) (transfer full): a + * Since: 2.28 */ /** - * g_file_attribute_info_list_dup: - * @list: a #GFileAttributeInfoList to duplicate. + * g_tls_certificate_new_from_file: + * @file: file containing a PEM-encoded certificate to import + * @error: #GError for error reporting, or %NULL to ignore. * - * Makes a duplicate of a file attribute info list. + * Creates a #GTlsCertificate from the PEM-encoded data in @file. If + * set @error. Otherwise, this behaves like g_tls_certificate_new(). * - * Returns: a copy of the given @list. + * Returns: the new certificate, or %NULL on error + * Since: 2.28 */ /** - * g_app_info_get_commandline: - * @appinfo: a #GAppInfo + * g_tls_certificate_new_from_files: + * @cert_file: file containing a PEM-encoded certificate to import + * @key_file: file containing a PEM-encoded private key to import + * @error: #GError for error reporting, or %NULL to ignore. * - * Gets the commandline with which the application will be - * started. - * or %NULL if this information is not available + * 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(). * - * Returns: a string containing the @appinfo's commandline, - * Since: 2.20 + * Returns: the new certificate, or %NULL on error + * Since: 2.28 */ /** - * g_dbus_interface_info_unref: - * @info: A #GDBusInterfaceInfo. + * g_tls_certificate_new_from_pem: + * @data: PEM-encoded certificate data + * @length: the length of @data, or -1 if it's 0-terminated. + * @error: #GError for error reporting, or %NULL to ignore. * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. + * Creates a new #GTlsCertificate from the PEM-encoded data in @data. + * If @data includes both a certificate and a private key, then the + * returned certificate will include the private key data as well. + * If @data includes multiple certificates, only the first one will be + * parsed. * - * Since: 2.26 + * Returns: the new certificate, or %NULL if @data is invalid + * Since: 2.28 */ /** - * g_charset_converter_get_num_fallbacks: - * @converter: a #GCharsetConverter + * g_tls_certificate_verify: + * @cert: a #GTlsCertificate + * @identity: (allow-none): the expected peer identity + * @trusted_ca: (allow-none): the certificate of a trusted authority * - * Gets the number of fallbacks that @converter has applied so far. + * This verifies @cert and returns a set of #GTlsCertificateFlags + * indicating any problems found with it. This can be used to verify a + * certificate outside the context of making a connection, or to + * check a certificate against a CA that is not part of the system + * CA database. + * If @identity is not %NULL, @cert's name(s) will be compared against + * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return + * value if it does not match. If @identity is %NULL, that bit will + * never be set in the return value. + * If @trusted_ca is not %NULL, then @cert (or one of the certificates + * in its chain) must be signed by it, or else + * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If + * value. + * (All other #GTlsCertificateFlags values will always be set or unset + * as appropriate.) * - * Returns: the number of fallbacks that @converter has applied - * Since: 2.24 + * Returns: the appropriate #GTlsCertificateFlags + * Since: 2.28 */ /** - * g_file_enumerator_is_closed: - * @enumerator: a #GFileEnumerator. + * g_tls_client_connection_get_accepted_cas: + * @conn: the #GTlsClientConnection * - * Checks if the file enumerator has been closed. + * Gets the list of distinguished names of the Certificate Authorities + * that the server will accept certificates from. This will be set + * during the TLS handshake if the server requests a certificate. + * Otherwise, it will be %NULL. + * Each item in the list is a #GByteArray which contains the complete + * subject DN of the certificate authority. + * CA DNs. You should unref each element with g_byte_array_unref() and then + * the free the list with g_list_free(). * - * Returns: %TRUE if the @enumerator is closed. + * Returns: (element-type GByteArray) (transfer full): the list of + * Since: 2.28 */ /** - * g_emblem_new: - * @icon: a GIcon containing the icon. + * g_tls_client_connection_get_server_identity: + * @conn: the #GTlsClientConnection * - * Creates a new emblem for @icon. + * Gets @conn's expected server identity + * expected server identity, or %NULL if the expected identity is not + * known. * - * Returns: a new #GEmblem. - * Since: 2.18 + * Returns: a #GSocketConnectable describing the + * Since: 2.28 */ /** - * G_PARAM_MASK: + * g_tls_client_connection_get_use_ssl3: + * @conn: the #GTlsClientConnection * - * Mask containing the bits of #GParamSpec.flags which are reserved for GLib. + * Gets whether @conn will use SSL 3.0 rather than the + * highest-supported version of TLS; see + * g_tls_client_connection_set_use_ssl3(). + * + * Returns: whether @conn will use SSL 3.0 + * Since: 2.28 */ /** - * G_DEFINE_INTERFACE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. + * g_tls_client_connection_get_validation_flags: + * @conn: the #GTlsClientConnection * - * A convenience macro for #GTypeInterface definitions, which declares - * a default vtable initialization function and defines a *_get_type() - * function. - * The macro expects the interface initialization function to have the - * name <literal>t_n ## _default_init</literal>, and the interface - * structure to have the name <literal>TN ## Interface</literal>. + * Gets @conn's validation flags * - * Since: 2.24 + * Returns: the validation flags + * Since: 2.28 */ /** - * g_file_has_uri_scheme: - * @file: input #GFile. - * @uri_scheme: a string containing a URI scheme. + * g_tls_client_connection_new: + * @base_io_stream: the #GIOStream to wrap + * @server_identity: (allow-none): the expected identity of the server + * @error: #GError for error reporting, or %NULL to ignore. * - * Checks to see if a #GFile has a given URI scheme. - * This call does no blocking i/o. - * given URI scheme, %FALSE if URI scheme is %NULL, - * not supported, or #GFile is invalid. + * Creates a new #GTlsClientConnection wrapping @base_io_stream (which + * must have pollable input and output streams) which is assumed to + * communicate with the server identified by @server_identity. * - * Returns: %TRUE if #GFile's backend supports the + * Returns: the new #GTlsClientConnection, or %NULL on error + * Since: 2.28 */ /** - * g_simple_async_result_new_take_error: (skip) - * @source_object: (allow-none): a #GObject, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data passed to @callback - * @error: a #GError + * g_tls_client_connection_set_server_identity: + * @conn: the #GTlsClientConnection + * @identity: a #GSocketConnectable describing the expected server identity * - * Creates a #GSimpleAsyncResult from an error condition, and takes over the - * caller's ownership of @error, so the caller does not need to free it anymore. + * Sets @conn's expected server identity, which is used both to tell + * servers on virtual hosts which certificate to present, and also + * to let @conn know what name to look for in the certificate when + * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. * - * Returns: a #GSimpleAsyncResult * Since: 2.28 */ /** - * SECTION:gsimpleactiongrou: - * @title: GSimpleActionGroup - * @short_description: A simple GActionGroup implementation + * g_tls_client_connection_set_use_ssl3: + * @conn: the #GTlsClientConnection + * @use_ssl3: whether to use SSL 3.0 * - * #GSimpleActionGroup is a hash table filled with #GAction objects, - * implementing the #GActionGroup interface. + * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than + * trying to properly negotiate the right version of TLS or SSL to use. + * This can be used when talking to servers that do not implement the + * fallbacks correctly and which will therefore fail to handshake with + * a "modern" TLS handshake attempt. + * + * Since: 2.28 */ /** - * GSocketConnectableIface: - * @g_iface: The parent interface. - * @enumerate: Creates a #GSocketAddressEnumerator - * @proxy_enumerate: Creates a #GProxyAddressEnumerator + * g_tls_client_connection_set_validation_flags: + * @conn: the #GTlsClientConnection + * @flags: the #GTlsCertificateFlags to use * - * Provides an interface for returning a #GSocketAddressEnumerator - * and #GProxyAddressEnumerator + * Sets @conn's validation flags, to override the default set of + * checks performed when validating a server certificate. By default, + * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. + * + * Since: 2.28 */ /** - * GPermission:can-release: + * g_tls_connection_emit_accept_certificate: + * @conn: a #GTlsConnection + * @peer_cert: the peer's #GTlsCertificate + * @errors: the problems with @peer_cert * - * %TRUE if it is generally possible to release the permission by calling - * g_permission_release(). + * Used by #GTlsConnection implementations to emit the + * #GTlsConnection::accept-certificate signal. + * %TRUE to accept @peer_cert + * + * Returns: %TRUE if one of the signal handlers has returned + * Since: 2.28 */ /** - * SECTION:gwin32inputstrea: - * @short_description: Streaming input operations for Windows file handles - * @include: gio/gwin32inputstream.h - * @see_also: #GInputStream + * g_tls_connection_get_certificate: + * @conn: a #GTlsConnection * - * #GWin32InputStream implements #GInputStream for reading from a - * Windows file handle. - * Note that <filename><gio/gwin32inputstream.h></filename> belongs - * to the Windows-specific GIO interfaces, thus you have to use the - * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it. + * Gets @conn's certificate, as set by + * g_tls_connection_set_certificate(). + * + * Returns: (transfer none): @conn's certificate, or %NULL + * Since: 2.28 */ /** - * g_bus_watch_name_on_connection_with_closures: - * @connection: A #GDBusConnection. - * @name: The name (well-known or unique) to watch. - * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. - * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. + * g_tls_connection_get_peer_certificate: + * @conn: a #GTlsConnection * - * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for - * easier binding in other languages. - * g_bus_unwatch_name() to stop watching the name. + * Gets @conn's peer's certificate after the handshake has completed. + * (It is not set during the emission of + * #GTlsConnection::accept-certificate.) * - * Returns: An identifier (never 0) that an be used with - * Rename to: g_bus_watch_name_on_connection - * Since: 2.26 + * Returns: (transfer none): @conn's peer's certificate, or %NULL + * Since: 2.28 */ /** - * g_file_mount_enclosing_volume: - * @location: input #GFile. - * @flags: flags affecting the operation - * @mount_operation: a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL. - * @user_data: the data to pass to callback function + * g_tls_connection_get_peer_certificate_errors: + * @conn: a #GTlsConnection * - * Starts a @mount_operation, mounting the volume that contains the file @location. - * When this operation has completed, @callback will be called with - * g_file_mount_enclosing_volume_finish(). - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Gets the errors associated with validating @conn's peer's + * certificate, after the handshake has completed. (It is not set + * during the emission of #GTlsConnection::accept-certificate.) + * + * Returns: @conn's peer's certificate errors + * Since: 2.28 */ /** - * G_PARAM_SPEC_BOXED: - * @pspec: a valid #GParamSpec instance + * g_tls_connection_get_rehandshake_mode: + * @conn: a #GTlsConnection * - * Cast a #GParamSpec instance into a #GParamSpecBoxed. + * Gets @conn rehandshaking mode. See + * g_tls_connection_set_rehandshake() for details. + * + * Returns: @conn's rehandshaking mode + * Since: 2.28 */ /** - * GVolumeMonitor::mount-added: - * @volume_monitor: The volume monitor emitting the signal. - * @mount: a #GMount that was added. + * g_tls_connection_get_require_close_notify: + * @conn: a #GTlsConnection * - * Emitted when a mount is added. + * Tests whether or not @conn expects a proper TLS close notification + * when the connection is closed. See + * g_tls_connection_set_require_close_notify() for details. + * notification. + * + * Returns: %TRUE if @conn requires a proper TLS close + * Since: 2.28 */ /** - * GWin32OutputStream: + * g_tls_connection_get_use_system_certdb: + * @conn: a #GTlsConnection * - * Implements #GOutputStream for outputting to Windows file handles + * Gets whether @conn uses the system certificate database to verify + * peer certificates. See g_tls_connection_set_use_system_certdb(). + * + * Returns: whether @conn uses the system certificate database + * Since: 2.28 */ /** - * G_FLAGS_CLASS: - * @class: a valid #GFlagsClass + * g_tls_connection_handshake: + * @conn: a #GTlsConnection + * @cancellable: a #GCancellable, or %NULL + * @error: a #GError, or %NULL * - * Casts a derived #GFlagsClass structure into a #GFlagsClass structure. + * Attempts a TLS handshake on @conn. + * On the client side, it is never necessary to call this method; + * although the connection needs to perform a handshake after + * connecting (or after sending a "STARTTLS"-type command) and may + * need to rehandshake later if the server requests it, + * #GTlsConnection will handle this for you automatically when you try + * to send or receive data on the connection. However, you can call + * g_tls_connection_handshake() manually if you want to know for sure + * whether the initial handshake succeeded or failed (as opposed to + * just immediately trying to write to @conn's output stream, in which + * case if it fails, it may not be possible to tell if it failed + * before or after completing the handshake). + * Likewise, on the server side, although a handshake is necessary at + * the beginning of the communication, you do not need to call this + * function explicitly unless you want clearer error reporting. + * However, you may call g_tls_connection_handshake() later on to + * renegotiate parameters (encryption methods, etc) with the client. + * #GTlsConnection::accept_certificate may be emitted during the + * handshake. + * + * Returns: success or failure + * Since: 2.28 */ /** - * G_IS_PARAM_SPEC_LONG: - * @pspec: a valid #GParamSpec instance + * g_tls_connection_handshake_async: + * @conn: a #GTlsConnection + * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @cancellable: a #GCancellable, or %NULL + * @callback: callback to call when the handshake is complete + * @user_data: the data to pass to the callback function * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. + * Asynchronously performs a TLS handshake on @conn. See + * g_tls_connection_handshake() for more information. * - * Returns: %TRUE on success. + * Since: 2.28 */ /** - * g_settings_get_flags: - * @settings: a #GSettings object - * @key: the key to get the value for - * @returns: the flags value + * g_tls_connection_handshake_finish: + * @conn: a #GTlsConnection + * @result: a #GAsyncResult. + * @error: a #GError pointer, or %NULL * - * Gets the value that is stored in @settings for @key and converts it - * to the flags value that it represents. - * In order to use this function the type of the value must be an array - * of strings and it must be marked in the schema file as an flags type. - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or is not marked as a flags type. - * If the value stored in the configuration database is not a valid - * value for the flags type then this function will return the default - * value. + * Finish an asynchronous TLS handshake operation. See + * g_tls_connection_handshake() for more information. + * case @error will be set. * - * Since: 2.26 + * Returns: %TRUE on success, %FALSE on failure, in which + * Since: 2.28 */ /** - * g_file_info_get_attribute_stringv: - * @info: a #GFileInfo. - * @attribute: a file attribute key. + * g_tls_connection_set_certificate: + * @conn: a #GTlsConnection + * @certificate: the certificate to use for @conn * - * Gets the value of a stringv attribute. If the attribute does - * not contain a stringv, %NULL will be returned. - * %NULL otherwise. Do not free. + * This sets the certificate that @conn will present to its peer + * during the TLS handshake. For a #GTlsServerConnection, it is + * mandatory to set this, and that will normally be done at construct + * time. + * For a #GTlsClientConnection, this is optional. If a handshake fails + * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server + * requires a certificate, and if you try connecting again, you should + * call this method first. You can call + * g_tls_client_connection_get_accepted_cas() on the failed connection + * to get a list of Certificate Authorities that the server will + * accept certificates from. + * (It is also possible that a server will allow the connection with + * or without a certificate; in that case, if you don't provide a + * certificate, you can tell that the server requested one by the fact + * that g_tls_client_connection_get_accepted_cas() will return + * non-%NULL.) * - * Returns: (transfer none): the contents of the @attribute value as a stringv, or - * Since: 2.22 + * Since: 2.28 */ /** - * GIcon: + * g_tls_connection_set_rehandshake_mode: + * @conn: a #GTlsConnection + * @mode: the rehandshaking mode * - * An abstract type that specifies an icon. + * Sets how @conn behaves with respect to rehandshaking requests. + * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to + * rehandshake after the initial handshake is complete. (For a client, + * this means it will refuse rehandshake requests from the server, and + * for a server, this means it will close the connection with an error + * if the client attempts to rehandshake.) + * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a + * rehandshake only if the other end of the connection supports the + * TLS <literal>renegotiation_info</literal> extension. This is the + * default behavior, but means that rehandshaking will not work + * against older implementations that do not support that extension. + * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow + * rehandshaking even without the + * <literal>renegotiation_info</literal> extension. On the server side + * in particular, this is not recommended, since it leaves the server + * open to certain attacks. However, this mode is necessary if you + * need to allow renegotiation with older client software. + * + * Since: 2.28 */ /** - * GEmblem: + * g_tls_connection_set_require_close_notify: + * @conn: a #GTlsConnection + * @require_close_notify: whether or not to require close notification * - * An object for Emblems + * Sets whether or not @conn expects a proper TLS close notification + * before the connection is closed. If this is %TRUE (the default), + * then @conn will expect to receive a TLS close notification from its + * peer before the connection is closed, and will return a + * %G_TLS_ERROR_EOF error if the connection is closed without proper + * notification (since this may indicate a network error, or + * man-in-the-middle attack). + * In some protocols, the application will know whether or not the + * connection was closed cleanly based on application-level data + * (because the application-level data includes a length field, or is + * somehow self-delimiting); in this case, the close notify is + * redundant and sometimes omitted. (TLS 1.1 explicitly allows this; + * in TLS 1.0 it is technically an error, but often done anyway.) You + * can use g_tls_connection_set_require_close_notify() to tell @conn + * to allow an "unannounced" connection close, in which case the close + * will show up as a 0-length read, as in a non-TLS + * #GSocketConnection, and it is up to the application to check that + * the data has been fully received. + * Note that this only affects the behavior when the peer closes the + * connection; when the application calls g_io_stream_close() itself + * on @conn, this will send a close notification regardless of the + * setting of this property. If you explicitly want to do an unclean + * close, you can close @conn's #GTlsConnection:base-io-stream rather + * than closing @conn itself. + * + * Since: 2.28 */ /** - * g_file_attribute_matcher_unref: - * @matcher: a #GFileAttributeMatcher. + * g_tls_connection_set_use_system_certdb: + * @conn: a #GTlsConnection + * @use_system_certdb: whether to use the system certificate database * - * Unreferences @matcher. If the reference count falls below 1, - * the @matcher is automatically freed. + * Sets whether @conn uses the system certificate database to verify + * peer certificates. This is %TRUE by default. If set to %FALSE, then + * peer certificate validation will always set the + * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning + * #GTlsConnection::accept-certificate will always be emitted on + * client-side connections, unless that bit is not set in + * #GTlsClientConnection:validation-flags). + * + * Since: 2.28 */ /** - * g_proxy_address_new: - * @inetaddr: The proxy server #GInetAddress. - * @port: The proxy server port. - * @protocol: The proxy protocol to support, in lower case (e.g. socks, http). - * @dest_hostname: The destination hostname the the proxy should tunnel to. - * @dest_port: The destination port to tunnel to. - * @username: (allow-none): The username to authenticate to the proxy server (or %NULL). - * @password: (allow-none): The password to authenticate to the proxy server (or %NULL). + * g_tls_error_quark: * - * Creates a new #GProxyAddress for @inetaddr with @protocol that should - * tunnel through @dest_hostname and @dest_port. + * Gets the TLS error quark. * - * Returns: a new #GProxyAddress - * Since: 2.26 + * Returns: a #GQuark. + * Since: 2.28 */ /** - * g_file_monitor_emit_event: - * @monitor: a #GFileMonitor. - * @child: a #GFile. - * @other_file: a #GFile. - * @event_type: a set of #GFileMonitorEvent flags. + * g_tls_server_connection_new: + * @base_io_stream: the #GIOStream to wrap + * @certificate: (allow-none): the default server certificate, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. * - * Emits the #GFileMonitor::changed signal if a change - * has taken place. Should be called from file monitor - * implementations only. - * The signal will be emitted from an idle handler (in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * context</link>). + * Creates a new #GTlsServerConnection wrapping @base_io_stream (which + * must have pollable input and output streams). + * + * Returns: the new #GTlsServerConnection, or %NULL on error + * Since: 2.28 */ /** - * g_charset_converter_set_use_fallback: - * @converter: a #GCharsetConverter - * @use_fallback: %TRUE to use fallbacks + * g_try_new: + * @struct_type: the type of the elements to allocate + * @n_structs: the number of elements to allocate * - * Sets the #GCharsetConverter:use-fallback property. + * Attempts to allocate @n_structs elements of type @struct_type, and returns + * %NULL on failure. Contrast with g_new(), which aborts the program on failure. + * The returned pointer is cast to a pointer to the given type. + * The function returns %NULL when @n_structs is 0 of if an overflow occurs. * - * Since: 2.24 + * Since: 2.8 + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type */ /** - * g_socket_receive_with_blocking: - * @socket: a #GSocket - * @buffer: a buffer to read data into (which should be at least @size bytes long). - * @size: the number of bytes you want to read from the socket - * @blocking: whether to do blocking or non-blocking I/O - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. + * g_try_new0: + * @struct_type: the type of the elements to allocate + * @n_structs: the number of elements to allocate * - * This behaves exactly the same as g_socket_receive(), except that - * the choice of blocking or non-blocking behavior is determined by - * the @blocking argument rather than by @socket's properties. + * Attempts to allocate @n_structs elements of type @struct_type, initialized + * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts + * the program on failure. + * The returned pointer is cast to a pointer to the given type. + * The function returns %NULL when @n_structs is 0 of if an overflow occurs. * - * Returns: Number of bytes read, or -1 on error - * Since: 2.26 + * Since: 2.8 + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type */ /** - * g_win32_input_stream_set_close_handle: - * @stream: a #GWin32InputStream - * @close_handle: %TRUE to close the handle when done + * g_try_renew: + * @struct_type: the type of the elements to allocate + * @mem: the currently allocated memory + * @n_structs: the number of elements to allocate * - * Sets whether the handle of @stream shall be closed - * when the stream is closed. + * Attempts to reallocate the memory pointed to by @mem, so that it now has + * space for @n_structs elements of type @struct_type, and returns %NULL on + * failure. Contrast with g_renew(), which aborts the program on failure. + * It returns the new address of the memory, which may have been moved. + * The function returns %NULL if an overflow occurs. * - * Since: 2.26 + * Since: 2.8 + * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type */ /** - * g_node_insert_data: - * @parent: the #GNode to place the new #GNode under - * @position: the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent - * @data: the data for the new #GNode + * g_unix_connection_receive_credentials: + * @connection: A #GUnixConnection. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Inserts a new #GNode at the given position. + * Receives credentials from the sending end of the connection. The + * sending end has to call g_unix_connection_send_credentials() (or + * similar) for this to work. + * As well as reading the credentials this also reads (and discards) a + * single byte from the stream, as this is required for credentials + * passing to work on some implementations. + * Other ways to exchange credentials with a foreign peer includes the + * #GUnixCredentialsMessage type and g_socket_get_credentials() function. + * g_object_unref()), %NULL if @error is set. * - * Returns: the new #GNode + * Returns: (transfer full): Received credentials on success (free with + * Since: 2.26 */ /** - * g_mount_get_name: - * @mount: a #GMount. + * g_unix_connection_receive_fd: + * @connection: a #GUnixConnection + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @error: (allow-none): #GError for error reporting, or %NULL to ignore * - * Gets the name of @mount. - * The returned string should be freed with g_free() - * when no longer needed. + * Receives a file descriptor from the sending end of the connection. + * The sending end has to call g_unix_connection_send_fd() for this + * to work. + * As well as reading the fd this also reads a single byte from the + * stream, as this is required for fd passing to work on some + * implementations. * - * Returns: the name for the given @mount. + * Returns: a file descriptor on success, -1 on error. + * Since: 2.22 */ /** - * g_file_info_set_attribute_boolean: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a boolean value. + * g_unix_connection_send_credentials: + * @connection: A #GUnixConnection. + * @cancellable: (allow-none): A #GCancellable or %NULL. + * @error: Return location for error or %NULL. * - * Sets the @attribute to contain the given @attr_value, - * if possible. + * Passes the credentials of the current user the receiving side + * of the connection. The recieving end has to call + * g_unix_connection_receive_credentials() (or similar) to accept the + * credentials. + * As well as sending the credentials this also writes a single NUL + * byte to the stream, as this is required for credentials passing to + * work on some implementations. + * Other ways to exchange credentials with a foreign peer includes the + * #GUnixCredentialsMessage type and g_socket_get_credentials() function. + * + * Returns: %TRUE on success, %FALSE if @error is set. + * Since: 2.26 */ /** - * g_mount_eject_with_operation_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_unix_connection_send_fd: + * @connection: a #GUnixConnection + * @fd: a file descriptor + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: (allow-none): #GError for error reporting, or %NULL to ignore. * - * Finishes ejecting a mount. If any errors occurred during the operation, + * Passes a file descriptor to the recieving side of the + * connection. The recieving end has to call g_unix_connection_receive_fd() + * to accept the file descriptor. + * As well as sending the fd this also writes a single byte to the + * stream, as this is required for fd passing to work on some + * implementations. * - * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. + * Returns: a %TRUE on success, %NULL on error. * Since: 2.22 */ /** - * SECTION:giomodul: - * @short_description: Loadable GIO Modules - * @include: gio/gio.h + * g_unix_credentials_message_get_credentials: + * @message: A #GUnixCredentialsMessage. * - * Provides an interface and default functions for loading and unloading - * modules. This is used internally to make GIO extensible, but can also - * be used by others to implement module loading. + * Gets the credentials stored in @message. + * + * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message. + * Since: 2.26 */ /** - * g_bus_get: - * @bus_type: A #GBusType. - * @cancellable: A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * g_unix_credentials_message_is_supported: * - * Asynchronously connects to the message bus specified by @bus_type. - * When the operation is finished, @callback will be invoked. You can - * then call g_bus_get_finish() to get the result of the operation. - * This is a asynchronous failable function. See g_bus_get_sync() for - * the synchronous version. + * Checks if passing a #GCredential on a #GSocket is supported on this platform. * + * Returns: %TRUE if supported, %FALSE otherwise * Since: 2.26 */ /** - * GInetAddress:is-mc-site-local: + * g_unix_credentials_message_new: * - * Whether this is a site-local multicast address. - * See g_inet_address_get_is_mc_site_local(). + * Creates a new #GUnixCredentialsMessage with credentials matching the current processes. * - * Since: 2.22 + * Returns: a new #GUnixCredentialsMessage + * Since: 2.26 */ /** - * g_dbus_method_invocation_get_sender: - * @invocation: A #GDBusMethodInvocation. + * g_unix_credentials_message_new_with_credentials: + * @credentials: A #GCredentials object. * - * Gets the bus name that invoked the method. + * Creates a new #GUnixCredentialsMessage holding @credentials. * - * Returns: A string. Do not free, it is owned by @invocation. + * Returns: a new #GUnixCredentialsMessage * Since: 2.26 */ /** - * g_credentials_is_same_user: - * @credentials: A #GCredentials. - * @other_credentials: A #GCredentials. - * @error: Return location for error or %NULL. + * g_unix_fd_list_append: + * @list: a #GUnixFDList + * @fd: a valid open file descriptor + * @error: a #GError pointer * - * Checks if @credentials and @other_credentials is the same user. - * This operation can fail if #GCredentials is not supported on the - * the OS. - * user, %FALSE otherwise or if @error is set. + * Adds a file descriptor to @list. + * The file descriptor is duplicated using dup(). You keep your copy + * of the descriptor and the copy contained in @list will be closed + * when @list is finalized. + * A possible cause of failure is exceeding the per-process or + * system-wide file descriptor limit. + * The index of the file descriptor in the list is returned. If you use + * this index with g_unix_fd_list_get() then you will receive back a + * duplicated copy of the same file descriptor. + * (and @error is set) * - * Returns: %TRUE if @credentials and @other_credentials has the same - * Since: 2.26 + * Returns: the index of the appended fd in case of success, else -1 + * Since: 2.24 */ /** - * g_data_output_stream_put_uint16: - * @stream: a #GDataOutputStream. - * @data: a #guint16. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_unix_fd_list_get: + * @list: a #GUnixFDList + * @index_: the index into the list + * @error: a #GError pointer * - * Puts an unsigned 16-bit integer into the output stream. + * Gets a file descriptor out of @list. + * programmer error for @index_ to be out of range; see + * g_unix_fd_list_get_length(). + * The file descriptor is duplicated using dup() and set as + * close-on-exec before being returned. You must call close() on it + * when you are done. + * A possible cause of failure is exceeding the per-process or + * system-wide file descriptor limit. * - * Returns: %TRUE if @data was successfully added to the @stream. + * Returns: the file descriptor, or -1 in case of error + * Since: 2.24 */ /** - * g_dbus_connection_send_message: - * @connection: A #GDBusConnection. - * @message: A #GDBusMessage - * @flags: Flags affecting how the message is sent. - * @out_serial: Return location for serial number assigned to @message when sending it or %NULL. - * @error: Return location for error or %NULL. + * g_unix_fd_list_get_length: + * @list: a #GUnixFDList * - * Asynchronously sends @message to the peer represented by @connection. - * Unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number - * will be assigned by @connection and set on @message via - * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the - * serial number used will be written to this location prior to - * submitting the message to the underlying transport. - * If @connection is closed then the operation will fail with - * %G_IO_ERROR_CLOSED. If @message is not well-formed, - * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. - * See <xref linkend="gdbus-server"/> and <xref - * linkend="gdbus-unix-fd-client"/> for an example of how to use this - * low-level API to send and receive UNIX file descriptors. - * Note that @message must be unlocked, unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - * transmission, %FALSE if @error is set. + * contained within). * - * Returns: %TRUE if the message was well-formed and queued for - * Since: 2.26 + * Gets the length of @list (ie: the number of file descriptors + * Returns: the length of @list + * Since: 2.24 */ /** - * G_FILE_ATTRIBUTE_UNIX_GID: + * g_unix_fd_list_new: * - * A key in the "unix" namespace for getting the group ID for the file. - * This attribute is only available for UNIX file systems. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * Creates a new #GUnixFDList containing no file descriptors. + * + * Returns: a new #GUnixFDList + * Since: 2.24 */ /** - * g_main_is_running: - * @loop: a #GMainLoop + * g_unix_fd_list_new_from_array: + * @fds: (array length=n_fds): the initial list of file descriptors + * @n_fds: the length of #fds, or -1 * - * Checks if the main loop is running. + * Creates a new #GUnixFDList containing the file descriptors given in + * may no longer be used by the caller. The array itself is owned by + * the caller. + * Each file descriptor in the array should be set to close-on-exec. + * If @n_fds is -1 then @fds must be terminated with -1. * - * Returns: %TRUE if the main loop is running - * Deprecated: 2.2: Use g_main_loop_is_running() instead + * Returns: a new #GUnixFDList + * Since: 2.24 */ /** - * g_icon_equal: - * @icon1: pointer to the first #GIcon. - * @icon2: pointer to the second #GIcon. + * g_unix_fd_list_peek_fds: + * @list: a #GUnixFDList + * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL * - * Checks if two icons are equal. + * Returns the array of file descriptors that is contained in this + * object. + * After this call, the descriptors remain the property of @list. The + * caller must not close them and must not free the array. The array is + * valid only until @list is changed in any way. + * If @length is non-%NULL then it is set to the number of file + * descriptors in the returned array. The returned array is also + * terminated with -1. + * This function never returns %NULL. In case there are no file + * descriptors contained in @list, an empty array is returned. + * descriptors * - * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. + * Returns: (array length=length) (transfer none): an array of file + * Since: 2.24 */ /** - * g_volume_should_automount: - * @volume: a #GVolume + * g_unix_fd_list_steal_fds: + * @list: a #GUnixFDList + * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL * - * Returns whether the volume should be automatically mounted. + * Returns the array of file descriptors that is contained in this + * object. + * After this call, the descriptors are no longer contained in + * descriptors have been added). + * The return result of this function must be freed with g_free(). + * The caller is also responsible for closing all of the file + * descriptors. The file descriptors in the array are set to + * close-on-exec. + * If @length is non-%NULL then it is set to the number of file + * descriptors in the returned array. The returned array is also + * terminated with -1. + * This function never returns %NULL. In case there are no file + * descriptors contained in @list, an empty array is returned. + * descriptors * - * Returns: %TRUE if the volume should be automatically mounted. + * Returns: (array length=length) (transfer full): an array of file + * Since: 2.24 */ /** - * g_seekable_tell: - * @seekable: a #GSeekable. + * g_unix_fd_message_append_fd: + * @message: a #GUnixFDMessage + * @fd: a valid open file descriptor + * @error: a #GError pointer * - * Tells the current position within the stream. + * Adds a file descriptor to @message. + * The file descriptor is duplicated using dup(). You keep your copy + * of the descriptor and the copy contained in @message will be closed + * when @message is finalized. + * A possible cause of failure is exceeding the per-process or + * system-wide file descriptor limit. * - * Returns: the offset from the beginning of the buffer. + * Returns: %TRUE in case of success, else %FALSE (and @error is set) + * Since: 2.22 */ /** - * SECTION:gsimpleactio: - * @title: GSimpleAction - * @short_description: A simple GSimpleAction + * g_unix_fd_message_get_fd_list: + * @message: a #GUnixFDMessage * - * A #GSimpleAction is the obvious simple implementation of the #GSimpleAction - * interface. This is the easiest way to create an action for purposes of - * adding it to a #GSimpleActionGroup. - * See also #GtkAction. + * Gets the #GUnixFDList contained in @message. This function does not + * return a reference to the caller, but the returned list is valid for + * the lifetime of @message. + * + * Returns: (transfer none): the #GUnixFDList from @message + * Since: 2.24 */ /** - * g_socket_listener_add_inet_port: - * @listener: a #GSocketListener - * @port: an IP port number (non-zero) - * @source_object: (allow-none): Optional #GObject identifying this source - * @error: #GError for error reporting, or %NULL to ignore. + * g_unix_fd_message_new: * - * Helper function for g_socket_listener_add_address() that - * creates a TCP/IP socket listening on IPv4 and IPv6 (if - * supported) on the specified port on all interfaces. - * to accept to identify this particular source, which is - * useful if you're listening on multiple addresses and do - * different things depending on what address is connected to. + * Creates a new #GUnixFDMessage containing an empty file descriptor + * list. * - * Returns: %TRUE on success, %FALSE on error. + * Returns: a new #GUnixFDMessage * Since: 2.22 */ /** - * G_VARIANT_TYPE_TUPLE: + * g_unix_fd_message_new_with_fd_list: + * @fd_list: a #GUnixFDList * - * An indefinite type that is a supertype of every tuple type, - * regardless of the number of items in the tuple. + * Creates a new #GUnixFDMessage containing @list. + * + * Returns: a new #GUnixFDMessage + * Since: 2.24 */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT: + * g_unix_fd_message_steal_fds: + * @message: a #GUnixFDMessage + * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * Returns the array of file descriptors that is contained in this + * object. + * After this call, the descriptors are no longer contained in + * descriptors have been added). + * The return result of this function must be freed with g_free(). + * The caller is also responsible for closing all of the file + * descriptors. + * If @length is non-%NULL then it is set to the number of file + * descriptors in the returned array. The returned array is also + * terminated with -1. + * This function never returns %NULL. In case there are no file + * descriptors contained in @message, an empty array is returned. + * descriptors + * + * Returns: (array length=length) (transfer full): an array of file + * Since: 2.22 */ /** - * g_tls_client_connection_get_accepted_cas: - * @conn: the #GTlsClientConnection + * g_unix_input_stream_get_close_fd: + * @stream: a #GUnixInputStream * - * Gets the list of distinguished names of the Certificate Authorities - * that the server will accept certificates from. This will be set - * during the TLS handshake if the server requests a certificate. - * Otherwise, it will be %NULL. - * Each item in the list is a #GByteArray which contains the complete - * subject DN of the certificate authority. - * CA DNs. You should unref each element with g_byte_array_unref() and then - * the free the list with g_list_free(). + * Returns whether the file descriptor of @stream will be + * closed when the stream is closed. * - * Returns: (element-type GByteArray) (transfer full): the list of - * Since: 2.28 + * Returns: %TRUE if the file descriptor is closed when done + * Since: 2.20 */ /** - * g_dbus_connection_call_finish: - * @connection: A #GDBusConnection. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call(). - * @error: Return location for error or %NULL. + * g_unix_input_stream_get_fd: + * @stream: a #GUnixInputStream * - * Finishes an operation started with g_dbus_connection_call(). - * return values. Free with g_variant_unref(). + * Return the UNIX file descriptor that the stream reads from. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * Since: 2.26 + * Returns: The file descriptor of @stream + * Since: 2.20 */ /** - * g_proxy_resolver_lookup_async: - * @resolver: a #GProxyResolver - * @uri: a URI representing the destination to connect to - * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback + * g_unix_input_stream_new: + * @fd: a UNIX file descriptor + * @close_fd: %TRUE to close the file descriptor when done * - * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more - * details. + * Creates a new #GUnixInputStream for the given @fd. + * If @close_fd is %TRUE, the file descriptor will be closed + * when the stream is closed. * - * Since: 2.26 + * Returns: a new #GUnixInputStream */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC: + * g_unix_input_stream_set_close_fd: + * @stream: a #GUnixInputStream + * @close_fd: %TRUE to close the file descriptor when done * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) - * is automatically polled for media. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * Sets whether the file descriptor of @stream shall be closed + * when the stream is closed. * - * Since: 2.22 + * Since: 2.20 */ /** - * g_node_prev_sibling: - * @node: a #GNode + * g_unix_is_mount_path_system_internal: + * @mount_path: a mount path, e.g. <filename>/media/disk</filename> or <filename>/usr</filename> * - * Gets the previous sibling of a #GNode. - * node or %NULL + * Determines if @mount_path is considered an implementation of the + * OS. This is primarily used for hiding mountable and mounted volumes + * that only are used in the OS and has little to no relevance to the + * casual user. + * of the OS. * - * Returns: the previous sibling of @node, or %NULL if @node is the first + * Returns: %TRUE if @mount_path is considered an implementation detail */ /** - * G_IS_PARAM_SPEC_BOOLEAN: - * @pspec: a valid #GParamSpec instance + * g_unix_mount_at: (skip) + * @mount_path: path for a possible unix mount. + * @time_read: (out) (allow-none): guint64 to contain a timestamp. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. + * Gets a #GUnixMountEntry for a given mount path. If @time_read + * is set, it will be filled with a unix timestamp for checking + * if the mounts have changed since with g_unix_mounts_changed_since(). * - * Returns: %TRUE on success. + * Returns: (transfer full): a #GUnixMountEntry. */ /** - * G_FILE_ATTRIBUTE_FILESYSTEM_SIZE: + * g_unix_mount_compare: + * @mount1: first #GUnixMountEntry to compare. + * @mount2: second #GUnixMountEntry to compare. * - * A key in the "filesystem" namespace for getting the total size (in bytes) of the file system, - * used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType - * is %G_FILE_ATTRIBUTE_TYPE_UINT64. + * Compares two unix mounts. + * or less than @mount2, respectively. + * + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, */ /** - * SECTION:gsetting: - * @short_description: High-level API for application settings + * g_unix_mount_free: + * @mount_entry: a #GUnixMount. * - * The #GSettings class provides a convenient API for storing and retrieving - * application settings. - * When creating a GSettings instance, you have to specify a schema - * that describes the keys in your settings and their types and default - * values, as well as some other information. - * Normally, a schema has as fixed path that determines where the settings - * are stored in the conceptual global tree of settings. However, schemas - * can also be 'relocatable', i.e. not equipped with a fixed path. This is - * useful e.g. when the schema describes an 'account', and you want to be - * able to store a arbitrary number of accounts. - * Unlike other configuration systems (like GConf), GSettings does not - * restrict keys to basic types like strings and numbers. GSettings stores - * values as #GVariant, and allows any #GVariantType for keys. Key names - * are restricted to lowercase characters, numbers and '-'. Furthermore, - * the names must begin with a lowercase character, must not end - * with a '-', and must not contain consecutive dashes. Key names can - * be up to 32 characters long. - * 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 - * <tag class="attribute">gettext-domain</tag> attribute of the - * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag> - * elements and the category that is specified in the l10n attribute of the - * <tag class="starttag">key</tag> element. - * GSettings uses schemas in a compact binary form that is created - * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link> - * utility. The input is a schema description in an XML format that can be - * described by the following DTD: - * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/gschema.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]| - * At runtime, schemas are identified by their id (as specified - * in the <tag class="attribute">id</tag> attribute of the - * <tag class="starttag">schema</tag> element). The - * convention for schema ids is to use a dotted name, similar in - * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular, - * if the settings are for a specific service that owns a D-Bus bus name, - * the D-Bus bus name and schema id should match. For schemas which deal - * with settings not associated with one named application, the id should - * not use StudlyCaps, e.g. "org.gnome.font-rendering". - * In addition to #GVariant types, keys can have types that have enumerated - * types. These can be described by a <tag class="starttag">choice</tag>, - * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see - * <xref linkend="schema-enumerated"/>. The underlying type of - * such a key is string, but you can use g_settings_get_enum(), - * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags() - * access the numeric values corresponding to the string value of enum - * and flags keys. - * <example id="schema-default-values"><title>Default values</title> - * <programlisting><![CDATA[ - * <schemalist> - * <schema id="org.gtk.Test" path="/tests/" gettext-domain="test"> - * <key name="greeting" type="s"> - * <default l10n="messages">"Hello, earthlings"</default> - * <summary>A greeting</summary> - * <description> - * Greeting of the invading martians - * </description> - * </key> - * <key name="box" type="(ii)"> - * <default>(20,30)</default> - * </key> - * </schema> - * </schemalist> - * ]]></programlisting></example> - * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title> - * <programlisting><![CDATA[ - * <schemalist> - * <enum id="myenum"> - * <value nick="first" value="1"/> - * <value nick="second" value="2"/> - * </enum> - * <enum id="myflags"> - * <value nick="flag1" value="1"/> - * <value nick="flag2" value="2"/> - * <value nick="flag3" value="4"/> - * </enum> - * <schema id="org.gtk.Test"> - * <key name="key-with-range" type="i"> - * <range min="1" max="100"/> - * <default>10</default> - * </key> - * <key name="key-with-choices" type="s"> - * <choices> - * <choice value='Elisabeth'/> - * <choice value='Annabeth'/> - * <choice value='Joe'/> - * </choices> - * <aliases> - * <alias value='Anna' target='Annabeth'/> - * <alias value='Beth' target='Elisabeth'/> - * </aliases> - * <default>'Joe'</default> - * </key> - * <key name='enumerated-key' enum='myenum'> - * <default>'first'</default> - * </key> - * <key name='flags-key' flags='myflags'> - * <default>["flag1",flag2"]</default> - * </key> - * </schema> - * </schemalist> - * ]]></programlisting></example> - * <refsect2> - * <title>Vendor overrides</title> - * <para> - * Default values are defined in the schemas that get installed by - * an application. Sometimes, it is necessary for a vendor or distributor - * to adjust these defaults. Since patching the XML source for the schema - * is inconvenient and error-prone, - * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads - * so-called 'vendor override' files. These are keyfiles in the same - * directory as the XML schema sources which can override default values. - * The schema id serves as the group name in the key file, and the values - * are expected in serialized GVariant form, as in the following example: - * <informalexample><programlisting> - * [org.gtk.Example] - * key1='string' - * key2=1.5 - * </programlisting></informalexample> - * </para> - * </refsect2> - * <refsect2> - * <title>Binding</title> - * <para> - * A very convenient feature of GSettings lets you bind #GObject properties - * directly to settings, using g_settings_bind(). Once a GObject property - * has been bound to a setting, changes on either side are automatically - * propagated to the other side. GSettings handles details like - * mapping between GObject and GVariant types, and preventing infinite - * cycles. - * </para> - * <para> - * This makes it very easy to hook up a preferences dialog to the - * underlying settings. To make this even more convenient, GSettings - * looks for a boolean property with the name "sensitivity" and - * automatically binds it to the writability of the bound setting. - * If this 'magic' gets in the way, it can be suppressed with the - * #G_SETTINGS_BIND_NO_SENSITIVITY flag. - * </para> - * </refsect2> + * Frees a unix mount. */ /** - * g_volume_enumerate_identifiers: - * @volume: a #GVolume + * g_unix_mount_get_device_path: + * @mount_entry: a #GUnixMount. * - * Gets the kinds of <link linkend="volume-identifier">identifiers</link> - * that @volume has. Use g_volume_get_identifer() to obtain - * the identifiers themselves. - * of strings containing kinds of identifiers. Use g_strfreev() to free. + * Gets the device path for a unix mount. * - * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array + * Returns: a string containing the device path. */ /** - * g_zlib_decompressor_get_file_info: - * @decompressor: a #GZlibDecompressor + * g_unix_mount_get_fs_type: + * @mount_entry: a #GUnixMount. * - * Retrieves the #GFileInfo constructed from the GZIP header data - * of compressed data processed by @compressor, or %NULL if @decompressor's - * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, - * or the header data was not fully processed yet, or it not present in the - * data stream at all. + * Gets the filesystem type for the unix mount. * - * Returns: (transfer none): a #GFileInfo, or %NULL - * Since: 2.26 + * Returns: a string containing the file system type. */ /** - * SECTION:ginputstrea: - * @short_description: Base class for implementing streaming input - * @include: gio/gio.h + * g_unix_mount_get_mount_path: + * @mount_entry: input #GUnixMountEntry to get the mount path for. * - * GInputStream has functions to read from a stream (g_input_stream_read()), - * to close a stream (g_input_stream_close()) and to skip some content - * (g_input_stream_skip()). - * To copy the content of an input stream to an output stream without - * manually handling the reads and writes, use g_output_stream_splice(). - * All of these functions have async variants too. + * Gets the mount path for a unix mount. + * + * Returns: the mount path for @mount_entry. */ /** - * g_permission_impl_update: - * @permission: a #GPermission instance - * @allowed: the new value for the 'allowed' property - * @can_acquire: the new value for the 'can-acquire' property - * @can_release: the new value for the 'can-release' property + * g_unix_mount_guess_can_eject: + * @mount_entry: a #GUnixMountEntry * - * This function is called by the #GPermission implementation to update - * the properties of the permission. You should never call this - * function except from a #GPermission implementation. - * GObject notify signals are generated, as appropriate. + * Guesses whether a Unix mount can be ejected. * - * Since: 2.26 + * Returns: %TRUE if @mount_entry is deemed to be ejectable. */ /** - * GAsyncReadyCallback: - * @source_object: the object the asynchronous operation was started with. - * @res: a #GAsyncResult. - * @user_data: user data passed to the callback. + * g_unix_mount_guess_icon: + * @mount_entry: a #GUnixMountEntry * - * Type definition for a function that will be called back when an asynchronous - * operation within GIO has been completed. + * Guesses the icon of a Unix mount. + * + * Returns: (transfer full): a #GIcon */ /** - * g_dbus_method_invocation_return_gerror: - * @invocation: A #GDBusMethodInvocation. - * @error: A #GError. + * g_unix_mount_guess_name: + * @mount_entry: a #GUnixMountEntry * - * Like g_dbus_method_invocation_return_error() but takes a #GError - * instead of the error domain, error code and message. - * This method will free @invocation, you cannot use it afterwards. + * Guesses the name of a Unix mount. + * The result is a translated string. + * be freed with g_free() * - * Since: 2.26 + * Returns: A newly allocated string that must */ /** - * g_settings_list_children: - * @settings: a #GSettings object - * @returns: (transfer full) (element-type utf8): a list of the children on @settings + * g_unix_mount_guess_should_display: + * @mount_entry: a #GUnixMountEntry * - * Gets the list of children on @settings. - * The list is exactly the list of strings for which it is not an error - * to call g_settings_get_child(). - * For GSettings objects that are lists, this value can change at any - * time and you should connect to the "children-changed" signal to watch - * request a child after listing it only for it to have been destroyed - * in the meantime. For this reason, g_settings_get_child() may return - * %NULL even for a child that was listed by this function. - * For GSettings objects that are not lists, you should probably not be - * calling this function from "normal" code (since you should already - * know what children are in your schema). This function may still be - * useful there for introspection reasons, however. - * You should free the return value with g_strfreev() when you are done - * with it. + * Guesses whether a Unix mount should be displayed in the UI. * - * For those changes. note that there is a race condition here: you may + * Returns: %TRUE if @mount_entry is deemed to be displayable. */ /** - * g_app_launch_context_get_startup_notify_id: - * @context: a #GAppLaunchContext - * @info: a #GAppInfo - * @files: (element-type GFile): a #GList of of #GFile objects + * g_unix_mount_is_readonly: + * @mount_entry: a #GUnixMount. * - * Initiates startup notification for the application and returns the - * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation, - * if supported. - * Startup notification IDs are defined in the <ulink - * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"> - * FreeDesktop.Org Startup Notifications standard</ulink>. - * not supported. + * Checks if a unix mount is mounted read only. * - * Returns: a startup notification ID for the application, or %NULL if + * Returns: %TRUE if @mount_entry is read only. */ /** - * g_dbus_address_get_stream_finish: - * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). - * @out_guid: %NULL or return location to store the GUID extracted from @address, if any. - * @error: Return location for error or %NULL. + * g_unix_mount_is_system_internal: + * @mount_entry: a #GUnixMount. * - * Finishes an operation started with g_dbus_address_get_stream(). + * Checks if a unix mount is a system path. * - * Returns: (transfer full): A #GIOStream or %NULL if @error is set. - * Since: 2.26 + * Returns: %TRUE if the unix mount is for a system path. */ /** - * G_TYPE_BYTE_ARRAY: + * g_unix_mount_monitor_new: * - * The #GType for a boxed type holding a #GByteArray reference. + * 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. * - * Since: 2.22 + * Returns: a #GUnixMountMonitor. */ /** - * g_file_set_attribute_string: - * @file: input #GFile. - * @attribute: a string containing the attribute's name. - * @value: a string containing the attribute's value. - * @flags: #GFileQueryInfoFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL + * g_unix_mount_monitor_set_rate_limit: + * @mount_monitor: a #GUnixMountMonitor + * @limit_msec: a integer with the limit in milliseconds to poll for changes. * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. - * If @attribute is of a different type, this operation will fail. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Sets the rate limit to which the @mount_monitor will report + * consecutive change events to the mount and mount point entry files. * - * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise. + * Since: 2.18 */ /** - * g_file_read_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @error: a #GError, or %NULL + * g_unix_mount_point_compare: + * @mount1: a #GUnixMount. + * @mount2: a #GUnixMount. * - * Finishes an asynchronous file read operation started with - * g_file_read_async(). - * Free the returned object with g_object_unref(). + * Compares two unix mount points. + * or less than @mount2, respectively. * - * Returns: (transfer full): a #GFileInputStream or %NULL on error. + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, */ /** - * g_socket_client_connect_to_uri_finish: - * @client: a #GSocketClient. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_unix_mount_point_free: + * @mount_point: unix mount point to free. * - * Finishes an async connect operation. See g_socket_client_connect_to_uri_async() + * Frees a unix mount point. + */ + + +/** + * g_unix_mount_point_get_device_path: + * @mount_point: a #GUnixMountPoint. * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.26 + * Gets the device path for a unix mount point. + * + * Returns: a string containing the device path. */ /** - * G_TYPE_IS_VALUE: - * @type: A #GType value. + * g_unix_mount_point_get_fs_type: + * @mount_point: a #GUnixMountPoint. * - * Checks whether the passed in type ID can be used for g_value_init(). - * That is, this macro checks whether this type provides an implementation - * of the #GTypeValueTable functions required for a type to create a #GValue of. + * Gets the file system type for the mount point. * - * Returns: Whether @type is suitable as a #GValue type. + * Returns: a string containing the file system type. */ /** - * g_file_load_contents_async: - * @file: input #GFile. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to callback function + * g_unix_mount_point_get_mount_path: + * @mount_point: a #GUnixMountPoint. * - * Starts an asynchronous load of the @file's contents. - * For more details, see g_file_load_contents() which is - * the synchronous version of this call. - * When the load operation has completed, @callback will be called - * with @user data. To finish the operation, call - * g_file_load_contents_finish() with the #GAsyncResult returned by - * the @callback. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Gets the mount path for a unix mount point. + * + * Returns: a string containing the mount path. */ /** - * g_dbus_connection_call_sync: - * @connection: A #GDBusConnection. - * @bus_name: A unique or well-known bus name. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to invoke method on. - * @method_name: The name of the method to invoke. - * @parameters: A #GVariant tuple with parameters for the method or %NULL if not passing parameters. - * @reply_type: The expected type of the reply, or %NULL. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @cancellable: A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * g_unix_mount_point_guess_can_eject: + * @mount_point: a #GUnixMountPoint * - * Synchronously invokes the @method_name method on the - * If @connection is closed then the operation will fail with - * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the - * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters - * contains a value not compatible with the D-Bus protocol, the operation - * fails with %G_IO_ERROR_INVALID_ARGUMENT. - * If @reply_type is non-%NULL then the reply will be checked for having - * this type and an error will be raised if it does not match. Said - * another way, if you give a @reply_type then any non-%NULL return - * value will be of this type. - * If the @parameters #GVariant is floating, it is consumed. - * This allows convenient 'inline' use of g_variant_new(), e.g.: - * |[ - * g_dbus_connection_call_sync (connection, - * "org.freedesktop.StringThings", - * "/org/freedesktop/StringThings", - * "org.freedesktop.StringThings", - * "TwoStrings", - * g_variant_new ("(ss)", - * "Thing One", - * "Thing Two"), - * NULL, - * G_DBUS_CALL_FLAGS_NONE, - * -1, - * NULL, - * &error); - * ]| - * The calling thread is blocked until a reply is received. See - * g_dbus_connection_call() for the asynchronous version of - * this method. - * return values. Free with g_variant_unref(). + * Guesses whether a Unix mount point can be ejected. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * Since: 2.26 + * Returns: %TRUE if @mount_point is deemed to be ejectable. */ /** - * g_output_stream_write_all: - * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. - * @count: the number of bytes to write - * @bytes_written: (out): location to store the number of bytes that was written to the stream - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occuring, or %NULL to ignore + * g_unix_mount_point_guess_icon: + * @mount_point: a #GUnixMountPoint * - * Tries to write @count bytes from @buffer into the stream. Will block - * during the operation. - * This function is similar to g_output_stream_write(), except it tries to - * write as many bytes as requested, only stopping on an error. - * On a successful write of @count bytes, %TRUE is returned, and @bytes_written - * is set to @count. - * If there is an error during the operation FALSE is returned and @error - * is set to indicate the error status, @bytes_written is updated to contain - * the number of bytes written into the stream before the error occurred. + * Guesses the icon of a Unix mount point. * - * Returns: %TRUE on success, %FALSE if there was an error + * Returns: (transfer full): a #GIcon */ /** - * G_TYPE_PARAM_BOXED: + * g_unix_mount_point_guess_name: + * @mount_point: a #GUnixMountPoint * - * The #GType of #GParamSpecBoxed. + * Guesses the name of a Unix mount point. + * The result is a translated string. + * be freed with g_free() + * + * Returns: A newly allocated string that must */ /** - * g_file_monitor_file: - * @file: input #GFile. - * @flags: a set of #GFileMonitorFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, or %NULL. + * g_unix_mount_point_is_loopback: + * @mount_point: a #GUnixMountPoint. * - * Obtains a file monitor for the given file. If no file notification - * mechanism exists, then regular polling of the file is used. - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Free the returned object with g_object_unref(). + * Checks if a unix mount point is a loopback device. * - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. + * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise. */ /** - * SECTION:gapplicationcommandlin: - * @title: GApplicationCommandLine - * @short_description: A command-line invocation of an application - * @see_also: #GApplication + * g_unix_mount_point_is_readonly: + * @mount_point: a #GUnixMountPoint. * - * #GApplicationCommandLine represents a command-line invocation of - * an application. It is created by #GApplication and emitted - * in the #GApplication::command-line signal and virtual function. - * The class contains the list of arguments that the program was invoked - * with. It is also possible to query if the commandline invocation was - * commandline to this process). - * The exit status of the originally-invoked process may be set and - * messages can be printed to stdout or stderr of that process. The - * lifecycle of the originally-invoked process is tied to the lifecycle - * dropped). - * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * <example id="gapplication-example-cmdline2"><title>Complicated commandline handling</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> + * Checks if a unix mount point is read only. * - * Local (ie: the current process is running in direct response to the - * Invocation) or remote (ie: some other process forwarded the - * Of this object (ie: the process exits when the last reference is + * Returns: %TRUE if a mount point is read only. */ /** - * g_async_initable_new_finish: - * @initable: the #GAsyncInitable from the callback - * @res: the #GAsyncResult.from the callback - * @error: a #GError location to store the error occuring, or %NULL to ignore. + * g_unix_mount_point_is_user_mountable: + * @mount_point: a #GUnixMountPoint. * - * Finishes the async construction for the various g_async_initable_new calls, - * returning the created object or %NULL on error. - * g_object_unref(). + * Checks if a unix mount point is mountable by the user. * - * Returns: (transfer full): a newly created #GObject, or %NULL on error. Free with - * Since: 2.22 + * Returns: %TRUE if the mount point is user mountable. */ /** - * g_pollable_input_stream_create_source: (skip) - * @stream: a #GPollableInputStream. - * @cancellable: (allow-none): a #GCancellable, or %NULL + * g_unix_mount_points_changed_since: + * @time: guint64 to contain a timestamp. * - * Creates a #GSource that triggers when @stream can be read, or - * source is of the #GPollableSourceFunc type. - * As with g_pollable_input_stream_is_readable(), it is possible that - * the stream may not actually be readable even after the source - * triggers, so you should use g_pollable_input_stream_read_nonblocking() - * rather than g_input_stream_read() from the callback. + * Checks if the unix mount points have changed since a given unix time. * - * Returns: (transfer full): a new #GSource - * Since: 2.28 + * Returns: %TRUE if the mount points have changed since @time. */ /** - * g_file_supports_thread_contexts: - * @file: a #GFile. + * g_unix_mount_points_get: (skip) + * @time_read: (out) (allow-none): guint64 to contain a timestamp. * - * Checks if @file supports <link - * linkend="g-main-context-push-thread-default-context">thread-default - * contexts</link>. If this returns %FALSE, you cannot perform - * asynchronous operations on @file in a thread that has a - * thread-default context. + * Gets a #GList of #GUnixMountPoint containing the unix mount points. + * If @time_read is set, it will be filled with the mount timestamp, + * allowing for checking if the mounts have changed with + * g_unix_mounts_points_changed_since(). + * a #GList of the UNIX mountpoints. * - * Returns: Whether or not @file supports thread-default contexts. - * Since: 2.22 + * Returns: (element-type GUnixMountPoint) (transfer full): */ /** - * g_file_move: - * @source: #GFile pointing to the source location. - * @destination: #GFile pointing to the destination location. - * @flags: set of #GFileCopyFlags. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @progress_callback: (scope call): #GFileProgressCallback function for updates. - * @progress_callback_data: (closure): gpointer to user data for the callback function. - * @error: #GError for returning error conditions, or %NULL + * g_unix_mounts_changed_since: + * @time: guint64 to contain a timestamp. * - * Tries to move the file or directory @source to the location specified by @destination. - * If native move operations are supported then this is used, otherwise a copy + delete - * fallback is used. The native implementation may support moving directories (for instance - * on moves inside the same filesystem), but the fallback code does not. - * If the flag #G_FILE_COPY_OVERWRITE is specified an already - * existing @destination file is overwritten. - * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks - * will be copied as symlinks, otherwise the target of the - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * If @progress_callback is not %NULL, then the operation can be monitored by - * setting this to a #GFileProgressCallback function. @progress_callback_data - * will be passed to this function. It is guaranteed that this callback will - * be called after all data has been transferred with the total number of bytes - * copied during the operation. - * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND - * error is returned, independent on the status of the @destination. - * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the - * error G_IO_ERROR_EXISTS is returned. - * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY - * error is returned. If trying to overwrite a directory with a directory the - * G_IO_ERROR_WOULD_MERGE error is returned. - * If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is - * specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error - * may be returned (if the native move operation isn't available). + * Checks if the unix mounts have changed since a given unix time. * - * Returns: %TRUE on successful move, %FALSE otherwise. + * Returns: %TRUE if the mounts have changed since @time. */ /** - * g_socket_connection_get_local_address: - * @connection: a #GSocketConnection - * @error: #GError for error reporting, or %NULL to ignore. + * g_unix_mounts_get: (skip) + * @time_read: (out) (allow-none): guint64 to contain a timestamp, or %NULL * - * Try to get the local address of a socket connection. - * Free the returned object with g_object_unref(). + * Gets a #GList of #GUnixMountEntry containing the unix mounts. + * If @time_read is set, it will be filled with the mount + * timestamp, allowing for checking if the mounts have changed + * with g_unix_mounts_changed_since(). + * a #GList of the UNIX mounts. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Since: 2.22 + * Returns: (element-type GUnixMountEntry) (transfer full): */ /** - * g_buffered_output_stream_new: - * @base_stream: a #GOutputStream. + * g_unix_output_stream_get_close_fd: + * @stream: a #GUnixOutputStream * - * Creates a new buffered output stream for a base stream. + * Returns whether the file descriptor of @stream will be + * closed when the stream is closed. * - * Returns: a #GOutputStream for the given @base_stream. + * Returns: %TRUE if the file descriptor is closed when done + * Since: 2.20 */ /** - * g_dbus_proxy_get_object_path: - * @proxy: A #GDBusProxy. + * g_unix_output_stream_get_fd: + * @stream: a #GUnixOutputStream * - * Gets the object path @proxy is for. + * Return the UNIX file descriptor that the stream writes to. * - * Returns: A string owned by @proxy. Do not free. - * Since: 2.26 + * Returns: The file descriptor of @stream + * Since: 2.20 */ /** - * G_TYPE_DBUS_ARG_INFO: + * g_unix_output_stream_new: + * @fd: a UNIX file descriptor + * @close_fd: %TRUE to close the file descriptor when done * - * The #GType for a boxed type holding a #GDBusArgInfo. + * Creates a new #GUnixOutputStream for the given @fd. + * If @close_fd, is %TRUE, the file descriptor will be closed when + * the output stream is destroyed. * - * Since: 2.26 + * Returns: a new #GOutputStream */ /** - * g_unix_mount_point_is_readonly: - * @mount_point: a #GUnixMountPoint. + * g_unix_output_stream_set_close_fd: + * @stream: a #GUnixOutputStream + * @close_fd: %TRUE to close the file descriptor when done * - * Checks if a unix mount point is read only. + * Sets whether the file descriptor of @stream shall be closed + * when the stream is closed. * - * Returns: %TRUE if a mount point is read only. + * Since: 2.20 */ /** - * GSocket:timeout: + * g_unix_socket_address_abstract_names_supported: * - * The timeout in seconds on socket I/O + * Checks if abstract unix domain socket names are supported. * - * Since: 2.26 + * Returns: %TRUE if supported, %FALSE otherwise + * Since: 2.22 */ /** - * g_dbus_message_get_header: - * @message: A #GDBusMessage. - * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) + * g_unix_socket_address_get_address_type: + * @address: a #GInetSocketAddress * - * Gets a header field on @message. - * otherwise. Do not free, it is owned by @message. + * Gets @address's type. * - * Returns: A #GVariant with the value if the header was found, %NULL + * Returns: a #GUnixSocketAddressType * Since: 2.26 */ /** - * g_socket_receive_message: - * @socket: a #GSocket - * @address: a pointer to a #GSocketAddress pointer, or %NULL - * @vectors: (array length=num_vectors): an array of #GInputVector structs - * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (allow-none): a pointer which may be filled with an array of #GSocketControlMessages, or %NULL - * @num_messages: a pointer which will be filled with the number of elements in @messages, or %NULL - * @flags: a pointer to an int containing #GSocketMsgFlags flags - * @cancellable: (allow-none): a %GCancellable or %NULL - * @error: a #GError pointer, or %NULL + * g_unix_socket_address_get_is_abstract: + * @address: a #GInetSocketAddress * - * Receive data from a socket. This is the most complicated and - * fully-featured version of this call. For easier use, see - * g_socket_receive() and g_socket_receive_from(). - * If @address is non-%NULL then @address will be set equal to the - * source address of the received packet. - * describe the buffers that received data will be scattered into. - * If @num_vectors is -1, then @vectors is assumed to be terminated - * by a #GInputVector with a %NULL buffer pointer. - * As a special case, if @num_vectors is 0 (in which case, @vectors - * may of course be %NULL), then a single byte is received and - * discarded. This is to facilitate the common practice of sending a - * single '\0' byte for the purposes of transferring ancillary data. - * array of #GSocketControlMessage instances or %NULL if no such - * messages was received. These correspond to the control messages - * received from the kernel, one #GSocketControlMessage per message - * from the kernel. This array is %NULL-terminated and must be freed - * by the caller using g_free() after calling g_object_unref() on each - * element. If @messages is %NULL, any control messages received will - * be discarded. - * messages received. - * If both @messages and @num_messages are non-%NULL, then - * for this are available in the #GSocketMsgFlags enum, but the - * values there are the same as the system values, and the flags - * are passed in as-is, so you can pass in system-specific flags too - * (and g_socket_receive_message() may pass system-specific flags out). - * As with g_socket_receive(), data may be discarded if @socket is - * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not - * provide enough buffer space to read a complete message. You can pass - * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without - * removing it from the receive queue, but there is no portable way to find - * out the length of the message other than by reading it into a - * sufficiently-large buffer. - * If the socket is in blocking mode the call will block until there - * is some data to receive or there is an error. If there is no data - * available and the socket is in non-blocking mode, a - * %G_IO_ERROR_WOULD_BLOCK error will be returned. To be notified when - * data is available, wait for the %G_IO_IN condition. - * On error -1 is returned and @error is set accordingly. + * Tests if @address is abstract. * - * In @messages (ie: not including the %NULL terminator). - * Returns: Number of bytes read, or -1 on error + * Returns: %TRUE if the address is abstract, %FALSE otherwise * Since: 2.22 + * Deprecated: Use g_unix_socket_address_get_address_type() */ /** - * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP: + * g_unix_socket_address_get_path: + * @address: a #GInetSocketAddress * - * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * Gets @address's path, or for abstract sockets the "name". + * Guaranteed to be zero-terminated, but an abstract socket + * may contain embedded zeros, and thus you should use + * g_unix_socket_address_get_path_len() to get the true length + * of this string. * + * Returns: the path for @address * Since: 2.22 */ /** - * g_inet_address_get_is_mc_site_local: - * @address: a #GInetAddress + * g_unix_socket_address_get_path_len: + * @address: a #GInetSocketAddress * - * Tests whether @address is a site-local multicast address. + * Gets the length of @address's path. + * For details, see g_unix_socket_address_get_path(). * - * Returns: %TRUE if @address is a site-local multicast address. + * Returns: the length of the path * Since: 2.22 */ /** - * G_TYPE_RESERVED_USER_FIRST: + * g_unix_socket_address_new: + * @path: the socket path * - * First available fundamental type number to create new fundamental - * type id with G_TYPE_MAKE_FUNDAMENTAL(). + * Creates a new #GUnixSocketAddress for @path. + * To create abstract socket addresses, on systems that support that, + * use g_unix_socket_address_new_abstract(). + * + * Returns: a new #GUnixSocketAddress + * Since: 2.22 */ /** - * SECTION:gtlsbacken: - * @title: GTlsBackend - * @short_description: TLS backend implementation - * @include: gio/gio.h + * g_unix_socket_address_new_abstract: + * @path: (array length=path_len) (element-type gchar): the abstract name + * @path_len: the length of @path, or -1 * + * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED + * #GUnixSocketAddress for @path. * + * Returns: a new #GUnixSocketAddress + * Deprecated: Use g_unix_socket_address_new_with_type(). */ /** - * GRegexCompileFlags: - * @G_REGEX_CASELESS: Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting. - * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting. - * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting. - * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting. - * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. - * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set. - * @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern. - * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. - * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way). - * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches. - * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched. - * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'. - * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'. - * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'. + * g_unix_socket_address_new_with_type: + * @path: (array length=path_len) (element-type gchar): the name + * @path_len: the length of @path, or -1 + * @type: a #GUnixSocketAddressType * - * Flags specifying compile-time options. + * Creates a new #GUnixSocketAddress of type @type with name @path. + * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to + * calling g_unix_socket_address_new(). + * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len + * bytes of @path will be copied to the socket's path, and only those + * bytes will be considered part of the name. (If @path_len is -1, + * then @path is assumed to be NUL-terminated.) For example, if @path + * was "test", then calling g_socket_address_get_native_size() on the + * returned socket would return 7 (2 bytes of overhead, 1 byte for the + * abstract-socket indicator byte, and 4 bytes for the name "test"). + * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then + * rest of the path will be padded with 0 bytes, and the entire + * zero-padded buffer will be considered the name. (As above, if + * this case, g_socket_address_get_native_size() will always return + * the full size of a <literal>struct sockaddr_un</literal>, although + * g_unix_socket_address_get_path_len() will still return just the + * length of @path. + * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over + * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course, + * when connecting to a server created by another process, you must + * use the appropriate type corresponding to how that process created + * its listening socket. * - * Since: 2.14 + * Returns: a new #GUnixSocketAddress + * Since: 2.26 */ /** - * g_io_modules_scan_all_in_directory: - * @dirname: pathname for a directory containing modules to scan. + * g_vfs_get_default: * - * Scans all the modules in the specified directory, ensuring that - * any extension point implemented by a module is registered. - * This may not actually load and initialize all the types in each - * module, some modules may be lazily loaded and initialized when - * an extension point it implementes is used with e.g. - * g_io_extension_point_get_extensions() or - * g_io_extension_point_get_extension_by_name(). - * If you need to guarantee that all types are loaded in all the modules, - * use g_io_modules_load_all_in_directory(). + * Gets the default #GVfs for the system. * - * Since: 2.24 + * Returns: (transfer none): a #GVfs. */ /** - * g_socket_service_stop: - * @service: a #GSocketService + * g_vfs_get_file_for_path: + * @vfs: a #GVfs. + * @path: a string containing a VFS path. * - * Stops the service, i.e. stops accepting connections - * from the added sockets when the mainloop runs. - * This call is threadsafe, so it may be called from a thread - * handling an incomming client request. + * Gets a #GFile for @path. + * Free the returned object with g_object_unref(). * - * Since: 2.22 + * Returns: (transfer full): a #GFile. */ /** - * G_FLAGS_CLASS_TYPE: - * @class: a #GFlagsClass + * g_vfs_get_file_for_uri: + * @vfs: a#GVfs. + * @uri: a string containing a URI * - * Get the type identifier from a given #GFlagsClass structure. + * Gets a #GFile for @uri. + * This operation never fails, but the returned object + * might not support any I/O operation if the URI + * is malformed or if the URI scheme is not supported. + * Free the returned object with g_object_unref(). * - * Returns: the #GType + * Returns: (transfer full): a #GFile. */ /** - * g_settings_new_with_backend_and_path: - * @schema: the name of the schema - * @backend: the #GSettingsBackend to use - * @path: the path to use - * @returns: a new #GSettings object + * g_vfs_get_local: * - * Creates a new #GSettings object with a given schema, backend and - * path. - * This is a mix of g_settings_new_with_backend() and - * g_settings_new_with_path(). + * Gets the local #GVfs for the system. * - * Since: 2.26 + * Returns: (transfer none): a #GVfs. */ /** - * g_bus_own_name_with_closures: - * @bus_type: The type of bus to own a name on. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to the bus of type @bus_type or %NULL. - * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. - * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. + * g_vfs_get_supported_uri_schemes: + * @vfs: a #GVfs. * - * Version of g_bus_own_name() using closures instead of callbacks for - * easier binding in other languages. - * g_bus_unown_name() to stop owning the name. + * Gets a list of URI schemes supported by @vfs. + * The returned array belongs to GIO and must + * not be freed or modified. * - * Returns: An identifier (never 0) that an be used with - * Rename to: g_bus_own_name - * Since: 2.26 + * Returns: (transfer none): a %NULL-terminated array of strings. */ @@ -31179,493 +31113,565 @@ /** - * g_settings_set_int: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * @returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * g_vfs_parse_name: + * @vfs: a #GVfs. + * @parse_name: a string to be parsed by the VFS module. * - * Sets @key in @settings to @value. - * A convenience variant of g_settings_set() for 32-bit integers. - * It is a programmer error to give a @key that isn't specified as - * having a int32 type in the schema for @settings. + * This operation never fails, but the returned object might + * not support any I/O operations if the @parse_name cannot + * be parsed by the #GVfs module. + * Free the returned object with g_object_unref(). * - * Since: 2.26 + * Returns: (transfer full): a #GFile for the given @parse_name. */ /** - * G_TYPE_DOUBLE: + * g_volume_can_eject: + * @volume: a #GVolume. * - * The fundamental type corresponding to #gdouble. + * Checks if a volume can be ejected. + * + * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise. */ /** - * G_VARIANT_TYPE_UINT64: + * g_volume_can_mount: + * @volume: a #GVolume. * - * The type of an integer value that can range from 0 to - * 18446744073709551616. That's a really big number, but a Rubik's - * cube can have a bit more than twice as many possible positions. + * Checks if a volume can be mounted. + * + * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise. */ /** - * g_file_replace_contents_finish: - * @file: input #GFile. - * @res: a #GAsyncResult. - * @new_etag: (out) (allow-none): a location of a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when it is no longer needed, or %NULL - * @error: a #GError, or %NULL + * g_volume_eject: + * @volume: a #GVolume. + * @flags: flags affecting the unmount if required for eject + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data that gets passed to @callback * - * Finishes an asynchronous replace of the given @file. See - * g_file_replace_contents_async(). Sets @new_etag to the new entity - * tag for the document, if present. + * Ejects a volume. This is an asynchronous operation, and is + * finished by calling g_volume_eject_finish() with the @volume + * and #GAsyncResult returned in the @callback. * - * Returns: %TRUE on success, %FALSE on failure. + * Deprecated: 2.22: Use g_volume_eject_with_operation() instead. */ /** - * GDBusConnectionClass: - * @closed: Signal class handler for the #GDBusConnection::closed signal. + * g_volume_eject_finish: + * @volume: pointer to a #GVolume. + * @result: a #GAsyncResult. + * @error: a #GError location to store an error, or %NULL to ignore * - * Class structure for #GDBusConnection. + * Finishes ejecting a volume. If any errors occured during the operation, * - * Since: 2.26 + * Returns: %TRUE, %FALSE if operation failed. + * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead. */ /** - * G_TYPE_RESERVED_GLIB_FIRST: + * g_volume_eject_with_operation: + * @volume: a #GVolume. + * @flags: flags affecting the unmount if required for eject + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback, or %NULL. + * @user_data: user data passed to @callback. * - * First fundamental type number to create a new fundamental type id with - * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. + * Ejects a volume. This is an asynchronous operation, and is + * finished by calling g_volume_eject_with_operation_finish() with the @volume + * and #GAsyncResult data returned in the @callback. + * + * Since: 2.22 */ /** - * GParamSpecUChar: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_volume_eject_with_operation_finish: + * @volume: a #GVolume. + * @result: a #GAsyncResult. + * @error: a #GError location to store the error occuring, or %NULL to ignore. * - * A #GParamSpec derived structure that contains the meta data for unsigned character properties. + * Finishes ejecting a volume. If any errors occurred during the operation, + * + * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise. + * Since: 2.22 */ /** - * g_network_address_parse_uri: - * @uri: the hostname and optionally a port - * @default_port: The default port if none is found in the URI - * @error: a pointer to a #GError, or %NULL + * g_volume_enumerate_identifiers: + * @volume: a #GVolume * - * Creates a new #GSocketConnectable for connecting to the given - * Using this rather than g_network_address_new() or - * g_network_address_parse_host() allows #GSocketClient to determine - * when to use application-specific proxy protocols. + * Gets the kinds of <link linkend="volume-identifier">identifiers</link> + * that @volume has. Use g_volume_get_identifer() to obtain + * the identifiers themselves. + * of strings containing kinds of identifiers. Use g_strfreev() to free. * - * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error - * Since: 2.26 + * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array */ /** - * g_inet_address_get_is_mc_org_local: - * @address: a #GInetAddress + * g_volume_get_activation_root: + * @volume: a #GVolume * - * Tests whether @address is an organization-local multicast address. + * Gets the activation root for a #GVolume if it is known ahead of + * mount time. Returns %NULL otherwise. If not %NULL and if @volume + * is mounted, then the result of g_mount_get_root() on the + * #GMount object obtained from g_volume_get_mount() will always + * either be equal or a prefix of what this function returns. In + * other words, in code + * <programlisting> + * GMount *mount; + * GFile *mount_root + * GFile *volume_activation_root; + * mount = g_volume_get_mount (volume); /* mounted, so never NULL */ + * mount_root = g_mount_get_root (mount); + * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */ + * </programlisting> + * then the expression + * <programlisting> + * (g_file_has_prefix (volume_activation_root, mount_root) || + * </programlisting> + * will always be %TRUE. + * Activation roots are typically used in #GVolumeMonitor + * implementations to find the underlying mount to shadow, see + * g_mount_is_shadowed() for more details. + * g_object_unref() to free. * - * Returns: %TRUE if @address is an organization-local multicast address. - * Since: 2.22 + * Returns: (transfer full): the activation root of @volume or %NULL. Use + * Since: 2.18 */ /** - * g_keyfile_settings_backend_new: - * @filename: the filename of the keyfile - * @root_path: the path under which all settings keys appear - * @root_group: (allow-none): the group name corresponding to - * @returns: (transfer full): a keyfile-backed #GSettingsBackend + * g_volume_get_drive: + * @volume: a #GVolume. * - * Creates a keyfile-backed #GSettingsBackend. - * The filename of the keyfile to use is given by @filename. - * All settings read to or written from the backend must fall under the - * path given in @root_path (which must start and end with a slash and - * not contain two consecutive slashes). @root_path may be "/". - * If @root_group is non-%NULL then it specifies the name of the keyfile - * group used for keys that are written directly below @root_path. For - * example, if @root_path is "/apps/example/" and @root_group is - * "toplevel", then settings the key "/apps/example/enabled" to a value - * of %TRUE will cause the following to appear in the keyfile: - * |[ - * [toplevel] - * enabled=true - * ]| - * If @root_group is %NULL then it is not permitted to store keys - * directly below the @root_path. - * the name of the subpath (with the final slash stripped) is used as - * the name of the keyfile group. To continue the example, if - * "/apps/example/profiles/default/font-size" were set to - * 12 then the following would appear in the keyfile: - * |[ - * [profiles/default] - * font-size=12 - * ]| - * The backend will refuse writes (and return writability as being - * %FALSE) for keys outside of @root_path and, in the event that - * Writes will also be refused if the backend detects that it has the - * writable). - * There is no checking done for your key namespace clashing with the - * syntax of the key file format. For example, if you have '[' or ']' - * characters in your path names or '=' in your key names you may be in - * trouble. + * Gets the drive for the @volume. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. * - * For keys not stored directly below @root_path (ie: in a sub-path), - * Inability to rewrite the keyfile (ie: the containing directory is not + * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive. */ /** - * G_OBJECT_CLASS_NAME: - * @class: a valid #GObjectClass + * g_volume_get_icon: + * @volume: a #GVolume. * - * Return the name of a class structure's type. - * should not be freed. + * Gets the icon for @volume. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. * - * Returns: Type name of @class. The string is owned by the type system and + * Returns: (transfer full): a #GIcon. */ /** - * GUnixMount: + * g_volume_get_identifier: + * @volume: a #GVolume + * @kind: the kind of identifier to return * - * Implementation of the #GMount interface for Unix systems. + * Gets the identifier of the given kind for @volume. + * See the <link linkend="volume-identifier">introduction</link> + * for more information about volume identifiers. + * requested identfier, or %NULL if the #GVolume + * doesn't have this kind of identifier + * + * Returns: a newly allocated string containing the */ /** - * g_socket_client_add_application_proxy: - * @client: a #GSocketClient - * @protocol: The proxy protocol + * g_volume_get_mount: + * @volume: a #GVolume. * - * Enable proxy protocols to be handled by the application. When the - * indicated proxy protocol is returned by the #GProxyResolver, - * #GSocketClient will consider this protocol as supported but will - * not try find a #GProxy instance to handle handshaking. The - * application must check for this case by calling - * g_socket_connection_get_remote_address() on the returned - * #GSocketConnection, and seeing if it's a #GProxyAddress of the - * appropriate type, to determine whether or not it needs to handle - * the proxy handshaking itself. - * This should be used for proxy protocols that are dialects of - * another protocol such as HTTP proxy. It also allows cohabitation of - * proxy protocols that are reused between protocols. A good example - * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also - * be use as generic socket proxy through the HTTP CONNECT method. + * Gets the mount for the @volume. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. + * + * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted. */ /** - * g_drive_stop: - * @drive: a #GDrive. - * @flags: flags affecting the unmount if required for stopping. - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback + * g_volume_get_name: + * @volume: a #GVolume. * - * Asynchronously stops a drive. - * When the operation is finished, @callback will be called. - * You can then call g_drive_stop_finish() to obtain the - * result of the operation. + * Gets the name of @volume. + * be freed with g_free() when no longer needed. * - * Since: 2.22 + * Returns: the name for the given @volume. The returned string should */ /** - * GFileDescriptorBased: + * g_volume_get_uuid: + * @volume: a #GVolume. * - * An interface for file descriptor based io objects. + * Gets the UUID for the @volume. The reference is typically based on + * the file system UUID for the volume in question and should be + * considered an opaque string. Returns %NULL if there is no UUID + * available. + * The returned string should be freed with g_free() + * when no longer needed. + * + * Returns: the UUID for @volume or %NULL if no UUID can be computed. */ /** - * g_memory_output_stream_get_data_size: - * @ostream: a #GMemoryOutputStream + * g_volume_monitor_adopt_orphan_mount: + * @mount: a #GMount object to find a parent for * - * Returns the number of bytes from the start up - * to including the last byte written in the stream - * that has not been truncated away. + * This function should be called by any #GVolumeMonitor + * implementation when a new #GMount object is created that is not + * associated with a #GVolume object. It must be called just before + * emitting the @mount_added signal. + * If the return value is not %NULL, the caller must associate the + * returned #GVolume object with the #GMount. This involves returning + * it in its g_mount_get_volume() implementation. The caller must + * also listen for the "removed" signal on the returned object + * and give up its reference when handling that signal + * Similary, if implementing g_volume_monitor_adopt_orphan_mount(), + * the implementor must take a reference to @mount and return it in + * its g_volume_get_mount() implemented. Also, the implementor must + * listen for the "unmounted" signal on @mount and give up its + * reference upon handling that signal. + * There are two main use cases for this function. + * One is when implementing a user space file system driver that reads + * blocks of a block device that is already represented by the native + * volume monitor (for example a CD Audio file system driver). Such + * a driver will generate its own #GMount object that needs to be + * assoicated with the #GVolume object that represents the volume. + * The other is for implementing a #GVolumeMonitor whose sole purpose + * is to return #GVolume objects representing entries in the users + * "favorite servers" list or similar. + * if no wants to adopt the #GMount. + * implementations should instead create shadow mounts with the URI of + * the mount they intend to adopt. See the proxy volume monitor in + * gvfs for an example of this. Also see g_mount_is_shadowed(), + * g_mount_shadow() and g_mount_unshadow() functions. * - * Returns: the number of bytes written to the stream - * Since: 2.18 + * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL + * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor */ /** - * GTypePluginUnuse: - * @plugin: the #GTypePlugin whose use count should be decreased + * g_volume_monitor_get: * - * The type of the @unuse_plugin function of #GTypePluginClass. + * Gets the volume monitor used by gio. + * g_object_unref() when done with it. + * + * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call */ /** - * g_file_info_get_is_symlink: - * @info: a #GFileInfo. + * g_volume_monitor_get_connected_drives: + * @volume_monitor: a #GVolumeMonitor. * - * Checks if a file is a symlink. + * Gets a list of drives connected to the system. + * The returned list should be freed with g_list_free(), after + * its elements have been unreffed with g_object_unref(). * - * Returns: %TRUE if the given @info is a symlink. + * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects. */ /** - * G_PARAM_SPEC_VALUE_TYPE: - * @pspec: a valid #GParamSpec + * g_volume_monitor_get_mount_for_uuid: + * @volume_monitor: a #GVolumeMonitor. + * @uuid: the UUID to look for * - * Retrieves the #GType to initialize a #GValue for this parameter. + * Finds a #GMount object by its UUID (see g_mount_get_uuid()) + * Free the returned object with g_object_unref(). + * + * Returns: (transfer full): a #GMount or %NULL if no such mount is available. */ /** - * GDataInputStream: + * g_volume_monitor_get_mounts: + * @volume_monitor: a #GVolumeMonitor. * - * An implementation of #GBufferedInputStream that allows for high-level - * data manipulation of arbitrary data (including binary operations). + * Gets a list of the mounts on the system. + * The returned list should be freed with g_list_free(), after + * its elements have been unreffed with g_object_unref(). + * + * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects. */ /** - * g_dbus_message_set_path: - * @message: A #GDBusMessage. - * @value: The value to set. + * g_volume_monitor_get_volume_for_uuid: + * @volume_monitor: a #GVolumeMonitor. + * @uuid: the UUID to look for * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. + * Finds a #GVolume object by its UUID (see g_volume_get_uuid()) + * Free the returned object with g_object_unref(). * - * Since: 2.26 + * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. */ /** - * g_io_stream_set_pending: - * @stream: a #GIOStream - * @error: a #GError location to store the error occuring, or %NULL to ignore + * g_volume_monitor_get_volumes: + * @volume_monitor: a #GVolumeMonitor. * - * Sets @stream to have actions pending. If the pending flag is - * already set or @stream is closed, it will return %FALSE and set + * Gets a list of the volumes on the system. + * The returned list should be freed with g_list_free(), after + * its elements have been unreffed with g_object_unref(). * - * Returns: %TRUE if pending was previously unset and is now set. - * Since: 2.22 + * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects. */ /** - * g_socket_service_start: - * @service: a #GSocketService + * g_volume_mount: + * @volume: a #GVolume. + * @flags: flags affecting the operation + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @user_data: user data that gets passed to @callback * - * Starts the service, i.e. start accepting connections - * from the added sockets when the mainloop runs. - * This call is threadsafe, so it may be called from a thread - * handling an incomming client request. + * Mounts a volume. This is an asynchronous operation, and is + * finished by calling g_volume_mount_finish() with the @volume + * and #GAsyncResult returned in the @callback. * - * Since: 2.22 + * Virtual: mount_fn */ /** - * G_IS_PARAM_SPEC_INT64: - * @pspec: a valid #GParamSpec instance + * g_volume_mount_finish: + * @volume: a #GVolume + * @result: a #GAsyncResult + * @error: a #GError location to store an error, or %NULL to ignore * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. + * Finishes mounting a volume. If any errors occured during the operation, + * If the mount operation succeeded, g_volume_get_mount() on @volume + * is guaranteed to return the mount right after calling this + * function; there's no need to listen for the 'mount-added' signal on + * #GVolumeMonitor. * - * Returns: %TRUE on success. + * Returns: %TRUE, %FALSE if operation failed. */ /** - * G_FILE_ATTRIBUTE_FILESYSTEM_FREE: + * g_volume_should_automount: + * @volume: a #GVolume * - * A key in the "filesystem" namespace for getting the number of bytes of free space left on the - * file system. Corresponding #GFileAttributeType is - * %G_FILE_ATTRIBUTE_TYPE_UINT64. + * Returns whether the volume should be automatically mounted. + * + * Returns: %TRUE if the volume should be automatically mounted. */ /** - * g_socket_client_get_enable_proxy: - * @client: a #GSocketClient. + * g_win32_input_stream_get_close_handle: + * @stream: a #GWin32InputStream * - * Gets the proxy enable state; see g_socket_client_set_enable_proxy() + * Returns whether the handle of @stream will be + * closed when the stream is closed. * - * Returns: whether proxying is enabled + * Returns: %TRUE if the handle is closed when done * Since: 2.26 */ /** - * g_io_stream_close: - * @stream: a #GIOStream - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: location to store the error occuring, or %NULL to ignore + * g_win32_input_stream_get_handle: + * @stream: a #GWin32InputStream * - * Closes the stream, releasing resources related to it. This will also - * closes the individual input and output streams, if they are not already - * closed. - * Once the stream is closed, all other operations will return - * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not - * return an error. - * Closing a stream will automatically flush any outstanding buffers - * in the stream. - * Streams will be automatically closed when the last reference - * is dropped, but you might want to call this function to make sure - * resources are released as early as possible. - * Some streams might keep the backing store of the stream (e.g. a file - * descriptor) open after the stream is closed. See the documentation for - * the individual stream for details. - * On failure the first error that happened will be reported, but the - * close operation will finish as much as possible. A stream that failed - * to close will still return %G_IO_ERROR_CLOSED for all operations. - * Still, it is important to check and report the error to the user, - * otherwise there might be a loss of data as all data might not be written. - * If @cancellable is not NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Cancelling a close will still leave the stream closed, but some streams - * can use a faster close that doesn't block to e.g. check errors. - * The default implementation of this method just calls close on the - * individual input/output streams. + * Return the Windows file handle that the stream reads from. * - * Returns: %TRUE on success, %FALSE on failure - * Since: 2.22 + * Returns: The file handle of @stream + * Since: 2.26 */ /** - * GTypeInstance: + * g_win32_input_stream_new: + * @handle: a Win32 file handle + * @close_fd: %TRUE to close the handle when done * - * An opaque structure used as the base of all type instances. + * Creates a new #GWin32InputStream for the given @fd. + * If @close_handle is %TRUE, the handle will be closed + * when the stream is closed. + * Note that "handle" here means a Win32 HANDLE, not a "file descriptor" + * as used in the Windows C libraries. + * + * Returns: a new #GWin32InputStream */ /** - * g_tcp_connection_set_graceful_disconnect: - * @connection: a #GTcpConnection - * @graceful_disconnect: Whether to do graceful disconnects or not + * g_win32_input_stream_set_close_handle: + * @stream: a #GWin32InputStream + * @close_handle: %TRUE to close the handle when done * - * This enabled graceful disconnects on close. A graceful disconnect - * means that we signal the recieving end that the connection is terminated - * and wait for it to close the connection before closing the connection. - * A graceful disconnect means that we can be sure that we successfully sent - * all the outstanding data to the other end, or get an error reported. - * However, it also means we have to wait for all the data to reach the - * other side and for it to acknowledge this by closing the socket, which may - * take a while. For this reason it is disabled by default. + * Sets whether the handle of @stream shall be closed + * when the stream is closed. * - * Since: 2.22 + * Since: 2.26 */ /** - * G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE: + * g_win32_output_stream_get_close_handle: + * @stream: a #GWin32OutputStream * - * A key in the "standard" namespace for getting the fast content type. - * The fast content type isn't as reliable as the regular one, as it - * only uses the filename to guess it, but it is faster to calculate than the - * regular content type. - * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * Returns whether the handle of @stream will be closed when the + * stream is closed. + * + * Returns: %TRUE if the handle is closed when done + * Since: 2.26 */ /** - * g_data_output_stream_put_string: - * @stream: a #GDataOutputStream. - * @str: a string. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. + * g_win32_output_stream_get_handle: + * @stream: a #GWin32OutputStream * - * Puts a string into the output stream. + * Return the Windows handle that the stream writes to. * - * Returns: %TRUE if @string was successfully added to the @stream. + * Returns: The handle descriptor of @stream + * Since: 2.26 */ /** - * GBaseFinalizeFunc: - * @g_class: The #GTypeClass structure to finalize. + * g_win32_output_stream_new: + * @handle: a Win32 file handle + * @close_handle: %TRUE to close the handle when done * - * A callback function used by the type system to finalize those portions - * of a derived types class structure that were setup from the corresponding - * GBaseInitFunc() function. Class finalization basically works the inverse - * way in which class intialization is performed. - * See GClassInitFunc() for a discussion of the class intialization process. + * Creates a new #GWin32OutputStream for the given @handle. + * If @close_handle, is %TRUE, the handle will be closed when the + * output stream is destroyed. + * + * Returns: a new #GOutputStream + * Since: 2.26 */ /** - * SECTION:gioerro: - * @short_description: Error helper functions - * @include: gio/gio.h + * g_win32_output_stream_set_close_handle: + * @stream: a #GWin32OutputStream + * @close_handle: %TRUE to close the handle when done * - * Contains helper functions for reporting errors to the user. + * Sets whether the handle of @stream shall be closed when the stream + * is closed. + * + * Since: 2.26 */ /** - * G_VARIANT_TYPE_HANDLE: + * g_zlib_compressor_get_file_info: + * @compressor: a #GZlibCompressor * - * The type of a 32bit signed integer value, that by convention, is used - * as an index into an array of file descriptors that are sent alongside - * a DBus message. - * If you are not interacting with DBus, then there is no reason to make - * use of this type. + * Returns the #GZlibCompressor:file-info property. + * + * Returns: (transfer none): a #GFileInfo, or %NULL + * Since: 2.26 */ /** - * g_unix_credentials_message_is_supported: + * g_zlib_compressor_new: + * @format: The format to use for the compressed data + * @level: compression level (0-9), -1 for default * - * Checks if passing a #GCredential on a #GSocket is supported on this platform. + * Creates a new #GZlibCompressor. * - * Returns: %TRUE if supported, %FALSE otherwise - * Since: 2.26 + * Returns: a new #GZlibCompressor + * Since: 2.24 */ /** - * GParamSpecDouble: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90. + * g_zlib_compressor_set_file_info: + * @compressor: a #GZlibCompressor + * @file_info: (allow-none): a #GFileInfo * - * A #GParamSpec derived structure that contains the meta data for double properties. + * Sets @file_info in @compressor. If non-%NULL, and @compressor's + * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, + * it will be used to set the file name and modification time in + * the GZIP header of the compressed data. + * progress; it may only be called immediately after creation of @compressor, + * or after resetting it with g_converter_reset(). + * + * Note: it is an error to call this function while a compression is in + * Since: 2.26 */ /** - * GBusNameWatcherFlags: - * @G_BUS_NAME_WATCHER_FLAGS_NONE: No flags set. - * @G_BUS_NAME_WATCHER_FLAGS_AUTO_START: If no-one owns the name when beginning to watch the name, ask the bus to launch an owner for the name. + * g_zlib_decompressor_get_file_info: + * @decompressor: a #GZlibDecompressor * - * Flags used in g_bus_watch_name(). + * Retrieves the #GFileInfo constructed from the GZIP header data + * of compressed data processed by @compressor, or %NULL if @decompressor's + * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, + * or the header data was not fully processed yet, or it not present in the + * data stream at all. * + * Returns: (transfer none): a #GFileInfo, or %NULL * Since: 2.26 */ /** - * g_content_type_is_a: - * @type: a content type string - * @supertype: a content type string + * g_zlib_decompressor_new: + * @format: The format to use for the compressed data * - * Determines if @type is a subset of @supertype. - * %FALSE otherwise. + * Creates a new #GZlibDecompressor. * - * Returns: %TRUE if @type is a kind of @supertype, + * Returns: a new #GZlibDecompressor + * Since: 2.24 + */ + + +/** + * gchararray: + * + * A C representable type name for #G_TYPE_STRING. + */ + + +/** + * 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 + * to handle @mime_type. + * + * Returns: a #GList containing the desktop ids which claim + */ + + +/** + * mime_info_cache_reload: + * @dir: directory path which needs reloading. + * + * Reload the mime information for the @dir. */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 554d70da..e6d50caf 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -3,1965 +3,2015 @@ /************************************************************/ /** - * G_NODE_IS_ROOT: - * @node: a #GNode - * - * Returns %TRUE if a #GNode is the root of a tree. - * (i.e. it has no parent or siblings) + * GBaseFinalizeFunc: + * @g_class: The #GTypeClass structure to finalize. * - * Returns: %TRUE if the #GNode is the root of a tree + * A callback function used by the type system to finalize those portions + * of a derived types class structure that were setup from the corresponding + * GBaseInitFunc() function. Class finalization basically works the inverse + * way in which class intialization is performed. + * See GClassInitFunc() for a discussion of the class intialization process. */ /** - * G_PARAM_SPEC_GET_CLASS: - * @pspec: a valid #GParamSpec + * GBaseInitFunc: + * @g_class: The #GTypeClass structure to initialize. * - * Retrieves the #GParamSpecClass of a #GParamSpec. + * A callback function used by the type system to do base initialization + * of the class structures of derived types. It is called as part of the + * initialization process of all derived classes and should reallocate + * or reset all dynamic class members copied over from the parent class. + * For example, class members (such as strings) that are not sufficiently + * handled by a plain memory copy of the parent class into the derived class + * have to be altered. See GClassInitFunc() for a discussion of the class + * intialization process. */ /** - * g_type_remove_class_cache_func: (skip) - * @cache_data: data that was given when adding @cache_func - * @cache_func: a #GTypeClassCacheFunc + * GBinding: * - * Removes a previously installed #GTypeClassCacheFunc. The cache - * maintained by @cache_func has to be empty when calling - * g_type_remove_class_cache_func() to avoid leaks. + * <structname>GBinding</structname> is an opaque structure whose members + * cannot be accessed directly. + * + * Since: 2.26 */ /** - * g_value_get_ulong: - * @value: a valid #GValue of type %G_TYPE_ULONG + * GBinding:flags: * - * Get the contents of a %G_TYPE_ULONG #GValue. + * Flags to be used to control the #GBinding * - * Returns: unsigned long integer contents of @value + * Since: 2.26 */ /** - * g_value_array_sort_with_data: - * @value_array: #GValueArray to sort - * @compare_func: (scope call): function to compare elements - * @user_data: (closure): extra data argument provided for @compare_func + * GBinding:source: * - * Sort @value_array using @compare_func to compare the elements accoring - * to the semantics of #GCompareDataFunc. - * The current implementation uses Quick-Sort as sorting algorithm. + * The #GObject that should be used as the source of the binding * - * Rename to: g_value_array_sort - * Returns: (transfer none): the #GValueArray passed in as @value_array + * Since: 2.26 */ /** - * g_signal_connect_closure_by_id: - * @instance: the instance to connect to. - * @signal_id: the id of the signal. - * @detail: the detail. - * @closure: the closure to connect. - * @after: whether the handler should be called before or after the default handler of the signal. + * GBinding:source-property: * - * Connects a closure to a signal for a particular object. + * The name of the property of #GBinding:source that should be used + * as the source of the binding * - * Returns: the handler id + * Since: 2.26 */ /** - * G_PRIORITY_DEFAULT_IDLE: + * GBinding:target: * - * Use this for default priority idle functions. - * In GLib this priority is used when adding idle functions with - * g_idle_add(). + * The #GObject that should be used as the target of the binding + * + * Since: 2.26 */ /** - * G_VALUE_HOLDS_CHAR: - * @value: a valid #GValue structure + * GBinding:target-property: * - * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. + * The name of the property of #GBinding:target that should be used + * as the target of the binding * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * G_TYPE_IS_FUNDAMENTAL: - * @type: A #GType value. + * GBindingFlags: + * @G_BINDING_DEFAULT: The default binding; if the source property changes, the target property is updated with its value. + * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. + * @G_BINDING_SYNC_CREATE: Synchronize the values of the source and target properties when creating the binding; the direction of the synchronization is always from the source to the target. + * @G_BINDING_INVERT_BOOLEAN: If the two properties being bound are booleans, setting one to %TRUE will result in the other being set to %FALSE and vice versa. This flag will only work for boolean properties, and cannot be used when passing custom transformation functions to g_object_bind_property_full(). * - * Checks if @type is a fundamental type. + * Flags to be passed to g_object_bind_property() or + * g_object_bind_property_full(). + * This enumeration can be extended at later date. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * g_main_run: - * @loop: a #GMainLoop + * GBindingTransformFunc: + * @binding: a #GBinding + * @source_value: the value of the source property + * @target_value: the value of the target property + * @user_data: data passed to the transform function * - * Runs a main loop until it stops running. + * A function to be called to transform the source property of @source + * from @source_value into the target property of @target + * using @target_value. + * otherwise * - * Deprecated: 2.2: Use g_main_loop_run() instead + * Returns: %TRUE if the transformation was successful, and %FALSE + * Since: 2.26 */ /** - * g_param_values_cmp: - * @pspec: a valid #GParamSpec - * @value1: a #GValue of correct type for @pspec - * @value2: a #GValue of correct type for @pspec - * - * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, - * if @value1 is found to be less than, equal to or greater than @value2, - * respectively. + * GBookmarkFile: * - * Returns: -1, 0 or +1, for a less than, equal to or greater than result + * The <structname>GBookmarkFile</structname> struct contains only + * private data and should not be directly accessed. */ /** - * g_source_set_closure: - * @source: the source - * @closure: a #GClosure + * GBookmarkFileError: + * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed + * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found + * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not register a bookmark + * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found + * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed + * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding + * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing + * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found * - * Set the callback for a source as a #GClosure. - * If the source is not one of the standard GLib types, the @closure_callback - * and @closure_marshal fields of the #GSourceFuncs structure must have been - * filled in with pointers to appropriate functions. + * Error codes returned by bookmark file parsing. */ /** - * g_type_add_class_private: - * @class_type: GType of an classed type. - * @private_size: size of private structure. + * GBoxedCopyFunc: + * @boxed: The boxed structure to be copied. * - * Registers a private class structure for a classed type; - * when the class is allocated, the private structures for - * the class and all of its parent types are allocated - * sequentially in the same memory block as the public - * structures. This function should be called in the - * type's get_type() function after the type is registered. - * The private structure can be retrieved using the - * G_TYPE_CLASS_GET_PRIVATE() macro. + * This function is provided by the user and should produce a copy of the passed + * in boxed structure. * - * Since: 2.24 + * Returns: The newly created copy of the boxed structure. */ /** - * SECTION:object: - * @short_description: The base object type - * @see_also: #GParamSpecObject, g_param_spec_object() - * @title: The Base Object Type + * GBoxedFreeFunc: + * @boxed: The boxed structure to be freed. * - * GObject is the fundamental type providing the common attributes and - * methods for all object types in GTK+, Pango and other libraries - * based on GObject. The GObject class provides methods for object - * construction and destruction, property access methods, and signal - * support. Signals are described in detail in <xref - * linkend="gobject-Signals"/>. - * <para id="floating-ref"> - * #GInitiallyUnowned is derived from #GObject. The only difference between - * the two is that the initial reference of a #GInitiallyUnowned is flagged - * as a <firstterm>floating</firstterm> reference. - * This means that it is not specifically claimed to be "owned" by - * any code portion. The main motivation for providing floating references is - * C convenience. In particular, it allows code to be written as: - * |[ - * container = create_container(); - * container_add_child (container, create_child()); - * ]| - * If <function>container_add_child()</function> will g_object_ref_sink() the - * passed in child, no reference of the newly created child is leaked. - * Without floating references, <function>container_add_child()</function> - * can only g_object_ref() the new child, so to implement this code without - * reference leaks, it would have to be written as: - * |[ - * Child *child; - * container = create_container(); - * child = create_child(); - * container_add_child (container, child); - * g_object_unref (child); - * ]| - * The floating reference can be converted into - * an ordinary reference by calling g_object_ref_sink(). - * For already sunken objects (objects that don't have a floating reference - * anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns - * a new reference. - * Since floating references are useful almost exclusively for C convenience, - * language bindings that provide automated reference and memory ownership - * maintenance (such as smart pointers or garbage collection) therefore don't - * need to expose floating references in their API. - * </para> - * Some object implementations may need to save an objects floating state - * across certain code portions (an example is #GtkMenu), to achive this, the - * following sequence can be used: - * |[ - * // save floating state - * gboolean was_floating = g_object_is_floating (object); - * g_object_ref_sink (object); - * // protected code portion - * ...; - * // restore floating state - * if (was_floating) - * g_object_force_floating (object); - * g_obejct_unref (object); // release previously acquired reference - * ]| + * This function is provided by the user and should free the boxed + * structure passed. */ /** - * g_cclosure_new: (skip) - * @callback_func: the function to invoke - * @user_data: user data to pass to @callback_func - * @destroy_data: destroy notify to be called when @user_data is no longer used - * - * Creates a new closure which invokes @callback_func with @user_data as - * the last parameter. + * GCClosure: + * @closure: the #GClosure + * @callback: the callback function * - * Returns: a new #GCClosure + * A #GCClosure is a specialization of #GClosure for C function callbacks. */ /** - * G_IS_PARAM_SPEC_CLASS: - * @pclass: a #GParamSpecClass + * GCallback: * - * Checks whether @pclass "is a" valid #GParamSpecClass structure of type - * %G_TYPE_PARAM or derived. + * The type used for callback functions in structure definitions and function + * signatures. This doesn't mean that all callback functions must take no + * parameters and return void. The required signature of a callback function + * is determined by the context in which is used (e.g. the signal to which it + * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. */ /** - * GBookmarkFile: + * GChecksum: * - * The <structname>GBookmarkFile</structname> struct contains only - * private data and should not be directly accessed. + * An opaque structure representing a checksumming operation. + * To create a new GChecksum, use g_checksum_new(). To free + * a GChecksum, use g_checksum_free(). + * + * Since: 2.16 */ /** - * g_cclosure_marshal_VOID__CHAR: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gchar parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * GChecksumType: + * @G_CHECKSUM_MD5: Use the MD5 hashing algorithm + * @G_CHECKSUM_SHA1: Use the SHA-1 hashing algorithm + * @G_CHECKSUM_SHA256: Use the SHA-256 hashing algorithm * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>. + * The hashing algorithm to be used by #GChecksum when performing the + * digest of some data. + * Note that the #GChecksumType enumeration may be extended at a later + * date to include new hashing algorithm types. + * + * Since: 2.16 */ /** - * g_param_spec_sink: - * @pspec: a valid #GParamSpec + * GChildWatchFunc: + * @pid: the process id of the child process + * @status: Status information about the child process, see waitpid(2) for more information about this field + * @data: user data passed to g_child_watch_add() * - * The initial reference count of a newly created #GParamSpec is 1, - * even though no one has explicitly called g_param_spec_ref() on it - * yet. So the initial reference count is flagged as "floating", until - * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink - * (pspec);</literal> in sequence on it, taking over the initial - * reference count (thus ending up with a @pspec that has a reference - * count of 1 still, but is not flagged "floating" anymore). + * The type of functions to be called when a child exists. */ /** - * G_TYPE_VARIANT_TYPE: - * - * The #GType for a boxed type holding a #GVariantType. + * GClassFinalizeFunc: + * @g_class: The #GTypeClass structure to finalize. + * @class_data: The @class_data member supplied via the #GTypeInfo structure. * - * Since: 2.24 + * A callback function used by the type system to finalize a class. + * This function is rarely needed, as dynamically allocated class resources + * should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). + * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo + * structure of a static type is invalid, because classes of static types + * will never be finalized (they are artificially kept alive when their + * reference count drops to zero). */ /** - * GObjectClass: - * @g_type_class: the parent class - * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons. - * @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system. - * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties. - * @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class. - * @finalize: instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class. - * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed. - * @notify: the class closure for the notify signal - * @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation. + * GClassInitFunc: + * @g_class: The #GTypeClass structure to initialize. + * @class_data: The @class_data member supplied via the #GTypeInfo structure. * - * The class structure for the <structname>GObject</structname> type. - * <example> - * <title>Implementing singletons using a constructor</title> - * <programlisting> - * static MySingleton *the_singleton = NULL; - * static GObject* - * my_singleton_constructor (GType type, - * guint n_construct_params, - * GObjectConstructParam *construct_params) + * A callback function used by the type system to initialize the class + * of a specific type. This function should initialize all static class + * members. + * The initialization process of a class involves: + * <itemizedlist> + * <listitem><para> + * 1 - Copying common members from the parent class over to the + * derived class structure. + * </para></listitem> + * <listitem><para> + * 2 - Zero initialization of the remaining members not copied + * over from the parent class. + * </para></listitem> + * <listitem><para> + * 3 - Invocation of the GBaseInitFunc() initializers of all parent + * types and the class' type. + * </para></listitem> + * <listitem><para> + * 4 - Invocation of the class' GClassInitFunc() initializer. + * </para></listitem> + * </itemizedlist> + * Since derived classes are partially initialized through a memory copy + * of the parent class, the general rule is that GBaseInitFunc() and + * GBaseFinalizeFunc() should take care of necessary reinitialization + * and release of those class members that were introduced by the type + * that specified these GBaseInitFunc()/GBaseFinalizeFunc(). + * GClassInitFunc() should only care about initializing static + * class members, while dynamic class members (such as allocated strings + * or reference counted resources) are better handled by a GBaseInitFunc() + * for this type, so proper initialization of the dynamic class members + * is performed for class initialization of derived types as well. + * An example may help to correspond the intend of the different class + * initializers: + * |[ + * typedef struct { + * GObjectClass parent_class; + * gint static_integer; + * gchar *dynamic_string; + * } TypeAClass; + * static void + * type_a_base_class_init (TypeAClass *class) * { - * GObject *object; - * if (!the_singleton) + * class->dynamic_string = g_strdup ("some string"); + * } + * static void + * type_a_base_class_finalize (TypeAClass *class) * { - * object = G_OBJECT_CLASS (parent_class)->constructor (type, - * n_construct_params, - * construct_params); - * the_singleton = MY_SINGLETON (object); + * g_free (class->dynamic_string); * } - * else - * object = g_object_ref (G_OBJECT (the_singleton)); - * return object; + * static void + * type_a_class_init (TypeAClass *class) + * { + * class->static_integer = 42; * } - * </programlisting></example> + * typedef struct { + * TypeAClass parent_class; + * gfloat static_float; + * GString *dynamic_gstring; + * } TypeBClass; + * static void + * type_b_base_class_init (TypeBClass *class) + * { + * class->dynamic_gstring = g_string_new ("some other string"); + * } + * static void + * type_b_base_class_finalize (TypeBClass *class) + * { + * g_string_free (class->dynamic_gstring); + * } + * static void + * type_b_class_init (TypeBClass *class) + * { + * class->static_float = 3.14159265358979323846; + * } + * ]| + * Initialization of TypeBClass will first cause initialization of + * TypeAClass (derived classes reference their parent classes, see + * g_type_class_ref() on this). + * Initialization of TypeAClass roughly involves zero-initializing its fields, + * then calling its GBaseInitFunc() type_a_base_class_init() to allocate + * its dynamic members (dynamic_string), and finally calling its GClassInitFunc() + * type_a_class_init() to initialize its static members (static_integer). + * The first step in the initialization process of TypeBClass is then + * a plain memory copy of the contents of TypeAClass into TypeBClass and + * zero-initialization of the remaining fields in TypeBClass. + * The dynamic members of TypeAClass within TypeBClass now need + * reinitialization which is performed by calling type_a_base_class_init() + * with an argument of TypeBClass. + * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() + * is called to allocate the dynamic members of TypeBClass (dynamic_gstring), + * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), + * is called to complete the initialization process with the static members + * (static_float). + * Corresponding finalization counter parts to the GBaseInitFunc() functions + * have to be provided to release allocated resources at class finalization + * time. */ /** - * g_type_create_instance: (skip) - * @type: An instantiatable type to create an instance for. - * - * Creates and initializes an instance of @type if @type is valid and - * can be instantiated. The type system only performs basic allocation - * happen through functions supplied by the type's fundamental type - * implementation. So use of g_type_create_instance() is reserved for - * implementators of fundamental types only. E.g. instances of the - * #GObject hierarchy should be created via g_object_new() and - * <emphasis>never</emphasis> directly through - * g_type_create_instance() which doesn't handle things like singleton - * use this function, unless you're implementing a fundamental - * type. Also language bindings should <emphasis>not</emphasis> use - * this function but g_object_new() instead. - * treatment by the fundamental type implementation. + * GClosure: + * @in_marshal: Indicates whether the closure is currently being invoked with g_closure_invoke() + * @is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate() * - * And structure setups for instances: actual instance creation should - * Objects or object construction. note: Do <emphasis>not</emphasis> - * Returns: An allocated and initialized instance, subject to further + * A #GClosure represents a callback supplied by the programmer. */ /** - * g_type_interface_prerequisites: - * @interface_type: an interface type - * @n_prerequisites: (out) (allow-none): location to return the number of prerequisites, or %NULL - * - * Returns the prerequisites of an interfaces type. - * newly-allocated zero-terminated array of #GType containing - * the prerequisites of @interface_type + * GClosureMarshal: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. + * @n_param_values: the length of the @param_values array + * @param_values: an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() * - * Since: 2.2 - * Returns: (array length=n_prerequisites) (transfer full): a + * The type used for marshaller functions. */ /** - * GTypeFlags: - * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type. - * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init(). + * GClosureNotify: + * @data: data specified when registering the notification callback + * @closure: the #GClosure on which the notification is emitted * - * Bit masks used to check or determine characteristics of a type. + * The type used for the various notification callbacks which can be registered + * on closures. */ /** - * g_main_set_poll_func: - * @func: the function to call to poll all file descriptors - * - * Sets the function to use for the handle polling of file descriptors - * for the default main context. + * GConnectFlags: + * @G_CONNECT_AFTER: whether the handler should be called before or after the default handler of the signal. + * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when calling the handler. * - * Deprecated: 2.2: Use g_main_context_set_poll_func() again + * The connection flags are used to specify the behaviour of a signal's + * connection. */ /** - * g_signal_add_emission_hook: - * @signal_id: the signal identifier, as returned by g_signal_lookup(). - * @detail: the detail on which to call the hook. - * @hook_func: a #GSignalEmissionHook function. - * @hook_data: user data for @hook_func. - * @data_destroy: a #GDestroyNotify for @hook_data. - * - * Adds an emission hook for a signal, which will get called for any emission - * of that signal, independent of the instance. This is possible only - * for signals which don't have #G_SIGNAL_NO_HOOKS flag set. + * GConvertError: + * @G_CONVERT_ERROR_NO_CONVERSION: Conversion between the requested character sets is not supported. + * @G_CONVERT_ERROR_ILLEGAL_SEQUENCE: Invalid byte sequence in conversion input. + * @G_CONVERT_ERROR_FAILED: Conversion failed for some reason. + * @G_CONVERT_ERROR_PARTIAL_INPUT: Partial character sequence at end of input. + * @G_CONVERT_ERROR_BAD_URI: URI is invalid. + * @G_CONVERT_ERROR_NOT_ABSOLUTE_PATH: Pathname is not an absolute path. * - * Returns: the hook id, for later use with g_signal_remove_emission_hook(). + * Error codes returned by character set conversion routines. */ /** - * GRegexEvalCallback: - * @match_info: the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string. - * @result: a #GString containing the new string - * @user_data: user data passed to g_regex_replace_eval() + * GCopyFunc: + * @src: A pointer to the data which should be copied + * @data: Additional data * - * Specifies the type of the function passed to g_regex_replace_eval(). - * It is called for each occurance of the pattern in the string passed - * to g_regex_replace_eval(), and it should append the replacement to + * A function of this signature is used to copy the node data + * when doing a deep-copy of a tree. * - * Returns: %FALSE to continue the replacement process, %TRUE to stop it - * Since: 2.14 + * Returns: A pointer to the copy + * Since: 2.4 */ /** - * G_PARAM_SPEC_INT64: - * @pspec: a valid #GParamSpec instance + * GDateTime: * - * Cast a #GParamSpec instance into a #GParamSpecInt64. + * <structname>GDateTime</structname> is an opaque structure whose members + * cannot be accessed directly. + * + * Since: 2.26 */ /** - * g_node_insert_data_before: - * @parent: the #GNode to place the new #GNode under - * @sibling: the sibling #GNode to place the new #GNode before - * @data: the data for the new #GNode - * - * Inserts a new #GNode before the given sibling. + * GEnumClass: + * @g_type_class: the parent class + * @minimum: the smallest possible value. + * @maximum: the largest possible value. + * @n_values: the number of possible values. + * @values: an array of #GEnumValue structs describing the individual values. * - * Returns: the new #GNode + * The class of an enumeration type holds information about its + * possible values. */ /** - * G_TYPE_UCHAR: + * GEnumValue: + * @value: the enum value + * @value_name: the name of the value + * @value_nick: the nickname of the value * - * The fundamental type corresponding to #guchar. + * A structure which contains a single enum value, its name, and its + * nickname. */ /** - * GObjectGetPropertyFunc: - * @object: a #GObject - * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). - * @value: a #GValue to return the property value in - * @pspec: the #GParamSpec describing the property + * GFlagsClass: + * @g_type_class: the parent class + * @mask: a mask covering all possible values. + * @n_values: the number of possible values. + * @values: an array of #GFlagsValue structs describing the individual values. * - * The type of the @get_property function of #GObjectClass. + * The class of a flags type holds information about its + * possible values. */ /** - * g_value_type_transformable: - * @src_type: Source type. - * @dest_type: Target type. - * - * Check whether g_value_transform() is able to transform values - * of type @src_type into values of type @dest_type. + * GFlagsValue: + * @value: the flags value + * @value_name: the name of the value + * @value_nick: the nickname of the value * - * Returns: %TRUE if the transformation is possible, %FALSE otherwise. + * A structure which contains a single flags value, its name, and its + * nickname. */ /** - * GInterfaceInfo: - * @interface_init: location of the interface initialization function - * @interface_finalize: location of the interface finalization function - * @interface_data: user-supplied data passed to the interface init/finalize functions + * GIconv: * - * A structure that provides information to the type system which is - * used specifically for managing interface types. + * The <structname>GIConv</structname> struct wraps an + * iconv() conversion descriptor. It contains private data + * and should only be accessed using the following functions. */ /** - * G_IS_PARAM_SPEC_FLAGS: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. + * GInitiallyUnowned: * - * Returns: %TRUE on success. + * All the fields in the <structname>GInitiallyUnowned</structname> structure + * are private to the #GInitiallyUnowned implementation and should never be + * accessed directly. */ /** - * GMemVTable: - * @malloc: function to use for allocating memory. - * @realloc: function to use for reallocating memory. - * @free: function to use to free memory. - * @calloc: function to use for allocating zero-filled memory. - * @try_malloc: function to use for allocating memory without a default error handler. - * @try_realloc: function to use for reallocating memory without a default error handler. + * GInitiallyUnownedClass: * - * A set of functions used to perform memory allocation. The same #GMemVTable must - * be used for all allocations in the same program; a call to g_mem_set_vtable(), - * if it exists, should be prior to any use of GLib. + * The class structure for the <structname>GInitiallyUnowned</structname> type. */ /** - * GTypePluginCompleteInterfaceInfo: - * @plugin: the #GTypePlugin - * @instance_type: the #GType of an instantiable type to which the interface is added - * @interface_type: the #GType of the interface whose info is completed - * @info: the #GInterfaceInfo to fill in + * GInstanceInitFunc: + * @instance: The instance to initialize. + * @g_class: The class of the type the instance is created for. * - * The type of the @complete_interface_info function of #GTypePluginClass. + * A callback function used by the type system to initialize a new + * instance of a type. This function initializes all instance members and + * allocates any resources required by it. + * Initialization of a derived instance involves calling all its parent + * types instance initializers, so the class member of the instance + * is altered during its initialization to always point to the class that + * belongs to the type the current initializer was introduced for. */ /** - * g_try_renew: - * @struct_type: the type of the elements to allocate - * @mem: the currently allocated memory - * @n_structs: the number of elements to allocate - * - * Attempts to reallocate the memory pointed to by @mem, so that it now has - * space for @n_structs elements of type @struct_type, and returns %NULL on - * failure. Contrast with g_renew(), which aborts the program on failure. - * It returns the new address of the memory, which may have been moved. - * The function returns %NULL if an overflow occurs. + * GInterfaceFinalizeFunc: + * @g_iface: The interface structure to finalize. + * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. * - * Since: 2.8 - * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type + * A callback function used by the type system to finalize an interface. + * This function should destroy any internal data and release any resources + * allocated by the corresponding GInterfaceInitFunc() function. */ /** - * g_value_set_pointer: - * @value: a valid #GValue of %G_TYPE_POINTER - * @v_pointer: pointer value to be set + * GInterfaceInfo: + * @interface_init: location of the interface initialization function + * @interface_finalize: location of the interface finalization function + * @interface_data: user-supplied data passed to the interface init/finalize functions * - * Set the contents of a pointer #GValue to @v_pointer. + * A structure that provides information to the type system which is + * used specifically for managing interface types. */ /** - * g_closure_sink: - * @closure: #GClosure to decrement the initial reference count on, if it's still being held + * GInterfaceInitFunc: + * @g_iface: The interface structure to initialize. + * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. * - * Takes over the initial ownership of a closure. Each closure is - * initially created in a <firstterm>floating</firstterm> state, which - * means that the initial reference count is not owned by any caller. - * g_closure_sink() checks to see if the object is still floating, and - * if so, unsets the floating state and decreases the reference - * count. If the closure is not floating, g_closure_sink() does - * nothing. The reason for the existance of the floating state is to - * prevent cumbersome code sequences like: - * |[ - * closure = g_cclosure_new (cb_func, cb_data); - * g_source_set_closure (source, closure); - * g_closure_unref (closure); // XXX GObject doesn't really need this - * ]| - * Because g_source_set_closure() (and similar functions) take ownership of the - * initial reference count, if it is unowned, we instead can write: - * |[ - * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); - * ]| - * Generally, this function is used together with g_closure_ref(). Ane example - * of storing a closure for later notification looks like: - * |[ - * static GClosure *notify_closure = NULL; - * void - * foo_notify_set_closure (GClosure *closure) - * { - * if (notify_closure) - * g_closure_unref (notify_closure); - * notify_closure = closure; - * if (notify_closure) - * { - * g_closure_ref (notify_closure); - * g_closure_sink (notify_closure); - * } - * } - * ]| - * Because g_closure_sink() may decrement the reference count of a closure - * (if it hasn't been called on @closure yet) just like g_closure_unref(), - * g_closure_ref() should be called prior to this function. + * A callback function used by the type system to initialize a new + * interface. This function should initialize all internal data and + * allocate any resources required by the interface. */ /** - * g_type_depth: - * @type: A #GType value. - * - * Returns the length of the ancestry of the passed in type. This - * includes the type itself, so that e.g. a fundamental type has depth 1. + * GMainContext: * - * Returns: The depth of @type. + * The <structname>GMainContext</structname> struct is an opaque data + * type representing a set of sources to be handled in a main loop. */ /** - * GObjectSetPropertyFunc: - * @object: a #GObject - * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). - * @value: the new value for the property - * @pspec: the #GParamSpec describing the property + * GMainLoop: * - * The type of the @set_property function of #GObjectClass. + * The <structname>GMainLoop</structname> struct is an opaque data type + * representing the main event loop of a GLib or GTK+ application. */ /** - * G_IS_VALUE: - * @value: A #GValue structure. + * GMarkupError: + * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8 + * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace + * @G_MARKUP_ERROR_PARSE: document was ill-formed + * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known + * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known + * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid + * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing * - * Checks if @value is a valid and initialized #GValue structure. - * - * Returns: %TRUE on success. + * Error codes returned by markup parsing. */ /** - * G_TYPE_PARAM_CHAR: + * GMarkupParseContext: * - * The #GType of #GParamSpecChar. + * A parse context is used to parse a stream of bytes that + * you expect to contain marked-up text. + * See g_markup_parse_context_new(), #GMarkupParser, and so + * on for more details. */ /** - * GParamSpecUnichar: - * @parent_instance: private #GParamSpec portion - * @default_value: default value for the property specified + * GMarkupParseFlags: + * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use + * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked sections are not passed literally to the @passthrough function of the parser. Instead, the content of the section (without the <literal><![CDATA[</literal> and <literal>]]></literal>) is passed to the @text function. This flag was added in GLib 2.12 + * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup itself have line/column information prefixed to them to let the caller know the location of the error. When this flag is set the location information is also prefixed to errors generated by the #GMarkupParser implementation functions * - * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. + * Flags that affect the behaviour of the parser. */ /** - * G_VARIANT_TYPE_BYTESTRING_ARRAY: + * GMarkupParser: + * @start_element: Callback to invoke when the opening tag of an element is seen. + * @end_element: Callback to invoke when the closing tag of an element is seen. Note that this is also called for empty tags like <literal><empty/></literal>. + * @text: Callback to invoke when some text is seen (text is always inside an element). Note that the text of an element may be spread over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also called for the content of CDATA marked sections. + * @passthrough: Callback to invoke for comments, processing instructions and doctype declarations; if you're re-writing the parsed document, write the passthrough text back out in the same position. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also called for CDATA marked sections. + * @error: Callback to invoke when an error occurs. * - * The type of an array of byte strings (an array of arrays of bytes). + * Any of the fields in #GMarkupParser can be %NULL, in which case they + * will be ignored. Except for the @error function, any of these callbacks + * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT, + * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT + * errors are intended to be set from these callbacks. If you set an error + * from a callback, g_markup_parse_context_parse() will report that error + * back to its caller. */ /** - * G_DEFINE_TYPE_EXTENDED: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * @_f_: #GTypeFlags to pass to g_type_register_static() - * @_C_: Custom code that gets inserted in the *_get_type() function. - * - * The most general convenience macro for type implementations, on which - * G_DEFINE_TYPE(), etc are based. - * |[ - * G_DEFINE_TYPE_EXTENDED (GtkGadget, - * gtk_gadget, - * GTK_TYPE_WIDGET, - * 0, - * G_IMPLEMENT_INTERFACE (TYPE_GIZMO, - * gtk_gadget_gizmo_init)); - * ]| - * expands to - * |[ - * static void gtk_gadget_init (GtkGadget *self); - * static void gtk_gadget_class_init (GtkGadgetClass *klass); - * static gpointer gtk_gadget_parent_class = NULL; - * static void gtk_gadget_class_intern_init (gpointer klass) - * { - * gtk_gadget_parent_class = g_type_class_peek_parent (klass); - * gtk_gadget_class_init ((GtkGadgetClass*) klass); - * } - * GType - * gtk_gadget_get_type (void) - * { - * static volatile gsize g_define_type_id__volatile = 0; - * if (g_once_init_enter (&g_define_type_id__volatile)) - * { - * GType g_define_type_id = - * g_type_register_static_simple (GTK_TYPE_WIDGET, - * g_intern_static_string ("GtkGadget"), - * sizeof (GtkGadgetClass), - * (GClassInitFunc) gtk_gadget_class_intern_init, - * sizeof (GtkGadget), - * (GInstanceInitFunc) gtk_gadget_init, - * (GTypeFlags) flags); - * { - * static const GInterfaceInfo g_implement_interface_info = { - * (GInterfaceInitFunc) gtk_gadget_gizmo_init - * }; - * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); - * } - * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); - * } - * return g_define_type_id__volatile; - * } - * ]| - * The only pieces which have to be manually provided are the definitions of - * the instance and class structure and the definitions of the instance and - * class init functions. + * GMemVTable: + * @malloc: function to use for allocating memory. + * @realloc: function to use for reallocating memory. + * @free: function to use to free memory. + * @calloc: function to use for allocating zero-filled memory. + * @try_malloc: function to use for allocating memory without a default error handler. + * @try_realloc: function to use for reallocating memory without a default error handler. * - * Since: 2.4 + * A set of functions used to perform memory allocation. The same #GMemVTable must + * be used for all allocations in the same program; a call to g_mem_set_vtable(), + * if it exists, should be prior to any use of GLib. */ /** - * g_object_set_data_full: (skip) - * @object: #GObject containing the associations - * @key: name of the key - * @data: data to associate with that key - * @destroy: function to call when the association is destroyed + * GObject: * - * Like g_object_set_data() except it adds notification - * for when the association is destroyed, either by setting it - * to a different value or when the object is destroyed. - * Note that the @destroy callback is not called if @data is %NULL. + * All the fields in the <structname>GObject</structname> structure are private + * to the #GObject implementation and should never be accessed directly. */ /** - * GBinding:source: - * - * The #GObject that should be used as the source of the binding + * GObject::notify: + * @gobject: the object which received the signal. + * @pspec: the #GParamSpec of the property which changed. * - * Since: 2.26 + * The notify signal is emitted on an object when one of its + * properties has been changed. Note that getting this signal + * doesn't guarantee that the value of the property has actually + * changed, it may also be emitted when the setter for the property + * is called to reinstate the previous value. + * This signal is typically used to obtain change notification for a + * single property, by specifying the property name as a detail in the + * g_signal_connect() call, like this: + * |[ + * g_signal_connect (text_view->buffer, "notify::paste-target-list", + * G_CALLBACK (gtk_text_view_target_list_notify), + * text_view) + * ]| + * It is important to note that you must use + * <link linkend="canonical-parameter-name">canonical</link> parameter names as + * detail strings for the notify signal. */ /** - * G_PARAM_SPEC_GTYPE: - * @pspec: a #GParamSpec - * - * Casts a #GParamSpec into a #GParamSpecGType. + * GObjectClass: + * @g_type_class: the parent class + * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons. + * @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system. + * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties. + * @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class. + * @finalize: instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class. + * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed. + * @notify: the class closure for the notify signal + * @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation. * - * Since: 2.10 + * The class structure for the <structname>GObject</structname> type. + * <example> + * <title>Implementing singletons using a constructor</title> + * <programlisting> + * static MySingleton *the_singleton = NULL; + * static GObject* + * my_singleton_constructor (GType type, + * guint n_construct_params, + * GObjectConstructParam *construct_params) + * { + * GObject *object; + * if (!the_singleton) + * { + * object = G_OBJECT_CLASS (parent_class)->constructor (type, + * n_construct_params, + * construct_params); + * the_singleton = MY_SINGLETON (object); + * } + * else + * object = g_object_ref (G_OBJECT (the_singleton)); + * return object; + * } + * </programlisting></example> */ /** - * g_value_get_param: - * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM - * - * Get the contents of a %G_TYPE_PARAM #GValue. + * GObjectConstructParam: + * @pspec: the #GParamSpec of the construct parameter + * @value: the value to set the parameter to * - * Returns: (transfer none): #GParamSpec content of @value + * The <structname>GObjectConstructParam</structname> struct is an auxiliary + * structure used to hand #GParamSpec/#GValue pairs to the @constructor of + * a #GObjectClass. */ /** - * G_TYPE_ERROR: - * - * The #GType for a boxed type holding a #GError. + * GObjectFinalizeFunc: + * @object: the #GObject being finalized * - * Since: 2.26 + * The type of the @finalize function of #GObjectClass. */ /** - * G_PARAM_SPEC_LONG: - * @pspec: a valid #GParamSpec instance + * GObjectGetPropertyFunc: + * @object: a #GObject + * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). + * @value: a #GValue to return the property value in + * @pspec: the #GParamSpec describing the property * - * Cast a #GParamSpec instance into a #GParamSpecLong. + * The type of the @get_property function of #GObjectClass. */ /** - * g_signal_lookup: - * @name: the signal's name. - * @itype: the type that the signal operates on. - * - * Given the name of the signal and the type of object it connects to, gets - * the signal's identifying integer. Emitting the signal by number is - * somewhat faster than using the name each time. - * Also tries the ancestors of the given type. - * See g_signal_new() for details on allowed signal names. + * GObjectSetPropertyFunc: + * @object: a #GObject + * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). + * @value: the new value for the property + * @pspec: the #GParamSpec describing the property * - * Returns: the signal's identifying number, or 0 if no signal was found. + * The type of the @set_property function of #GObjectClass. */ /** - * g_value_dup_object: - * @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT + * GOptionArg: + * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags. + * @G_OPTION_ARG_STRING: The option takes a string argument. + * @G_OPTION_ARG_INT: The option takes an integer argument. + * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument. + * @G_OPTION_ARG_FILENAME: The option takes a filename as argument. + * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings. + * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings. + * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12 + * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>). Since 2.12 * - * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing - * its reference count. - * should be unreferenced when no longer needed. + * The #GOptionArg enum values determine which type of extra argument the + * options expect to find. If an option expects an extra argument, it + * can be specified in several ways; with a short option: + * <option>-x arg</option>, with a long option: <option>--name arg</option> * - * Returns: (type GObject.Object) (transfer full): object content of @value, + * Or combined in a single argument: <option>--name=arg</option>. */ /** - * g_signal_emit_valist: - * @instance: the instance the signal is being emitted on. - * @signal_id: the signal id - * @detail: the detail - * @var_args: a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * GOptionArgFunc: + * @option_name: The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name. + * @value: The value to be parsed. + * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks. * - * Emits a signal. - * Note that g_signal_emit_valist() resets the return value to the default - * if no handlers are connected, in contrast to g_signal_emitv(). + * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK + * options. + * occurred, in which case @error should be set with g_set_error() + * + * Returns: %TRUE if the option was successfully parsed, %FALSE if an error */ /** - * g_variant_get_gtype: - * - * + * GOptionContext: * - * Since: 2.24 - * Deprecated: 2.26 + * A <structname>GOptionContext</structname> struct defines which options + * are accepted by the commandline option parser. The struct has only private + * fields and should not be directly accessed. */ /** - * G_VALUE_HOLDS_ULONG: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. + * GOptionEntry: + * @long_name: The long name of an option can be used to specify it in a commandline as --<replaceable>long_name</replaceable>. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>. + * @short_name: If an option has a short name, it can be specified -<replaceable>short_name</replaceable> in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name. + * @flags: Flags from #GOptionFlags. + * @arg: The type of the option, as a #GOptionArg. + * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: <variablelist> <varlistentry> <term>%G_OPTION_ARG_NONE</term> <listitem><para>%gboolean</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_INT</term> <listitem><para>%gint</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_DOUBLE</term> <listitem><para>%gdouble</para></listitem> </varlistentry> </variablelist> If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). + * @description: the description for the option in <option>--help</option> output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). + * @arg_description: The placeholder to use for the extra argument parsed by the option in <option>--help</option> output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). * - * Returns: %TRUE on success. + * A <structname>GOptionEntry</structname> defines a single option. + * To have an effect, they must be added to a #GOptionGroup with + * g_option_context_add_main_entries() or g_option_group_add_entries(). */ /** - * g_object_get_valist: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to get - * @var_args: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + * GOptionError: + * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options(). + * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed. + * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed. * - * Gets properties of an object. - * In general, a copy is made of the property contents and the caller - * is responsible for freeing the memory in the appropriate manner for - * the type, for instance by calling g_free() or g_object_unref(). - * See g_object_get(). + * Error codes returned by option parsing. */ /** - * g_value_get_uint64: - * @value: a valid #GValue of type %G_TYPE_UINT64 - * - * Get the contents of a %G_TYPE_UINT64 #GValue. + * GOptionErrorFunc: + * @context: The active #GOptionContext + * @group: The group to which the function belongs + * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + * @error: The #GError containing details about the parse error * - * Returns: unsigned 64bit integer contents of @value + * The type of function to be used as callback when a parse error occurs. */ /** - * G_TYPE_NONE: + * GOptionFlags: + * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output. + * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the <option>--help</option> output, even if it is defined in a group. + * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed. + * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8 + * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8 + * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8 + * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution which prefixes long option names with <literal>groupname-</literal> if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8. * - * A fundamental type which is used as a replacement for the C - * <literal>void</literal> return type. + * Flags which modify individual options. */ /** - * G_VARIANT_TYPE_BASIC: + * GOptionGroup: * - * An indefinite type that is a supertype of every basic (ie: - * non-container) type. + * A <structname>GOptionGroup</structname> struct defines the options in a single + * group. The struct has only private fields and should not be directly accessed. + * All options in a group share the same translation function. Libraries which + * need to parse commandline options are expected to provide a function for + * getting a <structname>GOptionGroup</structname> holding their options, which + * the application can then add to its #GOptionContext. */ /** - * G_OBJECT_TYPE: - * @object: Object to return the type id for. + * GOptionParseFunc: + * @context: The active #GOptionContext + * @group: The group to which the function belongs + * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + * @error: A return location for error details * - * Get the type id of an object. + * The type of function that can be called before and after parsing. + * occurred, in which case @error should be set with g_set_error() * - * Returns: Type id of @object. + * Returns: %TRUE if the function completed successfully, %FALSE if an error */ /** - * g_clear_object: (skip) - * @object_ptr: a pointer to a #GObject reference - * - * Clears a reference to a #GObject. - * If the reference is %NULL then this function does nothing. - * Otherwise, the reference count of the object is decreased and the - * pointer is set to %NULL. - * This function is threadsafe and modifies the pointer atomically, - * using memory barriers where needed. - * A macro is also included that allows this function to be used without - * pointer casts. + * GParamFlags: + * @G_PARAM_READABLE: the parameter is readable + * @G_PARAM_WRITABLE: the parameter is writable + * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction + * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction + * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required + * @G_PARAM_STATIC_NAME: the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 + * @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8 + * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 + * @G_PARAM_PRIVATE: internal + * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26 * - * Since: 2.28 + * Through the #GParamFlags flag values, certain aspects of parameters + * can be configured. */ /** - * G_IS_OBJECT_CLASS: - * @class: a #GObjectClass + * GParamSpec: + * @g_type_instance: private #GTypeInstance portion + * @name: name of this parameter + * @flags: #GParamFlags flags for this parameter + * @value_type: the #GValue type for this parameter + * @owner_type: #GType type that uses (introduces) this parameter * - * Checks whether @class "is a" valid #GObjectClass structure of type - * %G_TYPE_OBJECT or derived. + * All other fields of the <structname>GParamSpec</structname> struct are private and + * should not be used directly. */ /** - * GInitiallyUnowned: + * GParamSpecBoolean: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified * - * All the fields in the <structname>GInitiallyUnowned</structname> structure - * are private to the #GInitiallyUnowned implementation and should never be - * accessed directly. + * A #GParamSpec derived structure that contains the meta data for boolean properties. */ /** - * g_object_set: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to set - * @...: value for the first property, followed optionally by more name/value pairs, followed by %NULL + * GParamSpecBoxed: + * @parent_instance: private #GParamSpec portion * - * Sets properties on an object. + * A #GParamSpec derived structure that contains the meta data for boxed properties. */ /** - * G_VALUE_HOLDS_PARAM: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. + * GParamSpecChar: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Returns: %TRUE on success. + * A #GParamSpec derived structure that contains the meta data for character properties. */ /** - * g_object_is_floating: - * @object: (type GObject.Object): a #GObject - * - * Checks wether @object has a <link linkend="floating-ref">floating</link> - * reference. + * GParamSpecClass: + * @g_type_class: the parent class + * @value_type: the #GValue type for this parameter + * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class. + * @value_set_default: Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default(). + * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_set_validate(). + * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp(). * - * Since: 2.10 - * Returns: %TRUE if @object has a floating reference + * The class structure for the <structname>GParamSpec</structname> type. + * Normally, <structname>GParamSpec</structname> classes are filled by + * g_param_type_register_static(). */ /** - * GOptionErrorFunc: - * @context: The active #GOptionContext - * @group: The group to which the function belongs - * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() - * @error: The #GError containing details about the parse error + * GParamSpecDouble: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90. * - * The type of function to be used as callback when a parse error occurs. + * A #GParamSpec derived structure that contains the meta data for double properties. */ /** - * G_TYPE_PARAM_FLOAT: + * GParamSpecEnum: + * @parent_instance: private #GParamSpec portion + * @enum_class: the #GEnumClass for the enum + * @default_value: default value for the property specified * - * The #GType of #GParamSpecFloat. + * A #GParamSpec derived structure that contains the meta data for enum + * properties. */ /** - * G_TYPE_FUNDAMENTAL: - * @type: A #GType value. + * GParamSpecFlags: + * @parent_instance: private #GParamSpec portion + * @flags_class: the #GFlagsClass for the flags + * @default_value: default value for the property specified * - * The fundamental type which is the ancestor of @type. - * Fundamental types are types that serve as ultimate bases for the derived types, - * thus they are the roots of distinct inheritance hierarchies. + * A #GParamSpec derived structure that contains the meta data for flags + * properties. */ /** - * g_type_class_ref: - * @type: Type ID of a classed type. - * - * Increments the reference count of the class structure belonging to - * exist already. - * structure for the given type ID. + * GParamSpecFloat: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30. * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass + * A #GParamSpec derived structure that contains the meta data for float properties. */ /** - * GInitiallyUnownedClass: + * GParamSpecGType: + * @parent_instance: private #GParamSpec portion + * @is_a_type: a #GType whose subtypes can occur as values * - * The class structure for the <structname>GInitiallyUnowned</structname> type. + * A #GParamSpec derived structure that contains the meta data for #GType properties. + * + * Since: 2.10 */ /** - * GConvertError: - * @G_CONVERT_ERROR_NO_CONVERSION: Conversion between the requested character sets is not supported. - * @G_CONVERT_ERROR_ILLEGAL_SEQUENCE: Invalid byte sequence in conversion input. - * @G_CONVERT_ERROR_FAILED: Conversion failed for some reason. - * @G_CONVERT_ERROR_PARTIAL_INPUT: Partial character sequence at end of input. - * @G_CONVERT_ERROR_BAD_URI: URI is invalid. - * @G_CONVERT_ERROR_NOT_ABSOLUTE_PATH: Pathname is not an absolute path. + * GParamSpecInt: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Error codes returned by character set conversion routines. + * A #GParamSpec derived structure that contains the meta data for integer properties. */ /** - * G_PARAM_SPEC_TYPE_NAME: - * @pspec: a valid #GParamSpec + * GParamSpecInt64: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Retrieves the #GType name of this @pspec. + * A #GParamSpec derived structure that contains the meta data for 64bit integer properties. */ /** - * G_IS_PARAM_SPEC_OBJECT: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. + * GParamSpecLong: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Returns: %TRUE on success. + * A #GParamSpec derived structure that contains the meta data for long integer properties. */ /** - * g_type_interface_peek_parent: - * @g_iface: (type GObject.TypeInterface): A #GTypeInterface structure. - * - * Returns the corresponding #GTypeInterface structure of the parent type - * of the instance type to which @g_iface belongs. This is useful when - * deriving the implementation of an interface from the parent type and - * then possibly overriding some methods. - * corresponding #GTypeInterface structure of the parent type of the - * instance type to which @g_iface belongs, or %NULL if the parent - * type doesn't conform to the interface. + * GParamSpecObject: + * @parent_instance: private #GParamSpec portion * - * Returns: (transfer none) (type GObject.TypeInterface): The + * A #GParamSpec derived structure that contains the meta data for object properties. */ /** - * G_IS_PARAM_SPEC_VALUE_ARRAY: - * @pspec: a valid #GParamSpec instance + * GParamSpecOverride: * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. + * This is a type of #GParamSpec type that simply redirects operations to + * another paramspec. All operations other than getting or + * setting the value are redirected, including accessing the nick and + * blurb, validating a value, and so forth. See + * g_param_spec_get_redirect_target() for retrieving the overidden + * property. #GParamSpecOverride is used in implementing + * g_object_class_override_property(), and will not be directly useful + * unless you are implementing a new base type similar to GObject. * - * Returns: %TRUE on success. + * Since: 2.4 */ /** - * G_TYPE_ENUM: + * GParamSpecParam: + * @parent_instance: private #GParamSpec portion * - * The fundamental type from which all enumeration types are derived. + * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM + * properties. */ /** - * G_IS_PARAM_SPEC_BOXED: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. + * GParamSpecPointer: + * @parent_instance: private #GParamSpec portion * - * Returns: %TRUE on success. + * A #GParamSpec derived structure that contains the meta data for pointer properties. */ /** - * g_type_set_qdata: - * @type: a #GType - * @quark: a #GQuark id to identify the data - * @data: the data + * GParamSpecPool: * - * Attaches arbitrary data to a type. + * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be + * quickly accessed by owner and name. The implementation of the #GObject property + * system uses such a pool to store the #GParamSpecs of the properties all object + * types. */ /** - * GOptionParseFunc: - * @context: The active #GOptionContext - * @group: The group to which the function belongs - * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() - * @error: A return location for error details - * - * The type of function that can be called before and after parsing. - * occurred, in which case @error should be set with g_set_error() + * GParamSpecString: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified + * @cset_first: a string containing the allowed values for the first byte + * @cset_nth: a string containing the allowed values for the subsequent bytes + * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth. + * @null_fold_if_empty: replace empty string by %NULL + * @ensure_non_null: replace %NULL strings by an empty string * - * Returns: %TRUE if the function completed successfully, %FALSE if an error + * A #GParamSpec derived structure that contains the meta data for string + * properties. */ /** - * G_ENUM_CLASS: - * @class: a valid #GEnumClass + * GParamSpecTypeInfo: + * @instance_size: Size of the instance (object) structure. + * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. + * @instance_init: Location of the instance initialization function (optional). + * @value_type: The #GType of values conforming to this #GParamSpec + * @finalize: The instance finalization function (optional). + * @value_set_default: Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default(). + * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_set_validate(). + * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp(). * - * Casts a derived #GEnumClass structure into a #GEnumClass structure. + * This structure is used to provide the type system with the information + * required to initialize and destruct (finalize) a parameter's class and + * instances thereof. + * The initialized structure is passed to the g_param_type_register_static() + * The type system will perform a deep copy of this structure, so its memory + * does not need to be persistent across invocation of + * g_param_type_register_static(). */ /** - * G_TYPE_CLASS_GET_PRIVATE: - * @klass: the class of a type deriving from @private_type. - * @g_type: the type identifying which private data to retrieve. - * @c_type: The C type for the private structure. - * - * Gets the private class structure for a particular type. - * The private structure must have been registered in the - * get_type() function with g_type_add_class_private(). - * This macro should only be used in type implementations. + * GParamSpecUChar: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Since: 2.24 - * Returns: a pointer to the private data structure. + * A #GParamSpec derived structure that contains the meta data for unsigned character properties. */ /** - * GChecksumType: - * @G_CHECKSUM_MD5: Use the MD5 hashing algorithm - * @G_CHECKSUM_SHA1: Use the SHA-1 hashing algorithm - * @G_CHECKSUM_SHA256: Use the SHA-256 hashing algorithm - * - * The hashing algorithm to be used by #GChecksum when performing the - * digest of some data. - * Note that the #GChecksumType enumeration may be extended at a later - * date to include new hashing algorithm types. + * GParamSpecUInt: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Since: 2.16 + * A #GParamSpec derived structure that contains the meta data for unsigned integer properties. */ /** - * G_VALUE_COLLECT_FORMAT_MAX_LENGTH: + * GParamSpecUInt64: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * The maximal number of #GTypeCValue<!-- -->s which can be collected for a - * single #GValue. + * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. */ /** - * g_object_new: (skip) - * @object_type: the type id of the #GObject subtype to instantiate - * @first_property_name: the name of the first property - * @...: the value of the first property, followed optionally by more name/value pairs, followed by %NULL - * - * Creates a new instance of a #GObject subtype and sets its properties. - * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. + * GParamSpecULong: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Returns: (transfer full): a new instance of @object_type + * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. */ /** - * G_PARAM_SPEC_POINTER: - * @pspec: a valid #GParamSpec instance + * GParamSpecUnichar: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified * - * Casts a #GParamSpec instance into a #GParamSpecPointer. + * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. */ /** - * g_value_set_int64: - * @value: a valid #GValue of type %G_TYPE_INT64 - * @v_int64: 64bit integer value to be set + * GParamSpecValueArray: + * @parent_instance: private #GParamSpec portion + * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL + * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements * - * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. + * A #GParamSpec derived structure that contains the meta data for #GValueArray properties. */ /** - * G_VALUE_HOLDS_INT: - * @value: a valid #GValue structure + * GParamSpecVariant: + * @parent_instance: private #GParamSpec portion + * @type: a #GVariantType, or %NULL + * @default_value: a #GVariant, or %NULL * - * Checks whether the given #GValue can hold values of type %G_TYPE_INT. + * A #GParamSpec derived structure that contains the meta data for #GVariant properties. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * G_NODE_IS_LEAF: - * @node: a #GNode - * - * Returns %TRUE if a #GNode is a leaf node. - * (i.e. it has no children) + * GParameter: + * @name: the parameter name + * @value: the parameter value * - * Returns: %TRUE if the #GNode is a leaf node + * The <structname>GParameter</structname> struct is an auxiliary structure used + * to hand parameter name/value pairs to g_object_newv(). */ /** - * g_type_children: - * @type: The parent type. - * @n_children: (out) (allow-none): Optional #guint pointer to contain the number of child types. - * - * Return a newly allocated and 0-terminated array of type IDs, listing the - * child types of @type. The return value has to be g_free()ed after use. - * and 0-terminated array of child types. + * GPid: * - * Returns: (array length=n_children) (transfer full): Newly allocated + * A type which is used to hold a process identification. + * On UNIX, processes are identified by a process id (an integer), + * while Windows uses process handles (which are pointers). */ /** - * G_TYPE_PARAM_BOOLEAN: + * GPollFD: + * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32) + * @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR. + * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred. + * * - * The #GType of #GParamSpecBoolean. */ /** - * G_TYPE_ARRAY: + * GPollFunc: + * @ufds: an array of #GPollFD elements + * @nfsd: the number of elements in @ufds + * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout. * - * The #GType for a boxed type holding a #GArray reference. + * Specifies the type of function passed to g_main_context_set_poll_func(). + * The semantics of the function should match those of the poll() system call. + * reported, or -1 if an error occurred. * - * Since: 2.22 + * Returns: the number of #GPollFD elements which have events or errors */ /** - * g_flags_get_value_by_nick: - * @flags_class: a #GFlagsClass - * @nick: the nickname to look up + * GRegex: * - * Looks up a #GFlagsValue by nickname. - * no flag with that nickname + * A GRegex is the "compiled" form of a regular expression pattern. This + * structure is opaque and its fields cannot be accessed directly. * - * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is + * Since: 2.14 */ /** - * g_type_default_interface_unref: - * @g_iface: (type GObject.TypeInterface): the default vtable structure for a interface, as returned by g_type_default_interface_ref() + * GRegexCompileFlags: + * @G_REGEX_CASELESS: Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting. + * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting. + * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting. + * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting. + * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. + * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set. + * @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern. + * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. + * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way). + * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches. + * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched. + * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'. + * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'. + * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'. * - * Decrements the reference count for the type corresponding to the - * interface default vtable @g_iface. If the type is dynamic, then - * when no one is using the interface and all references have - * been released, the finalize function for the interface's default - * vtable (the <structfield>class_finalize</structfield> member of - * #GTypeInfo) will be called. + * Flags specifying compile-time options. * - * Since: 2.4 + * Since: 2.14 */ /** - * g_type_module_set_name: - * @module: a #GTypeModule. - * @name: a human-readable name to use in error messages. + * GRegexError: + * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed. + * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed. + * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string. + * @G_REGEX_ERROR_MATCH: The match process failed. + * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16 + * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16 + * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16 + * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16 + * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16 + * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16 + * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16 + * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16 + * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16 + * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16 + * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16 + * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16 + * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16 + * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16 + * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16 + * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16 + * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16 + * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16 + * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16 + * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16 + * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16 + * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16 + * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16 + * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16 + * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16 + * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16 + * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16 + * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16 + * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16 + * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16 + * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16 + * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16 + * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16 + * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16 + * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16 + * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16 + * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16 + * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16 * - * Sets the name for a #GTypeModule + * Error codes returned by regular expressions functions. + * + * Since: 2.14 */ /** - * g_param_spec_int64: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * GRegexEvalCallback: + * @match_info: the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string. + * @result: a #GString containing the new string + * @user_data: user data passed to g_regex_replace_eval() * - * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. - * See g_param_spec_internal() for details on property names. + * Specifies the type of the function passed to g_regex_replace_eval(). + * It is called for each occurance of the pattern in the string passed + * to g_regex_replace_eval(), and it should append the replacement to * - * Returns: a newly created parameter specification + * Returns: %FALSE to continue the replacement process, %TRUE to stop it + * Since: 2.14 */ /** - * g_enum_get_value_by_nick: - * @enum_class: a #GEnumClass - * @nick: the nickname to look up + * GRegexMatchFlags: + * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. + * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A". + * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z". + * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b". + * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match(). + * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator. + * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator. + * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator. + * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized. * - * Looks up a #GEnumValue by nickname. - * enumeration doesn't have a member with that nickname + * Flags specifying match-time options. * - * Returns: the #GEnumValue with nickname @nick, or %NULL if the + * Since: 2.14 */ /** - * g_value_set_double: - * @value: a valid #GValue of type %G_TYPE_DOUBLE - * @v_double: double value to be set + * GSignalAccumulator: + * @ihint: Signal invocation hint, see #GSignalInvocationHint. + * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission. + * @handler_return: A #GValue holding the return value of the signal handler. + * @data: Callback data that was specified when creating the signal. * - * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. + * The signal accumulator is a special callback function that can be used + * to collect return values of the various callbacks that are called + * during a signal emission. The signal accumulator is specified at signal + * creation time, if it is left %NULL, no accumulation of callback return + * values is performed. The return value of signal emissions is then the + * value returned by the last callback. + * should be aborted. Returning %FALSE means to abort the + * current emission and %TRUE is returned for continuation. + * + * Returns: The accumulator function returns whether the signal emission */ /** - * SECTION:generic_value: - * @short_description: A polymorphic type that can hold values of any other type - * @see_also: The fundamental types which all support #GValue operations and thus can be used as a type initializer for g_value_init() are defined by a separate interface. See the <link linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values API</link> for details. - * @title: Generic values + * GSignalCMarshaller: * - * The #GValue structure is basically a variable container that consists - * of a type identifier and a specific value of that type. - * The type identifier within a #GValue structure always determines the - * type of the associated value. - * To create a undefined #GValue structure, simply create a zero-filled - * #GValue structure. To initialize the #GValue, use the g_value_init() - * function. A #GValue cannot be used until it is initialized. - * The basic type operations (such as freeing and copying) are determined - * by the #GTypeValueTable associated with the type ID stored in the #GValue. - * Other #GValue operations (such as converting values between types) are - * provided by this interface. - * The code in the example program below demonstrates #GValue's - * features. - * |[ - * #include <glib-object.h> - * static void - * int2string (const GValue *src_value, - * GValue *dest_value) - * { - * if (g_value_get_int (src_value) == 42) - * g_value_set_static_string (dest_value, "An important number"); - * else - * g_value_set_static_string (dest_value, "What's that?"); - * } - * int - * main (int argc, - * char *argv[]) - * { - * /* GValues must start zero-filled */ - * GValue a = {0}; - * GValue b = {0}; - * const gchar *message; - * g_type_init (); - * /* The GValue starts empty */ - * g_assert (!G_VALUE_HOLDS_STRING (&a)); - * /* Put a string in it */ - * g_value_init (&a, G_TYPE_STRING); - * g_assert (G_VALUE_HOLDS_STRING (&a)); - * g_value_set_static_string (&a, "Hello, world!"); - * g_printf ("%s\n", g_value_get_string (&a)); - * /* Reset it to its pristine state */ - * g_value_unset (&a); - * /* It can then be reused for another type */ - * g_value_init (&a, G_TYPE_INT); - * g_value_set_int (&a, 42); - * /* Attempt to transform it into a GValue of type STRING */ - * g_value_init (&b, G_TYPE_STRING); - * /* An INT is transformable to a STRING */ - * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); - * /* Attempt to transform it again using a custom transform function */ - * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); - * return 0; - * } - * ]| + * This is the signature of marshaller functions, required to marshall + * arrays of parameter values to signal emissions into C language callback + * invocations. It is merely an alias to #GClosureMarshal since the #GClosure + * mechanism takes over responsibility of actual function invocation for the + * signal system. */ /** - * G_TYPE_CHECK_VALUE: - * @value: a #GValue + * GSignalEmissionHook: + * @ihint: Signal invocation hint, see #GSignalInvocationHint. + * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted. + * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission. + * @data: user data associated with the hook. * - * Checks if @value has been initialized to hold values - * of a value type. - * This macro should only be used in type implementations. + * A simple function pointer to get invoked when the signal is emitted. This + * allows you to tie a hook to the signal type, so that it will trap all + * emissions of that signal, from any object. + * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. + * hook is disconnected (and destroyed). * - * Returns: %TRUE on success. + * Returns: whether it wants to stay connected. If it returns %FALSE, the signal */ /** - * G_DEFINE_POINTER_TYPE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * - * A convenience macro for pointer type implementations, which defines a - * type_name_get_type() function registering the pointer type. + * GSignalFlags: + * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage. + * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage. + * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage. + * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted. + * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions. + * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code. + * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. * - * Since: 2.26 + * The signal flags are used to specify a signal's behaviour, the overall + * signal description outlines how especially the RUN flags control the + * stages of a signal emission. */ /** - * g_value_set_instance: - * @value: An initialized #GValue structure. - * @instance: the instance + * GSignalInvocationHint: + * @signal_id: The signal id of the signal invoking the callback + * @detail: The detail passed on for this emission + * @run_type: The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. * - * Sets @value from an instantiatable type via the - * value_table's collect_value() function. + * The #GSignalInvocationHint structure is used to pass on additional information + * to callbacks during a signal emission. */ /** - * g_type_free_instance: - * @instance: an instance of a type. + * GSignalMatchType: + * @G_SIGNAL_MATCH_ID: The signal id must be equal. + * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal. + * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same. + * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same. + * @G_SIGNAL_MATCH_DATA: The closure data must be the same. + * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched. * - * Frees an instance of a type, returning it to the instance pool for - * the type, if there is one. - * Like g_type_create_instance(), this function is reserved for - * implementors of fundamental types. + * The match types specify what g_signal_handlers_block_matched(), + * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() + * match signals by. */ /** - * GChecksum: - * - * An opaque structure representing a checksumming operation. - * To create a new GChecksum, use g_checksum_new(). To free - * a GChecksum, use g_checksum_free(). + * GSignalQuery: + * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown. + * @signal_name: The signal name. + * @itype: The interface/instance type that this signal can be emitted for. + * @signal_flags: The signal flags as passed in to g_signal_new(). + * @return_type: The return type for user callbacks. + * @n_params: The number of parameters that user callbacks take. + * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting> * - * Since: 2.16 + * A structure holding in-depth information for a specific signal. It is + * filled in by the g_signal_query() function. */ /** - * g_type_plugin_complete_interface_info: - * @plugin: the #GTypePlugin - * @instance_type: the #GType of an instantiable type to which the interface is added - * @interface_type: the #GType of the interface whose info is completed - * @info: the #GInterfaceInfo to fill in + * GSource: * - * Calls the @complete_interface_info function from the - * #GTypePluginClass of @plugin. There should be no need to use this - * function outside of the GObject type system itself. + * The <structname>GSource</structname> struct is an opaque data type + * representing an event source. */ /** - * G_CALLBACK: - * @f: a function pointer. + * GSourceCallbackFuncs: + * @ref: Called when a reference is added to the callback object + * @unref: Called when a reference to the callback object is dropped + * @get: Called to extract the callback function and data from the callback object. * - * Cast a function pointer to a #GCallback. + * The <structname>GSourceCallbackFuncs</structname> struct contains + * functions for managing callback objects. */ /** - * g_signal_chain_from_overridden: - * @instance_and_params: the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. - * @return_value: Location for the return value. + * GSourceFuncs: + * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the + * @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here. + * @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source. + * @finalize: Called when the source is finalized. * - * Calls the original class closure of a signal. This function should only - * be called from an overridden class closure; see - * g_signal_override_class_closure() and - * g_signal_override_class_handler(). + * The <structname>GSourceFuncs</structname> struct contains a table of + * functions used to handle event sources in a generic manner. + * For idle sources, the prepare and check functions always return %TRUE + * to indicate that the source is always ready to be processed. The prepare + * function also returns a timeout value of 0 to ensure that the poll() call + * doesn't block (since that would be time wasted which could have been spent + * running the idle function). + * For timeout sources, the prepare and check functions both return %TRUE + * if the timeout interval has expired. The prepare function also returns + * a timeout value to ensure that the poll() call doesn't block too long + * and miss the next timeout. + * For file descriptor sources, the prepare function typically returns %FALSE, + * since it must wait until poll() has been called before it knows whether + * any events need to be processed. It sets the returned timeout to -1 to + * indicate that it doesn't mind how long the poll() call blocks. In the + * check function, it tests the results of the poll() call to see if the + * required condition has been met, and returns %TRUE if so. */ /** - * G_TYPE_INT: + * GStrv: * - * The fundamental type corresponding to #gint. + * A C representable type name for #G_TYPE_STRV. */ /** - * g_source_set_dummy_callback: - * @source: the source + * GTestLogFatalFunc: + * @log_domain: the log domain of the message + * @log_level: the log level of the message (including the fatal and recursion flags) + * @message: the message to process + * @user_data: user data, set in g_test_log_set_fatal_handler() * - * Sets a dummy callback for @source. The callback will do nothing, and - * if the source expects a #gboolean return value, it will return %TRUE. - * (If the source expects any other type of return value, it will return - * a 0/%NULL value; whatever g_value_init() initializes a #GValue to for - * that type.) - * If the source is not one of the standard GLib types, the - * structure must have been filled in with pointers to appropriate - * functions. + * Specifies the prototype of fatal log handler functions. + * + * Returns: %TRUE if the program should abort, %FALSE otherwise + * Since: 2.22 */ /** - * g_value_set_gtype: - * @value: a valid #GValue of type %G_TYPE_GTYPE - * @v_gtype: #GType to be set + * GTimeSpan: * - * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. + * A value representing an interval of time, in microseconds. * - * Since: 2.12 + * Since: 2.26 */ /** - * g_value_fits_pointer: - * @value: An initialized #GValue structure. - * - * Determines if @value will fit inside the size of a pointer value. - * This is an internal function introduced mainly for C marshallers. + * GTimeType: + * @G_TIME_TYPE_STANDARD: the time is in local standard time + * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time + * @G_TIME_TYPE_UNIVERSAL: the time is in UTC * - * Returns: %TRUE if @value will fit inside a pointer value. + * Disambiguates a given time in two ways. + * First, specifies if the given time is in universal or local time. + * Second, if the time is in local time, specifies if it is local + * standard time or local daylight time. This is important for the case + * where the same local time occurs twice (during daylight savings time + * transitions, for example). */ /** - * G_VALUE_HOLDS_OBJECT: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. + * GToggleNotify: + * @data: Callback data passed to g_object_add_toggle_ref() + * @object: The object on which g_object_add_toggle_ref() was called. + * @is_last_ref: %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references. * - * Returns: %TRUE on success. + * A callback function used for notification when the state + * of a toggle reference changes. See g_object_add_toggle_ref(). */ /** - * G_IS_PARAM_SPEC_UINT64: - * @pspec: a valid #GParamSpec instance + * GTranslateFunc: + * @str: the untranslated string + * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func() * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. + * The type of functions which are used to translate user-visible + * strings, for <option>--help</option> output. + * The returned string is owned by GLib and must not be freed. * - * Returns: %TRUE on success. + * Returns: a translation of the string for the current locale. */ /** - * G_TYPE_PARAM_POINTER: + * GType: * - * The #GType of #GParamSpecPointer. + * A numerical value which represents the unique identifier of a registered + * type. */ /** - * g_node_prepend_data: - * @parent: the #GNode to place the new #GNode under - * @data: the data for the new #GNode - * - * Inserts a new #GNode as the first child of the given parent. + * GTypeCValue: + * @v_int: the field for holding integer values + * @v_long: the field for holding long integer values + * @v_int64: the field for holding 64 bit integer values + * @v_double: the field for holding floating point values + * @v_pointer: the field for holding pointers * - * Returns: the new #GNode + * A union holding one collected value. */ /** - * G_VARIANT_TYPE_INT64: + * GTypeClass: * - * The type of an integer value that can range from - * -9223372036854775808 to 9223372036854775807. + * An opaque structure used as the base of all classes. */ /** - * G_TYPE_HASH_TABLE: + * GTypeClassCacheFunc: + * @cache_data: data that was given to the g_type_add_class_cache_func() call + * @g_class: The #GTypeClass structure which is unreferenced * - * The #GType for a boxed type holding a #GHashTable reference. + * A callback function which is called when the reference count of a class + * drops to zero. It may use g_type_class_ref() to prevent the class from + * being freed. You should not call g_type_class_unref() from a + * #GTypeClassCacheFunc function to prevent infinite recursion, use + * g_type_class_unref_uncached() instead. + * The functions have to check the class id passed in to figure + * whether they actually want to cache the class of this type, since all + * classes are routed through the same #GTypeClassCacheFunc chain. + * called, %FALSE to continue. * - * Since: 2.10 + * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being */ /** - * G_PARAM_SPEC_PARAM: - * @pspec: a valid #GParamSpec instance + * GTypeDebugFlags: + * @G_TYPE_DEBUG_NONE: Print no messages. + * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping. + * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions. + * @G_TYPE_DEBUG_MASK: Mask covering all debug flags. * - * Casts a #GParamSpec instance into a #GParamSpecParam. + * The <type>GTypeDebugFlags</type> enumeration values can be passed to + * g_type_init_with_debug_flags() to trigger debugging messages during runtime. + * Note that the messages can also be triggered by setting the + * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of + * "objects" and "signals". */ /** - * G_IS_PARAM_SPEC_ENUM: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. + * GTypeFlags: + * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type. + * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init(). * - * Returns: %TRUE on success. + * Bit masks used to check or determine characteristics of a type. */ /** - * g_type_module_use: - * @module: a #GTypeModule - * - * Increases the use count of a #GTypeModule by one. If the - * use count was zero before, the plugin will be loaded. - * If loading the plugin fails, the use count is reset to - * its prior value. - * loading the plugin failed. + * GTypeFundamentalFlags: + * @G_TYPE_FLAG_CLASSED: Indicates a classed type. + * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed). + * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type. + * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable). * - * Returns: %FALSE if the plugin needed to be loaded and + * Bit masks used to check or determine specific characteristics of a + * fundamental type. */ /** - * GMainLoop: + * GTypeFundamentalInfo: + * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type * - * The <structname>GMainLoop</structname> struct is an opaque data type - * representing the main event loop of a GLib or GTK+ application. + * A structure that provides information to the type system which is + * used specifically for managing fundamental types. */ /** - * G_VARIANT_TYPE_OBJECT_PATH: + * GTypeInfo: + * @class_size: Size of the class structure (required for interface, classed and instantiatable types). + * @base_init: Location of the base initialization function (optional). + * @base_finalize: Location of the base finalization function (optional). + * @class_init: Location of the class initialization function for classed and instantiatable types. Location of the default vtable inititalization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties. + * @class_finalize: Location of the class finalization function for classed and instantiatable types. Location fo the default vtable finalization function for interface types. (optional) + * @class_data: User-supplied data passed to the class init/finalize functions. + * @instance_size: Size of the instance (object) structure (required for instantiatable types only). + * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. + * @instance_init: Location of the instance initialization function (optional, for instantiatable types only). + * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types). * - * The type of a DBus object reference. These are strings of a - * specific format used to identify objects at a given destination on - * the bus. - * If you are not interacting with DBus, then there is no reason to make - * use of this type. If you are, then the DBus specification contains a - * precise description of valid object paths. + * This structure is used to provide the type system with the information + * required to initialize and destruct (finalize) a type's class and + * its instances. + * The initialized structure is passed to the g_type_register_static() function + * (or is copied into the provided #GTypeInfo structure in the + * g_type_plugin_complete_type_info()). The type system will perform a deep + * copy of this structure, so its memory does not need to be persistent + * across invocation of g_type_register_static(). */ /** - * g_closure_new_object: - * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> - * @object: a #GObject pointer to store in the @data field of the newly allocated #GClosure - * - * A variant of g_closure_new_simple() which stores @object in the - * when implementing new types of closures. + * GTypeInstance: * - * Returns: (transfer full): a newly allocated #GClosure + * An opaque structure used as the base of all type instances. */ /** - * g_object_class_install_property: - * @oclass: a #GObjectClass - * @property_id: the id for the new property - * @pspec: the #GParamSpec for the new property + * GTypeInterface: * - * Installs a new property. This is usually done in the class initializer. - * Note that it is possible to redefine a property in a derived class, - * by installing a property with the same name. This can be useful at times, - * e.g. to change the range of allowed values or the default value. + * An opaque structure used as the base of all interface types. */ /** - * G_TYPE_INTERFACE: + * GTypeInterfaceCheckFunc: + * @check_data: data passed to g_type_add_interface_check(). + * @g_iface: the interface that has been initialized * - * The fundamental type from which all interfaces are derived. + * A callback called after an interface vtable is initialized. + * See g_type_add_interface_check(). + * + * Since: 2.4 */ /** - * GObject: + * GTypeModule: + * @name: the name of the module * - * All the fields in the <structname>GObject</structname> structure are private - * to the #GObject implementation and should never be accessed directly. + * The members of the <structname>GTypeModule</structname> structure should not + * be accessed directly, except for the @name field. */ /** - * GType: + * GTypeModuleClass: + * @parent_class: the parent class + * @load: loads the module and registers one or more types using g_type_module_register_type(). + * @unload: unloads the module * - * A numerical value which represents the unique identifier of a registered - * type. + * In order to implement dynamic loading of types based on #GTypeModule, + * the @load and @unload functions in #GTypeModuleClass must be implemented. */ /** - * g_signal_name: - * @signal_id: the signal's identifying number. - * - * Given the signal's identifier, finds its name. - * Two different signals may have the same name, if they have differing types. + * GTypePlugin: * - * Returns: the signal name, or %NULL if the signal number was invalid. + * The <structname>GTypePlugin</structname> typedef is used as a placeholder + * for objects that implement the <structname>GTypePlugin</structname> + * interface. */ /** - * g_value_take_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: duplicated unowned boxed value to be set - * - * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed - * and takes over the ownership of the callers reference to @v_boxed; - * the caller doesn't have to unref it any more. + * GTypePluginClass: + * @use_plugin: Increases the use count of the plugin. + * @unuse_plugin: Decreases the use count of the plugin. + * @complete_type_info: Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. + * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. * - * Since: 2.4 + * The #GTypePlugin interface is used by the type system in order to handle + * the lifecycle of dynamically loaded types. */ /** - * SECTION:value_array: - * @short_description: A container structure to maintain an array of generic values - * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array() - * @title: Value arrays + * GTypePluginCompleteInterfaceInfo: + * @plugin: the #GTypePlugin + * @instance_type: the #GType of an instantiable type to which the interface is added + * @interface_type: the #GType of the interface whose info is completed + * @info: the #GInterfaceInfo to fill in * - * The prime purpose of a #GValueArray is for it to be used as an - * object property that holds an array of values. A #GValueArray wraps - * an array of #GValue elements in order for it to be used as a boxed - * type through %G_TYPE_VALUE_ARRAY. + * The type of the @complete_interface_info function of #GTypePluginClass. */ /** - * G_VALUE_HOLDS_LONG: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_LONG. + * GTypePluginCompleteTypeInfo: + * @plugin: the #GTypePlugin + * @g_type: the #GType whose info is completed + * @info: the #GTypeInfo struct to fill in + * @value_table: the #GTypeValueTable to fill in * - * Returns: %TRUE on success. + * The type of the @complete_type_info function of #GTypePluginClass. */ /** - * g_value_set_uint: - * @value: a valid #GValue of type %G_TYPE_UINT - * @v_uint: unsigned integer value to be set + * GTypePluginUnuse: + * @plugin: the #GTypePlugin whose use count should be decreased * - * Set the contents of a %G_TYPE_UINT #GValue to @v_uint. + * The type of the @unuse_plugin function of #GTypePluginClass. */ /** - * G_IMPLEMENT_INTERFACE: - * @TYPE_IFACE: The #GType of the interface to add - * @iface_init: The interface init function - * - * A convenience macro to ease interface addition in the @_C_ section - * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). - * See G_DEFINE_TYPE_EXTENDED() for an example. - * Note that this macro can only be used together with the G_DEFINE_TYPE_* - * macros, since it depends on variable names from those macros. + * GTypePluginUse: + * @plugin: the #GTypePlugin whose use count should be increased * - * Since: 2.4 + * The type of the @use_plugin function of #GTypePluginClass, which gets called + * to increase the use count of @plugin. */ /** - * G_PARAM_SPEC_UNICHAR: - * @pspec: a valid #GParamSpec instance + * GTypeQuery: + * @type: the #GType value of the type. + * @type_name: the name of the type. + * @class_size: the size of the class structure. + * @instance_size: the size of the instance structure. * - * Cast a #GParamSpec instance into a #GParamSpecUnichar. + * A structure holding information for a specific type. It is + * filled in by the g_type_query() function. */ /** - * GParamSpecString: - * @parent_instance: private #GParamSpec portion - * @default_value: default value for the property specified - * @cset_first: a string containing the allowed values for the first byte - * @cset_nth: a string containing the allowed values for the subsequent bytes - * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth. - * @null_fold_if_empty: replace empty string by %NULL - * @ensure_non_null: replace %NULL strings by an empty string + * GTypeValueTable: + * @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]| + * @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]| + * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]| + * @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]| + * @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i' needs to be used, and for collection of floats 'd'. + * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined. + * @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations. + * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]| * - * A #GParamSpec derived structure that contains the meta data for string - * properties. + * The #GTypeValueTable provides the functions required by the #GValue implementation, + * to serve as a container for values of a type. */ /** - * g_cclosure_marshal_VOID__PARAM: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * GUserDirectory: + * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory + * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory + * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory + * @G_USER_DIRECTORY_MUSIC: the user's Music directory + * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory + * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory + * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory + * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory + * @G_USER_N_DIRECTORIES: the number of enum values * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>. + * These are logical ids for special directories which are defined + * depending on the platform used. You should use g_get_user_special_dir() + * to retrieve the full path associated to the logical id. + * The #GUserDirectory enumeration can be extended at later date. Not + * every platform has a directory for every logical id in this + * enumeration. + * + * Since: 2.14 */ /** - * g_param_spec_param: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @param_type: a #GType derived from %G_TYPE_PARAM - * @flags: flags for the property specified + * GValue: * - * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM - * property. - * See g_param_spec_internal() for details on property names. + * An opaque structure used to hold different types of values. + * to functions within a #GTypeValueTable structure, or implementations of + * the g_value_*() API. That is, code portions which implement new fundamental + * types. + * #GValue users can not make any assumptions about how data is stored + * within the 2 element @data union, and the @g_type member should + * only be accessed through the G_VALUE_TYPE() macro. * - * Returns: a newly created parameter specification + * The data within the structure has protected scope: it is accessible only */ /** - * g_param_spec_ulong: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG - * property. - * See g_param_spec_internal() for details on property names. + * GValueArray: + * @n_values: number of values contained in the array + * @values: array of values * - * Returns: a newly created parameter specification + * A #GValueArray contains an array of #GValue elements. */ /** - * G_TYPE_FROM_CLASS: - * @g_class: Location of a valid #GTypeClass structure. - * - * Get the type identifier from a given @class structure. - * This macro should only be used in type implementations. + * GValueTransform: + * @src_value: Source value. + * @dest_value: Target value. * - * Returns: the #GType + * The type of value transformation functions which can be registered with + * g_value_register_transform_func(). */ /** - * g_main_new: - * @is_running: set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_run() will set this to %TRUE anyway. - * - * Creates a new #GMainLoop for th default main context. + * GVariantType: * - * Returns: a new #GMainLoop - * Deprecated: 2.2: Use g_main_loop_new() instead + * A type in the GVariant type system. + * Two types may not be compared by value; use g_variant_type_equal() or + * g_variant_type_is_subtype(). May be copied using + * g_variant_type_copy() and freed using g_variant_type_free(). */ /** - * GPollFD: - * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32) - * @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR. - * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred. - * + * GWeakNotify: + * @data: data that was provided when the weak reference was established + * @where_the_object_was: the object being finalized * + * A #GWeakNotify function can be added to an object as a callback that gets + * triggered when the object is finalized. Since the object is already being + * finalized when the #GWeakNotify is called, there's not much you could do + * with the object, apart from e.g. using its adress as hash-index or the like. */ /** - * GParamSpecChar: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_BOOKMARK_FILE_ERROR: * - * A #GParamSpec derived structure that contains the meta data for character properties. + * Error domain for bookmark file parsing. + * Errors in this domain will be from the #GBookmarkFileError + * enumeration. See #GError for information on error domains. */ /** - * G_TYPE_IS_FLAGS: - * @type: a #GType ID. - * - * Checks whether @type "is a" %G_TYPE_FLAGS. + * G_CALLBACK: + * @f: a function pointer. * - * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS. + * Cast a function pointer to a #GCallback. */ /** - * g_flags_register_static: - * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. + * G_CCLOSURE_SWAP_DATA: + * @cclosure: a #GCClosure * - * Registers a new static flags type with the name @name. - * It is normally more convenient to let <link - * linkend="glib-mkenums">glib-mkenums</link> generate a - * my_flags_get_type() function from a usual C enumeration definition - * than to write one yourself using g_flags_register_static(). + * Checks whether the user data of the #GCClosure should be passed as the + * first parameter to the callback. See g_cclosure_new_swap(). * - * Returns: The new type identifier. + * Returns: %TRUE if data has to be swapped. */ /** - * g_type_init_with_debug_flags: - * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. + * G_CLOSURE_NEEDS_MARSHAL: + * @closure: a #GClosure * - * Similar to g_type_init(), but additionally sets debug flags. + * Check if the closure still needs a marshaller. See g_closure_set_marshal(). + * + * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on */ /** - * g_value_get_char: - * @value: a valid #GValue of type %G_TYPE_CHAR + * G_CLOSURE_N_NOTIFIERS: + * @cl: a #GClosure * - * Get the contents of a %G_TYPE_CHAR #GValue. + * Get the total number of notifiers connected with the closure @cl. + * The count includes the meta marshaller, the finalize and invalidate notifiers + * and the marshal guards. Note that each guard counts as two notifiers. + * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), + * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). * - * Returns: character contents of @value + * Returns: number of notifiers */ /** - * g_type_class_add_private: - * @g_class: class structure for an instantiatable type - * @private_size: size of private structure. - * - * Registers a private structure for an instantiatable type. - * When an object is allocated, the private structures for - * the type and all of its parent types are allocated - * sequentially in the same memory block as the public - * structures. - * Note that the accumulated size of the private structures of - * a type and all its parent types cannot excced 64kB. - * This function should be called in the type's class_init() function. - * The private structure can be retrieved using the - * G_TYPE_INSTANCE_GET_PRIVATE() macro. - * The following example shows attaching a private structure - * <structname>MyObjectPrivate</structname> to an object - * <structname>MyObject</structname> defined in the standard GObject - * fashion. - * type's class_init() function. - * |[ - * typedef struct _MyObject MyObject; - * typedef struct _MyObjectPrivate MyObjectPrivate; - * struct _MyObject { - * GObject parent; - * MyObjectPrivate *priv; - * }; - * struct _MyObjectPrivate { - * int some_field; - * }; - * static void - * my_object_class_init (MyObjectClass *klass) - * { - * g_type_class_add_private (klass, sizeof (MyObjectPrivate)); - * } - * static void - * my_object_init (MyObject *my_object) - * { - * my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object, - * MY_TYPE_OBJECT, - * MyObjectPrivate); - * } - * static int - * my_object_get_some_field (MyObject *my_object) - * { - * MyObjectPrivate *priv = my_object->priv; - * return priv->some_field; - * } - * ]| + * G_CONVERT_ERROR: * - * Since: 2.4 + * Error domain for character set conversions. Errors in this domain will + * be from the #GConvertError enumeration. See #GError for information on + * error domains. */ /** - * G_TYPE_PARAM_INT: + * G_DATALIST_FLAGS_MASK: * - * The #GType of #GParamSpecInt. + * A bitmask that restricts the possible flags passed to + * g_datalist_set_flags(). Passing a flags value where + * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. */ /** - * G_REGEX_ERROR: + * G_DEFINE_ABSTRACT_TYPE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. * - * Error domain for regular expressions. Errors in this domain will be - * from the #GRegexError enumeration. See #GError for information on - * error domains. + * A convenience macro for type implementations. + * Similar to G_DEFINE_TYPE(), but defines an abstract type. + * See G_DEFINE_TYPE_EXTENDED() for an example. * - * Since: 2.14 + * Since: 2.4 */ /** - * G_TYPE_IS_VALUE_TYPE: - * @type: A #GType value. + * G_DEFINE_ABSTRACT_TYPE_WITH_CODE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. + * @_C_: Custom code that gets inserted in the @type_name_get_type() function. * - * Checks if @type is a value type and can be used with g_value_init(). + * A convenience macro for type implementations. + * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to + * insert custom code into the *_get_type() function, e.g. interface implementations + * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. * - * Returns: %TRUE on success. + * Since: 2.4 */ /** - * GObjectConstructParam: - * @pspec: the #GParamSpec of the construct parameter - * @value: the value to set the parameter to + * G_DEFINE_BOXED_TYPE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @copy_func: the #GBoxedCopyFunc for the new type + * @free_func: the #GBoxedFreeFunc for the new type * - * The <structname>GObjectConstructParam</structname> struct is an auxiliary - * structure used to hand #GParamSpec/#GValue pairs to the @constructor of - * a #GObjectClass. + * A convenience macro for boxed type implementations, which defines a + * type_name_get_type() function registering the boxed type. + * + * Since: 2.26 */ /** - * g_type_get_qdata: - * @type: a #GType - * @quark: a #GQuark id to identify the data + * G_DEFINE_BOXED_TYPE_WITH_CODE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @copy_func: the #GBoxedCopyFunc for the new type + * @free_func: the #GBoxedFreeFunc for the new type + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Obtains data which has previously been attached to @type - * with g_type_set_qdata(). + * A convenience macro for boxed type implementations. + * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the + * type_name_get_type() function, e.g. to register value transformations with + * g_value_register_transform_func(). * - * Returns: (transfer none): the data, or %NULL if no data was found + * Since: 2.26 */ @@ -1984,1537 +2034,1160 @@ /** - * gchararray: - * - * A C representable type name for #G_TYPE_STRING. - */ - - -/** - * G_PARAM_SPEC_UINT: - * @pspec: a valid #GParamSpec instance - * - * Cast a #GParamSpec instance into a #GParamSpecUInt. - */ - - -/** - * GPollFunc: - * @ufds: an array of #GPollFD elements - * @nfsd: the number of elements in @ufds - * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout. + * G_DEFINE_DYNAMIC_TYPE_EXTENDED: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @TYPE_PARENT: The #GType of the parent type. + * @flags: #GTypeFlags to pass to g_type_module_register_type() + * @CODE: Custom code that gets inserted in the *_get_type() function. * - * Specifies the type of function passed to g_main_context_set_poll_func(). - * The semantics of the function should match those of the poll() system call. - * reported, or -1 if an error occurred. + * A more general version of G_DEFINE_DYNAMIC_TYPE() which + * allows to specify #GTypeFlags and custom code. + * |[ + * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, + * gtk_gadget, + * GTK_TYPE_THING, + * 0, + * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, + * gtk_gadget_gizmo_init)); + * ]| + * expands to + * |[ + * static void gtk_gadget_init (GtkGadget *self); + * static void gtk_gadget_class_init (GtkGadgetClass *klass); + * static void gtk_gadget_class_finalize (GtkGadgetClass *klass); + * static gpointer gtk_gadget_parent_class = NULL; + * static GType gtk_gadget_type_id = 0; + * static void gtk_gadget_class_intern_init (gpointer klass) + * { + * gtk_gadget_parent_class = g_type_class_peek_parent (klass); + * gtk_gadget_class_init ((GtkGadgetClass*) klass); + * } + * GType + * gtk_gadget_get_type (void) + * { + * return gtk_gadget_type_id; + * } + * static void + * gtk_gadget_register_type (GTypeModule *type_module) + * { + * const GTypeInfo g_define_type_info = { + * sizeof (GtkGadgetClass), + * (GBaseInitFunc) NULL, + * (GBaseFinalizeFunc) NULL, + * (GClassInitFunc) gtk_gadget_class_intern_init, + * (GClassFinalizeFunc) gtk_gadget_class_finalize, + * NULL, // class_data + * sizeof (GtkGadget), + * 0, // n_preallocs + * (GInstanceInitFunc) gtk_gadget_init, + * NULL // value_table + * }; + * gtk_gadget_type_id = g_type_module_register_type (type_module, + * GTK_TYPE_THING, + * GtkGadget, + * &g_define_type_info, + * (GTypeFlags) flags); + * { + * const GInterfaceInfo g_implement_interface_info = { + * (GInterfaceInitFunc) gtk_gadget_gizmo_init + * }; + * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); + * } + * } + * ]| * - * Returns: the number of #GPollFD elements which have events or errors + * Since: 2.14 */ /** - * G_IS_PARAM_SPEC_FLOAT: - * @pspec: a valid #GParamSpec instance + * G_DEFINE_INTERFACE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. + * A convenience macro for #GTypeInterface definitions, which declares + * a default vtable initialization function and defines a *_get_type() + * function. + * The macro expects the interface initialization function to have the + * name <literal>t_n ## _default_init</literal>, and the interface + * structure to have the name <literal>TN ## Interface</literal>. * - * Returns: %TRUE on success. + * Since: 2.24 */ /** - * G_DEFINE_ABSTRACT_TYPE: + * G_DEFINE_INTERFACE_WITH_CODE: * @TN: The name of the new type, in Camel case. * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. + * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * A convenience macro for type implementations. - * Similar to G_DEFINE_TYPE(), but defines an abstract type. - * See G_DEFINE_TYPE_EXTENDED() for an example. + * A convenience macro for #GTypeInterface definitions. Similar to + * G_DEFINE_INTERFACE(), but allows you to insert custom code into the + * *_get_type() function, e.g. additional interface implementations + * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See + * G_DEFINE_TYPE_EXTENDED() for a similar example using + * G_DEFINE_TYPE_WITH_CODE(). * - * Since: 2.4 + * Since: 2.24 */ /** - * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO: + * G_DEFINE_POINTER_TYPE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. * - * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:". - */ - - -/** - * G_TYPE_PARAM_FLAGS: + * A convenience macro for pointer type implementations, which defines a + * type_name_get_type() function registering the pointer type. * - * The #GType of #GParamSpecFlags. + * Since: 2.26 */ /** - * g_binding_get_flags: - * @binding: a #GBinding + * G_DEFINE_POINTER_TYPE_WITH_CODE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Retrieves the flags passed when constructing the #GBinding + * A convenience macro for pointer type implementations. + * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the + * type_name_get_type() function. * - * Returns: the #GBindingFlags used by the #GBinding * Since: 2.26 */ /** - * g_param_spec_gtype: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @is_a_type: a #GType whose subtypes are allowed as values of the property (use %G_TYPE_NONE for any type) - * @flags: flags for the property specified - * - * Creates a new #GParamSpecGType instance specifying a - * %G_TYPE_GTYPE property. - * See g_param_spec_internal() for details on property names. + * G_DEFINE_TYPE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. * - * Since: 2.10 - * Returns: a newly created parameter specification - */ - - -/** - * G_TYPE_PARAM_UCHAR: + * A convenience macro for type implementations, which declares a + * class initialization function, an instance initialization function (see #GTypeInfo for information about + * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines + * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example. * - * The #GType of #GParamSpecUChar. + * Since: 2.4 */ /** - * g_signal_new_class_handler: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_handler: a #GCallback which acts as class implementation of this signal. Used to invoke a class method generically. Pass %NULL to not associate a class method with this signal. - * @accumulator: the accumulator for this signal; may be %NULL. - * @accu_data: user data for the @accumulator. - * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. - * @n_params: the number of parameter types to follow. - * @...: a list of types, one for each parameter. + * G_DEFINE_TYPE_EXTENDED: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. + * @_f_: #GTypeFlags to pass to g_type_register_static() + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Creates a new signal. (This is usually done in the class initializer.) - * This is a variant of g_signal_new() that takes a C callback instead - * off a class offset for the signal's class handler. This function - * doesn't need a function pointer exposed in the class structure of - * an object definition, instead the function pointer is passed - * directly and can be overriden by derived classes with - * g_signal_override_class_closure() or - * g_signal_override_class_handler()and chained to with - * g_signal_chain_from_overridden() or - * g_signal_chain_from_overridden_handler(). - * See g_signal_new() for information about signal names. + * The most general convenience macro for type implementations, on which + * G_DEFINE_TYPE(), etc are based. + * |[ + * G_DEFINE_TYPE_EXTENDED (GtkGadget, + * gtk_gadget, + * GTK_TYPE_WIDGET, + * 0, + * G_IMPLEMENT_INTERFACE (TYPE_GIZMO, + * gtk_gadget_gizmo_init)); + * ]| + * expands to + * |[ + * static void gtk_gadget_init (GtkGadget *self); + * static void gtk_gadget_class_init (GtkGadgetClass *klass); + * static gpointer gtk_gadget_parent_class = NULL; + * static void gtk_gadget_class_intern_init (gpointer klass) + * { + * gtk_gadget_parent_class = g_type_class_peek_parent (klass); + * gtk_gadget_class_init ((GtkGadgetClass*) klass); + * } + * GType + * gtk_gadget_get_type (void) + * { + * static volatile gsize g_define_type_id__volatile = 0; + * if (g_once_init_enter (&g_define_type_id__volatile)) + * { + * GType g_define_type_id = + * g_type_register_static_simple (GTK_TYPE_WIDGET, + * g_intern_static_string ("GtkGadget"), + * sizeof (GtkGadgetClass), + * (GClassInitFunc) gtk_gadget_class_intern_init, + * sizeof (GtkGadget), + * (GInstanceInitFunc) gtk_gadget_init, + * (GTypeFlags) flags); + * { + * static const GInterfaceInfo g_implement_interface_info = { + * (GInterfaceInitFunc) gtk_gadget_gizmo_init + * }; + * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); + * } + * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); + * } + * return g_define_type_id__volatile; + * } + * ]| + * The only pieces which have to be manually provided are the definitions of + * the instance and class structure and the definitions of the instance and + * class init functions. * - * Returns: the signal id - * Since: 2.18 + * Since: 2.4 */ /** - * G_PARAM_SPEC_FLOAT: - * @pspec: a valid #GParamSpec instance + * G_DEFINE_TYPE_WITH_CODE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Cast a #GParamSpec instance into a #GParamSpecFloat. + * A convenience macro for type implementations. + * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the + * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). + * See G_DEFINE_TYPE_EXTENDED() for an example. + * + * Since: 2.4 */ /** - * G_IS_INITIALLY_UNOWNED: - * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. + * G_ENUM_CLASS: + * @class: a valid #GEnumClass * - * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. + * Casts a derived #GEnumClass structure into a #GEnumClass structure. */ /** - * g_param_value_validate: - * @pspec: a valid #GParamSpec - * @value: a #GValue of correct type for @pspec + * G_ENUM_CLASS_TYPE: + * @class: a #GEnumClass * - * Ensures that the contents of @value comply with the specifications - * set out by @pspec. For example, a #GParamSpecInt might require - * that integers stored in @value may not be smaller than -42 and not be - * greater than +42. If @value contains an integer outside of this range, - * it is modified accordingly, so the resulting value will fit into the - * range -42 .. +42. + * Get the type identifier from a given #GEnumClass structure. * - * Returns: whether modifying @value was necessary to ensure validity + * Returns: the #GType */ /** - * g_signal_handlers_unblock_matched: - * @instance: The instance to unblock handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. - * @signal_id: Signal the handlers have to be connected to. - * @detail: Signal detail the handlers have to be connected to. - * @closure: The closure the handlers will invoke. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * G_ENUM_CLASS_TYPE_NAME: + * @class: a #GEnumClass * - * Unblocks all handlers on an instance that match a certain selection - * criteria. The criteria mask is passed as an OR-ed combination of - * #GSignalMatchType flags, and the criteria values are passed as arguments. - * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC - * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. - * If no handlers were found, 0 is returned, the number of unblocked handlers - * otherwise. The match criteria should not apply to any handlers that are - * not currently blocked. + * Get the static type name from a given #GEnumClass structure. * - * Returns: The number of handlers that matched. + * Returns: the type name. */ /** - * g_signal_handler_find: - * @instance: The instance owning the signal handler to be found. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. - * @signal_id: Signal the handler has to be connected to. - * @detail: Signal detail the handler has to be connected to. - * @closure: The closure the handler will invoke. - * @func: The C closure callback of the handler (useless for non-C closures). - * @data: The closure data of the handler's closure. - * - * Finds the first signal handler that matches certain selection criteria. - * The criteria mask is passed as an OR-ed combination of #GSignalMatchType - * flags, and the criteria values are passed as arguments. - * The match @mask has to be non-0 for successful matches. - * If no handler was found, 0 is returned. + * G_FLAGS_CLASS: + * @class: a valid #GFlagsClass * - * Returns: A valid non-0 signal handler id for a successful match. + * Casts a derived #GFlagsClass structure into a #GFlagsClass structure. */ /** - * G_TYPE_INITIALLY_UNOWNED: + * G_FLAGS_CLASS_TYPE: + * @class: a #GFlagsClass * - * The type for #GInitiallyUnowned. + * Get the type identifier from a given #GFlagsClass structure. + * + * Returns: the #GType */ /** - * g_value_init: - * @value: A zero-filled (uninitialized) #GValue structure. - * @g_type: Type the #GValue should hold values of. + * G_FLAGS_CLASS_TYPE_NAME: + * @class: a #GFlagsClass * - * Initializes @value with the default value of @type. + * Get the static type name from a given #GFlagsClass structure. * - * Returns: (transfer none): the #GValue structure that has been passed in + * Returns: the type name. */ /** - * G_TYPE_DATE_TIME: + * G_IMPLEMENT_INTERFACE: + * @TYPE_IFACE: The #GType of the interface to add + * @iface_init: The interface init function * - * The #GType for a boxed type holding a #GDateTime. + * A convenience macro to ease interface addition in the @_C_ section + * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). + * See G_DEFINE_TYPE_EXTENDED() for an example. + * Note that this macro can only be used together with the G_DEFINE_TYPE_* + * macros, since it depends on variable names from those macros. * - * Since: 2.26 + * Since: 2.4 */ /** - * g_object_class_list_properties: - * @oclass: a #GObjectClass - * @n_properties: (out): return location for the length of the returned array + * G_IMPLEMENT_INTERFACE_DYNAMIC: + * @TYPE_IFACE: The #GType of the interface to add + * @iface_init: The interface init function * - * Get an array of #GParamSpec* for all properties of a class. - * #GParamSpec* which should be freed after use + * A convenience macro to ease interface addition in the @_C_ section + * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() + * for an example. + * Note that this macro can only be used together with the + * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable + * names from that macro. * - * Returns: (array length=n_properties) (transfer container): an array of + * Since: 2.24 */ /** - * GParamSpecLong: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_INITIALLY_UNOWNED: + * @object: Object which is subject to casting. * - * A #GParamSpec derived structure that contains the meta data for long integer properties. + * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) + * pointer. Depending on the current debugging level, this function may invoke + * certain runtime checks to identify invalid casts. */ /** - * g_cclosure_marshal_VOID__BOXED: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GBoxed* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * G_INITIALLY_UNOWNED_CLASS: + * @class: a valid #GInitiallyUnownedClass * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>. + * Casts a derived #GInitiallyUnownedClass structure into a + * #GInitiallyUnownedClass structure. */ /** - * g_param_spec_pool_lookup: - * @pool: a #GParamSpecPool - * @param_name: the name to look for - * @owner_type: the owner to look for - * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type. + * G_INITIALLY_UNOWNED_GET_CLASS: + * @object: a #GInitiallyUnowned instance. * - * Looks up a #GParamSpec in the pool. - * matching #GParamSpec was found. + * Get the class structure associated to a #GInitiallyUnowned instance. * - * Returns: (transfer none): The found #GParamSpec, or %NULL if no + * Returns: pointer to object class structure. */ /** - * G_IS_INITIALLY_UNOWNED_CLASS: - * @class: a #GInitiallyUnownedClass + * G_IS_ENUM_CLASS: + * @class: a #GEnumClass * - * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type - * %G_TYPE_INITIALLY_UNOWNED or derived. + * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM + * or derived. */ /** - * g_type_check_instance: - * @instance: A valid #GTypeInstance structure. - * @Returns: #TRUE if @instance is valid, #FALSE otherwise. + * G_IS_FLAGS_CLASS: + * @class: a #GFlagsClass * - * Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() - * macro. + * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS + * or derived. */ /** - * g_closure_invalidate: - * @closure: GClosure to invalidate + * G_IS_INITIALLY_UNOWNED: + * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. * - * Sets a flag on the closure to indicate that its calling - * environment has become invalid, and thus causes any future - * invocations of g_closure_invoke() on this @closure to be - * ignored. Also, invalidation notifiers installed on the closure will - * be called at this point. Note that unless you are holding a - * reference to the closure yourself, the invalidation notifiers may - * unref the closure and cause it to be destroyed, so if you need to - * access the closure after calling g_closure_invalidate(), make sure - * that you've previously called g_closure_ref(). - * Note that g_closure_invalidate() will also be called when the - * reference count of a closure drops to zero (unless it has already - * been invalidated before). + * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. */ /** - * G_DEFINE_INTERFACE_WITH_CODE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. - * @_C_: Custom code that gets inserted in the *_get_type() function. - * - * A convenience macro for #GTypeInterface definitions. Similar to - * G_DEFINE_INTERFACE(), but allows you to insert custom code into the - * *_get_type() function, e.g. additional interface implementations - * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See - * G_DEFINE_TYPE_EXTENDED() for a similar example using - * G_DEFINE_TYPE_WITH_CODE(). + * G_IS_INITIALLY_UNOWNED_CLASS: + * @class: a #GInitiallyUnownedClass * - * Since: 2.24 + * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type + * %G_TYPE_INITIALLY_UNOWNED or derived. */ /** - * GWeakNotify: - * @data: data that was provided when the weak reference was established - * @where_the_object_was: the object being finalized + * G_IS_OBJECT: + * @object: Instance to check for being a %G_TYPE_OBJECT. * - * A #GWeakNotify function can be added to an object as a callback that gets - * triggered when the object is finalized. Since the object is already being - * finalized when the #GWeakNotify is called, there's not much you could do - * with the object, apart from e.g. using its adress as hash-index or the like. + * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. */ /** - * g_signal_query: - * @signal_id: The signal id of the signal to query information for. - * @query: A user provided structure that is filled in with constant values upon success. + * G_IS_OBJECT_CLASS: + * @class: a #GObjectClass * - * Queries the signal system for in-depth information about a - * specific signal. This function will fill in a user-provided - * structure to hold signal-specific information. If an invalid - * signal id is passed in, the @signal_id member of the #GSignalQuery - * is 0. All members filled into the #GSignalQuery structure should - * be considered constant and have to be left untouched. + * Checks whether @class "is a" valid #GObjectClass structure of type + * %G_TYPE_OBJECT or derived. */ /** - * g_signal_has_handler_pending: - * @instance: the object whose signal handlers are sought. - * @signal_id: the signal id. - * @detail: the detail. - * @may_be_blocked: whether blocked handlers should count as match. - * - * Returns whether there are any handlers connected to @instance for the - * given signal id and detail. - * One example of when you might use this is when the arguments to the - * signal are difficult to compute. A class implementor may opt to not - * emit the signal if no one is attached anyway, thus saving the cost - * of building the arguments. - * otherwise. + * G_IS_PARAM_SPEC: + * @pspec: a #GParamSpec * - * Returns: %TRUE if a handler is connected to the signal, %FALSE + * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM + * or derived. */ /** - * G_PARAM_READWRITE: + * G_IS_PARAM_SPEC_BOOLEAN: + * @pspec: a valid #GParamSpec instance * - * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. + * + * Returns: %TRUE on success. */ /** - * g_param_spec_enum: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @enum_type: a #GType derived from %G_TYPE_ENUM - * @default_value: default value for the property specified - * @flags: flags for the property specified + * G_IS_PARAM_SPEC_BOXED: + * @pspec: a valid #GParamSpec instance * - * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM - * property. - * See g_param_spec_internal() for details on property names. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. * - * Returns: a newly created parameter specification + * Returns: %TRUE on success. */ /** - * G_VALUE_HOLDS_POINTER: - * @value: a valid #GValue structure + * G_IS_PARAM_SPEC_CHAR: + * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. * * Returns: %TRUE on success. */ /** - * g_value_set_long: - * @value: a valid #GValue of type %G_TYPE_LONG - * @v_long: long integer value to be set + * G_IS_PARAM_SPEC_CLASS: + * @pclass: a #GParamSpecClass * - * Set the contents of a %G_TYPE_LONG #GValue to @v_long. + * Checks whether @pclass "is a" valid #GParamSpecClass structure of type + * %G_TYPE_PARAM or derived. */ /** - * G_VALUE_HOLDS_STRING: - * @value: a valid #GValue structure + * G_IS_PARAM_SPEC_DOUBLE: + * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GValue can hold values of type %G_TYPE_STRING. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. * * Returns: %TRUE on success. */ /** - * g_cclosure_marshal_VOID__DOUBLE: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gdouble parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * G_IS_PARAM_SPEC_ENUM: + * @pspec: a valid #GParamSpec instance * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>. - */ - - -/** - * g_object_set_valist: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to set - * @var_args: value for the first property, followed optionally by more name/value pairs, followed by %NULL + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. * - * Sets properties on an object. + * Returns: %TRUE on success. */ /** - * G_TYPE_UINT64: + * G_IS_PARAM_SPEC_FLAGS: + * @pspec: a valid #GParamSpec instance * - * The fundamental type corresponding to #guint64. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. + * + * Returns: %TRUE on success. */ /** - * G_FLAGS_CLASS_TYPE_NAME: - * @class: a #GFlagsClass + * G_IS_PARAM_SPEC_FLOAT: + * @pspec: a valid #GParamSpec instance * - * Get the static type name from a given #GFlagsClass structure. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. * - * Returns: the type name. + * Returns: %TRUE on success. */ /** - * G_OPTION_ERROR: + * G_IS_PARAM_SPEC_GTYPE: + * @pspec: a #GParamSpec * - * Error domain for option parsing. Errors in this domain will - * be from the #GOptionError enumeration. See #GError for information on - * error domains. - */ - - -/** - * g_type_plugin_unuse: - * @plugin: a #GTypePlugin + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. * - * Calls the @unuse_plugin function from the #GTypePluginClass of - * the GObject type system itself. + * Since: 2.10 + * Returns: %TRUE on success. */ /** - * g_param_spec_set_qdata: - * @pspec: the #GParamSpec to set store a user data pointer - * @quark: a #GQuark, naming the user data pointer - * @data: an opaque user data pointer + * G_IS_PARAM_SPEC_INT: + * @pspec: a valid #GParamSpec instance * - * Sets an opaque, named pointer on a #GParamSpec. The name is - * specified through a #GQuark (retrieved e.g. via - * g_quark_from_static_string()), and the pointer can be gotten back - * from the @pspec with g_param_spec_get_qdata(). Setting a - * previously set user data pointer, overrides (frees) the old pointer - * set, using %NULL as pointer essentially removes the data stored. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. + * + * Returns: %TRUE on success. */ /** - * g_value_get_int: - * @value: a valid #GValue of type %G_TYPE_INT + * G_IS_PARAM_SPEC_INT64: + * @pspec: a valid #GParamSpec instance * - * Get the contents of a %G_TYPE_INT #GValue. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. * - * Returns: integer contents of @value + * Returns: %TRUE on success. */ /** - * g_type_register_fundamental: - * @type_id: A predefined type identifier. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @finfo: The #GTypeFundamentalInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. + * G_IS_PARAM_SPEC_LONG: + * @pspec: a valid #GParamSpec instance * - * Registers @type_id as the predefined identifier and @type_name as the - * name of a fundamental type. The type system uses the information - * contained in the #GTypeInfo structure pointed to by @info and the - * #GTypeFundamentalInfo structure pointed to by @finfo to manage the - * type and its instances. The value of @flags determines additional - * characteristics of the fundamental type. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. * - * Returns: The predefined type identifier. + * Returns: %TRUE on success. */ /** - * GParamSpecBoolean: - * @parent_instance: private #GParamSpec portion - * @default_value: default value for the property specified + * G_IS_PARAM_SPEC_OBJECT: + * @pspec: a valid #GParamSpec instance * - * A #GParamSpec derived structure that contains the meta data for boolean properties. - */ - - -/** - * GParamSpecUInt: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. * - * A #GParamSpec derived structure that contains the meta data for unsigned integer properties. + * Returns: %TRUE on success. */ /** - * g_param_spec_ref_sink: (skip) - * @pspec: a valid #GParamSpec + * G_IS_PARAM_SPEC_OVERRIDE: + * @pspec: a #GParamSpec * - * Convenience function to ref and sink a #GParamSpec. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. * - * Since: 2.10 - * Returns: the #GParamSpec that was passed into this function + * Since: 2.4 + * Returns: %TRUE on success. */ /** - * g_type_qname: - * @type: Type to return quark of type name for. + * G_IS_PARAM_SPEC_PARAM: + * @pspec: a valid #GParamSpec instance * - * Get the corresponding quark of the type IDs name. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. * - * Returns: The type names quark or 0. + * Returns: %TRUE on success. */ /** - * g_binding_get_target_property: - * @binding: a #GBinding + * G_IS_PARAM_SPEC_POINTER: + * @pspec: a valid #GParamSpec instance * - * Retrieves the name of the property of #GBinding:target used as the target - * of the binding + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. * - * Returns: the name of the target property - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * G_VALUE_HOLDS_ENUM: - * @value: a valid #GValue structure + * G_IS_PARAM_SPEC_STRING: + * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. * * Returns: %TRUE on success. */ /** - * g_param_spec_uint64: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * G_IS_PARAM_SPEC_UCHAR: + * @pspec: a valid #GParamSpec instance * - * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 - * property. - * See g_param_spec_internal() for details on property names. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. * - * Returns: a newly created parameter specification + * Returns: %TRUE on success. */ /** - * g_object_remove_weak_pointer: (skip) - * @object: The object that is weak referenced. - * @weak_pointer_location: (inout): The memory address of a pointer. + * G_IS_PARAM_SPEC_UINT: + * @pspec: a valid #GParamSpec instance * - * Removes a weak reference from @object that was previously added - * using g_object_add_weak_pointer(). The @weak_pointer_location has - * to match the one used with g_object_add_weak_pointer(). - */ - - -/** - * g_value_set_boolean: - * @value: a valid #GValue of type %G_TYPE_BOOLEAN - * @v_boolean: boolean value to be set + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. * - * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. + * Returns: %TRUE on success. */ /** - * g_param_spec_boxed: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @boxed_type: %G_TYPE_BOXED derived type of this property - * @flags: flags for the property specified + * G_IS_PARAM_SPEC_UINT64: + * @pspec: a valid #GParamSpec instance * - * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED - * derived property. - * See g_param_spec_internal() for details on property names. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. * - * Returns: a newly created parameter specification + * Returns: %TRUE on success. */ /** - * G_IS_PARAM_SPEC_INT: + * G_IS_PARAM_SPEC_ULONG: * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. * * Returns: %TRUE on success. */ /** - * g_value_get_enum: - * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM + * G_IS_PARAM_SPEC_UNICHAR: + * @pspec: a valid #GParamSpec instance * - * Get the contents of a %G_TYPE_ENUM #GValue. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. * - * Returns: enum contents of @value + * Returns: %TRUE on success. */ /** - * g_signal_connect_data: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. - * @destroy_data: a #GClosureNotify for @data. - * @connect_flags: a combination of #GConnectFlags. + * G_IS_PARAM_SPEC_VALUE_ARRAY: + * @pspec: a valid #GParamSpec instance * - * Connects a #GCallback function to a signal for a particular object. Similar - * to g_signal_connect(), but allows to provide a #GClosureNotify for the data - * which will be called when the signal handler is disconnected and no longer - * used. Specify @connect_flags if you need <literal>..._after()</literal> or - * <literal>..._swapped()</literal> variants of this function. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. * - * Returns: the handler id + * Returns: %TRUE on success. */ /** - * GBinding: + * G_IS_PARAM_SPEC_VARIANT: + * @pspec: a #GParamSpec * - * <structname>GBinding</structname> is an opaque structure whose members - * cannot be accessed directly. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. * + * Returns: %TRUE on success * Since: 2.26 */ /** - * g_param_spec_pointer: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @flags: flags for the property specified + * G_IS_VALUE: + * @value: A #GValue structure. * - * Creates a new #GParamSpecPoiner instance specifying a pointer property. - * See g_param_spec_internal() for details on property names. + * Checks if @value is a valid and initialized #GValue structure. * - * Returns: a newly created parameter specification + * Returns: %TRUE on success. */ /** - * G_PARAM_SPEC_FLAGS: - * @pspec: a valid #GParamSpec instance + * G_MARKUP_ERROR: * - * Cast a #GParamSpec instance into a #GParamSpecFlags. + * Error domain for markup parsing. + * Errors in this domain will be from the #GMarkupError enumeration. + * See #GError for information on error domains. */ /** - * g_signal_connect_after: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. - * - * Connects a #GCallback function to a signal for a particular object. - * The handler will be called after the default handler of the signal. + * G_NODE_IS_LEAF: + * @node: a #GNode * - * Returns: the handler id - */ - - -/** - * g_value_set_char: - * @value: a valid #GValue of type %G_TYPE_CHAR - * @v_char: character value to be set + * Returns %TRUE if a #GNode is a leaf node. + * (i.e. it has no children) * - * Set the contents of a %G_TYPE_CHAR #GValue to @v_char. + * Returns: %TRUE if the #GNode is a leaf node */ /** - * GRegexError: - * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed. - * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed. - * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string. - * @G_REGEX_ERROR_MATCH: The match process failed. - * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16 - * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16 - * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16 - * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16 - * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16 - * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16 - * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16 - * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16 - * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16 - * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16 - * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16 - * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16 - * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16 - * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16 - * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16 - * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16 - * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16 - * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16 - * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16 - * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16 - * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16 - * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16 - * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16 - * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16 - * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16 - * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16 - * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16 - * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16 - * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16 - * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16 - * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16 - * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16 - * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16 - * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16 - * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16 - * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16 - * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16 - * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16 + * G_NODE_IS_ROOT: + * @node: a #GNode * - * Error codes returned by regular expressions functions. + * Returns %TRUE if a #GNode is the root of a tree. + * (i.e. it has no parent or siblings) * - * Since: 2.14 + * Returns: %TRUE if the #GNode is the root of a tree */ /** - * G_BOOKMARK_FILE_ERROR: + * G_OBJECT: + * @object: Object which is subject to casting. * - * Error domain for bookmark file parsing. - * Errors in this domain will be from the #GBookmarkFileError - * enumeration. See #GError for information on error domains. + * Casts a #GObject or derived pointer into a (GObject*) pointer. + * Depending on the current debugging level, this function may invoke + * certain runtime checks to identify invalid casts. */ /** - * GEnumClass: - * @g_type_class: the parent class - * @minimum: the smallest possible value. - * @maximum: the largest possible value. - * @n_values: the number of possible values. - * @values: an array of #GEnumValue structs describing the individual values. + * G_OBJECT_CLASS: + * @class: a valid #GObjectClass * - * The class of an enumeration type holds information about its - * possible values. + * Casts a derived #GObjectClass structure into a #GObjectClass structure. */ /** - * GBinding:target: + * G_OBJECT_CLASS_NAME: + * @class: a valid #GObjectClass * - * The #GObject that should be used as the target of the binding + * Return the name of a class structure's type. + * should not be freed. * - * Since: 2.26 + * Returns: Type name of @class. The string is owned by the type system and */ /** - * G_TYPE_FUNDAMENTAL_MAX: + * G_OBJECT_CLASS_TYPE: + * @class: a valid #GObjectClass * - * An integer constant that represents the number of identifiers reserved - * for types that are assigned at compile-time. + * Get the type id of a class structure. + * + * Returns: Type id of @class. */ /** - * GBoxedCopyFunc: - * @boxed: The boxed structure to be copied. + * G_OBJECT_GET_CLASS: + * @object: a #GObject instance. * - * This function is provided by the user and should produce a copy of the passed - * in boxed structure. + * Get the class structure associated to a #GObject instance. * - * Returns: The newly created copy of the boxed structure. + * Returns: pointer to object class structure. */ /** - * g_object_interface_install_property: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface. - * @pspec: the #GParamSpec for the new property + * G_OBJECT_TYPE: + * @object: Object to return the type id for. * - * Add a property to an interface; this is only useful for interfaces - * that are added to GObject-derived types. Adding a property to an - * interface forces all objects classes with that interface to have a - * compatible property. The compatible property could be a newly - * created #GParamSpec, but normally - * g_object_class_override_property() will be used so that the object - * class only needs to provide an implementation and inherits the - * property description, default value, bounds, and so forth from the - * interface property. - * This function is meant to be called from the interface's default - * vtable initialization function (the @class_init member of - * #GTypeInfo.) It must not be called after after @class_init has - * been called for any object types implementing this interface. + * Get the type id of an object. * - * Since: 2.4 + * Returns: Type id of @object. */ /** - * GOptionEntry: - * @long_name: The long name of an option can be used to specify it in a commandline as --<replaceable>long_name</replaceable>. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>. - * @short_name: If an option has a short name, it can be specified -<replaceable>short_name</replaceable> in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name. - * @flags: Flags from #GOptionFlags. - * @arg: The type of the option, as a #GOptionArg. - * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: <variablelist> <varlistentry> <term>%G_OPTION_ARG_NONE</term> <listitem><para>%gboolean</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_INT</term> <listitem><para>%gint</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_DOUBLE</term> <listitem><para>%gdouble</para></listitem> </varlistentry> </variablelist> If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). - * @description: the description for the option in <option>--help</option> output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). - * @arg_description: The placeholder to use for the extra argument parsed by the option in <option>--help</option> output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). + * G_OBJECT_TYPE_NAME: + * @object: Object to return the type name for. * - * A <structname>GOptionEntry</structname> defines a single option. - * To have an effect, they must be added to a #GOptionGroup with - * g_option_context_add_main_entries() or g_option_group_add_entries(). + * Get the name of an object's type. + * should not be freed. + * + * Returns: Type name of @object. The string is owned by the type system and */ /** - * g_type_class_peek_parent: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to retrieve the parent class for. - * - * This is a convenience function often needed in class initializers. - * It returns the class structure of the immediate parent type of the - * class passed in. Since derived classes hold a reference count on - * their parent classes as long as they are instantiated, the returned - * class will always exist. This function is essentially equivalent - * to: - * <programlisting> - * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); - * </programlisting> - * of @g_class. + * G_OBJECT_WARN_INVALID_PROPERTY_ID: + * @object: the #GObject on which set_property() or get_property() was called + * @property_id: the numeric id of the property + * @pspec: the #GParamSpec of the property * - * Returns: (type GObject.TypeClass) (transfer none): The parent class + * This macro should be used to emit a standard warning about unexpected + * properties in set_property() and get_property() implementations. */ /** - * G_PARAM_SPEC_CHAR: - * @pspec: a valid #GParamSpec instance + * G_OPTION_ERROR: * - * Cast a #GParamSpec instance into a #GParamSpecChar. + * Error domain for option parsing. Errors in this domain will + * be from the #GOptionError enumeration. See #GError for information on + * error domains. */ /** - * G_VALUE_HOLDS_BOOLEAN: - * @value: a valid #GValue structure + * G_OPTION_REMAINING: * - * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. + * If a long option in the main group has this name, it is not treated as a + * regular option. Instead it collects all non-option arguments which would + * otherwise be left in <literal>argv</literal>. The option must be of type + * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY + * or %G_OPTION_ARG_FILENAME_ARRAY. + * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal> + * for leftover arguments has the advantage that GOption takes care of + * necessary encoding conversions for strings or filenames. * - * Returns: %TRUE on success. + * Since: 2.6 */ /** - * g_cclosure_marshal_VOID__POINTER: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gpointer parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * G_PARAM_MASK: * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>. + * Mask containing the bits of #GParamSpec.flags which are reserved for GLib. */ /** - * G_PARAM_SPEC_UCHAR: - * @pspec: a valid #GParamSpec instance + * G_PARAM_READWRITE: * - * Cast a #GParamSpec instance into a #GParamSpecUChar. + * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. */ /** - * G_TYPE_BOOLEAN: + * G_PARAM_SPEC: + * @pspec: a valid #GParamSpec * - * The fundamental type corresponding to #gboolean. + * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into + * a #GParamSpec object. */ /** - * GValue: - * - * An opaque structure used to hold different types of values. - * to functions within a #GTypeValueTable structure, or implementations of - * the g_value_*() API. That is, code portions which implement new fundamental - * types. - * #GValue users can not make any assumptions about how data is stored - * within the 2 element @data union, and the @g_type member should - * only be accessed through the G_VALUE_TYPE() macro. + * G_PARAM_SPEC_BOOLEAN: + * @pspec: a valid #GParamSpec instance * - * The data within the structure has protected scope: it is accessible only + * Cast a #GParamSpec instance into a #GParamSpecBoolean. */ /** - * g_cclosure_marshal_VOID__STRING: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gchar* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * G_PARAM_SPEC_BOXED: + * @pspec: a valid #GParamSpec instance * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>. + * Cast a #GParamSpec instance into a #GParamSpecBoxed. */ /** - * SECTION:gtypemodul: - * @short_description: Type loading modules <varlistentry> <term>#GTypePlugin</term> <listitem><para>The abstract type loader interface.</para></listitem> </varlistentry> <varlistentry> <term>#GModule</term> <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> </varlistentry> </variablelist> - * @title: GTypeModule + * G_PARAM_SPEC_CHAR: + * @pspec: a valid #GParamSpec instance * - * #GTypeModule provides a simple implementation of the #GTypePlugin - * interface. The model of #GTypeModule is a dynamically loaded module - * which implements some number of types and interface - * implementations. When the module is loaded, it registers its types - * and interfaces using g_type_module_register_type() and - * g_type_module_add_interface(). As long as any instances of these - * types and interface implementations are in use, the module is kept - * loaded. When the types and interfaces are gone, the module may be - * unloaded. If the types and interfaces become used again, the module - * will be reloaded. Note that the last unref can not happen in module - * code, since that would lead to the caller's code being unloaded before - * g_object_unref() returns to it. - * Keeping track of whether the module should be loaded or not is done by - * using a use count - it starts at zero, and whenever it is greater than - * zero, the module is loaded. The use count is maintained internally by - * the type system, but also can be explicitly controlled by - * g_type_module_use() and g_type_module_unuse(). Typically, when loading - * a module for the first type, g_type_module_use() will be used to load - * it so that it can initialize its types. At some later point, when the - * module no longer needs to be loaded except for the type - * implementations it contains, g_type_module_unuse() is called. - * #GTypeModule does not actually provide any implementation of module - * loading and unloading. To create a particular module type you must - * derive from #GTypeModule and implement the load and unload functions - * in #GTypeModuleClass. + * Cast a #GParamSpec instance into a #GParamSpecChar. */ /** - * G_VARIANT_TYPE_SIGNATURE: + * G_PARAM_SPEC_CLASS: + * @pclass: a valid #GParamSpecClass * - * The type of a DBus type signature. These are strings of a specific - * format used as type signatures for DBus methods and messages. - * If you are not interacting with DBus, then there is no reason to make - * use of this type. If you are, then the DBus specification contains a - * precise description of valid signature strings. + * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. */ /** - * GBaseInitFunc: - * @g_class: The #GTypeClass structure to initialize. + * G_PARAM_SPEC_DOUBLE: + * @pspec: a valid #GParamSpec instance * - * A callback function used by the type system to do base initialization - * of the class structures of derived types. It is called as part of the - * initialization process of all derived classes and should reallocate - * or reset all dynamic class members copied over from the parent class. - * For example, class members (such as strings) that are not sufficiently - * handled by a plain memory copy of the parent class into the derived class - * have to be altered. See GClassInitFunc() for a discussion of the class - * intialization process. + * Cast a #GParamSpec instance into a #GParamSpecDouble. */ /** - * g_param_spec_set_qdata_full: (skip) - * @pspec: the #GParamSpec to set store a user data pointer - * @quark: a #GQuark, naming the user data pointer - * @data: an opaque user data pointer - * @destroy: function to invoke with @data as argument, when @data needs to be freed + * G_PARAM_SPEC_ENUM: + * @pspec: a valid #GParamSpec instance * - * This function works like g_param_spec_set_qdata(), but in addition, - * a <literal>void (*destroy) (gpointer)</literal> function may be - * specified which is called with @data as argument when the @pspec is - * finalized, or the data is being overwritten by a call to - * g_param_spec_set_qdata() with the same @quark. + * Cast a #GParamSpec instance into a #GParamSpecEnum. */ /** - * g_value_take_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * @variant: a #GVariant, or %NULL - * - * Set the contents of a variant #GValue to @variant, and takes over - * the ownership of the caller's reference to @variant; - * the caller doesn't have to unref it any more (i.e. the reference - * count of the variant is not increased). - * It is a programmer error to pass a floating variant to this function. - * In particular this means that callbacks in closures, and signal handlers - * for signals of return type %G_TYPE_VARIANT, must never return floating - * variants. - * If you want the #GValue to hold its own reference to @variant, use - * g_value_set_variant() instead. - * This is an internal function introduced mainly for C marshallers. + * G_PARAM_SPEC_FLAGS: + * @pspec: a valid #GParamSpec instance * - * Since: 2.26 + * Cast a #GParamSpec instance into a #GParamSpecFlags. */ /** - * G_TYPE_PARAM_VALUE_ARRAY: + * G_PARAM_SPEC_FLOAT: + * @pspec: a valid #GParamSpec instance * - * The #GType of #GParamSpecValueArray. + * Cast a #GParamSpec instance into a #GParamSpecFloat. */ /** - * G_TYPE_PTR_ARRAY: - * - * The #GType for a boxed type holding a #GPtrArray reference. + * G_PARAM_SPEC_GET_CLASS: + * @pspec: a valid #GParamSpec * - * Since: 2.22 + * Retrieves the #GParamSpecClass of a #GParamSpec. */ /** - * G_VALUE_HOLDS_DOUBLE: - * @value: a valid #GValue structure + * G_PARAM_SPEC_GTYPE: + * @pspec: a #GParamSpec * - * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. + * Casts a #GParamSpec into a #GParamSpecGType. * - * Returns: %TRUE on success. + * Since: 2.10 */ /** - * g_node_insert_data: - * @parent: the #GNode to place the new #GNode under - * @position: the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent - * @data: the data for the new #GNode - * - * Inserts a new #GNode at the given position. + * G_PARAM_SPEC_INT: + * @pspec: a valid #GParamSpec instance * - * Returns: the new #GNode + * Cast a #GParamSpec instance into a #GParamSpecInt. */ /** - * g_flags_get_first_value: - * @flags_class: a #GFlagsClass - * @value: the value - * - * Returns the first #GFlagsValue which is set in @value. - * none is set + * G_PARAM_SPEC_INT64: + * @pspec: a valid #GParamSpec instance * - * Returns: the first #GFlagsValue which is set in @value, or %NULL if + * Cast a #GParamSpec instance into a #GParamSpecInt64. */ /** - * GMainContext: + * G_PARAM_SPEC_LONG: + * @pspec: a valid #GParamSpec instance * - * The <structname>GMainContext</structname> struct is an opaque data - * type representing a set of sources to be handled in a main loop. + * Cast a #GParamSpec instance into a #GParamSpecLong. */ /** - * SECTION:gboxe: - * @short_description: A mechanism to wrap opaque C structures registered by the type system - * @see_also: #GParamSpecBoxed, g_param_spec_boxed() - * @title: Boxed Types + * G_PARAM_SPEC_OBJECT: + * @pspec: a valid #GParamSpec instance * - * GBoxed is a generic wrapper mechanism for arbitrary C structures. The only - * thing the type system needs to know about the structures is how to copy and - * free them, beyond that they are treated as opaque chunks of memory. - * Boxed types are useful for simple value-holder structures like rectangles or - * points. They can also be used for wrapping structures defined in non-GObject - * based libraries. + * Casts a #GParamSpec instance into a #GParamSpecObject. */ /** - * G_TYPE_INSTANCE_GET_INTERFACE: - * @instance: Location of the #GTypeInstance structure. - * @g_type: The #GType of the interface to be returned. - * @c_type: The C type of the interface structure. + * G_PARAM_SPEC_OVERRIDE: + * @pspec: a #GParamSpec * - * Get the interface structure for interface @g_type of a given @instance. - * This macro should only be used in type implementations. + * Casts a #GParamSpec into a #GParamSpecOverride. * - * Returns: a pointer to the interface structure + * Since: 2.4 */ /** - * g_hash_table_thaw: - * @hash_table: a #GHashTable + * G_PARAM_SPEC_PARAM: + * @pspec: a valid #GParamSpec instance * - * This function is deprecated and will be removed in the next major - * release of GLib. It does nothing. + * Casts a #GParamSpec instance into a #GParamSpecParam. */ /** - * GChildWatchFunc: - * @pid: the process id of the child process - * @status: Status information about the child process, see waitpid(2) for more information about this field - * @data: user data passed to g_child_watch_add() + * G_PARAM_SPEC_POINTER: + * @pspec: a valid #GParamSpec instance * - * The type of functions to be called when a child exists. + * Casts a #GParamSpec instance into a #GParamSpecPointer. */ /** - * GParamSpecInt64: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_PARAM_SPEC_STRING: + * @pspec: a valid #GParamSpec instance * - * A #GParamSpec derived structure that contains the meta data for 64bit integer properties. + * Casts a #GParamSpec instance into a #GParamSpecString. */ /** - * GTypeDebugFlags: - * @G_TYPE_DEBUG_NONE: Print no messages. - * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping. - * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions. - * @G_TYPE_DEBUG_MASK: Mask covering all debug flags. + * G_PARAM_SPEC_TYPE: + * @pspec: a valid #GParamSpec * - * The <type>GTypeDebugFlags</type> enumeration values can be passed to - * g_type_init_with_debug_flags() to trigger debugging messages during runtime. - * Note that the messages can also be triggered by setting the - * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of - * "objects" and "signals". + * Retrieves the #GType of this @pspec. */ /** - * g_param_value_convert: + * G_PARAM_SPEC_TYPE_NAME: * @pspec: a valid #GParamSpec - * @src_value: souce #GValue - * @dest_value: destination #GValue of correct type for @pspec - * @strict_validation: %TRUE requires @dest_value to conform to @pspec without modifications - * - * Transforms @src_value into @dest_value if possible, and then - * validates @dest_value, in order for it to conform to @pspec. If - * transformed @dest_value complied to @pspec without modifications. - * See also g_value_type_transformable(), g_value_transform() and - * g_param_value_validate(). - * %FALSE otherwise and @dest_value is left untouched. * - * Returns: %TRUE if transformation and validation were successful, + * Retrieves the #GType name of this @pspec. */ /** - * G_PARAM_SPEC_BOOLEAN: + * G_PARAM_SPEC_UCHAR: * @pspec: a valid #GParamSpec instance * - * Cast a #GParamSpec instance into a #GParamSpecBoolean. + * Cast a #GParamSpec instance into a #GParamSpecUChar. */ /** - * g_type_module_register_type: - * @module: a #GTypeModule - * @parent_type: the type for the parent class - * @type_name: name for the type - * @type_info: type information structure - * @flags: flags field providing details about the type - * - * Looks up or registers a type that is implemented with a particular - * type plugin. If a type with name @type_name was previously registered, - * the #GType identifier for the type is returned, otherwise the type - * is newly registered, and the resulting #GType identifier returned. - * When reregistering a type (typically because a module is unloaded - * then reloaded, and reinitialized), @module and @parent_type must - * be the same as they were previously. - * As long as any instances of the type exist, the type plugin will - * not be unloaded. + * G_PARAM_SPEC_UINT: + * @pspec: a valid #GParamSpec instance * - * Returns: the new or existing type ID + * Cast a #GParamSpec instance into a #GParamSpecUInt. */ /** - * G_IS_PARAM_SPEC_OVERRIDE: - * @pspec: a #GParamSpec - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. + * G_PARAM_SPEC_UINT64: + * @pspec: a valid #GParamSpec instance * - * Since: 2.4 - * Returns: %TRUE on success. + * Cast a #GParamSpec instance into a #GParamSpecUInt64. */ /** - * G_IS_PARAM_SPEC_STRING: + * G_PARAM_SPEC_ULONG: * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. - * - * Returns: %TRUE on success. + * Cast a #GParamSpec instance into a #GParamSpecULong. */ /** - * g_value_get_pointer: - * @value: a valid #GValue of %G_TYPE_POINTER - * - * Get the contents of a pointer #GValue. + * G_PARAM_SPEC_UNICHAR: + * @pspec: a valid #GParamSpec instance * - * Returns: (transfer none): pointer contents of @value + * Cast a #GParamSpec instance into a #GParamSpecUnichar. */ /** - * g_object_class_find_property: - * @oclass: a #GObjectClass - * @property_name: the name of the property to look up - * - * Looks up the #GParamSpec for a property of a class. - * %NULL if the class doesn't have a property of that name + * G_PARAM_SPEC_VALUE_ARRAY: + * @pspec: a valid #GParamSpec instance * - * Returns: (transfer none): the #GParamSpec for the property, or + * Cast a #GParamSpec instance into a #GParamSpecValueArray. */ /** - * g_value_take_param: (skip) - * @value: a valid #GValue of type %G_TYPE_PARAM - * @param: the #GParamSpec to be set - * - * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes - * over the ownership of the callers reference to @param; the caller - * doesn't have to unref it any more. + * G_PARAM_SPEC_VALUE_TYPE: + * @pspec: a valid #GParamSpec * - * Since: 2.4 + * Retrieves the #GType to initialize a #GValue for this parameter. */ /** - * g_closure_new_simple: - * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> - * @data: data to store in the @data field of the newly allocated #GClosure + * G_PARAM_SPEC_VARIANT: + * @pspec: a #GParamSpec * - * Allocates a struct of the given size and initializes the initial - * part as a #GClosure. This function is mainly useful when - * implementing new types of closures. - * |[ - * typedef struct _MyClosure MyClosure; - * struct _MyClosure - * { - * GClosure closure; - * // extra data goes here - * }; - * static void - * my_closure_finalize (gpointer notify_data, - * GClosure *closure) - * { - * MyClosure *my_closure = (MyClosure *)closure; - * // free extra data here - * } - * MyClosure *my_closure_new (gpointer data) - * { - * GClosure *closure; - * MyClosure *my_closure; - * closure = g_closure_new_simple (sizeof (MyClosure), data); - * my_closure = (MyClosure *) closure; - * // initialize extra data here - * g_closure_add_finalize_notifier (closure, notify_data, - * my_closure_finalize); - * return my_closure; - * } - * ]| + * Casts a #GParamSpec into a #GParamSpecVariant. * - * Returns: (transfer full): a newly allocated #GClosure + * Since: 2.26 */ /** - * GTypeModule: - * @name: the name of the module + * G_PARAM_STATIC_STRINGS: * - * The members of the <structname>GTypeModule</structname> structure should not - * be accessed directly, except for the @name field. + * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. + * Since 2.13.0 */ /** - * g_closure_ref: - * @closure: #GClosure to increment the reference count on - * - * Increments the reference count on a closure to force it staying - * alive while the caller holds a pointer to it. + * G_PARAM_USER_SHIFT: * - * Returns: (transfer none): The @closure passed in, for convenience + * Minimum shift count to be used for user defined flags, to be stored in + * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT. */ /** - * G_VARIANT_TYPE_UNIT: + * G_PRIORITY_DEFAULT: * - * The empty tuple type. Has only one instance. Known also as "triv" - * or "void". + * Use this for default priority event sources. + * In GLib this priority is used when adding timeout functions + * with g_timeout_add(). In GDK this priority is used for events + * from the X server. */ /** - * SECTION:gtypeplugi: - * @short_description: An interface for dynamically loadable types - * @see_also: #GTypeModule and g_type_register_dynamic(). - * @title: GTypePlugin + * G_PRIORITY_DEFAULT_IDLE: * - * The GObject type system supports dynamic loading of types. The - * #GTypePlugin interface is used to handle the lifecycle of - * dynamically loaded types. It goes as follows: - * <orderedlist> - * <listitem><para> - * The type is initially introduced (usually upon loading the module - * the first time, or by your main application that knows what modules - * introduces what types), like this: - * |[ - * new_type_id = g_type_register_dynamic (parent_type_id, - * "TypeName", - * new_type_plugin, - * type_flags); - * ]| - * where <literal>new_type_plugin</literal> is an implementation of the - * #GTypePlugin interface. - * </para></listitem> - * <listitem><para> - * The type's implementation is referenced, e.g. through - * g_type_class_ref() or through g_type_create_instance() (this is - * being called by g_object_new()) or through one of the above done on - * a type derived from <literal>new_type_id</literal>. - * </para></listitem> - * <listitem><para> - * This causes the type system to load the type's implementation by calling - * g_type_plugin_use() and g_type_plugin_complete_type_info() on - * <literal>new_type_plugin</literal>. - * </para></listitem> - * <listitem><para> - * At some point the type's implementation isn't required anymore, e.g. after - * g_type_class_unref() or g_type_free_instance() (called when the reference - * count of an instance drops to zero). - * </para></listitem> - * <listitem><para> - * This causes the type system to throw away the information retrieved from - * g_type_plugin_complete_type_info() and then it calls - * g_type_plugin_unuse() on <literal>new_type_plugin</literal>. - * </para></listitem> - * <listitem><para> - * Things may repeat from the second step. - * </para></listitem> - * </orderedlist> - * So basically, you need to implement a #GTypePlugin type that - * carries a use_count, once use_count goes from zero to one, you need - * to load the implementation to successfully handle the upcoming - * g_type_plugin_complete_type_info() call. Later, maybe after - * succeeding use/unuse calls, once use_count drops to zero, you can - * unload the implementation again. The type system makes sure to call - * g_type_plugin_use() and g_type_plugin_complete_type_info() again - * when the type is needed again. - * #GTypeModule is an implementation of #GTypePlugin that already - * implements most of this except for the actual module loading and - * unloading. It even handles multiple registered types per module. + * Use this for default priority idle functions. + * In GLib this priority is used when adding idle functions with + * g_idle_add(). */ /** - * g_type_interfaces: - * @type: The type to list interface types for. - * @n_interfaces: (out) (allow-none): Optional #guint pointer to contain the number of interface types. - * - * Return a newly allocated and 0-terminated array of type IDs, listing the - * interface types that @type conforms to. The return value has to be - * g_free()ed after use. - * allocated and 0-terminated array of interface types. + * G_PRIORITY_HIGH: * - * Returns: (array length=n_interfaces) (transfer full): Newly + * Use this for high priority event sources. + * It is not used within GLib or GTK+. */ /** - * GOptionArgFunc: - * @option_name: The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name. - * @value: The value to be parsed. - * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() - * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks. - * - * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK - * options. - * occurred, in which case @error should be set with g_set_error() + * G_PRIORITY_HIGH_IDLE: * - * Returns: %TRUE if the option was successfully parsed, %FALSE if an error + * Use this for high priority idle functions. + * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, + * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is + * done to ensure that any pending resizes are processed before any + * pending redraws, so that widgets are not redrawn twice unnecessarily.) */ /** - * g_binding_get_target: - * @binding: a #GBinding - * - * Retrieves the #GObject instance used as the target of the binding + * G_PRIORITY_LOW: * - * Returns: (transfer none): the target #GObject - * Since: 2.26 + * Use this for very low priority background tasks. + * It is not used within GLib or GTK+. */ /** - * GTypePluginClass: - * @use_plugin: Increases the use count of the plugin. - * @unuse_plugin: Decreases the use count of the plugin. - * @complete_type_info: Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. - * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. + * G_REGEX_ERROR: * - * The #GTypePlugin interface is used by the type system in order to handle - * the lifecycle of dynamically loaded types. + * Error domain for regular expressions. Errors in this domain will be + * from the #GRegexError enumeration. See #GError for information on + * error domains. + * + * Since: 2.14 */ /** - * G_PARAM_SPEC_VALUE_TYPE: - * @pspec: a valid #GParamSpec + * G_SIGNAL_FLAGS_MASK: * - * Retrieves the #GType to initialize a #GValue for this parameter. + * A mask for all #GSignalFlags bits. */ /** - * GTypeInstance: + * G_SIGNAL_MATCH_MASK: * - * An opaque structure used as the base of all type instances. + * A mask for all #GSignalMatchType bits. */ /** - * G_TYPE_GTYPE: + * G_SIGNAL_TYPE_STATIC_SCOPE: * - * The type for #GType. + * This macro flags signal argument types for which the signal system may + * assume that instances thereof remain persistent across all signal emissions + * they are used in. This is only useful for non ref-counted, value-copy types. + * To flag a signal argument in this way, add + * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument + * of g_signal_new(). + * |[ + * g_signal_new ("size_request", + * G_TYPE_FROM_CLASS (gobject_class), + * G_SIGNAL_RUN_FIRST, + * G_STRUCT_OFFSET (GtkWidgetClass, size_request), + * NULL, NULL, + * _gtk_marshal_VOID__BOXED, + * G_TYPE_NONE, 1, + * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); + * ]| */ /** - * g_boxed_type_register_static: - * @name: Name of the new boxed type. - * @boxed_copy: Boxed structure copy function. - * @boxed_free: Boxed structure free function. + * G_TIME_SPAN_DAY: * - * This function creates a new %G_TYPE_BOXED derived type id for a new - * boxed type with name @name. Boxed type handling functions have to be - * provided to copy and free opaque boxed structures of this type. + * Evaluates to a time span of one day. * - * Returns: New %G_TYPE_BOXED derived type id for @name. + * Since: 2.26 */ @@ -3528,2454 +3201,1532 @@ /** - * G_VARIANT_TYPE: - * @type_string: a well-formed #GVariantType type string - * - * Converts a string to a const #GVariantType. Depending on the - * current debugging level, this function may perform a runtime check - * to ensure that @string is a valid GVariant type string. - * It is always a programmer error to use this macro with an invalid - * type string. - * Since 2.24 - */ - - -/** - * G_TYPE_STRV: - * - * The #GType for a boxed type holding a %NULL-terminated array of strings. - * The code fragments in the following example show the use of a property of - * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set() - * and g_object_get(). - * |[ - * g_object_class_install_property (object_class, - * PROP_AUTHORS, - * g_param_spec_boxed ("authors", - * _("Authors"), - * _("List of authors"), - * G_TYPE_STRV, - * G_PARAM_READWRITE)); - * gchar *authors[] = { "Owen", "Tim", NULL }; - * g_object_set (obj, "authors", authors, NULL); - * gchar *writers[]; - * g_object_get (obj, "authors", &writers, NULL); - * // do something with writers - * g_strfreev (writers); - * ]| - * - * Since: 2.4 - */ - - -/** - * G_TYPE_REGEX: - * - * The #GType for a boxed type holding a #GRegex reference. + * G_TIME_SPAN_MILLISECOND: * - * Since: 2.14 - */ - - -/** - * g_object_set_property: - * @object: a #GObject - * @property_name: the name of the property to set - * @value: the value + * Evaluates to a time span of one millisecond. * - * Sets a property on an object. + * Since: 2.26 */ /** - * GTypeFundamentalFlags: - * @G_TYPE_FLAG_CLASSED: Indicates a classed type. - * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed). - * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type. - * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable). + * G_TIME_SPAN_MINUTE: * - * Bit masks used to check or determine specific characteristics of a - * fundamental type. - */ - - -/** - * g_signal_emit: - * @instance: the instance the signal is being emitted on. - * @signal_id: the signal id - * @detail: the detail - * @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * Evaluates to a time span of one minute. * - * Emits a signal. - * Note that g_signal_emit() resets the return value to the default - * if no handlers are connected, in contrast to g_signal_emitv(). + * Since: 2.26 */ /** - * g_value_get_uchar: - * @value: a valid #GValue of type %G_TYPE_UCHAR + * G_TIME_SPAN_SECOND: * - * Get the contents of a %G_TYPE_UCHAR #GValue. + * Evaluates to a time span of one second. * - * Returns: unsigned character contents of @value + * Since: 2.26 */ /** - * g_param_spec_pool_list: - * @pool: a #GParamSpecPool - * @owner_type: the owner to look for - * @n_pspecs_p: (out): return location for the length of the returned array + * G_TYPE_ARRAY: * - * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in - * the pool. - * allocated array containing pointers to all #GParamSpecs - * owned by @owner_type in the pool + * The #GType for a boxed type holding a #GArray reference. * - * Returns: (array length=n_pspecs_p) (transfer container): a newly + * Since: 2.22 */ /** - * g_closure_set_meta_marshal: (skip) - * @closure: a #GClosure - * @marshal_data: context-dependent data to pass to @meta_marshal - * @meta_marshal: a #GClosureMarshal function + * G_TYPE_BOOLEAN: * - * Sets the meta marshaller of @closure. A meta marshaller wraps - * fashion. The most common use of this facility is for C callbacks. - * The same marshallers (generated by <link - * linkend="glib-genmarshal">glib-genmarshal</link>) are used - * everywhere, but the way that we get the callback function - * differs. In most cases we want to use @closure->callback, but in - * other cases we want to use some different technique to retrieve the - * callback function. - * For example, class closures for signals (see - * g_signal_type_cclosure_new()) retrieve the callback function from a - * fixed offset in the class structure. The meta marshaller retrieves - * the right callback and passes it to the marshaller as the + * The fundamental type corresponding to #gboolean. */ /** - * G_TYPE_INT64: + * G_TYPE_BOXED: * - * The fundamental type corresponding to #gint64. + * The fundamental type from which all boxed types are derived. */ /** - * G_TIME_SPAN_MILLISECOND: + * G_TYPE_BYTE_ARRAY: * - * Evaluates to a time span of one millisecond. + * The #GType for a boxed type holding a #GByteArray reference. * - * Since: 2.26 + * Since: 2.22 */ /** - * G_TYPE_CLOSURE: + * G_TYPE_CHAR: * - * The #GType for #GClosure. + * The fundamental type corresponding to #gchar. + * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer. + * This may or may not be the same type a the C type "gchar". */ /** - * GParamSpecULong: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_TYPE_CHECK_CLASS_CAST: + * @g_class: Location of a #GTypeClass structure. + * @g_type: The type to be returned. + * @c_type: The corresponding C type of class structure of @g_type. * - * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. + * Checks that @g_class is a class structure of the type identified by @g_type + * and issues a warning if this is not the case. Returns @g_class casted + * to a pointer to @c_type. + * This macro should only be used in type implementations. */ /** - * G_PARAM_SPEC_ULONG: - * @pspec: a valid #GParamSpec instance + * G_TYPE_CHECK_CLASS_TYPE: + * @g_class: Location of a #GTypeClass structure. + * @g_type: The type to be checked. * - * Cast a #GParamSpec instance into a #GParamSpecULong. + * Checks if @g_class is a class structure of the type identified by + * This macro should only be used in type implementations. + * + * Returns: %TRUE on success. */ /** - * G_PARAM_SPEC_VARIANT: - * @pspec: a #GParamSpec + * G_TYPE_CHECK_INSTANCE: + * @instance: Location of a #GTypeInstance structure. * - * Casts a #GParamSpec into a #GParamSpecVariant. + * Checks if @instance is a valid #GTypeInstance structure, + * otherwise issues a warning and returns %FALSE. + * This macro should only be used in type implementations. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * SECTION:gtyp: - * @short_description: The GLib Runtime type identification and management system - * - * The GType API is the foundation of the GObject system. It provides the - * facilities for registering and managing all fundamental data types, - * user-defined object and interface types. Before using any GType - * or GObject functions, g_type_init() must be called to initialize the - * type system. - * For type creation and registration purposes, all types fall into one of - * unloaded at run-time as dynamic types may be. Static types are created - * with g_type_register_static() that gets type specific information passed - * in via a #GTypeInfo structure. - * Dynamic types are created with g_type_register_dynamic() which takes a - * #GTypePlugin structure instead. The remaining type information (the - * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin - * and the g_type_plugin_*() API. - * These registration functions are usually called only once from a - * function whose only purpose is to return the type identifier for a - * specific class. Once the type (or class or interface) is registered, - * it may be instantiated, inherited, or implemented depending on exactly - * what sort of type it is. - * There is also a third registration function for registering fundamental - * types called g_type_register_fundamental() which requires both a #GTypeInfo - * structure and a #GTypeFundamentalInfo structure but it is seldom used - * since most fundamental types are predefined rather than user-defined. - * A final word about type names. - * Such an identifier needs to be at least three characters long. There is no - * upper length limit. The first character needs to be a letter (a-z or A-Z) - * or an underscore '_'. Subsequent characters can be letters, numbers or - * any of '-_+'. + * G_TYPE_CHECK_INSTANCE_CAST: + * @instance: Location of a #GTypeInstance structure. + * @g_type: The type to be returned. + * @c_type: The corresponding C type of @g_type. * - * Two categories: static or dynamic. Static types are never loaded or + * Checks that @instance is an instance of the type identified by @g_type + * and issues a warning if this is not the case. Returns @instance casted + * to a pointer to @c_type. + * This macro should only be used in type implementations. */ /** - * G_VALUE_HOLDS_INT64: - * @value: a valid #GValue structure + * G_TYPE_CHECK_INSTANCE_TYPE: + * @instance: Location of a #GTypeInstance structure. + * @g_type: The type to be checked * - * Checks whether the given #GValue can hold values of type %G_TYPE_INT64. + * Checks if @instance is an instance of the type identified by @g_type. + * This macro should only be used in type implementations. * * Returns: %TRUE on success. */ /** - * GTypeInterface: + * G_TYPE_CHECK_VALUE: + * @value: a #GValue * - * An opaque structure used as the base of all interface types. - */ - - -/** - * g_signal_handler_block: - * @instance: The instance to block the signal handler of. - * @handler_id: Handler id of the handler to be blocked. + * Checks if @value has been initialized to hold values + * of a value type. + * This macro should only be used in type implementations. * - * Blocks a handler of an instance so it will not be called during any - * signal emissions unless it is unblocked again. Thus "blocking" a - * signal handler means to temporarily deactive it, a signal handler - * has to be unblocked exactly the same amount of times it has been - * blocked before to become active again. - * The @handler_id has to be a valid signal handler id, connected to a - * signal of @instance. + * Returns: %TRUE on success. */ /** - * GOptionArg: - * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags. - * @G_OPTION_ARG_STRING: The option takes a string argument. - * @G_OPTION_ARG_INT: The option takes an integer argument. - * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument. - * @G_OPTION_ARG_FILENAME: The option takes a filename as argument. - * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings. - * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings. - * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12 - * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>). Since 2.12 + * G_TYPE_CHECK_VALUE_TYPE: + * @value: a #GValue + * @g_type: The type to be checked. * - * The #GOptionArg enum values determine which type of extra argument the - * options expect to find. If an option expects an extra argument, it - * can be specified in several ways; with a short option: - * <option>-x arg</option>, with a long option: <option>--name arg</option> + * Checks if @value has been initialized to hold values + * of type @g_type. + * This macro should only be used in type implementations. * - * Or combined in a single argument: <option>--name=arg</option>. + * Returns: %TRUE on success. */ /** - * g_type_is_a: - * @type: Type to check anchestry for. - * @is_a_type: Possible anchestor of @type or interface @type could conform to. + * G_TYPE_CLASS_GET_PRIVATE: + * @klass: the class of a type deriving from @private_type. + * @g_type: the type identifying which private data to retrieve. + * @c_type: The C type for the private structure. * - * If @is_a_type is a derivable type, check whether @type is a - * descendant of @is_a_type. If @is_a_type is an interface, check - * whether @type conforms to it. + * Gets the private class structure for a particular type. + * The private structure must have been registered in the + * get_type() function with g_type_add_class_private(). + * This macro should only be used in type implementations. * - * Returns: %TRUE if @type is_a @is_a_type holds true. + * Since: 2.24 + * Returns: a pointer to the private data structure. */ /** - * g_value_set_float: - * @value: a valid #GValue of type %G_TYPE_FLOAT - * @v_float: float value to be set + * G_TYPE_CLOSURE: * - * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. + * The #GType for #GClosure. */ /** - * g_value_set_param: - * @value: a valid #GValue of type %G_TYPE_PARAM - * @param: the #GParamSpec to be set + * G_TYPE_DATE: * - * Set the contents of a %G_TYPE_PARAM #GValue to @param. + * The #GType for #GDate. */ /** - * GTypeClassCacheFunc: - * @cache_data: data that was given to the g_type_add_class_cache_func() call - * @g_class: The #GTypeClass structure which is unreferenced - * - * A callback function which is called when the reference count of a class - * drops to zero. It may use g_type_class_ref() to prevent the class from - * being freed. You should not call g_type_class_unref() from a - * #GTypeClassCacheFunc function to prevent infinite recursion, use - * g_type_class_unref_uncached() instead. - * The functions have to check the class id passed in to figure - * whether they actually want to cache the class of this type, since all - * classes are routed through the same #GTypeClassCacheFunc chain. - * called, %FALSE to continue. + * G_TYPE_DATE_TIME: * - * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being - */ - - -/** - * GPid: + * The #GType for a boxed type holding a #GDateTime. * - * A type which is used to hold a process identification. - * On UNIX, processes are identified by a process id (an integer), - * while Windows uses process handles (which are pointers). + * Since: 2.26 */ /** - * g_param_spec_uchar: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. + * G_TYPE_DOUBLE: * - * Returns: a newly created parameter specification + * The fundamental type corresponding to #gdouble. */ /** - * g_value_take_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: string to take ownership of - * - * Sets the contents of a %G_TYPE_STRING #GValue to @v_string. + * G_TYPE_ENUM: * - * Since: 2.4 + * The fundamental type from which all enumeration types are derived. */ /** - * G_DEFINE_POINTER_TYPE_WITH_CODE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @_C_: Custom code that gets inserted in the *_get_type() function. + * G_TYPE_ERROR: * - * A convenience macro for pointer type implementations. - * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the - * type_name_get_type() function. + * The #GType for a boxed type holding a #GError. * * Since: 2.26 */ /** - * g_signal_new_valist: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_closure: The closure to invoke on signal emission; may be %NULL. - * @accumulator: the accumulator for this signal; may be %NULL. - * @accu_data: user data for the @accumulator. - * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. - * @n_params: the number of parameter types in @args. - * @args: va_list of #GType, one for each parameter. - * - * Creates a new signal. (This is usually done in the class initializer.) - * See g_signal_new() for details on allowed signal names. - * - * Returns: the signal id - */ - - -/** - * GOptionGroup: - * - * A <structname>GOptionGroup</structname> struct defines the options in a single - * group. The struct has only private fields and should not be directly accessed. - * All options in a group share the same translation function. Libraries which - * need to parse commandline options are expected to provide a function for - * getting a <structname>GOptionGroup</structname> holding their options, which - * the application can then add to its #GOptionContext. - */ - - -/** - * g_type_class_peek: - * @type: Type ID of a classed type. - * - * This function is essentially the same as g_type_class_ref(), except that - * the classes reference count isn't incremented. As a consequence, this function - * may return %NULL if the class of the type passed in does not currently - * exist (hasn't been referenced before). - * structure for the given type ID or %NULL if the class does not - * currently exist. + * G_TYPE_FLAGS: * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass + * The fundamental type from which all flags types are derived. */ /** - * g_param_spec_pool_list_owned: - * @pool: a #GParamSpecPool - * @owner_type: the owner to look for - * - * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in - * the pool. - * #GList of all #GParamSpec<!-- -->s owned by @owner_type in - * the pool#GParamSpec<!-- -->s. + * G_TYPE_FLAG_RESERVED_ID_BIT: * - * Returns: (transfer container) (element-type GObject.ParamSpec): a + * A bit in the type number that's supposed to be left untouched. */ /** - * G_TYPE_INVALID: + * G_TYPE_FLOAT: * - * An invalid #GType used as error return value in some functions which return - * a #GType. + * The fundamental type corresponding to #gfloat. */ /** - * g_try_new0: - * @struct_type: the type of the elements to allocate - * @n_structs: the number of elements to allocate + * G_TYPE_FROM_CLASS: + * @g_class: Location of a valid #GTypeClass structure. * - * Attempts to allocate @n_structs elements of type @struct_type, initialized - * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts - * the program on failure. - * The returned pointer is cast to a pointer to the given type. - * The function returns %NULL when @n_structs is 0 of if an overflow occurs. + * Get the type identifier from a given @class structure. + * This macro should only be used in type implementations. * - * Since: 2.8 - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type + * Returns: the #GType */ /** - * g_binding_get_source_property: - * @binding: a #GBinding + * G_TYPE_FROM_INSTANCE: + * @instance: Location of a valid #GTypeInstance structure. * - * Retrieves the name of the property of #GBinding:source used as the source - * of the binding + * Get the type identifier from a given @instance structure. + * This macro should only be used in type implementations. * - * Returns: the name of the source property - * Since: 2.26 + * Returns: the #GType */ /** - * g_param_spec_uint: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * G_TYPE_FROM_INTERFACE: + * @g_iface: Location of a valid #GTypeInterface structure. * - * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. - * See g_param_spec_internal() for details on property names. + * Get the type identifier from a given @interface structure. + * This macro should only be used in type implementations. * - * Returns: a newly created parameter specification + * Returns: the #GType */ /** - * SECTION:enumerations_flag: - * @short_description: Enumeration and flags types - * @title: Enumeration and Flag Types g_param_spec_flags() + * G_TYPE_FUNDAMENTAL: + * @type: A #GType value. * - * The GLib type system provides fundamental types for enumeration and - * flags types. (Flags types are like enumerations, but allow their - * values to be combined by bitwise or). A registered enumeration or - * flags type associates a name and a nickname with each allowed - * value, and the methods g_enum_get_value_by_name(), - * g_enum_get_value_by_nick(), g_flags_get_value_by_name() and - * g_flags_get_value_by_nick() can look up values by their name or - * nickname. When an enumeration or flags type is registered with the - * GLib type system, it can be used as value type for object - * properties, using g_param_spec_enum() or g_param_spec_flags(). - * GObject ships with a utility called <link - * linkend="glib-mkenums">glib-mkenums</link> that can construct - * suitable type registration functions from C enumeration - * definitions. + * The fundamental type which is the ancestor of @type. + * Fundamental types are types that serve as ultimate bases for the derived types, + * thus they are the roots of distinct inheritance hierarchies. */ /** - * GParamFlags: - * @G_PARAM_READABLE: the parameter is readable - * @G_PARAM_WRITABLE: the parameter is writable - * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction - * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction - * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required - * @G_PARAM_STATIC_NAME: the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 - * @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8 - * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 - * @G_PARAM_PRIVATE: internal - * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26 + * G_TYPE_FUNDAMENTAL_MAX: * - * Through the #GParamFlags flag values, certain aspects of parameters - * can be configured. + * An integer constant that represents the number of identifiers reserved + * for types that are assigned at compile-time. */ /** - * g_cclosure_marshal_BOOLEAN__FLAGS: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue which can store the returned #gboolean - * @n_param_values: 2 - * @param_values: a #GValue array holding instance and arg1 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * G_TYPE_FUNDAMENTAL_SHIFT: * - * A marshaller for a #GCClosure with a callback of type - * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter - * denotes a flags type. + * Shift value used in converting numbers to type IDs. */ /** - * g_type_module_register_flags: - * @module: a #GTypeModule - * @name: name for the type - * @const_static_values: an array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. - * - * Looks up or registers a flags type that is implemented with a particular - * type plugin. If a type with name @type_name was previously registered, - * the #GType identifier for the type is returned, otherwise the type - * is newly registered, and the resulting #GType identifier returned. - * As long as any instances of the type exist, the type plugin will - * not be unloaded. + * G_TYPE_GSTRING: * - * Since: 2.6 - * Returns: the new or existing type ID + * The #GType for #GString. */ /** - * G_TYPE_PARAM_OBJECT: + * G_TYPE_GTYPE: * - * The #GType of #GParamSpecObject. + * The type for #GType. */ /** - * g_enum_get_value_by_name: - * @enum_class: a #GEnumClass - * @name: the name to look up + * G_TYPE_HASH_TABLE: * - * Looks up a #GEnumValue by name. - * enumeration doesn't have a member with that name + * The #GType for a boxed type holding a #GHashTable reference. * - * Returns: the #GEnumValue with name @name, or %NULL if the + * Since: 2.10 */ /** - * g_signal_override_class_handler: - * @signal_name: the name for the signal - * @instance_type: the instance type on which to override the class handler for the signal. - * @class_handler: the handler. + * G_TYPE_HAS_VALUE_TABLE: + * @type: A #GType value. * - * Overrides the class closure (i.e. the default handler) for the - * given signal for emissions on instances of @instance_type with - * callabck @class_handler. @instance_type must be derived from the - * type to which the signal belongs. - * See g_signal_chain_from_overridden() and - * g_signal_chain_from_overridden_handler() for how to chain up to the - * parent class closure from inside the overridden one. + * Checks if @type has a #GTypeValueTable. * - * Since: 2.18 + * Returns: %TRUE on success. */ /** - * G_VARIANT_TYPE_STRING: + * G_TYPE_INITIALLY_UNOWNED: * - * The type of a string. "" is a string. %NULL is not a string. + * The type for #GInitiallyUnowned. */ /** - * g_signal_connect_closure: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @closure: the closure to connect. - * @after: whether the handler should be called before or after the default handler of the signal. + * G_TYPE_INSTANCE_GET_CLASS: + * @instance: Location of the #GTypeInstance structure. + * @g_type: The #GType of the class to be returned. + * @c_type: The C type of the class structure. * - * Connects a closure to a signal for a particular object. + * Get the class structure of a given @instance, casted + * to a specified ancestor type @g_type of the instance. + * Note that while calling a GInstanceInitFunc(), the class pointer gets + * modified, so it might not always return the expected pointer. + * This macro should only be used in type implementations. * - * Returns: the handler id + * Returns: a pointer to the class structure */ /** - * G_OPTION_REMAINING: + * G_TYPE_INSTANCE_GET_INTERFACE: + * @instance: Location of the #GTypeInstance structure. + * @g_type: The #GType of the interface to be returned. + * @c_type: The C type of the interface structure. * - * If a long option in the main group has this name, it is not treated as a - * regular option. Instead it collects all non-option arguments which would - * otherwise be left in <literal>argv</literal>. The option must be of type - * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY - * or %G_OPTION_ARG_FILENAME_ARRAY. - * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal> - * for leftover arguments has the advantage that GOption takes care of - * necessary encoding conversions for strings or filenames. + * Get the interface structure for interface @g_type of a given @instance. + * This macro should only be used in type implementations. * - * Since: 2.6 + * Returns: a pointer to the interface structure */ /** - * g_type_module_add_interface: - * @module: a #GTypeModule - * @instance_type: type to which to add the interface. - * @interface_type: interface type to add - * @interface_info: type information structure + * G_TYPE_INSTANCE_GET_PRIVATE: + * @instance: the instance of a type deriving from @private_type. + * @g_type: the type identifying which private data to retrieve. + * @c_type: The C type for the private structure. * - * Registers an additional interface for a type, whose interface lives - * in the given type plugin. If the interface was already registered - * for the type in this plugin, nothing will be done. - * As long as any instances of the type exist, the type plugin will - * not be unloaded. - */ - - -/** - * g_type_query: - * @type: the #GType value of a static, classed type. - * @query: (out caller-allocates): A user provided structure that is filled in with constant values upon success. + * Gets the private structure for a particular type. + * The private structure must have been registered in the + * class_init function with g_type_class_add_private(). + * This macro should only be used in type implementations. * - * Queries the type system for information about a specific type. - * This function will fill in a user-provided structure to hold - * type-specific information. If an invalid #GType is passed in, the - * #GTypeQuery structure should be considered constant and have to be - * left untouched. + * Since: 2.4 + * Returns: a pointer to the private data structure. */ /** - * GTypePluginCompleteTypeInfo: - * @plugin: the #GTypePlugin - * @g_type: the #GType whose info is completed - * @info: the #GTypeInfo struct to fill in - * @value_table: the #GTypeValueTable to fill in + * G_TYPE_INT: * - * The type of the @complete_type_info function of #GTypePluginClass. + * The fundamental type corresponding to #gint. */ /** - * g_type_register_static: - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. - * - * Registers @type_name as the name of a new static type derived from - * #GTypeInfo structure pointed to by @info to manage the type and its - * instances (if not abstract). The value of @flags determines the nature - * (e.g. abstract or not) of the type. + * G_TYPE_INT64: * - * Returns: The new type identifier. + * The fundamental type corresponding to #gint64. */ /** - * G_PARAM_SPEC_ENUM: - * @pspec: a valid #GParamSpec instance + * G_TYPE_INTERFACE: * - * Cast a #GParamSpec instance into a #GParamSpecEnum. + * The fundamental type from which all interfaces are derived. */ /** - * GSignalAccumulator: - * @ihint: Signal invocation hint, see #GSignalInvocationHint. - * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission. - * @handler_return: A #GValue holding the return value of the signal handler. - * @data: Callback data that was specified when creating the signal. - * - * The signal accumulator is a special callback function that can be used - * to collect return values of the various callbacks that are called - * during a signal emission. The signal accumulator is specified at signal - * creation time, if it is left %NULL, no accumulation of callback return - * values is performed. The return value of signal emissions is then the - * value returned by the last callback. - * should be aborted. Returning %FALSE means to abort the - * current emission and %TRUE is returned for continuation. + * G_TYPE_INVALID: * - * Returns: The accumulator function returns whether the signal emission + * An invalid #GType used as error return value in some functions which return + * a #GType. */ /** - * g_value_array_new: - * @n_prealloced: number of values to preallocate space for - * - * Allocate and initialize a new #GValueArray, optionally preserve space - * for @n_prealloced elements. New arrays always contain 0 elements, - * regardless of the value of @n_prealloced. + * G_TYPE_IO_CHANNEL: * - * Returns: a newly allocated #GValueArray with 0 values + * The #GType for #GIOChannel. */ /** - * g_value_array_remove: - * @value_array: #GValueArray to remove an element from - * @index_: position of value to remove, must be < value_array->n_values - * - * Remove the value at position @index_ from @value_array. + * G_TYPE_IO_CONDITION: * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * The #GType for #GIOCondition. */ /** - * g_object_get_qdata: - * @object: The GObject to get a stored user data pointer from - * @quark: A #GQuark, naming the user data pointer + * G_TYPE_IS_ABSTRACT: + * @type: A #GType value. * - * This function gets back user data pointers stored via - * g_object_set_qdata(). + * Checks if @type is an abstract type. An abstract type can not be + * instantiated and is normally used as an abstract base class for + * derived classes. * - * Returns: (transfer none): The user data pointer set, or %NULL + * Returns: %TRUE on success. */ /** - * GRegex: - * - * A GRegex is the "compiled" form of a regular expression pattern. This - * structure is opaque and its fields cannot be accessed directly. + * G_TYPE_IS_CLASSED: + * @type: A #GType value. * - * Since: 2.14 - */ - - -/** - * GToggleNotify: - * @data: Callback data passed to g_object_add_toggle_ref() - * @object: The object on which g_object_add_toggle_ref() was called. - * @is_last_ref: %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references. + * Checks if @type is a classed type. * - * A callback function used for notification when the state - * of a toggle reference changes. See g_object_add_toggle_ref(). + * Returns: %TRUE on success. */ /** - * g_object_watch_closure: - * @object: GObject restricting lifetime of @closure - * @closure: GClosure to watch + * G_TYPE_IS_DEEP_DERIVABLE: + * @type: A #GType value. * - * This function essentially limits the life time of the @closure to - * the life time of the object. That is, when the object is finalized, - * the @closure is invalidated by calling g_closure_invalidate() on - * it, in order to prevent invocations of the closure with a finalized - * (nonexisting) object. Also, g_object_ref() and g_object_unref() are - * added as marshal guards to the @closure, to ensure that an extra - * reference count is held on @object during invocation of the - * use this @object as closure data. - */ - - -/** - * g_object_weak_ref: (skip) - * @object: #GObject to reference weakly - * @notify: callback to invoke before the object is freed - * @data: extra data to pass to notify + * Checks if @type is a deep derivable type. A deep derivable type + * can be used as the base class of a deep (multi-level) class hierarchy. * - * Adds a weak reference callback to an object. Weak references are - * used for notification when an object is finalized. They are called - * "weak references" because they allow you to safely hold a pointer - * to an object without calling g_object_ref() (g_object_ref() adds a - * strong reference, that is, forces the object to stay alive). + * Returns: %TRUE on success. */ /** - * G_PRIORITY_LOW: + * G_TYPE_IS_DERIVABLE: + * @type: A #GType value. * - * Use this for very low priority background tasks. - * It is not used within GLib or GTK+. - */ - - -/** - * g_object_freeze_notify: - * @object: a #GObject + * Checks if @type is a derivable type. A derivable type can + * be used as the base class of a flat (single-level) class hierarchy. * - * Increases the freeze count on @object. If the freeze count is - * non-zero, the emission of "notify" signals on @object is - * stopped. The signals are queued until the freeze count is decreased - * to zero. - * This is necessary for accessors that modify multiple properties to prevent - * premature notification while the object is still being modified. + * Returns: %TRUE on success. */ /** - * G_TYPE_PARAM_LONG: + * G_TYPE_IS_DERIVED: + * @type: A #GType value. * - * The #GType of #GParamSpecLong. - */ - - -/** - * G_PARAM_SPEC_CLASS: - * @pclass: a valid #GParamSpecClass + * Checks if @type is derived (or in object-oriented terminology: + * inherited) from another type (this holds true for all non-fundamental + * types). * - * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. + * Returns: %TRUE on success. */ /** - * g_value_get_gtype: - * @value: a valid #GValue of type %G_TYPE_GTYPE + * G_TYPE_IS_ENUM: + * @type: a #GType ID. * - * Get the contents of a %G_TYPE_GTYPE #GValue. + * Checks whether @type "is a" %G_TYPE_ENUM. * - * Since: 2.12 - * Returns: the #GType stored in @value + * Returns: %TRUE if @type "is a" %G_TYPE_ENUM. */ /** - * g_signal_newv: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST - * @class_closure: The closure to invoke on signal emission; may be %NULL - * @accumulator: the accumulator for this signal; may be %NULL - * @accu_data: user data for the @accumulator - * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value - * @n_params: the length of @param_types - * @param_types: an array of types, one for each parameter - * - * Creates a new signal. (This is usually done in the class initializer.) - * See g_signal_new() for details on allowed signal names. + * G_TYPE_IS_FLAGS: + * @type: a #GType ID. * - * Returns: the signal id - */ - - -/** - * G_TYPE_PARAM_STRING: + * Checks whether @type "is a" %G_TYPE_FLAGS. * - * The #GType of #GParamSpecString. + * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS. */ /** - * G_TYPE_IS_ABSTRACT: + * G_TYPE_IS_FUNDAMENTAL: * @type: A #GType value. * - * Checks if @type is an abstract type. An abstract type can not be - * instantiated and is normally used as an abstract base class for - * derived classes. + * Checks if @type is a fundamental type. * * Returns: %TRUE on success. */ /** - * g_param_spec_ref: (skip) - * @pspec: a valid #GParamSpec + * G_TYPE_IS_INSTANTIATABLE: + * @type: A #GType value. * - * Increments the reference count of @pspec. + * Checks if @type can be instantiated. Instantiation is the + * process of creating an instance (object) of this type. * - * Returns: the #GParamSpec that was passed into this function + * Returns: %TRUE on success. */ /** - * g_value_get_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type + * G_TYPE_IS_INTERFACE: + * @type: A #GType value. * - * Get the contents of a %G_TYPE_BOXED derived #GValue. + * Checks if @type is an interface type. + * An interface type provides a pure API, the implementation + * of which is provided by another type (which is then said to conform + * to the interface). GLib interfaces are somewhat analogous to Java + * interfaces and C++ classes containing only pure virtual functions, + * with the difference that GType interfaces are not derivable (but see + * g_type_interface_add_prerequisite() for an alternative). * - * Returns: (transfer none): boxed contents of @value + * Returns: %TRUE on success. */ /** - * g_value_peek_pointer: - * @value: An initialized #GValue structure. + * G_TYPE_IS_OBJECT: + * @type: Type id to check * - * function asserts that g_value_fits_pointer() returned %TRUE for the - * passed in value. This is an internal function introduced mainly - * for C marshallers. + * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. * - * Returns: (transfer none): the value contents as pointer. This + * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT. */ /** - * g_main_destroy: - * @loop: a #GMainLoop - * - * Frees the memory allocated for the #GMainLoop. + * G_TYPE_IS_PARAM: + * @type: a #GType ID * - * Deprecated: 2.2: Use g_main_loop_unref() instead + * Checks whether @type "is a" %G_TYPE_PARAM. */ /** - * GTypeInterfaceCheckFunc: - * @check_data: data passed to g_type_add_interface_check(). - * @g_iface: the interface that has been initialized + * G_TYPE_IS_VALUE: + * @type: A #GType value. * - * A callback called after an interface vtable is initialized. - * See g_type_add_interface_check(). + * Checks whether the passed in type ID can be used for g_value_init(). + * That is, this macro checks whether this type provides an implementation + * of the #GTypeValueTable functions required for a type to create a #GValue of. * - * Since: 2.4 + * Returns: Whether @type is suitable as a #GValue type. */ /** - * G_TYPE_HAS_VALUE_TABLE: + * G_TYPE_IS_VALUE_ABSTRACT: * @type: A #GType value. * - * Checks if @type has a #GTypeValueTable. + * Checks if @type is an abstract value type. An abstract value type introduces + * a value table, but can't be used for g_value_init() and is normally used as + * an abstract base type for derived value types. * * Returns: %TRUE on success. */ /** - * g_type_class_peek_static: - * @type: Type ID of a classed type. - * - * A more efficient version of g_type_class_peek() which works only for - * static types. - * structure for the given type ID or %NULL if the class does not - * currently exist or is dynamically loaded. - * - * Since: 2.4 - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass - */ - - -/** - * g_signal_handler_is_connected: - * @instance: The instance where a signal handler is sought. - * @handler_id: the handler id. + * G_TYPE_IS_VALUE_TYPE: + * @type: A #GType value. * - * Returns whether @handler_id is the id of a handler connected to @instance. + * Checks if @type is a value type and can be used with g_value_init(). * - * Returns: whether @handler_id identifies a handler connected to @instance. + * Returns: %TRUE on success. */ /** - * g_param_spec_boolean: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN - * property. - * See g_param_spec_internal() for details on property names. + * G_TYPE_LONG: * - * Returns: a newly created parameter specification + * The fundamental type corresponding to #glong. */ /** - * G_DEFINE_DYNAMIC_TYPE_EXTENDED: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @TYPE_PARENT: The #GType of the parent type. - * @flags: #GTypeFlags to pass to g_type_module_register_type() - * @CODE: Custom code that gets inserted in the *_get_type() function. + * G_TYPE_MAKE_FUNDAMENTAL: + * @x: the fundamental type number. * - * A more general version of G_DEFINE_DYNAMIC_TYPE() which - * allows to specify #GTypeFlags and custom code. - * |[ - * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, - * gtk_gadget, - * GTK_TYPE_THING, - * 0, - * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, - * gtk_gadget_gizmo_init)); - * ]| - * expands to - * |[ - * static void gtk_gadget_init (GtkGadget *self); - * static void gtk_gadget_class_init (GtkGadgetClass *klass); - * static void gtk_gadget_class_finalize (GtkGadgetClass *klass); - * static gpointer gtk_gadget_parent_class = NULL; - * static GType gtk_gadget_type_id = 0; - * static void gtk_gadget_class_intern_init (gpointer klass) - * { - * gtk_gadget_parent_class = g_type_class_peek_parent (klass); - * gtk_gadget_class_init ((GtkGadgetClass*) klass); - * } - * GType - * gtk_gadget_get_type (void) - * { - * return gtk_gadget_type_id; - * } - * static void - * gtk_gadget_register_type (GTypeModule *type_module) - * { - * const GTypeInfo g_define_type_info = { - * sizeof (GtkGadgetClass), - * (GBaseInitFunc) NULL, - * (GBaseFinalizeFunc) NULL, - * (GClassInitFunc) gtk_gadget_class_intern_init, - * (GClassFinalizeFunc) gtk_gadget_class_finalize, - * NULL, // class_data - * sizeof (GtkGadget), - * 0, // n_preallocs - * (GInstanceInitFunc) gtk_gadget_init, - * NULL // value_table - * }; - * gtk_gadget_type_id = g_type_module_register_type (type_module, - * GTK_TYPE_THING, - * GtkGadget, - * &g_define_type_info, - * (GTypeFlags) flags); - * { - * const GInterfaceInfo g_implement_interface_info = { - * (GInterfaceInitFunc) gtk_gadget_gizmo_init - * }; - * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); - * } - * } - * ]| + * Get the type ID for the fundamental type number @x. + * Use g_type_fundamental_next() instead of this macro to create new fundamental + * types. * - * Since: 2.14 + * Returns: the GType */ /** - * GSignalInvocationHint: - * @signal_id: The signal id of the signal invoking the callback - * @detail: The detail passed on for this emission - * @run_type: The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. + * G_TYPE_NONE: * - * The #GSignalInvocationHint structure is used to pass on additional information - * to callbacks during a signal emission. + * A fundamental type which is used as a replacement for the C + * <literal>void</literal> return type. */ /** - * GTypeFundamentalInfo: - * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type + * G_TYPE_OBJECT: * - * A structure that provides information to the type system which is - * used specifically for managing fundamental types. + * The fundamental type for #GObject. */ /** - * g_param_value_set_default: - * @pspec: a valid #GParamSpec - * @value: a #GValue of correct type for @pspec + * G_TYPE_PARAM: * - * Sets @value to its default value as specified in @pspec. + * The fundamental type from which all #GParamSpec types are derived. */ /** - * G_TYPE_VARIANT: - * - * The fundamental type corresponding to #GVariant. - * All floating #GVariant instances passed through the #GType system are - * consumed. - * Note that callbacks in closures, and signal handlers - * for signals of return type %G_TYPE_VARIANT, must never return floating - * variants. - * with this fundamental type in 2.26. + * G_TYPE_PARAM_BOOLEAN: * - * Note: GLib 2.24 did include a boxed type with this name. It was replaced - * Since: 2.26 + * The #GType of #GParamSpecBoolean. */ /** - * G_DEFINE_TYPE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * - * A convenience macro for type implementations, which declares a - * class initialization function, an instance initialization function (see #GTypeInfo for information about - * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines - * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example. + * G_TYPE_PARAM_BOXED: * - * Since: 2.4 + * The #GType of #GParamSpecBoxed. */ /** - * g_signal_handlers_unblock_by_func: - * @instance: The instance to unblock handlers from. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. - * - * Unblocks all handlers on an instance that match @func and @data. + * G_TYPE_PARAM_CHAR: * - * Returns: The number of handlers that matched. + * The #GType of #GParamSpecChar. */ /** - * g_value_set_enum: - * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM - * @v_enum: enum value to be set + * G_TYPE_PARAM_DOUBLE: * - * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. + * The #GType of #GParamSpecDouble. */ /** - * g_param_spec_steal_qdata: - * @pspec: the #GParamSpec to get a stored user data pointer from - * @quark: a #GQuark, naming the user data pointer - * - * Gets back user data pointers stored via g_param_spec_set_qdata() - * and removes the @data from @pspec without invoking its destroy() - * function (if any was set). Usually, calling this function is only - * required to update user data pointers with a destroy notifier. + * G_TYPE_PARAM_ENUM: * - * Returns: (transfer none): the user data pointer set, or %NULL + * The #GType of #GParamSpecEnum. */ /** - * G_VARIANT_TYPE_ANY: + * G_TYPE_PARAM_FLAGS: * - * An indefinite type that is a supertype of every type (including - * itself). + * The #GType of #GParamSpecFlags. */ /** - * GInterfaceInitFunc: - * @g_iface: The interface structure to initialize. - * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. + * G_TYPE_PARAM_FLOAT: * - * A callback function used by the type system to initialize a new - * interface. This function should initialize all internal data and - * allocate any resources required by the interface. + * The #GType of #GParamSpecFloat. */ /** - * GBinding:target-property: + * G_TYPE_PARAM_GTYPE: * - * The name of the property of #GBinding:target that should be used - * as the target of the binding + * The #GType of #GParamSpecGType. * - * Since: 2.26 + * Since: 2.10 */ /** - * g_object_weak_unref: (skip) - * @object: #GObject to remove a weak reference from - * @notify: callback to search for - * @data: data to search for + * G_TYPE_PARAM_INT: * - * Removes a weak reference callback to an object. + * The #GType of #GParamSpecInt. */ /** - * g_node_append_data: - * @parent: the #GNode to place the new #GNode under - * @data: the data for the new #GNode - * - * Inserts a new #GNode as the last child of the given parent. + * G_TYPE_PARAM_INT64: * - * Returns: the new #GNode + * The #GType of #GParamSpecInt64. */ /** - * G_VARIANT_TYPE_DICTIONARY: + * G_TYPE_PARAM_LONG: * - * An indefinite type that is a supertype of every dictionary type -- - * that is, any array type that has an element type equal to any - * dictionary entry type. + * The #GType of #GParamSpecLong. */ /** - * g_type_name: - * @type: Type to return name for. - * - * Get the unique name that is assigned to a type ID. Note that this - * function (like all other GType API) cannot cope with invalid type - * IDs. %G_TYPE_INVALID may be passed to this function, as may be any - * other validly registered type ID, but randomized type IDs should - * not be passed in and will most likely lead to a crash. + * G_TYPE_PARAM_OBJECT: * - * Returns: Static type name or %NULL. + * The #GType of #GParamSpecObject. */ /** - * g_atomic_int_dec_and_test: - * @atomic: a pointer to an integer + * G_TYPE_PARAM_OVERRIDE: * - * Atomically decrements the integer pointed to by @atomic by 1. - * after decrementing it + * The #GType of #GParamSpecOverride. * - * Returns: %TRUE if the integer pointed to by @atomic is 0 * Since: 2.4 */ /** - * g_cclosure_marshal_VOID__INT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gint parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * G_TYPE_PARAM_PARAM: * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>. + * The #GType of #GParamSpecParam. */ /** - * g_value_dup_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * - * Get the contents of a variant #GValue, increasing its refcount. - * g_variant_unref() when no longer needed + * G_TYPE_PARAM_POINTER: * - * Returns: variant contents of @value, should be unrefed using - * Since: 2.26 + * The #GType of #GParamSpecPointer. */ /** - * G_TYPE_BOXED: + * G_TYPE_PARAM_STRING: * - * The fundamental type from which all boxed types are derived. + * The #GType of #GParamSpecString. */ /** - * g_value_get_long: - * @value: a valid #GValue of type %G_TYPE_LONG - * - * Get the contents of a %G_TYPE_LONG #GValue. + * G_TYPE_PARAM_UCHAR: * - * Returns: long integer contents of @value + * The #GType of #GParamSpecUChar. */ /** - * G_PARAM_SPEC_UINT64: - * @pspec: a valid #GParamSpec instance + * G_TYPE_PARAM_UINT: * - * Cast a #GParamSpec instance into a #GParamSpecUInt64. + * The #GType of #GParamSpecUInt. */ /** - * G_FLAGS_CLASS_TYPE: - * @class: a #GFlagsClass - * - * Get the type identifier from a given #GFlagsClass structure. + * G_TYPE_PARAM_UINT64: * - * Returns: the #GType + * The #GType of #GParamSpecUInt64. */ /** - * g_value_get_boolean: - * @value: a valid #GValue of type %G_TYPE_BOOLEAN - * - * Get the contents of a %G_TYPE_BOOLEAN #GValue. + * G_TYPE_PARAM_ULONG: * - * Returns: boolean contents of @value + * The #GType of #GParamSpecULong. */ /** - * g_cclosure_marshal_VOID__VARIANT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GVariant* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)</literal>. + * G_TYPE_PARAM_UNICHAR: * - * Since: 2.26 + * The #GType of #GParamSpecUnichar. */ /** - * G_PRIORITY_HIGH_IDLE: + * G_TYPE_PARAM_VALUE_ARRAY: * - * Use this for high priority idle functions. - * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, - * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is - * done to ensure that any pending resizes are processed before any - * pending redraws, so that widgets are not redrawn twice unnecessarily.) + * The #GType of #GParamSpecValueArray. */ /** - * G_TYPE_IS_DEEP_DERIVABLE: - * @type: A #GType value. + * G_TYPE_PARAM_VARIANT: * - * Checks if @type is a deep derivable type. A deep derivable type - * can be used as the base class of a deep (multi-level) class hierarchy. + * The #GType of #GParamSpecVariant. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * G_TYPE_FUNDAMENTAL_SHIFT: + * G_TYPE_POINTER: * - * Shift value used in converting numbers to type IDs. + * The fundamental type corresponding to #gpointer. */ /** - * GSignalFlags: - * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage. - * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage. - * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage. - * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted. - * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions. - * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code. - * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. + * G_TYPE_PTR_ARRAY: * - * The signal flags are used to specify a signal's behaviour, the overall - * signal description outlines how especially the RUN flags control the - * stages of a signal emission. + * The #GType for a boxed type holding a #GPtrArray reference. + * + * Since: 2.22 */ /** - * GParamSpecGType: - * @parent_instance: private #GParamSpec portion - * @is_a_type: a #GType whose subtypes can occur as values + * G_TYPE_REGEX: * - * A #GParamSpec derived structure that contains the meta data for #GType properties. + * The #GType for a boxed type holding a #GRegex reference. * - * Since: 2.10 + * Since: 2.14 */ /** - * g_value_array_prepend: - * @value_array: #GValueArray to add an element to - * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL - * - * Insert a copy of @value as first element of @value_array. If @value is - * %NULL, an uninitialized value is prepended. + * G_TYPE_RESERVED_BSE_FIRST: * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * First fundamental type number to create a new fundamental type id with + * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. */ /** - * G_TYPE_DATE: + * G_TYPE_RESERVED_BSE_LAST: * - * The #GType for #GDate. + * Last fundamental type number reserved for BSE. */ /** - * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITER: + * G_TYPE_RESERVED_GLIB_FIRST: * - * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". + * First fundamental type number to create a new fundamental type id with + * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. */ /** - * GEnumValue: - * @value: the enum value - * @value_name: the name of the value - * @value_nick: the nickname of the value + * G_TYPE_RESERVED_GLIB_LAST: * - * A structure which contains a single enum value, its name, and its - * nickname. + * Last fundamental type number reserved for GLib. */ /** - * GParamSpecFloat: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30. + * G_TYPE_RESERVED_USER_FIRST: * - * A #GParamSpec derived structure that contains the meta data for float properties. + * First available fundamental type number to create new fundamental + * type id with G_TYPE_MAKE_FUNDAMENTAL(). */ /** - * g_value_array_insert: - * @value_array: #GValueArray to add an element to - * @index_: insertion position, must be <= value_array->n_values - * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL - * - * Insert a copy of @value at specified position into @value_array. If @value - * is %NULL, an uninitialized value is inserted. + * G_TYPE_STRING: * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * The fundamental type corresponding to nul-terminated C strings. */ /** - * g_value_get_float: - * @value: a valid #GValue of type %G_TYPE_FLOAT + * G_TYPE_STRV: * - * Get the contents of a %G_TYPE_FLOAT #GValue. + * The #GType for a boxed type holding a %NULL-terminated array of strings. + * The code fragments in the following example show the use of a property of + * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set() + * and g_object_get(). + * |[ + * g_object_class_install_property (object_class, + * PROP_AUTHORS, + * g_param_spec_boxed ("authors", + * _("Authors"), + * _("List of authors"), + * G_TYPE_STRV, + * G_PARAM_READWRITE)); + * gchar *authors[] = { "Owen", "Tim", NULL }; + * g_object_set (obj, "authors", authors, NULL); + * gchar *writers[]; + * g_object_get (obj, "authors", &writers, NULL); + * // do something with writers + * g_strfreev (writers); + * ]| * - * Returns: float contents of @value + * Since: 2.4 */ /** - * SECTION:signal: - * @short_description: A means for customization of object behaviour and a general purpose notification mechanism - * @title: Signals + * G_TYPE_UCHAR: * - * The basic concept of the signal system is that of the - * <emphasis>emission</emphasis> of a signal. Signals are introduced - * per-type and are identified through strings. Signals introduced - * for a parent type are available in derived types as well, so - * basically they are a per-type facility that is inherited. A signal - * emission mainly involves invocation of a certain set of callbacks - * in precisely defined manner. There are two main categories of such - * callbacks, per-object - * <footnote><para>Although signals can deal with any kind of instantiatable - * type, i'm referring to those types as "object types" in the following, - * simply because that is the context most users will encounter signals in. - * </para></footnote> - * ones and user provided ones. - * The per-object callbacks are most often referred to as "object method - * handler" or "default (signal) handler", while user provided callbacks are - * usually just called "signal handler". - * The object method handler is provided at signal creation time (this most - * frequently happens at the end of an object class' creation), while user - * provided handlers are frequently connected and disconnected to/from a certain - * signal on certain object instances. - * A signal emission consists of five stages, unless prematurely stopped: - * <variablelist> - * <varlistentry><term></term><listitem><para> - * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - * </para></listitem></varlistentry> - * </variablelist> - * The user-provided signal handlers are called in the order they were - * connected in. - * All handlers may prematurely stop a signal emission, and any number of - * handlers may be connected, disconnected, blocked or unblocked during - * a signal emission. - * There are certain criteria for skipping user handlers in stages 2 and 4 - * of a signal emission. - * First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted - * during callback invocation, to return from the "blocked" state, a - * handler has to get unblocked exactly the same amount of times - * it has been blocked before. - * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional - * "detail" argument passed in to g_signal_emit() has to match the detail - * argument of the signal handler currently subject to invocation. - * Specification of no detail argument for signal handlers (omission of the - * detail part of the signal specification upon connection) serves as a - * wildcard and matches any detail argument passed in to emission. + * The fundamental type corresponding to #guchar. */ /** - * SECTION:value_collectio: - * @Short_description: Converting varargs to generic values - * @Title: Varargs Value Collection + * G_TYPE_UINT: * - * The macros in this section provide the varargs parsing support needed - * in variadic GObject functions such as g_object_new() or g_object_set(). - * They currently support the collection of integral types, floating point - * types and pointers. + * The fundamental type corresponding to #guint. */ /** - * G_TYPE_STRING: + * G_TYPE_UINT64: * - * The fundamental type corresponding to nul-terminated C strings. + * The fundamental type corresponding to #guint64. */ /** - * G_VARIANT_TYPE_UINT32: + * G_TYPE_ULONG: * - * The type of an integer value that can range from 0 to 4294967295. - * That's one number for everyone who was around in the late 1970s. + * The fundamental type corresponding to #gulong. */ /** - * g_type_init: + * G_TYPE_VALUE: * - * Prior to any use of the type system, g_type_init() has to be called - * to initialize the type system and assorted other code portions - * (such as the various fundamental type implementations or the signal - * system). - * Since version 2.24 this also initializes the thread system + * The type ID of the "GValue" type which is a boxed type, + * used to pass around pointers to GValues. */ /** - * g_renew: - * @struct_type: the type of the elements to allocate - * @mem: the currently allocated memory - * @n_structs: the number of elements to allocate - * - * Reallocates the memory pointed to by @mem, so that it now has space for - * the memory, which may have been moved. - * Care is taken to avoid overflow when calculating the size of the allocated block. + * G_TYPE_VALUE_ARRAY: * - * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type + * The type ID of the "GValueArray" type which is a boxed type, + * used to pass around pointers to GValueArrays. */ /** - * g_param_spec_get_qdata: - * @pspec: a valid #GParamSpec - * @quark: a #GQuark, naming the user data pointer + * G_TYPE_VARIANT: * - * Gets back user data pointers stored via g_param_spec_set_qdata(). + * The fundamental type corresponding to #GVariant. + * All floating #GVariant instances passed through the #GType system are + * consumed. + * Note that callbacks in closures, and signal handlers + * for signals of return type %G_TYPE_VARIANT, must never return floating + * variants. + * with this fundamental type in 2.26. * - * Returns: (transfer none): the user data pointer set, or %NULL + * Note: GLib 2.24 did include a boxed type with this name. It was replaced + * Since: 2.26 */ /** - * G_OBJECT_TYPE_NAME: - * @object: Object to return the type name for. + * G_TYPE_VARIANT_TYPE: * - * Get the name of an object's type. - * should not be freed. + * The #GType for a boxed type holding a #GVariantType. * - * Returns: Type name of @object. The string is owned by the type system and + * Since: 2.24 */ /** - * g_param_type_register_static: - * @name: 0-terminated string used as the name of the new #GParamSpec type. - * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. - * - * Registers @name as the name of a new static type derived from - * #G_TYPE_PARAM. The type system uses the information contained in - * the #GParamSpecTypeInfo structure pointed to by @info to manage the - * #GParamSpec type and its instances. + * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH: * - * Returns: The new type identifier. + * Allowed characters in a path. Includes "!$&'()*+,;=:@/". */ /** - * G_ENUM_CLASS_TYPE: - * @class: a #GEnumClass - * - * Get the type identifier from a given #GEnumClass structure. + * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT: * - * Returns: the #GType + * Allowed characters in path elements. Includes "!$&'()*+,;=:@". */ /** - * GCopyFunc: - * @src: A pointer to the data which should be copied - * @data: Additional data - * - * A function of this signature is used to copy the node data - * when doing a deep-copy of a tree. + * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO: * - * Returns: A pointer to the copy - * Since: 2.4 + * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:". */ /** - * G_TYPE_FLOAT: + * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS: * - * The fundamental type corresponding to #gfloat. + * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". */ /** - * G_VALUE_HOLDS_UCHAR: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. + * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITER: * - * Returns: %TRUE on success. + * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". */ /** - * G_TYPE_IS_INSTANTIATABLE: - * @type: A #GType value. + * G_VALUE_COLLECT: + * @value: a #GValue return location. @value is supposed to be initialized according to the value type to be collected + * @var_args: the va_list variable; it may be evaluated multiple times + * @flags: flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. + * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails * - * Checks if @type can be instantiated. Instantiation is the - * process of creating an instance (object) of this type. + * Collects a variable argument value from a va_list. We have to + * implement the varargs collection as a macro, because on some systems + * va_list variables cannot be passed by reference. + * you should use the #G_VALUE_COLLECT_INIT variant and pass the unitialized + * #GValue. That variant is faster than #G_VALUE_COLLECT. * - * Returns: %TRUE on success. + * Note: If you are creating the @value argument just before calling this macro, */ /** - * GSignalEmissionHook: - * @ihint: Signal invocation hint, see #GSignalInvocationHint. - * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted. - * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission. - * @data: user data associated with the hook. - * - * A simple function pointer to get invoked when the signal is emitted. This - * allows you to tie a hook to the signal type, so that it will trap all - * emissions of that signal, from any object. - * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. - * hook is disconnected (and destroyed). + * G_VALUE_COLLECT_FORMAT_MAX_LENGTH: * - * Returns: whether it wants to stay connected. If it returns %FALSE, the signal + * The maximal number of #GTypeCValue<!-- -->s which can be collected for a + * single #GValue. */ /** - * G_CLOSURE_NEEDS_MARSHAL: - * @closure: a #GClosure + * G_VALUE_COLLECT_INIT: + * @value: a #GValue return location. @value must contain only 0 bytes. + * @_value_type: the #GType to use for @value. + * @var_args: the va_list variable; it may be evaluated multiple times + * @flags: flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. + * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails * - * Check if the closure still needs a marshaller. See g_closure_set_marshal(). + * Collects a variable argument value from a va_list. We have to + * implement the varargs collection as a macro, because on some systems + * va_list variables cannot be passed by reference. * - * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on + * Since: 2.24 */ /** - * g_type_plugin_use: - * @plugin: a #GTypePlugin + * G_VALUE_HOLDS: + * @value: A #GValue structure. + * @type: A #GType value. * - * Calls the @use_plugin function from the #GTypePluginClass of - * the GObject type system itself. + * Checks if @value holds (or contains) a value of @type. + * This macro will also check for @value != %NULL and issue a + * warning if the check fails. + * + * Returns: %TRUE if @value holds the @type. */ /** - * G_TYPE_INSTANCE_GET_CLASS: - * @instance: Location of the #GTypeInstance structure. - * @g_type: The #GType of the class to be returned. - * @c_type: The C type of the class structure. + * G_VALUE_HOLDS_BOOLEAN: + * @value: a valid #GValue structure * - * Get the class structure of a given @instance, casted - * to a specified ancestor type @g_type of the instance. - * Note that while calling a GInstanceInitFunc(), the class pointer gets - * modified, so it might not always return the expected pointer. - * This macro should only be used in type implementations. + * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. * - * Returns: a pointer to the class structure + * Returns: %TRUE on success. */ /** - * g_object_class_install_properties: - * @oclass: a #GObjectClass - * @n_pspecs: the length of the #GParamSpec<!-- -->s array - * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array defining the new properties + * G_VALUE_HOLDS_BOXED: + * @value: a valid #GValue structure * - * Installs new properties from an array of #GParamSpec<!-- -->s. This is - * usually done in the class initializer. - * The property id of each property is the index of each #GParamSpec in - * the @pspecs array. - * The property id of 0 is treated specially by #GObject and it should not - * be used to store a #GParamSpec. - * This function should be used if you plan to use a static array of - * #GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this - * class initialization: - * |[ - * enum { - * PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES - * }; - * static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, }; - * static void - * my_object_class_init (MyObjectClass *klass) - * { - * GObjectClass *gobject_class = G_OBJECT_CLASS (klass); - * obj_properties[PROP_FOO] = - * g_param_spec_int ("foo", "Foo", "Foo", - * -1, G_MAXINT, - * 0, - * G_PARAM_READWRITE); - * obj_properties[PROP_BAR] = - * g_param_spec_string ("bar", "Bar", "Bar", - * NULL, - * G_PARAM_READWRITE); - * gobject_class->set_property = my_object_set_property; - * gobject_class->get_property = my_object_get_property; - * g_object_class_install_properties (gobject_class, - * N_PROPERTIES, - * obj_properties); - * } - * ]| - * allows calling g_object_notify_by_pspec() to notify of property changes: - * |[ - * void - * my_object_set_foo (MyObject *self, gint foo) - * { - * if (self->foo != foo) - * { - * self->foo = foo; - * g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]); - * } - * } - * ]| + * Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_value_set_object: - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * @v_object: (type GObject.Object): object value to be set + * G_VALUE_HOLDS_CHAR: + * @value: a valid #GValue structure * - * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. - * g_value_set_object() increases the reference count of @v_object - * (the #GValue holds a reference to @v_object). If you do not wish - * to increase the reference count of the object (i.e. you wish to - * pass your current reference to the #GValue because you no longer - * need it), use g_value_take_object() instead. - * It is important that your #GValue holds a reference to @v_object (either its - * own, or one it has taken) to ensure that the object won't be destroyed while - * the #GValue still exists). - */ - - -/** - * G_VARIANT_TYPE_ARRAY: + * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. * - * An indefinite type that is a supertype of every array type. + * Returns: %TRUE on success. */ /** - * GTypePluginUse: - * @plugin: the #GTypePlugin whose use count should be increased + * G_VALUE_HOLDS_DOUBLE: + * @value: a valid #GValue structure * - * The type of the @use_plugin function of #GTypePluginClass, which gets called - * to increase the use count of @plugin. - */ - - -/** - * G_VARIANT_TYPE_DOUBLE: + * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. * - * The type of a double precision IEEE754 floating point number. - * These guys go up to about 1.80e308 (plus and minus) but miss out on - * some numbers in between. In any case, that's far greater than the - * estimated number of fundamental particles in the observable - * universe. + * Returns: %TRUE on success. */ /** - * g_closure_add_invalidate_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data to pass to @notify_func - * @notify_func: the callback function to register + * G_VALUE_HOLDS_ENUM: + * @value: a valid #GValue structure * - * Registers an invalidation notifier which will be called when the - * notifiers are invoked before finalization notifiers, in an - * unspecified order. - */ - - -/** - * G_TYPE_FLAGS: + * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. * - * The fundamental type from which all flags types are derived. + * Returns: %TRUE on success. */ /** - * G_PARAM_STATIC_STRINGS: + * G_VALUE_HOLDS_FLAGS: + * @value: a valid #GValue structure * - * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. - * Since 2.13.0 + * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. + * + * Returns: %TRUE on success. */ /** - * g_enum_register_static: - * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. + * G_VALUE_HOLDS_FLOAT: + * @value: a valid #GValue structure * - * Registers a new static enumeration type with the name @name. - * It is normally more convenient to let <link - * linkend="glib-mkenums">glib-mkenums</link> generate a - * my_enum_get_type() function from a usual C enumeration definition - * than to write one yourself using g_enum_register_static(). + * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. * - * Returns: The new type identifier. + * Returns: %TRUE on success. */ /** - * GFlagsClass: - * @g_type_class: the parent class - * @mask: a mask covering all possible values. - * @n_values: the number of possible values. - * @values: an array of #GFlagsValue structs describing the individual values. + * G_VALUE_HOLDS_GTYPE: + * @value: a valid #GValue structure * - * The class of a flags type holds information about its - * possible values. - */ - - -/** - * g_object_set_data: - * @object: #GObject containing the associations. - * @key: name of the key - * @data: data to associate with that key + * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. * - * Each object carries around a table of associations from - * strings to pointers. This function lets you set an association. - * If the object already had an association with that name, - * the old association will be destroyed. + * Since: 2.12 + * Returns: %TRUE on success. */ /** - * G_TYPE_VALUE: + * G_VALUE_HOLDS_INT: + * @value: a valid #GValue structure * - * The type ID of the "GValue" type which is a boxed type, - * used to pass around pointers to GValues. - */ - - -/** - * G_TYPE_DOUBLE: + * Checks whether the given #GValue can hold values of type %G_TYPE_INT. * - * The fundamental type corresponding to #gdouble. + * Returns: %TRUE on success. */ /** - * GTypeValueTable: - * @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]| - * @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]| - * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]| - * @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]| - * @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i' needs to be used, and for collection of floats 'd'. - * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined. - * @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations. - * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]| + * G_VALUE_HOLDS_INT64: + * @value: a valid #GValue structure * - * The #GTypeValueTable provides the functions required by the #GValue implementation, - * to serve as a container for values of a type. - */ - - -/** - * g_cclosure_marshal_VOID__ENUM: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the enumeration parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * Checks whether the given #GValue can hold values of type %G_TYPE_INT64. * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type.. + * Returns: %TRUE on success. */ /** - * G_VARIANT_TYPE_BOOLEAN: + * G_VALUE_HOLDS_LONG: + * @value: a valid #GValue structure * - * The type of a value that can be either %TRUE or %FALSE. - */ - - -/** - * G_PARAM_SPEC_STRING: - * @pspec: a valid #GParamSpec instance + * Checks whether the given #GValue can hold values of type %G_TYPE_LONG. * - * Casts a #GParamSpec instance into a #GParamSpecString. + * Returns: %TRUE on success. */ /** - * G_PARAM_SPEC_TYPE: - * @pspec: a valid #GParamSpec + * G_VALUE_HOLDS_OBJECT: + * @value: a valid #GValue structure * - * Retrieves the #GType of this @pspec. - */ - - -/** - * GClosureNotify: - * @data: data specified when registering the notification callback - * @closure: the #GClosure on which the notification is emitted + * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. * - * The type used for the various notification callbacks which can be registered - * on closures. + * Returns: %TRUE on success. */ /** - * G_VARIANT_TYPE_VARIANT: + * G_VALUE_HOLDS_PARAM: + * @value: a valid #GValue structure * - * The type of a box that contains any other value (including another - * variant). - */ - - -/** - * G_VARIANT_TYPE_BYTESTRING: + * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. * - * The type of an array of bytes. This type is commonly used to pass - * around strings that may not be valid utf8. In that case, the - * convention is that the nul terminator character should be included as - * the last character in the array. + * Returns: %TRUE on success. */ /** - * GParamSpecVariant: - * @parent_instance: private #GParamSpec portion - * @type: a #GVariantType, or %NULL - * @default_value: a #GVariant, or %NULL + * G_VALUE_HOLDS_POINTER: + * @value: a valid #GValue structure * - * A #GParamSpec derived structure that contains the meta data for #GVariant properties. + * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * G_TYPE_MAKE_FUNDAMENTAL: - * @x: the fundamental type number. + * G_VALUE_HOLDS_STRING: + * @value: a valid #GValue structure * - * Get the type ID for the fundamental type number @x. - * Use g_type_fundamental_next() instead of this macro to create new fundamental - * types. + * Checks whether the given #GValue can hold values of type %G_TYPE_STRING. * - * Returns: the GType + * Returns: %TRUE on success. */ /** - * g_object_add_toggle_ref: (skip) - * @object: a #GObject - * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. - * @data: data to pass to @notify + * G_VALUE_HOLDS_UCHAR: + * @value: a valid #GValue structure * - * Increases the reference count of the object by one and sets a - * callback to be called when all other references to the object are - * dropped, or when this is already the last reference to the object - * and another reference is established. - * This functionality is intended for binding @object to a proxy - * object managed by another memory manager. This is done with two - * g_object_add_toggle_ref() and a reverse reference to the proxy - * object which is either a strong reference or weak reference. - * The setup is that when there are no other references to @object, - * only a weak reference is held in the reverse direction from @object - * to the proxy object, but when there are other references held to - * when the reference from @object to the proxy object should be - * <firstterm>toggled</firstterm> from strong to weak (@is_last_ref - * true) or weak to strong (@is_last_ref false). - * Since a (normal) reference must be held to the object before - * calling g_object_toggle_ref(), the initial state of the reverse - * link is always strong. - * Multiple toggle references may be added to the same gobject, - * however if there are multiple toggle references to an object, none - * of them will ever be notified until all but one are removed. For - * this reason, you should only ever use a toggle reference if there - * is important state in the proxy object. + * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. * - * Paired references: the strong reference added by - * Since: 2.8 + * Returns: %TRUE on success. */ /** - * g_signal_handler_unblock: - * @instance: The instance to unblock the signal handler of. - * @handler_id: Handler id of the handler to be unblocked. + * G_VALUE_HOLDS_UINT: + * @value: a valid #GValue structure * - * Undoes the effect of a previous g_signal_handler_block() call. A - * blocked handler is skipped during signal emissions and will not be - * invoked, unblocking it (for exactly the amount of times it has been - * blocked before) reverts its "blocked" state, so the handler will be - * recognized by the signal system and is called upon future or - * currently ongoing signal emissions (since the order in which - * handlers are called during signal emissions is deterministic, - * whether the unblocked handler in question is called as part of a - * currently ongoing emission depends on how far that emission has - * proceeded yet). - * The @handler_id has to be a valid id of a signal handler that is - * connected to a signal of @instance and is currently blocked. + * Checks whether the given #GValue can hold values of type %G_TYPE_UINT. + * + * Returns: %TRUE on success. */ /** - * G_TIME_SPAN_DAY: + * G_VALUE_HOLDS_UINT64: + * @value: a valid #GValue structure * - * Evaluates to a time span of one day. + * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_signal_chain_from_overridden_handler: - * @instance: the instance the signal is being emitted on. - * @...: parameters to be passed to the parent class closure, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * G_VALUE_HOLDS_ULONG: + * @value: a valid #GValue structure * - * Calls the original class closure of a signal. This function should - * only be called from an overridden class closure; see - * g_signal_override_class_closure() and - * g_signal_override_class_handler(). + * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. * - * Since: 2.18 + * Returns: %TRUE on success. */ /** - * g_param_spec_pool_insert: - * @pool: a #GParamSpecPool. - * @pspec: the #GParamSpec to insert - * @owner_type: a #GType identifying the owner of @pspec + * G_VALUE_HOLDS_VARIANT: + * @value: a valid #GValue structure * - * Inserts a #GParamSpec in the pool. + * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. + * + * Returns: %TRUE on success. + * Since: 2.26 */ /** - * g_type_register_static_simple: (skip) - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @class_size: Size of the class structure (see #GTypeInfo) - * @class_init: Location of the class initialization function (see #GTypeInfo) - * @instance_size: Size of the instance structure (see #GTypeInfo) - * @instance_init: Location of the instance initialization function (see #GTypeInfo) - * @flags: Bitwise combination of #GTypeFlags values. - * - * Registers @type_name as the name of a new static type derived from - * abstract or not) of the type. It works by filling a #GTypeInfo - * struct and calling g_type_register_static(). + * G_VALUE_LCOPY: + * @value: a #GValue return location. @value is supposed to be initialized according to the value type to be collected + * @var_args: the va_list variable; it may be evaluated multiple times + * @flags: flags which are passed on to the lcopy_value() function of the #GTypeValueTable of @value. + * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails * - * Since: 2.12 - * Returns: The new type identifier. + * Collects a value's variable argument locations from a va_list. Usage is + * analogous to G_VALUE_COLLECT(). */ /** - * G_TYPE_CHECK_INSTANCE: - * @instance: Location of a #GTypeInstance structure. + * G_VALUE_TYPE: + * @value: A #GValue structure. * - * Checks if @instance is a valid #GTypeInstance structure, - * otherwise issues a warning and returns %FALSE. - * This macro should only be used in type implementations. + * Get the type identifier of @value. * - * Returns: %TRUE on success. + * Returns: the #GType. */ /** - * g_param_spec_float: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * G_VALUE_TYPE_NAME: + * @value: A #GValue structure. * - * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. - * See g_param_spec_internal() for details on property names. + * Gets the the type name of @value. * - * Returns: a newly created parameter specification + * Returns: the type name. */ /** - * GSignalQuery: - * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown. - * @signal_name: The signal name. - * @itype: The interface/instance type that this signal can be emitted for. - * @signal_flags: The signal flags as passed in to g_signal_new(). - * @return_type: The return type for user callbacks. - * @n_params: The number of parameters that user callbacks take. - * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting> + * G_VARIANT_TYPE: + * @type_string: a well-formed #GVariantType type string * - * A structure holding in-depth information for a specific signal. It is - * filled in by the g_signal_query() function. + * Converts a string to a const #GVariantType. Depending on the + * current debugging level, this function may perform a runtime check + * to ensure that @string is a valid GVariant type string. + * It is always a programmer error to use this macro with an invalid + * type string. + * Since 2.24 */ /** - * GTestLogFatalFunc: - * @log_domain: the log domain of the message - * @log_level: the log level of the message (including the fatal and recursion flags) - * @message: the message to process - * @user_data: user data, set in g_test_log_set_fatal_handler() - * - * Specifies the prototype of fatal log handler functions. + * G_VARIANT_TYPE_ANY: * - * Returns: %TRUE if the program should abort, %FALSE otherwise - * Since: 2.22 + * An indefinite type that is a supertype of every type (including + * itself). */ /** - * g_cclosure_marshal_VOID__UCHAR: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #guchar parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * G_VARIANT_TYPE_ARRAY: * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>. + * An indefinite type that is a supertype of every array type. */ /** - * g_value_get_int64: - * @value: a valid #GValue of type %G_TYPE_INT64 - * - * Get the contents of a %G_TYPE_INT64 #GValue. + * G_VARIANT_TYPE_BASIC: * - * Returns: 64bit integer contents of @value + * An indefinite type that is a supertype of every basic (ie: + * non-container) type. */ /** - * g_cclosure_marshal_VOID__FLOAT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gfloat parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * G_VARIANT_TYPE_BOOLEAN: * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>. + * The type of a value that can be either %TRUE or %FALSE. */ /** - * g_signal_handler_disconnect: - * @instance: The instance to remove the signal handler from. - * @handler_id: Handler id of the handler to be disconnected. + * G_VARIANT_TYPE_BYTE: * - * Disconnects a handler from an instance so it will not be called during - * any future or currently ongoing emissions of the signal it has been - * connected to. The @handler_id becomes invalid and may be reused. - * The @handler_id has to be a valid signal handler id, connected to a - * signal of @instance. + * The type of an integer value that can range from 0 to 255. */ /** - * G_DEFINE_ABSTRACT_TYPE_WITH_CODE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * @_C_: Custom code that gets inserted in the @type_name_get_type() function. - * - * A convenience macro for type implementations. - * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to - * insert custom code into the *_get_type() function, e.g. interface implementations - * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. + * G_VARIANT_TYPE_BYTESTRING: * - * Since: 2.4 + * The type of an array of bytes. This type is commonly used to pass + * around strings that may not be valid utf8. In that case, the + * convention is that the nul terminator character should be included as + * the last character in the array. */ /** - * g_signal_handlers_disconnect_by_func: - * @instance: The instance to remove handlers from. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. - * - * Disconnects all handlers on an instance that match @func and @data. + * G_VARIANT_TYPE_BYTESTRING_ARRAY: * - * Returns: The number of handlers that matched. + * The type of an array of byte strings (an array of arrays of bytes). */ /** - * GSourceFuncs: - * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the - * @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here. - * @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source. - * @finalize: Called when the source is finalized. + * G_VARIANT_TYPE_DICTIONARY: * - * The <structname>GSourceFuncs</structname> struct contains a table of - * functions used to handle event sources in a generic manner. - * For idle sources, the prepare and check functions always return %TRUE - * to indicate that the source is always ready to be processed. The prepare - * function also returns a timeout value of 0 to ensure that the poll() call - * doesn't block (since that would be time wasted which could have been spent - * running the idle function). - * For timeout sources, the prepare and check functions both return %TRUE - * if the timeout interval has expired. The prepare function also returns - * a timeout value to ensure that the poll() call doesn't block too long - * and miss the next timeout. - * For file descriptor sources, the prepare function typically returns %FALSE, - * since it must wait until poll() has been called before it knows whether - * any events need to be processed. It sets the returned timeout to -1 to - * indicate that it doesn't mind how long the poll() call blocks. In the - * check function, it tests the results of the poll() call to see if the - * required condition has been met, and returns %TRUE if so. + * An indefinite type that is a supertype of every dictionary type -- + * that is, any array type that has an element type equal to any + * dictionary entry type. */ /** - * G_TYPE_CHAR: + * G_VARIANT_TYPE_DICT_ENTRY: * - * The fundamental type corresponding to #gchar. - * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer. - * This may or may not be the same type a the C type "gchar". + * An indefinite type that is a supertype of every dictionary entry + * type. */ /** - * g_param_spec_pool_remove: - * @pool: a #GParamSpecPool - * @pspec: the #GParamSpec to remove + * G_VARIANT_TYPE_DOUBLE: * - * Removes a #GParamSpec from the pool. + * The type of a double precision IEEE754 floating point number. + * These guys go up to about 1.80e308 (plus and minus) but miss out on + * some numbers in between. In any case, that's far greater than the + * estimated number of fundamental particles in the observable + * universe. */ /** - * g_param_spec_unref: (skip) - * @pspec: a valid #GParamSpec + * G_VARIANT_TYPE_HANDLE: * - * Decrements the reference count of a @pspec. + * The type of a 32bit signed integer value, that by convention, is used + * as an index into an array of file descriptors that are sent alongside + * a DBus message. + * If you are not interacting with DBus, then there is no reason to make + * use of this type. */ /** - * G_VALUE_HOLDS_GTYPE: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. + * G_VARIANT_TYPE_INT16: * - * Since: 2.12 - * Returns: %TRUE on success. + * The type of an integer value that can range from -32768 to 32767. */ /** - * G_OBJECT_CLASS: - * @class: a valid #GObjectClass + * G_VARIANT_TYPE_INT32: * - * Casts a derived #GObjectClass structure into a #GObjectClass structure. + * The type of an integer value that can range from -2147483648 to + * 2147483647. */ /** - * G_VARIANT_TYPE_INT32: + * G_VARIANT_TYPE_INT64: * - * The type of an integer value that can range from -2147483648 to - * 2147483647. + * The type of an integer value that can range from + * -9223372036854775808 to 9223372036854775807. */ /** - * GBindingFlags: - * @G_BINDING_DEFAULT: The default binding; if the source property changes, the target property is updated with its value. - * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. - * @G_BINDING_SYNC_CREATE: Synchronize the values of the source and target properties when creating the binding; the direction of the synchronization is always from the source to the target. - * @G_BINDING_INVERT_BOOLEAN: If the two properties being bound are booleans, setting one to %TRUE will result in the other being set to %FALSE and vice versa. This flag will only work for boolean properties, and cannot be used when passing custom transformation functions to g_object_bind_property_full(). - * - * Flags to be passed to g_object_bind_property() or - * g_object_bind_property_full(). - * This enumeration can be extended at later date. + * G_VARIANT_TYPE_MAYBE: * - * Since: 2.26 + * An indefinite type that is a supertype of every maybe type. */ /** - * g_type_plugin_complete_type_info: - * @plugin: a #GTypePlugin - * @g_type: the #GType whose info is completed - * @info: the #GTypeInfo struct to fill in - * @value_table: the #GTypeValueTable to fill in + * G_VARIANT_TYPE_OBJECT_PATH: * - * Calls the @complete_type_info function from the #GTypePluginClass of @plugin. - * There should be no need to use this function outside of the GObject - * type system itself. + * The type of a DBus object reference. These are strings of a + * specific format used to identify objects at a given destination on + * the bus. + * If you are not interacting with DBus, then there is no reason to make + * use of this type. If you are, then the DBus specification contains a + * precise description of valid object paths. */ /** - * G_TYPE_PARAM_PARAM: + * G_VARIANT_TYPE_SIGNATURE: * - * The #GType of #GParamSpecParam. + * The type of a DBus type signature. These are strings of a specific + * format used as type signatures for DBus methods and messages. + * If you are not interacting with DBus, then there is no reason to make + * use of this type. If you are, then the DBus specification contains a + * precise description of valid signature strings. */ /** - * g_value_set_flags: - * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS - * @v_flags: flags value to be set + * G_VARIANT_TYPE_STRING: * - * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. + * The type of a string. "" is a string. %NULL is not a string. */ /** - * G_IS_PARAM_SPEC_VARIANT: - * @pspec: a #GParamSpec - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. + * G_VARIANT_TYPE_STRING_ARRAY: * - * Returns: %TRUE on success - * Since: 2.26 + * The type of an array of strings. */ /** - * g_value_array_get_nth: - * @value_array: #GValueArray to get a value from - * @index_: index of the value of interest - * - * Return a pointer to the value at @index_ containd in @value_array. + * G_VARIANT_TYPE_TUPLE: * - * Returns: (transfer none): pointer to a value at @index_ in @value_array + * An indefinite type that is a supertype of every tuple type, + * regardless of the number of items in the tuple. */ /** - * GParamSpecFlags: - * @parent_instance: private #GParamSpec portion - * @flags_class: the #GFlagsClass for the flags - * @default_value: default value for the property specified + * G_VARIANT_TYPE_UINT16: * - * A #GParamSpec derived structure that contains the meta data for flags - * properties. + * The type of an integer value that can range from 0 to 65535. + * There were about this many people living in Toronto in the 1870s. */ /** - * g_object_run_dispose: - * @object: a #GObject + * G_VARIANT_TYPE_UINT32: * - * Releases all references to other objects. This can be used to break - * reference cycles. - * This functions should only be called from object system implementations. + * The type of an integer value that can range from 0 to 4294967295. + * That's one number for everyone who was around in the late 1970s. */ /** - * G_VALUE_TYPE_NAME: - * @value: A #GValue structure. - * - * Gets the the type name of @value. + * G_VARIANT_TYPE_UINT64: * - * Returns: the type name. + * The type of an integer value that can range from 0 to + * 18446744073709551616. That's a really big number, but a Rubik's + * cube can have a bit more than twice as many possible positions. */ /** - * g_type_parent: - * @type: The derived type. - * - * Return the direct parent type of the passed in type. If the passed - * in type has no parent, i.e. is a fundamental type, 0 is returned. + * G_VARIANT_TYPE_UNIT: * - * Returns: The parent type. + * The empty tuple type. Has only one instance. Known also as "triv" + * or "void". */ /** - * SECTION:gparamspe: - * @short_description: Metadata for parameter specifications - * @see_also: g_object_class_install_property(), g_object_set(), g_object_get(), g_object_set_property(), g_object_get_property(), g_value_register_transform_func() - * @title: GParamSpec + * G_VARIANT_TYPE_VARIANT: * - * #GParamSpec is an object structure that encapsulates the metadata - * required to specify parameters, such as e.g. #GObject properties. - * <para id="canonical-parameter-name"> - * Parameter names need to start with a letter (a-z or A-Z). Subsequent - * characters can be letters, numbers or a '-'. - * All other characters are replaced by a '-' during construction. - * The result of this replacement is called the canonical name of the - * parameter. - * </para> + * The type of a box that contains any other value (including another + * variant). */ /** - * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS: + * SECTION:enumerations_flag: + * @short_description: Enumeration and flags types + * @title: Enumeration and Flag Types g_param_spec_flags() * - * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". + * The GLib type system provides fundamental types for enumeration and + * flags types. (Flags types are like enumerations, but allow their + * values to be combined by bitwise or). A registered enumeration or + * flags type associates a name and a nickname with each allowed + * value, and the methods g_enum_get_value_by_name(), + * g_enum_get_value_by_nick(), g_flags_get_value_by_name() and + * g_flags_get_value_by_nick() can look up values by their name or + * nickname. When an enumeration or flags type is registered with the + * GLib type system, it can be used as value type for object + * properties, using g_param_spec_enum() or g_param_spec_flags(). + * GObject ships with a utility called <link + * linkend="glib-mkenums">glib-mkenums</link> that can construct + * suitable type registration functions from C enumeration + * definitions. */ @@ -6047,1361 +4798,1670 @@ /** - * GClassInitFunc: - * @g_class: The #GTypeClass structure to initialize. - * @class_data: The @class_data member supplied via the #GTypeInfo structure. + * SECTION:gboxe: + * @short_description: A mechanism to wrap opaque C structures registered by the type system + * @see_also: #GParamSpecBoxed, g_param_spec_boxed() + * @title: Boxed Types * - * A callback function used by the type system to initialize the class - * of a specific type. This function should initialize all static class - * members. - * The initialization process of a class involves: + * GBoxed is a generic wrapper mechanism for arbitrary C structures. The only + * thing the type system needs to know about the structures is how to copy and + * free them, beyond that they are treated as opaque chunks of memory. + * Boxed types are useful for simple value-holder structures like rectangles or + * points. They can also be used for wrapping structures defined in non-GObject + * based libraries. + */ + + +/** + * SECTION:gclosur: + * @short_description: Functions as first-class objects + * @title: Closures + * + * A #GClosure represents a callback supplied by the programmer. It + * will generally comprise a function of some kind and a marshaller + * used to call it. It is the reponsibility of the marshaller to + * convert the arguments for the invocation from #GValue<!-- -->s into + * a suitable form, perform the callback on the converted arguments, + * and transform the return value back into a #GValue. + * In the case of C programs, a closure usually just holds a pointer + * to a function and maybe a data argument, and the marshaller + * converts between #GValue<!-- --> and native C types. The GObject + * library provides the #GCClosure type for this purpose. Bindings for + * other languages need marshallers which convert between #GValue<!-- + * -->s and suitable representations in the runtime of the language in + * order to use functions written in that languages as callbacks. + * Within GObject, closures play an important role in the + * implementation of signals. When a signal is registered, the + * marshaller for any closure which is connected to this + * signal. GObject provides a number of C marshallers for this + * purpose, see the g_cclosure_marshal_*() functions. Additional C + * marshallers can be generated with the <link + * linkend="glib-genmarshal">glib-genmarshal</link> utility. Closures + * can be explicitly connected to signals with + * g_signal_connect_closure(), but it usually more convenient to let + * GObject create a closure automatically by using one of the + * g_signal_connect_*() functions which take a callback function/user + * data pair. + * Using closures has a number of important advantages over a simple + * callback function/data pointer combination: * <itemizedlist> * <listitem><para> - * 1 - Copying common members from the parent class over to the - * derived class structure. - * </para></listitem> - * <listitem><para> - * 2 - Zero initialization of the remaining members not copied - * over from the parent class. + * Closures allow the callee to get the types of the callback parameters, + * which means that language bindings don't have to write individual glue + * for each callback type. * </para></listitem> * <listitem><para> - * 3 - Invocation of the GBaseInitFunc() initializers of all parent - * types and the class' type. + * The reference counting of #GClosure makes it easy to handle reentrancy + * right; if a callback is removed while it is being invoked, the closure + * and its parameters won't be freed until the invocation finishes. * </para></listitem> * <listitem><para> - * 4 - Invocation of the class' GClassInitFunc() initializer. + * g_closure_invalidate() and invalidation notifiers allow callbacks to be + * automatically removed when the objects they point to go away. * </para></listitem> * </itemizedlist> - * Since derived classes are partially initialized through a memory copy - * of the parent class, the general rule is that GBaseInitFunc() and - * GBaseFinalizeFunc() should take care of necessary reinitialization - * and release of those class members that were introduced by the type - * that specified these GBaseInitFunc()/GBaseFinalizeFunc(). - * GClassInitFunc() should only care about initializing static - * class members, while dynamic class members (such as allocated strings - * or reference counted resources) are better handled by a GBaseInitFunc() - * for this type, so proper initialization of the dynamic class members - * is performed for class initialization of derived types as well. - * An example may help to correspond the intend of the different class - * initializers: + */ + + +/** + * SECTION:generic_value: + * @short_description: A polymorphic type that can hold values of any other type + * @see_also: The fundamental types which all support #GValue operations and thus can be used as a type initializer for g_value_init() are defined by a separate interface. See the <link linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values API</link> for details. + * @title: Generic values + * + * The #GValue structure is basically a variable container that consists + * of a type identifier and a specific value of that type. + * The type identifier within a #GValue structure always determines the + * type of the associated value. + * To create a undefined #GValue structure, simply create a zero-filled + * #GValue structure. To initialize the #GValue, use the g_value_init() + * function. A #GValue cannot be used until it is initialized. + * The basic type operations (such as freeing and copying) are determined + * by the #GTypeValueTable associated with the type ID stored in the #GValue. + * Other #GValue operations (such as converting values between types) are + * provided by this interface. + * The code in the example program below demonstrates #GValue's + * features. * |[ - * typedef struct { - * GObjectClass parent_class; - * gint static_integer; - * gchar *dynamic_string; - * } TypeAClass; - * static void - * type_a_base_class_init (TypeAClass *class) - * { - * class->dynamic_string = g_strdup ("some string"); - * } - * static void - * type_a_base_class_finalize (TypeAClass *class) - * { - * g_free (class->dynamic_string); - * } - * static void - * type_a_class_init (TypeAClass *class) - * { - * class->static_integer = 42; - * } - * typedef struct { - * TypeAClass parent_class; - * gfloat static_float; - * GString *dynamic_gstring; - * } TypeBClass; - * static void - * type_b_base_class_init (TypeBClass *class) - * { - * class->dynamic_gstring = g_string_new ("some other string"); - * } + * #include <glib-object.h> * static void - * type_b_base_class_finalize (TypeBClass *class) + * int2string (const GValue *src_value, + * GValue *dest_value) * { - * g_string_free (class->dynamic_gstring); + * if (g_value_get_int (src_value) == 42) + * g_value_set_static_string (dest_value, "An important number"); + * else + * g_value_set_static_string (dest_value, "What's that?"); * } - * static void - * type_b_class_init (TypeBClass *class) + * int + * main (int argc, + * char *argv[]) * { - * class->static_float = 3.14159265358979323846; + * /* GValues must start zero-filled */ + * GValue a = {0}; + * GValue b = {0}; + * const gchar *message; + * g_type_init (); + * /* The GValue starts empty */ + * g_assert (!G_VALUE_HOLDS_STRING (&a)); + * /* Put a string in it */ + * g_value_init (&a, G_TYPE_STRING); + * g_assert (G_VALUE_HOLDS_STRING (&a)); + * g_value_set_static_string (&a, "Hello, world!"); + * g_printf ("%s\n", g_value_get_string (&a)); + * /* Reset it to its pristine state */ + * g_value_unset (&a); + * /* It can then be reused for another type */ + * g_value_init (&a, G_TYPE_INT); + * g_value_set_int (&a, 42); + * /* Attempt to transform it into a GValue of type STRING */ + * g_value_init (&b, G_TYPE_STRING); + * /* An INT is transformable to a STRING */ + * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); + * g_value_transform (&a, &b); + * g_printf ("%s\n", g_value_get_string (&b)); + * /* Attempt to transform it again using a custom transform function */ + * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); + * g_value_transform (&a, &b); + * g_printf ("%s\n", g_value_get_string (&b)); + * return 0; * } * ]| - * Initialization of TypeBClass will first cause initialization of - * TypeAClass (derived classes reference their parent classes, see - * g_type_class_ref() on this). - * Initialization of TypeAClass roughly involves zero-initializing its fields, - * then calling its GBaseInitFunc() type_a_base_class_init() to allocate - * its dynamic members (dynamic_string), and finally calling its GClassInitFunc() - * type_a_class_init() to initialize its static members (static_integer). - * The first step in the initialization process of TypeBClass is then - * a plain memory copy of the contents of TypeAClass into TypeBClass and - * zero-initialization of the remaining fields in TypeBClass. - * The dynamic members of TypeAClass within TypeBClass now need - * reinitialization which is performed by calling type_a_base_class_init() - * with an argument of TypeBClass. - * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() - * is called to allocate the dynamic members of TypeBClass (dynamic_gstring), - * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), - * is called to complete the initialization process with the static members - * (static_float). - * Corresponding finalization counter parts to the GBaseInitFunc() functions - * have to be provided to release allocated resources at class finalization - * time. */ /** - * GRegexMatchFlags: - * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. - * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A". - * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z". - * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b". - * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match(). - * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator. - * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator. - * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator. - * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized. - * - * Flags specifying match-time options. + * SECTION:gparamspe: + * @short_description: Metadata for parameter specifications + * @see_also: g_object_class_install_property(), g_object_set(), g_object_get(), g_object_set_property(), g_object_get_property(), g_value_register_transform_func() + * @title: GParamSpec * - * Since: 2.14 + * #GParamSpec is an object structure that encapsulates the metadata + * required to specify parameters, such as e.g. #GObject properties. + * <para id="canonical-parameter-name"> + * Parameter names need to start with a letter (a-z or A-Z). Subsequent + * characters can be letters, numbers or a '-'. + * All other characters are replaced by a '-' during construction. + * The result of this replacement is called the canonical name of the + * parameter. + * </para> */ /** - * g_cclosure_new_object_swap: (skip) - * @callback_func: the function to invoke - * @object: a #GObject pointer to pass to @callback_func + * SECTION:gtyp: + * @short_description: The GLib Runtime type identification and management system * - * A variant of g_cclosure_new_swap() which uses @object as @user_data - * and calls g_object_watch_closure() on @object and the created - * closure. This function is useful when you have a callback closely - * associated with a #GObject, and want the callback to no longer run - * after the object is is freed. + * The GType API is the foundation of the GObject system. It provides the + * facilities for registering and managing all fundamental data types, + * user-defined object and interface types. Before using any GType + * or GObject functions, g_type_init() must be called to initialize the + * type system. + * For type creation and registration purposes, all types fall into one of + * unloaded at run-time as dynamic types may be. Static types are created + * with g_type_register_static() that gets type specific information passed + * in via a #GTypeInfo structure. + * Dynamic types are created with g_type_register_dynamic() which takes a + * #GTypePlugin structure instead. The remaining type information (the + * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin + * and the g_type_plugin_*() API. + * These registration functions are usually called only once from a + * function whose only purpose is to return the type identifier for a + * specific class. Once the type (or class or interface) is registered, + * it may be instantiated, inherited, or implemented depending on exactly + * what sort of type it is. + * There is also a third registration function for registering fundamental + * types called g_type_register_fundamental() which requires both a #GTypeInfo + * structure and a #GTypeFundamentalInfo structure but it is seldom used + * since most fundamental types are predefined rather than user-defined. + * A final word about type names. + * Such an identifier needs to be at least three characters long. There is no + * upper length limit. The first character needs to be a letter (a-z or A-Z) + * or an underscore '_'. Subsequent characters can be letters, numbers or + * any of '-_+'. * - * Returns: a new #GCClosure + * Two categories: static or dynamic. Static types are never loaded or */ /** - * g_param_spec_flags: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @flags_type: a #GType derived from %G_TYPE_FLAGS - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS - * property. - * See g_param_spec_internal() for details on property names. + * SECTION:gtypemodul: + * @short_description: Type loading modules <varlistentry> <term>#GTypePlugin</term> <listitem><para>The abstract type loader interface.</para></listitem> </varlistentry> <varlistentry> <term>#GModule</term> <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> </varlistentry> </variablelist> + * @title: GTypeModule * - * Returns: a newly created parameter specification + * #GTypeModule provides a simple implementation of the #GTypePlugin + * interface. The model of #GTypeModule is a dynamically loaded module + * which implements some number of types and interface + * implementations. When the module is loaded, it registers its types + * and interfaces using g_type_module_register_type() and + * g_type_module_add_interface(). As long as any instances of these + * types and interface implementations are in use, the module is kept + * loaded. When the types and interfaces are gone, the module may be + * unloaded. If the types and interfaces become used again, the module + * will be reloaded. Note that the last unref can not happen in module + * code, since that would lead to the caller's code being unloaded before + * g_object_unref() returns to it. + * Keeping track of whether the module should be loaded or not is done by + * using a use count - it starts at zero, and whenever it is greater than + * zero, the module is loaded. The use count is maintained internally by + * the type system, but also can be explicitly controlled by + * g_type_module_use() and g_type_module_unuse(). Typically, when loading + * a module for the first type, g_type_module_use() will be used to load + * it so that it can initialize its types. At some later point, when the + * module no longer needs to be loaded except for the type + * implementations it contains, g_type_module_unuse() is called. + * #GTypeModule does not actually provide any implementation of module + * loading and unloading. To create a particular module type you must + * derive from #GTypeModule and implement the load and unload functions + * in #GTypeModuleClass. */ /** - * G_TYPE_IS_CLASSED: - * @type: A #GType value. - * - * Checks if @type is a classed type. + * SECTION:gtypeplugi: + * @short_description: An interface for dynamically loadable types + * @see_also: #GTypeModule and g_type_register_dynamic(). + * @title: GTypePlugin * - * Returns: %TRUE on success. + * The GObject type system supports dynamic loading of types. The + * #GTypePlugin interface is used to handle the lifecycle of + * dynamically loaded types. It goes as follows: + * <orderedlist> + * <listitem><para> + * The type is initially introduced (usually upon loading the module + * the first time, or by your main application that knows what modules + * introduces what types), like this: + * |[ + * new_type_id = g_type_register_dynamic (parent_type_id, + * "TypeName", + * new_type_plugin, + * type_flags); + * ]| + * where <literal>new_type_plugin</literal> is an implementation of the + * #GTypePlugin interface. + * </para></listitem> + * <listitem><para> + * The type's implementation is referenced, e.g. through + * g_type_class_ref() or through g_type_create_instance() (this is + * being called by g_object_new()) or through one of the above done on + * a type derived from <literal>new_type_id</literal>. + * </para></listitem> + * <listitem><para> + * This causes the type system to load the type's implementation by calling + * g_type_plugin_use() and g_type_plugin_complete_type_info() on + * <literal>new_type_plugin</literal>. + * </para></listitem> + * <listitem><para> + * At some point the type's implementation isn't required anymore, e.g. after + * g_type_class_unref() or g_type_free_instance() (called when the reference + * count of an instance drops to zero). + * </para></listitem> + * <listitem><para> + * This causes the type system to throw away the information retrieved from + * g_type_plugin_complete_type_info() and then it calls + * g_type_plugin_unuse() on <literal>new_type_plugin</literal>. + * </para></listitem> + * <listitem><para> + * Things may repeat from the second step. + * </para></listitem> + * </orderedlist> + * So basically, you need to implement a #GTypePlugin type that + * carries a use_count, once use_count goes from zero to one, you need + * to load the implementation to successfully handle the upcoming + * g_type_plugin_complete_type_info() call. Later, maybe after + * succeeding use/unuse calls, once use_count drops to zero, you can + * unload the implementation again. The type system makes sure to call + * g_type_plugin_use() and g_type_plugin_complete_type_info() again + * when the type is needed again. + * #GTypeModule is an implementation of #GTypePlugin that already + * implements most of this except for the actual module loading and + * unloading. It even handles multiple registered types per module. */ /** - * GParamSpecTypeInfo: - * @instance_size: Size of the instance (object) structure. - * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. - * @instance_init: Location of the instance initialization function (optional). - * @value_type: The #GType of values conforming to this #GParamSpec - * @finalize: The instance finalization function (optional). - * @value_set_default: Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default(). - * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_set_validate(). - * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp(). + * SECTION:object: + * @short_description: The base object type + * @see_also: #GParamSpecObject, g_param_spec_object() + * @title: The Base Object Type * - * This structure is used to provide the type system with the information - * required to initialize and destruct (finalize) a parameter's class and - * instances thereof. - * The initialized structure is passed to the g_param_type_register_static() - * The type system will perform a deep copy of this structure, so its memory - * does not need to be persistent across invocation of - * g_param_type_register_static(). + * GObject is the fundamental type providing the common attributes and + * methods for all object types in GTK+, Pango and other libraries + * based on GObject. The GObject class provides methods for object + * construction and destruction, property access methods, and signal + * support. Signals are described in detail in <xref + * linkend="gobject-Signals"/>. + * <para id="floating-ref"> + * #GInitiallyUnowned is derived from #GObject. The only difference between + * the two is that the initial reference of a #GInitiallyUnowned is flagged + * as a <firstterm>floating</firstterm> reference. + * This means that it is not specifically claimed to be "owned" by + * any code portion. The main motivation for providing floating references is + * C convenience. In particular, it allows code to be written as: + * |[ + * container = create_container(); + * container_add_child (container, create_child()); + * ]| + * If <function>container_add_child()</function> will g_object_ref_sink() the + * passed in child, no reference of the newly created child is leaked. + * Without floating references, <function>container_add_child()</function> + * can only g_object_ref() the new child, so to implement this code without + * reference leaks, it would have to be written as: + * |[ + * Child *child; + * container = create_container(); + * child = create_child(); + * container_add_child (container, child); + * g_object_unref (child); + * ]| + * The floating reference can be converted into + * an ordinary reference by calling g_object_ref_sink(). + * For already sunken objects (objects that don't have a floating reference + * anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns + * a new reference. + * Since floating references are useful almost exclusively for C convenience, + * language bindings that provide automated reference and memory ownership + * maintenance (such as smart pointers or garbage collection) therefore don't + * need to expose floating references in their API. + * </para> + * Some object implementations may need to save an objects floating state + * across certain code portions (an example is #GtkMenu), to achive this, the + * following sequence can be used: + * |[ + * // save floating state + * gboolean was_floating = g_object_is_floating (object); + * g_object_ref_sink (object); + * // protected code portion + * ...; + * // restore floating state + * if (was_floating) + * g_object_force_floating (object); + * g_obejct_unref (object); // release previously acquired reference + * ]| */ /** - * G_TYPE_IS_VALUE_ABSTRACT: - * @type: A #GType value. - * - * Checks if @type is an abstract value type. An abstract value type introduces - * a value table, but can't be used for g_value_init() and is normally used as - * an abstract base type for derived value types. + * SECTION:param_value_type: + * @short_description: Standard Parameter and Value Types + * @see_also: #GParamSpec, #GValue, g_object_class_install_property(). + * @title: Parameters and Values * - * Returns: %TRUE on success. + * #GValue provides an abstract container structure which can be + * copied, transformed and compared while holding a value of any + * (derived) type, which is registered as a #GType with a + * #GTypeValueTable in its #GTypeInfo structure. Parameter + * specifications for most value types can be created as #GParamSpec + * derived instances, to implement e.g. #GObject properties which + * operate on #GValue containers. + * Parameter names need to start with a letter (a-z or A-Z). Subsequent + * characters can be letters, numbers or a '-'. + * All other characters are replaced by a '-' during construction. */ /** - * g_object_add_weak_pointer: (skip) - * @object: The object that should be weak referenced. - * @weak_pointer_location: (inout): The memory address of a pointer. + * SECTION:signal: + * @short_description: A means for customization of object behaviour and a general purpose notification mechanism + * @title: Signals * - * Adds a weak reference from weak_pointer to @object to indicate that - * the pointer located at @weak_pointer_location is only valid during - * the lifetime of @object. When the @object is finalized, + * The basic concept of the signal system is that of the + * <emphasis>emission</emphasis> of a signal. Signals are introduced + * per-type and are identified through strings. Signals introduced + * for a parent type are available in derived types as well, so + * basically they are a per-type facility that is inherited. A signal + * emission mainly involves invocation of a certain set of callbacks + * in precisely defined manner. There are two main categories of such + * callbacks, per-object + * <footnote><para>Although signals can deal with any kind of instantiatable + * type, i'm referring to those types as "object types" in the following, + * simply because that is the context most users will encounter signals in. + * </para></footnote> + * ones and user provided ones. + * The per-object callbacks are most often referred to as "object method + * handler" or "default (signal) handler", while user provided callbacks are + * usually just called "signal handler". + * The object method handler is provided at signal creation time (this most + * frequently happens at the end of an object class' creation), while user + * provided handlers are frequently connected and disconnected to/from a certain + * signal on certain object instances. + * A signal emission consists of five stages, unless prematurely stopped: + * <variablelist> + * <varlistentry><term></term><listitem><para> + * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals + * </para></listitem></varlistentry> + * </variablelist> + * The user-provided signal handlers are called in the order they were + * connected in. + * All handlers may prematurely stop a signal emission, and any number of + * handlers may be connected, disconnected, blocked or unblocked during + * a signal emission. + * There are certain criteria for skipping user handlers in stages 2 and 4 + * of a signal emission. + * First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted + * during callback invocation, to return from the "blocked" state, a + * handler has to get unblocked exactly the same amount of times + * it has been blocked before. + * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional + * "detail" argument passed in to g_signal_emit() has to match the detail + * argument of the signal handler currently subject to invocation. + * Specification of no detail argument for signal handlers (omission of the + * detail part of the signal specification upon connection) serves as a + * wildcard and matches any detail argument passed in to emission. */ /** - * G_TYPE_PARAM_OVERRIDE: - * - * The #GType of #GParamSpecOverride. + * SECTION:value_array: + * @short_description: A container structure to maintain an array of generic values + * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array() + * @title: Value arrays * - * Since: 2.4 + * The prime purpose of a #GValueArray is for it to be used as an + * object property that holds an array of values. A #GValueArray wraps + * an array of #GValue elements in order for it to be used as a boxed + * type through %G_TYPE_VALUE_ARRAY. */ /** - * G_VALUE_HOLDS_VARIANT: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. + * SECTION:value_collectio: + * @Short_description: Converting varargs to generic values + * @Title: Varargs Value Collection * - * Returns: %TRUE on success. - * Since: 2.26 + * The macros in this section provide the varargs parsing support needed + * in variadic GObject functions such as g_object_new() or g_object_set(). + * They currently support the collection of integral types, floating point + * types and pointers. */ /** - * g_param_spec_value_array: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL - * @flags: flags for the property specified + * g_alloca: + * @size: number of bytes to allocate. * - * Creates a new #GParamSpecValueArray instance specifying a - * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a - * %G_TYPE_BOXED type, as such, #GValue structures for this property - * can be accessed with g_value_set_boxed() and g_value_get_boxed(). - * See g_param_spec_internal() for details on property names. + * Allocates @size bytes on the stack; these bytes will be freed when the current + * stack frame is cleaned up. This macro essentially just wraps the alloca() + * function present on most UNIX variants. + * Thus it provides the same advantages and pitfalls as alloca(): + * <variablelist> + * <varlistentry><term></term><listitem><para> + * + alloca() is very fast, as on most systems it's implemented by just adjusting + * the stack pointer register. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * + It doesn't cause any memory fragmentation, within its scope, separate alloca() + * blocks just build up and are released together at function end. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * - Allocation sizes have to fit into the current stack frame. For instance in a + * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, + * so be sparse with alloca() uses. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * - Allocation failure due to insufficient stack space is not indicated with a %NULL + * return like e.g. with malloc(). Instead, most systems probably handle it the same + * way as out of stack space situations from infinite function recursion, i.e. + * with a segmentation fault. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays. + * Stack space allocated with alloca() in the same scope as a variable sized array + * will be freed together with the variable sized array upon exit of that scope, and + * not upon exit of the enclosing function scope. + * </para></listitem></varlistentry> + * </variablelist> * - * Returns: a newly created parameter specification + * Returns: space for @size bytes, allocated on the stack */ /** - * GTypeClass: + * g_atomic_int_dec_and_test: + * @atomic: a pointer to an integer * - * An opaque structure used as the base of all classes. + * Atomically decrements the integer pointed to by @atomic by 1. + * after decrementing it + * + * Returns: %TRUE if the integer pointed to by @atomic is 0 + * Since: 2.4 */ /** - * GBindingTransformFunc: - * @binding: a #GBinding - * @source_value: the value of the source property - * @target_value: the value of the target property - * @user_data: data passed to the transform function + * g_atomic_int_inc: + * @atomic: a pointer to an integer. * - * A function to be called to transform the source property of @source - * from @source_value into the target property of @target - * using @target_value. - * otherwise + * Atomically increments the integer pointed to by @atomic by 1. * - * Returns: %TRUE if the transformation was successful, and %FALSE - * Since: 2.26 + * Since: 2.4 */ /** - * g_param_spec_variant: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @type: a #GVariantType - * @default_value: (allow-none): a #GVariant of type @type to use as the default value, or %NULL - * @flags: flags for the property specified + * g_binding_get_flags: + * @binding: a #GBinding * - * Creates a new #GParamSpecVariant instance specifying a #GVariant - * property. - * If @default_value is floating, it is consumed. - * See g_param_spec_internal() for details on property names. + * Retrieves the flags passed when constructing the #GBinding * - * Returns: the newly created #GParamSpec + * Returns: the #GBindingFlags used by the #GBinding * Since: 2.26 */ /** - * G_TYPE_GSTRING: + * g_binding_get_source: + * @binding: a #GBinding * - * The #GType for #GString. + * Retrieves the #GObject instance used as the source of the binding + * + * Returns: (transfer none): the source #GObject + * Since: 2.26 */ /** - * G_PARAM_SPEC_OVERRIDE: - * @pspec: a #GParamSpec + * g_binding_get_source_property: + * @binding: a #GBinding * - * Casts a #GParamSpec into a #GParamSpecOverride. + * Retrieves the name of the property of #GBinding:source used as the source + * of the binding * - * Since: 2.4 + * Returns: the name of the source property + * Since: 2.26 */ /** - * G_VALUE_HOLDS_UINT64: - * @value: a valid #GValue structure + * g_binding_get_target: + * @binding: a #GBinding * - * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. + * Retrieves the #GObject instance used as the target of the binding * - * Returns: %TRUE on success. + * Returns: (transfer none): the target #GObject + * Since: 2.26 */ /** - * g_param_spec_get_blurb: - * @pspec: a valid #GParamSpec + * g_binding_get_target_property: + * @binding: a #GBinding * - * Get the short description of a #GParamSpec. + * Retrieves the name of the property of #GBinding:target used as the target + * of the binding * - * Returns: the short description of @pspec. + * Returns: the name of the target property + * Since: 2.26 */ /** - * g_value_get_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT + * g_boxed_copy: + * @boxed_type: The type of @src_boxed. + * @src_boxed: The boxed structure to be copied. * - * Get the contents of a variant #GValue. + * Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. * - * Returns: variant contents of @value - * Since: 2.26 + * Returns: The newly created copy of the boxed structure. */ /** - * g_signal_emit_by_name: - * @instance: the instance the signal is being emitted on. - * @detailed_signal: a string of the form "signal-name::detail". - * @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * g_boxed_free: + * @boxed_type: The type of @boxed. + * @boxed: The boxed structure to be freed. * - * Emits a signal. - * Note that g_signal_emit_by_name() resets the return value to the default - * if no handlers are connected, in contrast to g_signal_emitv(). + * Free the boxed structure @boxed which is of type @boxed_type. */ /** - * GTypeModuleClass: - * @parent_class: the parent class - * @load: loads the module and registers one or more types using g_type_module_register_type(). - * @unload: unloads the module + * g_boxed_type_register_static: + * @name: Name of the new boxed type. + * @boxed_copy: Boxed structure copy function. + * @boxed_free: Boxed structure free function. * - * In order to implement dynamic loading of types based on #GTypeModule, - * the @load and @unload functions in #GTypeModuleClass must be implemented. + * This function creates a new %G_TYPE_BOXED derived type id for a new + * boxed type with name @name. Boxed type handling functions have to be + * provided to copy and free opaque boxed structures of this type. + * + * Returns: New %G_TYPE_BOXED derived type id for @name. */ /** - * g_param_spec_unichar: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT - * property. #GValue structures for this property can be accessed with - * g_value_set_uint() and g_value_get_uint(). - * See g_param_spec_internal() for details on property names. + * g_cclosure_marshal_BOOLEAN__FLAGS: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: a #GValue which can store the returned #gboolean + * @n_param_values: 2 + * @param_values: a #GValue array holding instance and arg1 + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Returns: a newly created parameter specification + * A marshaller for a #GCClosure with a callback of type + * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter + * denotes a flags type. */ /** - * G_IS_PARAM_SPEC: - * @pspec: a #GParamSpec + * g_cclosure_marshal_BOOLEAN__OBJECT_BOXED_BOXED: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: a #GValue, which can store the returned string + * @n_param_values: 3 + * @param_values: a #GValue array holding instance, arg1 and arg2 + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM - * or derived. + * A marshaller for a #GCClosure with a callback of type + * <literal>gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)</literal>. + * + * Since: 2.26 */ /** - * g_object_get: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to get - * @...: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + * g_cclosure_marshal_BOOL__FLAGS: * - * Gets properties of an object. - * In general, a copy is made of the property contents and the caller - * is responsible for freeing the memory in the appropriate manner for - * the type, for instance by calling g_free() or g_object_unref(). - * <example> - * <title>Using g_object_get(<!-- -->)</title> - * An example of using g_object_get() to get the contents - * of three properties - one of type #G_TYPE_INT, - * one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT: - * <programlisting> - * gint intval; - * gchar *strval; - * GObject *objval; - * g_object_get (my_object, - * "int-property", &intval, - * "str-property", &strval, - * "obj-property", &objval, - * NULL); - * // Do something with intval, strval, objval - * g_free (strval); - * g_object_unref (objval); - * </programlisting> - * </example> + * Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). */ /** - * g_value_array_free: - * @value_array: #GValueArray to free + * g_cclosure_marshal_STRING__OBJECT_POINTER: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: a #GValue, which can store the returned string + * @n_param_values: 3 + * @param_values: a #GValue array holding instance, arg1 and arg2 + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Free a #GValueArray including its contents. + * A marshaller for a #GCClosure with a callback of type + * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>. */ /** - * G_VALUE_TYPE: - * @value: A #GValue structure. - * - * Get the type identifier of @value. + * g_cclosure_marshal_VOID__BOOLEAN: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gboolean parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Returns: the #GType. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>. */ /** - * g_object_bind_property_full: - * @source: the source #GObject - * @source_property: the property on @source to bind - * @target: the target #GObject - * @target_property: the property on @target to bind - * @flags: flags to pass to #GBinding - * @transform_to: (scope notified) (allow-none): the transformation function from the @source to the @target, or %NULL to use the default - * @transform_from: (scope notified) (allow-none): the transformation function from the @target to the @source, or %NULL to use the default - * @user_data: custom data to be passed to the transformation functions, or %NULL - * @notify: function to be called when disposing the binding, to free the resources used by the transformation functions - * - * Complete version of g_object_bind_property(). - * Creates a binding between @source_property on @source and @target_property - * on @target, allowing you to set the transformation functions to be used by - * the binding. - * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: - * if @target_property on @target changes then the @source_property on @source - * will be updated as well. The @transform_from function is only used in case - * of bidirectional bindings, otherwise it will be ignored - * The binding will automatically be removed when either the @source or the - * #GBinding instance. - * A #GObject can have multiple bindings. - * <note>The same @user_data parameter will be used for both @transform_to - * and @transform_from transformation functions; the @notify function will - * be called once, when the binding is removed. If you need different data - * for each transformation function, please use - * g_object_bind_property_with_closures() instead.</note> - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * g_cclosure_marshal_VOID__BOXED: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #GBoxed* parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Returns: (transfer none): the #GBinding instance representing the - * Since: 2.26 + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>. */ /** - * GInterfaceFinalizeFunc: - * @g_iface: The interface structure to finalize. - * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. + * g_cclosure_marshal_VOID__CHAR: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gchar parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A callback function used by the type system to finalize an interface. - * This function should destroy any internal data and release any resources - * allocated by the corresponding GInterfaceInitFunc() function. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>. */ /** - * GParamSpecUChar: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_cclosure_marshal_VOID__DOUBLE: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gdouble parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A #GParamSpec derived structure that contains the meta data for unsigned character properties. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>. */ /** - * g_object_get_data: - * @object: #GObject containing the associations - * @key: name of the key for that association - * - * Gets a named field from the objects table of associations (see g_object_set_data()). + * g_cclosure_marshal_VOID__ENUM: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the enumeration parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Returns: (transfer none): the data if found, or %NULL if no such data exists. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type.. */ /** - * g_object_get_property: - * @object: a #GObject - * @property_name: the name of the property to get - * @value: return location for the property value + * g_cclosure_marshal_VOID__FLAGS: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the flags parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Gets a property of an object. @value must have been initialized to the - * expected type of the property (or a type to which the expected type can be - * transformed) using g_value_init(). - * In general, a copy is made of the property contents and the caller is - * responsible for freeing the memory by calling g_value_unset(). - * Note that g_object_get_property() is really intended for language - * bindings, g_object_get() is much more convenient for C programming. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type. */ /** - * G_IS_OBJECT: - * @object: Instance to check for being a %G_TYPE_OBJECT. + * g_cclosure_marshal_VOID__FLOAT: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gfloat parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>. */ /** - * GFlagsValue: - * @value: the flags value - * @value_name: the name of the value - * @value_nick: the nickname of the value + * g_cclosure_marshal_VOID__INT: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gint parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A structure which contains a single flags value, its name, and its - * nickname. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>. */ /** - * g_value_set_uchar: - * @value: a valid #GValue of type %G_TYPE_UCHAR - * @v_uchar: unsigned character value to be set + * g_cclosure_marshal_VOID__LONG: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #glong parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>. */ /** - * G_TYPE_PARAM_UINT: + * g_cclosure_marshal_VOID__OBJECT: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #GObject* parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * The #GType of #GParamSpecUInt. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)</literal>. */ /** - * G_PARAM_SPEC_VALUE_ARRAY: - * @pspec: a valid #GParamSpec instance + * g_cclosure_marshal_VOID__PARAM: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Cast a #GParamSpec instance into a #GParamSpecValueArray. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>. */ /** - * GInstanceInitFunc: - * @instance: The instance to initialize. - * @g_class: The class of the type the instance is created for. + * g_cclosure_marshal_VOID__POINTER: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gpointer parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * A callback function used by the type system to initialize a new - * instance of a type. This function initializes all instance members and - * allocates any resources required by it. - * Initialization of a derived instance involves calling all its parent - * types instance initializers, so the class member of the instance - * is altered during its initialization to always point to the class that - * belongs to the type the current initializer was introduced for. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>. */ /** - * G_VARIANT_TYPE_MAYBE: + * g_cclosure_marshal_VOID__STRING: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gchar* parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * An indefinite type that is a supertype of every maybe type. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>. */ /** - * G_CONVERT_ERROR: + * g_cclosure_marshal_VOID__UCHAR: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #guchar parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Error domain for character set conversions. Errors in this domain will - * be from the #GConvertError enumeration. See #GError for information on - * error domains. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>. */ /** - * g_object_bind_property_with_closures: - * @source: the source #GObject - * @source_property: the property on @source to bind - * @target: the target #GObject - * @target_property: the property on @target to bind - * @flags: flags to pass to #GBinding - * @transform_to: a #GClosure wrapping the transformation function from the @source to the @target, or %NULL to use the default - * @transform_from: a #GClosure wrapping the transformation function from the @target to the @source, or %NULL to use the default - * - * Creates a binding between @source_property on @source and @target_property - * on @target, allowing you to set the transformation functions to be used by - * the binding. - * This function is the language bindings friendly version of - * g_object_bind_property_full(), using #GClosure<!-- -->s instead of - * function pointers. - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * g_cclosure_marshal_VOID__UINT: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #guint parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Rename to: g_object_bind_property_full - * Returns: (transfer none): the #GBinding instance representing the - * Since: 2.26 + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>. */ /** - * g_object_new_valist: (skip) - * @object_type: the type id of the #GObject subtype to instantiate - * @first_property_name: the name of the first property - * @var_args: the value of the first property, followed optionally by more name/value pairs, followed by %NULL - * - * Creates a new instance of a #GObject subtype and sets its properties. - * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. + * g_cclosure_marshal_VOID__UINT_POINTER: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 3 + * @param_values: a #GValue array holding instance, arg1 and arg2 + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Returns: a new instance of @object_type + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>. */ /** - * g_value_unset: - * @value: An initialized #GValue structure. + * g_cclosure_marshal_VOID__ULONG: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #gulong parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Clears the current value in @value and "unsets" the type, - * this releases all resources associated with this GValue. - * An unset value is the same as an uninitialized (zero-filled) - * #GValue structure. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>. */ /** - * GDateTime: + * g_cclosure_marshal_VOID__VARIANT: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 2 + * @param_values: a #GValue array holding the instance and the #GVariant* parameter + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * <structname>GDateTime</structname> is an opaque structure whose members - * cannot be accessed directly. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)</literal>. * * Since: 2.26 */ /** - * G_TIME_SPAN_SECOND: - * - * Evaluates to a time span of one second. + * g_cclosure_marshal_VOID__VOID: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: ignored + * @n_param_values: 1 + * @param_values: a #GValue array holding only the instance + * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @marshal_data: additional data specified when registering the marshaller * - * Since: 2.26 + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>. */ /** - * g_param_spec_get_nick: - * @pspec: a valid #GParamSpec + * g_cclosure_new: (skip) + * @callback_func: the function to invoke + * @user_data: user data to pass to @callback_func + * @destroy_data: destroy notify to be called when @user_data is no longer used * - * Get the nickname of a #GParamSpec. + * Creates a new closure which invokes @callback_func with @user_data as + * the last parameter. * - * Returns: the nickname of @pspec. + * Returns: a new #GCClosure */ /** - * G_TYPE_UINT: + * g_cclosure_new_object: (skip) + * @callback_func: the function to invoke + * @object: a #GObject pointer to pass to @callback_func * - * The fundamental type corresponding to #guint. + * A variant of g_cclosure_new() which uses @object as @user_data and + * calls g_object_watch_closure() on @object and the created + * closure. This function is useful when you have a callback closely + * associated with a #GObject, and want the callback to no longer run + * after the object is is freed. + * + * Returns: a new #GCClosure */ /** - * g_object_force_floating: - * @object: a #GObject + * g_cclosure_new_object_swap: (skip) + * @callback_func: the function to invoke + * @object: a #GObject pointer to pass to @callback_func * - * This function is intended for #GObject implementations to re-enforce a - * <link linkend="floating-ref">floating</link> object reference. - * Doing this is seldomly required, all - * #GInitiallyUnowned<!-- -->s are created with a floating reference which - * usually just needs to be sunken by calling g_object_ref_sink(). + * A variant of g_cclosure_new_swap() which uses @object as @user_data + * and calls g_object_watch_closure() on @object and the created + * closure. This function is useful when you have a callback closely + * associated with a #GObject, and want the callback to no longer run + * after the object is is freed. * - * Since: 2.10 + * Returns: a new #GCClosure */ /** - * g_alloca: - * @size: number of bytes to allocate. + * g_cclosure_new_swap: (skip) + * @callback_func: the function to invoke + * @user_data: user data to pass to @callback_func + * @destroy_data: destroy notify to be called when @user_data is no longer used * - * Allocates @size bytes on the stack; these bytes will be freed when the current - * stack frame is cleaned up. This macro essentially just wraps the alloca() - * function present on most UNIX variants. - * Thus it provides the same advantages and pitfalls as alloca(): - * <variablelist> - * <varlistentry><term></term><listitem><para> - * + alloca() is very fast, as on most systems it's implemented by just adjusting - * the stack pointer register. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * + It doesn't cause any memory fragmentation, within its scope, separate alloca() - * blocks just build up and are released together at function end. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * - Allocation sizes have to fit into the current stack frame. For instance in a - * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, - * so be sparse with alloca() uses. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * - Allocation failure due to insufficient stack space is not indicated with a %NULL - * return like e.g. with malloc(). Instead, most systems probably handle it the same - * way as out of stack space situations from infinite function recursion, i.e. - * with a segmentation fault. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays. - * Stack space allocated with alloca() in the same scope as a variable sized array - * will be freed together with the variable sized array upon exit of that scope, and - * not upon exit of the enclosing function scope. - * </para></listitem></varlistentry> - * </variablelist> + * Creates a new closure which invokes @callback_func with @user_data as + * the first parameter. * - * Returns: space for @size bytes, allocated on the stack + * Returns: (transfer full): a new #GCClosure */ /** - * g_pointer_type_register_static: - * @name: the name of the new pointer type. + * g_clear_object: (skip) + * @object_ptr: a pointer to a #GObject reference * - * Creates a new %G_TYPE_POINTER derived type id for a new - * pointer type with name @name. + * Clears a reference to a #GObject. + * If the reference is %NULL then this function does nothing. + * Otherwise, the reference count of the object is decreased and the + * pointer is set to %NULL. + * This function is threadsafe and modifies the pointer atomically, + * using memory barriers where needed. + * A macro is also included that allows this function to be used without + * pointer casts. * - * Returns: a new %G_TYPE_POINTER derived type id for @name. + * Since: 2.28 */ /** - * G_DEFINE_TYPE_WITH_CODE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * @_C_: Custom code that gets inserted in the *_get_type() function. - * - * A convenience macro for type implementations. - * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the - * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). - * See G_DEFINE_TYPE_EXTENDED() for an example. + * g_closure_add_finalize_notifier: (skip) + * @closure: a #GClosure + * @notify_data: data to pass to @notify_func + * @notify_func: the callback function to register * - * Since: 2.4 + * Registers a finalization notifier which will be called when the + * reference count of @closure goes down to 0. Multiple finalization + * notifiers on a single closure are invoked in unspecified order. If + * a single call to g_closure_unref() results in the closure being + * both invalidated and finalized, then the invalidate notifiers will + * be run before the finalize notifiers. */ /** - * g_cclosure_marshal_STRING__OBJECT_POINTER: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue, which can store the returned string - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_closure_add_invalidate_notifier: (skip) + * @closure: a #GClosure + * @notify_data: data to pass to @notify_func + * @notify_func: the callback function to register * - * A marshaller for a #GCClosure with a callback of type - * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>. + * Registers an invalidation notifier which will be called when the + * notifiers are invoked before finalization notifiers, in an + * unspecified order. */ /** - * g_value_set_param_take_ownership: (skip) - * @value: a valid #GValue of type %G_TYPE_PARAM - * @param: the #GParamSpec to be set - * - * This is an internal function introduced mainly for C marshallers. + * g_closure_add_marshal_guards: (skip) + * @closure: a #GClosure + * @pre_marshal_data: data to pass to @pre_marshal_notify + * @pre_marshal_notify: a function to call before the closure callback + * @post_marshal_data: data to pass to @post_marshal_notify + * @post_marshal_notify: a function to call after the closure callback * - * Deprecated: 2.4: Use g_value_take_param() instead. + * Adds a pair of notifiers which get invoked before and after the + * closure callback, respectively. This is typically used to protect + * the extra arguments for the duration of the callback. See + * g_object_watch_closure() for an example of marshal guards. */ /** - * G_PRIORITY_DEFAULT: + * g_closure_invalidate: + * @closure: GClosure to invalidate * - * Use this for default priority event sources. - * In GLib this priority is used when adding timeout functions - * with g_timeout_add(). In GDK this priority is used for events - * from the X server. + * Sets a flag on the closure to indicate that its calling + * environment has become invalid, and thus causes any future + * invocations of g_closure_invoke() on this @closure to be + * ignored. Also, invalidation notifiers installed on the closure will + * be called at this point. Note that unless you are holding a + * reference to the closure yourself, the invalidation notifiers may + * unref the closure and cause it to be destroyed, so if you need to + * access the closure after calling g_closure_invalidate(), make sure + * that you've previously called g_closure_ref(). + * Note that g_closure_invalidate() will also be called when the + * reference count of a closure drops to zero (unless it has already + * been invalidated before). */ /** - * g_type_class_unref_uncached: (skip) - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. + * g_closure_invoke: + * @closure: a #GClosure + * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. + * @n_param_values: the length of the @param_values array + * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure + * @invocation_hint: a context-dependent invocation hint * - * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc - * implementations. It unreferences a class without consulting the chain - * of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur - * otherwise. + * Invokes the closure, i.e. executes the callback represented by the @closure. */ /** - * g_param_spec_pool_new: - * @type_prefixing: Whether the pool will support type-prefixed property names. + * g_closure_new_object: + * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> + * @object: a #GObject pointer to store in the @data field of the newly allocated #GClosure * - * Creates a new #GParamSpecPool. - * If @type_prefixing is %TRUE, lookups in the newly created pool will - * allow to specify the owner as a colon-separated prefix of the - * property name, like "GtkContainer:border-width". This feature is - * deprecated, so you should always set @type_prefixing to %FALSE. + * A variant of g_closure_new_simple() which stores @object in the + * when implementing new types of closures. * - * Returns: (transfer none): a newly allocated #GParamSpecPool. + * Returns: (transfer full): a newly allocated #GClosure */ /** - * g_cclosure_marshal_BOOLEAN__OBJECT_BOXED_BOXED: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue, which can store the returned string - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_closure_new_simple: + * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> + * @data: data to store in the @data field of the newly allocated #GClosure * - * A marshaller for a #GCClosure with a callback of type - * <literal>gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)</literal>. + * Allocates a struct of the given size and initializes the initial + * part as a #GClosure. This function is mainly useful when + * implementing new types of closures. + * |[ + * typedef struct _MyClosure MyClosure; + * struct _MyClosure + * { + * GClosure closure; + * // extra data goes here + * }; + * static void + * my_closure_finalize (gpointer notify_data, + * GClosure *closure) + * { + * MyClosure *my_closure = (MyClosure *)closure; + * // free extra data here + * } + * MyClosure *my_closure_new (gpointer data) + * { + * GClosure *closure; + * MyClosure *my_closure; + * closure = g_closure_new_simple (sizeof (MyClosure), data); + * my_closure = (MyClosure *) closure; + * // initialize extra data here + * g_closure_add_finalize_notifier (closure, notify_data, + * my_closure_finalize); + * return my_closure; + * } + * ]| * - * Since: 2.26 + * Returns: (transfer full): a newly allocated #GClosure */ /** - * G_TYPE_IS_PARAM: - * @type: a #GType ID + * g_closure_ref: + * @closure: #GClosure to increment the reference count on * - * Checks whether @type "is a" %G_TYPE_PARAM. + * Increments the reference count on a closure to force it staying + * alive while the caller holds a pointer to it. + * + * Returns: (transfer none): The @closure passed in, for convenience */ /** - * g_flags_get_value_by_name: - * @flags_class: a #GFlagsClass - * @name: the name to look up - * - * Looks up a #GFlagsValue by name. - * flag with that name + * g_closure_remove_finalize_notifier: (skip) + * @closure: a #GClosure + * @notify_data: data which was passed to g_closure_add_finalize_notifier() when registering @notify_func + * @notify_func: the callback function to remove * - * Returns: the #GFlagsValue with name @name, or %NULL if there is no + * Removes a finalization notifier. + * Notice that notifiers are automatically removed after they are run. */ /** - * g_type_add_interface_dynamic: - * @instance_type: the #GType value of an instantiable type. - * @interface_type: the #GType value of an interface type. - * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. + * g_closure_remove_invalidate_notifier: (skip) + * @closure: a #GClosure + * @notify_data: data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func + * @notify_func: the callback function to remove * - * Adds the dynamic @interface_type to @instantiable_type. The information - * contained in the #GTypePlugin structure pointed to by @plugin - * is used to manage the relationship. + * Removes an invalidation notifier. + * Notice that notifiers are automatically removed after they are run. */ /** - * g_value_get_uint: - * @value: a valid #GValue of type %G_TYPE_UINT - * - * Get the contents of a %G_TYPE_UINT #GValue. + * g_closure_set_marshal: (skip) + * @closure: a #GClosure + * @marshal: a #GClosureMarshal function * - * Returns: unsigned integer contents of @value + * Sets the marshaller of @closure. The <literal>marshal_data</literal> + * of @marshal provides a way for a meta marshaller to provide additional + * information to the marshaller. (See g_closure_set_meta_marshal().) For + * GObject's C predefined marshallers (the g_cclosure_marshal_*() + * functions), what it provides is a callback function to use instead of */ /** - * G_TYPE_CHECK_CLASS_CAST: - * @g_class: Location of a #GTypeClass structure. - * @g_type: The type to be returned. - * @c_type: The corresponding C type of class structure of @g_type. + * g_closure_set_meta_marshal: (skip) + * @closure: a #GClosure + * @marshal_data: context-dependent data to pass to @meta_marshal + * @meta_marshal: a #GClosureMarshal function * - * Checks that @g_class is a class structure of the type identified by @g_type - * and issues a warning if this is not the case. Returns @g_class casted - * to a pointer to @c_type. - * This macro should only be used in type implementations. + * Sets the meta marshaller of @closure. A meta marshaller wraps + * fashion. The most common use of this facility is for C callbacks. + * The same marshallers (generated by <link + * linkend="glib-genmarshal">glib-genmarshal</link>) are used + * everywhere, but the way that we get the callback function + * differs. In most cases we want to use @closure->callback, but in + * other cases we want to use some different technique to retrieve the + * callback function. + * For example, class closures for signals (see + * g_signal_type_cclosure_new()) retrieve the callback function from a + * fixed offset in the class structure. The meta marshaller retrieves + * the right callback and passes it to the marshaller as the */ /** - * G_IS_ENUM_CLASS: - * @class: a #GEnumClass + * g_closure_sink: + * @closure: #GClosure to decrement the initial reference count on, if it's still being held * - * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM - * or derived. + * Takes over the initial ownership of a closure. Each closure is + * initially created in a <firstterm>floating</firstterm> state, which + * means that the initial reference count is not owned by any caller. + * g_closure_sink() checks to see if the object is still floating, and + * if so, unsets the floating state and decreases the reference + * count. If the closure is not floating, g_closure_sink() does + * nothing. The reason for the existance of the floating state is to + * prevent cumbersome code sequences like: + * |[ + * closure = g_cclosure_new (cb_func, cb_data); + * g_source_set_closure (source, closure); + * g_closure_unref (closure); // XXX GObject doesn't really need this + * ]| + * Because g_source_set_closure() (and similar functions) take ownership of the + * initial reference count, if it is unowned, we instead can write: + * |[ + * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); + * ]| + * Generally, this function is used together with g_closure_ref(). Ane example + * of storing a closure for later notification looks like: + * |[ + * static GClosure *notify_closure = NULL; + * void + * foo_notify_set_closure (GClosure *closure) + * { + * if (notify_closure) + * g_closure_unref (notify_closure); + * notify_closure = closure; + * if (notify_closure) + * { + * g_closure_ref (notify_closure); + * g_closure_sink (notify_closure); + * } + * } + * ]| + * Because g_closure_sink() may decrement the reference count of a closure + * (if it hasn't been called on @closure yet) just like g_closure_unref(), + * g_closure_ref() should be called prior to this function. */ /** - * g_node_next_sibling: - * @node: a #GNode - * - * Gets the next sibling of a #GNode. - * or %NULL + * g_closure_unref: + * @closure: #GClosure to decrement the reference count on * - * Returns: the next sibling of @node, or %NULL if @node is the last node + * Decrements the reference count of a closure after it was previously + * incremented by the same caller. If no other callers are using the + * closure, then the closure will be destroyed and freed. */ /** - * g_object_notify_by_pspec: - * @object: a #GObject - * @pspec: the #GParamSpec of a property installed on the class of @object. + * g_enum_complete_type_info: + * @g_enum_type: the type identifier of the type being completed + * @info: the #GTypeInfo struct to be filled in + * @const_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. * - * Emits a "notify" signal for the property specified by @pspec on @object. - * This function omits the property name lookup, hence it is faster than - * g_object_notify(). - * One way to avoid using g_object_notify() from within the - * class that registered the properties, and using g_object_notify_by_pspec() - * instead, is to store the GParamSpec used with - * g_object_class_install_property() inside a static array, e.g.: + * This function is meant to be called from the complete_type_info() + * function of a #GTypePlugin implementation, as in the following + * example: * |[ - * enum - * { - * PROP_0, - * PROP_FOO, - * PROP_LAST - * }; - * static GParamSpec *properties[PROP_LAST]; * static void - * my_object_class_init (MyObjectClass *klass) + * my_enum_complete_type_info (GTypePlugin *plugin, + * GType g_type, + * GTypeInfo *info, + * GTypeValueTable *value_table) * { - * properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", - * 0, 100, - * 50, - * G_PARAM_READWRITE); - * g_object_class_install_property (gobject_class, - * PROP_FOO, - * properties[PROP_FOO]); + * static const GEnumValue values[] = { + * { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, + * { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, + * { 0, NULL, NULL } + * }; + * g_enum_complete_type_info (type, info, values); * } * ]| - * and then notify a change on the "foo" property with: - * |[ - * g_object_notify_by_pspec (self, properties[PROP_FOO]); - * ]| + */ + + +/** + * g_enum_get_value: + * @enum_class: a #GEnumClass + * @value: the value to look up * - * Since: 2.26 + * Returns the #GEnumValue for a value. + * member of the enumeration + * + * Returns: the #GEnumValue for @value, or %NULL if @value is not a */ /** - * g_cclosure_new_object: (skip) - * @callback_func: the function to invoke - * @object: a #GObject pointer to pass to @callback_func + * g_enum_get_value_by_name: + * @enum_class: a #GEnumClass + * @name: the name to look up * - * A variant of g_cclosure_new() which uses @object as @user_data and - * calls g_object_watch_closure() on @object and the created - * closure. This function is useful when you have a callback closely - * associated with a #GObject, and want the callback to no longer run - * after the object is is freed. + * Looks up a #GEnumValue by name. + * enumeration doesn't have a member with that name * - * Returns: a new #GCClosure + * Returns: the #GEnumValue with name @name, or %NULL if the */ /** - * g_node_append: - * @parent: the #GNode to place the new #GNode under - * @node: the #GNode to insert + * g_enum_get_value_by_nick: + * @enum_class: a #GEnumClass + * @nick: the nickname to look up * - * Inserts a #GNode as the last child of the given parent. + * Looks up a #GEnumValue by nickname. + * enumeration doesn't have a member with that nickname * - * Returns: the inserted #GNode + * Returns: the #GEnumValue with nickname @nick, or %NULL if the */ /** - * g_object_remove_toggle_ref: (skip) - * @object: a #GObject - * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. - * @data: data to pass to @notify + * g_enum_register_static: + * @name: A nul-terminated string used as the name of the new type. + * @const_static_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. * - * Removes a reference added with g_object_add_toggle_ref(). The - * reference count of the object is decreased by one. + * Registers a new static enumeration type with the name @name. + * It is normally more convenient to let <link + * linkend="glib-mkenums">glib-mkenums</link> generate a + * my_enum_get_type() function from a usual C enumeration definition + * than to write one yourself using g_enum_register_static(). * - * Since: 2.8 + * Returns: The new type identifier. */ /** - * g_object_thaw_notify: - * @object: a #GObject + * g_flags_complete_type_info: + * @g_flags_type: the type identifier of the type being completed + * @info: the #GTypeInfo struct to be filled in + * @const_values: An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. * - * Reverts the effect of a previous call to - * g_object_freeze_notify(). The freeze count is decreased on @object - * and when it reaches zero, all queued "notify" signals are emitted. - * It is an error to call this function when the freeze count is zero. + * This function is meant to be called from the complete_type_info() + * function of a #GTypePlugin implementation, see the example for + * g_enum_complete_type_info() above. */ /** - * g_value_set_uint64: - * @value: a valid #GValue of type %G_TYPE_UINT64 - * @v_uint64: unsigned 64bit integer value to be set + * g_flags_get_first_value: + * @flags_class: a #GFlagsClass + * @value: the value * - * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. + * Returns the first #GFlagsValue which is set in @value. + * none is set + * + * Returns: the first #GFlagsValue which is set in @value, or %NULL if */ /** - * GTimeSpan: + * g_flags_get_value_by_name: + * @flags_class: a #GFlagsClass + * @name: the name to look up * - * A value representing an interval of time, in microseconds. + * Looks up a #GFlagsValue by name. + * flag with that name * - * Since: 2.26 + * Returns: the #GFlagsValue with name @name, or %NULL if there is no */ /** - * GParamSpec: - * @g_type_instance: private #GTypeInstance portion - * @name: name of this parameter - * @flags: #GParamFlags flags for this parameter - * @value_type: the #GValue type for this parameter - * @owner_type: #GType type that uses (introduces) this parameter + * g_flags_get_value_by_nick: + * @flags_class: a #GFlagsClass + * @nick: the nickname to look up * - * All other fields of the <structname>GParamSpec</structname> struct are private and - * should not be used directly. + * Looks up a #GFlagsValue by nickname. + * no flag with that nickname + * + * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is */ /** - * G_TYPE_IS_OBJECT: - * @type: Type id to check + * g_flags_register_static: + * @name: A nul-terminated string used as the name of the new type. + * @const_static_values: An array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. * - * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. + * Registers a new static flags type with the name @name. + * It is normally more convenient to let <link + * linkend="glib-mkenums">glib-mkenums</link> generate a + * my_flags_get_type() function from a usual C enumeration definition + * than to write one yourself using g_flags_register_static(). * - * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT. + * Returns: The new type identifier. */ /** - * g_signal_stop_emission: - * @instance: the object whose signal handlers you wish to stop. - * @signal_id: the signal identifier, as returned by g_signal_lookup(). - * @detail: the detail which the signal was emitted with. + * g_hash_table_freeze: + * @hash_table: a #GHashTable * - * Stops a signal's current emission. - * This will prevent the default method from running, if the signal was - * %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" - * flag). - * Prints a warning if used on a signal which isn't being emitted. + * This function is deprecated and will be removed in the next major + * release of GLib. It does nothing. */ /** - * g_cclosure_marshal_VOID__UINT_POINTER: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_hash_table_thaw: + * @hash_table: a #GHashTable * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>. + * This function is deprecated and will be removed in the next major + * release of GLib. It does nothing. */ /** - * G_VALUE_HOLDS_FLOAT: - * @value: a valid #GValue structure + * g_main_destroy: + * @loop: a #GMainLoop * - * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. + * Frees the memory allocated for the #GMainLoop. * - * Returns: %TRUE on success. + * Deprecated: 2.2: Use g_main_loop_unref() instead */ /** - * g_type_class_unref: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. + * g_main_is_running: + * @loop: a #GMainLoop * - * Decrements the reference count of the class structure being passed in. - * Once the last reference count of a class has been released, classes - * may be finalized by the type system, so further dereferencing of a - * class pointer after g_type_class_unref() are invalid. + * Checks if the main loop is running. + * + * Returns: %TRUE if the main loop is running + * Deprecated: 2.2: Use g_main_loop_is_running() instead */ /** - * g_value_set_int: - * @value: a valid #GValue of type %G_TYPE_INT - * @v_int: integer value to be set + * g_main_iteration: + * @may_block: set to %TRUE if it should block (i.e. wait) until an event source becomes ready. It will return after an event source has been processed. If set to %FALSE it will return immediately if no event source is ready to be processed. * - * Set the contents of a %G_TYPE_INT #GValue to @v_int. + * Runs a single iteration for the default #GMainContext. + * + * Returns: %TRUE if more events are pending. + * Deprecated: 2.2: Use g_main_context_iteration() instead. */ /** - * g_param_spec_long: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * g_main_new: + * @is_running: set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_run() will set this to %TRUE anyway. * - * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. - * See g_param_spec_internal() for details on property names. + * Creates a new #GMainLoop for th default main context. * - * Returns: a newly created parameter specification + * Returns: a new #GMainLoop + * Deprecated: 2.2: Use g_main_loop_new() instead */ /** - * g_value_dup_string: - * @value: a valid #GValue of type %G_TYPE_STRING + * g_main_pending: * - * Get a copy the contents of a %G_TYPE_STRING #GValue. + * Checks if any events are pending for the default #GMainContext + * (i.e. ready to be processed). * - * Returns: a newly allocated copy of the string content of @value + * Returns: %TRUE if any events are pending. + * Deprected: 2.2: Use g_main_context_pending() instead. */ /** - * G_TYPE_RESERVED_BSE_LAST: + * g_main_quit: + * @loop: a #GMainLoop * - * Last fundamental type number reserved for BSE. + * Stops the #GMainLoop. + * If g_main_run() was called to run the #GMainLoop, it will now return. + * + * Deprecated: 2.2: Use g_main_loop_quit() instead */ /** - * g_value_set_object_take_ownership: (skip) - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * @v_object: object value to be set + * g_main_run: + * @loop: a #GMainLoop * - * This is an internal function introduced mainly for C marshallers. + * Runs a main loop until it stops running. * - * Deprecated: 2.4: Use g_value_take_object() instead. + * Deprecated: 2.2: Use g_main_loop_run() instead */ /** - * g_value_set_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: boxed value to be set + * g_main_set_poll_func: + * @func: the function to call to poll all file descriptors * - * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + * Sets the function to use for the handle polling of file descriptors + * for the default main context. + * + * Deprecated: 2.2: Use g_main_context_set_poll_func() again */ /** - * SECTION:gclosur: - * @short_description: Functions as first-class objects - * @title: Closures + * g_new: + * @struct_type: the type of the elements to allocate + * @n_structs: the number of elements to allocate * - * A #GClosure represents a callback supplied by the programmer. It - * will generally comprise a function of some kind and a marshaller - * used to call it. It is the reponsibility of the marshaller to - * convert the arguments for the invocation from #GValue<!-- -->s into - * a suitable form, perform the callback on the converted arguments, - * and transform the return value back into a #GValue. - * In the case of C programs, a closure usually just holds a pointer - * to a function and maybe a data argument, and the marshaller - * converts between #GValue<!-- --> and native C types. The GObject - * library provides the #GCClosure type for this purpose. Bindings for - * other languages need marshallers which convert between #GValue<!-- - * -->s and suitable representations in the runtime of the language in - * order to use functions written in that languages as callbacks. - * Within GObject, closures play an important role in the - * implementation of signals. When a signal is registered, the - * marshaller for any closure which is connected to this - * signal. GObject provides a number of C marshallers for this - * purpose, see the g_cclosure_marshal_*() functions. Additional C - * marshallers can be generated with the <link - * linkend="glib-genmarshal">glib-genmarshal</link> utility. Closures - * can be explicitly connected to signals with - * g_signal_connect_closure(), but it usually more convenient to let - * GObject create a closure automatically by using one of the - * g_signal_connect_*() functions which take a callback function/user - * data pair. - * Using closures has a number of important advantages over a simple - * callback function/data pointer combination: - * <itemizedlist> - * <listitem><para> - * Closures allow the callee to get the types of the callback parameters, - * which means that language bindings don't have to write individual glue - * for each callback type. - * </para></listitem> - * <listitem><para> - * The reference counting of #GClosure makes it easy to handle reentrancy - * right; if a callback is removed while it is being invoked, the closure - * and its parameters won't be freed until the invocation finishes. - * </para></listitem> - * <listitem><para> - * g_closure_invalidate() and invalidation notifiers allow callbacks to be - * automatically removed when the objects they point to go away. - * </para></listitem> - * </itemizedlist> + * Allocates @n_structs elements of type @struct_type. + * The returned pointer is cast to a pointer to the given type. + * If @n_structs is 0 it returns %NULL. + * Care is taken to avoid overflow when calculating the size of the allocated block. + * Since the returned pointer is already casted to the right type, + * it is normally unnecessary to cast it explicitly, and doing + * so might hide memory allocation errors. + * + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type */ /** - * GParamSpecInt: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_new0: + * @struct_type: the type of the elements to allocate. + * @n_structs: the number of elements to allocate. * - * A #GParamSpec derived structure that contains the meta data for integer properties. + * Allocates @n_structs elements of type @struct_type, initialized to 0's. + * The returned pointer is cast to a pointer to the given type. + * If @n_structs is 0 it returns %NULL. + * Care is taken to avoid overflow when calculating the size of the allocated block. + * Since the returned pointer is already casted to the right type, + * it is normally unnecessary to cast it explicitly, and doing + * so might hide memory allocation errors. + * + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. */ /** - * G_VARIANT_TYPE_DICT_ENTRY: + * g_newa: + * @struct_type: Type of memory chunks to be allocated + * @n_structs: Number of chunks to be allocated * - * An indefinite type that is a supertype of every dictionary entry - * type. + * Wraps g_alloca() in a more typesafe manner. + * + * Returns: Pointer to stack space for @n_structs chunks of type @struct_type */ /** - * g_type_add_interface_static: - * @instance_type: #GType value of an instantiable type. - * @interface_type: #GType value of an interface type. - * @info: The #GInterfaceInfo structure for this (@instance_type, @interface_type) combination. + * g_node_append: + * @parent: the #GNode to place the new #GNode under + * @node: the #GNode to insert * - * Adds the static @interface_type to @instantiable_type. The information - * contained in the #GTypeInterfaceInfo structure pointed to by @info - * is used to manage the relationship. + * Inserts a #GNode as the last child of the given parent. + * + * Returns: the inserted #GNode */ /** - * G_SIGNAL_FLAGS_MASK: + * g_node_append_data: + * @parent: the #GNode to place the new #GNode under + * @data: the data for the new #GNode * - * A mask for all #GSignalFlags bits. + * Inserts a new #GNode as the last child of the given parent. + * + * Returns: the new #GNode */ /** - * g_signal_get_invocation_hint: - * @instance: the instance to query + * g_node_first_child: + * @node: a #GNode * - * Returns the invocation hint of the innermost signal emission of instance. + * Gets the first child of a #GNode. + * or has no children * - * Returns: the invocation hint of the innermost signal emission. + * Returns: the first child of @node, or %NULL if @node is %NULL */ /** - * g_type_get_plugin: - * @type: The #GType to retrieve the plugin for. + * g_node_insert_data: + * @parent: the #GNode to place the new #GNode under + * @position: the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent + * @data: the data for the new #GNode * - * Returns the #GTypePlugin structure for @type or - * %NULL if @type does not have a #GTypePlugin structure. - * dynamic type, %NULL otherwise. + * Inserts a new #GNode at the given position. * - * Returns: (transfer none): The corresponding plugin if @type is a + * Returns: the new #GNode */ /** - * g_signal_parse_name: - * @detailed_signal: a string of the form "signal-name::detail". - * @itype: The interface/instance type that introduced "signal-name". - * @signal_id_p: Location to store the signal id. - * @detail_p: Location to store the detail quark. - * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail. + * g_node_insert_data_before: + * @parent: the #GNode to place the new #GNode under + * @sibling: the sibling #GNode to place the new #GNode before + * @data: the data for the new #GNode * - * Internal function to parse a signal name into its @signal_id - * and @detail quark. + * Inserts a new #GNode before the given sibling. * - * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. + * Returns: the new #GNode */ /** - * G_IMPLEMENT_INTERFACE_DYNAMIC: - * @TYPE_IFACE: The #GType of the interface to add - * @iface_init: The interface init function + * g_node_next_sibling: + * @node: a #GNode * - * A convenience macro to ease interface addition in the @_C_ section - * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() - * for an example. - * Note that this macro can only be used together with the - * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable - * names from that macro. + * Gets the next sibling of a #GNode. + * or %NULL * - * Since: 2.24 + * Returns: the next sibling of @node, or %NULL if @node is the last node */ /** - * g_param_spec_int: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * g_node_prepend_data: + * @parent: the #GNode to place the new #GNode under + * @data: the data for the new #GNode * - * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. - * See g_param_spec_internal() for details on property names. + * Inserts a new #GNode as the first child of the given parent. * - * Returns: a newly created parameter specification + * Returns: the new #GNode */ /** - * g_closure_invoke: - * @closure: a #GClosure - * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. - * @n_param_values: the length of the @param_values array - * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure - * @invocation_hint: a context-dependent invocation hint + * g_node_prev_sibling: + * @node: a #GNode * - * Invokes the closure, i.e. executes the callback represented by the @closure. + * Gets the previous sibling of a #GNode. + * node or %NULL + * + * Returns: the previous sibling of @node, or %NULL if @node is the first */ /** - * g_cclosure_marshal_VOID__ULONG: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gulong parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_object_add_toggle_ref: (skip) + * @object: a #GObject + * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. + * @data: data to pass to @notify * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>. + * Increases the reference count of the object by one and sets a + * callback to be called when all other references to the object are + * dropped, or when this is already the last reference to the object + * and another reference is established. + * This functionality is intended for binding @object to a proxy + * object managed by another memory manager. This is done with two + * g_object_add_toggle_ref() and a reverse reference to the proxy + * object which is either a strong reference or weak reference. + * The setup is that when there are no other references to @object, + * only a weak reference is held in the reverse direction from @object + * to the proxy object, but when there are other references held to + * when the reference from @object to the proxy object should be + * <firstterm>toggled</firstterm> from strong to weak (@is_last_ref + * true) or weak to strong (@is_last_ref false). + * Since a (normal) reference must be held to the object before + * calling g_object_toggle_ref(), the initial state of the reverse + * link is always strong. + * Multiple toggle references may be added to the same gobject, + * however if there are multiple toggle references to an object, none + * of them will ever be notified until all but one are removed. For + * this reason, you should only ever use a toggle reference if there + * is important state in the proxy object. + * + * Paired references: the strong reference added by + * Since: 2.8 */ /** - * G_DEFINE_BOXED_TYPE_WITH_CODE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @copy_func: the #GBoxedCopyFunc for the new type - * @free_func: the #GBoxedFreeFunc for the new type - * @_C_: Custom code that gets inserted in the *_get_type() function. - * - * A convenience macro for boxed type implementations. - * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the - * type_name_get_type() function, e.g. to register value transformations with - * g_value_register_transform_func(). + * g_object_add_weak_pointer: (skip) + * @object: The object that should be weak referenced. + * @weak_pointer_location: (inout): The memory address of a pointer. * - * Since: 2.26 + * Adds a weak reference from weak_pointer to @object to indicate that + * the pointer located at @weak_pointer_location is only valid during + * the lifetime of @object. When the @object is finalized, */ @@ -7437,42 +6497,185 @@ /** - * SECTION:param_value_type: - * @short_description: Standard Parameter and Value Types - * @see_also: #GParamSpec, #GValue, g_object_class_install_property(). - * @title: Parameters and Values + * g_object_bind_property_full: + * @source: the source #GObject + * @source_property: the property on @source to bind + * @target: the target #GObject + * @target_property: the property on @target to bind + * @flags: flags to pass to #GBinding + * @transform_to: (scope notified) (allow-none): the transformation function from the @source to the @target, or %NULL to use the default + * @transform_from: (scope notified) (allow-none): the transformation function from the @target to the @source, or %NULL to use the default + * @user_data: custom data to be passed to the transformation functions, or %NULL + * @notify: function to be called when disposing the binding, to free the resources used by the transformation functions * - * #GValue provides an abstract container structure which can be - * copied, transformed and compared while holding a value of any - * (derived) type, which is registered as a #GType with a - * #GTypeValueTable in its #GTypeInfo structure. Parameter - * specifications for most value types can be created as #GParamSpec - * derived instances, to implement e.g. #GObject properties which - * operate on #GValue containers. - * Parameter names need to start with a letter (a-z or A-Z). Subsequent - * characters can be letters, numbers or a '-'. - * All other characters are replaced by a '-' during construction. + * Complete version of g_object_bind_property(). + * Creates a binding between @source_property on @source and @target_property + * on @target, allowing you to set the transformation functions to be used by + * the binding. + * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: + * if @target_property on @target changes then the @source_property on @source + * will be updated as well. The @transform_from function is only used in case + * of bidirectional bindings, otherwise it will be ignored + * The binding will automatically be removed when either the @source or the + * #GBinding instance. + * A #GObject can have multiple bindings. + * <note>The same @user_data parameter will be used for both @transform_to + * and @transform_from transformation functions; the @notify function will + * be called once, when the binding is removed. If you need different data + * for each transformation function, please use + * g_object_bind_property_with_closures() instead.</note> + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. + * + * Returns: (transfer none): the #GBinding instance representing the + * Since: 2.26 */ /** - * g_binding_get_source: - * @binding: a #GBinding + * g_object_bind_property_with_closures: + * @source: the source #GObject + * @source_property: the property on @source to bind + * @target: the target #GObject + * @target_property: the property on @target to bind + * @flags: flags to pass to #GBinding + * @transform_to: a #GClosure wrapping the transformation function from the @source to the @target, or %NULL to use the default + * @transform_from: a #GClosure wrapping the transformation function from the @target to the @source, or %NULL to use the default * - * Retrieves the #GObject instance used as the source of the binding + * Creates a binding between @source_property on @source and @target_property + * on @target, allowing you to set the transformation functions to be used by + * the binding. + * This function is the language bindings friendly version of + * g_object_bind_property_full(), using #GClosure<!-- -->s instead of + * function pointers. + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * - * Returns: (transfer none): the source #GObject + * Rename to: g_object_bind_property_full + * Returns: (transfer none): the #GBinding instance representing the * Since: 2.26 */ /** - * G_IS_PARAM_SPEC_POINTER: - * @pspec: a valid #GParamSpec instance + * g_object_class_find_property: + * @oclass: a #GObjectClass + * @property_name: the name of the property to look up * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. + * Looks up the #GParamSpec for a property of a class. + * %NULL if the class doesn't have a property of that name * - * Returns: %TRUE on success. + * Returns: (transfer none): the #GParamSpec for the property, or + */ + + +/** + * g_object_class_install_properties: + * @oclass: a #GObjectClass + * @n_pspecs: the length of the #GParamSpec<!-- -->s array + * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array defining the new properties + * + * Installs new properties from an array of #GParamSpec<!-- -->s. This is + * usually done in the class initializer. + * The property id of each property is the index of each #GParamSpec in + * the @pspecs array. + * The property id of 0 is treated specially by #GObject and it should not + * be used to store a #GParamSpec. + * This function should be used if you plan to use a static array of + * #GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this + * class initialization: + * |[ + * enum { + * PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES + * }; + * static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, }; + * static void + * my_object_class_init (MyObjectClass *klass) + * { + * GObjectClass *gobject_class = G_OBJECT_CLASS (klass); + * obj_properties[PROP_FOO] = + * g_param_spec_int ("foo", "Foo", "Foo", + * -1, G_MAXINT, + * 0, + * G_PARAM_READWRITE); + * obj_properties[PROP_BAR] = + * g_param_spec_string ("bar", "Bar", "Bar", + * NULL, + * G_PARAM_READWRITE); + * gobject_class->set_property = my_object_set_property; + * gobject_class->get_property = my_object_get_property; + * g_object_class_install_properties (gobject_class, + * N_PROPERTIES, + * obj_properties); + * } + * ]| + * allows calling g_object_notify_by_pspec() to notify of property changes: + * |[ + * void + * my_object_set_foo (MyObject *self, gint foo) + * { + * if (self->foo != foo) + * { + * self->foo = foo; + * g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]); + * } + * } + * ]| + * + * Since: 2.26 + */ + + +/** + * g_object_class_install_property: + * @oclass: a #GObjectClass + * @property_id: the id for the new property + * @pspec: the #GParamSpec for the new property + * + * Installs a new property. This is usually done in the class initializer. + * Note that it is possible to redefine a property in a derived class, + * by installing a property with the same name. This can be useful at times, + * e.g. to change the range of allowed values or the default value. + */ + + +/** + * g_object_class_list_properties: + * @oclass: a #GObjectClass + * @n_properties: (out): return location for the length of the returned array + * + * Get an array of #GParamSpec* for all properties of a class. + * #GParamSpec* which should be freed after use + * + * Returns: (array length=n_properties) (transfer container): an array of + */ + + +/** + * g_object_class_override_property: + * @oclass: a #GObjectClass + * @property_id: the new property ID + * @name: the name of a property registered in a parent class or in an interface of this class. + * + * Registers @property_id as referring to a property with the + * name @name in a parent class or in an interface implemented + * by @oclass. This allows this class to <firstterm>override</firstterm> + * a property implementation in a parent class or to provide + * the implementation of a property from an interface. + * <note> + * Internally, overriding is implemented by creating a property of type + * #GParamSpecOverride; generally operations that query the properties of + * the object class, such as g_object_class_find_property() or + * g_object_class_list_properties() will return the overridden + * property. However, in one case, the @construct_properties argument of + * the @constructor virtual function, the #GParamSpecOverride is passed + * instead, so that the @param_id field of the #GParamSpec will be + * correct. For virtually all uses, this makes no difference. If you + * need to get the overridden property, you can call + * g_param_spec_get_redirect_target(). + * </note> + * + * Since: 2.4 */ @@ -7558,906 +6761,1322 @@ /** - * g_cclosure_marshal_VOID__FLAGS: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the flags parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_object_disconnect: (skip) + * @object: a #GObject + * @signal_spec: the spec for the first signal + * @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type. + * A convenience function to disconnect multiple signals at once. + * The signal specs expected by this function have the form + * "any_signal", which means to disconnect any signal with matching + * callback and data, or "any_signal::signal_name", which only + * disconnects the signal named "signal_name". */ /** - * GClosure: - * @in_marshal: Indicates whether the closure is currently being invoked with g_closure_invoke() - * @is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate() + * g_object_force_floating: + * @object: a #GObject * - * A #GClosure represents a callback supplied by the programmer. + * This function is intended for #GObject implementations to re-enforce a + * <link linkend="floating-ref">floating</link> object reference. + * Doing this is seldomly required, all + * #GInitiallyUnowned<!-- -->s are created with a floating reference which + * usually just needs to be sunken by calling g_object_ref_sink(). + * + * Since: 2.10 */ /** - * G_TIME_SPAN_MINUTE: + * g_object_freeze_notify: + * @object: a #GObject * - * Evaluates to a time span of one minute. + * Increases the freeze count on @object. If the freeze count is + * non-zero, the emission of "notify" signals on @object is + * stopped. The signals are queued until the freeze count is decreased + * to zero. + * This is necessary for accessors that modify multiple properties to prevent + * premature notification while the object is still being modified. + */ + + +/** + * g_object_get: (skip) + * @object: a #GObject + * @first_property_name: name of the first property to get + * @...: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL * - * Since: 2.26 + * Gets properties of an object. + * In general, a copy is made of the property contents and the caller + * is responsible for freeing the memory in the appropriate manner for + * the type, for instance by calling g_free() or g_object_unref(). + * <example> + * <title>Using g_object_get(<!-- -->)</title> + * An example of using g_object_get() to get the contents + * of three properties - one of type #G_TYPE_INT, + * one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT: + * <programlisting> + * gint intval; + * gchar *strval; + * GObject *objval; + * g_object_get (my_object, + * "int-property", &intval, + * "str-property", &strval, + * "obj-property", &objval, + * NULL); + * // Do something with intval, strval, objval + * g_free (strval); + * g_object_unref (objval); + * </programlisting> + * </example> */ /** - * G_DEFINE_BOXED_TYPE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @copy_func: the #GBoxedCopyFunc for the new type - * @free_func: the #GBoxedFreeFunc for the new type + * g_object_get_data: + * @object: #GObject containing the associations + * @key: name of the key for that association * - * A convenience macro for boxed type implementations, which defines a - * type_name_get_type() function registering the boxed type. + * Gets a named field from the objects table of associations (see g_object_set_data()). * - * Since: 2.26 + * Returns: (transfer none): the data if found, or %NULL if no such data exists. */ /** - * GSignalCMarshaller: + * g_object_get_property: + * @object: a #GObject + * @property_name: the name of the property to get + * @value: return location for the property value * - * This is the signature of marshaller functions, required to marshall - * arrays of parameter values to signal emissions into C language callback - * invocations. It is merely an alias to #GClosureMarshal since the #GClosure - * mechanism takes over responsibility of actual function invocation for the - * signal system. + * Gets a property of an object. @value must have been initialized to the + * expected type of the property (or a type to which the expected type can be + * transformed) using g_value_init(). + * In general, a copy is made of the property contents and the caller is + * responsible for freeing the memory by calling g_value_unset(). + * Note that g_object_get_property() is really intended for language + * bindings, g_object_get() is much more convenient for C programming. */ /** - * g_signal_handlers_disconnect_matched: - * @instance: The instance to remove handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. - * @signal_id: Signal the handlers have to be connected to. - * @detail: Signal detail the handlers have to be connected to. - * @closure: The closure the handlers will invoke. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * g_object_get_qdata: + * @object: The GObject to get a stored user data pointer from + * @quark: A #GQuark, naming the user data pointer * - * Disconnects all handlers on an instance that match a certain - * selection criteria. The criteria mask is passed as an OR-ed - * combination of #GSignalMatchType flags, and the criteria values are - * passed as arguments. Passing at least one of the - * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or - * %G_SIGNAL_MATCH_DATA match flags is required for successful - * matches. If no handlers were found, 0 is returned, the number of - * disconnected handlers otherwise. + * This function gets back user data pointers stored via + * g_object_set_qdata(). * - * Returns: The number of handlers that matched. + * Returns: (transfer none): The user data pointer set, or %NULL */ /** - * g_cclosure_marshal_VOID__LONG: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #glong parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_object_get_valist: (skip) + * @object: a #GObject + * @first_property_name: name of the first property to get + * @var_args: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>. + * Gets properties of an object. + * In general, a copy is made of the property contents and the caller + * is responsible for freeing the memory in the appropriate manner for + * the type, for instance by calling g_free() or g_object_unref(). + * See g_object_get(). */ /** - * G_TYPE_PARAM_UNICHAR: + * g_object_interface_find_property: + * @g_iface: any interface vtable for the interface, or the default vtable for the interface + * @property_name: name of a property to lookup. * - * The #GType of #GParamSpecUnichar. + * Find the #GParamSpec with the given name for an + * interface. Generally, the interface vtable passed in as @g_iface + * will be the default vtable from g_type_default_interface_ref(), or, + * if you know the interface has already been loaded, + * g_type_default_interface_peek(). + * interface with the name @property_name, or %NULL if no + * such property exists. + * + * Since: 2.4 + * Returns: (transfer none): the #GParamSpec for the property of the */ /** - * G_TYPE_VALUE_ARRAY: + * g_object_interface_install_property: + * @g_iface: any interface vtable for the interface, or the default vtable for the interface. + * @pspec: the #GParamSpec for the new property * - * The type ID of the "GValueArray" type which is a boxed type, - * used to pass around pointers to GValueArrays. + * Add a property to an interface; this is only useful for interfaces + * that are added to GObject-derived types. Adding a property to an + * interface forces all objects classes with that interface to have a + * compatible property. The compatible property could be a newly + * created #GParamSpec, but normally + * g_object_class_override_property() will be used so that the object + * class only needs to provide an implementation and inherits the + * property description, default value, bounds, and so forth from the + * interface property. + * This function is meant to be called from the interface's default + * vtable initialization function (the @class_init member of + * #GTypeInfo.) It must not be called after after @class_init has + * been called for any object types implementing this interface. + * + * Since: 2.4 */ /** - * G_IS_PARAM_SPEC_UINT: - * @pspec: a valid #GParamSpec instance + * g_object_interface_list_properties: + * @g_iface: any interface vtable for the interface, or the default vtable for the interface + * @n_properties_p: (out): location to store number of properties returned. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. + * Lists the properties of an interface.Generally, the interface + * vtable passed in as @g_iface will be the default vtable from + * g_type_default_interface_ref(), or, if you know the interface has + * already been loaded, g_type_default_interface_peek(). + * pointer to an array of pointers to #GParamSpec + * structures. The paramspecs are owned by GLib, but the + * array should be freed with g_free() when you are done with + * it. * - * Returns: %TRUE on success. + * Since: 2.4 + * Returns: (array length=n_properties_p) (transfer container): a */ /** - * GParameter: - * @name: the parameter name - * @value: the parameter value + * g_object_is_floating: + * @object: (type GObject.Object): a #GObject * - * The <structname>GParameter</structname> struct is an auxiliary structure used - * to hand parameter name/value pairs to g_object_newv(). + * Checks wether @object has a <link linkend="floating-ref">floating</link> + * reference. + * + * Since: 2.10 + * Returns: %TRUE if @object has a floating reference */ /** - * g_cclosure_new_swap: (skip) - * @callback_func: the function to invoke - * @user_data: user data to pass to @callback_func - * @destroy_data: destroy notify to be called when @user_data is no longer used + * g_object_new: (skip) + * @object_type: the type id of the #GObject subtype to instantiate + * @first_property_name: the name of the first property + * @...: the value of the first property, followed optionally by more name/value pairs, followed by %NULL * - * Creates a new closure which invokes @callback_func with @user_data as - * the first parameter. + * Creates a new instance of a #GObject subtype and sets its properties. + * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) + * which are not explicitly specified are set to their default values. * - * Returns: (transfer full): a new #GCClosure + * Returns: (transfer full): a new instance of @object_type */ /** - * g_type_fundamental: - * @type_id: valid type ID + * g_object_new_valist: (skip) + * @object_type: the type id of the #GObject subtype to instantiate + * @first_property_name: the name of the first property + * @var_args: the value of the first property, followed optionally by more name/value pairs, followed by %NULL * - * Internal function, used to extract the fundamental type ID portion. - * use G_TYPE_FUNDAMENTAL() instead. + * Creates a new instance of a #GObject subtype and sets its properties. + * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) + * which are not explicitly specified are set to their default values. * - * Returns: fundamental type ID + * Returns: a new instance of @object_type */ /** - * g_type_add_class_cache_func: (skip) - * @cache_data: data to be passed to @cache_func - * @cache_func: a #GTypeClassCacheFunc + * g_object_newv: + * @object_type: the type id of the #GObject subtype to instantiate + * @n_parameters: the length of the @parameters array + * @parameters: (array length=n_parameters): an array of #GParameter * - * Adds a #GTypeClassCacheFunc to be called before the reference count of a - * class goes from one to zero. This can be used to prevent premature class - * destruction. All installed #GTypeClassCacheFunc functions will be chained - * until one of them returns %TRUE. The functions have to check the class id - * passed in to figure whether they actually want to cache the class of this - * type, since all classes are routed through the same #GTypeClassCacheFunc - * chain. + * Creates a new instance of a #GObject subtype and sets its properties. + * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) + * which are not explicitly specified are set to their default values. + * + * Rename to: g_object_new + * Returns: (type GObject.Object) (transfer full): a new instance of */ /** - * G_INITIALLY_UNOWNED_GET_CLASS: - * @object: a #GInitiallyUnowned instance. + * g_object_notify: + * @object: a #GObject + * @property_name: the name of a property installed on the class of @object. * - * Get the class structure associated to a #GInitiallyUnowned instance. + * Emits a "notify" signal for the property @property_name on @object. + * When possible, eg. when signaling a property change from within the class + * that registered the property, you should use g_object_notify_by_pspec() + * instead. + */ + + +/** + * g_object_notify_by_pspec: + * @object: a #GObject + * @pspec: the #GParamSpec of a property installed on the class of @object. * - * Returns: pointer to object class structure. + * Emits a "notify" signal for the property specified by @pspec on @object. + * This function omits the property name lookup, hence it is faster than + * g_object_notify(). + * One way to avoid using g_object_notify() from within the + * class that registered the properties, and using g_object_notify_by_pspec() + * instead, is to store the GParamSpec used with + * g_object_class_install_property() inside a static array, e.g.: + * |[ + * enum + * { + * PROP_0, + * PROP_FOO, + * PROP_LAST + * }; + * static GParamSpec *properties[PROP_LAST]; + * static void + * my_object_class_init (MyObjectClass *klass) + * { + * properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", + * 0, 100, + * 50, + * G_PARAM_READWRITE); + * g_object_class_install_property (gobject_class, + * PROP_FOO, + * properties[PROP_FOO]); + * } + * ]| + * and then notify a change on the "foo" property with: + * |[ + * g_object_notify_by_pspec (self, properties[PROP_FOO]); + * ]| + * + * Since: 2.26 */ /** - * g_object_interface_find_property: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface - * @property_name: name of a property to lookup. + * g_object_ref: + * @object: (type GObject.Object): a #GObject * - * Find the #GParamSpec with the given name for an - * interface. Generally, the interface vtable passed in as @g_iface - * will be the default vtable from g_type_default_interface_ref(), or, - * if you know the interface has already been loaded, - * g_type_default_interface_peek(). - * interface with the name @property_name, or %NULL if no - * such property exists. + * Increases the reference count of @object. * - * Since: 2.4 - * Returns: (transfer none): the #GParamSpec for the property of the + * Returns: (type GObject.Object) (transfer none): the same @object */ /** - * G_TYPE_PARAM_ENUM: + * g_object_ref_sink: + * @object: (type GObject.Object): a #GObject * - * The #GType of #GParamSpecEnum. + * Increase the reference count of @object, and possibly remove the + * <link linkend="floating-ref">floating</link> reference, if @object + * has a floating reference. + * In other words, if the object is floating, then this call "assumes + * ownership" of the floating reference, converting it to a normal + * reference by clearing the floating flag while leaving the reference + * count unchanged. If the object is not floating, then this call + * adds a new normal reference increasing the reference count by one. + * + * Since: 2.10 + * Returns: (type GObject.Object) (transfer none): @object */ /** - * G_IS_PARAM_SPEC_DOUBLE: - * @pspec: a valid #GParamSpec instance + * g_object_remove_toggle_ref: (skip) + * @object: a #GObject + * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. + * @data: data to pass to @notify * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. + * Removes a reference added with g_object_add_toggle_ref(). The + * reference count of the object is decreased by one. * - * Returns: %TRUE on success. + * Since: 2.8 */ /** - * G_TYPE_CHECK_INSTANCE_TYPE: - * @instance: Location of a #GTypeInstance structure. - * @g_type: The type to be checked + * g_object_remove_weak_pointer: (skip) + * @object: The object that is weak referenced. + * @weak_pointer_location: (inout): The memory address of a pointer. * - * Checks if @instance is an instance of the type identified by @g_type. - * This macro should only be used in type implementations. + * Removes a weak reference from @object that was previously added + * using g_object_add_weak_pointer(). The @weak_pointer_location has + * to match the one used with g_object_add_weak_pointer(). + */ + + +/** + * g_object_run_dispose: + * @object: a #GObject * - * Returns: %TRUE on success. + * Releases all references to other objects. This can be used to break + * reference cycles. + * This functions should only be called from object system implementations. */ /** - * g_value_transform: - * @src_value: Source value. - * @dest_value: Target value. + * g_object_set: (skip) + * @object: a #GObject + * @first_property_name: name of the first property to set + * @...: value for the first property, followed optionally by more name/value pairs, followed by %NULL * - * Tries to cast the contents of @src_value into a type appropriate - * to store in @dest_value, e.g. to transform a %G_TYPE_INT value - * into a %G_TYPE_FLOAT value. Performing transformations between - * value types might incur precision lossage. Especially - * transformations into strings might reveal seemingly arbitrary - * results and shouldn't be relied upon for production code (such - * as rcfile value or object property serialization). - * Upon failing transformations, @dest_value is left untouched. + * Sets properties on an object. + */ + + +/** + * g_object_set_data: + * @object: #GObject containing the associations. + * @key: name of the key + * @data: data to associate with that key * - * Returns: Whether a transformation rule was found and could be applied. + * Each object carries around a table of associations from + * strings to pointers. This function lets you set an association. + * If the object already had an association with that name, + * the old association will be destroyed. */ /** - * G_TYPE_IO_CONDITION: + * g_object_set_data_full: (skip) + * @object: #GObject containing the associations + * @key: name of the key + * @data: data to associate with that key + * @destroy: function to call when the association is destroyed * - * The #GType for #GIOCondition. + * Like g_object_set_data() except it adds notification + * for when the association is destroyed, either by setting it + * to a different value or when the object is destroyed. + * Note that the @destroy callback is not called if @data is %NULL. */ /** - * g_atomic_int_inc: - * @atomic: a pointer to an integer. + * g_object_set_property: + * @object: a #GObject + * @property_name: the name of the property to set + * @value: the value * - * Atomically increments the integer pointed to by @atomic by 1. + * Sets a property on an object. + */ + + +/** + * g_object_set_qdata: (skip) + * @object: The GObject to set store a user data pointer + * @quark: A #GQuark, naming the user data pointer + * @data: An opaque user data pointer * - * Since: 2.4 + * This sets an opaque, named pointer on an object. + * The name is specified through a #GQuark (retrived e.g. via + * g_quark_from_static_string()), and the pointer + * can be gotten back from the @object with g_object_get_qdata() + * until the @object is finalized. + * Setting a previously set user data pointer, overrides (frees) + * the old pointer set, using #NULL as pointer essentially + * removes the data stored. */ /** - * G_TYPE_PARAM_ULONG: + * g_object_set_qdata_full: (skip) + * @object: The GObject to set store a user data pointer + * @quark: A #GQuark, naming the user data pointer + * @data: An opaque user data pointer + * @destroy: Function to invoke with @data as argument, when @data needs to be freed * - * The #GType of #GParamSpecULong. + * This function works like g_object_set_qdata(), but in addition, + * a void (*destroy) (gpointer) function may be specified which is + * called with @data as argument when the @object is finalized, or + * the data is being overwritten by a call to g_object_set_qdata() + * with the same @quark. */ /** - * GUserDirectory: - * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory - * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory - * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory - * @G_USER_DIRECTORY_MUSIC: the user's Music directory - * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory - * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory - * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory - * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory - * @G_USER_N_DIRECTORIES: the number of enum values + * g_object_set_valist: (skip) + * @object: a #GObject + * @first_property_name: name of the first property to set + * @var_args: value for the first property, followed optionally by more name/value pairs, followed by %NULL * - * These are logical ids for special directories which are defined - * depending on the platform used. You should use g_get_user_special_dir() - * to retrieve the full path associated to the logical id. - * The #GUserDirectory enumeration can be extended at later date. Not - * every platform has a directory for every logical id in this - * enumeration. + * Sets properties on an object. + */ + + +/** + * g_object_steal_data: + * @object: #GObject containing the associations + * @key: name of the key * - * Since: 2.14 + * Remove a specified datum from the object's data associations, + * without invoking the association's destroy handler. + * + * Returns: (transfer full): the data if found, or %NULL if no such data exists. */ /** - * g_value_get_object: - * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * g_object_steal_qdata: + * @object: The GObject to get a stored user data pointer from + * @quark: A #GQuark, naming the user data pointer * - * Get the contents of a %G_TYPE_OBJECT derived #GValue. + * This function gets back user data pointers stored via + * g_object_set_qdata() and removes the @data from object + * without invoking its destroy() function (if any was + * set). + * Usually, calling this function is only required to update + * user data pointers with a destroy notifier, for example: + * |[ + * void + * object_add_to_user_list (GObject *object, + * const gchar *new_string) + * { + * // the quark, naming the object data + * GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); + * // retrive the old string list + * GList *list = g_object_steal_qdata (object, quark_string_list); + * // prepend new string + * list = g_list_prepend (list, g_strdup (new_string)); + * // this changed 'list', so we need to set it again + * g_object_set_qdata_full (object, quark_string_list, list, free_string_list); + * } + * static void + * free_string_list (gpointer data) + * { + * GList *node, *list = data; + * for (node = list; node; node = node->next) + * g_free (node->data); + * g_list_free (list); + * } + * ]| + * Using g_object_get_qdata() in the above example, instead of + * g_object_steal_qdata() would have left the destroy function set, + * and thus the partial string list would have been freed upon + * g_object_set_qdata_full(). * - * Returns: (type GObject.Object) (transfer none): object contents of @value + * Returns: (transfer full): The user data pointer set, or %NULL */ /** - * G_TYPE_RESERVED_GLIB_LAST: + * g_object_thaw_notify: + * @object: a #GObject * - * Last fundamental type number reserved for GLib. + * Reverts the effect of a previous call to + * g_object_freeze_notify(). The freeze count is decreased on @object + * and when it reaches zero, all queued "notify" signals are emitted. + * It is an error to call this function when the freeze count is zero. */ /** - * G_PARAM_SPEC_OBJECT: - * @pspec: a valid #GParamSpec instance + * g_object_unref: + * @object: (type GObject.Object): a #GObject * - * Casts a #GParamSpec instance into a #GParamSpecObject. + * Decreases the reference count of @object. When its reference count + * drops to 0, the object is finalized (i.e. its memory is freed). */ /** - * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH: + * g_object_watch_closure: + * @object: GObject restricting lifetime of @closure + * @closure: GClosure to watch * - * Allowed characters in a path. Includes "!$&'()*+,;=:@/". + * This function essentially limits the life time of the @closure to + * the life time of the object. That is, when the object is finalized, + * the @closure is invalidated by calling g_closure_invalidate() on + * it, in order to prevent invocations of the closure with a finalized + * (nonexisting) object. Also, g_object_ref() and g_object_unref() are + * added as marshal guards to the @closure, to ensure that an extra + * reference count is held on @object during invocation of the + * use this @object as closure data. */ /** - * GParamSpecObject: - * @parent_instance: private #GParamSpec portion + * g_object_weak_ref: (skip) + * @object: #GObject to reference weakly + * @notify: callback to invoke before the object is freed + * @data: extra data to pass to notify * - * A #GParamSpec derived structure that contains the meta data for object properties. + * Adds a weak reference callback to an object. Weak references are + * used for notification when an object is finalized. They are called + * "weak references" because they allow you to safely hold a pointer + * to an object without calling g_object_ref() (g_object_ref() adds a + * strong reference, that is, forces the object to stay alive). */ /** - * GTimeType: - * @G_TIME_TYPE_STANDARD: the time is in local standard time - * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time - * @G_TIME_TYPE_UNIVERSAL: the time is in UTC + * g_object_weak_unref: (skip) + * @object: #GObject to remove a weak reference from + * @notify: callback to search for + * @data: data to search for * - * Disambiguates a given time in two ways. - * First, specifies if the given time is in universal or local time. - * Second, if the time is in local time, specifies if it is local - * standard time or local daylight time. This is important for the case - * where the same local time occurs twice (during daylight savings time - * transitions, for example). + * Removes a weak reference callback to an object. */ /** - * G_PARAM_MASK: + * g_param_spec_boolean: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Mask containing the bits of #GParamSpec.flags which are reserved for GLib. + * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN + * property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * GTypeInfo: - * @class_size: Size of the class structure (required for interface, classed and instantiatable types). - * @base_init: Location of the base initialization function (optional). - * @base_finalize: Location of the base finalization function (optional). - * @class_init: Location of the class initialization function for classed and instantiatable types. Location of the default vtable inititalization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties. - * @class_finalize: Location of the class finalization function for classed and instantiatable types. Location fo the default vtable finalization function for interface types. (optional) - * @class_data: User-supplied data passed to the class init/finalize functions. - * @instance_size: Size of the instance (object) structure (required for instantiatable types only). - * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. - * @instance_init: Location of the instance initialization function (optional, for instantiatable types only). - * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types). + * g_param_spec_boxed: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @boxed_type: %G_TYPE_BOXED derived type of this property + * @flags: flags for the property specified * - * This structure is used to provide the type system with the information - * required to initialize and destruct (finalize) a type's class and - * its instances. - * The initialized structure is passed to the g_type_register_static() function - * (or is copied into the provided #GTypeInfo structure in the - * g_type_plugin_complete_type_info()). The type system will perform a deep - * copy of this structure, so its memory does not need to be persistent - * across invocation of g_type_register_static(). + * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED + * derived property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * GClassFinalizeFunc: - * @g_class: The #GTypeClass structure to finalize. - * @class_data: The @class_data member supplied via the #GTypeInfo structure. + * g_param_spec_char: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * A callback function used by the type system to finalize a class. - * This function is rarely needed, as dynamically allocated class resources - * should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). - * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo - * structure of a static type is invalid, because classes of static types - * will never be finalized (they are artificially kept alive when their - * reference count drops to zero). + * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. + * + * Returns: a newly created parameter specification */ /** - * G_TYPE_PARAM_UINT64: + * g_param_spec_double: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * The #GType of #GParamSpecUInt64. + * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE + * property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * G_VARIANT_TYPE_INT16: + * g_param_spec_enum: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @enum_type: a #GType derived from %G_TYPE_ENUM + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * The type of an integer value that can range from -32768 to 32767. + * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM + * property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_value_get_double: - * @value: a valid #GValue of type %G_TYPE_DOUBLE + * g_param_spec_flags: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @flags_type: a #GType derived from %G_TYPE_FLAGS + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Get the contents of a %G_TYPE_DOUBLE #GValue. + * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS + * property. + * See g_param_spec_internal() for details on property names. * - * Returns: double contents of @value + * Returns: a newly created parameter specification */ /** - * g_cclosure_marshal_BOOL__FLAGS: + * g_param_spec_float: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). + * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_cclosure_marshal_VOID__OBJECT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GObject* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_param_spec_get_blurb: + * @pspec: a valid #GParamSpec * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)</literal>. + * Get the short description of a #GParamSpec. + * + * Returns: the short description of @pspec. */ /** - * GValueArray: - * @n_values: number of values contained in the array - * @values: array of values + * g_param_spec_get_name: + * @pspec: a valid #GParamSpec * - * A #GValueArray contains an array of #GValue elements. + * Get the name of a #GParamSpec. + * + * Returns: the name of @pspec. */ /** - * g_object_set_qdata_full: (skip) - * @object: The GObject to set store a user data pointer - * @quark: A #GQuark, naming the user data pointer - * @data: An opaque user data pointer - * @destroy: Function to invoke with @data as argument, when @data needs to be freed + * g_param_spec_get_nick: + * @pspec: a valid #GParamSpec * - * This function works like g_object_set_qdata(), but in addition, - * a void (*destroy) (gpointer) function may be specified which is - * called with @data as argument when the @object is finalized, or - * the data is being overwritten by a call to g_object_set_qdata() - * with the same @quark. + * Get the nickname of a #GParamSpec. + * + * Returns: the nickname of @pspec. */ /** - * g_type_from_name: - * @name: Type name to lookup. + * g_param_spec_get_qdata: + * @pspec: a valid #GParamSpec + * @quark: a #GQuark, naming the user data pointer * - * Lookup the type ID from a given type name, returning 0 if no type - * has been registered under this name (this is the preferred method - * to find out by name whether a specific type has been registered - * yet). + * Gets back user data pointers stored via g_param_spec_set_qdata(). * - * Returns: Corresponding type ID or 0. + * Returns: (transfer none): the user data pointer set, or %NULL */ /** - * g_object_newv: - * @object_type: the type id of the #GObject subtype to instantiate - * @n_parameters: the length of the @parameters array - * @parameters: (array length=n_parameters): an array of #GParameter + * g_param_spec_get_redirect_target: + * @pspec: a #GParamSpec * - * Creates a new instance of a #GObject subtype and sets its properties. - * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. + * If the paramspec redirects operations to another paramspec, + * returns that paramspec. Redirect is used typically for + * providing a new implementation of a property in a derived + * type while preserving all the properties from the parent + * type. Redirection is established by creating a property + * of type #GParamSpecOverride. See g_object_class_override_property() + * for an example of the use of this capability. + * paramspec should be redirected, or %NULL if none. * - * Rename to: g_object_new - * Returns: (type GObject.Object) (transfer full): a new instance of + * Since: 2.4 + * Returns: (transfer none): paramspec to which requests on this */ /** - * g_type_interface_get_plugin: - * @instance_type: the #GType value of an instantiatable type. - * @interface_type: the #GType value of an interface type. + * g_param_spec_gtype: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @is_a_type: a #GType whose subtypes are allowed as values of the property (use %G_TYPE_NONE for any type) + * @flags: flags for the property specified * - * Returns the #GTypePlugin structure for the dynamic interface - * have a #GTypePlugin structure. See g_type_add_interface_dynamic(). - * interface @interface_type of @instance_type. + * Creates a new #GParamSpecGType instance specifying a + * %G_TYPE_GTYPE property. + * See g_param_spec_internal() for details on property names. * - * Returns: (transfer none): the #GTypePlugin for the dynamic + * Since: 2.10 + * Returns: a newly created parameter specification */ /** - * G_TYPE_CHECK_VALUE_TYPE: - * @value: a #GValue - * @g_type: The type to be checked. + * g_param_spec_int: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Checks if @value has been initialized to hold values - * of type @g_type. - * This macro should only be used in type implementations. + * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. + * See g_param_spec_internal() for details on property names. * - * Returns: %TRUE on success. + * Returns: a newly created parameter specification */ /** - * G_CLOSURE_N_NOTIFIERS: - * @cl: a #GClosure + * g_param_spec_int64: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Get the total number of notifiers connected with the closure @cl. - * The count includes the meta marshaller, the finalize and invalidate notifiers - * and the marshal guards. Note that each guard counts as two notifiers. - * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), - * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). + * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. + * See g_param_spec_internal() for details on property names. * - * Returns: number of notifiers + * Returns: a newly created parameter specification */ /** - * G_PARAM_SPEC_BOXED: - * @pspec: a valid #GParamSpec instance + * g_param_spec_internal: (skip) + * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM + * @name: the canonical name of the property + * @nick: the nickname of the property + * @blurb: a short description of the property + * @flags: a combination of #GParamFlags * - * Cast a #GParamSpec instance into a #GParamSpecBoxed. + * Creates a new #GParamSpec instance. + * A property name consists of segments consisting of ASCII letters and + * digits, separated by either the '-' or '_' character. The first + * character of a property name must be a letter. Names which violate these + * rules lead to undefined behaviour. + * When creating and looking up a #GParamSpec, either separator can be + * used, but they cannot be mixed. Using '-' is considerably more + * efficient and in fact required when using property names as detail + * strings for signals. + * Beyond the name, #GParamSpec<!-- -->s have two more descriptive + * strings associated with them, the @nick, which should be suitable + * for use as a label for the property in a property editor, and the + * e.g. a tooltip. The @nick and @blurb should ideally be localized. + * + * Returns: a newly allocated #GParamSpec instance */ /** - * g_object_steal_qdata: - * @object: The GObject to get a stored user data pointer from - * @quark: A #GQuark, naming the user data pointer + * g_param_spec_long: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * This function gets back user data pointers stored via - * g_object_set_qdata() and removes the @data from object - * without invoking its destroy() function (if any was - * set). - * Usually, calling this function is only required to update - * user data pointers with a destroy notifier, for example: - * |[ - * void - * object_add_to_user_list (GObject *object, - * const gchar *new_string) - * { - * // the quark, naming the object data - * GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); - * // retrive the old string list - * GList *list = g_object_steal_qdata (object, quark_string_list); - * // prepend new string - * list = g_list_prepend (list, g_strdup (new_string)); - * // this changed 'list', so we need to set it again - * g_object_set_qdata_full (object, quark_string_list, list, free_string_list); - * } - * static void - * free_string_list (gpointer data) - * { - * GList *node, *list = data; - * for (node = list; node; node = node->next) - * g_free (node->data); - * g_list_free (list); - * } - * ]| - * Using g_object_get_qdata() in the above example, instead of - * g_object_steal_qdata() would have left the destroy function set, - * and thus the partial string list would have been freed upon - * g_object_set_qdata_full(). + * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. + * See g_param_spec_internal() for details on property names. * - * Returns: (transfer full): The user data pointer set, or %NULL + * Returns: a newly created parameter specification */ /** - * g_object_set_qdata: (skip) - * @object: The GObject to set store a user data pointer - * @quark: A #GQuark, naming the user data pointer - * @data: An opaque user data pointer + * g_param_spec_object: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @object_type: %G_TYPE_OBJECT derived type of this property + * @flags: flags for the property specified * - * This sets an opaque, named pointer on an object. - * The name is specified through a #GQuark (retrived e.g. via - * g_quark_from_static_string()), and the pointer - * can be gotten back from the @object with g_object_get_qdata() - * until the @object is finalized. - * Setting a previously set user data pointer, overrides (frees) - * the old pointer set, using #NULL as pointer essentially - * removes the data stored. + * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT + * derived property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_type_add_interface_check: (skip) - * @check_data: data to pass to @check_func - * @check_func: function to be called after each interface is initialized. + * g_param_spec_override: (skip) + * @name: the name of the property. + * @overridden: The property that is being overridden * - * Adds a function to be called after an interface vtable is - * initialized for any class (i.e. after the @interface_init member of - * #GInterfaceInfo has been called). - * This function is useful when you want to check an invariant that - * depends on the interfaces of a class. For instance, the - * implementation of #GObject uses this facility to check that an - * object implements all of the properties that are defined on its - * interfaces. + * Creates a new property of type #GParamSpecOverride. This is used + * to direct operations to another paramspec, and will not be directly + * useful unless you are implementing a new base type similar to GObject. * * Since: 2.4 + * Returns: the newly created #GParamSpec */ /** - * G_IS_PARAM_SPEC_ULONG: - * @pspec: a valid #GParamSpec instance + * g_param_spec_param: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @param_type: a #GType derived from %G_TYPE_PARAM + * @flags: flags for the property specified * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. + * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM + * property. + * See g_param_spec_internal() for details on property names. * - * Returns: %TRUE on success. + * Returns: a newly created parameter specification */ /** - * GBinding:flags: + * g_param_spec_pointer: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @flags: flags for the property specified * - * Flags to be used to control the #GBinding + * Creates a new #GParamSpecPoiner instance specifying a pointer property. + * See g_param_spec_internal() for details on property names. * - * Since: 2.26 + * Returns: a newly created parameter specification */ /** - * GParamSpecClass: - * @g_type_class: the parent class - * @value_type: the #GValue type for this parameter - * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class. - * @value_set_default: Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default(). - * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_set_validate(). - * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp(). + * g_param_spec_pool_insert: + * @pool: a #GParamSpecPool. + * @pspec: the #GParamSpec to insert + * @owner_type: a #GType identifying the owner of @pspec * - * The class structure for the <structname>GParamSpec</structname> type. - * Normally, <structname>GParamSpec</structname> classes are filled by - * g_param_type_register_static(). + * Inserts a #GParamSpec in the pool. */ /** - * g_value_array_copy: - * @value_array: #GValueArray to copy + * g_param_spec_pool_list: + * @pool: a #GParamSpecPool + * @owner_type: the owner to look for + * @n_pspecs_p: (out): return location for the length of the returned array * - * Construct an exact copy of a #GValueArray by duplicating all its - * contents. + * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in + * the pool. + * allocated array containing pointers to all #GParamSpecs + * owned by @owner_type in the pool * - * Returns: (transfer full): Newly allocated copy of #GValueArray + * Returns: (array length=n_pspecs_p) (transfer container): a newly */ /** - * g_enum_get_value: - * @enum_class: a #GEnumClass - * @value: the value to look up + * g_param_spec_pool_list_owned: + * @pool: a #GParamSpecPool + * @owner_type: the owner to look for * - * Returns the #GEnumValue for a value. - * member of the enumeration + * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in + * the pool. + * #GList of all #GParamSpec<!-- -->s owned by @owner_type in + * the pool#GParamSpec<!-- -->s. * - * Returns: the #GEnumValue for @value, or %NULL if @value is not a + * Returns: (transfer container) (element-type GObject.ParamSpec): a */ /** - * G_IS_PARAM_SPEC_LONG: - * @pspec: a valid #GParamSpec instance + * g_param_spec_pool_lookup: + * @pool: a #GParamSpecPool + * @param_name: the name to look for + * @owner_type: the owner to look for + * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. + * Looks up a #GParamSpec in the pool. + * matching #GParamSpec was found. * - * Returns: %TRUE on success. + * Returns: (transfer none): The found #GParamSpec, or %NULL if no */ /** - * g_value_register_transform_func: (skip) - * @src_type: Source type. - * @dest_type: Target type. - * @transform_func: a function which transforms values of type @src_type into value of type @dest_type + * g_param_spec_pool_new: + * @type_prefixing: Whether the pool will support type-prefixed property names. * - * Registers a value transformation function for use in g_value_transform(). - * A previously registered transformation function for @src_type and @dest_type - * will be replaced. + * Creates a new #GParamSpecPool. + * If @type_prefixing is %TRUE, lookups in the newly created pool will + * allow to specify the owner as a colon-separated prefix of the + * property name, like "GtkContainer:border-width". This feature is + * deprecated, so you should always set @type_prefixing to %FALSE. + * + * Returns: (transfer none): a newly allocated #GParamSpecPool. */ /** - * g_object_ref: - * @object: (type GObject.Object): a #GObject + * g_param_spec_pool_remove: + * @pool: a #GParamSpecPool + * @pspec: the #GParamSpec to remove * - * Increases the reference count of @object. + * Removes a #GParamSpec from the pool. + */ + + +/** + * g_param_spec_ref: (skip) + * @pspec: a valid #GParamSpec * - * Returns: (type GObject.Object) (transfer none): the same @object + * Increments the reference count of @pspec. + * + * Returns: the #GParamSpec that was passed into this function */ /** - * G_IS_FLAGS_CLASS: - * @class: a #GFlagsClass + * g_param_spec_ref_sink: (skip) + * @pspec: a valid #GParamSpec * - * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS - * or derived. + * Convenience function to ref and sink a #GParamSpec. + * + * Since: 2.10 + * Returns: the #GParamSpec that was passed into this function */ /** - * g_newa: - * @struct_type: Type of memory chunks to be allocated - * @n_structs: Number of chunks to be allocated + * g_param_spec_set_qdata: + * @pspec: the #GParamSpec to set store a user data pointer + * @quark: a #GQuark, naming the user data pointer + * @data: an opaque user data pointer * - * Wraps g_alloca() in a more typesafe manner. + * Sets an opaque, named pointer on a #GParamSpec. The name is + * specified through a #GQuark (retrieved e.g. via + * g_quark_from_static_string()), and the pointer can be gotten back + * from the @pspec with g_param_spec_get_qdata(). Setting a + * previously set user data pointer, overrides (frees) the old pointer + * set, using %NULL as pointer essentially removes the data stored. + */ + + +/** + * g_param_spec_set_qdata_full: (skip) + * @pspec: the #GParamSpec to set store a user data pointer + * @quark: a #GQuark, naming the user data pointer + * @data: an opaque user data pointer + * @destroy: function to invoke with @data as argument, when @data needs to be freed * - * Returns: Pointer to stack space for @n_structs chunks of type @struct_type + * This function works like g_param_spec_set_qdata(), but in addition, + * a <literal>void (*destroy) (gpointer)</literal> function may be + * specified which is called with @data as argument when the @pspec is + * finalized, or the data is being overwritten by a call to + * g_param_spec_set_qdata() with the same @quark. */ /** - * g_cclosure_marshal_VOID__BOOLEAN: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gboolean parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_param_spec_sink: + * @pspec: a valid #GParamSpec * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>. + * The initial reference count of a newly created #GParamSpec is 1, + * even though no one has explicitly called g_param_spec_ref() on it + * yet. So the initial reference count is flagged as "floating", until + * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink + * (pspec);</literal> in sequence on it, taking over the initial + * reference count (thus ending up with a @pspec that has a reference + * count of 1 still, but is not flagged "floating" anymore). */ /** - * g_type_remove_interface_check: (skip) - * @check_data: callback data passed to g_type_add_interface_check() - * @check_func: callback function passed to g_type_add_interface_check() + * g_param_spec_steal_qdata: + * @pspec: the #GParamSpec to get a stored user data pointer from + * @quark: a #GQuark, naming the user data pointer * - * Removes an interface check function added with - * g_type_add_interface_check(). + * Gets back user data pointers stored via g_param_spec_set_qdata() + * and removes the @data from @pspec without invoking its destroy() + * function (if any was set). Usually, calling this function is only + * required to update user data pointers with a destroy notifier. * - * Since: 2.4 + * Returns: (transfer none): the user data pointer set, or %NULL */ /** - * g_cclosure_marshal_VOID__VOID: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 1 - * @param_values: a #GValue array holding only the instance - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_param_spec_string: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>. + * Creates a new #GParamSpecString instance. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_value_array_sort: - * @value_array: #GValueArray to sort - * @compare_func: (scope call): function to compare elements + * g_param_spec_uchar: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Sort @value_array using @compare_func to compare the elements accoring to - * the semantics of #GCompareFunc. - * The current implementation uses Quick-Sort as sorting algorithm. + * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * Returns: a newly created parameter specification */ /** - * G_TYPE_CHECK_INSTANCE_CAST: - * @instance: Location of a #GTypeInstance structure. - * @g_type: The type to be returned. - * @c_type: The corresponding C type of @g_type. + * g_param_spec_uint: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Checks that @instance is an instance of the type identified by @g_type - * and issues a warning if this is not the case. Returns @instance casted - * to a pointer to @c_type. - * This macro should only be used in type implementations. + * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_value_set_static_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: static boxed value to be set + * g_param_spec_uint64: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. - * The boxed value is assumed to be static, and is thus not duplicated - * when setting the #GValue. + * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 + * property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_type_default_interface_ref: - * @g_type: an interface type + * g_param_spec_ulong: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Increments the reference count for the interface type @g_type, - * and returns the default interface vtable for the type. - * If the type is not currently in use, then the default vtable - * for the type will be created and initalized by calling - * the base interface init and default vtable init functions for - * the type (the @<structfield>base_init</structfield> - * and <structfield>class_init</structfield> members of #GTypeInfo). - * Calling g_type_default_interface_ref() is useful when you - * want to make sure that signals and properties for an interface - * have been installed. - * vtable for the interface; call g_type_default_interface_unref() - * when you are done using the interface. + * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG + * property. + * See g_param_spec_internal() for details on property names. * - * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default + * Returns: a newly created parameter specification */ /** - * G_IS_PARAM_SPEC_PARAM: - * @pspec: a valid #GParamSpec instance + * g_param_spec_unichar: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. + * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT + * property. #GValue structures for this property can be accessed with + * g_value_set_uint() and g_value_get_uint(). + * See g_param_spec_internal() for details on property names. * - * Returns: %TRUE on success. + * Returns: a newly created parameter specification */ /** - * g_object_unref: - * @object: (type GObject.Object): a #GObject + * g_param_spec_unref: (skip) + * @pspec: a valid #GParamSpec * - * Decreases the reference count of @object. When its reference count - * drops to 0, the object is finalized (i.e. its memory is freed). + * Decrements the reference count of a @pspec. */ /** - * GBoxedFreeFunc: - * @boxed: The boxed structure to be freed. + * g_param_spec_value_array: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL + * @flags: flags for the property specified * - * This function is provided by the user and should free the boxed - * structure passed. + * Creates a new #GParamSpecValueArray instance specifying a + * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a + * %G_TYPE_BOXED type, as such, #GValue structures for this property + * can be accessed with g_value_set_boxed() and g_value_get_boxed(). + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * G_CCLOSURE_SWAP_DATA: - * @cclosure: a #GCClosure + * g_param_spec_variant: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @type: a #GVariantType + * @default_value: (allow-none): a #GVariant of type @type to use as the default value, or %NULL + * @flags: flags for the property specified * - * Checks whether the user data of the #GCClosure should be passed as the - * first parameter to the callback. See g_cclosure_new_swap(). + * Creates a new #GParamSpecVariant instance specifying a #GVariant + * property. + * If @default_value is floating, it is consumed. + * See g_param_spec_internal() for details on property names. * - * Returns: %TRUE if data has to be swapped. + * Returns: the newly created #GParamSpec + * Since: 2.26 */ /** - * g_value_take_object: (skip) - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * @v_object: object value to be set + * g_param_type_register_static: + * @name: 0-terminated string used as the name of the new #GParamSpec type. + * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. * - * Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object - * and takes over the ownership of the callers reference to @v_object; - * the caller doesn't have to unref it any more (i.e. the reference - * count of the object is not increased). - * If you want the #GValue to hold its own reference to @v_object, use - * g_value_set_object() instead. + * Registers @name as the name of a new static type derived from + * #G_TYPE_PARAM. The type system uses the information contained in + * the #GParamSpecTypeInfo structure pointed to by @info to manage the + * #GParamSpec type and its instances. * - * Since: 2.4 + * Returns: The new type identifier. */ /** - * G_ENUM_CLASS_TYPE_NAME: - * @class: a #GEnumClass + * g_param_value_convert: + * @pspec: a valid #GParamSpec + * @src_value: souce #GValue + * @dest_value: destination #GValue of correct type for @pspec + * @strict_validation: %TRUE requires @dest_value to conform to @pspec without modifications * - * Get the static type name from a given #GEnumClass structure. + * Transforms @src_value into @dest_value if possible, and then + * validates @dest_value, in order for it to conform to @pspec. If + * transformed @dest_value complied to @pspec without modifications. + * See also g_value_type_transformable(), g_value_transform() and + * g_param_value_validate(). + * %FALSE otherwise and @dest_value is left untouched. * - * Returns: the type name. + * Returns: %TRUE if transformation and validation were successful, */ /** - * G_VALUE_COLLECT: - * @value: a #GValue return location. @value is supposed to be initialized according to the value type to be collected - * @var_args: the va_list variable; it may be evaluated multiple times - * @flags: flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. - * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails + * g_param_value_defaults: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec * - * Collects a variable argument value from a va_list. We have to - * implement the varargs collection as a macro, because on some systems - * va_list variables cannot be passed by reference. - * you should use the #G_VALUE_COLLECT_INIT variant and pass the unitialized - * #GValue. That variant is faster than #G_VALUE_COLLECT. + * Checks whether @value contains the default value as specified in @pspec. * - * Note: If you are creating the @value argument just before calling this macro, + * Returns: whether @value contains the canonical default for this @pspec + */ + + +/** + * g_param_value_set_default: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec + * + * Sets @value to its default value as specified in @pspec. + */ + + +/** + * g_param_value_validate: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec + * + * Ensures that the contents of @value comply with the specifications + * set out by @pspec. For example, a #GParamSpecInt might require + * that integers stored in @value may not be smaller than -42 and not be + * greater than +42. If @value contains an integer outside of this range, + * it is modified accordingly, so the resulting value will fit into the + * range -42 .. +42. + * + * Returns: whether modifying @value was necessary to ensure validity + */ + + +/** + * g_param_values_cmp: + * @pspec: a valid #GParamSpec + * @value1: a #GValue of correct type for @pspec + * @value2: a #GValue of correct type for @pspec + * + * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, + * if @value1 is found to be less than, equal to or greater than @value2, + * respectively. + * + * Returns: -1, 0 or +1, for a less than, equal to or greater than result + */ + + +/** + * g_pointer_type_register_static: + * @name: the name of the new pointer type. + * + * Creates a new %G_TYPE_POINTER derived type id for a new + * pointer type with name @name. + * + * Returns: a new %G_TYPE_POINTER derived type id for @name. + */ + + +/** + * g_renew: + * @struct_type: the type of the elements to allocate + * @mem: the currently allocated memory + * @n_structs: the number of elements to allocate + * + * Reallocates the memory pointed to by @mem, so that it now has space for + * the memory, which may have been moved. + * Care is taken to avoid overflow when calculating the size of the allocated block. + * + * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type + */ + + +/** + * g_signal_accumulator_first_wins: + * @ihint: standard #GSignalAccumulator parameter + * @return_accu: standard #GSignalAccumulator parameter + * @handler_return: standard #GSignalAccumulator parameter + * @dummy: standard #GSignalAccumulator parameter + * + * A predefined #GSignalAccumulator for signals intended to be used as a + * hook for application code to provide a particular value. Usually + * only one such value is desired and multiple handlers for the same + * signal don't make much sense (except for the case of the default + * handler defined in the class structure, in which case you will + * usually want the signal connection to override the class handler). + * This accumulator will use the return value from the first signal + * handler that is run as the return value for the signal and not run + * + * Any further handlers (ie: the first handler "wins"). + * Returns: standard #GSignalAccumulator result + * Since: 2.28 */ @@ -8482,373 +8101,651 @@ /** - * GTypePlugin: + * g_signal_add_emission_hook: + * @signal_id: the signal identifier, as returned by g_signal_lookup(). + * @detail: the detail on which to call the hook. + * @hook_func: a #GSignalEmissionHook function. + * @hook_data: user data for @hook_func. + * @data_destroy: a #GDestroyNotify for @hook_data. * - * The <structname>GTypePlugin</structname> typedef is used as a placeholder - * for objects that implement the <structname>GTypePlugin</structname> - * interface. + * Adds an emission hook for a signal, which will get called for any emission + * of that signal, independent of the instance. This is possible only + * for signals which don't have #G_SIGNAL_NO_HOOKS flag set. + * + * Returns: the hook id, for later use with g_signal_remove_emission_hook(). */ /** - * g_new0: - * @struct_type: the type of the elements to allocate. - * @n_structs: the number of elements to allocate. + * g_signal_chain_from_overridden: + * @instance_and_params: the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. + * @return_value: Location for the return value. * - * Allocates @n_structs elements of type @struct_type, initialized to 0's. - * The returned pointer is cast to a pointer to the given type. - * If @n_structs is 0 it returns %NULL. - * Care is taken to avoid overflow when calculating the size of the allocated block. - * Since the returned pointer is already casted to the right type, - * it is normally unnecessary to cast it explicitly, and doing - * so might hide memory allocation errors. + * Calls the original class closure of a signal. This function should only + * be called from an overridden class closure; see + * g_signal_override_class_closure() and + * g_signal_override_class_handler(). + */ + + +/** + * g_signal_chain_from_overridden_handler: + * @instance: the instance the signal is being emitted on. + * @...: parameters to be passed to the parent class closure, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. * - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. + * Calls the original class closure of a signal. This function should + * only be called from an overridden class closure; see + * g_signal_override_class_closure() and + * g_signal_override_class_handler(). + * + * Since: 2.18 */ /** - * g_value_dup_boxed: (skip) - * @value: a valid #GValue of %G_TYPE_BOXED derived type + * g_signal_connect: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. * - * Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, - * the boxed value is duplicated and needs to be later freed with - * return_value); + * Connects a #GCallback function to a signal for a particular object. + * The handler will be called before the default handler of the signal. * - * G_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), - * Returns: boxed contents of @value + * Returns: the handler id */ /** - * g_value_dup_param: (skip) - * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM + * g_signal_connect_after: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. * - * Get the contents of a %G_TYPE_PARAM #GValue, increasing its - * reference count. - * no longer needed. + * Connects a #GCallback function to a signal for a particular object. + * The handler will be called after the default handler of the signal. * - * Returns: #GParamSpec content of @value, should be unreferenced when + * Returns: the handler id */ /** - * GOptionFlags: - * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output. - * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the <option>--help</option> output, even if it is defined in a group. - * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed. - * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8 - * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8 - * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8 - * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution which prefixes long option names with <literal>groupname-</literal> if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8. + * g_signal_connect_closure: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @closure: the closure to connect. + * @after: whether the handler should be called before or after the default handler of the signal. * - * Flags which modify individual options. + * Connects a closure to a signal for a particular object. + * + * Returns: the handler id */ /** - * G_TYPE_INSTANCE_GET_PRIVATE: - * @instance: the instance of a type deriving from @private_type. - * @g_type: the type identifying which private data to retrieve. - * @c_type: The C type for the private structure. + * g_signal_connect_closure_by_id: + * @instance: the instance to connect to. + * @signal_id: the id of the signal. + * @detail: the detail. + * @closure: the closure to connect. + * @after: whether the handler should be called before or after the default handler of the signal. * - * Gets the private structure for a particular type. - * The private structure must have been registered in the - * class_init function with g_type_class_add_private(). - * This macro should only be used in type implementations. + * Connects a closure to a signal for a particular object. * - * Since: 2.4 - * Returns: a pointer to the private data structure. + * Returns: the handler id */ /** - * G_VALUE_HOLDS: - * @value: A #GValue structure. - * @type: A #GType value. + * g_signal_connect_data: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. + * @destroy_data: a #GClosureNotify for @data. + * @connect_flags: a combination of #GConnectFlags. * - * Checks if @value holds (or contains) a value of @type. - * This macro will also check for @value != %NULL and issue a - * warning if the check fails. + * Connects a #GCallback function to a signal for a particular object. Similar + * to g_signal_connect(), but allows to provide a #GClosureNotify for the data + * which will be called when the signal handler is disconnected and no longer + * used. Specify @connect_flags if you need <literal>..._after()</literal> or + * <literal>..._swapped()</literal> variants of this function. * - * Returns: %TRUE if @value holds the @type. + * Returns: the handler id */ /** - * G_PARAM_SPEC: - * @pspec: a valid #GParamSpec + * g_signal_connect_object: (skip) + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @gobject: the object to pass as data to @c_handler. + * @connect_flags: a combination of #GConnnectFlags. * - * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into - * a #GParamSpec object. + * This is similar to g_signal_connect_data(), but uses a closure which + * ensures that the @gobject stays alive during the call to @c_handler + * by temporarily adding a reference count to @gobject. + * Note that there is a bug in GObject that makes this function + * much less useful than it might seem otherwise. Once @gobject is + * disposed, the callback will no longer be called, but, the signal + * handler is <emphasis>not</emphasis> currently disconnected. If the + * matter, since the signal will automatically be removed, but + * if @instance persists, then the signal handler will leak. You + * should not remove the signal yourself because in a future versions of + * GObject, the handler <emphasis>will</emphasis> automatically + * be disconnected. + * It's possible to work around this problem in a way that will + * continue to work with future versions of GObject by checking + * that the signal handler is still connected before disconnected it: + * <informalexample><programlisting> + * if (g_signal_handler_is_connected (instance, id)) + * g_signal_handler_disconnect (instance, id); + * </programlisting></informalexample> + * + * Returns: the handler id. */ /** - * g_flags_complete_type_info: - * @g_flags_type: the type identifier of the type being completed - * @info: the #GTypeInfo struct to be filled in - * @const_values: An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * g_signal_connect_swapped: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. * - * This function is meant to be called from the complete_type_info() - * function of a #GTypePlugin implementation, see the example for - * g_enum_complete_type_info() above. + * Connects a #GCallback function to a signal for a particular object. + * The instance on which the signal is emitted and @data will be swapped when + * calling the handler. + * + * Returns: the handler id */ /** - * G_TYPE_PARAM: + * g_signal_emit: + * @instance: the instance the signal is being emitted on. + * @signal_id: the signal id + * @detail: the detail + * @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. * - * The fundamental type from which all #GParamSpec types are derived. + * Emits a signal. + * Note that g_signal_emit() resets the return value to the default + * if no handlers are connected, in contrast to g_signal_emitv(). */ /** - * g_object_steal_data: - * @object: #GObject containing the associations - * @key: name of the key + * g_signal_emit_by_name: + * @instance: the instance the signal is being emitted on. + * @detailed_signal: a string of the form "signal-name::detail". + * @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. * - * Remove a specified datum from the object's data associations, - * without invoking the association's destroy handler. + * Emits a signal. + * Note that g_signal_emit_by_name() resets the return value to the default + * if no handlers are connected, in contrast to g_signal_emitv(). + */ + + +/** + * g_signal_emit_valist: + * @instance: the instance the signal is being emitted on. + * @signal_id: the signal id + * @detail: the detail + * @var_args: a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. * - * Returns: (transfer full): the data if found, or %NULL if no such data exists. + * Emits a signal. + * Note that g_signal_emit_valist() resets the return value to the default + * if no handlers are connected, in contrast to g_signal_emitv(). */ /** - * GParamSpecPool: + * g_signal_emitv: + * @instance_and_params: argument list for the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. + * @signal_id: the signal id + * @detail: the detail + * @return_value: Location to store the return value of the signal emission. * - * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be - * quickly accessed by owner and name. The implementation of the #GObject property - * system uses such a pool to store the #GParamSpecs of the properties all object - * types. + * Emits a signal. + * Note that g_signal_emitv() doesn't change @return_value if no handlers are + * connected, in contrast to g_signal_emit() and g_signal_emit_valist(). */ /** - * G_OBJECT_CLASS_NAME: - * @class: a valid #GObjectClass + * g_signal_get_invocation_hint: + * @instance: the instance to query * - * Return the name of a class structure's type. - * should not be freed. + * Returns the invocation hint of the innermost signal emission of instance. * - * Returns: Type name of @class. The string is owned by the type system and + * Returns: the invocation hint of the innermost signal emission. */ /** - * g_object_ref_sink: - * @object: (type GObject.Object): a #GObject + * g_signal_handler_block: + * @instance: The instance to block the signal handler of. + * @handler_id: Handler id of the handler to be blocked. * - * Increase the reference count of @object, and possibly remove the - * <link linkend="floating-ref">floating</link> reference, if @object - * has a floating reference. - * In other words, if the object is floating, then this call "assumes - * ownership" of the floating reference, converting it to a normal - * reference by clearing the floating flag while leaving the reference - * count unchanged. If the object is not floating, then this call - * adds a new normal reference increasing the reference count by one. + * Blocks a handler of an instance so it will not be called during any + * signal emissions unless it is unblocked again. Thus "blocking" a + * signal handler means to temporarily deactive it, a signal handler + * has to be unblocked exactly the same amount of times it has been + * blocked before to become active again. + * The @handler_id has to be a valid signal handler id, connected to a + * signal of @instance. + */ + + +/** + * g_signal_handler_disconnect: + * @instance: The instance to remove the signal handler from. + * @handler_id: Handler id of the handler to be disconnected. * - * Since: 2.10 - * Returns: (type GObject.Object) (transfer none): @object + * Disconnects a handler from an instance so it will not be called during + * any future or currently ongoing emissions of the signal it has been + * connected to. The @handler_id becomes invalid and may be reused. + * The @handler_id has to be a valid signal handler id, connected to a + * signal of @instance. */ /** - * g_signal_list_ids: - * @itype: Instance or interface type. - * @n_ids: Location to store the number of signal ids for @itype. + * g_signal_handler_find: + * @instance: The instance owning the signal handler to be found. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. + * @signal_id: Signal the handler has to be connected to. + * @detail: Signal detail the handler has to be connected to. + * @closure: The closure the handler will invoke. + * @func: The C closure callback of the handler (useless for non-C closures). + * @data: The closure data of the handler's closure. * - * Lists the signals by id that a certain instance or interface type - * created. Further information about the signals can be acquired through - * g_signal_query(). + * Finds the first signal handler that matches certain selection criteria. + * The criteria mask is passed as an OR-ed combination of #GSignalMatchType + * flags, and the criteria values are passed as arguments. + * The match @mask has to be non-0 for successful matches. + * If no handler was found, 0 is returned. * - * Returns: Newly allocated array of signal IDs. + * Returns: A valid non-0 signal handler id for a successful match. */ /** - * GTypeCValue: - * @v_int: the field for holding integer values - * @v_long: the field for holding long integer values - * @v_int64: the field for holding 64 bit integer values - * @v_double: the field for holding floating point values - * @v_pointer: the field for holding pointers + * g_signal_handler_is_connected: + * @instance: The instance where a signal handler is sought. + * @handler_id: the handler id. * - * A union holding one collected value. + * Returns whether @handler_id is the id of a handler connected to @instance. + * + * Returns: whether @handler_id identifies a handler connected to @instance. */ /** - * g_object_notify: - * @object: a #GObject - * @property_name: the name of a property installed on the class of @object. + * g_signal_handler_unblock: + * @instance: The instance to unblock the signal handler of. + * @handler_id: Handler id of the handler to be unblocked. * - * Emits a "notify" signal for the property @property_name on @object. - * When possible, eg. when signaling a property change from within the class - * that registered the property, you should use g_object_notify_by_pspec() - * instead. + * Undoes the effect of a previous g_signal_handler_block() call. A + * blocked handler is skipped during signal emissions and will not be + * invoked, unblocking it (for exactly the amount of times it has been + * blocked before) reverts its "blocked" state, so the handler will be + * recognized by the signal system and is called upon future or + * currently ongoing signal emissions (since the order in which + * handlers are called during signal emissions is deterministic, + * whether the unblocked handler in question is called as part of a + * currently ongoing emission depends on how far that emission has + * proceeded yet). + * The @handler_id has to be a valid id of a signal handler that is + * connected to a signal of @instance and is currently blocked. */ /** - * G_VARIANT_TYPE_TUPLE: + * g_signal_handlers_block_by_func: + * @instance: The instance to block handlers from. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * An indefinite type that is a supertype of every tuple type, - * regardless of the number of items in the tuple. + * Blocks all handlers on an instance that match @func and @data. + * + * Returns: The number of handlers that matched. */ /** - * G_TYPE_FLAG_RESERVED_ID_BIT: + * g_signal_handlers_block_matched: + * @instance: The instance to block handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @signal_id: Signal the handlers have to be connected to. + * @detail: Signal detail the handlers have to be connected to. + * @closure: The closure the handlers will invoke. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * A bit in the type number that's supposed to be left untouched. + * Blocks all handlers on an instance that match a certain selection criteria. + * The criteria mask is passed as an OR-ed combination of #GSignalMatchType + * flags, and the criteria values are passed as arguments. + * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC + * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. + * If no handlers were found, 0 is returned, the number of blocked handlers + * otherwise. + * + * Returns: The number of handlers that matched. */ /** - * g_type_next_base: - * @leaf_type: Descendant of @root_type and the type to be returned. - * @root_type: Immediate parent of the returned type. + * g_signal_handlers_disconnect_by_func: + * @instance: The instance to remove handlers from. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * Given a @leaf_type and a @root_type which is contained in its - * anchestry, return the type that @root_type is the immediate parent - * of. In other words, this function determines the type that is - * derived directly from @root_type which is also a base class of - * be used to determine the types and order in which the leaf type is - * descended from the root type. + * Disconnects all handlers on an instance that match @func and @data. * - * Returns: Immediate child of @root_type and anchestor of @leaf_type. + * Returns: The number of handlers that matched. */ /** - * g_param_spec_char: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * g_signal_handlers_disconnect_matched: + * @instance: The instance to remove handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @signal_id: Signal the handlers have to be connected to. + * @detail: Signal detail the handlers have to be connected to. + * @closure: The closure the handlers will invoke. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. + * Disconnects all handlers on an instance that match a certain + * selection criteria. The criteria mask is passed as an OR-ed + * combination of #GSignalMatchType flags, and the criteria values are + * passed as arguments. Passing at least one of the + * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or + * %G_SIGNAL_MATCH_DATA match flags is required for successful + * matches. If no handlers were found, 0 is returned, the number of + * disconnected handlers otherwise. * - * Returns: a newly created parameter specification + * Returns: The number of handlers that matched. */ /** - * GConnectFlags: - * @G_CONNECT_AFTER: whether the handler should be called before or after the default handler of the signal. - * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when calling the handler. + * g_signal_handlers_unblock_by_func: + * @instance: The instance to unblock handlers from. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * The connection flags are used to specify the behaviour of a signal's - * connection. + * Unblocks all handlers on an instance that match @func and @data. + * + * Returns: The number of handlers that matched. */ /** - * g_node_prev_sibling: - * @node: a #GNode + * g_signal_handlers_unblock_matched: + * @instance: The instance to unblock handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @signal_id: Signal the handlers have to be connected to. + * @detail: Signal detail the handlers have to be connected to. + * @closure: The closure the handlers will invoke. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * Gets the previous sibling of a #GNode. - * node or %NULL + * Unblocks all handlers on an instance that match a certain selection + * criteria. The criteria mask is passed as an OR-ed combination of + * #GSignalMatchType flags, and the criteria values are passed as arguments. + * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC + * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. + * If no handlers were found, 0 is returned, the number of unblocked handlers + * otherwise. The match criteria should not apply to any handlers that are + * not currently blocked. * - * Returns: the previous sibling of @node, or %NULL if @node is the first + * Returns: The number of handlers that matched. */ /** - * G_IS_PARAM_SPEC_BOOLEAN: - * @pspec: a valid #GParamSpec instance + * g_signal_has_handler_pending: + * @instance: the object whose signal handlers are sought. + * @signal_id: the signal id. + * @detail: the detail. + * @may_be_blocked: whether blocked handlers should count as match. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. + * Returns whether there are any handlers connected to @instance for the + * given signal id and detail. + * One example of when you might use this is when the arguments to the + * signal are difficult to compute. A class implementor may opt to not + * emit the signal if no one is attached anyway, thus saving the cost + * of building the arguments. + * otherwise. * - * Returns: %TRUE on success. + * Returns: %TRUE if a handler is connected to the signal, %FALSE */ /** - * GTranslateFunc: - * @str: the untranslated string - * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func() + * g_signal_list_ids: + * @itype: Instance or interface type. + * @n_ids: Location to store the number of signal ids for @itype. * - * The type of functions which are used to translate user-visible - * strings, for <option>--help</option> output. - * The returned string is owned by GLib and must not be freed. + * Lists the signals by id that a certain instance or interface type + * created. Further information about the signals can be acquired through + * g_signal_query(). * - * Returns: a translation of the string for the current locale. + * Returns: Newly allocated array of signal IDs. */ /** - * G_TYPE_CHECK_CLASS_TYPE: - * @g_class: Location of a #GTypeClass structure. - * @g_type: The type to be checked. + * g_signal_lookup: + * @name: the signal's name. + * @itype: the type that the signal operates on. * - * Checks if @g_class is a class structure of the type identified by - * This macro should only be used in type implementations. + * Given the name of the signal and the type of object it connects to, gets + * the signal's identifying integer. Emitting the signal by number is + * somewhat faster than using the name each time. + * Also tries the ancestors of the given type. + * See g_signal_new() for details on allowed signal names. * - * Returns: %TRUE on success. + * Returns: the signal's identifying number, or 0 if no signal was found. */ /** - * G_VARIANT_TYPE_BYTE: + * g_signal_name: + * @signal_id: the signal's identifying number. * - * The type of an integer value that can range from 0 to 255. + * Given the signal's identifier, finds its name. + * Two different signals may have the same name, if they have differing types. + * + * Returns: the signal name, or %NULL if the signal number was invalid. */ /** - * g_value_reset: - * @value: An initialized #GValue structure. + * g_signal_new: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_offset: The offset of the function pointer in the class structure for this type. Used to invoke a class method generically. Pass 0 to not associate a class method slot with this signal. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @n_params: the number of parameter types to follow. + * @...: a list of types, one for each parameter. * - * Clears the current value in @value and resets it to the default value - * (as if the value had just been initialized). + * Creates a new signal. (This is usually done in the class initializer.) + * A signal name consists of segments consisting of ASCII letters and + * digits, separated by either the '-' or '_' character. The first + * character of a signal name must be a letter. Names which violate these + * rules lead to undefined behaviour of the GSignal system. + * When registering a signal and looking up a signal, either separator can + * be used, but they cannot be mixed. + * If 0 is used for @class_offset subclasses cannot override the class handler + * in their <code>class_init</code> method by doing + * <code>super_class->signal_handler = my_signal_handler</code>. Instead they + * will have to use g_signal_override_class_handler(). * - * Returns: the #GValue structure that has been passed in + * Returns: the signal id */ /** - * g_type_module_register_enum: - * @module: a #GTypeModule - * @name: name for the type - * @const_static_values: an array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * g_signal_new_class_handler: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_handler: a #GCallback which acts as class implementation of this signal. Used to invoke a class method generically. Pass %NULL to not associate a class method with this signal. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @n_params: the number of parameter types to follow. + * @...: a list of types, one for each parameter. * - * Looks up or registers an enumeration that is implemented with a particular - * type plugin. If a type with name @type_name was previously registered, - * the #GType identifier for the type is returned, otherwise the type - * is newly registered, and the resulting #GType identifier returned. - * As long as any instances of the type exist, the type plugin will - * not be unloaded. + * Creates a new signal. (This is usually done in the class initializer.) + * This is a variant of g_signal_new() that takes a C callback instead + * off a class offset for the signal's class handler. This function + * doesn't need a function pointer exposed in the class structure of + * an object definition, instead the function pointer is passed + * directly and can be overriden by derived classes with + * g_signal_override_class_closure() or + * g_signal_override_class_handler()and chained to with + * g_signal_chain_from_overridden() or + * g_signal_chain_from_overridden_handler(). + * See g_signal_new() for information about signal names. * - * Since: 2.6 - * Returns: the new or existing type ID + * Returns: the signal id + * Since: 2.18 */ /** - * G_IS_PARAM_SPEC_UCHAR: - * @pspec: a valid #GParamSpec instance + * g_signal_new_valist: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_closure: The closure to invoke on signal emission; may be %NULL. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @n_params: the number of parameter types in @args. + * @args: va_list of #GType, one for each parameter. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. + * Creates a new signal. (This is usually done in the class initializer.) + * See g_signal_new() for details on allowed signal names. * - * Returns: %TRUE on success. + * Returns: the signal id */ /** - * GTypeQuery: - * @type: the #GType value of the type. - * @type_name: the name of the type. - * @class_size: the size of the class structure. - * @instance_size: the size of the instance structure. + * g_signal_newv: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type + * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST + * @class_closure: The closure to invoke on signal emission; may be %NULL + * @accumulator: the accumulator for this signal; may be %NULL + * @accu_data: user data for the @accumulator + * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations + * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value + * @n_params: the length of @param_types + * @param_types: an array of types, one for each parameter * - * A structure holding information for a specific type. It is - * filled in by the g_type_query() function. + * Creates a new signal. (This is usually done in the class initializer.) + * See g_signal_new() for details on allowed signal names. + * + * Returns: the signal id + */ + + +/** + * g_signal_override_class_closure: + * @signal_id: the signal id + * @instance_type: the instance type on which to override the class closure for the signal. + * @class_closure: the closure. + * + * Overrides the class closure (i.e. the default handler) for the given signal + * for emissions on instances of @instance_type. @instance_type must be derived + * from the type to which the signal belongs. + * See g_signal_chain_from_overridden() and + * g_signal_chain_from_overridden_handler() for how to chain up to the + * parent class closure from inside the overridden one. + */ + + +/** + * g_signal_override_class_handler: + * @signal_name: the name for the signal + * @instance_type: the instance type on which to override the class handler for the signal. + * @class_handler: the handler. + * + * Overrides the class closure (i.e. the default handler) for the + * given signal for emissions on instances of @instance_type with + * callabck @class_handler. @instance_type must be derived from the + * type to which the signal belongs. + * See g_signal_chain_from_overridden() and + * g_signal_chain_from_overridden_handler() for how to chain up to the + * parent class closure from inside the overridden one. + * + * Since: 2.18 + */ + + +/** + * g_signal_parse_name: + * @detailed_signal: a string of the form "signal-name::detail". + * @itype: The interface/instance type that introduced "signal-name". + * @signal_id_p: Location to store the signal id. + * @detail_p: Location to store the detail quark. + * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail. + * + * Internal function to parse a signal name into its @signal_id + * and @detail quark. + * + * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. + */ + + +/** + * g_signal_query: + * @signal_id: The signal id of the signal to query information for. + * @query: A user provided structure that is filled in with constant values upon success. + * + * Queries the signal system for in-depth information about a + * specific signal. This function will fill in a user-provided + * structure to hold signal-specific information. If an invalid + * signal id is passed in, the @signal_id member of the #GSignalQuery + * is 0. All members filled into the #GSignalQuery structure should + * be considered constant and have to be left untouched. + */ + + +/** + * g_signal_remove_emission_hook: + * @signal_id: the id of the signal + * @hook_id: the id of the emission hook, as returned by g_signal_add_emission_hook() + * + * Deletes an emission hook. + */ + + +/** + * g_signal_stop_emission: + * @instance: the object whose signal handlers you wish to stop. + * @signal_id: the signal identifier, as returned by g_signal_lookup(). + * @detail: the detail which the signal was emitted with. + * + * Stops a signal's current emission. + * This will prevent the default method from running, if the signal was + * %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" + * flag). + * Prints a warning if used on a signal which isn't being emitted. */ @@ -8876,410 +8773,500 @@ /** - * g_object_interface_list_properties: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface - * @n_properties_p: (out): location to store number of properties returned. + * g_source_set_closure: + * @source: the source + * @closure: a #GClosure * - * Lists the properties of an interface.Generally, the interface - * vtable passed in as @g_iface will be the default vtable from - * g_type_default_interface_ref(), or, if you know the interface has - * already been loaded, g_type_default_interface_peek(). - * pointer to an array of pointers to #GParamSpec - * structures. The paramspecs are owned by GLib, but the - * array should be freed with g_free() when you are done with - * it. + * Set the callback for a source as a #GClosure. + * If the source is not one of the standard GLib types, the @closure_callback + * and @closure_marshal fields of the #GSourceFuncs structure must have been + * filled in with pointers to appropriate functions. + */ + + +/** + * g_source_set_dummy_callback: + * @source: the source * - * Since: 2.4 - * Returns: (array length=n_properties_p) (transfer container): a + * Sets a dummy callback for @source. The callback will do nothing, and + * if the source expects a #gboolean return value, it will return %TRUE. + * (If the source expects any other type of return value, it will return + * a 0/%NULL value; whatever g_value_init() initializes a #GValue to for + * that type.) + * If the source is not one of the standard GLib types, the + * structure must have been filled in with pointers to appropriate + * functions. */ /** - * g_signal_connect_object: (skip) - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @gobject: the object to pass as data to @c_handler. - * @connect_flags: a combination of #GConnnectFlags. + * g_strdup_value_contents: + * @value: #GValue which contents are to be described. * - * This is similar to g_signal_connect_data(), but uses a closure which - * ensures that the @gobject stays alive during the call to @c_handler - * by temporarily adding a reference count to @gobject. - * Note that there is a bug in GObject that makes this function - * much less useful than it might seem otherwise. Once @gobject is - * disposed, the callback will no longer be called, but, the signal - * handler is <emphasis>not</emphasis> currently disconnected. If the - * matter, since the signal will automatically be removed, but - * if @instance persists, then the signal handler will leak. You - * should not remove the signal yourself because in a future versions of - * GObject, the handler <emphasis>will</emphasis> automatically - * be disconnected. - * It's possible to work around this problem in a way that will - * continue to work with future versions of GObject by checking - * that the signal handler is still connected before disconnected it: - * <informalexample><programlisting> - * if (g_signal_handler_is_connected (instance, id)) - * g_signal_handler_disconnect (instance, id); - * </programlisting></informalexample> + * Return a newly allocated string, which describes the contents of a + * #GValue. The main purpose of this function is to describe #GValue + * contents for debugging output, the way in which the contents are + * described may change between different GLib versions. * - * Returns: the handler id. + * Returns: Newly allocated string. */ /** - * g_signal_accumulator_first_wins: - * @ihint: standard #GSignalAccumulator parameter - * @return_accu: standard #GSignalAccumulator parameter - * @handler_return: standard #GSignalAccumulator parameter - * @dummy: standard #GSignalAccumulator parameter + * g_try_new: + * @struct_type: the type of the elements to allocate + * @n_structs: the number of elements to allocate * - * A predefined #GSignalAccumulator for signals intended to be used as a - * hook for application code to provide a particular value. Usually - * only one such value is desired and multiple handlers for the same - * signal don't make much sense (except for the case of the default - * handler defined in the class structure, in which case you will - * usually want the signal connection to override the class handler). - * This accumulator will use the return value from the first signal - * handler that is run as the return value for the signal and not run + * Attempts to allocate @n_structs elements of type @struct_type, and returns + * %NULL on failure. Contrast with g_new(), which aborts the program on failure. + * The returned pointer is cast to a pointer to the given type. + * The function returns %NULL when @n_structs is 0 of if an overflow occurs. * - * Any further handlers (ie: the first handler "wins"). - * Returns: standard #GSignalAccumulator result - * Since: 2.28 + * Since: 2.8 + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type */ /** - * g_new: + * g_try_new0: * @struct_type: the type of the elements to allocate * @n_structs: the number of elements to allocate * - * Allocates @n_structs elements of type @struct_type. + * Attempts to allocate @n_structs elements of type @struct_type, initialized + * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts + * the program on failure. * The returned pointer is cast to a pointer to the given type. - * If @n_structs is 0 it returns %NULL. - * Care is taken to avoid overflow when calculating the size of the allocated block. - * Since the returned pointer is already casted to the right type, - * it is normally unnecessary to cast it explicitly, and doing - * so might hide memory allocation errors. + * The function returns %NULL when @n_structs is 0 of if an overflow occurs. * + * Since: 2.8 * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type */ /** - * G_IS_PARAM_SPEC_GTYPE: - * @pspec: a #GParamSpec + * g_try_renew: + * @struct_type: the type of the elements to allocate + * @mem: the currently allocated memory + * @n_structs: the number of elements to allocate * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. + * Attempts to reallocate the memory pointed to by @mem, so that it now has + * space for @n_structs elements of type @struct_type, and returns %NULL on + * failure. Contrast with g_renew(), which aborts the program on failure. + * It returns the new address of the memory, which may have been moved. + * The function returns %NULL if an overflow occurs. * - * Since: 2.10 - * Returns: %TRUE on success. + * Since: 2.8 + * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type */ /** - * G_IS_PARAM_SPEC_CHAR: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. + * g_type_add_class_cache_func: (skip) + * @cache_data: data to be passed to @cache_func + * @cache_func: a #GTypeClassCacheFunc * - * Returns: %TRUE on success. + * Adds a #GTypeClassCacheFunc to be called before the reference count of a + * class goes from one to zero. This can be used to prevent premature class + * destruction. All installed #GTypeClassCacheFunc functions will be chained + * until one of them returns %TRUE. The functions have to check the class id + * passed in to figure whether they actually want to cache the class of this + * type, since all classes are routed through the same #GTypeClassCacheFunc + * chain. */ /** - * G_TYPE_BYTE_ARRAY: + * g_type_add_class_private: + * @class_type: GType of an classed type. + * @private_size: size of private structure. * - * The #GType for a boxed type holding a #GByteArray reference. + * Registers a private class structure for a classed type; + * when the class is allocated, the private structures for + * the class and all of its parent types are allocated + * sequentially in the same memory block as the public + * structures. This function should be called in the + * type's get_type() function after the type is registered. + * The private structure can be retrieved using the + * G_TYPE_CLASS_GET_PRIVATE() macro. * - * Since: 2.22 + * Since: 2.24 */ /** - * GValueTransform: - * @src_value: Source value. - * @dest_value: Target value. + * g_type_add_interface_check: (skip) + * @check_data: data to pass to @check_func + * @check_func: function to be called after each interface is initialized. * - * The type of value transformation functions which can be registered with - * g_value_register_transform_func(). + * Adds a function to be called after an interface vtable is + * initialized for any class (i.e. after the @interface_init member of + * #GInterfaceInfo has been called). + * This function is useful when you want to check an invariant that + * depends on the interfaces of a class. For instance, the + * implementation of #GObject uses this facility to check that an + * object implements all of the properties that are defined on its + * interfaces. + * + * Since: 2.4 */ /** - * g_cclosure_marshal_VOID__UINT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #guint parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * g_type_add_interface_dynamic: + * @instance_type: the #GType value of an instantiable type. + * @interface_type: the #GType value of an interface type. + * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>. + * Adds the dynamic @interface_type to @instantiable_type. The information + * contained in the #GTypePlugin structure pointed to by @plugin + * is used to manage the relationship. */ /** - * G_IS_PARAM_SPEC_UNICHAR: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. + * g_type_add_interface_static: + * @instance_type: #GType value of an instantiable type. + * @interface_type: #GType value of an interface type. + * @info: The #GInterfaceInfo structure for this (@instance_type, @interface_type) combination. * - * Returns: %TRUE on success. + * Adds the static @interface_type to @instantiable_type. The information + * contained in the #GTypeInterfaceInfo structure pointed to by @info + * is used to manage the relationship. */ /** - * GIconv: + * g_type_check_instance: + * @instance: A valid #GTypeInstance structure. + * @Returns: #TRUE if @instance is valid, #FALSE otherwise. * - * The <structname>GIConv</structname> struct wraps an - * iconv() conversion descriptor. It contains private data - * and should only be accessed using the following functions. + * Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() + * macro. */ /** - * G_SIGNAL_TYPE_STATIC_SCOPE: + * g_type_children: + * @type: The parent type. + * @n_children: (out) (allow-none): Optional #guint pointer to contain the number of child types. * - * This macro flags signal argument types for which the signal system may - * assume that instances thereof remain persistent across all signal emissions - * they are used in. This is only useful for non ref-counted, value-copy types. - * To flag a signal argument in this way, add - * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument - * of g_signal_new(). - * |[ - * g_signal_new ("size_request", - * G_TYPE_FROM_CLASS (gobject_class), - * G_SIGNAL_RUN_FIRST, - * G_STRUCT_OFFSET (GtkWidgetClass, size_request), - * NULL, NULL, - * _gtk_marshal_VOID__BOXED, - * G_TYPE_NONE, 1, - * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); - * ]| + * Return a newly allocated and 0-terminated array of type IDs, listing the + * child types of @type. The return value has to be g_free()ed after use. + * and 0-terminated array of child types. + * + * Returns: (array length=n_children) (transfer full): Newly allocated */ /** - * g_enum_complete_type_info: - * @g_enum_type: the type identifier of the type being completed - * @info: the #GTypeInfo struct to be filled in - * @const_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * g_type_class_add_private: + * @g_class: class structure for an instantiatable type + * @private_size: size of private structure. * - * This function is meant to be called from the complete_type_info() - * function of a #GTypePlugin implementation, as in the following - * example: + * Registers a private structure for an instantiatable type. + * When an object is allocated, the private structures for + * the type and all of its parent types are allocated + * sequentially in the same memory block as the public + * structures. + * Note that the accumulated size of the private structures of + * a type and all its parent types cannot excced 64kB. + * This function should be called in the type's class_init() function. + * The private structure can be retrieved using the + * G_TYPE_INSTANCE_GET_PRIVATE() macro. + * The following example shows attaching a private structure + * <structname>MyObjectPrivate</structname> to an object + * <structname>MyObject</structname> defined in the standard GObject + * fashion. + * type's class_init() function. * |[ + * typedef struct _MyObject MyObject; + * typedef struct _MyObjectPrivate MyObjectPrivate; + * struct _MyObject { + * GObject parent; + * MyObjectPrivate *priv; + * }; + * struct _MyObjectPrivate { + * int some_field; + * }; * static void - * my_enum_complete_type_info (GTypePlugin *plugin, - * GType g_type, - * GTypeInfo *info, - * GTypeValueTable *value_table) + * my_object_class_init (MyObjectClass *klass) * { - * static const GEnumValue values[] = { - * { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, - * { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, - * { 0, NULL, NULL } - * }; - * g_enum_complete_type_info (type, info, values); + * g_type_class_add_private (klass, sizeof (MyObjectPrivate)); + * } + * static void + * my_object_init (MyObject *my_object) + * { + * my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object, + * MY_TYPE_OBJECT, + * MyObjectPrivate); + * } + * static int + * my_object_get_some_field (MyObject *my_object) + * { + * MyObjectPrivate *priv = my_object->priv; + * return priv->some_field; * } * ]| + * + * Since: 2.4 */ /** - * G_TYPE_ULONG: + * g_type_class_peek: + * @type: Type ID of a classed type. * - * The fundamental type corresponding to #gulong. + * This function is essentially the same as g_type_class_ref(), except that + * the classes reference count isn't incremented. As a consequence, this function + * may return %NULL if the class of the type passed in does not currently + * exist (hasn't been referenced before). + * structure for the given type ID or %NULL if the class does not + * currently exist. + * + * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass */ /** - * G_TYPE_IS_VALUE: - * @type: A #GType value. + * g_type_class_peek_parent: + * @g_class: (type GObject.TypeClass): The #GTypeClass structure to retrieve the parent class for. * - * Checks whether the passed in type ID can be used for g_value_init(). - * That is, this macro checks whether this type provides an implementation - * of the #GTypeValueTable functions required for a type to create a #GValue of. + * This is a convenience function often needed in class initializers. + * It returns the class structure of the immediate parent type of the + * class passed in. Since derived classes hold a reference count on + * their parent classes as long as they are instantiated, the returned + * class will always exist. This function is essentially equivalent + * to: + * <programlisting> + * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); + * </programlisting> + * of @g_class. * - * Returns: Whether @type is suitable as a #GValue type. + * Returns: (type GObject.TypeClass) (transfer none): The parent class */ /** - * GParamSpecEnum: - * @parent_instance: private #GParamSpec portion - * @enum_class: the #GEnumClass for the enum - * @default_value: default value for the property specified + * g_type_class_peek_static: + * @type: Type ID of a classed type. * - * A #GParamSpec derived structure that contains the meta data for enum - * properties. + * A more efficient version of g_type_class_peek() which works only for + * static types. + * structure for the given type ID or %NULL if the class does not + * currently exist or is dynamically loaded. + * + * Since: 2.4 + * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass */ /** - * G_VALUE_COLLECT_INIT: - * @value: a #GValue return location. @value must contain only 0 bytes. - * @_value_type: the #GType to use for @value. - * @var_args: the va_list variable; it may be evaluated multiple times - * @flags: flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. - * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails + * g_type_class_ref: + * @type: Type ID of a classed type. * - * Collects a variable argument value from a va_list. We have to - * implement the varargs collection as a macro, because on some systems - * va_list variables cannot be passed by reference. + * Increments the reference count of the class structure belonging to + * exist already. + * structure for the given type ID. * - * Since: 2.24 + * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass */ /** - * g_type_fundamental_next: + * g_type_class_unref: + * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. * - * Returns the next free fundamental type id which can be used to - * register a new fundamental type with g_type_register_fundamental(). - * The returned type ID represents the highest currently registered - * fundamental type identifier. - * or 0 if the type system ran out of fundamental type IDs. + * Decrements the reference count of the class structure being passed in. + * Once the last reference count of a class has been released, classes + * may be finalized by the type system, so further dereferencing of a + * class pointer after g_type_class_unref() are invalid. + */ + + +/** + * g_type_class_unref_uncached: (skip) + * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. * - * Returns: The nextmost fundamental type ID to be registered, + * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc + * implementations. It unreferences a class without consulting the chain + * of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur + * otherwise. */ /** - * g_value_array_append: - * @value_array: #GValueArray to add an element to - * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL + * g_type_create_instance: (skip) + * @type: An instantiatable type to create an instance for. * - * Insert a copy of @value as last element of @value_array. If @value is - * %NULL, an uninitialized value is appended. + * Creates and initializes an instance of @type if @type is valid and + * can be instantiated. The type system only performs basic allocation + * happen through functions supplied by the type's fundamental type + * implementation. So use of g_type_create_instance() is reserved for + * implementators of fundamental types only. E.g. instances of the + * #GObject hierarchy should be created via g_object_new() and + * <emphasis>never</emphasis> directly through + * g_type_create_instance() which doesn't handle things like singleton + * use this function, unless you're implementing a fundamental + * type. Also language bindings should <emphasis>not</emphasis> use + * this function but g_object_new() instead. + * treatment by the fundamental type implementation. * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * And structure setups for instances: actual instance creation should + * Objects or object construction. note: Do <emphasis>not</emphasis> + * Returns: An allocated and initialized instance, subject to further */ /** - * GStrv: + * g_type_default_interface_peek: + * @g_type: an interface type * - * A C representable type name for #G_TYPE_STRV. + * If the interface type @g_type is currently in use, returns its + * default interface vtable. + * vtable for the interface, or %NULL if the type is not currently in + * use. + * + * Since: 2.4 + * Returns: (type GObject.TypeInterface) (transfer none): the default */ /** - * G_TYPE_FROM_INTERFACE: - * @g_iface: Location of a valid #GTypeInterface structure. + * g_type_default_interface_ref: + * @g_type: an interface type * - * Get the type identifier from a given @interface structure. - * This macro should only be used in type implementations. + * Increments the reference count for the interface type @g_type, + * and returns the default interface vtable for the type. + * If the type is not currently in use, then the default vtable + * for the type will be created and initalized by calling + * the base interface init and default vtable init functions for + * the type (the @<structfield>base_init</structfield> + * and <structfield>class_init</structfield> members of #GTypeInfo). + * Calling g_type_default_interface_ref() is useful when you + * want to make sure that signals and properties for an interface + * have been installed. + * vtable for the interface; call g_type_default_interface_unref() + * when you are done using the interface. * - * Returns: the #GType + * Since: 2.4 + * Returns: (type GObject.TypeInterface) (transfer none): the default */ /** - * G_VALUE_HOLDS_BOXED: - * @value: a valid #GValue structure + * g_type_default_interface_unref: + * @g_iface: (type GObject.TypeInterface): the default vtable structure for a interface, as returned by g_type_default_interface_ref() * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. + * Decrements the reference count for the type corresponding to the + * interface default vtable @g_iface. If the type is dynamic, then + * when no one is using the interface and all references have + * been released, the finalize function for the interface's default + * vtable (the <structfield>class_finalize</structfield> member of + * #GTypeInfo) will be called. * - * Returns: %TRUE on success. + * Since: 2.4 */ /** - * G_TYPE_PARAM_BOXED: + * g_type_depth: + * @type: A #GType value. * - * The #GType of #GParamSpecBoxed. + * Returns the length of the ancestry of the passed in type. This + * includes the type itself, so that e.g. a fundamental type has depth 1. + * + * Returns: The depth of @type. */ /** - * g_closure_remove_invalidate_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func - * @notify_func: the callback function to remove + * g_type_free_instance: + * @instance: an instance of a type. * - * Removes an invalidation notifier. - * Notice that notifiers are automatically removed after they are run. + * Frees an instance of a type, returning it to the instance pool for + * the type, if there is one. + * Like g_type_create_instance(), this function is reserved for + * implementors of fundamental types. */ /** - * g_value_get_string: - * @value: a valid #GValue of type %G_TYPE_STRING + * g_type_from_name: + * @name: Type name to lookup. * - * Get the contents of a %G_TYPE_STRING #GValue. + * Lookup the type ID from a given type name, returning 0 if no type + * has been registered under this name (this is the preferred method + * to find out by name whether a specific type has been registered + * yet). * - * Returns: string content of @value + * Returns: Corresponding type ID or 0. */ /** - * G_FLAGS_CLASS: - * @class: a valid #GFlagsClass + * g_type_fundamental: + * @type_id: valid type ID * - * Casts a derived #GFlagsClass structure into a #GFlagsClass structure. + * Internal function, used to extract the fundamental type ID portion. + * use G_TYPE_FUNDAMENTAL() instead. + * + * Returns: fundamental type ID */ /** - * g_closure_add_marshal_guards: (skip) - * @closure: a #GClosure - * @pre_marshal_data: data to pass to @pre_marshal_notify - * @pre_marshal_notify: a function to call before the closure callback - * @post_marshal_data: data to pass to @post_marshal_notify - * @post_marshal_notify: a function to call after the closure callback + * g_type_fundamental_next: * - * Adds a pair of notifiers which get invoked before and after the - * closure callback, respectively. This is typically used to protect - * the extra arguments for the duration of the callback. See - * g_object_watch_closure() for an example of marshal guards. + * Returns the next free fundamental type id which can be used to + * register a new fundamental type with g_type_register_fundamental(). + * The returned type ID represents the highest currently registered + * fundamental type identifier. + * or 0 if the type system ran out of fundamental type IDs. + * + * Returns: The nextmost fundamental type ID to be registered, */ /** - * g_value_set_string_take_ownership: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: duplicated unowned string to be set + * g_type_get_plugin: + * @type: The #GType to retrieve the plugin for. * - * This is an internal function introduced mainly for C marshallers. + * Returns the #GTypePlugin structure for @type or + * %NULL if @type does not have a #GTypePlugin structure. + * dynamic type, %NULL otherwise. * - * Deprecated: 2.4: Use g_value_take_string() instead. + * Returns: (transfer none): The corresponding plugin if @type is a */ /** - * g_main_quit: - * @loop: a #GMainLoop + * g_type_get_qdata: + * @type: a #GType + * @quark: a #GQuark id to identify the data * - * Stops the #GMainLoop. - * If g_main_run() was called to run the #GMainLoop, it will now return. + * Obtains data which has previously been attached to @type + * with g_type_set_qdata(). * - * Deprecated: 2.2: Use g_main_loop_quit() instead + * Returns: (transfer none): the data, or %NULL if no data was found */ /** - * GOptionError: - * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options(). - * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed. - * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed. + * g_type_init: * - * Error codes returned by option parsing. + * Prior to any use of the type system, g_type_init() has to be called + * to initialize the type system and assorted other code portions + * (such as the various fundamental type implementations or the signal + * system). + * Since version 2.24 this also initializes the thread system */ /** - * g_type_interface_peek: - * @instance_class: (type GObject.TypeClass): A #GTypeClass structure. - * @iface_type: An interface ID which this class conforms to. - * - * Returns the #GTypeInterface structure of an interface to which the - * passed in class conforms. - * structure of iface_type if implemented by @instance_class, %NULL - * otherwise + * g_type_init_with_debug_flags: + * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. * - * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface + * Similar to g_type_init(), but additionally sets debug flags. */ @@ -9296,252 +9283,302 @@ /** - * GClosureMarshal: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. - * @n_param_values: the length of the @param_values array - * @param_values: an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() + * g_type_interface_get_plugin: + * @instance_type: the #GType value of an instantiatable type. + * @interface_type: the #GType value of an interface type. * - * The type used for marshaller functions. - */ - - -/** - * g_signal_override_class_closure: - * @signal_id: the signal id - * @instance_type: the instance type on which to override the class closure for the signal. - * @class_closure: the closure. + * Returns the #GTypePlugin structure for the dynamic interface + * have a #GTypePlugin structure. See g_type_add_interface_dynamic(). + * interface @interface_type of @instance_type. * - * Overrides the class closure (i.e. the default handler) for the given signal - * for emissions on instances of @instance_type. @instance_type must be derived - * from the type to which the signal belongs. - * See g_signal_chain_from_overridden() and - * g_signal_chain_from_overridden_handler() for how to chain up to the - * parent class closure from inside the overridden one. + * Returns: (transfer none): the #GTypePlugin for the dynamic */ /** - * G_TYPE_POINTER: + * g_type_interface_peek: + * @instance_class: (type GObject.TypeClass): A #GTypeClass structure. + * @iface_type: An interface ID which this class conforms to. * - * The fundamental type corresponding to #gpointer. + * Returns the #GTypeInterface structure of an interface to which the + * passed in class conforms. + * structure of iface_type if implemented by @instance_class, %NULL + * otherwise + * + * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface */ /** - * g_value_set_boxed_take_ownership: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: duplicated unowned boxed value to be set + * g_type_interface_peek_parent: + * @g_iface: (type GObject.TypeInterface): A #GTypeInterface structure. * - * This is an internal function introduced mainly for C marshallers. + * Returns the corresponding #GTypeInterface structure of the parent type + * of the instance type to which @g_iface belongs. This is useful when + * deriving the implementation of an interface from the parent type and + * then possibly overriding some methods. + * corresponding #GTypeInterface structure of the parent type of the + * instance type to which @g_iface belongs, or %NULL if the parent + * type doesn't conform to the interface. * - * Deprecated: 2.4: Use g_value_take_boxed() instead. + * Returns: (transfer none) (type GObject.TypeInterface): The */ /** - * GSource: + * g_type_interface_prerequisites: + * @interface_type: an interface type + * @n_prerequisites: (out) (allow-none): location to return the number of prerequisites, or %NULL * - * The <structname>GSource</structname> struct is an opaque data type - * representing an event source. + * Returns the prerequisites of an interfaces type. + * newly-allocated zero-terminated array of #GType containing + * the prerequisites of @interface_type + * + * Since: 2.2 + * Returns: (array length=n_prerequisites) (transfer full): a */ /** - * g_hash_table_freeze: - * @hash_table: a #GHashTable + * g_type_interfaces: + * @type: The type to list interface types for. + * @n_interfaces: (out) (allow-none): Optional #guint pointer to contain the number of interface types. * - * This function is deprecated and will be removed in the next major - * release of GLib. It does nothing. + * Return a newly allocated and 0-terminated array of type IDs, listing the + * interface types that @type conforms to. The return value has to be + * g_free()ed after use. + * allocated and 0-terminated array of interface types. + * + * Returns: (array length=n_interfaces) (transfer full): Newly */ /** - * G_OBJECT_CLASS_TYPE: - * @class: a valid #GObjectClass + * g_type_is_a: + * @type: Type to check anchestry for. + * @is_a_type: Possible anchestor of @type or interface @type could conform to. * - * Get the type id of a class structure. + * If @is_a_type is a derivable type, check whether @type is a + * descendant of @is_a_type. If @is_a_type is an interface, check + * whether @type conforms to it. * - * Returns: Type id of @class. + * Returns: %TRUE if @type is_a @is_a_type holds true. */ /** - * G_PRIORITY_HIGH: + * g_type_module_add_interface: + * @module: a #GTypeModule + * @instance_type: type to which to add the interface. + * @interface_type: interface type to add + * @interface_info: type information structure * - * Use this for high priority event sources. - * It is not used within GLib or GTK+. + * Registers an additional interface for a type, whose interface lives + * in the given type plugin. If the interface was already registered + * for the type in this plugin, nothing will be done. + * As long as any instances of the type exist, the type plugin will + * not be unloaded. */ /** - * G_TYPE_RESERVED_USER_FIRST: + * g_type_module_register_enum: + * @module: a #GTypeModule + * @name: name for the type + * @const_static_values: an array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. * - * First available fundamental type number to create new fundamental - * type id with G_TYPE_MAKE_FUNDAMENTAL(). + * Looks up or registers an enumeration that is implemented with a particular + * type plugin. If a type with name @type_name was previously registered, + * the #GType identifier for the type is returned, otherwise the type + * is newly registered, and the resulting #GType identifier returned. + * As long as any instances of the type exist, the type plugin will + * not be unloaded. + * + * Since: 2.6 + * Returns: the new or existing type ID */ /** - * G_TYPE_IO_CHANNEL: + * g_type_module_register_flags: + * @module: a #GTypeModule + * @name: name for the type + * @const_static_values: an array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. * - * The #GType for #GIOChannel. + * Looks up or registers a flags type that is implemented with a particular + * type plugin. If a type with name @type_name was previously registered, + * the #GType identifier for the type is returned, otherwise the type + * is newly registered, and the resulting #GType identifier returned. + * As long as any instances of the type exist, the type plugin will + * not be unloaded. + * + * Since: 2.6 + * Returns: the new or existing type ID */ /** - * GRegexCompileFlags: - * @G_REGEX_CASELESS: Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting. - * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting. - * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting. - * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting. - * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. - * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set. - * @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern. - * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. - * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way). - * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches. - * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched. - * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'. - * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'. - * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'. + * g_type_module_register_type: + * @module: a #GTypeModule + * @parent_type: the type for the parent class + * @type_name: name for the type + * @type_info: type information structure + * @flags: flags field providing details about the type * - * Flags specifying compile-time options. + * Looks up or registers a type that is implemented with a particular + * type plugin. If a type with name @type_name was previously registered, + * the #GType identifier for the type is returned, otherwise the type + * is newly registered, and the resulting #GType identifier returned. + * When reregistering a type (typically because a module is unloaded + * then reloaded, and reinitialized), @module and @parent_type must + * be the same as they were previously. + * As long as any instances of the type exist, the type plugin will + * not be unloaded. * - * Since: 2.14 + * Returns: the new or existing type ID */ /** - * GParamSpecValueArray: - * @parent_instance: private #GParamSpec portion - * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL - * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements + * g_type_module_set_name: + * @module: a #GTypeModule. + * @name: a human-readable name to use in error messages. * - * A #GParamSpec derived structure that contains the meta data for #GValueArray properties. + * Sets the name for a #GTypeModule */ /** - * G_PARAM_SPEC_DOUBLE: - * @pspec: a valid #GParamSpec instance + * g_type_module_unuse: + * @module: a #GTypeModule * - * Cast a #GParamSpec instance into a #GParamSpecDouble. + * Decreases the use count of a #GTypeModule by one. If the + * result is zero, the module will be unloaded. (However, the + * #GTypeModule will not be freed, and types associated with the + * #GTypeModule are not unregistered. Once a #GTypeModule is + * initialized, it must exist forever.) */ /** - * G_TYPE_LONG: + * g_type_module_use: + * @module: a #GTypeModule * - * The fundamental type corresponding to #glong. + * Increases the use count of a #GTypeModule by one. If the + * use count was zero before, the plugin will be loaded. + * If loading the plugin fails, the use count is reset to + * its prior value. + * loading the plugin failed. + * + * Returns: %FALSE if the plugin needed to be loaded and */ /** - * G_VARIANT_TYPE_UINT16: + * g_type_name: + * @type: Type to return name for. * - * The type of an integer value that can range from 0 to 65535. - * There were about this many people living in Toronto in the 1870s. + * Get the unique name that is assigned to a type ID. Note that this + * function (like all other GType API) cannot cope with invalid type + * IDs. %G_TYPE_INVALID may be passed to this function, as may be any + * other validly registered type ID, but randomized type IDs should + * not be passed in and will most likely lead to a crash. + * + * Returns: Static type name or %NULL. */ /** - * g_param_spec_internal: (skip) - * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM - * @name: the canonical name of the property - * @nick: the nickname of the property - * @blurb: a short description of the property - * @flags: a combination of #GParamFlags + * g_type_next_base: + * @leaf_type: Descendant of @root_type and the type to be returned. + * @root_type: Immediate parent of the returned type. * - * Creates a new #GParamSpec instance. - * A property name consists of segments consisting of ASCII letters and - * digits, separated by either the '-' or '_' character. The first - * character of a property name must be a letter. Names which violate these - * rules lead to undefined behaviour. - * When creating and looking up a #GParamSpec, either separator can be - * used, but they cannot be mixed. Using '-' is considerably more - * efficient and in fact required when using property names as detail - * strings for signals. - * Beyond the name, #GParamSpec<!-- -->s have two more descriptive - * strings associated with them, the @nick, which should be suitable - * for use as a label for the property in a property editor, and the - * e.g. a tooltip. The @nick and @blurb should ideally be localized. + * Given a @leaf_type and a @root_type which is contained in its + * anchestry, return the type that @root_type is the immediate parent + * of. In other words, this function determines the type that is + * derived directly from @root_type which is also a base class of + * be used to determine the types and order in which the leaf type is + * descended from the root type. * - * Returns: a newly allocated #GParamSpec instance + * Returns: Immediate child of @root_type and anchestor of @leaf_type. */ /** - * g_value_set_ulong: - * @value: a valid #GValue of type %G_TYPE_ULONG - * @v_ulong: unsigned long integer value to be set + * g_type_parent: + * @type: The derived type. * - * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. + * Return the direct parent type of the passed in type. If the passed + * in type has no parent, i.e. is a fundamental type, 0 is returned. + * + * Returns: The parent type. */ /** - * GParamSpecBoxed: - * @parent_instance: private #GParamSpec portion + * g_type_plugin_complete_interface_info: + * @plugin: the #GTypePlugin + * @instance_type: the #GType of an instantiable type to which the interface is added + * @interface_type: the #GType of the interface whose info is completed + * @info: the #GInterfaceInfo to fill in * - * A #GParamSpec derived structure that contains the meta data for boxed properties. + * Calls the @complete_interface_info function from the + * #GTypePluginClass of @plugin. There should be no need to use this + * function outside of the GObject type system itself. */ /** - * G_OBJECT_GET_CLASS: - * @object: a #GObject instance. - * - * Get the class structure associated to a #GObject instance. + * g_type_plugin_complete_type_info: + * @plugin: a #GTypePlugin + * @g_type: the #GType whose info is completed + * @info: the #GTypeInfo struct to fill in + * @value_table: the #GTypeValueTable to fill in * - * Returns: pointer to object class structure. + * Calls the @complete_type_info function from the #GTypePluginClass of @plugin. + * There should be no need to use this function outside of the GObject + * type system itself. */ /** - * g_param_spec_get_redirect_target: - * @pspec: a #GParamSpec - * - * If the paramspec redirects operations to another paramspec, - * returns that paramspec. Redirect is used typically for - * providing a new implementation of a property in a derived - * type while preserving all the properties from the parent - * type. Redirection is established by creating a property - * of type #GParamSpecOverride. See g_object_class_override_property() - * for an example of the use of this capability. - * paramspec should be redirected, or %NULL if none. + * g_type_plugin_unuse: + * @plugin: a #GTypePlugin * - * Since: 2.4 - * Returns: (transfer none): paramspec to which requests on this + * Calls the @unuse_plugin function from the #GTypePluginClass of + * the GObject type system itself. */ /** - * g_main_is_running: - * @loop: a #GMainLoop - * - * Checks if the main loop is running. + * g_type_plugin_use: + * @plugin: a #GTypePlugin * - * Returns: %TRUE if the main loop is running - * Deprecated: 2.2: Use g_main_loop_is_running() instead + * Calls the @use_plugin function from the #GTypePluginClass of + * the GObject type system itself. */ /** - * g_boxed_free: - * @boxed_type: The type of @boxed. - * @boxed: The boxed structure to be freed. + * g_type_qname: + * @type: Type to return quark of type name for. * - * Free the boxed structure @boxed which is of type @boxed_type. + * Get the corresponding quark of the type IDs name. + * + * Returns: The type names quark or 0. */ /** - * G_TYPE_OBJECT: + * g_type_query: + * @type: the #GType value of a static, classed type. + * @query: (out caller-allocates): A user provided structure that is filled in with constant values upon success. * - * The fundamental type for #GObject. + * Queries the type system for information about a specific type. + * This function will fill in a user-provided structure to hold + * type-specific information. If an invalid #GType is passed in, the + * #GTypeQuery structure should be considered constant and have to be + * left untouched. */ @@ -9562,936 +9599,960 @@ /** - * GParamSpecPointer: - * @parent_instance: private #GParamSpec portion + * g_type_register_fundamental: + * @type_id: A predefined type identifier. + * @type_name: 0-terminated string used as the name of the new type. + * @info: The #GTypeInfo structure for this type. + * @finfo: The #GTypeFundamentalInfo structure for this type. + * @flags: Bitwise combination of #GTypeFlags values. * - * A #GParamSpec derived structure that contains the meta data for pointer properties. + * Registers @type_id as the predefined identifier and @type_name as the + * name of a fundamental type. The type system uses the information + * contained in the #GTypeInfo structure pointed to by @info and the + * #GTypeFundamentalInfo structure pointed to by @finfo to manage the + * type and its instances. The value of @flags determines additional + * characteristics of the fundamental type. + * + * Returns: The predefined type identifier. */ /** - * g_main_iteration: - * @may_block: set to %TRUE if it should block (i.e. wait) until an event source becomes ready. It will return after an event source has been processed. If set to %FALSE it will return immediately if no event source is ready to be processed. + * g_type_register_static: + * @parent_type: Type from which this type will be derived. + * @type_name: 0-terminated string used as the name of the new type. + * @info: The #GTypeInfo structure for this type. + * @flags: Bitwise combination of #GTypeFlags values. * - * Runs a single iteration for the default #GMainContext. + * Registers @type_name as the name of a new static type derived from + * #GTypeInfo structure pointed to by @info to manage the type and its + * instances (if not abstract). The value of @flags determines the nature + * (e.g. abstract or not) of the type. * - * Returns: %TRUE if more events are pending. - * Deprecated: 2.2: Use g_main_context_iteration() instead. + * Returns: The new type identifier. */ /** - * g_signal_connect_swapped: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. + * g_type_register_static_simple: (skip) + * @parent_type: Type from which this type will be derived. + * @type_name: 0-terminated string used as the name of the new type. + * @class_size: Size of the class structure (see #GTypeInfo) + * @class_init: Location of the class initialization function (see #GTypeInfo) + * @instance_size: Size of the instance structure (see #GTypeInfo) + * @instance_init: Location of the instance initialization function (see #GTypeInfo) + * @flags: Bitwise combination of #GTypeFlags values. * - * Connects a #GCallback function to a signal for a particular object. - * The instance on which the signal is emitted and @data will be swapped when - * calling the handler. + * Registers @type_name as the name of a new static type derived from + * abstract or not) of the type. It works by filling a #GTypeInfo + * struct and calling g_type_register_static(). * - * Returns: the handler id + * Since: 2.12 + * Returns: The new type identifier. */ /** - * g_value_copy: - * @src_value: An initialized #GValue structure. - * @dest_value: An initialized #GValue structure of the same type as @src_value. + * g_type_remove_class_cache_func: (skip) + * @cache_data: data that was given when adding @cache_func + * @cache_func: a #GTypeClassCacheFunc * - * Copies the value of @src_value into @dest_value. + * Removes a previously installed #GTypeClassCacheFunc. The cache + * maintained by @cache_func has to be empty when calling + * g_type_remove_class_cache_func() to avoid leaks. */ /** - * G_VARIANT_TYPE_UINT64: + * g_type_remove_interface_check: (skip) + * @check_data: callback data passed to g_type_add_interface_check() + * @check_func: callback function passed to g_type_add_interface_check() * - * The type of an integer value that can range from 0 to - * 18446744073709551616. That's a really big number, but a Rubik's - * cube can have a bit more than twice as many possible positions. + * Removes an interface check function added with + * g_type_add_interface_check(). + * + * Since: 2.4 */ /** - * G_TYPE_PARAM_GTYPE: + * g_type_set_qdata: + * @type: a #GType + * @quark: a #GQuark id to identify the data + * @data: the data * - * The #GType of #GParamSpecGType. + * Attaches arbitrary data to a type. + */ + + +/** + * g_type_value_table_peek: (skip) + * @type: A #GType value. * - * Since: 2.10 + * Returns the location of the #GTypeValueTable associated with @type. + * <emphasis>Note that this function should only be used from source code + * that implements or has internal knowledge of the implementation of + * %NULL if there is no #GTypeValueTable associated with @type. + * + * Returns: Location of the #GTypeValueTable associated with @type or */ /** - * G_OBJECT: - * @object: Object which is subject to casting. + * g_value_array_append: + * @value_array: #GValueArray to add an element to + * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL * - * Casts a #GObject or derived pointer into a (GObject*) pointer. - * Depending on the current debugging level, this function may invoke - * certain runtime checks to identify invalid casts. + * Insert a copy of @value as last element of @value_array. If @value is + * %NULL, an uninitialized value is appended. + * + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * GVariantType: + * g_value_array_copy: + * @value_array: #GValueArray to copy * - * A type in the GVariant type system. - * Two types may not be compared by value; use g_variant_type_equal() or - * g_variant_type_is_subtype(). May be copied using - * g_variant_type_copy() and freed using g_variant_type_free(). + * Construct an exact copy of a #GValueArray by duplicating all its + * contents. + * + * Returns: (transfer full): Newly allocated copy of #GValueArray */ /** - * G_DATALIST_FLAGS_MASK: + * g_value_array_free: + * @value_array: #GValueArray to free * - * A bitmask that restricts the possible flags passed to - * g_datalist_set_flags(). Passing a flags value where - * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. + * Free a #GValueArray including its contents. */ /** - * GOptionContext: + * g_value_array_get_nth: + * @value_array: #GValueArray to get a value from + * @index_: index of the value of interest * - * A <structname>GOptionContext</structname> struct defines which options - * are accepted by the commandline option parser. The struct has only private - * fields and should not be directly accessed. + * Return a pointer to the value at @index_ containd in @value_array. + * + * Returns: (transfer none): pointer to a value at @index_ in @value_array */ /** - * g_type_module_unuse: - * @module: a #GTypeModule + * g_value_array_insert: + * @value_array: #GValueArray to add an element to + * @index_: insertion position, must be <= value_array->n_values + * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL * - * Decreases the use count of a #GTypeModule by one. If the - * result is zero, the module will be unloaded. (However, the - * #GTypeModule will not be freed, and types associated with the - * #GTypeModule are not unregistered. Once a #GTypeModule is - * initialized, it must exist forever.) + * Insert a copy of @value at specified position into @value_array. If @value + * is %NULL, an uninitialized value is inserted. + * + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * G_TYPE_IS_ENUM: - * @type: a #GType ID. + * g_value_array_new: + * @n_prealloced: number of values to preallocate space for * - * Checks whether @type "is a" %G_TYPE_ENUM. + * Allocate and initialize a new #GValueArray, optionally preserve space + * for @n_prealloced elements. New arrays always contain 0 elements, + * regardless of the value of @n_prealloced. * - * Returns: %TRUE if @type "is a" %G_TYPE_ENUM. + * Returns: a newly allocated #GValueArray with 0 values */ /** - * G_TYPE_RESERVED_GLIB_FIRST: + * g_value_array_prepend: + * @value_array: #GValueArray to add an element to + * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL * - * First fundamental type number to create a new fundamental type id with - * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. + * Insert a copy of @value as first element of @value_array. If @value is + * %NULL, an uninitialized value is prepended. + * + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * G_INITIALLY_UNOWNED_CLASS: - * @class: a valid #GInitiallyUnownedClass + * g_value_array_remove: + * @value_array: #GValueArray to remove an element from + * @index_: position of value to remove, must be < value_array->n_values * - * Casts a derived #GInitiallyUnownedClass structure into a - * #GInitiallyUnownedClass structure. + * Remove the value at position @index_ from @value_array. + * + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * g_main_pending: + * g_value_array_sort: + * @value_array: #GValueArray to sort + * @compare_func: (scope call): function to compare elements * - * Checks if any events are pending for the default #GMainContext - * (i.e. ready to be processed). + * Sort @value_array using @compare_func to compare the elements accoring to + * the semantics of #GCompareFunc. + * The current implementation uses Quick-Sort as sorting algorithm. * - * Returns: %TRUE if any events are pending. - * Deprected: 2.2: Use g_main_context_pending() instead. + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * G_TYPE_IS_INTERFACE: - * @type: A #GType value. + * g_value_array_sort_with_data: + * @value_array: #GValueArray to sort + * @compare_func: (scope call): function to compare elements + * @user_data: (closure): extra data argument provided for @compare_func * - * Checks if @type is an interface type. - * An interface type provides a pure API, the implementation - * of which is provided by another type (which is then said to conform - * to the interface). GLib interfaces are somewhat analogous to Java - * interfaces and C++ classes containing only pure virtual functions, - * with the difference that GType interfaces are not derivable (but see - * g_type_interface_add_prerequisite() for an alternative). + * Sort @value_array using @compare_func to compare the elements accoring + * to the semantics of #GCompareDataFunc. + * The current implementation uses Quick-Sort as sorting algorithm. * - * Returns: %TRUE on success. + * Rename to: g_value_array_sort + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * g_value_set_static_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: static string to be set + * g_value_copy: + * @src_value: An initialized #GValue structure. + * @dest_value: An initialized #GValue structure of the same type as @src_value. * - * Set the contents of a %G_TYPE_STRING #GValue to @v_string. - * The string is assumed to be static, and is thus not duplicated - * when setting the #GValue. + * Copies the value of @src_value into @dest_value. */ /** - * g_param_value_defaults: - * @pspec: a valid #GParamSpec - * @value: a #GValue of correct type for @pspec + * g_value_dup_boxed: (skip) + * @value: a valid #GValue of %G_TYPE_BOXED derived type * - * Checks whether @value contains the default value as specified in @pspec. + * Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, + * the boxed value is duplicated and needs to be later freed with + * return_value); * - * Returns: whether @value contains the canonical default for this @pspec + * G_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), + * Returns: boxed contents of @value */ /** - * G_OBJECT_WARN_INVALID_PROPERTY_ID: - * @object: the #GObject on which set_property() or get_property() was called - * @property_id: the numeric id of the property - * @pspec: the #GParamSpec of the property + * g_value_dup_object: + * @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT * - * This macro should be used to emit a standard warning about unexpected - * properties in set_property() and get_property() implementations. + * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing + * its reference count. + * should be unreferenced when no longer needed. + * + * Returns: (type GObject.Object) (transfer full): object content of @value, */ /** - * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT: + * g_value_dup_param: (skip) + * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM * - * Allowed characters in path elements. Includes "!$&'()*+,;=:@". + * Get the contents of a %G_TYPE_PARAM #GValue, increasing its + * reference count. + * no longer needed. + * + * Returns: #GParamSpec content of @value, should be unreferenced when */ /** - * g_param_spec_override: (skip) - * @name: the name of the property. - * @overridden: The property that is being overridden + * g_value_dup_string: + * @value: a valid #GValue of type %G_TYPE_STRING * - * Creates a new property of type #GParamSpecOverride. This is used - * to direct operations to another paramspec, and will not be directly - * useful unless you are implementing a new base type similar to GObject. + * Get a copy the contents of a %G_TYPE_STRING #GValue. * - * Since: 2.4 - * Returns: the newly created #GParamSpec + * Returns: a newly allocated copy of the string content of @value */ /** - * g_type_value_table_peek: (skip) - * @type: A #GType value. + * g_value_dup_variant: + * @value: a valid #GValue of type %G_TYPE_VARIANT * - * Returns the location of the #GTypeValueTable associated with @type. - * <emphasis>Note that this function should only be used from source code - * that implements or has internal knowledge of the implementation of - * %NULL if there is no #GTypeValueTable associated with @type. + * Get the contents of a variant #GValue, increasing its refcount. + * g_variant_unref() when no longer needed * - * Returns: Location of the #GTypeValueTable associated with @type or + * Returns: variant contents of @value, should be unrefed using + * Since: 2.26 */ /** - * g_type_default_interface_peek: - * @g_type: an interface type + * g_value_fits_pointer: + * @value: An initialized #GValue structure. * - * If the interface type @g_type is currently in use, returns its - * default interface vtable. - * vtable for the interface, or %NULL if the type is not currently in - * use. + * Determines if @value will fit inside the size of a pointer value. + * This is an internal function introduced mainly for C marshallers. * - * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default + * Returns: %TRUE if @value will fit inside a pointer value. */ /** - * g_strdup_value_contents: - * @value: #GValue which contents are to be described. + * g_value_get_boolean: + * @value: a valid #GValue of type %G_TYPE_BOOLEAN * - * Return a newly allocated string, which describes the contents of a - * #GValue. The main purpose of this function is to describe #GValue - * contents for debugging output, the way in which the contents are - * described may change between different GLib versions. + * Get the contents of a %G_TYPE_BOOLEAN #GValue. * - * Returns: Newly allocated string. + * Returns: boolean contents of @value */ /** - * G_TYPE_PARAM_VARIANT: + * g_value_get_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type * - * The #GType of #GParamSpecVariant. + * Get the contents of a %G_TYPE_BOXED derived #GValue. * - * Since: 2.26 + * Returns: (transfer none): boxed contents of @value */ /** - * GObjectFinalizeFunc: - * @object: the #GObject being finalized + * g_value_get_char: + * @value: a valid #GValue of type %G_TYPE_CHAR * - * The type of the @finalize function of #GObjectClass. + * Get the contents of a %G_TYPE_CHAR #GValue. + * + * Returns: character contents of @value */ /** - * g_closure_unref: - * @closure: #GClosure to decrement the reference count on + * g_value_get_double: + * @value: a valid #GValue of type %G_TYPE_DOUBLE * - * Decrements the reference count of a closure after it was previously - * incremented by the same caller. If no other callers are using the - * closure, then the closure will be destroyed and freed. + * Get the contents of a %G_TYPE_DOUBLE #GValue. + * + * Returns: double contents of @value */ /** - * g_value_type_compatible: - * @src_type: source type to be copied. - * @dest_type: destination type for copying. + * g_value_get_enum: + * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM * - * Returns whether a #GValue of type @src_type can be copied into - * a #GValue of type @dest_type. + * Get the contents of a %G_TYPE_ENUM #GValue. * - * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. + * Returns: enum contents of @value */ /** - * g_signal_emitv: - * @instance_and_params: argument list for the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. - * @signal_id: the signal id - * @detail: the detail - * @return_value: Location to store the return value of the signal emission. + * g_value_get_flags: + * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS * - * Emits a signal. - * Note that g_signal_emitv() doesn't change @return_value if no handlers are - * connected, in contrast to g_signal_emit() and g_signal_emit_valist(). + * Get the contents of a %G_TYPE_FLAGS #GValue. + * + * Returns: flags contents of @value */ /** - * G_INITIALLY_UNOWNED: - * @object: Object which is subject to casting. + * g_value_get_float: + * @value: a valid #GValue of type %G_TYPE_FLOAT * - * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) - * pointer. Depending on the current debugging level, this function may invoke - * certain runtime checks to identify invalid casts. + * Get the contents of a %G_TYPE_FLOAT #GValue. + * + * Returns: float contents of @value */ /** - * G_TYPE_FROM_INSTANCE: - * @instance: Location of a valid #GTypeInstance structure. + * g_value_get_gtype: + * @value: a valid #GValue of type %G_TYPE_GTYPE * - * Get the type identifier from a given @instance structure. - * This macro should only be used in type implementations. + * Get the contents of a %G_TYPE_GTYPE #GValue. * - * Returns: the #GType + * Since: 2.12 + * Returns: the #GType stored in @value */ /** - * G_VALUE_LCOPY: - * @value: a #GValue return location. @value is supposed to be initialized according to the value type to be collected - * @var_args: the va_list variable; it may be evaluated multiple times - * @flags: flags which are passed on to the lcopy_value() function of the #GTypeValueTable of @value. - * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails + * g_value_get_int: + * @value: a valid #GValue of type %G_TYPE_INT * - * Collects a value's variable argument locations from a va_list. Usage is - * analogous to G_VALUE_COLLECT(). + * Get the contents of a %G_TYPE_INT #GValue. + * + * Returns: integer contents of @value */ /** - * G_VALUE_HOLDS_FLAGS: - * @value: a valid #GValue structure + * g_value_get_int64: + * @value: a valid #GValue of type %G_TYPE_INT64 * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. + * Get the contents of a %G_TYPE_INT64 #GValue. * - * Returns: %TRUE on success. + * Returns: 64bit integer contents of @value */ /** - * g_signal_new: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_offset: The offset of the function pointer in the class structure for this type. Used to invoke a class method generically. Pass 0 to not associate a class method slot with this signal. - * @accumulator: the accumulator for this signal; may be %NULL. - * @accu_data: user data for the @accumulator. - * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. - * @n_params: the number of parameter types to follow. - * @...: a list of types, one for each parameter. + * g_value_get_long: + * @value: a valid #GValue of type %G_TYPE_LONG * - * Creates a new signal. (This is usually done in the class initializer.) - * A signal name consists of segments consisting of ASCII letters and - * digits, separated by either the '-' or '_' character. The first - * character of a signal name must be a letter. Names which violate these - * rules lead to undefined behaviour of the GSignal system. - * When registering a signal and looking up a signal, either separator can - * be used, but they cannot be mixed. - * If 0 is used for @class_offset subclasses cannot override the class handler - * in their <code>class_init</code> method by doing - * <code>super_class->signal_handler = my_signal_handler</code>. Instead they - * will have to use g_signal_override_class_handler(). + * Get the contents of a %G_TYPE_LONG #GValue. * - * Returns: the signal id + * Returns: long integer contents of @value */ /** - * g_boxed_copy: - * @boxed_type: The type of @src_boxed. - * @src_boxed: The boxed structure to be copied. + * g_value_get_object: + * @value: a valid #GValue of %G_TYPE_OBJECT derived type * - * Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. + * Get the contents of a %G_TYPE_OBJECT derived #GValue. * - * Returns: The newly created copy of the boxed structure. + * Returns: (type GObject.Object) (transfer none): object contents of @value */ /** - * GBookmarkFileError: - * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed - * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found - * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not register a bookmark - * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found - * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed - * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding - * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing - * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found + * g_value_get_param: + * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM * - * Error codes returned by bookmark file parsing. + * Get the contents of a %G_TYPE_PARAM #GValue. + * + * Returns: (transfer none): #GParamSpec content of @value */ /** - * GTypePluginUnuse: - * @plugin: the #GTypePlugin whose use count should be decreased + * g_value_get_pointer: + * @value: a valid #GValue of %G_TYPE_POINTER * - * The type of the @unuse_plugin function of #GTypePluginClass. + * Get the contents of a pointer #GValue. + * + * Returns: (transfer none): pointer contents of @value */ /** - * G_DEFINE_INTERFACE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. + * g_value_get_string: + * @value: a valid #GValue of type %G_TYPE_STRING * - * A convenience macro for #GTypeInterface definitions, which declares - * a default vtable initialization function and defines a *_get_type() - * function. - * The macro expects the interface initialization function to have the - * name <literal>t_n ## _default_init</literal>, and the interface - * structure to have the name <literal>TN ## Interface</literal>. + * Get the contents of a %G_TYPE_STRING #GValue. * - * Since: 2.24 + * Returns: string content of @value */ /** - * GCallback: + * g_value_get_uchar: + * @value: a valid #GValue of type %G_TYPE_UCHAR * - * The type used for callback functions in structure definitions and function - * signatures. This doesn't mean that all callback functions must take no - * parameters and return void. The required signature of a callback function - * is determined by the context in which is used (e.g. the signal to which it - * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. + * Get the contents of a %G_TYPE_UCHAR #GValue. + * + * Returns: unsigned character contents of @value */ /** - * G_VARIANT_TYPE_STRING_ARRAY: + * g_value_get_uint: + * @value: a valid #GValue of type %G_TYPE_UINT * - * The type of an array of strings. + * Get the contents of a %G_TYPE_UINT #GValue. + * + * Returns: unsigned integer contents of @value */ /** - * g_value_set_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: caller-owned string to be duplicated for the #GValue + * g_value_get_uint64: + * @value: a valid #GValue of type %G_TYPE_UINT64 * - * Set the contents of a %G_TYPE_STRING #GValue to @v_string. + * Get the contents of a %G_TYPE_UINT64 #GValue. + * + * Returns: unsigned 64bit integer contents of @value */ /** - * G_SIGNAL_MATCH_MASK: + * g_value_get_ulong: + * @value: a valid #GValue of type %G_TYPE_ULONG * - * A mask for all #GSignalMatchType bits. + * Get the contents of a %G_TYPE_ULONG #GValue. + * + * Returns: unsigned long integer contents of @value */ /** - * g_signal_connect: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. + * g_value_get_variant: + * @value: a valid #GValue of type %G_TYPE_VARIANT * - * Connects a #GCallback function to a signal for a particular object. - * The handler will be called before the default handler of the signal. + * Get the contents of a variant #GValue. * - * Returns: the handler id + * Returns: variant contents of @value + * Since: 2.26 */ /** - * G_TYPE_PARAM_INT64: + * g_value_init: + * @value: A zero-filled (uninitialized) #GValue structure. + * @g_type: Type the #GValue should hold values of. * - * The #GType of #GParamSpecInt64. + * Initializes @value with the default value of @type. + * + * Returns: (transfer none): the #GValue structure that has been passed in */ /** - * g_param_spec_get_name: - * @pspec: a valid #GParamSpec + * g_value_peek_pointer: + * @value: An initialized #GValue structure. * - * Get the name of a #GParamSpec. + * function asserts that g_value_fits_pointer() returned %TRUE for the + * passed in value. This is an internal function introduced mainly + * for C marshallers. * - * Returns: the name of @pspec. + * Returns: (transfer none): the value contents as pointer. This */ /** - * g_param_spec_double: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE - * property. - * See g_param_spec_internal() for details on property names. + * g_value_register_transform_func: (skip) + * @src_type: Source type. + * @dest_type: Target type. + * @transform_func: a function which transforms values of type @src_type into value of type @dest_type * - * Returns: a newly created parameter specification + * Registers a value transformation function for use in g_value_transform(). + * A previously registered transformation function for @src_type and @dest_type + * will be replaced. */ /** - * g_value_set_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * @variant: a #GVariant, or %NULL + * g_value_reset: + * @value: An initialized #GValue structure. * - * Set the contents of a variant #GValue to @variant. - * If the variant is floating, it is consumed. + * Clears the current value in @value and resets it to the default value + * (as if the value had just been initialized). * - * Since: 2.26 + * Returns: the #GValue structure that has been passed in */ /** - * G_VALUE_HOLDS_UINT: - * @value: a valid #GValue structure + * g_value_set_boolean: + * @value: a valid #GValue of type %G_TYPE_BOOLEAN + * @v_boolean: boolean value to be set * - * Checks whether the given #GValue can hold values of type %G_TYPE_UINT. + * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. + */ + + +/** + * g_value_set_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: boxed value to be set * - * Returns: %TRUE on success. + * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. */ /** - * G_IS_PARAM_SPEC_INT64: - * @pspec: a valid #GParamSpec instance + * g_value_set_boxed_take_ownership: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: duplicated unowned boxed value to be set * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. + * This is an internal function introduced mainly for C marshallers. * - * Returns: %TRUE on success. + * Deprecated: 2.4: Use g_value_take_boxed() instead. */ /** - * GParamSpecUInt64: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_value_set_char: + * @value: a valid #GValue of type %G_TYPE_CHAR + * @v_char: character value to be set * - * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. + * Set the contents of a %G_TYPE_CHAR #GValue to @v_char. */ /** - * g_try_new: - * @struct_type: the type of the elements to allocate - * @n_structs: the number of elements to allocate - * - * Attempts to allocate @n_structs elements of type @struct_type, and returns - * %NULL on failure. Contrast with g_new(), which aborts the program on failure. - * The returned pointer is cast to a pointer to the given type. - * The function returns %NULL when @n_structs is 0 of if an overflow occurs. + * g_value_set_double: + * @value: a valid #GValue of type %G_TYPE_DOUBLE + * @v_double: double value to be set * - * Since: 2.8 - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type + * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. */ /** - * g_closure_add_finalize_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data to pass to @notify_func - * @notify_func: the callback function to register + * g_value_set_enum: + * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM + * @v_enum: enum value to be set * - * Registers a finalization notifier which will be called when the - * reference count of @closure goes down to 0. Multiple finalization - * notifiers on a single closure are invoked in unspecified order. If - * a single call to g_closure_unref() results in the closure being - * both invalidated and finalized, then the invalidate notifiers will - * be run before the finalize notifiers. + * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. */ /** - * g_param_spec_object: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @object_type: %G_TYPE_OBJECT derived type of this property - * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT - * derived property. - * See g_param_spec_internal() for details on property names. + * g_value_set_flags: + * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS + * @v_flags: flags value to be set * - * Returns: a newly created parameter specification + * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. */ /** - * g_closure_remove_finalize_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_finalize_notifier() when registering @notify_func - * @notify_func: the callback function to remove + * g_value_set_float: + * @value: a valid #GValue of type %G_TYPE_FLOAT + * @v_float: float value to be set * - * Removes a finalization notifier. - * Notice that notifiers are automatically removed after they are run. + * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. */ /** - * g_signal_remove_emission_hook: - * @signal_id: the id of the signal - * @hook_id: the id of the emission hook, as returned by g_signal_add_emission_hook() + * g_value_set_gtype: + * @value: a valid #GValue of type %G_TYPE_GTYPE + * @v_gtype: #GType to be set * - * Deletes an emission hook. + * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. + * + * Since: 2.12 */ /** - * GParamSpecDouble: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90. + * g_value_set_instance: + * @value: An initialized #GValue structure. + * @instance: the instance * - * A #GParamSpec derived structure that contains the meta data for double properties. + * Sets @value from an instantiatable type via the + * value_table's collect_value() function. */ /** - * G_TYPE_IS_DERIVED: - * @type: A #GType value. + * g_value_set_int: + * @value: a valid #GValue of type %G_TYPE_INT + * @v_int: integer value to be set * - * Checks if @type is derived (or in object-oriented terminology: - * inherited) from another type (this holds true for all non-fundamental - * types). + * Set the contents of a %G_TYPE_INT #GValue to @v_int. + */ + + +/** + * g_value_set_int64: + * @value: a valid #GValue of type %G_TYPE_INT64 + * @v_int64: 64bit integer value to be set * - * Returns: %TRUE on success. + * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. */ /** - * GObject::notify: - * @gobject: the object which received the signal. - * @pspec: the #GParamSpec of the property which changed. + * g_value_set_long: + * @value: a valid #GValue of type %G_TYPE_LONG + * @v_long: long integer value to be set * - * The notify signal is emitted on an object when one of its - * properties has been changed. Note that getting this signal - * doesn't guarantee that the value of the property has actually - * changed, it may also be emitted when the setter for the property - * is called to reinstate the previous value. - * This signal is typically used to obtain change notification for a - * single property, by specifying the property name as a detail in the - * g_signal_connect() call, like this: - * |[ - * g_signal_connect (text_view->buffer, "notify::paste-target-list", - * G_CALLBACK (gtk_text_view_target_list_notify), - * text_view) - * ]| - * It is important to note that you must use - * <link linkend="canonical-parameter-name">canonical</link> parameter names as - * detail strings for the notify signal. + * Set the contents of a %G_TYPE_LONG #GValue to @v_long. */ /** - * G_PARAM_USER_SHIFT: + * g_value_set_object: + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * @v_object: (type GObject.Object): object value to be set * - * Minimum shift count to be used for user defined flags, to be stored in - * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT. + * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. + * g_value_set_object() increases the reference count of @v_object + * (the #GValue holds a reference to @v_object). If you do not wish + * to increase the reference count of the object (i.e. you wish to + * pass your current reference to the #GValue because you no longer + * need it), use g_value_take_object() instead. + * It is important that your #GValue holds a reference to @v_object (either its + * own, or one it has taken) to ensure that the object won't be destroyed while + * the #GValue still exists). */ /** - * GBinding:source-property: + * g_value_set_object_take_ownership: (skip) + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * @v_object: object value to be set * - * The name of the property of #GBinding:source that should be used - * as the source of the binding + * This is an internal function introduced mainly for C marshallers. * - * Since: 2.26 + * Deprecated: 2.4: Use g_value_take_object() instead. */ /** - * g_param_spec_string: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecString instance. - * See g_param_spec_internal() for details on property names. + * g_value_set_param: + * @value: a valid #GValue of type %G_TYPE_PARAM + * @param: the #GParamSpec to be set * - * Returns: a newly created parameter specification + * Set the contents of a %G_TYPE_PARAM #GValue to @param. */ /** - * GParamSpecOverride: + * g_value_set_param_take_ownership: (skip) + * @value: a valid #GValue of type %G_TYPE_PARAM + * @param: the #GParamSpec to be set * - * This is a type of #GParamSpec type that simply redirects operations to - * another paramspec. All operations other than getting or - * setting the value are redirected, including accessing the nick and - * blurb, validating a value, and so forth. See - * g_param_spec_get_redirect_target() for retrieving the overidden - * property. #GParamSpecOverride is used in implementing - * g_object_class_override_property(), and will not be directly useful - * unless you are implementing a new base type similar to GObject. + * This is an internal function introduced mainly for C marshallers. * - * Since: 2.4 + * Deprecated: 2.4: Use g_value_take_param() instead. */ /** - * G_TYPE_PARAM_DOUBLE: + * g_value_set_pointer: + * @value: a valid #GValue of %G_TYPE_POINTER + * @v_pointer: pointer value to be set * - * The #GType of #GParamSpecDouble. + * Set the contents of a pointer #GValue to @v_pointer. */ /** - * g_value_get_flags: - * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS + * g_value_set_static_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: static boxed value to be set * - * Get the contents of a %G_TYPE_FLAGS #GValue. + * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + * The boxed value is assumed to be static, and is thus not duplicated + * when setting the #GValue. + */ + + +/** + * g_value_set_static_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: static string to be set * - * Returns: flags contents of @value + * Set the contents of a %G_TYPE_STRING #GValue to @v_string. + * The string is assumed to be static, and is thus not duplicated + * when setting the #GValue. */ /** - * G_TYPE_IS_DERIVABLE: - * @type: A #GType value. + * g_value_set_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: caller-owned string to be duplicated for the #GValue * - * Checks if @type is a derivable type. A derivable type can - * be used as the base class of a flat (single-level) class hierarchy. + * Set the contents of a %G_TYPE_STRING #GValue to @v_string. + */ + + +/** + * g_value_set_string_take_ownership: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: duplicated unowned string to be set * - * Returns: %TRUE on success. + * This is an internal function introduced mainly for C marshallers. + * + * Deprecated: 2.4: Use g_value_take_string() instead. */ /** - * GSignalMatchType: - * @G_SIGNAL_MATCH_ID: The signal id must be equal. - * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal. - * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same. - * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same. - * @G_SIGNAL_MATCH_DATA: The closure data must be the same. - * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched. + * g_value_set_uchar: + * @value: a valid #GValue of type %G_TYPE_UCHAR + * @v_uchar: unsigned character value to be set * - * The match types specify what g_signal_handlers_block_matched(), - * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() - * match signals by. + * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. */ /** - * G_PARAM_SPEC_INT: - * @pspec: a valid #GParamSpec instance + * g_value_set_uint: + * @value: a valid #GValue of type %G_TYPE_UINT + * @v_uint: unsigned integer value to be set * - * Cast a #GParamSpec instance into a #GParamSpecInt. + * Set the contents of a %G_TYPE_UINT #GValue to @v_uint. */ /** - * GCClosure: - * @closure: the #GClosure - * @callback: the callback function + * g_value_set_uint64: + * @value: a valid #GValue of type %G_TYPE_UINT64 + * @v_uint64: unsigned 64bit integer value to be set * - * A #GCClosure is a specialization of #GClosure for C function callbacks. + * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. */ /** - * g_object_disconnect: (skip) - * @object: a #GObject - * @signal_spec: the spec for the first signal - * @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL + * g_value_set_ulong: + * @value: a valid #GValue of type %G_TYPE_ULONG + * @v_ulong: unsigned long integer value to be set * - * A convenience function to disconnect multiple signals at once. - * The signal specs expected by this function have the form - * "any_signal", which means to disconnect any signal with matching - * callback and data, or "any_signal::signal_name", which only - * disconnects the signal named "signal_name". + * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. */ /** - * g_closure_set_marshal: (skip) - * @closure: a #GClosure - * @marshal: a #GClosureMarshal function + * g_value_set_variant: + * @value: a valid #GValue of type %G_TYPE_VARIANT + * @variant: a #GVariant, or %NULL * - * Sets the marshaller of @closure. The <literal>marshal_data</literal> - * of @marshal provides a way for a meta marshaller to provide additional - * information to the marshaller. (See g_closure_set_meta_marshal().) For - * GObject's C predefined marshallers (the g_cclosure_marshal_*() - * functions), what it provides is a callback function to use instead of + * Set the contents of a variant #GValue to @variant. + * If the variant is floating, it is consumed. + * + * Since: 2.26 */ /** - * GSourceCallbackFuncs: - * @ref: Called when a reference is added to the callback object - * @unref: Called when a reference to the callback object is dropped - * @get: Called to extract the callback function and data from the callback object. + * g_value_take_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: duplicated unowned boxed value to be set * - * The <structname>GSourceCallbackFuncs</structname> struct contains - * functions for managing callback objects. + * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed + * and takes over the ownership of the callers reference to @v_boxed; + * the caller doesn't have to unref it any more. + * + * Since: 2.4 */ /** - * G_VARIANT_TYPE_HANDLE: + * g_value_take_object: (skip) + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * @v_object: object value to be set * - * The type of a 32bit signed integer value, that by convention, is used - * as an index into an array of file descriptors that are sent alongside - * a DBus message. - * If you are not interacting with DBus, then there is no reason to make - * use of this type. + * Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object + * and takes over the ownership of the callers reference to @v_object; + * the caller doesn't have to unref it any more (i.e. the reference + * count of the object is not increased). + * If you want the #GValue to hold its own reference to @v_object, use + * g_value_set_object() instead. + * + * Since: 2.4 */ /** - * GParamSpecParam: - * @parent_instance: private #GParamSpec portion + * g_value_take_param: (skip) + * @value: a valid #GValue of type %G_TYPE_PARAM + * @param: the #GParamSpec to be set * - * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM - * properties. + * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes + * over the ownership of the callers reference to @param; the caller + * doesn't have to unref it any more. + * + * Since: 2.4 */ /** - * g_object_class_override_property: - * @oclass: a #GObjectClass - * @property_id: the new property ID - * @name: the name of a property registered in a parent class or in an interface of this class. + * g_value_take_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: string to take ownership of * - * Registers @property_id as referring to a property with the - * name @name in a parent class or in an interface implemented - * by @oclass. This allows this class to <firstterm>override</firstterm> - * a property implementation in a parent class or to provide - * the implementation of a property from an interface. - * <note> - * Internally, overriding is implemented by creating a property of type - * #GParamSpecOverride; generally operations that query the properties of - * the object class, such as g_object_class_find_property() or - * g_object_class_list_properties() will return the overridden - * property. However, in one case, the @construct_properties argument of - * the @constructor virtual function, the #GParamSpecOverride is passed - * instead, so that the @param_id field of the #GParamSpec will be - * correct. For virtually all uses, this makes no difference. If you - * need to get the overridden property, you can call - * g_param_spec_get_redirect_target(). - * </note> + * Sets the contents of a %G_TYPE_STRING #GValue to @v_string. * * Since: 2.4 */ /** - * G_TYPE_RESERVED_BSE_FIRST: + * g_value_take_variant: + * @value: a valid #GValue of type %G_TYPE_VARIANT + * @variant: a #GVariant, or %NULL * - * First fundamental type number to create a new fundamental type id with - * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. + * Set the contents of a variant #GValue to @variant, and takes over + * the ownership of the caller's reference to @variant; + * the caller doesn't have to unref it any more (i.e. the reference + * count of the variant is not increased). + * It is a programmer error to pass a floating variant to this function. + * In particular this means that callbacks in closures, and signal handlers + * for signals of return type %G_TYPE_VARIANT, must never return floating + * variants. + * If you want the #GValue to hold its own reference to @variant, use + * g_value_set_variant() instead. + * This is an internal function introduced mainly for C marshallers. + * + * Since: 2.26 */ /** - * g_signal_handlers_block_matched: - * @instance: The instance to block handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. - * @signal_id: Signal the handlers have to be connected to. - * @detail: Signal detail the handlers have to be connected to. - * @closure: The closure the handlers will invoke. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * g_value_transform: + * @src_value: Source value. + * @dest_value: Target value. * - * Blocks all handlers on an instance that match a certain selection criteria. - * The criteria mask is passed as an OR-ed combination of #GSignalMatchType - * flags, and the criteria values are passed as arguments. - * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC - * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. - * If no handlers were found, 0 is returned, the number of blocked handlers - * otherwise. + * Tries to cast the contents of @src_value into a type appropriate + * to store in @dest_value, e.g. to transform a %G_TYPE_INT value + * into a %G_TYPE_FLOAT value. Performing transformations between + * value types might incur precision lossage. Especially + * transformations into strings might reveal seemingly arbitrary + * results and shouldn't be relied upon for production code (such + * as rcfile value or object property serialization). + * Upon failing transformations, @dest_value is left untouched. * - * Returns: The number of handlers that matched. + * Returns: Whether a transformation rule was found and could be applied. */ /** - * g_node_first_child: - * @node: a #GNode + * g_value_type_compatible: + * @src_type: source type to be copied. + * @dest_type: destination type for copying. * - * Gets the first child of a #GNode. - * or has no children + * Returns whether a #GValue of type @src_type can be copied into + * a #GValue of type @dest_type. * - * Returns: the first child of @node, or %NULL if @node is %NULL + * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. */ /** - * GBaseFinalizeFunc: - * @g_class: The #GTypeClass structure to finalize. + * g_value_type_transformable: + * @src_type: Source type. + * @dest_type: Target type. * - * A callback function used by the type system to finalize those portions - * of a derived types class structure that were setup from the corresponding - * GBaseInitFunc() function. Class finalization basically works the inverse - * way in which class intialization is performed. - * See GClassInitFunc() for a discussion of the class intialization process. + * Check whether g_value_transform() is able to transform values + * of type @src_type into values of type @dest_type. + * + * Returns: %TRUE if the transformation is possible, %FALSE otherwise. */ /** - * g_signal_handlers_block_by_func: - * @instance: The instance to block handlers from. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * g_value_unset: + * @value: An initialized #GValue structure. * - * Blocks all handlers on an instance that match @func and @data. + * Clears the current value in @value and "unsets" the type, + * this releases all resources associated with this GValue. + * An unset value is the same as an uninitialized (zero-filled) + * #GValue structure. + */ + + +/** + * g_variant_get_gtype: * - * Returns: The number of handlers that matched. + * + * + * Since: 2.24 + * Deprecated: 2.26 + */ + + +/** + * gchararray: + * + * A C representable type name for #G_TYPE_STRING. */ |