1 /************************************************************/
2 /* THIS FILE IS GENERATED DO NOT EDIT */
3 /************************************************************/
8 * If @action is currently enabled.
10 * If the action is disabled then calls to g_action_activate() and
11 * g_action_change_state() have no effect.
20 * The name of the action. This is mostly meaningful for identifying
21 * the action once it has been added to a #GActionGroup.
28 * GAction:parameter-type:
30 * The type of the parameter that must be given when activating the
40 * The state of the action, or %NULL if the action is stateless.
49 * The #GVariantType of the state that the action has, or %NULL if the
50 * action is stateless.
58 * @name: the name of the action
59 * @activate: the callback to connect to the "activate" signal of the action
60 * @parameter_type: the type of the parameter that must be passed to the activate function for this action, given as a single GVariant type string (or %NULL for no parameter)
61 * @state: the initial state for this action, given in GVariant text format. The state is parsed with no extra type information, so type tags must be added to the string if they are necessary.
62 * @change_state: the callback to connect to the "change-state" signal of the action
64 * This struct defines a single action. It is for use with
65 * g_action_map_add_action_entries().
67 * The order of the items in the structure are intended to reflect
68 * frequency of use. It is permissible to use an incomplete initialiser
69 * in order to leave some of the later values as %NULL. All values
70 * after @name are optional. Additional optional fields may be added in
73 * See g_action_map_add_action_entries() for an example.
78 * GActionGroup::action-added:
79 * @action_group: the #GActionGroup that changed
80 * @action_name: the name of the action in @action_group
82 * Signals that a new action was just added to the group.
83 * This signal is emitted after the action has been added
91 * GActionGroup::action-enabled-changed:
92 * @action_group: the #GActionGroup that changed
93 * @action_name: the name of the action in @action_group
94 * @enabled: whether the action is enabled or not
96 * Signals that the enabled status of the named action has changed.
103 * GActionGroup::action-removed:
104 * @action_group: the #GActionGroup that changed
105 * @action_name: the name of the action in @action_group
107 * Signals that an action is just about to be removed from the group.
108 * This signal is emitted before the action is removed, so the action
109 * is still visible and can be queried from the signal handler.
116 * GActionGroup::action-state-changed:
117 * @action_group: the #GActionGroup that changed
118 * @action_name: the name of the action in @action_group
119 * @value: the new value of the state
121 * Signals that the state of the named action has changed.
128 * GActionGroupInterface:
129 * @has_action: the virtual function pointer for g_action_group_has_action()
130 * @list_actions: the virtual function pointer for g_action_group_list_actions()
131 * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type()
132 * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type()
133 * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
134 * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
135 * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
136 * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
137 * @query_action: the virtual function pointer for g_action_group_query_action()
138 * @activate_action: the virtual function pointer for g_action_group_activate_action()
139 * @action_added: the class closure for the #GActionGroup::action-added signal
140 * @action_removed: the class closure for the #GActionGroup::action-removed signal
141 * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
142 * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
144 * The virtual function table for #GActionGroup.
152 * @get_name: the virtual function pointer for g_action_get_name()
153 * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type()
154 * @get_state_type: the virtual function pointer for g_action_get_state_type()
155 * @get_state_hint: the virtual function pointer for g_action_get_state_hint()
156 * @get_enabled: the virtual function pointer for g_action_get_enabled()
157 * @get_state: the virtual function pointer for g_action_get_state()
158 * @change_state: the virtual function pointer for g_action_change_state()
159 * @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.
161 * The virtual function table for #GAction.
168 * GActionMapInterface:
169 * @lookup_action: the virtual function pointer for g_action_map_lookup_action()
170 * @add_action: the virtual function pointer for g_action_map_add_action()
171 * @remove_action: the virtual function pointer for g_action_map_remove_action()
173 * The virtual function table for #GActionMap.
182 * Information about an installed application and methods to launch
183 * it (with file arguments).
188 * GAppInfoCreateFlags:
189 * @G_APP_INFO_CREATE_NONE: No flags.
190 * @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens in a terminal window.
191 * @G_APP_INFO_CREATE_SUPPORTS_URIS: Application supports URI arguments.
192 * @G_APP_INFO_CREATE_SUPPORTS_STARTUP_NOTIFICATION: Application supports startup notification. Since 2.26
194 * Flags used when creating a #GAppInfo.
200 * @g_iface: The parent interface.
201 * @dup: Copies a #GAppInfo.
202 * @equal: Checks two #GAppInfo<!-- -->s for equality.
203 * @get_id: Gets a string identifier for a #GAppInfo.
204 * @get_name: Gets the name of the application for a #GAppInfo.
205 * @get_description: Gets a short description for the application described by the #GAppInfo.
206 * @get_executable: Gets the executable name for the #GAppInfo.
207 * @get_icon: Gets the #GIcon for the #GAppInfo.
208 * @launch: Launches an application specified by the #GAppInfo.
209 * @supports_uris: Indicates whether the application specified supports launching URIs.
210 * @supports_files: Indicates whether the application specified accepts filename arguments.
211 * @launch_uris: Launches an application with a list of URIs.
212 * @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>.
213 * @set_as_default_for_type: Sets an application as default for a given content type.
214 * @set_as_default_for_extension: Sets an application as default for a given file extension.
215 * @add_supports_type: Adds to the #GAppInfo information about supported file types.
216 * @can_remove_supports_type: Checks for support for removing supported file types from a #GAppInfo.
217 * @remove_supports_type: Removes a supported application type from a #GAppInfo.
218 * @can_delete: Checks if a #GAppInfo can be deleted. Since 2.20
219 * @do_delete: Deletes a #GAppInfo. Since 2.20
220 * @get_commandline: Gets the commandline for the #GAppInfo. Since 2.20
221 * @get_display_name: Gets the display name for the #GAppInfo. Since 2.24
222 * @set_as_last_used_for_type: Sets the application as the last used. See g_app_info_set_as_last_used_for_type().
224 * Application Information interface, for operating system portability.
231 * Integrating the launch with the launching application. This is used to
232 * handle for instance startup notification and launching the new application
233 * on the same screen as the launching window.
247 * GApplication::activate:
248 * @application: the application
250 * The ::activate signal is emitted on the primary instance when an
251 * activation occurs. See g_application_activate().
256 * GApplication::command-line:
257 * @application: the application
258 * @command_line: a #GApplicationCommandLine representing the passed commandline
260 * The ::command-line signal is emitted on the primary instance when
261 * a commandline is not handled locally. See g_application_run() and
262 * the #GApplicationCommandLine documentation for more information.
264 * process. See g_application_command_line_set_exit_status().
266 * Returns: An integer that is set as the exit status for the calling
271 * GApplication::open:
272 * @application: the application
273 * @files: (array length=n_files) (element-type GFile): an array of #GFiles
274 * @n_files: the length of @files
275 * @hint: a hint provided by the calling instance
277 * The ::open signal is emitted on the primary instance when there are
278 * files to open. See g_application_open() for more information.
283 * GApplication::shutdown:
284 * @application: the application
286 * The ::shutdown signal is emitted only on the registered primary instance
287 * immediately after the main loop terminates.
292 * GApplication::startup:
293 * @application: the application
295 * The ::startup signal is emitted on the primary instance immediately
296 * after registration. See g_application_register().
302 * @startup: invoked on the primary instance immediately after registration
303 * @shutdown: invoked only on the registered primary instance immediately after the main loop terminates
304 * @activate: invoked on the primary instance when an activation occurs
305 * @open: invoked on the primary instance when there are files to open
306 * @command_line: invoked on the primary instance when a command-line is not handled locally
307 * @local_command_line: invoked (locally) when the process has been invoked via commandline execution (as opposed to, say, D-Bus activation - which is not currently supported by GApplication). The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information.
308 * @before_emit: invoked on the primary instance before 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance
309 * @after_emit: invoked on the primary instance after 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance
310 * @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions
311 * @quit_mainloop: Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32
312 * @run_mainloop: Used to be invoked on the primary instance from g_application_run() if the use-count is non-zero. Since 2.32, GApplication is iterating the main context directly and is not using @run_mainloop anymore
314 * Virtual function table for #GApplication.
321 * GApplicationCommandLineClass:
323 * The <structname>GApplicationCommandLineClass</structname> structure
324 * contains private data only
332 * @G_APPLICATION_FLAGS_NONE: Default
333 * @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.
334 * @G_APPLICATION_IS_LAUNCHER: Don't try to become the primary instance.
335 * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in the primary instance). Note that this flag only affects the default implementation of local_command_line(), and has no effect if %G_APPLICATION_HANDLES_COMMAND_LINE is given. See g_application_run() for details.
336 * @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command line arguments (in the primary instance). Note that this flag only affect the default implementation of local_command_line(). See g_application_run() for details.
337 * @G_APPLICATION_SEND_ENVIRONMENT: Send the environment of the launching process to the primary instance. Set this flag if your application is expected to behave differently depending on certain environment variables. For instance, an editor might be expected to use the <envar>GIT_COMMITTER_NAME</envar> environment variable when editing a git commit message. The environment is available to the #GApplication::command-line signal handler, via g_application_command_line_getenv().
338 * @G_APPLICATION_NON_UNIQUE: Make no attempts to do any of the typical single-instance application negotiation. The application neither attempts to become the owner of the application ID nor does it check if an existing owner already exists. Everything occurs in the local process. Since: 2.30.
340 * Flags used to define the behaviour of a #GApplication.
348 * @G_ASK_PASSWORD_NEED_PASSWORD: operation requires a password.
349 * @G_ASK_PASSWORD_NEED_USERNAME: operation requires a username.
350 * @G_ASK_PASSWORD_NEED_DOMAIN: operation requires a domain.
351 * @G_ASK_PASSWORD_SAVING_SUPPORTED: operation supports saving settings.
352 * @G_ASK_PASSWORD_ANONYMOUS_SUPPORTED: operation supports anonymous users.
354 * #GAskPasswordFlags are used to request specific information from the
355 * user, or to notify the user of their choices in an authentication
363 * Interface for asynchronously initializable objects.
370 * GAsyncInitableIface:
371 * @g_iface: The parent interface.
372 * @init_async: Starts initialization of the object.
373 * @init_finish: Finishes initialization of the object.
375 * Provides an interface for asynchronous initializing object such that
376 * initialization may fail.
383 * GAsyncReadyCallback:
384 * @source_object: the object the asynchronous operation was started with.
385 * @res: a #GAsyncResult.
386 * @user_data: user data passed to the callback.
388 * Type definition for a function that will be called back when an asynchronous
389 * operation within GIO has been completed.
396 * Holds results information for an asynchronous operation,
397 * usually passed directly to a asynchronous _finish() operation.
403 * @g_iface: The parent interface.
404 * @get_user_data: Gets the user data passed to the callback.
405 * @get_source_object: Gets the source object that issued the asynchronous operation.
407 * Interface definition for #GAsyncResult.
413 * @g_class: The #GTypeClass structure to finalize.
415 * A callback function used by the type system to finalize those portions
416 * of a derived types class structure that were setup from the corresponding
417 * GBaseInitFunc() function. Class finalization basically works the inverse
418 * way in which class intialization is performed.
419 * See GClassInitFunc() for a discussion of the class intialization process.
425 * @g_class: The #GTypeClass structure to initialize.
427 * A callback function used by the type system to do base initialization
428 * of the class structures of derived types. It is called as part of the
429 * initialization process of all derived classes and should reallocate
430 * or reset all dynamic class members copied over from the parent class.
431 * For example, class members (such as strings) that are not sufficiently
432 * handled by a plain memory copy of the parent class into the derived class
433 * have to be altered. See GClassInitFunc() for a discussion of the class
434 * intialization process.
441 * <structname>GBinding</structname> is an opaque structure whose members
442 * cannot be accessed directly.
450 * @G_BINDING_DEFAULT: The default binding; if the source property changes, the target property is updated with its value.
451 * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated.
452 * @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.
453 * @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().
455 * Flags to be passed to g_object_bind_property() or
456 * g_object_bind_property_full().
458 * This enumeration can be extended at later date.
465 * GBindingTransformFunc:
466 * @binding: a #GBinding
467 * @source_value: the value of the source property
468 * @target_value: the value of the target property
469 * @user_data: data passed to the transform function
471 * A function to be called to transform the source property of @source
472 * from @source_value into the target property of @target
473 * using @target_value.
477 * Returns: %TRUE if the transformation was successful, and %FALSE
485 * The <structname>GBookmarkFile</structname> struct contains only
486 * private data and should not be directly accessed.
491 * GBookmarkFileError:
492 * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed
493 * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found
494 * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not register a bookmark
495 * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found
496 * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed
497 * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding
498 * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing
499 * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found
501 * Error codes returned by bookmark file parsing.
507 * @boxed: The boxed structure to be copied.
509 * This function is provided by the user and should produce a copy
510 * of the passed in boxed structure.
512 * Returns: The newly created copy of the boxed structure.
518 * @boxed: The boxed structure to be freed.
520 * This function is provided by the user and should free the boxed
526 * GBufferedInputStream:
528 * Implements #GFilterInputStream with a sized input buffer.
533 * GBufferedOutputStream:
535 * An implementation of #GFilterOutputStream with a sized buffer.
540 * GBusAcquiredCallback:
541 * @connection: The #GDBusConnection to a message bus.
542 * @name: The name that is requested to be owned.
543 * @user_data: User data passed to g_bus_own_name().
545 * Invoked when a connection to a message bus has been obtained.
552 * GBusNameAcquiredCallback:
553 * @connection: The #GDBusConnection on which to acquired the name.
554 * @name: The name being owned.
555 * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
557 * Invoked when the name is acquired.
564 * GBusNameAppearedCallback:
565 * @connection: The #GDBusConnection the name is being watched on.
566 * @name: The name being watched.
567 * @name_owner: Unique name of the owner of the name being watched.
568 * @user_data: User data passed to g_bus_watch_name().
570 * Invoked when the name being watched is known to have to have a owner.
577 * GBusNameLostCallback:
578 * @connection: The #GDBusConnection on which to acquire the name or %NULL if the connection was disconnected.
579 * @name: The name being owned.
580 * @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
582 * Invoked when the name is lost or @connection has been closed.
589 * GBusNameOwnerFlags:
590 * @G_BUS_NAME_OWNER_FLAGS_NONE: No flags set.
591 * @G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT: Allow another message bus connection to claim the the name.
592 * @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.
594 * Flags used in g_bus_own_name().
601 * GBusNameVanishedCallback:
602 * @connection: The #GDBusConnection the name is being watched on.
603 * @name: The name being watched.
604 * @user_data: User data passed to g_bus_watch_name().
606 * Invoked when the name being watched is known not to have to have a owner.
613 * GBusNameWatcherFlags:
614 * @G_BUS_NAME_WATCHER_FLAGS_NONE: No flags set.
615 * @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.
617 * Flags used in g_bus_watch_name().
625 * @G_BUS_TYPE_STARTER: An alias for the message bus that activated the process, if any.
626 * @G_BUS_TYPE_NONE: Not a message bus.
627 * @G_BUS_TYPE_SYSTEM: The system-wide message bus.
628 * @G_BUS_TYPE_SESSION: The login session message bus.
630 * An enumeration for well-known message buses.
638 * @closure: the #GClosure
639 * @callback: the callback function
641 * A #GCClosure is a specialization of #GClosure for C function callbacks.
648 * The type used for callback functions in structure definitions and function
649 * signatures. This doesn't mean that all callback functions must take no
650 * parameters and return void. The required signature of a callback function
651 * is determined by the context in which is used (e.g. the signal to which it
652 * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback.
659 * Allows actions to be cancelled.
664 * GCancellable::cancelled:
665 * @cancellable: a #GCancellable.
667 * Emitted when the operation has been cancelled.
669 * Can be used by implementations of cancellable operations. If the
670 * operation is cancelled from another thread, the signal will be
671 * emitted in the thread that cancelled the operation, not the
672 * thread that is running the operation.
674 * Note that disconnecting from this signal (or any signal) in a
675 * multi-threaded program is prone to race conditions. For instance
676 * it is possible that a signal handler may be invoked even
677 * <emphasis>after</emphasis> a call to
678 * g_signal_handler_disconnect() for that handler has already
681 * There is also a problem when cancellation happen
682 * right before connecting to the signal. If this happens the
683 * signal will unexpectedly not be emitted, and checking before
684 * connecting to the signal leaves a race condition where this is
687 * In order to make it safe and easy to connect handlers there
688 * are two helper functions: g_cancellable_connect() and
689 * g_cancellable_disconnect() which protect against problems
692 * An example of how to us this:
694 * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
695 * if (g_cancellable_set_error_if_cancelled (cancellable))
698 * /<!-- -->* Set up all the data needed to be able to
699 * * handle cancellation of the operation *<!-- -->/
700 * my_data = my_data_new (...);
704 * id = g_cancellable_connect (cancellable,
705 * G_CALLBACK (cancelled_handler)
708 * /<!-- -->* cancellable operation here... *<!-- -->/
710 * g_cancellable_disconnect (cancellable, id);
712 * /<!-- -->* cancelled_handler is never called after this, it
713 * * is now safe to free the data *<!-- -->/
714 * my_data_free (my_data);
717 * Note that the cancelled signal is emitted in the thread that
718 * the user cancelled from, which may be the main thread. So, the
719 * cancellable signal should not do something that can block.
724 * GCancellableSourceFunc:
725 * @cancellable: the #GCancellable
726 * @user_data: data passed in by the user.
728 * This is the function type of the callback used for the #GSource
729 * returned by g_cancellable_source_new().
731 * Returns: it should return %FALSE if the source should be removed.
739 * Conversions between character sets.
746 * An opaque structure representing a checksumming operation.
747 * To create a new GChecksum, use g_checksum_new(). To free
748 * a GChecksum, use g_checksum_free().
756 * @G_CHECKSUM_MD5: Use the MD5 hashing algorithm
757 * @G_CHECKSUM_SHA1: Use the SHA-1 hashing algorithm
758 * @G_CHECKSUM_SHA256: Use the SHA-256 hashing algorithm
760 * The hashing algorithm to be used by #GChecksum when performing the
761 * digest of some data.
763 * Note that the #GChecksumType enumeration may be extended at a later
764 * date to include new hashing algorithm types.
772 * @pid: the process id of the child process
773 * @status: Status information about the child process, see waitpid(2) for more information about this field
774 * @user_data: user data passed to g_child_watch_add()
776 * The type of functions to be called when a child exists.
781 * GClassFinalizeFunc:
782 * @g_class: The #GTypeClass structure to finalize.
783 * @class_data: The @class_data member supplied via the #GTypeInfo structure.
785 * A callback function used by the type system to finalize a class.
786 * This function is rarely needed, as dynamically allocated class resources
787 * should be handled by GBaseInitFunc() and GBaseFinalizeFunc().
788 * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo
789 * structure of a static type is invalid, because classes of static types
790 * will never be finalized (they are artificially kept alive when their
791 * reference count drops to zero).
797 * @g_class: The #GTypeClass structure to initialize.
798 * @class_data: The @class_data member supplied via the #GTypeInfo structure.
800 * A callback function used by the type system to initialize the class
801 * of a specific type. This function should initialize all static class
803 * The initialization process of a class involves:
806 * 1 - Copying common members from the parent class over to the
807 * derived class structure.
810 * 2 - Zero initialization of the remaining members not copied
811 * over from the parent class.
814 * 3 - Invocation of the GBaseInitFunc() initializers of all parent
815 * types and the class' type.
818 * 4 - Invocation of the class' GClassInitFunc() initializer.
821 * Since derived classes are partially initialized through a memory copy
822 * of the parent class, the general rule is that GBaseInitFunc() and
823 * GBaseFinalizeFunc() should take care of necessary reinitialization
824 * and release of those class members that were introduced by the type
825 * that specified these GBaseInitFunc()/GBaseFinalizeFunc().
826 * GClassInitFunc() should only care about initializing static
827 * class members, while dynamic class members (such as allocated strings
828 * or reference counted resources) are better handled by a GBaseInitFunc()
829 * for this type, so proper initialization of the dynamic class members
830 * is performed for class initialization of derived types as well.
831 * An example may help to correspond the intend of the different class
836 * GObjectClass parent_class;
837 * gint static_integer;
838 * gchar *dynamic_string;
841 * type_a_base_class_init (TypeAClass *class)
843 * class->dynamic_string = g_strdup ("some string");
846 * type_a_base_class_finalize (TypeAClass *class)
848 * g_free (class->dynamic_string);
851 * type_a_class_init (TypeAClass *class)
853 * class->static_integer = 42;
857 * TypeAClass parent_class;
858 * gfloat static_float;
859 * GString *dynamic_gstring;
862 * type_b_base_class_init (TypeBClass *class)
864 * class->dynamic_gstring = g_string_new ("some other string");
867 * type_b_base_class_finalize (TypeBClass *class)
869 * g_string_free (class->dynamic_gstring);
872 * type_b_class_init (TypeBClass *class)
874 * class->static_float = 3.14159265358979323846;
877 * Initialization of TypeBClass will first cause initialization of
878 * TypeAClass (derived classes reference their parent classes, see
879 * g_type_class_ref() on this).
880 * Initialization of TypeAClass roughly involves zero-initializing its fields,
881 * then calling its GBaseInitFunc() type_a_base_class_init() to allocate
882 * its dynamic members (dynamic_string), and finally calling its GClassInitFunc()
883 * type_a_class_init() to initialize its static members (static_integer).
884 * The first step in the initialization process of TypeBClass is then
885 * a plain memory copy of the contents of TypeAClass into TypeBClass and
886 * zero-initialization of the remaining fields in TypeBClass.
887 * The dynamic members of TypeAClass within TypeBClass now need
888 * reinitialization which is performed by calling type_a_base_class_init()
889 * with an argument of TypeBClass.
890 * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init()
891 * is called to allocate the dynamic members of TypeBClass (dynamic_gstring),
892 * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(),
893 * is called to complete the initialization process with the static members
895 * Corresponding finalization counter parts to the GBaseInitFunc() functions
896 * have to be provided to release allocated resources at class finalization
903 * @in_marshal: Indicates whether the closure is currently being invoked with g_closure_invoke()
904 * @is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate()
906 * A #GClosure represents a callback supplied by the programmer.
912 * @closure: the #GClosure to which the marshaller belongs
913 * @return_value: (allow-none): a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value.
914 * @n_param_values: the length of the @param_values array
915 * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure
916 * @invocation_hint: (allow-none): the invocation hint given as the last argument to g_closure_invoke()
917 * @marshal_data: (allow-none): additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal()
919 * The type used for marshaller functions.
925 * @data: data specified when registering the notification callback
926 * @closure: the #GClosure on which the notification is emitted
928 * The type used for the various notification callbacks which can be registered
935 * @G_CONNECT_AFTER: whether the handler should be called before or after the default handler of the signal.
936 * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when calling the handler.
938 * The connection flags are used to specify the behaviour of a signal's
945 * @G_CONVERT_ERROR_NO_CONVERSION: Conversion between the requested character sets is not supported.
946 * @G_CONVERT_ERROR_ILLEGAL_SEQUENCE: Invalid byte sequence in conversion input.
947 * @G_CONVERT_ERROR_FAILED: Conversion failed for some reason.
948 * @G_CONVERT_ERROR_PARTIAL_INPUT: Partial character sequence at end of input.
949 * @G_CONVERT_ERROR_BAD_URI: URI is invalid.
950 * @G_CONVERT_ERROR_NOT_ABSOLUTE_PATH: Pathname is not an absolute path.
952 * Error codes returned by character set conversion routines.
959 * Seek object for streaming operations.
967 * @G_CONVERTER_NO_FLAGS: No flags.
968 * @G_CONVERTER_INPUT_AT_END: At end of input data
969 * @G_CONVERTER_FLUSH: Flush data
971 * Flags used when calling a g_converter_convert().
979 * @g_iface: The parent interface.
980 * @convert: Converts data.
981 * @reset: Reverts the internal state of the converter to its initial state.
983 * Provides an interface for converting data from one type
984 * to another type. The conversion can be stateful
985 * and may fail at any place.
992 * GConverterInputStream:
994 * An implementation of #GFilterInputStream that allows data
1000 * GConverterOutputStream:
1002 * An implementation of #GFilterOutputStream that allows data
1009 * @G_CONVERTER_ERROR: There was an error during conversion.
1010 * @G_CONVERTER_CONVERTED: Some data was consumed or produced
1011 * @G_CONVERTER_FINISHED: The conversion is finished
1012 * @G_CONVERTER_FLUSHED: Flushing is finished
1014 * Results returned from g_converter_convert().
1022 * @src: A pointer to the data which should be copied
1023 * @data: Additional data
1025 * A function of this signature is used to copy the node data
1026 * when doing a deep-copy of a tree.
1028 * Returns: A pointer to the copy
1036 * The #GCredentials structure contains only private data and
1037 * should only be accessed using the provided API.
1044 * GCredentialsClass:
1046 * Class structure for #GCredentials.
1054 * @G_CREDENTIALS_TYPE_INVALID: Indicates an invalid native credential type.
1055 * @G_CREDENTIALS_TYPE_LINUX_UCRED: The native credentials type is a <type>struct ucred</type>.
1056 * @G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED: The native credentials type is a <type>struct cmsgcred</type>.
1057 * @G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED: The native credentials type is a <type>struct sockpeercred</type>. Added in 2.30.
1059 * Enumeration describing different kinds of native credential types.
1066 * GDBusAnnotationInfo:
1067 * @ref_count: The reference count or -1 if statically allocated.
1068 * @key: The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated".
1069 * @value: The value of the annotation.
1070 * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
1072 * Information about an annotation.
1080 * @ref_count: The reference count or -1 if statically allocated.
1081 * @name: Name of the argument, e.g. @unix_user_id.
1082 * @signature: D-Bus signature of the argument (a single complete type).
1083 * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
1085 * Information about an argument for a method or a signal.
1092 * GDBusAuthMechanism:credentials:
1094 * If authenticating as a server, this property contains the
1095 * received credentials, if any.
1097 * If authenticating as a client, the property contains the
1098 * credentials that were sent, if any.
1103 * GDBusAuthObserver:
1105 * The #GDBusAuthObserver structure contains only private data and
1106 * should only be accessed using the provided API.
1113 * GDBusAuthObserver::authorize-authenticated-peer:
1114 * @observer: The #GDBusAuthObserver emitting the signal.
1115 * @stream: A #GIOStream for the #GDBusConnection.
1116 * @credentials: Credentials received from the peer or %NULL.
1118 * Emitted to check if a peer that is successfully authenticated
1121 * Returns: %TRUE if the peer is authorized, %FALSE if not.
1127 * GDBusAuthObserverClass:
1128 * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal.
1130 * Class structure for #GDBusAuthObserverClass.
1138 * @G_DBUS_CALL_FLAGS_NONE: No flags set.
1139 * @G_DBUS_CALL_FLAGS_NO_AUTO_START: The bus must not launch an owner for the destination name in response to this method invocation.
1141 * Flags used in g_dbus_connection_call() and similar APIs.
1148 * GDBusCapabilityFlags:
1149 * @G_DBUS_CAPABILITY_FLAGS_NONE: No flags set.
1150 * @G_DBUS_CAPABILITY_FLAGS_UNIX_FD_PASSING: The connection supports exchanging UNIX file descriptors with the remote peer.
1152 * Capabilities negotiated with the remote peer.
1161 * The #GDBusConnection structure contains only private data and
1162 * should only be accessed using the provided API.
1169 * GDBusConnection::closed:
1170 * @connection: The #GDBusConnection emitting the signal.
1171 * @remote_peer_vanished: %TRUE if @connection is closed because the remote peer closed its end of the connection.
1172 * @error: A #GError with more details about the event or %NULL.
1174 * Emitted when the connection is closed.
1176 * The cause of this event can be
1179 * If g_dbus_connection_close() is called. In this case
1180 * @remote_peer_vanished is set to %FALSE and @error is %NULL.
1181 * </para></listitem>
1183 * If the remote peer closes the connection. In this case
1184 * @remote_peer_vanished is set to %TRUE and @error is set.
1185 * </para></listitem>
1187 * If the remote peer sends invalid or malformed data. In this
1188 * case @remote_peer_vanished is set to %FALSE and @error
1190 * </para></listitem>
1193 * Upon receiving this signal, you should give up your reference to
1194 * @connection. You are guaranteed that this signal is emitted only
1202 * GDBusConnection:address:
1204 * A D-Bus address specifying potential endpoints that can be used
1205 * when establishing the connection.
1212 * GDBusConnection:authentication-observer:
1214 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
1221 * GDBusConnection:capabilities:
1223 * Flags from the #GDBusCapabilityFlags enumeration
1224 * representing connection features negotiated with the other peer.
1231 * GDBusConnection:closed:
1233 * A boolean specifying whether the connection has been closed.
1240 * GDBusConnection:exit-on-close:
1242 * A boolean specifying whether the process will be terminated (by
1243 * calling <literal>raise(SIGTERM)</literal>) if the connection
1244 * is closed by the remote peer.
1246 * Note that #GDBusConnection objects returned by g_bus_get_finish() and
1247 * g_bus_get_sync() will (usually) have this property set to %TRUE.
1254 * GDBusConnection:flags:
1256 * Flags from the #GDBusConnectionFlags enumeration.
1263 * GDBusConnection:guid:
1265 * The GUID of the peer performing the role of server when
1268 * If you are constructing a #GDBusConnection and pass
1269 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the
1270 * #GDBusConnection:flags property then you MUST also set this
1271 * property to a valid guid.
1273 * If you are constructing a #GDBusConnection and pass
1274 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the
1275 * #GDBusConnection:flags property you will be able to read the GUID
1276 * of the other peer here after the connection has been successfully
1284 * GDBusConnection:locked:
1286 * A boolean specifying whether the message is locked.
1293 * GDBusConnection:stream:
1295 * The underlying #GIOStream used for I/O.
1297 * If this is passed on construction and is a #GSocketConnection,
1298 * then the corresponding #GSocket will be put into non-blocking mode.
1300 * While the #GDBusConnection is active, it will interact with this
1301 * stream from a worker thread, so it is not safe to interact with
1302 * the stream directly.
1309 * GDBusConnection:unique-name:
1311 * The unique name as assigned by the message bus or %NULL if the
1312 * connection is not open or not a message bus connection.
1319 * GDBusConnectionClass:
1320 * @closed: Signal class handler for the #GDBusConnection::closed signal.
1322 * Class structure for #GDBusConnection.
1329 * GDBusConnectionFlags:
1330 * @G_DBUS_CONNECTION_FLAGS_NONE: No flags set.
1331 * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT: Perform authentication against server.
1332 * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER: Perform authentication against client.
1333 * @G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: When authenticating as a server, allow the anonymous authentication method.
1334 * @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.
1335 * @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.
1337 * Flags used when creating a new #GDBusConnection.
1346 * Certain timeout errors, e.g. while starting a service. Warning: this is
1347 * Error codes for the %G_DBUS_ERROR error domain.
1355 * @error_code: An error code.
1356 * @dbus_error_name: The D-Bus error name to associate with @error_code.
1358 * Struct used in g_dbus_error_register_error_domain().
1367 * Base type for D-Bus interfaces.
1374 * GDBusInterfaceGetPropertyFunc:
1375 * @connection: A #GDBusConnection.
1376 * @sender: The unique bus name of the remote caller.
1377 * @object_path: The object path that the method was invoked on.
1378 * @interface_name: The D-Bus interface name for the property.
1379 * @property_name: The name of the property to get the value of.
1380 * @error: Return location for error.
1381 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
1383 * The type of the @get_property function in #GDBusInterfaceVTable.
1385 * @error is set. If the returned #GVariant is floating, it is
1386 * consumed - otherwise its reference count is decreased by one.
1388 * Returns: A #GVariant with the value for @property_name or %NULL if
1394 * GDBusInterfaceIface:
1395 * @parent_iface: The parent interface.
1396 * @get_info: Returns a #GDBusInterfaceInfo. See g_dbus_interface_get_info().
1397 * @get_object: Gets the enclosing #GDBusObject. See g_dbus_interface_get_object().
1398 * @set_object: Sets the enclosing #GDBusObject. See g_dbus_interface_set_object().
1399 * @dup_object: Gets a reference to the enclosing #GDBusObject. See g_dbus_interface_dup_object(). Added in 2.32.
1401 * Base type for D-Bus interfaces.
1408 * GDBusInterfaceInfo:
1409 * @ref_count: The reference count or -1 if statically allocated.
1410 * @name: The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties".
1411 * @methods: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusMethodInfo structures or %NULL if there are no methods.
1412 * @signals: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusSignalInfo structures or %NULL if there are no signals.
1413 * @properties: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusPropertyInfo structures or %NULL if there are no properties.
1414 * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
1416 * Information about a D-Bus interface.
1423 * GDBusInterfaceMethodCallFunc:
1424 * @connection: A #GDBusConnection.
1425 * @sender: The unique bus name of the remote caller.
1426 * @object_path: The object path that the method was invoked on.
1427 * @interface_name: The D-Bus interface name the method was invoked on.
1428 * @method_name: The name of the method that was invoked.
1429 * @parameters: A #GVariant tuple with parameters.
1430 * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
1431 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
1433 * The type of the @method_call function in #GDBusInterfaceVTable.
1440 * GDBusInterfaceSetPropertyFunc:
1441 * @connection: A #GDBusConnection.
1442 * @sender: The unique bus name of the remote caller.
1443 * @object_path: The object path that the method was invoked on.
1444 * @interface_name: The D-Bus interface name for the property.
1445 * @property_name: The name of the property to get the value of.
1446 * @value: The value to set the property to.
1447 * @error: Return location for error.
1448 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
1450 * The type of the @set_property function in #GDBusInterfaceVTable.
1452 * Returns: %TRUE if the property was set to @value, %FALSE if @error is set.
1458 * GDBusInterfaceSkeleton:
1460 * The #GDBusInterfaceSkeleton structure contains private data and should
1461 * only be accessed using the provided API.
1468 * GDBusInterfaceSkeleton::g-authorize-method:
1469 * @interface: The #GDBusInterfaceSkeleton emitting the signal.
1470 * @invocation: A #GDBusMethodInvocation.
1472 * Emitted when a method is invoked by a remote caller and used to
1473 * determine if the method call is authorized.
1475 * Note that this signal is emitted in a thread dedicated to
1476 * handling the method call so handlers are allowed to perform
1477 * blocking IO. This means that it is appropriate to call
1479 * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync">polkit_authority_check_authorization_sync()</ulink>
1481 * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS">POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION</ulink> flag set.
1483 * If %FALSE is returned then no further handlers are run and the
1484 * signal handler must take a reference to @invocation and finish
1485 * handling the call (e.g. return an error via
1486 * g_dbus_method_invocation_return_error()).
1488 * Otherwise, if %TRUE is returned, signal emission continues. If no
1489 * handlers return %FALSE, then the method is dispatched. If
1490 * @interface has an enclosing #GDBusObjectSkeleton, then the
1491 * #GDBusObjectSkeleton::authorize-method signal handlers run before
1492 * the handlers for this signal.
1494 * The default class handler just returns %TRUE.
1496 * Please note that the common case is optimized: if no signals
1497 * handlers are connected and the default class handler isn't
1498 * overridden (for both @interface and the enclosing
1499 * #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does
1501 * %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD
1502 * flags set, no dedicated thread is ever used and the call will be
1503 * handled in the same thread as the object that @interface belongs
1504 * to was exported in.
1506 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
1512 * GDBusInterfaceSkeleton:g-flags:
1514 * Flags from the #GDBusInterfaceSkeletonFlags enumeration.
1521 * GDBusInterfaceSkeletonClass:
1522 * @parent_class: The parent class.
1523 * @get_info: Returns a #GDBusInterfaceInfo. See g_dbus_interface_skeleton_get_info() for details.
1524 * @get_vtable: Returns a #GDBusInterfaceVTable. See g_dbus_interface_skeleton_get_vtable() for details.
1525 * @get_properties: Returns a #GVariant with all properties. See g_dbus_interface_skeleton_get_properties().
1526 * @flush: Emits outstanding changes, if any. See g_dbus_interface_skeleton_flush().
1527 * @g_authorize_method: Signal class handler for the #GDBusInterfaceSkeleton::g-authorize-method signal.
1529 * Class structure for #GDBusInterfaceSkeleton.
1536 * GDBusInterfaceSkeletonFlags:
1537 * @G_DBUS_INTERFACE_SKELETON_FLAGS_NONE: No flags set.
1538 * @G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD: Each method invocation is handled in a thread dedicated to the invocation. This means that the method implementation can use blocking IO without blocking any other part of the process. It also means that the method implementation must use locking to access data structures used by other threads.
1540 * Flags describing the behavior of a #GDBusInterfaceSkeleton instance.
1547 * GDBusInterfaceVTable:
1548 * @method_call: Function for handling incoming method calls.
1549 * @get_property: Function for getting a property.
1550 * @set_property: Function for setting a property.
1552 * Virtual table for handling properties and method calls for a D-Bus
1555 * If you want to handle getting/setting D-Bus properties asynchronously, simply
1556 * register an object with the <literal>org.freedesktop.DBus.Properties</literal>
1557 * D-Bus interface using g_dbus_connection_register_object().
1566 * The #GDBusMessage structure contains only private data and should
1567 * only be accessed using the provided API.
1574 * GDBusMessageByteOrder:
1575 * @G_DBUS_MESSAGE_BYTE_ORDER_BIG_ENDIAN: The byte order is big endian.
1576 * @G_DBUS_MESSAGE_BYTE_ORDER_LITTLE_ENDIAN: The byte order is little endian.
1578 * Enumeration used to describe the byte order of a D-Bus message.
1585 * GDBusMessageClass:
1587 * Class structure for #GDBusMessage.
1594 * GDBusMessageFilterFunction:
1595 * @connection: (transfer none): A #GDBusConnection.
1596 * @message: (transfer full): A locked #GDBusMessage that the filter function takes ownership of.
1597 * @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.
1598 * @user_data: User data passed when adding the filter.
1600 * Signature for function used in g_dbus_connection_add_filter().
1602 * A filter function is passed a #GDBusMessage and expected to return
1603 * a #GDBusMessage too. Passive filter functions that don't modify the
1604 * message can simply return the @message object:
1606 * static GDBusMessage *
1607 * passive_filter (GDBusConnection *connection
1608 * GDBusMessage *message,
1609 * gboolean incoming,
1610 * gpointer user_data)
1612 * /<!-- -->* inspect @message *<!-- -->/
1616 * Filter functions that wants to drop a message can simply return %NULL:
1618 * static GDBusMessage *
1619 * drop_filter (GDBusConnection *connection
1620 * GDBusMessage *message,
1621 * gboolean incoming,
1622 * gpointer user_data)
1624 * if (should_drop_message)
1626 * g_object_unref (message);
1632 * Finally, a filter function may modify a message by copying it:
1634 * static GDBusMessage *
1635 * modifying_filter (GDBusConnection *connection
1636 * GDBusMessage *message,
1637 * gboolean incoming,
1638 * gpointer user_data)
1640 * GDBusMessage *copy;
1644 * copy = g_dbus_message_copy (message, &error);
1645 * /<!-- -->* handle @error being is set *<!-- -->/
1646 * g_object_unref (message);
1648 * /<!-- -->* modify @copy *<!-- -->/
1653 * If the returned #GDBusMessage is different from @message and cannot
1654 * be sent on @connection (it could use features, such as file
1655 * descriptors, not compatible with @connection), then a warning is
1656 * logged to <emphasis>standard error</emphasis>. Applications can
1657 * check this ahead of time using g_dbus_message_to_blob() passing a
1658 * #GDBusCapabilityFlags value obtained from @connection.
1660 * g_object_unref() or %NULL to drop the message. Passive filter
1661 * functions can simply return the passed @message object.
1663 * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
1669 * GDBusMessageFlags:
1670 * @G_DBUS_MESSAGE_FLAGS_NONE: No flags set.
1671 * @G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED: A reply is not expected.
1672 * @G_DBUS_MESSAGE_FLAGS_NO_AUTO_START: The bus must not launch an owner for the destination name in response to this message.
1674 * Message flags used in #GDBusMessage.
1681 * GDBusMessageHeaderField:
1682 * @G_DBUS_MESSAGE_HEADER_FIELD_INVALID: Not a valid header field.
1683 * @G_DBUS_MESSAGE_HEADER_FIELD_PATH: The object path.
1684 * @G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE: The interface name.
1685 * @G_DBUS_MESSAGE_HEADER_FIELD_MEMBER: The method or signal name.
1686 * @G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME: The name of the error that occurred.
1687 * @G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL: The serial number the message is a reply to.
1688 * @G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION: The name the message is intended for.
1689 * @G_DBUS_MESSAGE_HEADER_FIELD_SENDER: Unique name of the sender of the message (filled in by the bus).
1690 * @G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE: The signature of the message body.
1691 * @G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS: The number of UNIX file descriptors that accompany the message.
1693 * Header fields used in #GDBusMessage.
1701 * @G_DBUS_MESSAGE_TYPE_INVALID: Message is of invalid type.
1702 * @G_DBUS_MESSAGE_TYPE_METHOD_CALL: Method call.
1703 * @G_DBUS_MESSAGE_TYPE_METHOD_RETURN: Method reply.
1704 * @G_DBUS_MESSAGE_TYPE_ERROR: Error reply.
1705 * @G_DBUS_MESSAGE_TYPE_SIGNAL: Signal emission.
1707 * Message types used in #GDBusMessage.
1715 * @ref_count: The reference count or -1 if statically allocated.
1716 * @name: The name of the D-Bus method, e.g. @RequestName.
1717 * @in_args: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no in arguments.
1718 * @out_args: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no out arguments.
1719 * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
1721 * Information about a method on an D-Bus interface.
1728 * GDBusMethodInvocation:
1730 * The #GDBusMethodInvocation structure contains only private data and
1731 * should only be accessed using the provided API.
1738 * GDBusMethodInvocationClass:
1740 * Class structure for #GDBusMethodInvocation.
1748 * @ref_count: The reference count or -1 if statically allocated.
1749 * @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.
1750 * @interfaces: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusInterfaceInfo structures or %NULL if there are no interfaces.
1751 * @nodes: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusNodeInfo structures or %NULL if there are no nodes.
1752 * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
1754 * Information about nodes in a remote object hierarchy.
1761 * GDBusObject::interface-added:
1762 * @object: The #GDBusObject emitting the signal.
1763 * @interface: The #GDBusInterface that was added.
1765 * Emitted when @interface is added to @object.
1772 * GDBusObject::interface-removed:
1773 * @object: The #GDBusObject emitting the signal.
1774 * @interface: The #GDBusInterface that was removed.
1776 * Emitted when @interface is removed from @object.
1784 * @parent_iface: The parent interface.
1785 * @get_object_path: Returns the object path. See g_dbus_object_get_object_path().
1786 * @get_interfaces: Returns all interfaces. See g_dbus_object_get_interfaces().
1787 * @get_interface: Returns an interface by name. See g_dbus_object_get_interface().
1788 * @interface_added: Signal handler for the #GDBusObject::interface-added signal.
1789 * @interface_removed: Signal handler for the #GDBusObject::interface-removed signal.
1791 * Base object type for D-Bus objects.
1798 * GDBusObjectManager::interface-added:
1799 * @manager: The #GDBusObjectManager emitting the signal.
1800 * @object: The #GDBusObject on which an interface was added.
1801 * @interface: The #GDBusInterface that was added.
1803 * Emitted when @interface is added to @object.
1805 * This signal exists purely as a convenience to avoid having to
1806 * connect signals to all objects managed by @manager.
1813 * GDBusObjectManager::interface-removed:
1814 * @manager: The #GDBusObjectManager emitting the signal.
1815 * @object: The #GDBusObject on which an interface was removed.
1816 * @interface: The #GDBusInterface that was removed.
1818 * Emitted when @interface has been removed from @object.
1820 * This signal exists purely as a convenience to avoid having to
1821 * connect signals to all objects managed by @manager.
1828 * GDBusObjectManager::object-added:
1829 * @manager: The #GDBusObjectManager emitting the signal.
1830 * @object: The #GDBusObject that was added.
1832 * Emitted when @object is added to @manager.
1839 * GDBusObjectManager::object-removed:
1840 * @manager: The #GDBusObjectManager emitting the signal.
1841 * @object: The #GDBusObject that was removed.
1843 * Emitted when @object is removed from @manager.
1850 * GDBusObjectManagerClient:
1852 * The #GDBusObjectManagerClient structure contains private data and should
1853 * only be accessed using the provided API.
1860 * GDBusObjectManagerClient::interface-proxy-properties-changed:
1861 * @manager: The #GDBusObjectManagerClient emitting the signal.
1862 * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
1863 * @interface_proxy: The #GDBusProxy that has properties that are changing.
1864 * @changed_properties: A #GVariant containing the properties that changed.
1865 * @invalidated_properties: A %NULL terminated array of properties that was invalidated.
1867 * Emitted when one or more D-Bus properties on proxy changes. The
1868 * local cache has already been updated when this signal fires. Note
1869 * that both @changed_properties and @invalidated_properties are
1870 * guaranteed to never be %NULL (either may be empty though).
1872 * This signal exists purely as a convenience to avoid having to
1873 * connect signals to all interface proxies managed by @manager.
1875 * This signal is emitted in the
1876 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
1877 * that @manager was constructed in.
1884 * GDBusObjectManagerClient::interface-proxy-signal:
1885 * @manager: The #GDBusObjectManagerClient emitting the signal.
1886 * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal.
1887 * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal.
1888 * @sender_name: The sender of the signal or NULL if the connection is not a bus connection.
1889 * @signal_name: The signal name.
1890 * @parameters: A #GVariant tuple with parameters for the signal.
1892 * Emitted when a D-Bus signal is received on @interface_proxy.
1894 * This signal exists purely as a convenience to avoid having to
1895 * connect signals to all interface proxies managed by @manager.
1897 * This signal is emitted in the
1898 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
1899 * that @manager was constructed in.
1906 * GDBusObjectManagerClient:bus-type:
1908 * If this property is not %G_BUS_TYPE_NONE, then
1909 * #GDBusObjectManagerClient:connection must be %NULL and will be set to the
1910 * #GDBusConnection obtained by calling g_bus_get() with the value
1918 * GDBusObjectManagerClient:connection:
1920 * The #GDBusConnection to use.
1927 * GDBusObjectManagerClient:flags:
1929 * Flags from the #GDBusObjectManagerClientFlags enumeration.
1936 * GDBusObjectManagerClient:get-proxy-type-destroy-notify:
1938 * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data.
1945 * GDBusObjectManagerClient:get-proxy-type-func:
1947 * The #GDBusProxyTypeFunc to use when determining what #GType to
1948 * use for interface proxies or %NULL.
1955 * GDBusObjectManagerClient:get-proxy-type-user-data:
1957 * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func.
1964 * GDBusObjectManagerClient:name:
1966 * The well-known name or unique name that the manager is for.
1973 * GDBusObjectManagerClient:name-owner:
1975 * The unique name that owns #GDBusObjectManagerClient:name or %NULL if
1976 * no-one is currently owning the name. Connect to the
1977 * #GObject::notify signal to track changes to this property.
1984 * GDBusObjectManagerClient:object-path:
1986 * The object path the manager is for.
1993 * GDBusObjectManagerClientClass:
1994 * @parent_class: The parent class.
1995 * @interface_proxy_signal: Signal class handler for the #GDBusObjectManagerClient::interface-proxy-signal signal.
1996 * @interface_proxy_properties_changed: Signal class handler for the #GDBusObjectManagerClient::interface-proxy-properties-changed signal.
1998 * Class structure for #GDBusObjectManagerClient.
2005 * GDBusObjectManagerClientFlags:
2006 * @G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_NONE: No flags set.
2007 * @G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START: If not set and the manager is 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 managers for well-known names.
2009 * Flags used when constructing a #GDBusObjectManagerClient.
2016 * GDBusObjectManagerIface:
2017 * @parent_iface: The parent interface.
2018 * @get_object_path: Virtual function for g_dbus_object_manager_get_object_path().
2019 * @get_objects: Virtual function for g_dbus_object_manager_get_objects().
2020 * @get_object: Virtual function for g_dbus_object_manager_get_object().
2021 * @get_interface: Virtual function for g_dbus_object_manager_get_interface().
2022 * @object_added: Signal handler for the #GDBusObjectManager::object-added signal.
2023 * @object_removed: Signal handler for the #GDBusObjectManager::object-removed signal.
2024 * @interface_added: Signal handler for the #GDBusObjectManager::interface-added signal.
2025 * @interface_removed: Signal handler for the #GDBusObjectManager::interface-removed signal.
2027 * Base type for D-Bus object managers.
2034 * GDBusObjectManagerServer:
2036 * The #GDBusObjectManagerServer structure contains private data and should
2037 * only be accessed using the provided API.
2044 * GDBusObjectManagerServer:connection:
2046 * The #GDBusConnection to export objects on.
2053 * GDBusObjectManagerServer:object-path:
2055 * The object path to register the manager object at.
2062 * GDBusObjectManagerServerClass:
2063 * @parent_class: The parent class.
2065 * Class structure for #GDBusObjectManagerServer.
2074 * The #GDBusObjectProxy structure contains private data and should
2075 * only be accessed using the provided API.
2082 * GDBusObjectProxy:g-connection:
2084 * The connection of the proxy.
2091 * GDBusObjectProxy:g-object-path:
2093 * The object path of the proxy.
2100 * GDBusObjectProxyClass:
2101 * @parent_class: The parent class.
2103 * Class structure for #GDBusObjectProxy.
2110 * GDBusObjectSkeleton:
2112 * The #GDBusObjectSkeleton structure contains private data and should only be
2113 * accessed using the provided API.
2120 * GDBusObjectSkeleton::authorize-method:
2121 * @object: The #GDBusObjectSkeleton emitting the signal.
2122 * @interface: The #GDBusInterfaceSkeleton that @invocation is for.
2123 * @invocation: A #GDBusMethodInvocation.
2125 * Emitted when a method is invoked by a remote caller and used to
2126 * determine if the method call is authorized.
2128 * This signal is like #GDBusInterfaceSkeleton<!-- -->'s
2129 * #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is
2130 * for the enclosing object.
2132 * The default class handler just returns %TRUE.
2134 * Returns: %TRUE if the call is authorized, %FALSE otherwise.
2140 * GDBusObjectSkeleton:g-object-path:
2142 * The object path where the object is exported.
2149 * GDBusObjectSkeletonClass:
2150 * @parent_class: The parent class.
2151 * @authorize_method: Signal class handler for the #GDBusObjectSkeleton::authorize-method signal.
2153 * Class structure for #GDBusObjectSkeleton.
2160 * GDBusPropertyInfo:
2161 * @ref_count: The reference count or -1 if statically allocated.
2162 * @name: The name of the D-Bus property, e.g. "SupportedFilesystems".
2163 * @signature: The D-Bus signature of the property (a single complete type).
2164 * @flags: Access control flags for the property.
2165 * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
2167 * Information about a D-Bus property on a D-Bus interface.
2174 * GDBusPropertyInfoFlags:
2175 * @G_DBUS_PROPERTY_INFO_FLAGS_NONE: No flags set.
2176 * @G_DBUS_PROPERTY_INFO_FLAGS_READABLE: Property is readable.
2177 * @G_DBUS_PROPERTY_INFO_FLAGS_WRITABLE: Property is writable.
2179 * Flags describing the access control of a D-Bus property.
2188 * The #GDBusProxy structure contains only private data and
2189 * should only be accessed using the provided API.
2196 * GDBusProxy::g-properties-changed:
2197 * @proxy: The #GDBusProxy emitting the signal.
2198 * @changed_properties: A #GVariant containing the properties that changed
2199 * @invalidated_properties: A %NULL terminated array of properties that was invalidated
2201 * Emitted when one or more D-Bus properties on @proxy changes. The
2202 * local cache has already been updated when this signal fires. Note
2203 * that both @changed_properties and @invalidated_properties are
2204 * guaranteed to never be %NULL (either may be empty though).
2206 * If the proxy has the flag
2207 * %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then
2208 * @invalidated_properties will always be empty.
2210 * This signal corresponds to the
2211 * <literal>PropertiesChanged</literal> D-Bus signal on the
2212 * <literal>org.freedesktop.DBus.Properties</literal> interface.
2219 * GDBusProxy::g-signal:
2220 * @proxy: The #GDBusProxy emitting the signal.
2221 * @sender_name: The sender of the signal or %NULL if the connection is not a bus connection.
2222 * @signal_name: The name of the signal.
2223 * @parameters: A #GVariant tuple with parameters for the signal.
2225 * Emitted when a signal from the remote object and interface that @proxy is for, has been received.
2232 * GDBusProxy:g-bus-type:
2234 * If this property is not %G_BUS_TYPE_NONE, then
2235 * #GDBusProxy:g-connection must be %NULL and will be set to the
2236 * #GDBusConnection obtained by calling g_bus_get() with the value
2244 * GDBusProxy:g-connection:
2246 * The #GDBusConnection the proxy is for.
2253 * GDBusProxy:g-default-timeout:
2255 * The timeout to use if -1 (specifying default timeout) is passed
2256 * as @timeout_msec in the g_dbus_proxy_call() and
2257 * g_dbus_proxy_call_sync() functions.
2259 * This allows applications to set a proxy-wide timeout for all
2260 * remote method invocations on the proxy. If this property is -1,
2261 * the default timeout (typically 25 seconds) is used. If set to
2262 * %G_MAXINT, then no timeout is used.
2269 * GDBusProxy:g-flags:
2271 * Flags from the #GDBusProxyFlags enumeration.
2278 * GDBusProxy:g-interface-info:
2280 * Ensure that interactions with this proxy conform to the given
2281 * interface. This is mainly to ensure that malformed data received
2282 * from the other peer is ignored. The given #GDBusInterfaceInfo is
2283 * said to be the <emphasis>expected interface</emphasis>.
2285 * The checks performed are:
2288 * When completing a method call, if the type signature of
2289 * the reply message isn't what's expected, the reply is
2290 * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
2291 * </para></listitem>
2293 * Received signals that have a type signature mismatch are dropped and
2294 * a warning is logged via g_warning().
2295 * </para></listitem>
2297 * Properties received via the initial <literal>GetAll()</literal> call
2298 * or via the <literal>::PropertiesChanged</literal> signal (on the
2299 * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface) or
2300 * set using g_dbus_proxy_set_cached_property() with a type signature
2301 * mismatch are ignored and a warning is logged via g_warning().
2302 * </para></listitem>
2304 * Note that these checks are never done on methods, signals and
2305 * properties that are not referenced in the given
2306 * #GDBusInterfaceInfo, since extending a D-Bus interface on the
2307 * service-side is not considered an ABI break.
2314 * GDBusProxy:g-interface-name:
2316 * The D-Bus interface name the proxy is for.
2323 * GDBusProxy:g-name:
2325 * The well-known or unique name that the proxy is for.
2332 * GDBusProxy:g-name-owner:
2334 * The unique name that owns #GDBusProxy:g-name or %NULL if no-one
2335 * currently owns that name. You may connect to #GObject::notify signal to
2336 * track changes to this property.
2343 * GDBusProxy:g-object-path:
2345 * The object path the proxy is for.
2353 * @g_properties_changed: Signal class handler for the #GDBusProxy::g-properties-changed signal.
2354 * @g_signal: Signal class handler for the #GDBusProxy::g-signal signal.
2356 * Class structure for #GDBusProxy.
2364 * @G_DBUS_PROXY_FLAGS_NONE: No flags set.
2365 * @G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES: Don't load properties.
2366 * @G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS: Don't connect to signals on the remote object.
2367 * @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.
2368 * @G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES: If set, the property value for any <emphasis>invalidated property</emphasis> will be (asynchronously) retrieved upon receiving the <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">PropertiesChanged</ulink> D-Bus signal and the property will not cause emission of the #GDBusProxy::g-properties-changed signal. When the value is received the #GDBusProxy::g-properties-changed signal is emitted for the property along with the retrieved value. Since 2.32.
2370 * Flags used when constructing an instance of a #GDBusProxy derived class.
2377 * GDBusProxyTypeFunc:
2378 * @manager: A #GDBusObjectManagerClient.
2379 * @object_path: The object path of the remote object.
2380 * @interface_name: (allow-none): The interface name of the remote object or %NULL if a #GDBusObjectProxy #GType is requested.
2381 * @user_data: User data.
2383 * Function signature for a function used to determine the #GType to
2384 * use for an interface proxy (if @interface_name is not %NULL) or
2385 * object proxy (if @interface_name is %NULL).
2387 * This function is called in the
2388 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
2389 * that @manager was constructed in.
2391 * must be a #GDBusProxy<!-- -->- or #GDBusObjectProxy<!-- -->-derived
2394 * Returns: A #GType to use for the remote object. The returned type
2400 * GDBusSendMessageFlags:
2401 * @G_DBUS_SEND_MESSAGE_FLAGS_NONE: No flags set.
2402 * @G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL: Do not automatically assign a serial number from the #GDBusConnection object when sending a message.
2404 * Flags used when sending #GDBusMessage<!-- -->s on a #GDBusConnection.
2413 * The #GDBusServer structure contains only private data and
2414 * should only be accessed using the provided API.
2421 * GDBusServer::new-connection:
2422 * @server: The #GDBusServer emitting the signal.
2423 * @connection: A #GDBusConnection for the new connection.
2425 * Emitted when a new authenticated connection has been made. Use
2426 * g_dbus_connection_get_peer_credentials() to figure out what
2427 * identity (if any), was authenticated.
2429 * If you want to accept the connection, take a reference to the
2430 * @connection object and return %TRUE. When you are done with the
2431 * connection call g_dbus_connection_close() and give up your
2432 * reference. Note that the other peer may disconnect at any time -
2433 * a typical thing to do when accepting a connection is to listen to
2434 * the #GDBusConnection::closed signal.
2436 * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
2437 * then the signal is emitted in a new thread dedicated to the
2438 * connection. Otherwise the signal is emitted in the <link
2439 * linkend="g-main-context-push-thread-default">thread-default main
2440 * loop</link> of the thread that @server was constructed in.
2442 * You are guaranteed that signal handlers for this signal runs
2443 * before incoming messages on @connection are processed. This means
2444 * that it's suitable to call g_dbus_connection_register_object() or
2445 * similar from the signal handler.
2449 * Returns: %TRUE to claim @connection, %FALSE to let other handlers
2455 * GDBusServer:active:
2457 * Whether the server is currently active.
2464 * GDBusServer:address:
2466 * The D-Bus address to listen on.
2473 * GDBusServer:authentication-observer:
2475 * A #GDBusAuthObserver object to assist in the authentication process or %NULL.
2482 * GDBusServer:client-address:
2484 * The D-Bus address that clients can use.
2491 * GDBusServer:flags:
2493 * Flags from the #GDBusServerFlags enumeration.
2502 * The guid of the server.
2510 * @new_connection: Signal class handler for the #GDBusServer::new-connection signal.
2512 * Class structure for #GDBusServer.
2520 * @G_DBUS_SERVER_FLAGS_NONE: No flags set.
2521 * @G_DBUS_SERVER_FLAGS_RUN_IN_THREAD: All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details).
2522 * @G_DBUS_SERVER_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS: Allow the anonymous authentication method.
2524 * Flags used when creating a #GDBusServer.
2531 * GDBusSignalCallback:
2532 * @connection: A #GDBusConnection.
2533 * @sender_name: The unique bus name of the sender of the signal.
2534 * @object_path: The object path that the signal was emitted on.
2535 * @interface_name: The name of the interface.
2536 * @signal_name: The name of the signal.
2537 * @parameters: A #GVariant tuple with parameters for the signal.
2538 * @user_data: User data passed when subscribing to the signal.
2540 * Signature for callback function used in g_dbus_connection_signal_subscribe().
2548 * @G_DBUS_SIGNAL_FLAGS_NONE: No flags set.
2549 * @G_DBUS_SIGNAL_FLAGS_NO_MATCH_RULE: Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually).
2551 * Flags used when subscribing to signals via g_dbus_connection_signal_subscribe().
2559 * @ref_count: The reference count or -1 if statically allocated.
2560 * @name: The name of the D-Bus signal, e.g. "NameOwnerChanged".
2561 * @args: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusArgInfo structures or %NULL if there are no arguments.
2562 * @annotations: (array zero-terminated=1): A pointer to a %NULL-terminated array of pointers to #GDBusAnnotationInfo structures or %NULL if there are no annotations.
2564 * Information about a signal on a D-Bus interface.
2571 * GDBusSubtreeDispatchFunc:
2572 * @connection: A #GDBusConnection.
2573 * @sender: The unique bus name of the remote caller.
2574 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
2575 * @interface_name: The D-Bus interface name that the method call or property access is for.
2576 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
2577 * @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
2578 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
2580 * The type of the @dispatch function in #GDBusSubtreeVTable.
2582 * Subtrees are flat. @node, if non-%NULL, is always exactly one
2583 * segment of the object path (ie: it never contains a slash).
2585 * Returns: A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods.
2591 * GDBusSubtreeEnumerateFunc:
2592 * @connection: A #GDBusConnection.
2593 * @sender: The unique bus name of the remote caller.
2594 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
2595 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
2597 * The type of the @enumerate function in #GDBusSubtreeVTable.
2599 * This function is called when generating introspection data and also
2600 * when preparing to dispatch incoming messages in the event that the
2601 * %G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not
2602 * specified (ie: to verify that the object path is valid).
2604 * Hierarchies are not supported; the items that you return should not
2605 * contain the '/' character.
2607 * The return value will be freed with g_strfreev().
2609 * Returns: A newly allocated array of strings for node names that are children of @object_path.
2615 * GDBusSubtreeFlags:
2616 * @G_DBUS_SUBTREE_FLAGS_NONE: No flags set.
2617 * @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.
2619 * Flags passed to g_dbus_connection_register_subtree().
2626 * GDBusSubtreeIntrospectFunc:
2627 * @connection: A #GDBusConnection.
2628 * @sender: The unique bus name of the remote caller.
2629 * @object_path: The object path that was registered with g_dbus_connection_register_subtree().
2630 * @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
2631 * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
2633 * The type of the @introspect function in #GDBusSubtreeVTable.
2635 * Subtrees are flat. @node, if non-%NULL, is always exactly one
2636 * segment of the object path (ie: it never contains a slash).
2638 * This function should return %NULL to indicate that there is no object
2641 * If this function returns non-%NULL, the return value is expected to
2642 * be a %NULL-terminated array of pointers to #GDBusInterfaceInfo
2643 * structures describing the interfaces implemented by @node. This
2644 * array will have g_dbus_interface_info_unref() called on each item
2645 * before being freed with g_free().
2647 * The difference between returning %NULL and an array containing zero
2648 * items is that the standard DBus interfaces will returned to the
2649 * remote introspector in the empty array case, but not in the %NULL
2652 * Returns: A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL.
2658 * GDBusSubtreeVTable:
2659 * @enumerate: Function for enumerating child nodes.
2660 * @introspect: Function for introspecting a child node.
2661 * @dispatch: Function for dispatching a remote call on a child node.
2663 * Virtual table for handling subtrees registered with g_dbus_connection_register_subtree().
2672 * An implementation of #GBufferedInputStream that allows for high-level
2673 * data manipulation of arbitrary data (including binary operations).
2678 * GDataOutputStream:
2680 * An implementation of #GBufferedOutputStream that allows for high-level
2681 * data manipulation of arbitrary data (including binary operations).
2686 * GDataOutputStream:byte-order:
2688 * Determines the byte ordering that is used when writing
2689 * multi-byte entities (such as integers) to the stream.
2694 * GDataStream:byte-order:
2696 * The ::byte-order property determines the byte ordering that
2697 * is used when reading multi-byte entities (such as integers)
2703 * GDataStream:newline-type:
2705 * The :newline-type property determines what is considered
2706 * as a line ending when reading complete lines from the stream.
2711 * GDataStreamByteOrder:
2712 * @G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN: Selects Big Endian byte order.
2713 * @G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN: Selects Little Endian byte order.
2714 * @G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN: Selects endianness based on host machine's architecture.
2716 * #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources
2717 * across various machine architectures.
2722 * GDataStreamNewlineType:
2723 * @G_DATA_STREAM_NEWLINE_TYPE_LF: Selects "LF" line endings, common on most modern UNIX platforms.
2724 * @G_DATA_STREAM_NEWLINE_TYPE_CR: Selects "CR" line endings.
2725 * @G_DATA_STREAM_NEWLINE_TYPE_CR_LF: Selects "CR, LF" line ending, common on Microsoft Windows.
2726 * @G_DATA_STREAM_NEWLINE_TYPE_ANY: Automatically try to handle any line ending type.
2728 * #GDataStreamNewlineType is used when checking for or setting the line endings for a given file.
2735 * <structname>GDateTime</structname> is an opaque structure whose members
2736 * cannot be accessed directly.
2747 * Associates a string with a bit flag.
2748 * Used in g_parse_debug_string().
2755 * Information about an installed application from a desktop file.
2760 * GDesktopAppInfo:filename:
2762 * The origin filename of this #GDesktopAppInfo
2767 * GDesktopAppInfoLookup:
2769 * Interface that is used by backends to associate default
2770 * handlers with URI schemes.
2775 * GDesktopAppLaunchCallback:
2776 * @appinfo: a #GDesktopAppInfo
2777 * @pid: Process identifier
2778 * @user_data: User data
2780 * During invocation, g_desktop_app_info_launch_uris_as_manager() may
2781 * create one or more child processes. This callback is invoked once
2782 * for each, providing the process ID.
2789 * Opaque drive object.
2795 * @drive: a #GDrive.
2797 * Emitted when the drive's state has changed.
2802 * GDrive::disconnected:
2803 * @drive: a #GDrive.
2805 * This signal is emitted when the #GDrive have been
2806 * disconnected. If the recipient is holding references to the
2807 * object they should release them so the object can be
2813 * GDrive::eject-button:
2814 * @drive: a #GDrive.
2816 * Emitted when the physical eject button (if any) of a drive has
2822 * GDrive::stop-button:
2823 * @drive: a #GDrive.
2825 * Emitted when the physical stop button (if any) of a drive has
2834 * @g_iface: The parent interface.
2835 * @changed: Signal emitted when the drive is changed.
2836 * @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.
2837 * @eject_button: Signal emitted when the physical eject button (if any) of a drive have been pressed.
2838 * @get_name: Returns the name for the given #GDrive.
2839 * @get_icon: Returns a #GIcon for the given #GDrive.
2840 * @has_volumes: Returns %TRUE if the #GDrive has mountable volumes.
2841 * @get_volumes: Returns a list #GList of #GVolume for the #GDrive.
2842 * @is_media_removable: Returns %TRUE if the #GDrive supports removal and insertion of media.
2843 * @has_media: Returns %TRUE if the #GDrive has media inserted.
2844 * @is_media_check_automatic: Returns %TRUE if the #GDrive is capabable of automatically detecting media changes.
2845 * @can_poll_for_media: Returns %TRUE if the #GDrive is capable of manually polling for media change.
2846 * @can_eject: Returns %TRUE if the #GDrive can eject media.
2847 * @eject: Ejects a #GDrive.
2848 * @eject_finish: Finishes an eject operation.
2849 * @poll_for_media: Poll for media insertion/removal on a #GDrive.
2850 * @poll_for_media_finish: Finishes a media poll operation.
2851 * @get_identifier: Returns the identifier of the given kind, or %NULL if the #GDrive doesn't have one.
2852 * @enumerate_identifiers: Returns an array strings listing the kinds of identifiers which the #GDrive has.
2853 * @get_start_stop_type: Gets a #GDriveStartStopType with details about starting/stopping the drive. Since 2.22.
2854 * @can_stop: Returns %TRUE if a #GDrive can be stopped. Since 2.22.
2855 * @stop: Stops a #GDrive. Since 2.22.
2856 * @stop_finish: Finishes a stop operation. Since 2.22.
2857 * @can_start: Returns %TRUE if a #GDrive can be started. Since 2.22.
2858 * @can_start_degraded: Returns %TRUE if a #GDrive can be started degraded. Since 2.22.
2859 * @start: Starts a #GDrive. Since 2.22.
2860 * @start_finish: Finishes a start operation. Since 2.22.
2861 * @stop_button: Signal emitted when the physical stop button (if any) of a drive have been pressed. Since 2.22.
2862 * @eject_with_operation: Starts ejecting a #GDrive using a #GMountOperation. Since 2.22.
2863 * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
2864 * @get_sort_key: Gets a key used for sorting #GDrive instances or %NULL if no such key exists. Since 2.32.
2866 * Interface for creating #GDrive implementations.
2872 * @G_DRIVE_START_NONE: No flags set.
2874 * Flags used when starting a drive.
2881 * GDriveStartStopType:
2882 * @G_DRIVE_START_STOP_TYPE_UNKNOWN: Unknown or drive doesn't support start/stop.
2883 * @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.
2884 * @G_DRIVE_START_STOP_TYPE_NETWORK: The start/stop methods are used for connecting/disconnect to the drive over the network.
2885 * @G_DRIVE_START_STOP_TYPE_MULTIDISK: The start/stop methods will assemble/disassemble a virtual drive from several physical drives.
2886 * @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)
2888 * Enumeration describing how a drive can be started/stopped.
2897 * An object for Emblems
2903 * @G_EMBLEM_ORIGIN_UNKNOWN: Emblem of unknown origin
2904 * @G_EMBLEM_ORIGIN_DEVICE: Emblem adds device-specific information
2905 * @G_EMBLEM_ORIGIN_LIVEMETADATA: Emblem depicts live metadata, such as "readonly"
2906 * @G_EMBLEM_ORIGIN_TAG: Emblem comes from a user-defined tag, e.g. set by nautilus (in the future)
2908 * GEmblemOrigin is used to add information about the origin of the emblem
2918 * An implementation of #GIcon for icons with emblems.
2924 * @g_type_class: the parent class
2925 * @minimum: the smallest possible value.
2926 * @maximum: the largest possible value.
2927 * @n_values: the number of possible values.
2928 * @values: an array of #GEnumValue structs describing the individual values.
2930 * The class of an enumeration type holds information about its
2937 * @value: the enum value
2938 * @value_name: the name of the value
2939 * @value_nick: the nickname of the value
2941 * A structure which contains a single enum value, its name, and its
2948 * @domain: error domain, e.g. #G_FILE_ERROR
2949 * @code: error code, e.g. %G_FILE_ERROR_NOENT
2950 * @message: human-readable informative error message
2952 * The <structname>GError</structname> structure contains
2953 * information about an error that has occurred.
2960 * A handle to an object implementing the #GFileIface interface.
2961 * Generally stores a location within the file system. Handles do not
2962 * necessarily represent files or directories that currently exist.
2967 * GFileAttributeInfo:
2968 * @name: the name of the attribute.
2969 * @type: the #GFileAttributeType type of the attribute.
2970 * @flags: a set of #GFileAttributeInfoFlags.
2972 * Information about a specific attribute.
2977 * GFileAttributeInfoFlags:
2978 * @G_FILE_ATTRIBUTE_INFO_NONE: no flags set.
2979 * @G_FILE_ATTRIBUTE_INFO_COPY_WITH_FILE: copy the attribute values when the file is copied.
2980 * @G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED: copy the attribute values when the file is moved.
2982 * Flags specifying the behaviour of an attribute.
2987 * GFileAttributeInfoList:
2988 * @infos: an array of #GFileAttributeInfo<!-- -->s.
2989 * @n_infos: the number of values in the array.
2991 * Acts as a lightweight registry for possible valid file attributes.
2992 * The registry stores Key-Value pair formats as #GFileAttributeInfo<!-- -->s.
2997 * GFileAttributeMatcher:
2999 * Determines if a string matches a file attribute.
3004 * GFileAttributeStatus:
3005 * @G_FILE_ATTRIBUTE_STATUS_UNSET: Attribute value is unset (empty).
3006 * @G_FILE_ATTRIBUTE_STATUS_SET: Attribute value is set.
3007 * @G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING: Indicates an error in setting the value.
3009 * Used by g_file_set_attributes_from_info() when setting file attributes.
3014 * GFileAttributeType:
3015 * @G_FILE_ATTRIBUTE_TYPE_INVALID: indicates an invalid or uninitalized type.
3016 * @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated UTF8 string.
3017 * @G_FILE_ATTRIBUTE_TYPE_BYTE_STRING: a zero terminated string of non-zero bytes.
3018 * @G_FILE_ATTRIBUTE_TYPE_BOOLEAN: a boolean value.
3019 * @G_FILE_ATTRIBUTE_TYPE_UINT32: an unsigned 4-byte/32-bit integer.
3020 * @G_FILE_ATTRIBUTE_TYPE_INT32: a signed 4-byte/32-bit integer.
3021 * @G_FILE_ATTRIBUTE_TYPE_UINT64: an unsigned 8-byte/64-bit integer.
3022 * @G_FILE_ATTRIBUTE_TYPE_INT64: a signed 8-byte/64-bit integer.
3023 * @G_FILE_ATTRIBUTE_TYPE_OBJECT: a #GObject.
3024 * @G_FILE_ATTRIBUTE_TYPE_STRINGV: a %NULL terminated char **. Since 2.22
3026 * The data types for file attributes.
3032 * @G_FILE_COPY_NONE: No flags set.
3033 * @G_FILE_COPY_OVERWRITE: Overwrite any existing files
3034 * @G_FILE_COPY_BACKUP: Make a backup of any existing files.
3035 * @G_FILE_COPY_NOFOLLOW_SYMLINKS: Don't follow symlinks.
3036 * @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set used for copy (see #GFileInfo).
3037 * @G_FILE_COPY_NO_FALLBACK_FOR_MOVE: Don't use copy and delete fallback if native move not supported.
3038 * @G_FILE_COPY_TARGET_DEFAULT_PERMS: Leaves target file with default perms, instead of setting the source file perms.
3040 * Flags used when copying or moving files.
3046 * @G_FILE_CREATE_NONE: No flags set.
3047 * @G_FILE_CREATE_PRIVATE: Create a file that can only be accessed by the current user.
3048 * @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
3050 * Flags used when an operation may create a file.
3055 * GFileDescriptorBased:
3057 * An interface for file descriptor based io objects.
3062 * GFileDescriptorBasedIface:
3063 * @g_iface: The parent interface.
3072 * A per matched file iterator.
3079 * A subclass of GIOStream for opened files. This adds
3080 * a few file-specific operations and seeking and truncating.
3082 * #GFileIOStream implements GSeekable.
3089 * Gets an icon for a #GFile. Implements #GLoadableIcon.
3096 * The file containing the icon.
3102 * @g_iface: The parent interface.
3103 * @dup: Duplicates a #GFile.
3104 * @hash: Creates a hash of a #GFile.
3105 * @equal: Checks equality of two given #GFile<!-- -->s.
3106 * @is_native: Checks to see if a file is native to the system.
3107 * @has_uri_scheme: Checks to see if a #GFile has a given URI scheme.
3108 * @get_uri_scheme: Gets the URI scheme for a #GFile.
3109 * @get_basename: Gets the basename for a given #GFile.
3110 * @get_path: Gets the current path within a #GFile.
3111 * @get_uri: Gets a URI for the path within a #GFile.
3112 * @get_parse_name: Gets the parsed name for the #GFile.
3113 * @get_parent: Gets the parent directory for the #GFile.
3114 * @prefix_matches: Checks whether a #GFile contains a specified file.
3115 * @get_relative_path: Gets the path for a #GFile relative to a given path.
3116 * @resolve_relative_path: Resolves a relative path for a #GFile to an absolute path.
3117 * @get_child_for_display_name: Gets the child #GFile for a given display name.
3118 * @enumerate_children: Gets a #GFileEnumerator with the children of a #GFile.
3119 * @enumerate_children_async: Asynchronously gets a #GFileEnumerator with the children of a #GFile.
3120 * @enumerate_children_finish: Finishes asynchronously enumerating the children.
3121 * @query_info: Gets the #GFileInfo for a #GFile.
3122 * @query_info_async: Asynchronously gets the #GFileInfo for a #GFile.
3123 * @query_info_finish: Finishes an asynchronous query info operation.
3124 * @query_filesystem_info: Gets a #GFileInfo for the file system #GFile is on.
3125 * @query_filesystem_info_async: Asynchronously gets a #GFileInfo for the file system #GFile is on.
3126 * @query_filesystem_info_finish: Finishes asynchronously getting the file system info.
3127 * @find_enclosing_mount: Gets a #GMount for the #GFile.
3128 * @find_enclosing_mount_async: Asynchronously gets the #GMount for a #GFile.
3129 * @find_enclosing_mount_finish: Finishes asynchronously getting the volume.
3130 * @set_display_name: Sets the display name for a #GFile.
3131 * @set_display_name_async: Asynchronously sets a #GFile's display name.
3132 * @set_display_name_finish: Finishes asynchronously setting a #GFile's display name.
3133 * @query_settable_attributes: Returns a list of #GFileAttribute<!-- -->s that can be set.
3134 * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttribute<!-- -->s that can be set.
3135 * @_query_settable_attributes_finish: Finishes asynchronously querying settable attributes.
3136 * @query_writable_namespaces: Returns a list of #GFileAttribute namespaces that are writable.
3137 * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttribute namespaces that are writable.
3138 * @_query_writable_namespaces_finish: Finishes asynchronously querying the writable namespaces.
3139 * @set_attribute: Sets a #GFileAttribute.
3140 * @set_attributes_from_info: Sets a #GFileAttribute with information from a #GFileInfo.
3141 * @set_attributes_async: Asynchronously sets a file's attributes.
3142 * @set_attributes_finish: Finishes setting a file's attributes asynchronously.
3143 * @read_fn: Reads a file asynchronously.
3144 * @read_async: Asynchronously reads a file.
3145 * @read_finish: Finishes asynchronously reading a file.
3146 * @append_to: Writes to the end of a file.
3147 * @append_to_async: Asynchronously writes to the end of a file.
3148 * @append_to_finish: Finishes an asynchronous file append operation.
3149 * @create: Creates a new file.
3150 * @create_async: Asynchronously creates a file.
3151 * @create_finish: Finishes asynchronously creating a file.
3152 * @replace: Replaces the contents of a file.
3153 * @replace_async: Asynchronously replaces the contents of a file.
3154 * @replace_finish: Finishes asynchronously replacing a file.
3155 * @delete_file: Deletes a file.
3156 * @_delete_file_async: Asynchronously deletes a file.
3157 * @_delete_file_finish: Finishes an asynchronous delete.
3158 * @trash: Sends a #GFile to the Trash location.
3159 * @_trash_async: Asynchronously sends a #GFile to the Trash location.
3160 * @_trash_finish: Finishes an asynchronous file trashing operation.
3161 * @make_directory: Makes a directory.
3162 * @_make_directory_async: Asynchronously makes a directory.
3163 * @_make_directory_finish: Finishes making a directory asynchronously.
3164 * @make_symbolic_link: Makes a symbolic link.
3165 * @_make_symbolic_link_async: Asynchronously makes a symbolic link
3166 * @_make_symbolic_link_finish: Finishes making a symbolic link asynchronously.
3167 * @copy: Copies a file.
3168 * @copy_async: Asynchronously copies a file.
3169 * @copy_finish: Finishes an asynchronous copy operation.
3170 * @move: Moves a file.
3171 * @_move_async: Asynchronously moves a file.
3172 * @_move_finish: Finishes an asynchronous move operation.
3173 * @mount_mountable: Mounts a mountable object.
3174 * @mount_mountable_finish: Finishes a mounting operation.
3175 * @unmount_mountable: Unmounts a mountable object.
3176 * @unmount_mountable_finish: Finishes an unmount operation.
3177 * @eject_mountable: Ejects a mountable.
3178 * @eject_mountable_finish: Finishes an eject operation.
3179 * @mount_enclosing_volume: Mounts a specified location.
3180 * @mount_enclosing_volume_finish: Finishes mounting a specified location.
3181 * @monitor_dir: Creates a #GFileMonitor for the location.
3182 * @monitor_file: Creates a #GFileMonitor for the location.
3183 * @open_readwrite: Open file read/write. Since 2.22.
3184 * @open_readwrite_async: Asynchronously opens file read/write. Since 2.22.
3185 * @open_readwrite_finish: Finishes an asynchronous open read/write. Since 2.22.
3186 * @create_readwrite: Creates file read/write. Since 2.22.
3187 * @create_readwrite_async: Asynchronously creates file read/write. Since 2.22.
3188 * @create_readwrite_finish: Finishes an asynchronous creates read/write. Since 2.22.
3189 * @replace_readwrite: Replaces file read/write. Since 2.22.
3190 * @replace_readwrite_async: Asynchronously replaces file read/write. Since 2.22.
3191 * @replace_readwrite_finish: Finishes an asynchronous replace read/write. Since 2.22.
3192 * @start_mountable: Starts a mountable object. Since 2.22.
3193 * @start_mountable_finish: Finishes an start operation. Since 2.22.
3194 * @stop_mountable: Stops a mountable. Since 2.22.
3195 * @stop_mountable_finish: Finishes an stop operation. Since 2.22.
3196 * @supports_thread_contexts: a boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22.
3197 * @unmount_mountable_with_operation: Unmounts a mountable object using a #GMountOperation. Since 2.22.
3198 * @unmount_mountable_with_operation_finish: Finishes an unmount operation using a #GMountOperation. Since 2.22.
3199 * @eject_mountable_with_operation: Ejects a mountable object using a #GMountOperation. Since 2.22.
3200 * @eject_mountable_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
3201 * @poll_mountable: Polls a mountable object for media changes. Since 2.22.
3202 * @poll_mountable_finish: Finishes an poll operation for media changes. Since 2.22.
3204 * An interface for writing VFS file handles.
3211 * Stores information about a file system object referenced by a #GFile.
3218 * A subclass of GInputStream for opened files. This adds
3219 * a few file-specific operations and seeking.
3221 * #GFileInputStream implements #GSeekable.
3228 * Watches for changes to a file.
3233 * GFileMonitor::changed:
3234 * @monitor: a #GFileMonitor.
3236 * @other_file: (allow-none): a #GFile or #NULL.
3237 * @event_type: a #GFileMonitorEvent.
3239 * Emitted when @file has been changed.
3241 * If using #G_FILE_MONITOR_SEND_MOVED flag and @event_type is
3242 * #G_FILE_MONITOR_SEND_MOVED, @file will be set to a #GFile containing the
3243 * old path, and @other_file will be set to a #GFile containing the new path.
3245 * In all the other cases, @other_file will be set to #NULL.
3250 * GFileMonitorEvent:
3251 * @G_FILE_MONITOR_EVENT_CHANGED: a file changed.
3252 * @G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT: a hint that this was probably the last change in a set of changes.
3253 * @G_FILE_MONITOR_EVENT_DELETED: a file was deleted.
3254 * @G_FILE_MONITOR_EVENT_CREATED: a file was created.
3255 * @G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED: a file attribute was changed.
3256 * @G_FILE_MONITOR_EVENT_PRE_UNMOUNT: the file location will soon be unmounted.
3257 * @G_FILE_MONITOR_EVENT_UNMOUNTED: the file location was unmounted.
3258 * @G_FILE_MONITOR_EVENT_MOVED: the file was moved.
3260 * Specifies what type of event a monitor event is.
3265 * GFileMonitorFlags:
3266 * @G_FILE_MONITOR_NONE: No flags set.
3267 * @G_FILE_MONITOR_WATCH_MOUNTS: Watch for mount events.
3268 * @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).
3270 * Flags used to set what a #GFileMonitor will watch for.
3275 * GFileOutputStream:
3277 * A subclass of GOutputStream for opened files. This adds
3278 * a few file-specific operations and seeking and truncating.
3280 * #GFileOutputStream implements GSeekable.
3285 * GFileProgressCallback:
3286 * @current_num_bytes: the current number of bytes in the operation.
3287 * @total_num_bytes: the total number of bytes in the operation.
3288 * @user_data: user data passed to the callback.
3290 * When doing file operations that may take a while, such as moving
3291 * a file or copying a file, a progress callback is used to pass how
3292 * far along that operation is to the application.
3297 * GFileQueryInfoFlags:
3298 * @G_FILE_QUERY_INFO_NONE: No flags set.
3299 * @G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS: Don't follow symlinks.
3301 * Flags used when querying a #GFileInfo.
3306 * GFileReadMoreCallback:
3307 * @file_contents: the data as currently read.
3308 * @file_size: the size of the data currently read.
3309 * @callback_data: data passed to the callback.
3311 * When loading the partial contents of a file with g_file_load_partial_contents_async(),
3312 * it may become necessary to determine if any more data from the file should be loaded.
3313 * A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data
3314 * should be read, or %FALSE otherwise.
3316 * Returns: %TRUE if more data should be read back. %FALSE otherwise.
3322 * @G_FILE_TYPE_UNKNOWN: File's type is unknown.
3323 * @G_FILE_TYPE_REGULAR: File handle represents a regular file.
3324 * @G_FILE_TYPE_DIRECTORY: File handle represents a directory.
3325 * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link (Unix systems).
3326 * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, block device, or character device.
3327 * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems).
3328 * @G_FILE_TYPE_MOUNTABLE: File is a mountable location.
3330 * Indicates the file's on-disk type.
3335 * GFilenameCompleter:
3337 * Completes filenames based on files that exist within the file system.
3342 * GFilenameCompleter::got-completion-data:
3344 * Emitted when the file name completion information comes available.
3349 * GFilesystemPreviewType:
3350 * @G_FILESYSTEM_PREVIEW_TYPE_IF_ALWAYS: Only preview files if user has explicitly requested it.
3351 * @G_FILESYSTEM_PREVIEW_TYPE_IF_LOCAL: Preview files if user has requested preview of "local" files.
3352 * @G_FILESYSTEM_PREVIEW_TYPE_NEVER: Never preview files.
3354 * Indicates a hint from the file system whether files should be
3355 * previewed in a file manager. Returned as the value of the key
3356 * #G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW.
3361 * GFilterInputStream:
3363 * A base class for all input streams that work on an underlying stream.
3368 * GFilterOutputStream:
3370 * A base class for all output streams that work on an underlying stream.
3376 * @g_type_class: the parent class
3377 * @mask: a mask covering all possible values.
3378 * @n_values: the number of possible values.
3379 * @values: an array of #GFlagsValue structs describing the individual values.
3381 * The class of a flags type holds information about its
3388 * @value: the flags value
3389 * @value_name: the name of the value
3390 * @value_nick: the nickname of the value
3392 * A structure which contains a single flags value, its name, and its
3399 * @data: a data pointer
3401 * Declares a type of function which takes an arbitrary
3402 * data pointer argument and has no return value. It is
3403 * not currently used in GLib or GTK+.
3410 * An opaque structure representing a HMAC operation.
3411 * To create a new GHmac, use g_hmac_new(). To free
3412 * a GHmac, use g_hmac_unref().
3420 * @G_IO_ERROR_FAILED: Generic error condition for when any operation fails.
3421 * @G_IO_ERROR_NOT_FOUND: File not found.
3422 * @G_IO_ERROR_EXISTS: File already exists.
3423 * @G_IO_ERROR_IS_DIRECTORY: File is a directory.
3424 * @G_IO_ERROR_NOT_DIRECTORY: File is not a directory.
3425 * @G_IO_ERROR_NOT_EMPTY: File is a directory that isn't empty.
3426 * @G_IO_ERROR_NOT_REGULAR_FILE: File is not a regular file.
3427 * @G_IO_ERROR_NOT_SYMBOLIC_LINK: File is not a symbolic link.
3428 * @G_IO_ERROR_NOT_MOUNTABLE_FILE: File cannot be mounted.
3429 * @G_IO_ERROR_FILENAME_TOO_LONG: Filename is too many characters.
3430 * @G_IO_ERROR_INVALID_FILENAME: Filename is invalid or contains invalid characters.
3431 * @G_IO_ERROR_TOO_MANY_LINKS: File contains too many symbolic links.
3432 * @G_IO_ERROR_NO_SPACE: No space left on drive.
3433 * @G_IO_ERROR_INVALID_ARGUMENT: Invalid argument.
3434 * @G_IO_ERROR_PERMISSION_DENIED: Permission denied.
3435 * @G_IO_ERROR_NOT_SUPPORTED: Operation not supported for the current backend.
3436 * @G_IO_ERROR_NOT_MOUNTED: File isn't mounted.
3437 * @G_IO_ERROR_ALREADY_MOUNTED: File is already mounted.
3438 * @G_IO_ERROR_CLOSED: File was closed.
3439 * @G_IO_ERROR_CANCELLED: Operation was cancelled. See #GCancellable.
3440 * @G_IO_ERROR_PENDING: Operations are still pending.
3441 * @G_IO_ERROR_READ_ONLY: File is read only.
3442 * @G_IO_ERROR_CANT_CREATE_BACKUP: Backup couldn't be created.
3443 * @G_IO_ERROR_WRONG_ETAG: File's Entity Tag was incorrect.
3444 * @G_IO_ERROR_TIMED_OUT: Operation timed out.
3445 * @G_IO_ERROR_WOULD_RECURSE: Operation would be recursive.
3446 * @G_IO_ERROR_BUSY: File is busy.
3447 * @G_IO_ERROR_WOULD_BLOCK: Operation would block.
3448 * @G_IO_ERROR_HOST_NOT_FOUND: Host couldn't be found (remote operations).
3449 * @G_IO_ERROR_WOULD_MERGE: Operation would merge files.
3450 * @G_IO_ERROR_FAILED_HANDLED: Operation failed and a helper program has already interacted with the user. Do not display any error dialog.
3451 * @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
3452 * @G_IO_ERROR_NOT_INITIALIZED: The object has not been initialized. Since 2.22
3453 * @G_IO_ERROR_ADDRESS_IN_USE: The requested address is already in use. Since 2.22
3454 * @G_IO_ERROR_PARTIAL_INPUT: Need more input to finish operation. Since 2.24
3455 * @G_IO_ERROR_INVALID_DATA: There input data was invalid. Since 2.24
3456 * @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.
3457 * @G_IO_ERROR_HOST_UNREACHABLE: Host unreachable. Since 2.26
3458 * @G_IO_ERROR_NETWORK_UNREACHABLE: Network unreachable. Since 2.26
3459 * @G_IO_ERROR_CONNECTION_REFUSED: Connection refused. Since 2.26
3460 * @G_IO_ERROR_PROXY_FAILED: Connection to proxy server failed. Since 2.26
3461 * @G_IO_ERROR_PROXY_AUTH_FAILED: Proxy authentication failed. Since 2.26
3462 * @G_IO_ERROR_PROXY_NEED_AUTH: Proxy server needs authentication. Since 2.26
3463 * @G_IO_ERROR_PROXY_NOT_ALLOWED: Proxy connection is not allowed by ruleset. Since 2.26
3465 * Error codes returned by GIO functions.
3472 * Opaque module base class for extending GIO.
3479 * Represents a scope for loading IO modules. A scope can be used for blocking
3480 * duplicate modules, or blocking a module you don't want to load.
3482 * The scope can be used with g_io_modules_load_all_in_directory_with_scope()
3483 * or g_io_modules_scan_all_in_directory_with_scope().
3490 * GIOModuleScopeFlags:
3491 * @G_IO_MODULE_SCOPE_NONE: No module scan flags
3492 * @G_IO_MODULE_SCOPE_BLOCK_DUPLICATES: When using this scope to load or scan modules, automatically block a modules which has the same base basename as previously loaded module.
3494 * Flags for use with g_io_module_scope_new().
3503 * Opaque class for defining and scheduling IO jobs.
3508 * GIOSchedulerJobFunc:
3509 * @job: a #GIOSchedulerJob.
3510 * @cancellable: optional #GCancellable object, %NULL to ignore.
3511 * @user_data: the data to pass to callback function
3515 * Long-running jobs should periodically check the @cancellable
3516 * to see if they have been cancelled.
3518 * complete the job, %FALSE if the job is complete (or cancelled)
3520 * Returns: %TRUE if this function should be called again to
3527 * Base class for read-write streams.
3532 * GIOStreamSpliceFlags:
3533 * @G_IO_STREAM_SPLICE_NONE: Do not close either stream.
3534 * @G_IO_STREAM_SPLICE_CLOSE_STREAM1: Close the first stream after the splice.
3535 * @G_IO_STREAM_SPLICE_CLOSE_STREAM2: Close the second stream after the splice.
3536 * @G_IO_STREAM_SPLICE_WAIT_FOR_BOTH: Wait for both splice operations to finish before calling the callback.
3538 * GIOStreamSpliceFlags determine how streams should be spliced.
3547 * An abstract type that specifies an icon.
3553 * @g_iface: The parent interface.
3554 * @hash: A hash for a given #GIcon.
3555 * @equal: Checks if two #GIcon<!-- -->s are equal.
3556 * @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).
3557 * @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).
3559 * GIconIface is used to implement GIcon types for various
3560 * different systems. See #GThemedIcon and #GLoadableIcon for
3561 * examples of how to implement this interface.
3568 * The <structname>GIConv</structname> struct wraps an
3569 * iconv() conversion descriptor. It contains private data
3570 * and should only be accessed using the following functions.
3577 * An IPv4 or IPv6 internet address.
3582 * GInetAddress:is-any:
3584 * Whether this is the "any" address for its family.
3585 * See g_inet_address_get_is_any().
3592 * GInetAddress:is-link-local:
3594 * Whether this is a link-local address.
3595 * See g_inet_address_get_is_link_local().
3602 * GInetAddress:is-loopback:
3604 * Whether this is the loopback address for its family.
3605 * See g_inet_address_get_is_loopback().
3612 * GInetAddress:is-mc-global:
3614 * Whether this is a global multicast address.
3615 * See g_inet_address_get_is_mc_global().
3622 * GInetAddress:is-mc-link-local:
3624 * Whether this is a link-local multicast address.
3625 * See g_inet_address_get_is_mc_link_local().
3632 * GInetAddress:is-mc-node-local:
3634 * Whether this is a node-local multicast address.
3635 * See g_inet_address_get_is_mc_node_local().
3642 * GInetAddress:is-mc-org-local:
3644 * Whether this is an organization-local multicast address.
3645 * See g_inet_address_get_is_mc_org_local().
3652 * GInetAddress:is-mc-site-local:
3654 * Whether this is a site-local multicast address.
3655 * See g_inet_address_get_is_mc_site_local().
3662 * GInetAddress:is-multicast:
3664 * Whether this is a multicast address.
3665 * See g_inet_address_get_is_multicast().
3672 * GInetAddress:is-site-local:
3674 * Whether this is a site-local address.
3675 * See g_inet_address_get_is_loopback().
3684 * A combination of an IPv4 or IPv6 base address and a length,
3685 * representing a range of IP addresses.
3692 * GInetSocketAddress:
3694 * An IPv4 or IPv6 socket address, corresponding to a <type>struct
3695 * sockaddr_in</type> or <type>struct sockaddr_in6</type>.
3700 * GInetSocketAddress:flowinfo:
3702 * The <literal>sin6_flowinfo</literal> field, for IPv6 addresses.
3709 * GInetSocketAddress:scope_id:
3711 * The <literal>sin6_scope_id</literal> field, for IPv6 addresses.
3720 * Interface for initializable objects.
3728 * @g_iface: The parent interface.
3729 * @init: Initializes the object.
3731 * Provides an interface for initializing object such that initialization
3739 * GInitiallyUnowned:
3741 * All the fields in the <structname>GInitiallyUnowned</structname> structure
3742 * are private to the #GInitiallyUnowned implementation and should never be
3743 * accessed directly.
3748 * GInitiallyUnownedClass:
3750 * The class structure for the <structname>GInitiallyUnowned</structname> type.
3757 * Base class for streaming input operations.
3763 * @buffer: Pointer to a buffer where data will be written.
3764 * @size: the available size in @buffer.
3766 * Structure used for scatter/gather data input.
3767 * You generally pass in an array of #GInputVector<!-- -->s
3768 * and the operation will store the read data starting in the
3769 * first buffer, switching to the next as needed.
3776 * GInstanceInitFunc:
3777 * @instance: The instance to initialize.
3778 * @g_class: The class of the type the instance is created for.
3780 * A callback function used by the type system to initialize a new
3781 * instance of a type. This function initializes all instance members and
3782 * allocates any resources required by it.
3783 * Initialization of a derived instance involves calling all its parent
3784 * types instance initializers, so the class member of the instance
3785 * is altered during its initialization to always point to the class that
3786 * belongs to the type the current initializer was introduced for.
3791 * GInterfaceFinalizeFunc:
3792 * @g_iface: The interface structure to finalize.
3793 * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
3795 * A callback function used by the type system to finalize an interface.
3796 * This function should destroy any internal data and release any resources
3797 * allocated by the corresponding GInterfaceInitFunc() function.
3803 * @interface_init: location of the interface initialization function
3804 * @interface_finalize: location of the interface finalization function
3805 * @interface_data: user-supplied data passed to the interface init/finalize functions
3807 * A structure that provides information to the type system which is
3808 * used specifically for managing interface types.
3813 * GInterfaceInitFunc:
3814 * @g_iface: The interface structure to initialize.
3815 * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
3817 * A callback function used by the type system to initialize a new
3818 * interface. This function should initialize all internal data and
3819 * allocate any resources required by the interface.
3824 * GLIB_CHECK_VERSION:
3825 * @major: the major version to check for
3826 * @minor: the minor version to check for
3827 * @micro: the micro version to check for
3829 * Checks the version of the GLib library that is being compiled
3833 * <title>Checking the version of the GLib library</title>
3835 * if (!GLIB_CHECK_VERSION (1, 2, 0))
3836 * g_error ("GLib version 1.2.0 or above is needed");
3840 * See glib_check_version() for a runtime check.
3842 * is the same as or newer than the passed-in version.
3844 * Returns: %TRUE if the version of the GLib header files
3849 * GLIB_VERSION_2_26:
3851 * A macro that evaluates to the 2.26 version of GLib, in a format
3852 * that can be used by the C pre-processor.
3859 * GLIB_VERSION_2_28:
3861 * A macro that evaluates to the 2.28 version of GLib, in a format
3862 * that can be used by the C pre-processor.
3869 * GLIB_VERSION_2_30:
3871 * A macro that evaluates to the 2.30 version of GLib, in a format
3872 * that can be used by the C pre-processor.
3879 * GLIB_VERSION_2_32:
3881 * A macro that evaluates to the 2.32 version of GLib, in a format
3882 * that can be used by the C pre-processor.
3889 * GLIB_VERSION_MAX_ALLOWED:
3891 * A macro that should be defined by the user prior to including
3892 * the glib.h header.
3893 * The definition should be one of the predefined GLib version
3894 * macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,...
3896 * This macro defines the upper bound for the GLib API to use.
3898 * If a function has been introduced in a newer version of GLib,
3899 * it is possible to use this symbol to get compiler warnings when
3900 * trying to use that function.
3907 * GLIB_VERSION_MIN_REQUIRED:
3909 * A macro that should be defined by the user prior to including
3910 * the glib.h header.
3911 * The definition should be one of the predefined GLib version
3912 * macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,...
3914 * This macro defines the lower bound for the GLib API to use.
3916 * If a function has been deprecated in a newer version of GLib,
3917 * it is possible to use this symbol to avoid the compiler warnings
3918 * without disabling warning for every deprecated function.
3927 * Generic type for all kinds of icons that can be loaded
3933 * GLoadableIconIface:
3934 * @g_iface: The parent interface.
3935 * @load: Loads an icon.
3936 * @load_async: Loads an icon asynchronously.
3937 * @load_finish: Finishes an asynchronous icon load.
3939 * Interface for icons that can be loaded as a stream.
3946 * The <structname>GMainContext</structname> struct is an opaque data
3947 * type representing a set of sources to be handled in a main loop.
3954 * The <structname>GMainLoop</structname> struct is an opaque data type
3955 * representing the main event loop of a GLib or GTK+ application.
3961 * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8
3962 * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace
3963 * @G_MARKUP_ERROR_PARSE: document was ill-formed
3964 * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known
3965 * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known
3966 * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid
3967 * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing
3969 * Error codes returned by markup parsing.
3974 * GMarkupParseContext:
3976 * A parse context is used to parse a stream of bytes that
3977 * you expect to contain marked-up text.
3979 * See g_markup_parse_context_new(), #GMarkupParser, and so
3980 * on for more details.
3985 * GMarkupParseFlags:
3986 * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use
3987 * @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
3988 * @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
3990 * Flags that affect the behaviour of the parser.
3996 * @start_element: Callback to invoke when the opening tag of an element is seen.
3997 * @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>.
3998 * @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.
3999 * @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.
4000 * @error: Callback to invoke when an error occurs.
4002 * Any of the fields in #GMarkupParser can be %NULL, in which case they
4003 * will be ignored. Except for the @error function, any of these callbacks
4004 * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT,
4005 * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT
4006 * errors are intended to be set from these callbacks. If you set an error
4007 * from a callback, g_markup_parse_context_parse() will report that error
4008 * back to its caller.
4014 * @malloc: function to use for allocating memory.
4015 * @realloc: function to use for reallocating memory.
4016 * @free: function to use to free memory.
4017 * @calloc: function to use for allocating zero-filled memory.
4018 * @try_malloc: function to use for allocating memory without a default error handler.
4019 * @try_realloc: function to use for reallocating memory without a default error handler.
4021 * A set of functions used to perform memory allocation. The same #GMemVTable must
4022 * be used for all allocations in the same program; a call to g_mem_set_vtable(),
4023 * if it exists, should be prior to any use of GLib.
4028 * GMemoryInputStream:
4030 * Implements #GInputStream for arbitrary memory chunks.
4035 * GMemoryOutputStream:
4037 * Implements #GOutputStream for arbitrary memory chunks.
4042 * GMemoryOutputStream:data:
4044 * Pointer to buffer where data will be written.
4051 * GMemoryOutputStream:data-size:
4053 * Size of data written to the buffer.
4060 * GMemoryOutputStream:destroy-function: (skip)
4062 * Function called with the buffer as argument when the stream is destroyed.
4069 * GMemoryOutputStream:realloc-function: (skip)
4071 * Function with realloc semantics called to enlarge the buffer.
4078 * GMemoryOutputStream:size:
4080 * Current size of the data buffer.
4089 * #GMenu is an opaque structure type. You must access it using the
4097 * GMenuAttributeIter:
4099 * #GMenuAttributeIter is an opaque structure type. You must access it
4100 * using the functions below.
4109 * #GMenuItem is an opaque structure type. You must access it using the
4119 * #GMenuLinkIter is an opaque structure type. You must access it using
4120 * the functions below.
4129 * #GMenuModel is an opaque structure type. You must access it using the
4137 * GMenuModel::items-changed:
4138 * @model: the #GMenuModel that is changing
4139 * @position: the position of the change
4140 * @removed: the number of items removed
4141 * @added: the number of items added
4143 * Emitted when a change has occured to the menu.
4145 * The only changes that can occur to a menu is that items are removed
4146 * or added. Items may not change (except by being removed and added
4147 * back in the same location). This signal is capable of describing
4148 * both of those changes (at the same time).
4150 * The signal means that starting at the index @position, @removed
4151 * items were removed and @added items were added in their place. If
4152 * @removed is zero then only items were added. If @added is zero
4153 * then only items were removed.
4155 * As an example, if the menu contains items a, b, c, d (in that
4156 * order) and the signal (2, 1, 3) occurs then the new composition of
4157 * the menu will be a, b, _, _, _, d (with each _ representing some
4160 * Signal handlers may query the model (particularly the added items)
4161 * and expect to see the results of the modification that is being
4162 * reported. The signal is emitted after the modification.
4169 * A handle to an object implementing the #GMountIface interface.
4175 * @mount: the object on which the signal is emitted
4177 * Emitted when the mount has been changed.
4182 * GMount::pre-unmount:
4183 * @mount: the object on which the signal is emitted
4185 * This signal is emitted when the #GMount is about to be
4193 * GMount::unmounted:
4194 * @mount: the object on which the signal is emitted
4196 * This signal is emitted when the #GMount have been
4197 * unmounted. If the recipient is holding references to the
4198 * object they should release them so the object can be
4205 * @g_iface: The parent interface.
4206 * @changed: Changed signal that is emitted when the mount's state has changed.
4207 * @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.
4208 * @pre_unmount: The ::pre-unmount 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.
4209 * @get_root: Gets a #GFile to the root directory of the #GMount.
4210 * @get_name: Gets a string containing the name of the #GMount.
4211 * @get_icon: Gets a #GIcon for the #GMount.
4212 * @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.
4213 * @get_volume: Gets a #GVolume the mount is located on. Returns %NULL if the #GMount is not associated with a #GVolume.
4214 * @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.
4215 * @can_unmount: Checks if a #GMount can be unmounted.
4216 * @can_eject: Checks if a #GMount can be ejected.
4217 * @unmount: Starts unmounting a #GMount.
4218 * @unmount_finish: Finishes an unmounting operation.
4219 * @eject: Starts ejecting a #GMount.
4220 * @eject_finish: Finishes an eject operation.
4221 * @remount: Starts remounting a #GMount.
4222 * @remount_finish: Finishes a remounting operation.
4223 * @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.
4224 * @guess_content_type_finish: Finishes a content type guessing operation. Added in 2.18.
4225 * @guess_content_type_sync: Synchronous variant of @guess_content_type. Added in 2.18
4226 * @unmount_with_operation: Starts unmounting a #GMount using a #GMountOperation. Since 2.22.
4227 * @unmount_with_operation_finish: Finishes an unmounting operation using a #GMountOperation. Since 2.22.
4228 * @eject_with_operation: Starts ejecting a #GMount using a #GMountOperation. Since 2.22.
4229 * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
4230 * @get_default_location: Gets a #GFile indication a start location that can be use as the entry point for this mount. Since 2.24.
4231 * @get_sort_key: Gets a key used for sorting #GMount instance or %NULL if no such key exists. Since 2.32.
4233 * Interface for implementing operations for mounts.
4239 * @G_MOUNT_MOUNT_NONE: No flags set.
4241 * Flags used when mounting a mount.
4248 * Class for providing authentication methods for mounting operations,
4249 * such as mounting a file locally, or authenticating with a server.
4254 * GMountOperation::aborted:
4256 * Emitted by the backend when e.g. a device becomes unavailable
4257 * while a mount operation is in progress.
4259 * Implementations of GMountOperation should handle this signal
4260 * by dismissing open password dialogs.
4267 * GMountOperation::ask-password:
4268 * @op: a #GMountOperation requesting a password.
4269 * @message: string containing a message to display to the user.
4270 * @default_user: string containing the default user name.
4271 * @default_domain: string containing the default domain.
4272 * @flags: a set of #GAskPasswordFlags.
4274 * Emitted when a mount operation asks the user for a password.
4276 * If the message contains a line break, the first line should be
4277 * presented as a heading. For example, it may be used as the
4278 * primary text in a #GtkMessageDialog.
4283 * GMountOperation::ask-question:
4284 * @op: a #GMountOperation asking a question.
4285 * @message: string containing a message to display to the user.
4286 * @choices: an array of strings for each possible choice.
4288 * Emitted when asking the user a question and gives a list of
4289 * choices for the user to choose from.
4291 * If the message contains a line break, the first line should be
4292 * presented as a heading. For example, it may be used as the
4293 * primary text in a #GtkMessageDialog.
4298 * GMountOperation::reply:
4299 * @op: a #GMountOperation.
4300 * @result: a #GMountOperationResult indicating how the request was handled
4302 * Emitted when the user has replied to the mount operation.
4307 * GMountOperation::show-processes:
4308 * @op: a #GMountOperation.
4309 * @message: string containing a message to display to the user.
4310 * @processes: (element-type GPid): an array of #GPid for processes blocking the operation.
4311 * @choices: an array of strings for each possible choice.
4313 * Emitted when one or more processes are blocking an operation
4314 * e.g. unmounting/ejecting a #GMount or stopping a #GDrive.
4316 * Note that this signal may be emitted several times to update the
4317 * list of blocking processes as processes close files. The
4318 * application should only respond with g_mount_operation_reply() to
4319 * the latest signal (setting #GMountOperation:choice to the choice
4322 * If the message contains a line break, the first line should be
4323 * presented as a heading. For example, it may be used as the
4324 * primary text in a #GtkMessageDialog.
4331 * GMountOperation:anonymous:
4333 * Whether to use an anonymous user when authenticating.
4338 * GMountOperation:choice:
4340 * The index of the user's choice when a question is asked during the
4341 * mount operation. See the #GMountOperation::ask-question signal.
4346 * GMountOperation:domain:
4348 * The domain to use for the mount operation.
4353 * GMountOperation:password:
4355 * The password that is used for authentication when carrying out
4356 * the mount operation.
4361 * GMountOperation:password-save:
4363 * Determines if and how the password information should be saved.
4368 * GMountOperation:username:
4370 * The user name that is used for authentication when carrying out
4371 * the mount operation.
4376 * GMountOperationResult:
4377 * @G_MOUNT_OPERATION_HANDLED: The request was fulfilled and the user specified data is now available
4378 * @G_MOUNT_OPERATION_ABORTED: The user requested the mount operation to be aborted
4379 * @G_MOUNT_OPERATION_UNHANDLED: The request was unhandled (i.e. not implemented)
4381 * #GMountOperationResult is returned as a result when a request for
4382 * information is send by the mounting operation.
4387 * GMountUnmountFlags:
4388 * @G_MOUNT_UNMOUNT_NONE: No flags set.
4389 * @G_MOUNT_UNMOUNT_FORCE: Unmount even if there are outstanding file operations on the mount.
4391 * Flags used when an unmounting a mount.
4398 * A #GSocketConnectable for resolving a hostname and connecting to
4406 * #GNetworkMonitor monitors the status of network connections and
4407 * indicates when a possibly-user-visible change has occurred.
4414 * GNetworkMonitor::network-changed:
4415 * @monitor: a #GNetworkMonitor
4416 * @available: the current value of #GNetworkMonitor:network-available
4418 * Emitted when the network configuration changes. If @available is
4419 * %TRUE, then some hosts may be reachable that were not reachable
4420 * before, while others that were reachable before may no longer be
4421 * reachable. If @available is %FALSE, then no remote hosts are
4429 * GNetworkMonitor:network-available:
4431 * Whether the network is considered available. That is, whether the
4432 * system has a default route for at least one of IPv4 or IPv6.
4434 * Real-world networks are of course much more complicated than
4435 * this; the machine may be connected to a wifi hotspot that
4436 * requires payment before allowing traffic through, or may be
4437 * connected to a functioning router that has lost its own upstream
4438 * connectivity. Some hosts might only be accessible when a VPN is
4439 * active. Other hosts might only be accessible when the VPN is
4440 * <emphasis>not</emphasis> active. Thus, it is best to use
4441 * g_network_monitor_can_reach() or
4442 * g_network_monitor_can_reach_async() to test for reachability on a
4443 * host-by-host basis. (On the other hand, when the property is
4444 * %FALSE, the application can reasonably expect that no remote
4445 * hosts at all are reachable, and should indicate this to the user
4448 * See also #GNetworkMonitor::network-changed.
4457 * A #GSocketConnectable for resolving a SRV record and connecting to
4464 * @G_NORMALIZE_DEFAULT: standardize differences that do not affect the text content, such as the above-mentioned accent representation
4465 * @G_NORMALIZE_NFD: another name for %G_NORMALIZE_DEFAULT
4466 * @G_NORMALIZE_DEFAULT_COMPOSE: like %G_NORMALIZE_DEFAULT, but with composed forms rather than a maximally decomposed form
4467 * @G_NORMALIZE_NFC: another name for %G_NORMALIZE_DEFAULT_COMPOSE
4468 * @G_NORMALIZE_ALL: beyond %G_NORMALIZE_DEFAULT also standardize the "compatibility" characters in Unicode, such as SUPERSCRIPT THREE to the standard forms (in this case DIGIT THREE). Formatting information may be lost but for most text operations such characters should be considered the same
4469 * @G_NORMALIZE_NFKD: another name for %G_NORMALIZE_ALL
4470 * @G_NORMALIZE_ALL_COMPOSE: like %G_NORMALIZE_ALL, but with composed forms rather than a maximally decomposed form
4471 * @G_NORMALIZE_NFKC: another name for %G_NORMALIZE_ALL_COMPOSE
4473 * Defines how a Unicode string is transformed in a canonical
4474 * form, standardizing such issues as whether a character with
4475 * an accent is represented as a base character and combining
4476 * accent or as a single precomposed character. Unicode strings
4477 * should generally be normalized before comparing them.
4484 * All the fields in the <structname>GObject</structname> structure are private
4485 * to the #GObject implementation and should never be accessed directly.
4491 * @g_type_class: the parent class
4492 * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the @constructor of the parent class. Overriding @constructor should be rarely needed, e.g. to handle construct properties, or to implement singletons.
4493 * @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.
4494 * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties.
4495 * @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.
4496 * @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.
4497 * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed.
4498 * @notify: the class closure for the notify signal
4499 * @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.
4501 * The class structure for the <structname>GObject</structname> type.
4504 * <title>Implementing singletons using a constructor</title>
4506 * static MySingleton *the_singleton = NULL;
4509 * my_singleton_constructor (GType type,
4510 * guint n_construct_params,
4511 * GObjectConstructParam *construct_params)
4515 * if (!the_singleton)
4517 * object = G_OBJECT_CLASS (parent_class)->constructor (type,
4518 * n_construct_params,
4519 * construct_params);
4520 * the_singleton = MY_SINGLETON (object);
4523 * object = g_object_ref (G_OBJECT (the_singleton));
4527 * </programlisting></example>
4532 * GObjectConstructParam:
4533 * @pspec: the #GParamSpec of the construct parameter
4534 * @value: the value to set the parameter to
4536 * The <structname>GObjectConstructParam</structname> struct is an auxiliary
4537 * structure used to hand #GParamSpec/#GValue pairs to the @constructor of
4543 * GObjectFinalizeFunc:
4544 * @object: the #GObject being finalized
4546 * The type of the @finalize function of #GObjectClass.
4551 * GObjectGetPropertyFunc:
4552 * @object: a #GObject
4553 * @property_id: the numeric id under which the property was registered with g_object_class_install_property().
4554 * @value: a #GValue to return the property value in
4555 * @pspec: the #GParamSpec describing the property
4557 * The type of the @get_property function of #GObjectClass.
4562 * GObjectSetPropertyFunc:
4563 * @object: a #GObject
4564 * @property_id: the numeric id under which the property was registered with g_object_class_install_property().
4565 * @value: the new value for the property
4566 * @pspec: the #GParamSpec describing the property
4568 * The type of the @set_property function of #GObjectClass.
4574 * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
4575 * @G_OPTION_ARG_STRING: The option takes a string argument.
4576 * @G_OPTION_ARG_INT: The option takes an integer argument.
4577 * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument.
4578 * @G_OPTION_ARG_FILENAME: The option takes a filename as argument.
4579 * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings.
4580 * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings.
4581 * @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
4582 * @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
4584 * The #GOptionArg enum values determine which type of extra argument the
4585 * options expect to find. If an option expects an extra argument, it
4586 * can be specified in several ways; with a short option:
4587 * <option>-x arg</option>, with a long option: <option>--name arg</option>
4588 * or combined in a single argument: <option>--name=arg</option>.
4594 * @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.
4595 * @value: The value to be parsed.
4596 * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
4597 * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks.
4599 * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
4602 * occurred, in which case @error should be set with g_set_error()
4604 * Returns: %TRUE if the option was successfully parsed, %FALSE if an error
4611 * A <structname>GOptionContext</structname> struct defines which options
4612 * are accepted by the commandline option parser. The struct has only private
4613 * fields and should not be directly accessed.
4619 * @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>.
4620 * @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.
4621 * @flags: Flags from #GOptionFlags.
4622 * @arg: The type of the option, as a #GOptionArg.
4623 * @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().
4624 * @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().
4625 * @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().
4627 * A <structname>GOptionEntry</structname> defines a single option.
4628 * To have an effect, they must be added to a #GOptionGroup with
4629 * g_option_context_add_main_entries() or g_option_group_add_entries().
4635 * @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().
4636 * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
4637 * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
4639 * Error codes returned by option parsing.
4645 * @context: The active #GOptionContext
4646 * @group: The group to which the function belongs
4647 * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
4648 * @error: The #GError containing details about the parse error
4650 * The type of function to be used as callback when a parse error occurs.
4656 * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output.
4657 * @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.
4658 * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed.
4659 * @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
4660 * @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
4661 * @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
4662 * @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.
4664 * Flags which modify individual options.
4671 * A <structname>GOptionGroup</structname> struct defines the options in a single
4672 * group. The struct has only private fields and should not be directly accessed.
4674 * All options in a group share the same translation function. Libraries which
4675 * need to parse commandline options are expected to provide a function for
4676 * getting a <structname>GOptionGroup</structname> holding their options, which
4677 * the application can then add to its #GOptionContext.
4683 * @context: The active #GOptionContext
4684 * @group: The group to which the function belongs
4685 * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new()
4686 * @error: A return location for error details
4688 * The type of function that can be called before and after parsing.
4690 * occurred, in which case @error should be set with g_set_error()
4692 * Returns: %TRUE if the function completed successfully, %FALSE if an error
4699 * Base class for writing output.
4701 * All classes derived from GOutputStream should implement synchronous
4702 * writing, splicing, flushing and closing streams, but may implement
4703 * asynchronous versions.
4708 * GOutputStreamSpliceFlags:
4709 * @G_OUTPUT_STREAM_SPLICE_NONE: Do not close either stream.
4710 * @G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE: Close the source stream after the splice.
4711 * @G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET: Close the target stream after the splice.
4713 * GOutputStreamSpliceFlags determine how streams should be spliced.
4719 * @buffer: Pointer to a buffer of data to read.
4720 * @size: the size of @buffer.
4722 * Structure used for scatter/gather data output.
4723 * You generally pass in an array of #GOutputVector<!-- -->s
4724 * and the operation will use all the buffers as if they were
4733 * @G_PARAM_READABLE: the parameter is readable
4734 * @G_PARAM_WRITABLE: the parameter is writable
4735 * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction
4736 * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction
4737 * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required
4738 * @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
4739 * @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
4740 * @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
4741 * @G_PARAM_PRIVATE: internal
4742 * @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
4744 * Through the #GParamFlags flag values, certain aspects of parameters
4745 * can be configured.
4751 * @g_type_instance: private #GTypeInstance portion
4752 * @name: name of this parameter: always an interned string
4753 * @flags: #GParamFlags flags for this parameter
4754 * @value_type: the #GValue type for this parameter
4755 * @owner_type: #GType type that uses (introduces) this parameter
4757 * All other fields of the <structname>GParamSpec</structname> struct are private and
4758 * should not be used directly.
4763 * GParamSpecBoolean:
4764 * @parent_instance: private #GParamSpec portion
4765 * @default_value: default value for the property specified
4767 * A #GParamSpec derived structure that contains the meta data for boolean properties.
4773 * @parent_instance: private #GParamSpec portion
4775 * A #GParamSpec derived structure that contains the meta data for boxed properties.
4781 * @parent_instance: private #GParamSpec portion
4782 * @minimum: minimum value for the property specified
4783 * @maximum: maximum value for the property specified
4784 * @default_value: default value for the property specified
4786 * A #GParamSpec derived structure that contains the meta data for character properties.
4792 * @g_type_class: the parent class
4793 * @value_type: the #GValue type for this parameter
4794 * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class.
4795 * @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().
4796 * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_validate().
4797 * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp().
4799 * The class structure for the <structname>GParamSpec</structname> type.
4800 * Normally, <structname>GParamSpec</structname> classes are filled by
4801 * g_param_type_register_static().
4807 * @parent_instance: private #GParamSpec portion
4808 * @minimum: minimum value for the property specified
4809 * @maximum: maximum value for the property specified
4810 * @default_value: default value for the property specified
4811 * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90.
4813 * A #GParamSpec derived structure that contains the meta data for double properties.
4819 * @parent_instance: private #GParamSpec portion
4820 * @enum_class: the #GEnumClass for the enum
4821 * @default_value: default value for the property specified
4823 * A #GParamSpec derived structure that contains the meta data for enum
4830 * @parent_instance: private #GParamSpec portion
4831 * @flags_class: the #GFlagsClass for the flags
4832 * @default_value: default value for the property specified
4834 * A #GParamSpec derived structure that contains the meta data for flags
4841 * @parent_instance: private #GParamSpec portion
4842 * @minimum: minimum value for the property specified
4843 * @maximum: maximum value for the property specified
4844 * @default_value: default value for the property specified
4845 * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30.
4847 * A #GParamSpec derived structure that contains the meta data for float properties.
4853 * @parent_instance: private #GParamSpec portion
4854 * @is_a_type: a #GType whose subtypes can occur as values
4856 * A #GParamSpec derived structure that contains the meta data for #GType properties.
4864 * @parent_instance: private #GParamSpec portion
4865 * @minimum: minimum value for the property specified
4866 * @maximum: maximum value for the property specified
4867 * @default_value: default value for the property specified
4869 * A #GParamSpec derived structure that contains the meta data for integer properties.
4875 * @parent_instance: private #GParamSpec portion
4876 * @minimum: minimum value for the property specified
4877 * @maximum: maximum value for the property specified
4878 * @default_value: default value for the property specified
4880 * A #GParamSpec derived structure that contains the meta data for 64bit integer properties.
4886 * @parent_instance: private #GParamSpec portion
4887 * @minimum: minimum value for the property specified
4888 * @maximum: maximum value for the property specified
4889 * @default_value: default value for the property specified
4891 * A #GParamSpec derived structure that contains the meta data for long integer properties.
4897 * @parent_instance: private #GParamSpec portion
4899 * A #GParamSpec derived structure that contains the meta data for object properties.
4904 * GParamSpecOverride:
4906 * This is a type of #GParamSpec type that simply redirects operations to
4907 * another paramspec. All operations other than getting or
4908 * setting the value are redirected, including accessing the nick and
4909 * blurb, validating a value, and so forth. See
4910 * g_param_spec_get_redirect_target() for retrieving the overidden
4911 * property. #GParamSpecOverride is used in implementing
4912 * g_object_class_override_property(), and will not be directly useful
4913 * unless you are implementing a new base type similar to GObject.
4921 * @parent_instance: private #GParamSpec portion
4923 * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM
4929 * GParamSpecPointer:
4930 * @parent_instance: private #GParamSpec portion
4932 * A #GParamSpec derived structure that contains the meta data for pointer properties.
4938 * @parent_instance: private #GParamSpec portion
4939 * @default_value: default value for the property specified
4940 * @cset_first: a string containing the allowed values for the first byte
4941 * @cset_nth: a string containing the allowed values for the subsequent bytes
4942 * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth.
4943 * @null_fold_if_empty: replace empty string by %NULL
4944 * @ensure_non_null: replace %NULL strings by an empty string
4946 * A #GParamSpec derived structure that contains the meta data for string
4952 * GParamSpecTypeInfo:
4953 * @instance_size: Size of the instance (object) structure.
4954 * @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.
4955 * @instance_init: Location of the instance initialization function (optional).
4956 * @value_type: The #GType of values conforming to this #GParamSpec
4957 * @finalize: The instance finalization function (optional).
4958 * @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().
4959 * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_validate().
4960 * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp().
4962 * This structure is used to provide the type system with the information
4963 * required to initialize and destruct (finalize) a parameter's class and
4964 * instances thereof.
4965 * The initialized structure is passed to the g_param_type_register_static()
4966 * The type system will perform a deep copy of this structure, so its memory
4967 * does not need to be persistent across invocation of
4968 * g_param_type_register_static().
4974 * @parent_instance: private #GParamSpec portion
4975 * @minimum: minimum value for the property specified
4976 * @maximum: maximum value for the property specified
4977 * @default_value: default value for the property specified
4979 * A #GParamSpec derived structure that contains the meta data for unsigned character properties.
4985 * @parent_instance: private #GParamSpec portion
4986 * @minimum: minimum value for the property specified
4987 * @maximum: maximum value for the property specified
4988 * @default_value: default value for the property specified
4990 * A #GParamSpec derived structure that contains the meta data for unsigned integer properties.
4996 * @parent_instance: private #GParamSpec portion
4997 * @minimum: minimum value for the property specified
4998 * @maximum: maximum value for the property specified
4999 * @default_value: default value for the property specified
5001 * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties.
5007 * @parent_instance: private #GParamSpec portion
5008 * @minimum: minimum value for the property specified
5009 * @maximum: maximum value for the property specified
5010 * @default_value: default value for the property specified
5012 * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties.
5017 * GParamSpecUnichar:
5018 * @parent_instance: private #GParamSpec portion
5019 * @default_value: default value for the property specified
5021 * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties.
5026 * GParamSpecValueArray:
5027 * @parent_instance: private #GParamSpec portion
5028 * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL
5029 * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements
5031 * A #GParamSpec derived structure that contains the meta data for #GValueArray properties.
5036 * GParamSpecVariant:
5037 * @parent_instance: private #GParamSpec portion
5038 * @type: a #GVariantType, or %NULL
5039 * @default_value: a #GVariant, or %NULL
5041 * A #GParamSpec derived structure that contains the meta data for #GVariant properties.
5049 * @name: the parameter name
5050 * @value: the parameter value
5052 * The <structname>GParameter</structname> struct is an auxiliary structure used
5053 * to hand parameter name/value pairs to g_object_newv().
5059 * @G_PASSWORD_SAVE_NEVER: never save a password.
5060 * @G_PASSWORD_SAVE_FOR_SESSION: save a password for the session.
5061 * @G_PASSWORD_SAVE_PERMANENTLY: save a password permanently.
5063 * #GPasswordSave is used to indicate the lifespan of a saved password.
5065 * #Gvfs stores passwords in the Gnome keyring when this flag allows it
5066 * to, and later retrieves it again from there.
5073 * #GPermission is an opaque data structure and can only be accessed
5074 * using the following functions.
5079 * GPermission:allowed:
5081 * %TRUE if the caller currently has permission to perform the action that
5082 * @permission represents the permission to perform.
5087 * GPermission:can-acquire:
5089 * %TRUE if it is generally possible to acquire the permission by calling
5090 * g_permission_acquire().
5095 * GPermission:can-release:
5097 * %TRUE if it is generally possible to release the permission by calling
5098 * g_permission_release().
5105 * A type which is used to hold a process identification.
5107 * On UNIX, processes are identified by a process id (an integer),
5108 * while Windows uses process handles (which are pointers).
5110 * GPid is used in GLib only for descendant processes spawned with
5111 * the g_spawn functions.
5117 * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32)
5118 * @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.
5119 * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred.
5121 * Represents a file descriptor, which events to poll for, and which events
5128 * @ufds: an array of #GPollFD elements
5129 * @nfsd: the number of elements in @ufds
5130 * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout.
5132 * Specifies the type of function passed to g_main_context_set_poll_func().
5133 * The semantics of the function should match those of the poll() system call.
5135 * reported, or -1 if an error occurred.
5137 * Returns: the number of #GPollFD elements which have events or errors
5142 * GPollableInputStream:
5144 * An interface for a #GInputStream that can be polled for readability.
5151 * GPollableInputStreamInterface:
5152 * @g_iface: The parent interface.
5153 * @can_poll: Checks if the #GPollableInputStream instance is actually pollable
5154 * @is_readable: Checks if the stream is readable
5155 * @create_source: Creates a #GSource to poll the stream
5156 * @read_nonblocking: Does a non-blocking read or returns %G_IO_ERROR_WOULD_BLOCK
5158 * The interface for pollable input streams.
5160 * The default implementation of @can_poll always returns %TRUE.
5162 * The default implementation of @read_nonblocking calls
5163 * g_pollable_input_stream_is_readable(), and then calls
5164 * g_input_stream_read() if it returns %TRUE. This means you only need
5165 * to override it if it is possible that your @is_readable
5166 * implementation may return %TRUE when the stream is not actually
5174 * GPollableOutputStream:
5176 * An interface for a #GOutputStream that can be polled for readability.
5183 * GPollableOutputStreamInterface:
5184 * @g_iface: The parent interface.
5185 * @can_poll: Checks if the #GPollableOutputStream instance is actually pollable
5186 * @is_writable: Checks if the stream is writable
5187 * @create_source: Creates a #GSource to poll the stream
5188 * @write_nonblocking: Does a non-blocking write or returns %G_IO_ERROR_WOULD_BLOCK
5190 * The interface for pollable output streams.
5192 * The default implementation of @can_poll always returns %TRUE.
5194 * The default implementation of @write_nonblocking calls
5195 * g_pollable_output_stream_is_writable(), and then calls
5196 * g_output_stream_write() if it returns %TRUE. This means you only
5197 * need to override it if it is possible that your @is_writable
5198 * implementation may return %TRUE when the stream is not actually
5206 * GPollableSourceFunc:
5207 * @pollable_stream: the #GPollableInputStream or #GPollableOutputStream
5208 * @user_data: data passed in by the user.
5210 * This is the function type of the callback used for the #GSource
5211 * returned by g_pollable_input_stream_create_source() and
5212 * g_pollable_output_stream_create_source().
5214 * Returns: it should return %FALSE if the source should be removed.
5221 * @string: the message to output
5223 * Specifies the type of the print handler functions.
5224 * These are called with the complete formatted string to output.
5231 * Interface that handles proxy connection and payload.
5240 * A #GInetSocketAddress representing a connection via a proxy server
5247 * GProxyAddressEnumerator:
5249 * A subclass of #GSocketAddressEnumerator that takes another address
5250 * enumerator and wraps its results in #GProxyAddress<!-- -->es as
5251 * directed by the default #GProxyResolver.
5257 * @g_iface: The parent interface.
5258 * @connect: Connect to proxy server and wrap (if required) the #connection to handle payload.
5259 * @connect_async: Same as connect() but asynchronous.
5260 * @connect_finish: Returns the result of connect_async()
5261 * @supports_hostname: Returns whether the proxy supports hostname lookups.
5263 * Provides an interface for handling proxy connection and payload.
5272 * Interface that can be used to resolve proxy address.
5278 * @head: a pointer to the first element of the queue
5279 * @tail: a pointer to the last element of the queue
5280 * @length: the number of elements in the queue
5282 * Contains the public fields of a
5283 * <link linkend="glib-Double-ended-Queues">Queue</link>.
5289 * @data: memory block to reallocate
5290 * @size: size to reallocate @data to
5292 * Changes the size of the memory block pointed to by @data to
5295 * The function should have the same semantics as realloc().
5297 * Returns: a pointer to the reallocated memory
5304 * A GRegex is the "compiled" form of a regular expression pattern. This
5305 * structure is opaque and its fields cannot be accessed directly.
5312 * GRegexCompileFlags:
5313 * @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.
5314 * @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.
5315 * @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.
5316 * @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.
5317 * @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.
5318 * @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.
5319 * @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.
5320 * @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).
5321 * @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.
5322 * @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.
5323 * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
5324 * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'.
5325 * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'.
5327 * Flags specifying compile-time options.
5335 * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed.
5336 * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed.
5337 * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string.
5338 * @G_REGEX_ERROR_MATCH: The match process failed.
5339 * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16
5340 * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16
5341 * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16
5342 * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16
5343 * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16
5344 * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16
5345 * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16
5346 * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16
5347 * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16
5348 * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16
5349 * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16
5350 * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16
5351 * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16
5352 * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16
5353 * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16
5354 * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16
5355 * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16
5356 * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16
5357 * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16
5358 * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16
5359 * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16
5360 * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16
5361 * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16
5362 * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16
5363 * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16
5364 * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16
5365 * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16
5366 * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16
5367 * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16
5368 * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16
5369 * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16
5370 * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16
5371 * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16
5372 * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16
5373 * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16
5374 * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16
5375 * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16
5376 * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16
5378 * Error codes returned by regular expressions functions.
5385 * GRegexEvalCallback:
5386 * @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.
5387 * @result: a #GString containing the new string
5388 * @user_data: user data passed to g_regex_replace_eval()
5390 * Specifies the type of the function passed to g_regex_replace_eval().
5391 * It is called for each occurrence of the pattern in the string passed
5392 * to g_regex_replace_eval(), and it should append the replacement to
5395 * Returns: %FALSE to continue the replacement process, %TRUE to stop it
5402 * @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.
5403 * @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".
5404 * @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".
5405 * @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".
5406 * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match().
5407 * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator.
5408 * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator.
5409 * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator.
5410 * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized.
5412 * Flags specifying match-time options.
5419 * GRemoteActionGroupInterface:
5420 * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()
5421 * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full()
5423 * The virtual function table for #GRemoteActionGroup.
5432 * The object that handles DNS resolution. Use g_resolver_get_default()
5433 * to get the default resolver.
5438 * GResolver::reload:
5439 * @resolver: a #GResolver
5441 * Emitted when the resolver notices that the system resolver
5442 * configuration has changed.
5448 * @G_RESOLVER_ERROR_NOT_FOUND: the requested name/address/service was not found
5449 * @G_RESOLVER_ERROR_TEMPORARY_FAILURE: the requested information could not be looked up due to a network error or similar problem
5450 * @G_RESOLVER_ERROR_INTERNAL: unknown error
5452 * An error code used with %G_RESOLVER_ERROR in a #GError returned
5453 * from a #GResolver routine.
5462 * A resource bundle.
5470 * @G_RESOURCE_ERROR_NOT_FOUND: no file was found at the requested path
5471 * @G_RESOURCE_ERROR_INTERNAL: unknown error
5473 * An error code used with %G_RESOURCE_ERROR in a #GError returned
5474 * from a #GResource routine.
5482 * @G_RESOURCE_FLAGS_NONE: No flags set.
5483 * @G_RESOURCE_FLAGS_COMPRESSED: The file is compressed.
5485 * GResourceFlags give information about a particular file inside a resource
5493 * GResourceLookupFlags:
5494 * @G_RESOURCE_LOOKUP_FLAGS_NONE: No flags set.
5496 * GResourceLookupFlags determine how resource path lookups are handled.
5505 * Seek object for streaming operations.
5511 * @g_iface: The parent interface.
5512 * @tell: Tells the current location within a stream.
5513 * @can_seek: Checks if seeking is supported by the stream.
5514 * @seek: Seeks to a location within a stream.
5515 * @can_truncate: Checks if truncation is supported by the stream.
5516 * @truncate_fn: Truncates a stream.
5518 * Provides an interface for implementing seekable functionality on I/O Streams.
5523 * GSettings::change-event:
5524 * @settings: the object on which the signal was emitted
5525 * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL
5526 * @n_keys: the length of the @keys array, or 0
5528 * The "change-event" signal is emitted once per change event that
5529 * affects this settings object. You should connect to this signal
5530 * only if you are interested in viewing groups of changes before they
5531 * are split out into multiple emissions of the "changed" signal.
5532 * For most use cases it is more appropriate to use the "changed" signal.
5534 * In the event that the change event applies to one or more specified
5535 * keys, @keys will be an array of #GQuark of length @n_keys. In the
5536 * event that the change event applies to the #GSettings object as a
5537 * whole (ie: potentially every key has been changed) then @keys will
5538 * be %NULL and @n_keys will be 0.
5540 * The default handler for this signal invokes the "changed" signal
5541 * for each affected key. If any other connected handler returns
5542 * %TRUE then this default functionality will be suppressed.
5544 * event. FALSE to propagate the event further.
5546 * Returns: %TRUE to stop other handlers from being invoked for the
5551 * GSettings::changed:
5552 * @settings: the object on which the signal was emitted
5553 * @key: the name of the key that changed
5555 * The "changed" signal is emitted when a key has potentially changed.
5556 * You should call one of the g_settings_get() calls to check the new
5559 * This signal supports detailed connections. You can connect to the
5560 * detailed signal "changed::x" in order to only receive callbacks
5561 * when key "x" changes.
5566 * GSettings::writable-change-event:
5567 * @settings: the object on which the signal was emitted
5568 * @key: the quark of the key, or 0
5570 * The "writable-change-event" signal is emitted once per writability
5571 * change event that affects this settings object. You should connect
5572 * to this signal if you are interested in viewing groups of changes
5573 * before they are split out into multiple emissions of the
5574 * "writable-changed" signal. For most use cases it is more
5575 * appropriate to use the "writable-changed" signal.
5577 * In the event that the writability change applies only to a single
5578 * key, @key will be set to the #GQuark for that key. In the event
5579 * that the writability change affects the entire settings object,
5582 * The default handler for this signal invokes the "writable-changed"
5583 * and "changed" signals for each affected key. This is done because
5584 * changes in writability might also imply changes in value (if for
5585 * example, a new mandatory setting is introduced). If any other
5586 * connected handler returns %TRUE then this default functionality
5587 * will be suppressed.
5589 * event. FALSE to propagate the event further.
5591 * Returns: %TRUE to stop other handlers from being invoked for the
5596 * GSettings::writable-changed:
5597 * @settings: the object on which the signal was emitted
5600 * The "writable-changed" signal is emitted when the writability of a
5601 * key has potentially changed. You should call
5602 * g_settings_is_writable() in order to determine the new status.
5604 * This signal supports detailed connections. You can connect to the
5605 * detailed signal "writable-changed::x" in order to only receive
5606 * callbacks when the writability of "x" changes.
5611 * GSettings:context:
5613 * The name of the context that the settings are stored in.
5618 * GSettings:delay-apply:
5620 * Whether the #GSettings object is in 'delay-apply' mode. See
5621 * g_settings_delay() for details.
5628 * GSettings:has-unapplied:
5630 * If this property is %TRUE, the #GSettings object has outstanding
5631 * changes that will be applied when g_settings_apply() is called.
5638 * The path within the backend where the settings are stored.
5645 * The name of the schema that describes the types of keys
5646 * for this #GSettings object.
5648 * The type of this property is *not* #GSettingsSchema.
5649 * #GSettingsSchema has only existed since version 2.32 and
5650 * unfortunately this name was used in previous versions to refer to
5651 * the schema ID rather than the schema itself. Take care to use the
5652 * 'settings-schema' property if you wish to pass in a
5655 * Deprecated:2.32:Use the 'schema-id' property instead. In a future
5656 * version, this property may instead refer to a #GSettingsSchema.
5661 * GSettings:schema-id:
5663 * The name of the schema that describes the types of keys
5664 * for this #GSettings object.
5669 * GSettings:settings-schema:
5671 * The #GSettingsSchema describing the types of keys for this
5672 * #GSettings object.
5674 * Ideally, this property would be called 'schema'. #GSettingsSchema
5675 * has only existed since version 2.32, however, and before then the
5676 * 'schema' property was used to refer to the ID of the schema rather
5677 * than the schema itself. Take care.
5684 * An implementation of a settings storage repository.
5689 * GSettingsBindFlags:
5690 * @G_SETTINGS_BIND_DEFAULT: Equivalent to <literal>G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET</literal>
5691 * @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.
5692 * @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.
5693 * @G_SETTINGS_BIND_NO_SENSITIVITY: Do not try to bind a "sensitivity" property to the writability of the setting
5694 * @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
5695 * @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 cannot pass this flag to g_settings_bind_with_mapping().
5697 * Flags used when creating a binding. These flags determine in which
5698 * direction the binding works. The default is to synchronize in both
5704 * GSettingsBindGetMapping:
5705 * @value: return location for the property value
5706 * @variant: the #GVariant
5707 * @user_data: user data that was specified when the binding was created
5709 * The type for the function that is used to convert from #GSettings to
5710 * an object property. The @value is already initialized to hold values
5711 * of the appropriate type.
5713 * Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
5718 * GSettingsBindSetMapping:
5719 * @value: a #GValue containing the property value to map
5720 * @expected_type: the #GVariantType to create
5721 * @user_data: user data that was specified when the binding was created
5723 * The type for the function that is used to convert an object property
5724 * value to a #GVariant for storing it in #GSettings.
5726 * or %NULL in case of an error
5728 * Returns: a new #GVariant holding the data from @value,
5733 * GSettingsGetMapping:
5734 * @value: the #GVariant to map, or %NULL
5735 * @result: (out): the result of the mapping
5736 * @user_data: (closure): the user data that was passed to g_settings_get_mapped()
5738 * The type of the function that is used to convert from a value stored
5739 * in a #GSettings to a value that is useful to the application.
5741 * If the value is successfully mapped, the result should be stored at
5742 * @result and %TRUE returned. If mapping fails (for example, if @value
5743 * is not in the right format) then %FALSE should be returned.
5745 * If @value is %NULL then it means that the mapping function is being
5746 * given a "last chance" to successfully return a valid value. %TRUE
5747 * must be returned in this case.
5749 * Returns: %TRUE if the conversion succeeded, %FALSE in case of an error
5756 * This is an opaque structure type. You may not access it directly.
5763 * GSettingsSchemaSource:
5765 * This is an opaque structure type. You may not access it directly.
5772 * GSignalAccumulator:
5773 * @ihint: Signal invocation hint, see #GSignalInvocationHint.
5774 * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission.
5775 * @handler_return: A #GValue holding the return value of the signal handler.
5776 * @data: Callback data that was specified when creating the signal.
5778 * The signal accumulator is a special callback function that can be used
5779 * to collect return values of the various callbacks that are called
5780 * during a signal emission. The signal accumulator is specified at signal
5781 * creation time, if it is left %NULL, no accumulation of callback return
5782 * values is performed. The return value of signal emissions is then the
5783 * value returned by the last callback.
5785 * should be aborted. Returning %FALSE means to abort the
5786 * current emission and %TRUE is returned for continuation.
5788 * Returns: The accumulator function returns whether the signal emission
5793 * GSignalCMarshaller:
5795 * This is the signature of marshaller functions, required to marshall
5796 * arrays of parameter values to signal emissions into C language callback
5797 * invocations. It is merely an alias to #GClosureMarshal since the #GClosure
5798 * mechanism takes over responsibility of actual function invocation for the
5804 * GSignalCVaMarshaller:
5806 * This is the signature of va_list marshaller functions, an optional
5807 * marshaller that can be used in some situations to avoid
5808 * marshalling the signal argument into GValues.
5813 * GSignalEmissionHook:
5814 * @ihint: Signal invocation hint, see #GSignalInvocationHint.
5815 * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted.
5816 * @param_values: (array length=n_param_values): the instance on which the signal was emitted, followed by the parameters of the emission.
5817 * @data: user data associated with the hook.
5819 * A simple function pointer to get invoked when the signal is emitted. This
5820 * allows you to tie a hook to the signal type, so that it will trap all
5821 * emissions of that signal, from any object.
5823 * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
5825 * hook is disconnected (and destroyed).
5827 * Returns: whether it wants to stay connected. If it returns %FALSE, the signal
5833 * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage.
5834 * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage.
5835 * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage.
5836 * @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.
5837 * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions.
5838 * @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.
5839 * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal.
5840 * @G_SIGNAL_MUST_COLLECT: Varargs signal emission will always collect the arguments, even if there are no signal handlers connected. Since 2.30.
5841 * @G_SIGNAL_DEPRECATED: The signal is deprecated and will be removed in a future version. A warning will be generated if it is connected while running with G_ENABLE_DIAGNOSTIC=1. Since 2.32.
5843 * The signal flags are used to specify a signal's behaviour, the overall
5844 * signal description outlines how especially the RUN flags control the
5845 * stages of a signal emission.
5850 * GSignalInvocationHint:
5851 * @signal_id: The signal id of the signal invoking the callback
5852 * @detail: The detail passed on for this emission
5853 * @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.
5855 * The #GSignalInvocationHint structure is used to pass on additional information
5856 * to callbacks during a signal emission.
5862 * @G_SIGNAL_MATCH_ID: The signal id must be equal.
5863 * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal.
5864 * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
5865 * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
5866 * @G_SIGNAL_MATCH_DATA: The closure data must be the same.
5867 * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched.
5869 * The match types specify what g_signal_handlers_block_matched(),
5870 * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
5877 * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown.
5878 * @signal_name: The signal name.
5879 * @itype: The interface/instance type that this signal can be emitted for.
5880 * @signal_flags: The signal flags as passed in to g_signal_new().
5881 * @return_type: The return type for user callbacks.
5882 * @n_params: The number of parameters that user callbacks take.
5883 * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> @return_type callback (#gpointer data1, [param_types param_names,] gpointer data2); </programlisting>
5885 * A structure holding in-depth information for a specific signal. It is
5886 * filled in by the g_signal_query() function.
5891 * GSimpleAction::activate:
5892 * @simple: the #GSimpleAction
5893 * @parameter: (allow-none): the parameter to the activation
5895 * Indicates that the action was just activated.
5897 * @parameter will always be of the expected type. In the event that
5898 * an incorrect type was given, no signal will be emitted.
5905 * GSimpleAction::change-state:
5906 * @simple: the #GSimpleAction
5907 * @value: (allow-none): the requested value for the state
5909 * Indicates that the action just received a request to change its
5912 * @value will always be of the correct state type. In the event that
5913 * an incorrect type was given, no signal will be emitted.
5915 * If no handler is connected to this signal then the default
5916 * behaviour is to call g_simple_action_set_state() to set the state
5917 * to the requested value. If you connect a signal handler then no
5918 * default action is taken. If the state should change then you must
5919 * call g_simple_action_set_state() from the handler.
5922 * <title>Example 'change-state' handler</title>
5925 * change_volume_state (GSimpleAction *action,
5927 * gpointer user_data)
5931 * requested = g_variant_get_int32 (value);
5933 * // Volume only goes from 0 to 10
5934 * if (0 <= requested && requested <= 10)
5935 * g_simple_action_set_state (action, value);
5940 * The handler need not set the state to the requested value. It
5941 * could set it to any value at all, or take some other action.
5948 * GSimpleAction:enabled:
5950 * If @action is currently enabled.
5952 * If the action is disabled then calls to g_action_activate() and
5953 * g_action_change_state() have no effect.
5960 * GSimpleAction:name:
5962 * The name of the action. This is mostly meaningful for identifying
5963 * the action once it has been added to a #GSimpleActionGroup.
5970 * GSimpleAction:parameter-type:
5972 * The type of the parameter that must be given when activating the
5980 * GSimpleAction:state:
5982 * The state of the action, or %NULL if the action is stateless.
5989 * GSimpleAction:state-type:
5991 * The #GVariantType of the state that the action has, or %NULL if the
5992 * action is stateless.
5999 * GSimpleActionGroup:
6001 * The #GSimpleActionGroup structure contains private data and should only be accessed using the provided API.
6008 * GSimpleAsyncResult:
6010 * A simple implementation of #GAsyncResult.
6015 * GSimpleAsyncThreadFunc:
6016 * @res: a #GSimpleAsyncResult.
6017 * @object: a #GObject.
6018 * @cancellable: optional #GCancellable object, %NULL to ignore.
6020 * Simple thread function that runs an asynchronous operation and
6021 * checks for cancellation.
6026 * GSimplePermission:
6028 * #GSimplePermission is an opaque data structure. There are no methods
6029 * except for those defined by #GPermission.
6036 * A lowlevel network socket object.
6043 * GSocket:broadcast:
6045 * Whether the socket should allow sending to and receiving from broadcast addresses.
6052 * GSocket:multicast-loopback:
6054 * Whether outgoing multicast packets loop back to the local host.
6061 * GSocket:multicast-ttl:
6063 * Time-to-live out outgoing multicast packets
6072 * The timeout in seconds on socket I/O
6081 * Time-to-live for outgoing unicast packets
6090 * A socket endpoint address, corresponding to <type>struct sockaddr</type>
6091 * or one of its subtypes.
6096 * GSocketAddressEnumerator:
6098 * Enumerator type for objects that contain or generate
6099 * #GSocketAddress<!-- -->es.
6106 * A helper class for network servers to listen for and accept connections.
6113 * GSocketClient::event:
6114 * @client: the #GSocketClient
6115 * @event: the event that is occurring
6116 * @connectable: the #GSocketConnectable that @event is occurring on
6117 * @connection: the current representation of the connection
6119 * Emitted when @client's activity on @connectable changes state.
6120 * Among other things, this can be used to provide progress
6121 * information about a network connection in the UI. The meanings of
6122 * the different @event values are as follows:
6126 * <term>%G_SOCKET_CLIENT_RESOLVING:</term>
6128 * @client is about to look up @connectable in DNS.
6129 * @connection will be %NULL.
6130 * </para></listitem>
6133 * <term>%G_SOCKET_CLIENT_RESOLVED:</term>
6135 * @client has successfully resolved @connectable in DNS.
6136 * @connection will be %NULL.
6137 * </para></listitem>
6140 * <term>%G_SOCKET_CLIENT_CONNECTING:</term>
6142 * @client is about to make a connection to a remote host;
6143 * either a proxy server or the destination server itself.
6144 * @connection is the #GSocketConnection, which is not yet
6146 * </para></listitem>
6149 * <term>%G_SOCKET_CLIENT_CONNECTED:</term>
6151 * @client has successfully connected to a remote host.
6152 * @connection is the connected #GSocketConnection.
6153 * </para></listitem>
6156 * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATING:</term>
6158 * @client is about to negotiate with a proxy to get it to
6159 * connect to @connectable. @connection is the
6160 * #GSocketConnection to the proxy server.
6161 * </para></listitem>
6164 * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATED:</term>
6166 * @client has negotiated a connection to @connectable through
6167 * a proxy server. @connection is the stream returned from
6168 * g_proxy_connect(), which may or may not be a
6169 * #GSocketConnection.
6170 * </para></listitem>
6173 * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKING:</term>
6175 * @client is about to begin a TLS handshake. @connection is a
6176 * #GTlsClientConnection.
6177 * </para></listitem>
6180 * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKED:</term>
6182 * @client has successfully completed the TLS handshake.
6183 * @connection is a #GTlsClientConnection.
6184 * </para></listitem>
6187 * <term>%G_SOCKET_CLIENT_COMPLETE:</term>
6189 * @client has either successfully connected to @connectable
6190 * (in which case @connection is the #GSocketConnection that
6191 * it will be returning to the caller) or has failed (in which
6192 * case @connection is %NULL and the client is about to return
6194 * </para></listitem>
6198 * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
6199 * multiple times (or not at all) for a given connectable (in
6200 * particular, if @client ends up attempting to connect to more than
6201 * one address). However, if @client emits the #GSocketClient::event
6202 * signal at all for a given connectable, that it will always emit
6203 * it with %G_SOCKET_CLIENT_COMPLETE when it is done.
6205 * Note that there may be additional #GSocketClientEvent values in
6206 * the future; unrecognized @event values should be ignored.
6213 * GSocketClientEvent:
6214 * @G_SOCKET_CLIENT_RESOLVING: The client is doing a DNS lookup.
6215 * @G_SOCKET_CLIENT_RESOLVED: The client has completed a DNS lookup.
6216 * @G_SOCKET_CLIENT_CONNECTING: The client is connecting to a remote host (either a proxy or the destination server).
6217 * @G_SOCKET_CLIENT_CONNECTED: The client has connected to a remote host.
6218 * @G_SOCKET_CLIENT_PROXY_NEGOTIATING: The client is negotiating with a proxy to connect to the destination server.
6219 * @G_SOCKET_CLIENT_PROXY_NEGOTIATED: The client has negotiated with the proxy server.
6220 * @G_SOCKET_CLIENT_TLS_HANDSHAKING: The client is performing a TLS handshake.
6221 * @G_SOCKET_CLIENT_TLS_HANDSHAKED: The client has performed a TLS handshake.
6222 * @G_SOCKET_CLIENT_COMPLETE: The client is done with a particular #GSocketConnectable.
6224 * Describes an event occurring on a #GSocketClient. See the
6225 * #GSocketClient::event signal for more details.
6227 * Additional values may be added to this type in the future.
6234 * GSocketConnectable:
6236 * Interface for objects that contain or generate #GSocketAddress<!-- -->es.
6241 * GSocketConnectableIface:
6242 * @g_iface: The parent interface.
6243 * @enumerate: Creates a #GSocketAddressEnumerator
6244 * @proxy_enumerate: Creates a #GProxyAddressEnumerator
6246 * Provides an interface for returning a #GSocketAddressEnumerator
6247 * and #GProxyAddressEnumerator
6252 * GSocketConnection:
6254 * A socket connection GIOStream object for connection-oriented sockets.
6261 * GSocketControlMessage:
6263 * Base class for socket-type specific control messages that can be sent and
6264 * received over #GSocket.
6269 * GSocketControlMessageClass:
6270 * @get_size: gets the size of the message.
6271 * @get_level: gets the protocol of the message.
6272 * @get_type: gets the protocol specific type of the message.
6273 * @serialize: Writes out the message data.
6274 * @deserialize: Tries to deserialize a message.
6282 * @G_SOCKET_FAMILY_INVALID: no address family
6283 * @G_SOCKET_FAMILY_IPV4: the IPv4 family
6284 * @G_SOCKET_FAMILY_IPV6: the IPv6 family
6285 * @G_SOCKET_FAMILY_UNIX: the UNIX domain family
6287 * The protocol family of a #GSocketAddress. (These values are
6288 * identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX,
6296 * GSocketListenerClass:
6297 * @changed: virtual method called when the set of socket listened to changes
6305 * @G_SOCKET_MSG_NONE: No flags.
6306 * @G_SOCKET_MSG_OOB: Request to send/receive out of band data.
6307 * @G_SOCKET_MSG_PEEK: Read data from the socket without removing it from the queue.
6308 * @G_SOCKET_MSG_DONTROUTE: Don't use a gateway to send out the packet, only send to hosts on directly connected networks.
6310 * Flags used in g_socket_receive_message() and g_socket_send_message().
6311 * The flags listed in the enum are some commonly available flags, but the
6312 * values used for them are the same as on the platform, and any other flags
6313 * are passed in/out as is. So to use a platform specific flag, just include
6314 * the right system header and pass in the flag.
6322 * @G_SOCKET_PROTOCOL_UNKNOWN: The protocol type is unknown
6323 * @G_SOCKET_PROTOCOL_DEFAULT: The default protocol for the family/type
6324 * @G_SOCKET_PROTOCOL_TCP: TCP over IP
6325 * @G_SOCKET_PROTOCOL_UDP: UDP over IP
6326 * @G_SOCKET_PROTOCOL_SCTP: SCTP over IP
6328 * A protocol identifier is specified when creating a #GSocket, which is a
6329 * family/type specific identifier, where 0 means the default protocol for
6330 * the particular family/type.
6332 * This enum contains a set of commonly available and used protocols. You
6333 * can also pass any other identifiers handled by the platform in order to
6334 * use protocols not listed here.
6343 * A helper class for handling accepting incomming connections in the
6351 * GSocketService::incoming:
6352 * @service: the #GSocketService
6353 * @connection: a new #GSocketConnection object
6354 * @source_object: (allow-none): the source_object passed to g_socket_listener_add_address()
6356 * The ::incoming signal is emitted when a new incoming connection
6357 * to @service needs to be handled. The handler must initiate the
6358 * handling of @connection, but may not block; in essence,
6359 * asynchronous operations must be used.
6361 * @connection will be unreffed once the signal handler returns,
6362 * so you need to ref it yourself if you are planning to use it.
6364 * Returns: %TRUE to stop other handlers from being called
6370 * GSocketServiceClass:
6371 * @incomming: signal emitted when new connections are accepted
6378 * GSocketSourceFunc:
6379 * @socket: the #GSocket
6380 * @condition: the current condition at the source fired.
6381 * @user_data: data passed in by the user.
6383 * This is the function type of the callback used for the #GSource
6384 * returned by g_socket_create_source().
6386 * Returns: it should return %FALSE if the source should be removed.
6393 * @G_SOCKET_TYPE_INVALID: Type unknown or wrong
6394 * @G_SOCKET_TYPE_STREAM: Reliable connection-based byte streams (e.g. TCP).
6395 * @G_SOCKET_TYPE_DATAGRAM: Connectionless, unreliable datagram passing. (e.g. UDP)
6396 * @G_SOCKET_TYPE_SEQPACKET: Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP).
6398 * Flags used when creating a #GSocket. Some protocols may not implement
6399 * all the socket types.
6408 * The <structname>GSource</structname> struct is an opaque data type
6409 * representing an event source.
6414 * GSourceCallbackFuncs:
6415 * @ref: Called when a reference is added to the callback object
6416 * @unref: Called when a reference to the callback object is dropped
6417 * @get: Called to extract the callback function and data from the callback object. The <structname>GSourceCallbackFuncs</structname> struct contains functions for managing callback objects.
6424 * GSourceDummyMarshal:
6426 * This is just a placeholder for #GClosureMarshal,
6427 * which cannot be used here for dependency reasons.
6433 * @user_data: data passed to the function, set when the source was created with one of the above functions
6435 * Specifies the type of function passed to g_timeout_add(),
6436 * g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
6438 * Returns: %FALSE if the source should be removed
6444 * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the @timeout_ values returned which were >= 0.
6445 * @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.
6446 * @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.
6447 * @finalize: Called when the source is finalized.
6449 * The <structname>GSourceFuncs</structname> struct contains a table of
6450 * functions used to handle event sources in a generic manner.
6452 * For idle sources, the prepare and check functions always return %TRUE
6453 * to indicate that the source is always ready to be processed. The prepare
6454 * function also returns a timeout value of 0 to ensure that the poll() call
6455 * doesn't block (since that would be time wasted which could have been spent
6456 * running the idle function).
6458 * For timeout sources, the prepare and check functions both return %TRUE
6459 * if the timeout interval has expired. The prepare function also returns
6460 * a timeout value to ensure that the poll() call doesn't block too long
6461 * and miss the next timeout.
6463 * For file descriptor sources, the prepare function typically returns %FALSE,
6464 * since it must wait until poll() has been called before it knows whether
6465 * any events need to be processed. It sets the returned timeout to -1 to
6466 * indicate that it doesn't mind how long the poll() call blocks. In the
6467 * check function, it tests the results of the poll() call to see if the
6468 * required condition has been met, and returns %TRUE if so.
6473 * GSpawnChildSetupFunc:
6474 * @user_data: user data to pass to the function.
6476 * Specifies the type of the setup function passed to g_spawn_async(),
6477 * g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very
6478 * limited ways, be used to affect the child's execution.
6480 * On POSIX platforms, the function is called in the child after GLib
6481 * has performed all the setup it plans to perform, but before calling
6482 * exec(). Actions taken in this function will only affect the child,
6485 * On Windows, the function is called in the parent. Its usefulness on
6486 * Windows is thus questionable. In many cases executing the child setup
6487 * function in the parent can have ill effects, and you should be very
6488 * careful when porting software to Windows that uses child setup
6491 * However, even on POSIX, you are extremely limited in what you can
6492 * safely do from a #GSpawnChildSetupFunc, because any mutexes that
6493 * were held by other threads in the parent process at the time of the
6494 * fork() will still be locked in the child process, and they will
6495 * never be unlocked (since the threads that held them don't exist in
6496 * the child). POSIX allows only async-signal-safe functions (see
6497 * <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
6498 * to be called in the child between fork() and exec(), which
6499 * drastically limits the usefulness of child setup functions.
6501 * In particular, it is not safe to call any function which may
6502 * call malloc(), which includes POSIX functions such as setenv().
6503 * If you need to set up the child environment differently from
6504 * the parent, you should use g_get_environ(), g_environ_setenv(),
6505 * and g_environ_unsetenv(), and then pass the complete environment
6506 * list to the <literal>g_spawn...</literal> function.
6512 * @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
6513 * @G_SPAWN_ERROR_READ: Read or select on pipes failed.
6514 * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
6515 * @G_SPAWN_ERROR_ACCES: execv() returned <literal>EACCES</literal>
6516 * @G_SPAWN_ERROR_PERM: execv() returned <literal>EPERM</literal>
6517 * @G_SPAWN_ERROR_TOO_BIG: execv() returned <literal>E2BIG</literal>
6518 * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG
6519 * @G_SPAWN_ERROR_NOEXEC: execv() returned <literal>ENOEXEC</literal>
6520 * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned <literal>ENAMETOOLONG</literal>
6521 * @G_SPAWN_ERROR_NOENT: execv() returned <literal>ENOENT</literal>
6522 * @G_SPAWN_ERROR_NOMEM: execv() returned <literal>ENOMEM</literal>
6523 * @G_SPAWN_ERROR_NOTDIR: execv() returned <literal>ENOTDIR</literal>
6524 * @G_SPAWN_ERROR_LOOP: execv() returned <literal>ELOOP</literal>
6525 * @G_SPAWN_ERROR_TXTBUSY: execv() returned <literal>ETXTBUSY</literal>
6526 * @G_SPAWN_ERROR_IO: execv() returned <literal>EIO</literal>
6527 * @G_SPAWN_ERROR_NFILE: execv() returned <literal>ENFILE</literal>
6528 * @G_SPAWN_ERROR_MFILE: execv() returned <literal>EMFILE</literal>
6529 * @G_SPAWN_ERROR_INVAL: execv() returned <literal>EINVAL</literal>
6530 * @G_SPAWN_ERROR_ISDIR: execv() returned <literal>EISDIR</literal>
6531 * @G_SPAWN_ERROR_LIBBAD: execv() returned <literal>ELIBBAD</literal>
6532 * @G_SPAWN_ERROR_FAILED: Some other fatal failure, <literal>error->message</literal> should explain.
6534 * Error codes returned by spawning processes.
6540 * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will be inherited by the child; otherwise all descriptors except stdin/stdout/stderr will be closed before calling exec() in the child.
6541 * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you must use g_child_watch_add() yourself (or call waitpid() or handle <literal>SIGCHLD</literal> yourself), or the child will become a zombie.
6542 * @G_SPAWN_SEARCH_PATH: <literal>argv[0]</literal> need not be an absolute path, it will be looked for in the user's <envar>PATH</envar>.
6543 * @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded, instead of going to the same location as the parent's standard output.
6544 * @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded.
6545 * @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard input (by default, the child's standard input is attached to <filename>/dev/null</filename>).
6546 * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of <literal>argv</literal> is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally g_spawn_async_with_pipes() uses <literal>argv[0]</literal> as the file to execute, and passes all of <literal>argv</literal> to the child.
6548 * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
6555 * A single target host/port that a network service is running on.
6562 * A C representable type name for #G_TYPE_STRV.
6569 * A #GSocketConnection for UNIX domain socket connections.
6576 * GTestLogFatalFunc:
6577 * @log_domain: the log domain of the message
6578 * @log_level: the log level of the message (including the fatal and recursion flags)
6579 * @message: the message to process
6580 * @user_data: user data, set in g_test_log_set_fatal_handler()
6582 * Specifies the prototype of fatal log handler functions.
6584 * Returns: %TRUE if the program should abort, %FALSE otherwise
6592 * An implementation of #GIcon for themed icons.
6604 * GThemedIcon:names:
6606 * A %NULL-terminated array of icon names.
6611 * GThemedIcon:use-default-fallbacks:
6613 * Whether to use the default fallbacks found by shortening the icon name
6614 * at '-' characters. If the "names" array has more than one element,
6615 * ignores any past the first.
6617 * For example, if the icon name was "gnome-dev-cdrom-audio", the array
6621 * "gnome-dev-cdrom-audio",
6622 * "gnome-dev-cdrom",
6632 * GThreadedSocketService:
6634 * A helper class for handling accepting incoming connections in the
6635 * glib mainloop and handling them in a thread.
6642 * GThreadedSocketService::run:
6643 * @service: the #GThreadedSocketService.
6644 * @connection: a new #GSocketConnection object.
6645 * @source_object: the source_object passed to g_socket_listener_add_address().
6647 * The ::run signal is emitted in a worker thread in response to an
6648 * incoming connection. This thread is dedicated to handling
6649 * @connection and may perform blocking IO. The signal handler need
6650 * not return until the connection is closed.
6652 * Returns: %TRUE to stop further signal handlers from being called
6659 * A value representing an interval of time, in microseconds.
6667 * @G_TIME_TYPE_STANDARD: the time is in local standard time
6668 * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time
6669 * @G_TIME_TYPE_UNIVERSAL: the time is in UTC
6671 * Disambiguates a given time in two ways.
6673 * First, specifies if the given time is in universal or local time.
6675 * Second, if the time is in local time, specifies if it is local
6676 * standard time or local daylight time. This is important for the case
6677 * where the same local time occurs twice (during daylight savings time
6678 * transitions, for example).
6683 * GTlsAuthenticationMode:
6684 * @G_TLS_AUTHENTICATION_NONE: client authentication not required
6685 * @G_TLS_AUTHENTICATION_REQUESTED: client authentication is requested
6686 * @G_TLS_AUTHENTICATION_REQUIRED: client authentication is required
6688 * The client authentication mode for a #GTlsServerConnection.
6697 * TLS (Transport Layer Security, aka SSL) backend. This is an
6698 * internal type used to coordinate the different classes implemented
6706 * GTlsBackendInterface:
6707 * @g_iface: The parent interface.
6708 * @supports_tls: returns whether the backend supports TLS.
6709 * @get_default_database: returns a default #GTlsDatabase instance.
6710 * @get_certificate_type: returns the #GTlsCertificate implementation type
6711 * @get_client_connection_type: returns the #GTlsClientConnection implementation type
6712 * @get_server_connection_type: returns the #GTlsServerConnection implementation type
6713 * @get_file_database_type: returns the #GTlsFileDatabase implementation type.
6715 * Provides an interface for describing TLS-related types.
6724 * Abstract base class for TLS certificate types.
6731 * GTlsCertificate:certificate:
6733 * The DER (binary) encoded representation of the certificate's
6734 * public key. This property and the
6735 * #GTlsCertificate:certificate-pem property represent the same
6736 * data, just in different forms.
6743 * GTlsCertificate:certificate-pem:
6745 * The PEM (ASCII) encoded representation of the certificate's
6746 * public key. This property and the #GTlsCertificate:certificate
6747 * property represent the same data, just in different forms.
6754 * GTlsCertificate:issuer:
6756 * A #GTlsCertificate representing the entity that issued this
6757 * certificate. If %NULL, this means that the certificate is either
6758 * self-signed, or else the certificate of the issuer is not
6766 * GTlsCertificate:private-key:
6768 * The DER (binary) encoded representation of the certificate's
6769 * private key, in either PKCS#1 format or unencrypted PKCS#8
6770 * format. This property (or the #GTlsCertificate:private-key-pem
6771 * property) can be set when constructing a key (eg, from a file),
6772 * but cannot be read.
6774 * PKCS#8 format is supported since 2.32; earlier releases only
6775 * support PKCS#1. You can use the <literal>openssl rsa</literal>
6776 * tool to convert PKCS#8 keys to PKCS#1.
6783 * GTlsCertificate:private-key-pem:
6785 * The PEM (ASCII) encoded representation of the certificate's
6786 * private key in either PKCS#1 format ("<literal>BEGIN RSA PRIVATE
6787 * KEY</literal>") or unencrypted PKCS#8 format ("<literal>BEGIN
6788 * PRIVATE KEY</literal>"). This property (or the
6789 * #GTlsCertificate:private-key property) can be set when
6790 * constructing a key (eg, from a file), but cannot be read.
6792 * PKCS#8 format is supported since 2.32; earlier releases only
6793 * support PKCS#1. You can use the <literal>openssl rsa</literal>
6794 * tool to convert PKCS#8 keys to PKCS#1.
6801 * GTlsCertificateFlags:
6802 * @G_TLS_CERTIFICATE_UNKNOWN_CA: The signing certificate authority is not known.
6803 * @G_TLS_CERTIFICATE_BAD_IDENTITY: The certificate does not match the expected identity of the site that it was retrieved from.
6804 * @G_TLS_CERTIFICATE_NOT_ACTIVATED: The certificate's activation time is still in the future
6805 * @G_TLS_CERTIFICATE_EXPIRED: The certificate has expired
6806 * @G_TLS_CERTIFICATE_REVOKED: The certificate has been revoked according to the #GTlsConnection's certificate revocation list.
6807 * @G_TLS_CERTIFICATE_INSECURE: The certificate's algorithm is considered insecure.
6808 * @G_TLS_CERTIFICATE_GENERIC_ERROR: Some other error occurred validating the certificate
6809 * @G_TLS_CERTIFICATE_VALIDATE_ALL: the combination of all of the above flags
6811 * A set of flags describing TLS certification validation. This can be
6812 * used to set which validation steps to perform (eg, with
6813 * g_tls_client_connection_set_validation_flags()), or to describe why
6814 * a particular certificate was rejected (eg, in
6815 * #GTlsConnection::accept-certificate).
6822 * GTlsClientConnection:
6824 * TLS client-side connection; the client-side implementation of a
6832 * GTlsClientConnection:accepted-cas:
6834 * A list of the distinguished names of the Certificate Authorities
6835 * that the server will accept client certificates signed by. If the
6836 * server requests a client certificate during the handshake, then
6837 * this property will be set after the handshake completes.
6839 * Each item in the list is a #GByteArray which contains the complete
6840 * subject DN of the certificate authority.
6847 * GTlsClientConnection:server-identity:
6849 * A #GSocketConnectable describing the identity of the server that
6850 * is expected on the other end of the connection.
6852 * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in
6853 * #GTlsClientConnection:validation-flags, this object will be used
6854 * to determine the expected identify of the remote end of the
6855 * connection; if #GTlsClientConnection:server-identity is not set,
6856 * or does not match the identity presented by the server, then the
6857 * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail.
6859 * In addition to its use in verifying the server certificate,
6860 * this is also used to give a hint to the server about what
6861 * certificate we expect, which is useful for servers that serve
6869 * GTlsClientConnection:use-ssl3:
6871 * If %TRUE, tells the connection to use SSL 3.0 rather than trying
6872 * to negotiate the best version of TLS or SSL to use. This can be
6873 * used when talking to servers that don't implement version
6874 * negotiation correctly and therefore refuse to handshake at all with
6875 * a "modern" TLS handshake.
6882 * GTlsClientConnection:validation-flags:
6884 * What steps to perform when validating a certificate received from
6885 * a server. Server certificates that fail to validate in all of the
6886 * ways indicated here will be rejected unless the application
6887 * overrides the default via #GTlsConnection::accept-certificate.
6896 * TLS connection. This is an abstract type that will be subclassed by
6897 * a TLS-library-specific subtype.
6904 * GTlsConnection::accept-certificate:
6905 * @conn: a #GTlsConnection
6906 * @peer_cert: the peer's #GTlsCertificate
6907 * @errors: the problems with @peer_cert.
6909 * Emitted during the TLS handshake after the peer certificate has
6910 * been received. You can examine @peer_cert's certification path by
6911 * calling g_tls_certificate_get_issuer() on it.
6913 * For a client-side connection, @peer_cert is the server's
6914 * certificate, and the signal will only be emitted if the
6915 * certificate was not acceptable according to @conn's
6916 * #GTlsClientConnection:validation_flags. If you would like the
6917 * certificate to be accepted despite @errors, return %TRUE from the
6918 * signal handler. Otherwise, if no handler accepts the certificate,
6919 * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE.
6921 * For a server-side connection, @peer_cert is the certificate
6922 * presented by the client, if this was requested via the server's
6923 * #GTlsServerConnection:authentication_mode. On the server side,
6924 * the signal is always emitted when the client presents a
6925 * certificate, and the certificate will only be accepted if a
6926 * handler returns %TRUE.
6928 * Note that if this signal is emitted as part of asynchronous I/O
6929 * in the main thread, then you should not attempt to interact with
6930 * the user before returning from the signal handler. If you want to
6931 * let the user decide whether or not to accept the certificate, you
6932 * would have to return %FALSE from the signal handler on the first
6933 * attempt, and then after the connection attempt returns a
6934 * %G_TLS_ERROR_HANDSHAKE, you can interact with the user, and if
6935 * the user decides to accept the certificate, remember that fact,
6936 * create a new connection, and return %TRUE from the signal handler
6939 * If you are doing I/O in another thread, you do not
6940 * need to worry about this, and can simply block in the signal
6941 * handler until the UI thread returns an answer.
6943 * immediately end the signal emission). %FALSE to allow the signal
6944 * emission to continue, which will cause the handshake to fail if
6945 * no one else overrides it.
6947 * Returns: %TRUE to accept @peer_cert (which will also
6953 * GTlsConnection:base-io-stream:
6955 * The #GIOStream that the connection wraps
6962 * GTlsConnection:certificate:
6964 * The connection's certificate; see
6965 * g_tls_connection_set_certificate().
6972 * GTlsConnection:database:
6974 * The certificate database to use when verifying this TLS connection.
6975 * If no cerificate database is set, then the default database will be
6976 * used. See g_tls_backend_get_default_database().
6983 * GTlsConnection:interaction:
6985 * A #GTlsInteraction object to be used when the connection or certificate
6986 * database need to interact with the user. This will be used to prompt the
6987 * user for passwords where necessary.
6994 * GTlsConnection:peer-certificate:
6996 * The connection's peer's certificate, after the TLS handshake has
6997 * completed and the certificate has been accepted. Note in
6998 * particular that this is not yet set during the emission of
6999 * #GTlsConnection::accept-certificate.
7001 * (You can watch for a #GObject::notify signal on this property to
7002 * detect when a handshake has occurred.)
7009 * GTlsConnection:peer-certificate-errors:
7011 * The errors noticed-and-ignored while verifying
7012 * #GTlsConnection:peer-certificate. Normally this should be 0, but
7013 * it may not be if #GTlsClientConnection:validation-flags is not
7014 * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
7015 * #GTlsConnection::accept-certificate overrode the default
7023 * GTlsConnection:rehandshake-mode:
7025 * The rehandshaking mode. See
7026 * g_tls_connection_set_rehandshake_mode().
7033 * GTlsConnection:require-close-notify:
7035 * Whether or not proper TLS close notification is required.
7036 * See g_tls_connection_set_require_close_notify().
7043 * GTlsConnection:use-system-certdb:
7045 * Whether or not the system certificate database will be used to
7046 * verify peer certificates. See
7047 * g_tls_connection_set_use_system_certdb().
7049 * Deprecated: 2.30: Use GTlsConnection:database instead
7056 * Abstract base class for the backend-specific database types.
7063 * GTlsDatabaseLookupFlags:
7064 * @G_TLS_DATABASE_LOOKUP_NONE: No lookup flags
7065 * @G_TLS_DATABASE_LOOKUP_KEYPAIR: Restrict lookup to certificates that have a private key.
7067 * Flags for g_tls_database_lookup_certificate_handle(),
7068 * g_tls_database_lookup_certificate_issuer(),
7069 * and g_tls_database_lookup_certificates_issued_by().
7076 * GTlsDatabaseVerifyFlags:
7077 * @G_TLS_DATABASE_VERIFY_NONE: No verification flags
7079 * Flags for g_tls_database_verify_chain().
7087 * @G_TLS_ERROR_UNAVAILABLE: No TLS provider is available
7088 * @G_TLS_ERROR_MISC: Miscellaneous TLS error
7089 * @G_TLS_ERROR_BAD_CERTIFICATE: A certificate could not be parsed
7090 * @G_TLS_ERROR_NOT_TLS: The TLS handshake failed because the peer does not seem to be a TLS server.
7091 * @G_TLS_ERROR_HANDSHAKE: The TLS handshake failed because the peer's certificate was not acceptable.
7092 * @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().
7093 * @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().
7095 * An error code used with %G_TLS_ERROR in a #GError returned from a
7096 * TLS-related routine.
7105 * Implemented by a #GTlsDatabase which allows you to load certificates
7113 * GTlsFileDatabase:anchors:
7115 * The path to a file containing PEM encoded certificate authority
7116 * root anchors. The certificates in this file will be treated as
7117 * root authorities for the purpose of verifying other certificates
7118 * via the g_tls_database_verify_chain() operation.
7125 * GTlsFileDatabaseInterface:
7126 * @g_iface: The parent interface.
7128 * Provides an interface for #GTlsFileDatabase implementations.
7135 * An object representing interaction that the TLS connection and database
7136 * might have with the user.
7143 * GTlsInteractionClass:
7144 * @ask_password: ask for a password synchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument should have been filled in by using g_tls_password_set_value() or a similar function.
7145 * @ask_password_async: ask for a password asynchronously.
7146 * @ask_password_finish: complete operation to ask for a password asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument of the async method should have been filled in by using g_tls_password_set_value() or a similar function.
7148 * The class for #GTlsInteraction. Derived classes implement the various
7149 * virtual interaction methods to handle TLS interactions.
7151 * Derived classes can choose to implement whichever interactions methods they'd
7152 * like to support by overriding those virtual methods in their class
7153 * initialization function. If a derived class implements an async method,
7154 * it must also implement the corresponding finish method.
7156 * The synchronous interaction methods should implement to display modal dialogs,
7157 * and the asynchronous methods to display modeless dialogs.
7159 * If the user cancels an interaction, then the result should be
7160 * %G_TLS_INTERACTION_FAILED and the error should be set with a domain of
7161 * %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED.
7168 * GTlsInteractionResult:
7169 * @G_TLS_INTERACTION_UNHANDLED: The interaction was unhandled (i.e. not implemented).
7170 * @G_TLS_INTERACTION_HANDLED: The interaction completed, and resulting data is available.
7171 * @G_TLS_INTERACTION_FAILED: The interaction has failed, or was cancelled. and the operation should be aborted.
7173 * #GTlsInteractionResult is returned by various functions in #GTlsInteraction
7174 * when finishing an interaction request.
7183 * An abstract interface representing a password used in TLS. Often used in
7184 * user interaction such as unlocking a key storage token.
7191 * GTlsPasswordFlags:
7192 * @G_TLS_PASSWORD_NONE: No flags
7193 * @G_TLS_PASSWORD_RETRY: The password was wrong, and the user should retry.
7194 * @G_TLS_PASSWORD_MANY_TRIES: Hint to the user that the password has been wrong many times, and the user may not have many chances left.
7195 * @G_TLS_PASSWORD_FINAL_TRY: Hint to the user that this is the last try to get this password right.
7197 * Various flags for the password.
7204 * GTlsRehandshakeMode:
7205 * @G_TLS_REHANDSHAKE_NEVER: Never allow rehandshaking
7206 * @G_TLS_REHANDSHAKE_SAFELY: Allow safe rehandshaking only
7207 * @G_TLS_REHANDSHAKE_UNSAFELY: Allow unsafe rehandshaking
7209 * When to allow rehandshaking. See
7210 * g_tls_connection_set_rehandshake_mode().
7217 * GTlsServerConnection:
7219 * TLS server-side connection. This is the server-side implementation
7220 * of a #GTlsConnection.
7227 * GTlsServerConnection:authentication-mode:
7229 * The #GTlsAuthenticationMode for the server. This can be changed
7230 * before calling g_tls_connection_handshake() if you want to
7231 * rehandshake with a different mode from the initial handshake.
7239 * @data: Callback data passed to g_object_add_toggle_ref()
7240 * @object: The object on which g_object_add_toggle_ref() was called.
7241 * @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.
7243 * A callback function used for notification when the state
7244 * of a toggle reference changes. See g_object_add_toggle_ref().
7250 * @str: the untranslated string
7251 * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func()
7253 * The type of functions which are used to translate user-visible
7254 * strings, for <option>--help</option> output.
7256 * The returned string is owned by GLib and must not be freed.
7258 * Returns: a translation of the string for the current locale.
7265 * A numerical value which represents the unique identifier of a registered
7273 * An opaque structure used as the base of all classes.
7278 * GTypeClassCacheFunc:
7279 * @cache_data: data that was given to the g_type_add_class_cache_func() call
7280 * @g_class: The #GTypeClass structure which is unreferenced
7282 * A callback function which is called when the reference count of a class
7283 * drops to zero. It may use g_type_class_ref() to prevent the class from
7284 * being freed. You should not call g_type_class_unref() from a
7285 * #GTypeClassCacheFunc function to prevent infinite recursion, use
7286 * g_type_class_unref_uncached() instead.
7288 * The functions have to check the class id passed in to figure
7289 * whether they actually want to cache the class of this type, since all
7290 * classes are routed through the same #GTypeClassCacheFunc chain.
7292 * called, %FALSE to continue.
7294 * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
7300 * @G_TYPE_DEBUG_NONE: Print no messages.
7301 * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping.
7302 * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions.
7303 * @G_TYPE_DEBUG_MASK: Mask covering all debug flags.
7305 * The <type>GTypeDebugFlags</type> enumeration values can be passed to
7306 * g_type_init_with_debug_flags() to trigger debugging messages during runtime.
7307 * Note that the messages can also be triggered by setting the
7308 * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of
7309 * "objects" and "signals".
7315 * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type.
7316 * @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().
7318 * Bit masks used to check or determine characteristics of a type.
7323 * GTypeFundamentalFlags:
7324 * @G_TYPE_FLAG_CLASSED: Indicates a classed type.
7325 * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed).
7326 * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type.
7327 * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable).
7329 * Bit masks used to check or determine specific characteristics of a
7335 * GTypeFundamentalInfo:
7336 * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type
7338 * A structure that provides information to the type system which is
7339 * used specifically for managing fundamental types.
7345 * @class_size: Size of the class structure (required for interface, classed and instantiatable types).
7346 * @base_init: Location of the base initialization function (optional).
7347 * @base_finalize: Location of the base finalization function (optional).
7348 * @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.
7349 * @class_finalize: Location of the class finalization function for classed and instantiatable types. Location fo the default vtable finalization function for interface types. (optional)
7350 * @class_data: User-supplied data passed to the class init/finalize functions.
7351 * @instance_size: Size of the instance (object) structure (required for instantiatable types only).
7352 * @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.
7353 * @instance_init: Location of the instance initialization function (optional, for instantiatable types only).
7354 * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types).
7356 * This structure is used to provide the type system with the information
7357 * required to initialize and destruct (finalize) a type's class and
7359 * The initialized structure is passed to the g_type_register_static() function
7360 * (or is copied into the provided #GTypeInfo structure in the
7361 * g_type_plugin_complete_type_info()). The type system will perform a deep
7362 * copy of this structure, so its memory does not need to be persistent
7363 * across invocation of g_type_register_static().
7370 * An opaque structure used as the base of all type instances.
7377 * An opaque structure used as the base of all interface types.
7382 * GTypeInterfaceCheckFunc:
7383 * @check_data: data passed to g_type_add_interface_check().
7384 * @g_iface: the interface that has been initialized
7386 * A callback called after an interface vtable is initialized.
7387 * See g_type_add_interface_check().
7395 * @name: the name of the module
7397 * The members of the <structname>GTypeModule</structname> structure should not
7398 * be accessed directly, except for the @name field.
7404 * @parent_class: the parent class
7405 * @load: loads the module and registers one or more types using g_type_module_register_type().
7406 * @unload: unloads the module
7408 * In order to implement dynamic loading of types based on #GTypeModule,
7409 * the @load and @unload functions in #GTypeModuleClass must be implemented.
7416 * The <structname>GTypePlugin</structname> typedef is used as a placeholder
7417 * for objects that implement the <structname>GTypePlugin</structname>
7424 * @use_plugin: Increases the use count of the plugin.
7425 * @unuse_plugin: Decreases the use count of the plugin.
7426 * @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.
7427 * @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.
7429 * The #GTypePlugin interface is used by the type system in order to handle
7430 * the lifecycle of dynamically loaded types.
7435 * GTypePluginCompleteInterfaceInfo:
7436 * @plugin: the #GTypePlugin
7437 * @instance_type: the #GType of an instantiable type to which the interface is added
7438 * @interface_type: the #GType of the interface whose info is completed
7439 * @info: the #GInterfaceInfo to fill in
7441 * The type of the @complete_interface_info function of #GTypePluginClass.
7446 * GTypePluginCompleteTypeInfo:
7447 * @plugin: the #GTypePlugin
7448 * @g_type: the #GType whose info is completed
7449 * @info: the #GTypeInfo struct to fill in
7450 * @value_table: the #GTypeValueTable to fill in
7452 * The type of the @complete_type_info function of #GTypePluginClass.
7458 * @plugin: the #GTypePlugin whose use count should be decreased
7460 * The type of the @unuse_plugin function of #GTypePluginClass.
7466 * @plugin: the #GTypePlugin whose use count should be increased
7468 * The type of the @use_plugin function of #GTypePluginClass, which gets called
7469 * to increase the use count of @plugin.
7475 * @type: the #GType value of the type.
7476 * @type_name: the name of the type.
7477 * @class_size: the size of the class structure.
7478 * @instance_size: the size of the instance structure.
7480 * A structure holding information for a specific type. It is
7481 * filled in by the g_type_query() function.
7487 * @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 (""); ]|
7488 * @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); ]|
7489 * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of @src_value into @dest_value in a way, that even after @src_value has been freed, the contents of @dest_value remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]|
7490 * @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; ]|
7491 * @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'.
7492 * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup @value similar to value_init(); e.g. for a string value that does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. @n_collect_values is exactly the string length of @collect_format, and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. @collect_flags is an argument provided as a hint by the caller. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @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 signal emission 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.
7493 * @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.
7494 * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. @n_collect_values equals the string length of @lcopy_format, and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */ *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|
7496 * The #GTypeValueTable provides the functions required by the #GValue implementation,
7497 * to serve as a container for values of a type.
7502 * GUnicodeBreakType:
7503 * @G_UNICODE_BREAK_MANDATORY: Mandatory Break (BK)
7504 * @G_UNICODE_BREAK_CARRIAGE_RETURN: Carriage Return (CR)
7505 * @G_UNICODE_BREAK_LINE_FEED: Line Feed (LF)
7506 * @G_UNICODE_BREAK_COMBINING_MARK: Attached Characters and Combining Marks (CM)
7507 * @G_UNICODE_BREAK_SURROGATE: Surrogates (SG)
7508 * @G_UNICODE_BREAK_ZERO_WIDTH_SPACE: Zero Width Space (ZW)
7509 * @G_UNICODE_BREAK_INSEPARABLE: Inseparable (IN)
7510 * @G_UNICODE_BREAK_NON_BREAKING_GLUE: Non-breaking ("Glue") (GL)
7511 * @G_UNICODE_BREAK_CONTINGENT: Contingent Break Opportunity (CB)
7512 * @G_UNICODE_BREAK_SPACE: Space (SP)
7513 * @G_UNICODE_BREAK_AFTER: Break Opportunity After (BA)
7514 * @G_UNICODE_BREAK_BEFORE: Break Opportunity Before (BB)
7515 * @G_UNICODE_BREAK_BEFORE_AND_AFTER: Break Opportunity Before and After (B2)
7516 * @G_UNICODE_BREAK_HYPHEN: Hyphen (HY)
7517 * @G_UNICODE_BREAK_NON_STARTER: Nonstarter (NS)
7518 * @G_UNICODE_BREAK_OPEN_PUNCTUATION: Opening Punctuation (OP)
7519 * @G_UNICODE_BREAK_CLOSE_PUNCTUATION: Closing Punctuation (CL)
7520 * @G_UNICODE_BREAK_QUOTATION: Ambiguous Quotation (QU)
7521 * @G_UNICODE_BREAK_EXCLAMATION: Exclamation/Interrogation (EX)
7522 * @G_UNICODE_BREAK_IDEOGRAPHIC: Ideographic (ID)
7523 * @G_UNICODE_BREAK_NUMERIC: Numeric (NU)
7524 * @G_UNICODE_BREAK_INFIX_SEPARATOR: Infix Separator (Numeric) (IS)
7525 * @G_UNICODE_BREAK_SYMBOL: Symbols Allowing Break After (SY)
7526 * @G_UNICODE_BREAK_ALPHABETIC: Ordinary Alphabetic and Symbol Characters (AL)
7527 * @G_UNICODE_BREAK_PREFIX: Prefix (Numeric) (PR)
7528 * @G_UNICODE_BREAK_POSTFIX: Postfix (Numeric) (PO)
7529 * @G_UNICODE_BREAK_COMPLEX_CONTEXT: Complex Content Dependent (South East Asian) (SA)
7530 * @G_UNICODE_BREAK_AMBIGUOUS: Ambiguous (Alphabetic or Ideographic) (AI)
7531 * @G_UNICODE_BREAK_UNKNOWN: Unknown (XX)
7532 * @G_UNICODE_BREAK_NEXT_LINE: Next Line (NL)
7533 * @G_UNICODE_BREAK_WORD_JOINER: Word Joiner (WJ)
7534 * @G_UNICODE_BREAK_HANGUL_L_JAMO: Hangul L Jamo (JL)
7535 * @G_UNICODE_BREAK_HANGUL_V_JAMO: Hangul V Jamo (JV)
7536 * @G_UNICODE_BREAK_HANGUL_T_JAMO: Hangul T Jamo (JT)
7537 * @G_UNICODE_BREAK_HANGUL_LV_SYLLABLE: Hangul LV Syllable (H2)
7538 * @G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE: Hangul LVT Syllable (H3)
7539 * @G_UNICODE_BREAK_CLOSE_PARANTHESIS: Closing Parenthesis (CP). Since 2.28
7540 * @G_UNICODE_BREAK_CONDITIONAL_JAPANESE_STARTER: Conditional Japanese Starter (CJ). Since: 2.32
7541 * @G_UNICODE_BREAK_HEBREW_LETTER: Hebrew Letter (HL). Since: 2.32
7543 * These are the possible line break classifications.
7545 * The five Hangul types were added in Unicode 4.1, so, has been
7546 * introduced in GLib 2.10. Note that new types may be added in the future.
7547 * Applications should be ready to handle unknown values.
7548 * They may be regarded as %G_UNICODE_BREAK_UNKNOWN.
7550 * See <ulink url="http://www.unicode.org/unicode/reports/tr14/">http://www.unicode.org/unicode/reports/tr14/</ulink>.
7556 * @G_UNICODE_SCRIPT_COMMON: a character used by multiple different scripts
7557 * @G_UNICODE_SCRIPT_INHERITED: a mark glyph that takes its script from the i base glyph to which it is attached
7558 * @G_UNICODE_SCRIPT_ARABIC: Arabic
7559 * @G_UNICODE_SCRIPT_ARMENIAN: Armenian
7560 * @G_UNICODE_SCRIPT_BENGALI: Bengali
7561 * @G_UNICODE_SCRIPT_BOPOMOFO: Bopomofo
7562 * @G_UNICODE_SCRIPT_CHEROKEE: Cherokee
7563 * @G_UNICODE_SCRIPT_COPTIC: Coptic
7564 * @G_UNICODE_SCRIPT_CYRILLIC: Cyrillic
7565 * @G_UNICODE_SCRIPT_DESERET: Deseret
7566 * @G_UNICODE_SCRIPT_DEVANAGARI: Devanagari
7567 * @G_UNICODE_SCRIPT_ETHIOPIC: Ethiopic
7568 * @G_UNICODE_SCRIPT_GEORGIAN: Georgian
7569 * @G_UNICODE_SCRIPT_GOTHIC: Gothic
7570 * @G_UNICODE_SCRIPT_GREEK: Greek
7571 * @G_UNICODE_SCRIPT_GUJARATI: Gujarati
7572 * @G_UNICODE_SCRIPT_GURMUKHI: Gurmukhi
7573 * @G_UNICODE_SCRIPT_HAN: Han
7574 * @G_UNICODE_SCRIPT_HANGUL: Hangul
7575 * @G_UNICODE_SCRIPT_HEBREW: Hebrew
7576 * @G_UNICODE_SCRIPT_HIRAGANA: Hiragana
7577 * @G_UNICODE_SCRIPT_KANNADA: Kannada
7578 * @G_UNICODE_SCRIPT_KATAKANA: Katakana
7579 * @G_UNICODE_SCRIPT_KHMER: Khmer
7580 * @G_UNICODE_SCRIPT_LAO: Lao
7581 * @G_UNICODE_SCRIPT_LATIN: Latin
7582 * @G_UNICODE_SCRIPT_MALAYALAM: Malayalam
7583 * @G_UNICODE_SCRIPT_MONGOLIAN: Mongolian
7584 * @G_UNICODE_SCRIPT_MYANMAR: Myanmar
7585 * @G_UNICODE_SCRIPT_OGHAM: Ogham
7586 * @G_UNICODE_SCRIPT_OLD_ITALIC: Old Italic
7587 * @G_UNICODE_SCRIPT_ORIYA: Oriya
7588 * @G_UNICODE_SCRIPT_RUNIC: Runic
7589 * @G_UNICODE_SCRIPT_SINHALA: Sinhala
7590 * @G_UNICODE_SCRIPT_SYRIAC: Syriac
7591 * @G_UNICODE_SCRIPT_TAMIL: Tamil
7592 * @G_UNICODE_SCRIPT_TELUGU: Telugu
7593 * @G_UNICODE_SCRIPT_THAANA: Thaana
7594 * @G_UNICODE_SCRIPT_THAI: Thai
7595 * @G_UNICODE_SCRIPT_TIBETAN: Tibetan Canadian Aboriginal
7596 * @G_UNICODE_SCRIPT_YI: Yi
7597 * @G_UNICODE_SCRIPT_TAGALOG: Tagalog
7598 * @G_UNICODE_SCRIPT_HANUNOO: Hanunoo
7599 * @G_UNICODE_SCRIPT_BUHID: Buhid
7600 * @G_UNICODE_SCRIPT_TAGBANWA: Tagbanwa
7601 * @G_UNICODE_SCRIPT_BRAILLE: Braille
7602 * @G_UNICODE_SCRIPT_CYPRIOT: Cypriot
7603 * @G_UNICODE_SCRIPT_LIMBU: Limbu
7604 * @G_UNICODE_SCRIPT_OSMANYA: Osmanya
7605 * @G_UNICODE_SCRIPT_SHAVIAN: Shavian
7606 * @G_UNICODE_SCRIPT_LINEAR_B: Linear B
7607 * @G_UNICODE_SCRIPT_TAI_LE: Tai Le
7608 * @G_UNICODE_SCRIPT_UGARITIC: Ugaritic New Tai Lue
7609 * @G_UNICODE_SCRIPT_BUGINESE: Buginese
7610 * @G_UNICODE_SCRIPT_GLAGOLITIC: Glagolitic
7611 * @G_UNICODE_SCRIPT_TIFINAGH: Tifinagh Syloti Nagri Old Persian
7612 * @G_UNICODE_SCRIPT_KHAROSHTHI: Kharoshthi
7613 * @G_UNICODE_SCRIPT_UNKNOWN: an unassigned code point
7614 * @G_UNICODE_SCRIPT_BALINESE: Balinese
7615 * @G_UNICODE_SCRIPT_CUNEIFORM: Cuneiform
7616 * @G_UNICODE_SCRIPT_PHOENICIAN: Phoenician
7617 * @G_UNICODE_SCRIPT_PHAGS_PA: Phags-pa
7618 * @G_UNICODE_SCRIPT_NKO: N'Ko
7619 * @G_UNICODE_SCRIPT_KAYAH_LI: Kayah Li. Since 2.16.3
7620 * @G_UNICODE_SCRIPT_LEPCHA: Lepcha. Since 2.16.3
7621 * @G_UNICODE_SCRIPT_REJANG: Rejang. Since 2.16.3
7622 * @G_UNICODE_SCRIPT_SUNDANESE: Sundanese. Since 2.16.3
7623 * @G_UNICODE_SCRIPT_SAURASHTRA: Saurashtra. Since 2.16.3
7624 * @G_UNICODE_SCRIPT_CHAM: Cham. Since 2.16.3
7625 * @G_UNICODE_SCRIPT_OL_CHIKI: Ol Chiki. Since 2.16.3
7626 * @G_UNICODE_SCRIPT_VAI: Vai. Since 2.16.3
7627 * @G_UNICODE_SCRIPT_CARIAN: Carian. Since 2.16.3
7628 * @G_UNICODE_SCRIPT_LYCIAN: Lycian. Since 2.16.3
7629 * @G_UNICODE_SCRIPT_LYDIAN: Lydian. Since 2.16.3
7630 * @G_UNICODE_SCRIPT_AVESTAN: Avestan. Since 2.26
7631 * @G_UNICODE_SCRIPT_BAMUM: Bamum. Since 2.26 Egyptian Hieroglpyhs. Since 2.26 Imperial Aramaic. Since 2.26 Inscriptional Pahlavi. Since 2.26 Inscriptional Parthian. Since 2.26
7632 * @G_UNICODE_SCRIPT_JAVANESE: Javanese. Since 2.26
7633 * @G_UNICODE_SCRIPT_KAITHI: Kaithi. Since 2.26
7634 * @G_UNICODE_SCRIPT_LISU: Lisu. Since 2.26 Meetei Mayek. Since 2.26 Old South Arabian. Since 2.26
7635 * @G_UNICODE_SCRIPT_OLD_TURKIC: Old Turkic. Since 2.28
7636 * @G_UNICODE_SCRIPT_SAMARITAN: Samaritan. Since 2.26
7637 * @G_UNICODE_SCRIPT_TAI_THAM: Tai Tham. Since 2.26
7638 * @G_UNICODE_SCRIPT_TAI_VIET: Tai Viet. Since 2.26
7639 * @G_UNICODE_SCRIPT_BATAK: Batak. Since 2.28
7640 * @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28
7641 * @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28
7642 * @G_UNICODE_SCRIPT_CHAKMA: Chakma. Since: 2.32
7643 * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32
7644 * @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32
7645 * @G_UNICODE_SCRIPT_MIAO: Miao. Since: 2.32
7646 * @G_UNICODE_SCRIPT_SHARADA: Sharada. Since: 2.32
7647 * @G_UNICODE_SCRIPT_SORA_SOMPENG: Sora Sompeng. Since: 2.32
7648 * @G_UNICODE_SCRIPT_TAKRI: Takri. Since: 2.32
7650 * The #GUnicodeScript enumeration identifies different writing
7651 * systems. The values correspond to the names as defined in the
7652 * Unicode standard. The enumeration has been added in GLib 2.14,
7653 * and is interchangeable with #PangoScript.
7655 * Note that new types may be added in the future. Applications
7656 * should be ready to handle unknown values.
7658 * url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex
7659 * #24: Script names</ulink>.
7665 * @G_UNICODE_CONTROL: General category "Other, Control" (Cc)
7666 * @G_UNICODE_FORMAT: General category "Other, Format" (Cf)
7667 * @G_UNICODE_UNASSIGNED: General category "Other, Not Assigned" (Cn)
7668 * @G_UNICODE_PRIVATE_USE: General category "Other, Private Use" (Co)
7669 * @G_UNICODE_SURROGATE: General category "Other, Surrogate" (Cs)
7670 * @G_UNICODE_LOWERCASE_LETTER: General category "Letter, Lowercase" (Ll)
7671 * @G_UNICODE_MODIFIER_LETTER: General category "Letter, Modifier" (Lm)
7672 * @G_UNICODE_OTHER_LETTER: General category "Letter, Other" (Lo)
7673 * @G_UNICODE_TITLECASE_LETTER: General category "Letter, Titlecase" (Lt)
7674 * @G_UNICODE_UPPERCASE_LETTER: General category "Letter, Uppercase" (Lu)
7675 * @G_UNICODE_SPACING_MARK: General category "Mark, Spacing" (Mc)
7676 * @G_UNICODE_ENCLOSING_MARK: General category "Mark, Enclosing" (Me)
7677 * @G_UNICODE_NON_SPACING_MARK: General category "Mark, Nonspacing" (Mn)
7678 * @G_UNICODE_DECIMAL_NUMBER: General category "Number, Decimal Digit" (Nd)
7679 * @G_UNICODE_LETTER_NUMBER: General category "Number, Letter" (Nl)
7680 * @G_UNICODE_OTHER_NUMBER: General category "Number, Other" (No)
7681 * @G_UNICODE_CONNECT_PUNCTUATION: General category "Punctuation, Connector" (Pc)
7682 * @G_UNICODE_DASH_PUNCTUATION: General category "Punctuation, Dash" (Pd)
7683 * @G_UNICODE_CLOSE_PUNCTUATION: General category "Punctuation, Close" (Pe)
7684 * @G_UNICODE_FINAL_PUNCTUATION: General category "Punctuation, Final quote" (Pf)
7685 * @G_UNICODE_INITIAL_PUNCTUATION: General category "Punctuation, Initial quote" (Pi)
7686 * @G_UNICODE_OTHER_PUNCTUATION: General category "Punctuation, Other" (Po)
7687 * @G_UNICODE_OPEN_PUNCTUATION: General category "Punctuation, Open" (Ps)
7688 * @G_UNICODE_CURRENCY_SYMBOL: General category "Symbol, Currency" (Sc)
7689 * @G_UNICODE_MODIFIER_SYMBOL: General category "Symbol, Modifier" (Sk)
7690 * @G_UNICODE_MATH_SYMBOL: General category "Symbol, Math" (Sm)
7691 * @G_UNICODE_OTHER_SYMBOL: General category "Symbol, Other" (So)
7692 * @G_UNICODE_LINE_SEPARATOR: General category "Separator, Line" (Zl)
7693 * @G_UNICODE_PARAGRAPH_SEPARATOR: General category "Separator, Paragraph" (Zp)
7694 * @G_UNICODE_SPACE_SEPARATOR: General category "Separator, Space" (Zs)
7696 * These are the possible character classifications from the
7697 * Unicode specification.
7698 * See <ulink url="http://www.unicode.org/Public/UNIDATA/UnicodeData.html">http://www.unicode.org/Public/UNIDATA/UnicodeData.html</ulink>.
7703 * GUnixCredentialsMessage:
7705 * The #GUnixCredentialsMessage structure contains only private data
7706 * and should only be accessed using the provided API.
7713 * GUnixCredentialsMessage:credentials:
7715 * The credentials stored in the message.
7722 * GUnixCredentialsMessageClass:
7724 * Class structure for #GUnixCredentialsMessage.
7733 * Implements #GInputStream for reading from selectable unix file descriptors
7738 * GUnixInputStream:close-fd:
7740 * Whether to close the file descriptor when the stream is closed.
7747 * GUnixInputStream:fd:
7749 * The file descriptor that the stream reads from.
7758 * Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>).
7759 * This corresponds roughly to a mtab entry.
7764 * GUnixMountMonitor:
7766 * Watches #GUnixMount<!-- -->s for changes.
7771 * GUnixMountMonitor::mountpoints-changed:
7772 * @monitor: the object on which the signal is emitted
7774 * Emitted when the unix mount points have changed.
7779 * GUnixMountMonitor::mounts-changed:
7780 * @monitor: the object on which the signal is emitted
7782 * Emitted when the unix mounts have changed.
7789 * Defines a Unix mount point (e.g. <filename>/dev</filename>).
7790 * This corresponds roughly to a fstab entry.
7795 * GUnixOutputStream:
7797 * Implements #GOutputStream for outputting to selectable unix file descriptors
7802 * GUnixOutputStream:close-fd:
7804 * Whether to close the file descriptor when the stream is closed.
7811 * GUnixOutputStream:fd:
7813 * The file descriptor that the stream writes to.
7820 * GUnixSocketAddress:
7822 * A UNIX-domain (local) socket address, corresponding to a
7823 * <type>struct sockaddr_un</type>.
7828 * GUnixSocketAddress:abstract:
7830 * Whether or not this is an abstract address
7832 * distinguishes between zero-padded and non-zero-padded
7833 * abstract addresses.
7835 * Deprecated: Use #GUnixSocketAddress:address-type, which
7840 * GUnixSocketAddressType:
7841 * @G_UNIX_SOCKET_ADDRESS_INVALID: invalid
7842 * @G_UNIX_SOCKET_ADDRESS_ANONYMOUS: anonymous
7843 * @G_UNIX_SOCKET_ADDRESS_PATH: a filesystem path
7844 * @G_UNIX_SOCKET_ADDRESS_ABSTRACT: an abstract name
7845 * @G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED: an abstract name, 0-padded to the full length of a unix socket name
7847 * The type of name used by a #GUnixSocketAddress.
7848 * %G_UNIX_SOCKET_ADDRESS_PATH indicates a traditional unix domain
7849 * socket bound to a filesystem path. %G_UNIX_SOCKET_ADDRESS_ANONYMOUS
7850 * indicates a socket not bound to any name (eg, a client-side socket,
7851 * or a socket created with socketpair()).
7853 * For abstract sockets, there are two incompatible ways of naming
7854 * them; the man pages suggest using the entire <literal>struct
7855 * sockaddr_un</literal> as the name, padding the unused parts of the
7856 * %sun_path field with zeroes; this corresponds to
7857 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs
7858 * instead just use a portion of %sun_path, and pass an appropriate
7859 * smaller length to bind() or connect(). This is
7860 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT.
7868 * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory
7869 * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory
7870 * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory
7871 * @G_USER_DIRECTORY_MUSIC: the user's Music directory
7872 * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory
7873 * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory
7874 * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory
7875 * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory
7876 * @G_USER_N_DIRECTORIES: the number of enum values
7878 * These are logical ids for special directories which are defined
7879 * depending on the platform used. You should use g_get_user_special_dir()
7880 * to retrieve the full path associated to the logical id.
7882 * The #GUserDirectory enumeration can be extended at later date. Not
7883 * every platform has a directory for every logical id in this
7893 * An opaque structure used to hold different types of values.
7894 * The data within the structure has protected scope: it is accessible only
7895 * to functions within a #GTypeValueTable structure, or implementations of
7896 * the g_value_*() API. That is, code portions which implement new fundamental
7898 * #GValue users cannot make any assumptions about how data is stored
7899 * within the 2 element @data union, and the @g_type member should
7900 * only be accessed through the G_VALUE_TYPE() macro.
7906 * @n_values: number of values contained in the array
7907 * @values: array of values
7909 * A #GValueArray contains an array of #GValue elements.
7915 * @src_value: Source value.
7916 * @dest_value: Target value.
7918 * The type of value transformation functions which can be registered with
7919 * g_value_register_transform_func().
7926 * A type in the GVariant type system.
7928 * Two types may not be compared by value; use g_variant_type_equal() or
7929 * g_variant_type_is_subtype_of(). May be copied using
7930 * g_variant_type_copy() and freed using g_variant_type_free().
7937 * Virtual File System object.
7944 * Declares a type of function which takes no arguments
7945 * and has no return value. It is used to specify the type
7946 * function passed to g_atexit().
7953 * Opaque mountable volume object.
7960 * Emitted when the volume has been changed.
7967 * This signal is emitted when the #GVolume have been removed. If
7968 * the recipient is holding references to the object they should
7969 * release them so the object can be finalized.
7975 * @g_iface: The parent interface.
7976 * @changed: Changed signal that is emitted when the volume's state has changed.
7977 * @removed: The removed signal that 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.
7978 * @get_name: Gets a string containing the name of the #GVolume.
7979 * @get_icon: Gets a #GIcon for the #GVolume.
7980 * @get_uuid: Gets the UUID for the #GVolume. 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.
7981 * @get_drive: Gets a #GDrive the volume is located on. Returns %NULL if the #GVolume is not associated with a #GDrive.
7982 * @get_mount: Gets a #GMount representing the mounted volume. Returns %NULL if the #GVolume is not mounted.
7983 * @can_mount: Returns %TRUE if the #GVolume can be mounted.
7984 * @can_eject: Checks if a #GVolume can be ejected.
7985 * @mount_fn: Mounts a given #GVolume. #GVolume implementations must emit the #GMountOperation::aborted signal before completing a mount operation that is aborted while awaiting input from the user through a #GMountOperation instance.
7986 * @mount_finish: Finishes a mount operation.
7987 * @eject: Ejects a given #GVolume.
7988 * @eject_finish: Finishes an eject operation.
7989 * @get_identifier: Returns the <link linkend="volume-identifier">identifier</link> of the given kind, or %NULL if the #GVolume doesn't have one.
7990 * @enumerate_identifiers: Returns an array strings listing the kinds of <link linkend="volume-identifier">identifiers</link> which the #GVolume has.
7991 * @should_automount: Returns %TRUE if the #GVolume should be automatically mounted.
7992 * @get_activation_root: Returns the activation root for the #GVolume if it is known in advance or %NULL if it is not known.
7993 * @eject_with_operation: Starts ejecting a #GVolume using a #GMountOperation. Since 2.22.
7994 * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
7995 * @get_sort_key: Gets a key used for sorting #GVolume instance or %NULL if no such key exists. Since 2.32.
7997 * Interface for implementing operations for mountable volumes.
8004 * A Volume Monitor that watches for volume events.
8009 * GVolumeMonitor::drive-changed:
8010 * @volume_monitor: The volume monitor emitting the signal.
8011 * @drive: the drive that changed
8013 * Emitted when a drive changes.
8018 * GVolumeMonitor::drive-connected:
8019 * @volume_monitor: The volume monitor emitting the signal.
8020 * @drive: a #GDrive that was connected.
8022 * Emitted when a drive is connected to the system.
8027 * GVolumeMonitor::drive-disconnected:
8028 * @volume_monitor: The volume monitor emitting the signal.
8029 * @drive: a #GDrive that was disconnected.
8031 * Emitted when a drive is disconnected from the system.
8036 * GVolumeMonitor::drive-eject-button:
8037 * @volume_monitor: The volume monitor emitting the signal.
8038 * @drive: the drive where the eject button was pressed
8040 * Emitted when the eject button is pressed on @drive.
8047 * GVolumeMonitor::drive-stop-button:
8048 * @volume_monitor: The volume monitor emitting the signal.
8049 * @drive: the drive where the stop button was pressed
8051 * Emitted when the stop button is pressed on @drive.
8058 * GVolumeMonitor::mount-added:
8059 * @volume_monitor: The volume monitor emitting the signal.
8060 * @mount: a #GMount that was added.
8062 * Emitted when a mount is added.
8067 * GVolumeMonitor::mount-changed:
8068 * @volume_monitor: The volume monitor emitting the signal.
8069 * @mount: a #GMount that changed.
8071 * Emitted when a mount changes.
8076 * GVolumeMonitor::mount-pre-unmount:
8077 * @volume_monitor: The volume monitor emitting the signal.
8078 * @mount: a #GMount that is being unmounted.
8080 * Emitted when a mount is about to be removed.
8085 * GVolumeMonitor::mount-removed:
8086 * @volume_monitor: The volume monitor emitting the signal.
8087 * @mount: a #GMount that was removed.
8089 * Emitted when a mount is removed.
8094 * GVolumeMonitor::volume-added:
8095 * @volume_monitor: The volume monitor emitting the signal.
8096 * @volume: a #GVolume that was added.
8098 * Emitted when a mountable volume is added to the system.
8103 * GVolumeMonitor::volume-changed:
8104 * @volume_monitor: The volume monitor emitting the signal.
8105 * @volume: a #GVolume that changed.
8107 * Emitted when mountable volume is changed.
8112 * GVolumeMonitor::volume-removed:
8113 * @volume_monitor: The volume monitor emitting the signal.
8114 * @volume: a #GVolume that was removed.
8116 * Emitted when a mountable volume is removed from the system.
8122 * @data: data that was provided when the weak reference was established
8123 * @where_the_object_was: the object being finalized
8125 * A #GWeakNotify function can be added to an object as a callback that gets
8126 * triggered when the object is finalized. Since the object is already being
8127 * finalized when the #GWeakNotify is called, there's not much you could do
8128 * with the object, apart from e.g. using its address as hash-index or the like.
8133 * GWin32InputStream:close-handle:
8135 * Whether to close the file handle when the stream is closed.
8142 * GWin32InputStream:handle:
8144 * The handle that the stream reads from.
8151 * GWin32OutputStream:close-handle:
8153 * Whether to close the file handle when the stream is closed.
8160 * GWin32OutputStream:handle:
8162 * The file handle that the stream writes to.
8171 * Zlib decompression
8176 * GZlibCompressor:file-info:
8178 * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is
8179 * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name
8180 * and modification time from the file info to the the GZIP header.
8187 * GZlibCompressorFormat:
8188 * @G_ZLIB_COMPRESSOR_FORMAT_ZLIB: deflate compression with zlib header
8189 * @G_ZLIB_COMPRESSOR_FORMAT_GZIP: gzip file format
8190 * @G_ZLIB_COMPRESSOR_FORMAT_RAW: deflate compression with no header
8192 * Used to select the type of data format to use for #GZlibDecompressor
8193 * and #GZlibCompressor.
8200 * GZlibDecompressor:
8202 * Zlib decompression
8207 * GZlibDecompressor:file-info:
8209 * A #GFileInfo containing the information found in the GZIP header
8210 * of the data stream processed, or %NULL if the header was not yet
8211 * fully processed, is not present at all, or the compressor's
8212 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP.
8219 * G_BOOKMARK_FILE_ERROR:
8221 * Error domain for bookmark file parsing.
8222 * Errors in this domain will be from the #GBookmarkFileError
8223 * enumeration. See #GError for information on error domains.
8230 * Inserts a breakpoint instruction into the code.
8232 * On x86 and alpha systems this is implemented as a soft interrupt
8233 * and on other architectures it raises a <literal>SIGTRAP</literal> signal.
8239 * @f: a function pointer.
8241 * Cast a function pointer to a #GCallback.
8246 * G_CCLOSURE_SWAP_DATA:
8247 * @cclosure: a #GCClosure
8249 * Checks whether the user data of the #GCClosure should be passed as the
8250 * first parameter to the callback. See g_cclosure_new_swap().
8252 * Returns: %TRUE if data has to be swapped.
8257 * G_CLOSURE_NEEDS_MARSHAL:
8258 * @closure: a #GClosure
8260 * Check if the closure still needs a marshaller. See g_closure_set_marshal().
8264 * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
8269 * G_CLOSURE_N_NOTIFIERS:
8272 * Get the total number of notifiers connected with the closure @cl.
8273 * The count includes the meta marshaller, the finalize and invalidate notifiers
8274 * and the marshal guards. Note that each guard counts as two notifiers.
8275 * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(),
8276 * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards().
8278 * Returns: number of notifiers
8285 * Error domain for character set conversions. Errors in this domain will
8286 * be from the #GConvertError enumeration. See #GError for information on
8292 * G_DATALIST_FLAGS_MASK:
8294 * A bitmask that restricts the possible flags passed to
8295 * g_datalist_set_flags(). Passing a flags value where
8296 * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error.
8303 * Error domain for errors generated by a remote message bus. Errors
8304 * in this domain will be from the #GDBusError enumeration. See
8305 * #GError for more information on error domains.
8307 * Note that errors in this error domain is intended only for
8308 * returning errors from a remote message bus process. Errors
8309 * generated locally in-process by e.g. #GDBusConnection is from the
8310 * %G_IO_ERROR domain.
8317 * G_DEFINE_ABSTRACT_TYPE:
8318 * @TN: The name of the new type, in Camel case.
8319 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
8320 * @T_P: The #GType of the parent type.
8322 * A convenience macro for type implementations.
8323 * Similar to G_DEFINE_TYPE(), but defines an abstract type.
8324 * See G_DEFINE_TYPE_EXTENDED() for an example.
8331 * G_DEFINE_ABSTRACT_TYPE_WITH_CODE:
8332 * @TN: The name of the new type, in Camel case.
8333 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
8334 * @T_P: The #GType of the parent type.
8335 * @_C_: Custom code that gets inserted in the @type_name_get_type() function.
8337 * A convenience macro for type implementations.
8338 * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to
8339 * insert custom code into the *_get_type() function, e.g. interface implementations
8340 * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example.
8347 * G_DEFINE_BOXED_TYPE:
8348 * @TypeName: The name of the new type, in Camel case.
8349 * @type_name: The name of the new type, in lowercase, with words separated by '_'.
8350 * @copy_func: the #GBoxedCopyFunc for the new type
8351 * @free_func: the #GBoxedFreeFunc for the new type
8353 * A convenience macro for boxed type implementations, which defines a
8354 * type_name_get_type() function registering the boxed type.
8361 * G_DEFINE_BOXED_TYPE_WITH_CODE:
8362 * @TypeName: The name of the new type, in Camel case.
8363 * @type_name: The name of the new type, in lowercase, with words separated by '_'.
8364 * @copy_func: the #GBoxedCopyFunc for the new type
8365 * @free_func: the #GBoxedFreeFunc for the new type
8366 * @_C_: Custom code that gets inserted in the *_get_type() function.
8368 * A convenience macro for boxed type implementations.
8369 * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the
8370 * type_name_get_type() function, e.g. to register value transformations with
8371 * g_value_register_transform_func().
8378 * G_DEFINE_DYNAMIC_TYPE:
8379 * @TN: The name of the new type, in Camel case.
8380 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
8381 * @T_P: The #GType of the parent type.
8383 * A convenience macro for dynamic type implementations, which declares a
8384 * class initialization function, an instance initialization function (see
8385 * #GTypeInfo for information about these) and a static variable named
8386 * @t_n<!-- -->_parent_class pointing to the parent class. Furthermore,
8387 * it defines a <function>*_get_type()</function> and a static
8388 * <function>*_register_type()</function> function for use in your
8389 * <function>module_init()</function>.
8390 * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
8397 * G_DEFINE_DYNAMIC_TYPE_EXTENDED:
8398 * @TypeName: The name of the new type, in Camel case.
8399 * @type_name: The name of the new type, in lowercase, with words separated by '_'.
8400 * @TYPE_PARENT: The #GType of the parent type.
8401 * @flags: #GTypeFlags to pass to g_type_module_register_type()
8402 * @CODE: Custom code that gets inserted in the *_get_type() function.
8404 * A more general version of G_DEFINE_DYNAMIC_TYPE() which
8405 * allows to specify #GTypeFlags and custom code.
8408 * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
8412 * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
8413 * gtk_gadget_gizmo_init));
8417 * static void gtk_gadget_init (GtkGadget *self);
8418 * static void gtk_gadget_class_init (GtkGadgetClass *klass);
8419 * static void gtk_gadget_class_finalize (GtkGadgetClass *klass);
8421 * static gpointer gtk_gadget_parent_class = NULL;
8422 * static GType gtk_gadget_type_id = 0;
8424 * static void gtk_gadget_class_intern_init (gpointer klass)
8426 * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
8427 * gtk_gadget_class_init ((GtkGadgetClass*) klass);
8431 * gtk_gadget_get_type (void)
8433 * return gtk_gadget_type_id;
8437 * gtk_gadget_register_type (GTypeModule *type_module)
8439 * const GTypeInfo g_define_type_info = {
8440 * sizeof (GtkGadgetClass),
8441 * (GBaseInitFunc) NULL,
8442 * (GBaseFinalizeFunc) NULL,
8443 * (GClassInitFunc) gtk_gadget_class_intern_init,
8444 * (GClassFinalizeFunc) gtk_gadget_class_finalize,
8445 * NULL, // class_data
8446 * sizeof (GtkGadget),
8448 * (GInstanceInitFunc) gtk_gadget_init,
8449 * NULL // value_table
8451 * gtk_gadget_type_id = g_type_module_register_type (type_module,
8454 * &g_define_type_info,
8455 * (GTypeFlags) flags);
8457 * const GInterfaceInfo g_implement_interface_info = {
8458 * (GInterfaceInitFunc) gtk_gadget_gizmo_init
8460 * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
8470 * G_DEFINE_INTERFACE:
8471 * @TN: The name of the new type, in Camel case.
8472 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
8473 * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type.
8475 * A convenience macro for #GTypeInterface definitions, which declares
8476 * a default vtable initialization function and defines a *_get_type()
8479 * The macro expects the interface initialization function to have the
8480 * name <literal>t_n ## _default_init</literal>, and the interface
8481 * structure to have the name <literal>TN ## Interface</literal>.
8488 * G_DEFINE_INTERFACE_WITH_CODE:
8489 * @TN: The name of the new type, in Camel case.
8490 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
8491 * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type.
8492 * @_C_: Custom code that gets inserted in the *_get_type() function.
8494 * A convenience macro for #GTypeInterface definitions. Similar to
8495 * G_DEFINE_INTERFACE(), but allows you to insert custom code into the
8496 * *_get_type() function, e.g. additional interface implementations
8497 * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See
8498 * G_DEFINE_TYPE_EXTENDED() for a similar example using
8499 * G_DEFINE_TYPE_WITH_CODE().
8506 * G_DEFINE_POINTER_TYPE:
8507 * @TypeName: The name of the new type, in Camel case.
8508 * @type_name: The name of the new type, in lowercase, with words separated by '_'.
8510 * A convenience macro for pointer type implementations, which defines a
8511 * type_name_get_type() function registering the pointer type.
8518 * G_DEFINE_POINTER_TYPE_WITH_CODE:
8519 * @TypeName: The name of the new type, in Camel case.
8520 * @type_name: The name of the new type, in lowercase, with words separated by '_'.
8521 * @_C_: Custom code that gets inserted in the *_get_type() function.
8523 * A convenience macro for pointer type implementations.
8524 * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the
8525 * type_name_get_type() function.
8533 * @TN: The name of the new type, in Camel case.
8534 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
8535 * @T_P: The #GType of the parent type.
8537 * A convenience macro for type implementations, which declares a
8538 * class initialization function, an instance initialization function (see #GTypeInfo for information about
8539 * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, it defines
8540 * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example.
8547 * G_DEFINE_TYPE_EXTENDED:
8548 * @TN: The name of the new type, in Camel case.
8549 * @t_n: The name of the new type, in lowercase, with words separated by '_'.
8550 * @T_P: The #GType of the parent type.
8551 * @_f_: #GTypeFlags to pass to g_type_register_static()
8552 * @_C_: Custom code that gets inserted in the *_get_type() function.
8554 * The most general convenience macro for type implementations, on which
8555 * G_DEFINE_TYPE(), etc are based.
8558 * G_DEFINE_TYPE_EXTENDED (GtkGadget,
8562 * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
8563 * gtk_gadget_gizmo_init));
8567 * static void gtk_gadget_init (GtkGadget *self);
8568 * static void gtk_gadget_class_init (GtkGadgetClass *klass);
8569 * static gpointer gtk_gadget_parent_class = NULL;
8570 * static void gtk_gadget_class_intern_init (gpointer klass)
8572 * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
8573 * gtk_gadget_class_init ((GtkGadgetClass*) klass);
8577 * gtk_gadget_get_type (void)
8579 * static volatile gsize g_define_type_id__volatile = 0;
8580 * if (g_once_init_enter (&g_define_type_id__volatile))
8582 * GType g_define_type_id =
8583 * g_type_register_static_simple (GTK_TYPE_WIDGET,
8584 * g_intern_static_string ("GtkGadget"),
8585 * sizeof (GtkGadgetClass),
8586 * (GClassInitFunc) gtk_gadget_class_intern_init,
8587 * sizeof (GtkGadget),
8588 * (GInstanceInitFunc) gtk_gadget_init,
8589 * (GTypeFlags) flags);
8591 * const GInterfaceInfo g_implement_interface_info = {
8592 * (GInterfaceInitFunc) gtk_gadget_gizmo_init
8594 * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
8596 * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
8598 * return g_define_type_id__volatile;
8601 * The only pieces which have to be manually provided are the definitions of
8602 * the instance and class structure and the definitions of the instance and
8603 * class init functions.
8610 * G_DEFINE_TYPE_WITH_CODE:
8611 * @TN: The name of the new type, in Camel case.
8612 * @t_n: The name of the new type in lowercase, with words separated by '_'.
8613 * @T_P: The #GType of the parent type.
8614 * @_C_: Custom code that gets inserted in the *_get_type() function.
8616 * A convenience macro for type implementations.
8617 * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the
8618 * *_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
8619 * See G_DEFINE_TYPE_EXTENDED() for an example.
8626 * G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME:
8628 * Extension point for default handler to URI association. See
8629 * <link linkend="extending-gio">Extending GIO</link>.
8635 * @class: a valid #GEnumClass
8637 * Casts a derived #GEnumClass structure into a #GEnumClass structure.
8642 * G_ENUM_CLASS_TYPE:
8643 * @class: a #GEnumClass
8645 * Get the type identifier from a given #GEnumClass structure.
8647 * Returns: the #GType
8652 * G_ENUM_CLASS_TYPE_NAME:
8653 * @class: a #GEnumClass
8655 * Get the static type name from a given #GEnumClass structure.
8657 * Returns: the type name.
8662 * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE:
8664 * A key in the "access" namespace for checking deletion privileges.
8665 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8666 * This attribute will be %TRUE if the user is able to delete the file.
8671 * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE:
8673 * A key in the "access" namespace for getting execution privileges.
8674 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8675 * This attribute will be %TRUE if the user is able to execute the file.
8680 * G_FILE_ATTRIBUTE_ACCESS_CAN_READ:
8682 * A key in the "access" namespace for getting read privileges.
8683 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8684 * This attribute will be %TRUE if the user is able to read the file.
8689 * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME:
8691 * A key in the "access" namespace for checking renaming privileges.
8692 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8693 * This attribute will be %TRUE if the user is able to rename the file.
8698 * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH:
8700 * A key in the "access" namespace for checking trashing privileges.
8701 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8702 * This attribute will be %TRUE if the user is able to move the file to
8708 * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE:
8710 * A key in the "access" namespace for getting write privileges.
8711 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8712 * This attribute will be %TRUE if the user is able to write to the file.
8717 * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE:
8719 * A key in the "dos" namespace for checking if the file's archive flag
8720 * is set. This attribute is %TRUE if the archive flag is set. This attribute
8721 * is only available for DOS file systems. Corresponding #GFileAttributeType
8722 * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8727 * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM:
8729 * A key in the "dos" namespace for checking if the file's backup flag
8730 * is set. This attribute is %TRUE if the backup flag is set. This attribute
8731 * is only available for DOS file systems. Corresponding #GFileAttributeType
8732 * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8737 * G_FILE_ATTRIBUTE_ETAG_VALUE:
8739 * A key in the "etag" namespace for getting the value of the file's
8740 * entity tag. Corresponding #GFileAttributeType is
8741 * %G_FILE_ATTRIBUTE_TYPE_STRING.
8746 * G_FILE_ATTRIBUTE_FILESYSTEM_FREE:
8748 * A key in the "filesystem" namespace for getting the number of bytes of free space left on the
8749 * file system. Corresponding #GFileAttributeType is
8750 * %G_FILE_ATTRIBUTE_TYPE_UINT64.
8755 * G_FILE_ATTRIBUTE_FILESYSTEM_READONLY:
8757 * A key in the "filesystem" namespace for checking if the file system
8758 * is read only. Is set to %TRUE if the file system is read only.
8759 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8764 * G_FILE_ATTRIBUTE_FILESYSTEM_SIZE:
8766 * A key in the "filesystem" namespace for getting the total size (in bytes) of the file system,
8767 * used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType
8768 * is %G_FILE_ATTRIBUTE_TYPE_UINT64.
8773 * G_FILE_ATTRIBUTE_FILESYSTEM_TYPE:
8775 * A key in the "filesystem" namespace for getting the file system's type.
8776 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
8781 * G_FILE_ATTRIBUTE_FILESYSTEM_USED:
8783 * A key in the "filesystem" namespace for getting the number of bytes of used on the
8784 * file system. Corresponding #GFileAttributeType is
8785 * %G_FILE_ATTRIBUTE_TYPE_UINT64.
8792 * G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW:
8794 * A key in the "filesystem" namespace for hinting a file manager
8795 * application whether it should preview (e.g. thumbnail) files on the
8796 * file system. The value for this key contain a
8797 * #GFilesystemPreviewType.
8802 * G_FILE_ATTRIBUTE_GVFS_BACKEND:
8804 * A key in the "gvfs" namespace that gets the name of the current
8805 * GVFS backend in use. Corresponding #GFileAttributeType is
8806 * %G_FILE_ATTRIBUTE_TYPE_STRING.
8811 * G_FILE_ATTRIBUTE_ID_FILE:
8813 * A key in the "id" namespace for getting a file identifier.
8814 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
8815 * An example use would be during listing files, to avoid recursive
8816 * directory scanning.
8821 * G_FILE_ATTRIBUTE_ID_FILESYSTEM:
8823 * A key in the "id" namespace for getting the file system identifier.
8824 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
8825 * An example use would be during drag and drop to see if the source
8826 * and target are on the same filesystem (default to move) or not (default
8832 * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT:
8834 * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected.
8835 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8840 * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT:
8842 * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable.
8843 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8848 * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL:
8850 * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled.
8851 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8858 * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START:
8860 * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started.
8861 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8868 * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED:
8870 * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started
8872 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8879 * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP:
8881 * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped.
8882 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8889 * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT:
8891 * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable.
8892 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8897 * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI:
8899 * A key in the "mountable" namespace for getting the HAL UDI for the mountable
8900 * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
8905 * G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC:
8907 * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE)
8908 * is automatically polled for media.
8909 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
8916 * G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE:
8918 * A key in the "mountable" namespace for getting the #GDriveStartStopType.
8919 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
8926 * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE:
8928 * A key in the "mountable" namespace for getting the unix device.
8929 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
8934 * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE:
8936 * A key in the "mountable" namespace for getting the unix device file.
8937 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
8944 * G_FILE_ATTRIBUTE_OWNER_GROUP:
8946 * A key in the "owner" namespace for getting the file owner's group.
8947 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
8952 * G_FILE_ATTRIBUTE_OWNER_USER:
8954 * A key in the "owner" namespace for getting the user name of the
8955 * file's owner. Corresponding #GFileAttributeType is
8956 * %G_FILE_ATTRIBUTE_TYPE_STRING.
8961 * G_FILE_ATTRIBUTE_OWNER_USER_REAL:
8963 * A key in the "owner" namespace for getting the real name of the
8964 * user that owns the file. Corresponding #GFileAttributeType is
8965 * %G_FILE_ATTRIBUTE_TYPE_STRING.
8970 * G_FILE_ATTRIBUTE_PREVIEW_ICON:
8972 * A key in the "preview" namespace for getting a #GIcon that can be
8973 * used to get preview of the file. For example, it may be a low
8974 * resolution thumbnail without metadata. Corresponding
8975 * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value
8976 * for this key should contain a #GIcon.
8983 * G_FILE_ATTRIBUTE_SELINUX_CONTEXT:
8985 * A key in the "selinux" namespace for getting the file's SELinux
8986 * context. Corresponding #GFileAttributeType is
8987 * %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only
8988 * available if GLib has been built with SELinux support.
8993 * G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE:
8995 * A key in the "standard" namespace for getting the amount of disk space
8996 * that is consumed by the file (in bytes). This will generally be larger
8997 * than the file size (due to block size overhead) but can occasionally be
8998 * smaller (for example, for sparse files).
8999 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
9006 * G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE:
9008 * A key in the "standard" namespace for getting the content type of the file.
9009 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
9010 * The value for this key should contain a valid content type.
9015 * G_FILE_ATTRIBUTE_STANDARD_COPY_NAME:
9017 * A key in the "standard" namespace for getting the copy name of the file.
9018 * The copy name is an optional version of the name. If available it's always
9019 * in UTF8, and corresponds directly to the original filename (only transcoded to
9020 * UTF8). This is useful if you want to copy the file to another filesystem that
9021 * might have a different encoding. If the filename is not a valid string in the
9022 * encoding selected for the filesystem it is in then the copy name will not be set.
9024 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
9029 * G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION:
9031 * A key in the "standard" namespace for getting the description of the file.
9032 * The description is a utf8 string that describes the file, generally containing
9033 * the filename, but can also contain furter information. Example descriptions
9034 * could be "filename (on hostname)" for a remote file or "filename (in trash)"
9035 * for a file in the trash. This is useful for instance as the window title
9036 * when displaying a directory or for a bookmarks menu.
9038 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
9043 * G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME:
9045 * A key in the "standard" namespace for getting the display name of the file.
9046 * A display name is guaranteed to be in UTF8 and can thus be displayed in
9048 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
9053 * G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME:
9055 * A key in the "standard" namespace for edit name of the file.
9056 * An edit name is similar to the display name, but it is meant to be
9057 * used when you want to rename the file in the UI. The display name
9058 * might contain information you don't want in the new filename (such as
9059 * "(invalid unicode)" if the filename was in an invalid encoding).
9061 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
9066 * G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE:
9068 * A key in the "standard" namespace for getting the fast content type.
9069 * The fast content type isn't as reliable as the regular one, as it
9070 * only uses the filename to guess it, but it is faster to calculate than the
9071 * regular content type.
9072 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
9077 * G_FILE_ATTRIBUTE_STANDARD_ICON:
9079 * A key in the "standard" namespace for getting the icon for the file.
9080 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT.
9081 * The value for this key should contain a #GIcon.
9086 * G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP:
9088 * A key in the "standard" namespace for checking if a file is a backup file.
9089 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
9094 * G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN:
9096 * A key in the "standard" namespace for checking if a file is hidden.
9097 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
9102 * G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK:
9104 * A key in the "standard" namespace for checking if the file is a symlink.
9105 * Typically the actual type is something else, if we followed the symlink
9107 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
9112 * G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL:
9114 * A key in the "standard" namespace for checking if a file is virtual.
9115 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
9120 * G_FILE_ATTRIBUTE_STANDARD_NAME:
9122 * A key in the "standard" namespace for getting the name of the file.
9123 * The name is the on-disk filename which may not be in any known encoding,
9124 * and can thus not be generally displayed as is.
9125 * Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the
9126 * name in a user interface.
9127 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
9132 * G_FILE_ATTRIBUTE_STANDARD_SIZE:
9134 * A key in the "standard" namespace for getting the file's size (in bytes).
9135 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
9140 * G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER:
9142 * A key in the "standard" namespace for setting the sort order of a file.
9143 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32.
9144 * An example use would be in file managers, which would use this key
9145 * to set the order files are displayed. Files with smaller sort order
9146 * should be sorted first, and files without sort order as if sort order
9152 * G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET:
9154 * A key in the "standard" namespace for getting the symlink target, if the file
9155 * is a symlink. Corresponding #GFileAttributeType is
9156 * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
9161 * G_FILE_ATTRIBUTE_STANDARD_TARGET_URI:
9163 * A key in the "standard" namespace for getting the target URI for the file, in
9164 * the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files.
9165 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
9170 * G_FILE_ATTRIBUTE_STANDARD_TYPE:
9172 * A key in the "standard" namespace for storing file types.
9173 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
9174 * The value for this key should contain a #GFileType.
9179 * G_FILE_ATTRIBUTE_THUMBNAILING_FAILED:
9181 * A key in the "thumbnail" namespace for checking if thumbnailing failed.
9182 * This attribute is %TRUE if thumbnailing failed. Corresponding
9183 * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
9188 * G_FILE_ATTRIBUTE_THUMBNAIL_PATH:
9190 * A key in the "thumbnail" namespace for getting the path to the thumbnail
9191 * image. Corresponding #GFileAttributeType is
9192 * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
9197 * G_FILE_ATTRIBUTE_TIME_ACCESS:
9199 * A key in the "time" namespace for getting the time the file was last
9200 * accessed. Corresponding #GFileAttributeType is
9201 * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the
9202 * file was last accessed.
9207 * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC:
9209 * A key in the "time" namespace for getting the microseconds of the time
9210 * the file was last accessed. This should be used in conjunction with
9211 * #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is
9212 * %G_FILE_ATTRIBUTE_TYPE_UINT32.
9217 * G_FILE_ATTRIBUTE_TIME_CHANGED:
9219 * A key in the "time" namespace for getting the time the file was last
9220 * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
9221 * and contains the UNIX time since the file was last changed.
9223 * This corresponds to the traditional UNIX ctime.
9228 * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC:
9230 * A key in the "time" namespace for getting the microseconds of the time
9231 * the file was last changed. This should be used in conjunction with
9232 * #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is
9233 * %G_FILE_ATTRIBUTE_TYPE_UINT32.
9238 * G_FILE_ATTRIBUTE_TIME_CREATED:
9240 * A key in the "time" namespace for getting the time the file was created.
9241 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
9242 * and contains the UNIX time since the file was created.
9244 * This corresponds to the NTFS ctime.
9249 * G_FILE_ATTRIBUTE_TIME_CREATED_USEC:
9251 * A key in the "time" namespace for getting the microseconds of the time
9252 * the file was created. This should be used in conjunction with
9253 * #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is
9254 * %G_FILE_ATTRIBUTE_TYPE_UINT32.
9259 * G_FILE_ATTRIBUTE_TIME_MODIFIED:
9261 * A key in the "time" namespace for getting the time the file was last
9262 * modified. Corresponding #GFileAttributeType is
9263 * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the
9264 * file was modified.
9269 * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC:
9271 * A key in the "time" namespace for getting the miliseconds of the time
9272 * the file was last modified. This should be used in conjunction with
9273 * #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is
9274 * %G_FILE_ATTRIBUTE_TYPE_UINT32.
9279 * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE:
9281 * A key in the "trash" namespace. When requested against
9282 * items in "trash:///", will return the date and time when the file
9283 * was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss.
9284 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
9291 * G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT:
9293 * A key in the "trash" namespace. When requested against
9294 * "trash:///" returns the number of (toplevel) items in the trash folder.
9295 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
9300 * G_FILE_ATTRIBUTE_TRASH_ORIG_PATH:
9302 * A key in the "trash" namespace. When requested against
9303 * items in "trash:///", will return the original path to the file before it
9304 * was trashed. Corresponding #GFileAttributeType is
9305 * %G_FILE_ATTRIBUTE_TYPE_STRING.
9312 * G_FILE_ATTRIBUTE_UNIX_BLOCKS:
9314 * A key in the "unix" namespace for getting the number of blocks allocated
9315 * for the file. This attribute is only available for UNIX file systems.
9316 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
9321 * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE:
9323 * A key in the "unix" namespace for getting the block size for the file
9324 * system. This attribute is only available for UNIX file systems.
9325 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
9330 * G_FILE_ATTRIBUTE_UNIX_DEVICE:
9332 * A key in the "unix" namespace for getting the device id of the device the
9333 * file is located on (see stat() documentation). This attribute is only
9334 * available for UNIX file systems. Corresponding #GFileAttributeType is
9335 * %G_FILE_ATTRIBUTE_TYPE_UINT32.
9340 * G_FILE_ATTRIBUTE_UNIX_GID:
9342 * A key in the "unix" namespace for getting the group ID for the file.
9343 * This attribute is only available for UNIX file systems.
9344 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
9349 * G_FILE_ATTRIBUTE_UNIX_INODE:
9351 * A key in the "unix" namespace for getting the inode of the file.
9352 * This attribute is only available for UNIX file systems. Corresponding
9353 * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
9358 * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT:
9360 * A key in the "unix" namespace for checking if the file represents a
9361 * UNIX mount point. This attribute is %TRUE if the file is a UNIX mount
9362 * point. This attribute is only available for UNIX file systems.
9363 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
9368 * G_FILE_ATTRIBUTE_UNIX_MODE:
9370 * A key in the "unix" namespace for getting the mode of the file
9371 * (e.g. whether the file is a regular file, symlink, etc). See lstat()
9372 * documentation. This attribute is only available for UNIX file systems.
9373 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
9378 * G_FILE_ATTRIBUTE_UNIX_NLINK:
9380 * A key in the "unix" namespace for getting the number of hard links
9381 * for a file. See lstat() documentation. This attribute is only available
9382 * for UNIX file systems. Corresponding #GFileAttributeType is
9383 * %G_FILE_ATTRIBUTE_TYPE_UINT32.
9388 * G_FILE_ATTRIBUTE_UNIX_RDEV:
9390 * A key in the "unix" namespace for getting the device ID for the file
9391 * (if it is a special file). See lstat() documentation. This attribute
9392 * is only available for UNIX file systems. Corresponding #GFileAttributeType
9393 * is %G_FILE_ATTRIBUTE_TYPE_UINT32.
9398 * G_FILE_ATTRIBUTE_UNIX_UID:
9400 * A key in the "unix" namespace for getting the user ID for the file.
9401 * This attribute is only available for UNIX file systems.
9402 * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
9408 * @class: a valid #GFlagsClass
9410 * Casts a derived #GFlagsClass structure into a #GFlagsClass structure.
9415 * G_FLAGS_CLASS_TYPE:
9416 * @class: a #GFlagsClass
9418 * Get the type identifier from a given #GFlagsClass structure.
9420 * Returns: the #GType
9425 * G_FLAGS_CLASS_TYPE_NAME:
9426 * @class: a #GFlagsClass
9428 * Get the static type name from a given #GFlagsClass structure.
9430 * Returns: the type name.
9435 * G_IMPLEMENT_INTERFACE:
9436 * @TYPE_IFACE: The #GType of the interface to add
9437 * @iface_init: The interface init function
9439 * A convenience macro to ease interface addition in the @_C_ section
9440 * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
9441 * See G_DEFINE_TYPE_EXTENDED() for an example.
9443 * Note that this macro can only be used together with the G_DEFINE_TYPE_*
9444 * macros, since it depends on variable names from those macros.
9451 * G_IMPLEMENT_INTERFACE_DYNAMIC:
9452 * @TYPE_IFACE: The #GType of the interface to add
9453 * @iface_init: The interface init function
9455 * A convenience macro to ease interface addition in the @_C_ section
9456 * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED()
9459 * Note that this macro can only be used together with the
9460 * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
9461 * names from that macro.
9468 * G_INITIALLY_UNOWNED:
9469 * @object: Object which is subject to casting.
9471 * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*)
9472 * pointer. Depending on the current debugging level, this function may invoke
9473 * certain runtime checks to identify invalid casts.
9478 * G_INITIALLY_UNOWNED_CLASS:
9479 * @class: a valid #GInitiallyUnownedClass
9481 * Casts a derived #GInitiallyUnownedClass structure into a
9482 * #GInitiallyUnownedClass structure.
9487 * G_INITIALLY_UNOWNED_GET_CLASS:
9488 * @object: a #GInitiallyUnowned instance.
9490 * Get the class structure associated to a #GInitiallyUnowned instance.
9492 * Returns: pointer to object class structure.
9499 * Error domain for GIO. Errors in this domain will be from the #GIOErrorEnum enumeration.
9500 * See #GError for more information on error domains.
9506 * @class: a #GEnumClass
9508 * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM
9515 * @class: a #GFlagsClass
9517 * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS
9523 * G_IS_INITIALLY_UNOWNED:
9524 * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED.
9526 * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED.
9531 * G_IS_INITIALLY_UNOWNED_CLASS:
9532 * @class: a #GInitiallyUnownedClass
9534 * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type
9535 * %G_TYPE_INITIALLY_UNOWNED or derived.
9541 * @object: Instance to check for being a %G_TYPE_OBJECT.
9543 * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
9548 * G_IS_OBJECT_CLASS:
9549 * @class: a #GObjectClass
9551 * Checks whether @class "is a" valid #GObjectClass structure of type
9552 * %G_TYPE_OBJECT or derived.
9558 * @pspec: a #GParamSpec
9560 * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM
9566 * G_IS_PARAM_SPEC_BOOLEAN:
9567 * @pspec: a valid #GParamSpec instance
9569 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN.
9571 * Returns: %TRUE on success.
9576 * G_IS_PARAM_SPEC_BOXED:
9577 * @pspec: a valid #GParamSpec instance
9579 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED.
9581 * Returns: %TRUE on success.
9586 * G_IS_PARAM_SPEC_CHAR:
9587 * @pspec: a valid #GParamSpec instance
9589 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR.
9591 * Returns: %TRUE on success.
9596 * G_IS_PARAM_SPEC_CLASS:
9597 * @pclass: a #GParamSpecClass
9599 * Checks whether @pclass "is a" valid #GParamSpecClass structure of type
9600 * %G_TYPE_PARAM or derived.
9605 * G_IS_PARAM_SPEC_DOUBLE:
9606 * @pspec: a valid #GParamSpec instance
9608 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE.
9610 * Returns: %TRUE on success.
9615 * G_IS_PARAM_SPEC_ENUM:
9616 * @pspec: a valid #GParamSpec instance
9618 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM.
9620 * Returns: %TRUE on success.
9625 * G_IS_PARAM_SPEC_FLAGS:
9626 * @pspec: a valid #GParamSpec instance
9628 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS.
9630 * Returns: %TRUE on success.
9635 * G_IS_PARAM_SPEC_FLOAT:
9636 * @pspec: a valid #GParamSpec instance
9638 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT.
9640 * Returns: %TRUE on success.
9645 * G_IS_PARAM_SPEC_GTYPE:
9646 * @pspec: a #GParamSpec
9648 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE.
9651 * Returns: %TRUE on success.
9656 * G_IS_PARAM_SPEC_INT:
9657 * @pspec: a valid #GParamSpec instance
9659 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT.
9661 * Returns: %TRUE on success.
9666 * G_IS_PARAM_SPEC_INT64:
9667 * @pspec: a valid #GParamSpec instance
9669 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64.
9671 * Returns: %TRUE on success.
9676 * G_IS_PARAM_SPEC_LONG:
9677 * @pspec: a valid #GParamSpec instance
9679 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG.
9681 * Returns: %TRUE on success.
9686 * G_IS_PARAM_SPEC_OBJECT:
9687 * @pspec: a valid #GParamSpec instance
9689 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT.
9691 * Returns: %TRUE on success.
9696 * G_IS_PARAM_SPEC_OVERRIDE:
9697 * @pspec: a #GParamSpec
9699 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE.
9702 * Returns: %TRUE on success.
9707 * G_IS_PARAM_SPEC_PARAM:
9708 * @pspec: a valid #GParamSpec instance
9710 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM.
9712 * Returns: %TRUE on success.
9717 * G_IS_PARAM_SPEC_POINTER:
9718 * @pspec: a valid #GParamSpec instance
9720 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER.
9722 * Returns: %TRUE on success.
9727 * G_IS_PARAM_SPEC_STRING:
9728 * @pspec: a valid #GParamSpec instance
9730 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING.
9732 * Returns: %TRUE on success.
9737 * G_IS_PARAM_SPEC_UCHAR:
9738 * @pspec: a valid #GParamSpec instance
9740 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR.
9742 * Returns: %TRUE on success.
9747 * G_IS_PARAM_SPEC_UINT:
9748 * @pspec: a valid #GParamSpec instance
9750 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT.
9752 * Returns: %TRUE on success.
9757 * G_IS_PARAM_SPEC_UINT64:
9758 * @pspec: a valid #GParamSpec instance
9760 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64.
9762 * Returns: %TRUE on success.
9767 * G_IS_PARAM_SPEC_ULONG:
9768 * @pspec: a valid #GParamSpec instance
9770 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG.
9772 * Returns: %TRUE on success.
9777 * G_IS_PARAM_SPEC_UNICHAR:
9778 * @pspec: a valid #GParamSpec instance
9780 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR.
9782 * Returns: %TRUE on success.
9787 * G_IS_PARAM_SPEC_VALUE_ARRAY:
9788 * @pspec: a valid #GParamSpec instance
9790 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.
9792 * Returns: %TRUE on success.
9793 * Deprecated: 2.32: Use #GArray instead of #GValueArray
9798 * G_IS_PARAM_SPEC_VARIANT:
9799 * @pspec: a #GParamSpec
9801 * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT.
9803 * Returns: %TRUE on success
9810 * @value: A #GValue structure.
9812 * Checks if @value is a valid and initialized #GValue structure.
9814 * Returns: %TRUE on success.
9821 * Error domain for markup parsing.
9822 * Errors in this domain will be from the #GMarkupError enumeration.
9823 * See #GError for information on error domains.
9828 * G_NETWORK_MONITOR_EXTENSION_POINT_NAME:
9830 * Extension point for network status monitoring functionality.
9831 * See <link linkend="extending-gio">Extending GIO</link>.
9841 * Returns %TRUE if a #GNode is a leaf node.
9843 * (i.e. it has no children)
9845 * Returns: %TRUE if the #GNode is a leaf node
9853 * Returns %TRUE if a #GNode is the root of a tree.
9855 * (i.e. it has no parent or siblings)
9857 * Returns: %TRUE if the #GNode is the root of a tree
9863 * @object: Object which is subject to casting.
9865 * Casts a #GObject or derived pointer into a (GObject*) pointer.
9866 * Depending on the current debugging level, this function may invoke
9867 * certain runtime checks to identify invalid casts.
9873 * @class: a valid #GObjectClass
9875 * Casts a derived #GObjectClass structure into a #GObjectClass structure.
9880 * G_OBJECT_CLASS_NAME:
9881 * @class: a valid #GObjectClass
9883 * Return the name of a class structure's type.
9885 * should not be freed.
9887 * Returns: Type name of @class. The string is owned by the type system and
9892 * G_OBJECT_CLASS_TYPE:
9893 * @class: a valid #GObjectClass
9895 * Get the type id of a class structure.
9897 * Returns: Type id of @class.
9902 * G_OBJECT_GET_CLASS:
9903 * @object: a #GObject instance.
9905 * Get the class structure associated to a #GObject instance.
9907 * Returns: pointer to object class structure.
9913 * @object: Object to return the type id for.
9915 * Get the type id of an object.
9917 * Returns: Type id of @object.
9922 * G_OBJECT_TYPE_NAME:
9923 * @object: Object to return the type name for.
9925 * Get the name of an object's type.
9927 * should not be freed.
9929 * Returns: Type name of @object. The string is owned by the type system and
9934 * G_OBJECT_WARN_INVALID_PROPERTY_ID:
9935 * @object: the #GObject on which set_property() or get_property() was called
9936 * @property_id: the numeric id of the property
9937 * @pspec: the #GParamSpec of the property
9939 * This macro should be used to emit a standard warning about unexpected
9940 * properties in set_property() and get_property() implementations.
9947 * Error domain for option parsing. Errors in this domain will
9948 * be from the #GOptionError enumeration. See #GError for information on
9954 * G_OPTION_REMAINING:
9956 * If a long option in the main group has this name, it is not treated as a
9957 * regular option. Instead it collects all non-option arguments which would
9958 * otherwise be left in <literal>argv</literal>. The option must be of type
9959 * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
9960 * or %G_OPTION_ARG_FILENAME_ARRAY.
9963 * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
9964 * for leftover arguments has the advantage that GOption takes care of
9965 * necessary encoding conversions for strings or filenames.
9974 * Mask containing the bits of #GParamSpec.flags which are reserved for GLib.
9979 * G_PARAM_READWRITE:
9981 * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE.
9987 * @pspec: a valid #GParamSpec
9989 * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into
9990 * a #GParamSpec object.
9995 * G_PARAM_SPEC_BOOLEAN:
9996 * @pspec: a valid #GParamSpec instance
9998 * Cast a #GParamSpec instance into a #GParamSpecBoolean.
10003 * G_PARAM_SPEC_BOXED:
10004 * @pspec: a valid #GParamSpec instance
10006 * Cast a #GParamSpec instance into a #GParamSpecBoxed.
10011 * G_PARAM_SPEC_CHAR:
10012 * @pspec: a valid #GParamSpec instance
10014 * Cast a #GParamSpec instance into a #GParamSpecChar.
10019 * G_PARAM_SPEC_CLASS:
10020 * @pclass: a valid #GParamSpecClass
10022 * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure.
10027 * G_PARAM_SPEC_DOUBLE:
10028 * @pspec: a valid #GParamSpec instance
10030 * Cast a #GParamSpec instance into a #GParamSpecDouble.
10035 * G_PARAM_SPEC_ENUM:
10036 * @pspec: a valid #GParamSpec instance
10038 * Cast a #GParamSpec instance into a #GParamSpecEnum.
10043 * G_PARAM_SPEC_FLAGS:
10044 * @pspec: a valid #GParamSpec instance
10046 * Cast a #GParamSpec instance into a #GParamSpecFlags.
10051 * G_PARAM_SPEC_FLOAT:
10052 * @pspec: a valid #GParamSpec instance
10054 * Cast a #GParamSpec instance into a #GParamSpecFloat.
10059 * G_PARAM_SPEC_GET_CLASS:
10060 * @pspec: a valid #GParamSpec
10062 * Retrieves the #GParamSpecClass of a #GParamSpec.
10067 * G_PARAM_SPEC_GTYPE:
10068 * @pspec: a #GParamSpec
10070 * Casts a #GParamSpec into a #GParamSpecGType.
10077 * G_PARAM_SPEC_INT:
10078 * @pspec: a valid #GParamSpec instance
10080 * Cast a #GParamSpec instance into a #GParamSpecInt.
10085 * G_PARAM_SPEC_INT64:
10086 * @pspec: a valid #GParamSpec instance
10088 * Cast a #GParamSpec instance into a #GParamSpecInt64.
10093 * G_PARAM_SPEC_LONG:
10094 * @pspec: a valid #GParamSpec instance
10096 * Cast a #GParamSpec instance into a #GParamSpecLong.
10101 * G_PARAM_SPEC_OBJECT:
10102 * @pspec: a valid #GParamSpec instance
10104 * Casts a #GParamSpec instance into a #GParamSpecObject.
10109 * G_PARAM_SPEC_OVERRIDE:
10110 * @pspec: a #GParamSpec
10112 * Casts a #GParamSpec into a #GParamSpecOverride.
10119 * G_PARAM_SPEC_PARAM:
10120 * @pspec: a valid #GParamSpec instance
10122 * Casts a #GParamSpec instance into a #GParamSpecParam.
10127 * G_PARAM_SPEC_POINTER:
10128 * @pspec: a valid #GParamSpec instance
10130 * Casts a #GParamSpec instance into a #GParamSpecPointer.
10135 * G_PARAM_SPEC_STRING:
10136 * @pspec: a valid #GParamSpec instance
10138 * Casts a #GParamSpec instance into a #GParamSpecString.
10143 * G_PARAM_SPEC_TYPE:
10144 * @pspec: a valid #GParamSpec
10146 * Retrieves the #GType of this @pspec.
10151 * G_PARAM_SPEC_TYPE_NAME:
10152 * @pspec: a valid #GParamSpec
10154 * Retrieves the #GType name of this @pspec.
10159 * G_PARAM_SPEC_UCHAR:
10160 * @pspec: a valid #GParamSpec instance
10162 * Cast a #GParamSpec instance into a #GParamSpecUChar.
10167 * G_PARAM_SPEC_UINT:
10168 * @pspec: a valid #GParamSpec instance
10170 * Cast a #GParamSpec instance into a #GParamSpecUInt.
10175 * G_PARAM_SPEC_UINT64:
10176 * @pspec: a valid #GParamSpec instance
10178 * Cast a #GParamSpec instance into a #GParamSpecUInt64.
10183 * G_PARAM_SPEC_ULONG:
10184 * @pspec: a valid #GParamSpec instance
10186 * Cast a #GParamSpec instance into a #GParamSpecULong.
10191 * G_PARAM_SPEC_UNICHAR:
10192 * @pspec: a valid #GParamSpec instance
10194 * Cast a #GParamSpec instance into a #GParamSpecUnichar.
10199 * G_PARAM_SPEC_VALUE_ARRAY:
10200 * @pspec: a valid #GParamSpec instance
10202 * Cast a #GParamSpec instance into a #GParamSpecValueArray.
10204 * Deprecated: 2.32: Use #GArray instead of #GValueArray
10209 * G_PARAM_SPEC_VALUE_TYPE:
10210 * @pspec: a valid #GParamSpec
10212 * Retrieves the #GType to initialize a #GValue for this parameter.
10217 * G_PARAM_SPEC_VARIANT:
10218 * @pspec: a #GParamSpec
10220 * Casts a #GParamSpec into a #GParamSpecVariant.
10227 * G_PARAM_STATIC_STRINGS:
10229 * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB.
10236 * G_PARAM_USER_SHIFT:
10238 * Minimum shift count to be used for user defined flags, to be stored in
10239 * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT.
10244 * G_PRIORITY_DEFAULT:
10246 * Use this for default priority event sources.
10248 * In GLib this priority is used when adding timeout functions
10249 * with g_timeout_add(). In GDK this priority is used for events
10250 * from the X server.
10255 * G_PRIORITY_DEFAULT_IDLE:
10257 * Use this for default priority idle functions.
10259 * In GLib this priority is used when adding idle functions with
10267 * Use this for high priority event sources.
10269 * It is not used within GLib or GTK+.
10274 * G_PRIORITY_HIGH_IDLE:
10276 * Use this for high priority idle functions.
10278 * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
10279 * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
10280 * done to ensure that any pending resizes are processed before any
10281 * pending redraws, so that widgets are not redrawn twice unnecessarily.)
10288 * Use this for very low priority background tasks.
10290 * It is not used within GLib or GTK+.
10295 * G_PROXY_EXTENSION_POINT_NAME:
10297 * Extension point for proxy functionality.
10298 * See <link linkend="extending-gio">Extending GIO</link>.
10305 * G_PROXY_RESOLVER_EXTENSION_POINT_NAME:
10307 * Extension point for proxy resolving functionality.
10308 * See <link linkend="extending-gio">Extending GIO</link>.
10315 * A statically-allocated #GQueue must be initialized with this
10316 * macro before it can be used. This macro can be used to initialize
10317 * a variable, but it cannot be assigned to a variable. In that case
10318 * you have to use g_queue_init().
10321 * GQueue my_queue = G_QUEUE_INIT;
10331 * Error domain for regular expressions. Errors in this domain will be
10332 * from the #GRegexError enumeration. See #GError for information on
10340 * G_RESOLVER_ERROR:
10342 * Error domain for #GResolver. Errors in this domain will be from the
10343 * #GResolverError enumeration. See #GError for more information on
10349 * G_RESOURCE_ERROR:
10351 * Error domain for #GResource. Errors in this domain will be from the
10352 * #GResourceError enumeration. See #GError for more information on
10358 * G_SETTINGS_BACKEND_EXTENSION_POINT_NAME:
10360 * Extension point for #GSettingsBackend functionality.
10365 * G_SIGNAL_FLAGS_MASK:
10367 * A mask for all #GSignalFlags bits.
10372 * G_SIGNAL_MATCH_MASK:
10374 * A mask for all #GSignalMatchType bits.
10379 * G_SIGNAL_TYPE_STATIC_SCOPE:
10381 * This macro flags signal argument types for which the signal system may
10382 * assume that instances thereof remain persistent across all signal emissions
10383 * they are used in. This is only useful for non ref-counted, value-copy types.
10385 * To flag a signal argument in this way, add
10386 * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
10387 * of g_signal_new().
10389 * g_signal_new ("size_request",
10390 * G_TYPE_FROM_CLASS (gobject_class),
10391 * G_SIGNAL_RUN_FIRST,
10392 * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
10394 * _gtk_marshal_VOID__BOXED,
10396 * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
10402 * G_SOURCE_CONTINUE:
10404 * Use this macro as the return value of a #GSourceFunc to leave
10405 * the #GSource in the main loop.
10414 * Use this macro as the return value of a #GSourceFunc to remove
10415 * the #GSource from the main loop.
10424 * Error domain for spawning processes. Errors in this domain will
10425 * be from the #GSpawnError enumeration. See #GError for information on
10433 * Evaluates to a time span of one day.
10440 * G_TIME_SPAN_HOUR:
10442 * Evaluates to a time span of one hour.
10449 * G_TIME_SPAN_MILLISECOND:
10451 * Evaluates to a time span of one millisecond.
10458 * G_TIME_SPAN_MINUTE:
10460 * Evaluates to a time span of one minute.
10467 * G_TIME_SPAN_SECOND:
10469 * Evaluates to a time span of one second.
10476 * G_TLS_BACKEND_EXTENSION_POINT_NAME:
10478 * Extension point for TLS functionality via #GTlsBackend.
10479 * See <link linkend="extending-gio">Extending GIO</link>.
10484 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT:
10486 * The purpose used to verify the client certificate in a TLS connection.
10487 * Used by TLS servers.
10492 * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER:
10494 * The purpose used to verify the server certificate in a TLS connection. This
10495 * is the most common purpose in use. Used by TLS clients.
10502 * Error domain for TLS. Errors in this domain will be from the
10503 * #GTlsError enumeration. See #GError for more information on error
10511 * The #GType for a boxed type holding a #GArray reference.
10520 * The fundamental type corresponding to #gboolean.
10527 * The fundamental type from which all boxed types are derived.
10534 * The #GType for #GBytes.
10541 * G_TYPE_BYTE_ARRAY:
10543 * The #GType for a boxed type holding a #GByteArray reference.
10552 * The fundamental type corresponding to #gchar.
10553 * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
10554 * This may or may not be the same type a the C type "gchar".
10559 * G_TYPE_CHECK_CLASS_CAST:
10560 * @g_class: Location of a #GTypeClass structure.
10561 * @g_type: The type to be returned.
10562 * @c_type: The corresponding C type of class structure of @g_type.
10564 * Checks that @g_class is a class structure of the type identified by @g_type
10565 * and issues a warning if this is not the case. Returns @g_class casted
10566 * to a pointer to @c_type.
10568 * This macro should only be used in type implementations.
10573 * G_TYPE_CHECK_CLASS_TYPE:
10574 * @g_class: Location of a #GTypeClass structure.
10575 * @g_type: The type to be checked.
10577 * Checks if @g_class is a class structure of the type identified by
10580 * This macro should only be used in type implementations.
10582 * Returns: %TRUE on success.
10587 * G_TYPE_CHECK_INSTANCE:
10588 * @instance: Location of a #GTypeInstance structure.
10590 * Checks if @instance is a valid #GTypeInstance structure,
10591 * otherwise issues a warning and returns %FALSE.
10593 * This macro should only be used in type implementations.
10595 * Returns: %TRUE on success.
10600 * G_TYPE_CHECK_INSTANCE_CAST:
10601 * @instance: Location of a #GTypeInstance structure.
10602 * @g_type: The type to be returned.
10603 * @c_type: The corresponding C type of @g_type.
10605 * Checks that @instance is an instance of the type identified by @g_type
10606 * and issues a warning if this is not the case. Returns @instance casted
10607 * to a pointer to @c_type.
10609 * This macro should only be used in type implementations.
10614 * G_TYPE_CHECK_INSTANCE_TYPE:
10615 * @instance: Location of a #GTypeInstance structure.
10616 * @g_type: The type to be checked
10618 * Checks if @instance is an instance of the type identified by @g_type.
10620 * This macro should only be used in type implementations.
10622 * Returns: %TRUE on success.
10627 * G_TYPE_CHECK_VALUE:
10628 * @value: a #GValue
10630 * Checks if @value has been initialized to hold values
10633 * This macro should only be used in type implementations.
10635 * Returns: %TRUE on success.
10640 * G_TYPE_CHECK_VALUE_TYPE:
10641 * @value: a #GValue
10642 * @g_type: The type to be checked.
10644 * Checks if @value has been initialized to hold values
10647 * This macro should only be used in type implementations.
10649 * Returns: %TRUE on success.
10654 * G_TYPE_CLASS_GET_PRIVATE:
10655 * @klass: the class of a type deriving from @private_type.
10656 * @g_type: the type identifying which private data to retrieve.
10657 * @c_type: The C type for the private structure.
10659 * Gets the private class structure for a particular type.
10660 * The private structure must have been registered in the
10661 * get_type() function with g_type_add_class_private().
10663 * This macro should only be used in type implementations.
10666 * Returns: a pointer to the private data structure.
10673 * The #GType for #GClosure.
10680 * The #GType for #GDate.
10685 * G_TYPE_DATE_TIME:
10687 * The #GType for a boxed type holding a #GDateTime.
10694 * G_TYPE_DBUS_ANNOTATION_INFO:
10696 * The #GType for a boxed type holding a #GDBusAnnotationInfo.
10703 * G_TYPE_DBUS_ARG_INFO:
10705 * The #GType for a boxed type holding a #GDBusArgInfo.
10712 * G_TYPE_DBUS_INTERFACE_INFO:
10714 * The #GType for a boxed type holding a #GDBusInterfaceInfo.
10721 * G_TYPE_DBUS_METHOD_INFO:
10723 * The #GType for a boxed type holding a #GDBusMethodInfo.
10730 * G_TYPE_DBUS_NODE_INFO:
10732 * The #GType for a boxed type holding a #GDBusNodeInfo.
10739 * G_TYPE_DBUS_PROPERTY_INFO:
10741 * The #GType for a boxed type holding a #GDBusPropertyInfo.
10748 * G_TYPE_DBUS_SIGNAL_INFO:
10750 * The #GType for a boxed type holding a #GDBusSignalInfo.
10759 * The fundamental type corresponding to #gdouble.
10766 * The fundamental type from which all enumeration types are derived.
10773 * The #GType for a boxed type holding a #GError.
10782 * The fundamental type from which all flags types are derived.
10787 * G_TYPE_FLAG_RESERVED_ID_BIT:
10789 * A bit in the type number that's supposed to be left untouched.
10796 * The fundamental type corresponding to #gfloat.
10801 * G_TYPE_FROM_CLASS:
10802 * @g_class: Location of a valid #GTypeClass structure.
10804 * Get the type identifier from a given @class structure.
10806 * This macro should only be used in type implementations.
10808 * Returns: the #GType
10813 * G_TYPE_FROM_INSTANCE:
10814 * @instance: Location of a valid #GTypeInstance structure.
10816 * Get the type identifier from a given @instance structure.
10818 * This macro should only be used in type implementations.
10820 * Returns: the #GType
10825 * G_TYPE_FROM_INTERFACE:
10826 * @g_iface: Location of a valid #GTypeInterface structure.
10828 * Get the type identifier from a given @interface structure.
10830 * This macro should only be used in type implementations.
10832 * Returns: the #GType
10837 * G_TYPE_FUNDAMENTAL:
10838 * @type: A #GType value.
10840 * The fundamental type which is the ancestor of @type.
10841 * Fundamental types are types that serve as ultimate bases for the derived types,
10842 * thus they are the roots of distinct inheritance hierarchies.
10847 * G_TYPE_FUNDAMENTAL_MAX:
10849 * An integer constant that represents the number of identifiers reserved
10850 * for types that are assigned at compile-time.
10855 * G_TYPE_FUNDAMENTAL_SHIFT:
10857 * Shift value used in converting numbers to type IDs.
10864 * The #GType for #GString.
10871 * The type for #GType.
10876 * G_TYPE_HASH_TABLE:
10878 * The #GType for a boxed type holding a #GHashTable reference.
10885 * G_TYPE_HAS_VALUE_TABLE:
10886 * @type: A #GType value.
10888 * Checks if @type has a #GTypeValueTable.
10890 * Returns: %TRUE on success.
10895 * G_TYPE_INITIALLY_UNOWNED:
10897 * The type for #GInitiallyUnowned.
10902 * G_TYPE_INSTANCE_GET_CLASS:
10903 * @instance: Location of the #GTypeInstance structure.
10904 * @g_type: The #GType of the class to be returned.
10905 * @c_type: The C type of the class structure.
10907 * Get the class structure of a given @instance, casted
10908 * to a specified ancestor type @g_type of the instance.
10910 * Note that while calling a GInstanceInitFunc(), the class pointer gets
10911 * modified, so it might not always return the expected pointer.
10913 * This macro should only be used in type implementations.
10915 * Returns: a pointer to the class structure
10920 * G_TYPE_INSTANCE_GET_INTERFACE:
10921 * @instance: Location of the #GTypeInstance structure.
10922 * @g_type: The #GType of the interface to be returned.
10923 * @c_type: The C type of the interface structure.
10925 * Get the interface structure for interface @g_type of a given @instance.
10927 * This macro should only be used in type implementations.
10929 * Returns: a pointer to the interface structure
10934 * G_TYPE_INSTANCE_GET_PRIVATE:
10935 * @instance: the instance of a type deriving from @private_type.
10936 * @g_type: the type identifying which private data to retrieve.
10937 * @c_type: The C type for the private structure.
10939 * Gets the private structure for a particular type.
10940 * The private structure must have been registered in the
10941 * class_init function with g_type_class_add_private().
10943 * This macro should only be used in type implementations.
10946 * Returns: a pointer to the private data structure.
10953 * The fundamental type corresponding to #gint.
10960 * The fundamental type corresponding to #gint64.
10965 * G_TYPE_INTERFACE:
10967 * The fundamental type from which all interfaces are derived.
10974 * An invalid #GType used as error return value in some functions which return
10980 * G_TYPE_IO_CHANNEL:
10982 * The #GType for #GIOChannel.
10987 * G_TYPE_IO_CONDITION:
10989 * The #GType for #GIOCondition.
10994 * G_TYPE_IS_ABSTRACT:
10995 * @type: A #GType value.
10997 * Checks if @type is an abstract type. An abstract type cannot be
10998 * instantiated and is normally used as an abstract base class for
11001 * Returns: %TRUE on success.
11006 * G_TYPE_IS_CLASSED:
11007 * @type: A #GType value.
11009 * Checks if @type is a classed type.
11011 * Returns: %TRUE on success.
11016 * G_TYPE_IS_DEEP_DERIVABLE:
11017 * @type: A #GType value.
11019 * Checks if @type is a deep derivable type. A deep derivable type
11020 * can be used as the base class of a deep (multi-level) class hierarchy.
11022 * Returns: %TRUE on success.
11027 * G_TYPE_IS_DERIVABLE:
11028 * @type: A #GType value.
11030 * Checks if @type is a derivable type. A derivable type can
11031 * be used as the base class of a flat (single-level) class hierarchy.
11033 * Returns: %TRUE on success.
11038 * G_TYPE_IS_DERIVED:
11039 * @type: A #GType value.
11041 * Checks if @type is derived (or in object-oriented terminology:
11042 * inherited) from another type (this holds true for all non-fundamental
11045 * Returns: %TRUE on success.
11051 * @type: a #GType ID.
11053 * Checks whether @type "is a" %G_TYPE_ENUM.
11055 * Returns: %TRUE if @type "is a" %G_TYPE_ENUM.
11061 * @type: a #GType ID.
11063 * Checks whether @type "is a" %G_TYPE_FLAGS.
11065 * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS.
11070 * G_TYPE_IS_FUNDAMENTAL:
11071 * @type: A #GType value.
11073 * Checks if @type is a fundamental type.
11075 * Returns: %TRUE on success.
11080 * G_TYPE_IS_INSTANTIATABLE:
11081 * @type: A #GType value.
11083 * Checks if @type can be instantiated. Instantiation is the
11084 * process of creating an instance (object) of this type.
11086 * Returns: %TRUE on success.
11091 * G_TYPE_IS_INTERFACE:
11092 * @type: A #GType value.
11094 * Checks if @type is an interface type.
11095 * An interface type provides a pure API, the implementation
11096 * of which is provided by another type (which is then said to conform
11097 * to the interface). GLib interfaces are somewhat analogous to Java
11098 * interfaces and C++ classes containing only pure virtual functions,
11099 * with the difference that GType interfaces are not derivable (but see
11100 * g_type_interface_add_prerequisite() for an alternative).
11102 * Returns: %TRUE on success.
11107 * G_TYPE_IS_OBJECT:
11108 * @type: Type id to check
11110 * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it.
11112 * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
11118 * @type: a #GType ID
11120 * Checks whether @type "is a" %G_TYPE_PARAM.
11126 * @type: A #GType value.
11128 * Checks whether the passed in type ID can be used for g_value_init().
11129 * That is, this macro checks whether this type provides an implementation
11130 * of the #GTypeValueTable functions required for a type to create a #GValue of.
11132 * Returns: Whether @type is suitable as a #GValue type.
11137 * G_TYPE_IS_VALUE_ABSTRACT:
11138 * @type: A #GType value.
11140 * Checks if @type is an abstract value type. An abstract value type introduces
11141 * a value table, but can't be used for g_value_init() and is normally used as
11142 * an abstract base type for derived value types.
11144 * Returns: %TRUE on success.
11149 * G_TYPE_IS_VALUE_TYPE:
11150 * @type: A #GType value.
11152 * Checks if @type is a value type and can be used with g_value_init().
11154 * Returns: %TRUE on success.
11161 * The #GType for a boxed type holding a #GKeyFile.
11170 * The fundamental type corresponding to #glong.
11175 * G_TYPE_MAIN_CONTEXT:
11177 * The #GType for a boxed type holding a #GMainContext.
11184 * G_TYPE_MAIN_LOOP:
11186 * The #GType for a boxed type holding a #GMainLoop.
11193 * G_TYPE_MAKE_FUNDAMENTAL:
11194 * @x: the fundamental type number.
11196 * Get the type ID for the fundamental type number @x.
11197 * Use g_type_fundamental_next() instead of this macro to create new fundamental
11200 * Returns: the GType
11205 * G_TYPE_MATCH_INFO:
11207 * The #GType for a boxed type holding a #GMatchInfo reference.
11216 * A fundamental type which is used as a replacement for the C
11217 * <literal>void</literal> return type.
11224 * The fundamental type for #GObject.
11231 * The fundamental type from which all #GParamSpec types are derived.
11236 * G_TYPE_PARAM_BOOLEAN:
11238 * The #GType of #GParamSpecBoolean.
11243 * G_TYPE_PARAM_BOXED:
11245 * The #GType of #GParamSpecBoxed.
11250 * G_TYPE_PARAM_CHAR:
11252 * The #GType of #GParamSpecChar.
11257 * G_TYPE_PARAM_DOUBLE:
11259 * The #GType of #GParamSpecDouble.
11264 * G_TYPE_PARAM_ENUM:
11266 * The #GType of #GParamSpecEnum.
11271 * G_TYPE_PARAM_FLAGS:
11273 * The #GType of #GParamSpecFlags.
11278 * G_TYPE_PARAM_FLOAT:
11280 * The #GType of #GParamSpecFloat.
11285 * G_TYPE_PARAM_GTYPE:
11287 * The #GType of #GParamSpecGType.
11294 * G_TYPE_PARAM_INT:
11296 * The #GType of #GParamSpecInt.
11301 * G_TYPE_PARAM_INT64:
11303 * The #GType of #GParamSpecInt64.
11308 * G_TYPE_PARAM_LONG:
11310 * The #GType of #GParamSpecLong.
11315 * G_TYPE_PARAM_OBJECT:
11317 * The #GType of #GParamSpecObject.
11322 * G_TYPE_PARAM_OVERRIDE:
11324 * The #GType of #GParamSpecOverride.
11331 * G_TYPE_PARAM_PARAM:
11333 * The #GType of #GParamSpecParam.
11338 * G_TYPE_PARAM_POINTER:
11340 * The #GType of #GParamSpecPointer.
11345 * G_TYPE_PARAM_STRING:
11347 * The #GType of #GParamSpecString.
11352 * G_TYPE_PARAM_UCHAR:
11354 * The #GType of #GParamSpecUChar.
11359 * G_TYPE_PARAM_UINT:
11361 * The #GType of #GParamSpecUInt.
11366 * G_TYPE_PARAM_UINT64:
11368 * The #GType of #GParamSpecUInt64.
11373 * G_TYPE_PARAM_ULONG:
11375 * The #GType of #GParamSpecULong.
11380 * G_TYPE_PARAM_UNICHAR:
11382 * The #GType of #GParamSpecUnichar.
11387 * G_TYPE_PARAM_VALUE_ARRAY:
11389 * The #GType of #GParamSpecValueArray.
11391 * Deprecated: 2.32: Use #GArray instead of #GValueArray
11396 * G_TYPE_PARAM_VARIANT:
11398 * The #GType of #GParamSpecVariant.
11407 * The fundamental type corresponding to #gpointer.
11412 * G_TYPE_PTR_ARRAY:
11414 * The #GType for a boxed type holding a #GPtrArray reference.
11423 * The #GType for a boxed type holding a #GRegex reference.
11430 * G_TYPE_RESERVED_BSE_FIRST:
11432 * First fundamental type number to create a new fundamental type id with
11433 * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE.
11438 * G_TYPE_RESERVED_BSE_LAST:
11440 * Last fundamental type number reserved for BSE.
11445 * G_TYPE_RESERVED_GLIB_FIRST:
11447 * First fundamental type number to create a new fundamental type id with
11448 * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib.
11453 * G_TYPE_RESERVED_GLIB_LAST:
11455 * Last fundamental type number reserved for GLib.
11460 * G_TYPE_RESERVED_USER_FIRST:
11462 * First available fundamental type number to create new fundamental
11463 * type id with G_TYPE_MAKE_FUNDAMENTAL().
11470 * The #GType for #GResource.
11475 * G_TYPE_SETTINGS_SCHEMA:
11477 * A boxed #GType corresponding to #GSettingsSchema.
11484 * G_TYPE_SETTINGS_SCHEMA_SOURCE:
11486 * A boxed #GType corresponding to #GSettingsSchemaSource.
11495 * The #GType for a boxed type holding a #GSource.
11504 * The fundamental type corresponding to nul-terminated C strings.
11511 * The #GType for a boxed type holding a %NULL-terminated array of strings.
11513 * The code fragments in the following example show the use of a property of
11514 * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
11515 * and g_object_get().
11518 * g_object_class_install_property (object_class,
11520 * g_param_spec_boxed ("authors",
11522 * _("List of authors"),
11524 * G_PARAM_READWRITE));
11526 * gchar *authors[] = { "Owen", "Tim", NULL };
11527 * g_object_set (obj, "authors", authors, NULL);
11529 * gchar *writers[];
11530 * g_object_get (obj, "authors", &writers, NULL);
11531 * /* do something with writers */
11532 * g_strfreev (writers);
11542 * The fundamental type corresponding to #guchar.
11549 * The fundamental type corresponding to #guint.
11556 * The fundamental type corresponding to #guint64.
11563 * The fundamental type corresponding to #gulong.
11570 * The type ID of the "GValue" type which is a boxed type,
11571 * used to pass around pointers to GValues.
11576 * G_TYPE_VALUE_ARRAY:
11578 * The type ID of the "GValueArray" type which is a boxed type,
11579 * used to pass around pointers to GValueArrays.
11581 * Deprecated: 2.32: Use #GArray instead of #GValueArray
11588 * The fundamental type corresponding to #GVariant.
11590 * All floating #GVariant instances passed through the #GType system are
11593 * Note that callbacks in closures, and signal handlers
11594 * for signals of return type %G_TYPE_VARIANT, must never return floating
11597 * Note: GLib 2.24 did include a boxed type with this name. It was replaced
11598 * with this fundamental type in 2.26.
11605 * G_TYPE_VARIANT_BUILDER:
11607 * The #GType for a boxed type holding a #GVariantBuilder.
11614 * G_TYPE_VARIANT_TYPE:
11616 * The #GType for a boxed type holding a #GVariantType.
11623 * G_UNICHAR_MAX_DECOMPOSITION_LENGTH:
11625 * The maximum length (in codepoints) of a compatibility or canonical
11626 * decomposition of a single Unicode character.
11628 * This is as defined by Unicode 6.1.
11635 * G_UNICODE_COMBINING_MARK:
11637 * Older name for %G_UNICODE_SPACING_MARK.
11639 * Deprecated: 2.30: Use %G_UNICODE_SPACING_MARK.
11644 * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH:
11646 * Allowed characters in a path. Includes "!$&'()*+,;=:@/".
11651 * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT:
11653 * Allowed characters in path elements. Includes "!$&'()*+,;=:@".
11658 * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO:
11660 * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:".
11665 * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS:
11667 * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@".
11672 * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS:
11674 * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=".
11680 * @value: A #GValue structure.
11681 * @type: A #GType value.
11683 * Checks if @value holds (or contains) a value of @type.
11684 * This macro will also check for @value != %NULL and issue a
11685 * warning if the check fails.
11687 * Returns: %TRUE if @value holds the @type.
11692 * G_VALUE_HOLDS_BOOLEAN:
11693 * @value: a valid #GValue structure
11695 * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN.
11697 * Returns: %TRUE on success.
11702 * G_VALUE_HOLDS_BOXED:
11703 * @value: a valid #GValue structure
11705 * Checks whether the given #GValue can hold values derived
11706 * from type %G_TYPE_BOXED.
11708 * Returns: %TRUE on success.
11713 * G_VALUE_HOLDS_CHAR:
11714 * @value: a valid #GValue structure
11716 * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR.
11718 * Returns: %TRUE on success.
11723 * G_VALUE_HOLDS_DOUBLE:
11724 * @value: a valid #GValue structure
11726 * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE.
11728 * Returns: %TRUE on success.
11733 * G_VALUE_HOLDS_ENUM:
11734 * @value: a valid #GValue structure
11736 * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM.
11738 * Returns: %TRUE on success.
11743 * G_VALUE_HOLDS_FLAGS:
11744 * @value: a valid #GValue structure
11746 * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS.
11748 * Returns: %TRUE on success.
11753 * G_VALUE_HOLDS_FLOAT:
11754 * @value: a valid #GValue structure
11756 * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT.
11758 * Returns: %TRUE on success.
11763 * G_VALUE_HOLDS_GTYPE:
11764 * @value: a valid #GValue structure
11766 * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE.
11769 * Returns: %TRUE on success.
11774 * G_VALUE_HOLDS_INT:
11775 * @value: a valid #GValue structure
11777 * Checks whether the given #GValue can hold values of type %G_TYPE_INT.
11779 * Returns: %TRUE on success.
11784 * G_VALUE_HOLDS_INT64:
11785 * @value: a valid #GValue structure
11787 * Checks whether the given #GValue can hold values of type %G_TYPE_INT64.
11789 * Returns: %TRUE on success.
11794 * G_VALUE_HOLDS_LONG:
11795 * @value: a valid #GValue structure
11797 * Checks whether the given #GValue can hold values of type %G_TYPE_LONG.
11799 * Returns: %TRUE on success.
11804 * G_VALUE_HOLDS_OBJECT:
11805 * @value: a valid #GValue structure
11807 * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.
11809 * Returns: %TRUE on success.
11814 * G_VALUE_HOLDS_PARAM:
11815 * @value: a valid #GValue structure
11817 * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM.
11819 * Returns: %TRUE on success.
11824 * G_VALUE_HOLDS_POINTER:
11825 * @value: a valid #GValue structure
11827 * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER.
11829 * Returns: %TRUE on success.
11834 * G_VALUE_HOLDS_STRING:
11835 * @value: a valid #GValue structure
11837 * Checks whether the given #GValue can hold values of type %G_TYPE_STRING.
11839 * Returns: %TRUE on success.
11844 * G_VALUE_HOLDS_UCHAR:
11845 * @value: a valid #GValue structure
11847 * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR.
11849 * Returns: %TRUE on success.
11854 * G_VALUE_HOLDS_UINT:
11855 * @value: a valid #GValue structure
11857 * Checks whether the given #GValue can hold values of type %G_TYPE_UINT.
11859 * Returns: %TRUE on success.
11864 * G_VALUE_HOLDS_UINT64:
11865 * @value: a valid #GValue structure
11867 * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64.
11869 * Returns: %TRUE on success.
11874 * G_VALUE_HOLDS_ULONG:
11875 * @value: a valid #GValue structure
11877 * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG.
11879 * Returns: %TRUE on success.
11884 * G_VALUE_HOLDS_VARIANT:
11885 * @value: a valid #GValue structure
11887 * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT.
11889 * Returns: %TRUE on success.
11897 * A #GValue must be initialized before it can be used.
11898 * This macro can be used as initializer instead of an explicit
11899 * <literal>{ 0 }</literal> when declaring a variable,
11900 * but it cannot be assigned to a variable.
11903 * GValue value = G_VALUE_INIT;
11911 * G_VALUE_NOCOPY_CONTENTS:
11913 * If passed to G_VALUE_COLLECT(), allocated data won't be copied
11914 * but used verbatim. This does not affect ref-counted types like
11921 * @value: A #GValue structure.
11923 * Get the type identifier of @value.
11925 * Returns: the #GType.
11930 * G_VALUE_TYPE_NAME:
11931 * @value: A #GValue structure.
11933 * Gets the the type name of @value.
11935 * Returns: the type name.
11941 * @type_string: a well-formed #GVariantType type string
11943 * Converts a string to a const #GVariantType. Depending on the
11944 * current debugging level, this function may perform a runtime check
11945 * to ensure that @string is a valid GVariant type string.
11947 * It is always a programmer error to use this macro with an invalid
11948 * type string. If in doubt, use g_variant_type_string_is_valid() to
11949 * check if the string is valid.
11956 * G_VARIANT_TYPE_ANY:
11958 * An indefinite type that is a supertype of every type (including
11964 * G_VARIANT_TYPE_ARRAY:
11966 * An indefinite type that is a supertype of every array type.
11971 * G_VARIANT_TYPE_BASIC:
11973 * An indefinite type that is a supertype of every basic (ie:
11974 * non-container) type.
11979 * G_VARIANT_TYPE_BOOLEAN:
11981 * The type of a value that can be either %TRUE or %FALSE.
11986 * G_VARIANT_TYPE_BYTE:
11988 * The type of an integer value that can range from 0 to 255.
11993 * G_VARIANT_TYPE_BYTESTRING:
11995 * The type of an array of bytes. This type is commonly used to pass
11996 * around strings that may not be valid utf8. In that case, the
11997 * convention is that the nul terminator character should be included as
11998 * the last character in the array.
12003 * G_VARIANT_TYPE_BYTESTRING_ARRAY:
12005 * The type of an array of byte strings (an array of arrays of bytes).
12010 * G_VARIANT_TYPE_DICTIONARY:
12012 * An indefinite type that is a supertype of every dictionary type --
12013 * that is, any array type that has an element type equal to any
12014 * dictionary entry type.
12019 * G_VARIANT_TYPE_DICT_ENTRY:
12021 * An indefinite type that is a supertype of every dictionary entry
12027 * G_VARIANT_TYPE_DOUBLE:
12029 * The type of a double precision IEEE754 floating point number.
12030 * These guys go up to about 1.80e308 (plus and minus) but miss out on
12031 * some numbers in between. In any case, that's far greater than the
12032 * estimated number of fundamental particles in the observable
12038 * G_VARIANT_TYPE_HANDLE:
12040 * The type of a 32bit signed integer value, that by convention, is used
12041 * as an index into an array of file descriptors that are sent alongside
12044 * If you are not interacting with D-Bus, then there is no reason to make
12045 * use of this type.
12050 * G_VARIANT_TYPE_INT16:
12052 * The type of an integer value that can range from -32768 to 32767.
12057 * G_VARIANT_TYPE_INT32:
12059 * The type of an integer value that can range from -2147483648 to
12065 * G_VARIANT_TYPE_INT64:
12067 * The type of an integer value that can range from
12068 * -9223372036854775808 to 9223372036854775807.
12073 * G_VARIANT_TYPE_MAYBE:
12075 * An indefinite type that is a supertype of every maybe type.
12080 * G_VARIANT_TYPE_OBJECT_PATH:
12082 * The type of a D-Bus object reference. These are strings of a
12083 * specific format used to identify objects at a given destination on
12086 * If you are not interacting with D-Bus, then there is no reason to make
12087 * use of this type. If you are, then the D-Bus specification contains a
12088 * precise description of valid object paths.
12093 * G_VARIANT_TYPE_OBJECT_PATH_ARRAY:
12095 * The type of an array of object paths.
12100 * G_VARIANT_TYPE_SIGNATURE:
12102 * The type of a D-Bus type signature. These are strings of a specific
12103 * format used as type signatures for D-Bus methods and messages.
12105 * If you are not interacting with D-Bus, then there is no reason to make
12106 * use of this type. If you are, then the D-Bus specification contains a
12107 * precise description of valid signature strings.
12112 * G_VARIANT_TYPE_STRING:
12114 * The type of a string. "" is a string. %NULL is not a string.
12119 * G_VARIANT_TYPE_STRING_ARRAY:
12121 * The type of an array of strings.
12126 * G_VARIANT_TYPE_TUPLE:
12128 * An indefinite type that is a supertype of every tuple type,
12129 * regardless of the number of items in the tuple.
12134 * G_VARIANT_TYPE_UINT16:
12136 * The type of an integer value that can range from 0 to 65535.
12137 * There were about this many people living in Toronto in the 1870s.
12142 * G_VARIANT_TYPE_UINT32:
12144 * The type of an integer value that can range from 0 to 4294967295.
12145 * That's one number for everyone who was around in the late 1970s.
12150 * G_VARIANT_TYPE_UINT64:
12152 * The type of an integer value that can range from 0 to
12153 * 18446744073709551616. That's a really big number, but a Rubik's
12154 * cube can have a bit more than twice as many possible positions.
12159 * G_VARIANT_TYPE_UNIT:
12161 * The empty tuple type. Has only one instance. Known also as "triv"
12167 * G_VARIANT_TYPE_VARDICT:
12169 * The type of a dictionary mapping strings to variants (the ubiquitous
12177 * G_VARIANT_TYPE_VARIANT:
12179 * The type of a box that contains any other value (including another
12185 * G_VFS_EXTENSION_POINT_NAME:
12187 * Extension point for #GVfs functionality.
12188 * See <link linkend="extending-gio">Extending GIO</link>.
12193 * G_VOLUME_IDENTIFIER_KIND_CLASS:
12195 * The string used to obtain the volume <emphasis>class</emphasis>
12196 * with g_volume_get_identifier().
12198 * Known volume classes include <literal>device</literal> and
12199 * <literal>network</literal>. Other classes may be added in the
12202 * This is intended to be used by applications to classify #GVolume
12203 * instances into different sections - for example a file manager or
12204 * file chooser can use this information to show
12205 * <literal>network</literal> volumes under a "Network" heading and
12206 * <literal>device</literal> volumes under a "Devices" heading.
12211 * G_VOLUME_IDENTIFIER_KIND_HAL_UDI:
12213 * The string used to obtain a Hal UDI with g_volume_get_identifier().
12218 * G_VOLUME_IDENTIFIER_KIND_LABEL:
12220 * The string used to obtain a filesystem label with g_volume_get_identifier().
12225 * G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT:
12227 * The string used to obtain a NFS mount with g_volume_get_identifier().
12232 * G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE:
12234 * The string used to obtain a Unix device path with g_volume_get_identifier().
12239 * G_VOLUME_IDENTIFIER_KIND_UUID:
12241 * The string used to obtain a UUID with g_volume_get_identifier().
12246 * G_VOLUME_MONITOR_EXTENSION_POINT_NAME:
12248 * Extension point for volume monitor functionality.
12249 * See <link linkend="extending-gio">Extending GIO</link>.
12254 * SECTION:extensionpoints
12255 * @short_description: Extension Points
12257 * @see_also: <link linkend="extending-gio">Extending GIO</link>
12259 * #GIOExtensionPoint provides a mechanism for modules to extend the
12260 * functionality of the library or application that loaded it in an
12261 * organized fashion.
12263 * An extension point is identified by a name, and it may optionally
12264 * require that any implementation must by of a certain type (or derived
12265 * thereof). Use g_io_extension_point_register() to register an
12266 * extension point, and g_io_extension_point_set_required_type() to
12267 * set a required type.
12269 * A module can implement an extension point by specifying the #GType
12270 * that implements the functionality. Additionally, each implementation
12271 * of an extension point has a name, and a priority. Use
12272 * g_io_extension_point_implement() to implement an extension point.
12275 * GIOExtensionPoint *ep;
12277 * /* Register an extension point */
12278 * ep = g_io_extension_point_register ("my-extension-point");
12279 * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
12283 * /* Implement an extension point */
12284 * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
12285 * g_io_extension_point_implement ("my-extension-point",
12286 * my_example_impl_get_type (),
12291 * It is up to the code that registered the extension point how
12292 * it uses the implementations that have been associated with it.
12293 * Depending on the use case, it may use all implementations, or
12294 * only the one with the highest priority, or pick a specific
12297 * To avoid opening all modules just to find out what extension
12298 * points they implement, GIO makes use of a caching mechanism,
12299 * see <link linkend="gio-querymodules">gio-querymodules</link>.
12300 * You are expected to run this command after installing a
12303 * The <envar>GIO_EXTRA_MODULES</envar> environment variable can be
12304 * used to specify additional directories to automatically load modules
12305 * from. This environment variable has the same syntax as the
12306 * <envar>PATH</envar>. If two modules have the same base name in different
12307 * directories, then the latter one will be ignored. If additional
12308 * directories are specified GIO will load modules from the built-in
12316 * @short_description: An action interface
12318 * #GAction represents a single named action.
12320 * The main interface to an action is that it can be activated with
12321 * g_action_activate(). This results in the 'activate' signal being
12322 * emitted. An activation has a #GVariant parameter (which may be
12323 * %NULL). The correct type for the parameter is determined by a static
12324 * parameter type (which is given at construction time).
12326 * An action may optionally have a state, in which case the state may be
12327 * set with g_action_change_state(). This call takes a #GVariant. The
12328 * correct type for the state is determined by a static state type
12329 * (which is given at construction time).
12331 * The state may have a hint associated with it, specifying its valid
12334 * #GAction is merely the interface to the concept of an action, as
12335 * described above. Various implementations of actions exist, including
12336 * #GSimpleAction and #GtkAction.
12338 * In all cases, the implementing class is responsible for storing the
12339 * name of the action, the parameter type, the enabled state, the
12340 * optional state type and the state and emitting the appropriate
12341 * signals when these change. The implementor responsible for filtering
12342 * calls to g_action_activate() and g_action_change_state() for type
12343 * safety and for the state being enabled.
12345 * Probably the only useful thing to do with a #GAction is to put it
12346 * inside of a #GSimpleActionGroup.
12351 * SECTION:gactiongroup
12352 * @title: GActionGroup
12353 * @short_description: A group of actions
12354 * @see_also: #GAction
12356 * #GActionGroup represents a group of actions. Actions can be used to
12357 * expose functionality in a structured way, either from one part of a
12358 * program to another, or to the outside world. Action groups are often
12359 * used together with a #GMenuModel that provides additional
12360 * representation data for displaying the actions to the user, e.g. in
12363 * The main way to interact with the actions in a GActionGroup is to
12364 * activate them with g_action_group_activate_action(). Activating an
12365 * action may require a #GVariant parameter. The required type of the
12366 * parameter can be inquired with g_action_group_get_action_parameter_type().
12367 * Actions may be disabled, see g_action_group_get_action_enabled().
12368 * Activating a disabled action has no effect.
12370 * Actions may optionally have a state in the form of a #GVariant. The
12371 * current state of an action can be inquired with
12372 * g_action_group_get_action_state(). Activating a stateful action may
12373 * change its state, but it is also possible to set the state by calling
12374 * g_action_group_change_action_state().
12376 * As typical example, consider a text editing application which has an
12377 * option to change the current font to 'bold'. A good way to represent
12378 * this would be a stateful action, with a boolean state. Activating the
12379 * action would toggle the state.
12381 * Each action in the group has a unique name (which is a string). All
12382 * method calls, except g_action_group_list_actions() take the name of
12383 * an action as an argument.
12385 * The #GActionGroup API is meant to be the 'public' API to the action
12386 * group. The calls here are exactly the interaction that 'external
12387 * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
12388 * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
12389 * the action group implementation) are found on subclasses. This is
12390 * why you will find - for example - g_action_group_get_action_enabled()
12391 * but not an equivalent <function>set()</function> call.
12393 * Signals are emitted on the action group in response to state changes
12394 * on individual actions.
12396 * Implementations of #GActionGroup should provide implementations for
12397 * the virtual functions g_action_group_list_actions() and
12398 * g_action_group_query_action(). The other virtual functions should
12399 * not be implemented - their "wrappers" are actually implemented with
12400 * calls to g_action_group_query_action().
12405 * SECTION:gactiongroupexporter
12406 * @title: GActionGroup exporter
12407 * @short_description: Export GActionGroups on D-Bus
12408 * @see_also: #GActionGroup, #GDBusActionGroup
12410 * These functions support exporting a #GActionGroup on D-Bus.
12411 * The D-Bus interface that is used is a private implementation
12414 * To access an exported #GActionGroup remotely, use
12415 * g_dbus_action_group_get() to obtain a #GDBusActionGroup.
12420 * SECTION:gactionmap
12421 * @title: GActionMap
12422 * @short_description: Interface for action containers
12424 * The GActionMap interface is implemented by #GActionGroup
12425 * implementations that operate by containing a number of
12426 * named #GAction instances, such as #GSimpleActionGroup.
12428 * One useful application of this interface is to map the
12429 * names of actions from various action groups to unique,
12430 * prefixed names (e.g. by prepending "app." or "win.").
12431 * This is the motivation for the 'Map' part of the interface
12440 * @short_description: Application information and launch contexts
12441 * @include: gio/gio.h
12443 * #GAppInfo and #GAppLaunchContext are used for describing and launching
12444 * applications installed on the system.
12446 * As of GLib 2.20, URIs will always be converted to POSIX paths
12447 * (using g_file_get_path()) when using g_app_info_launch() even if
12448 * the application requested an URI and not a POSIX path. For example
12449 * for an desktop-file based application with Exec key <literal>totem
12450 * %U</literal> and a single URI,
12451 * <literal>sftp://foo/file.avi</literal>, then
12452 * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be
12453 * passed. This will only work if a set of suitable GIO extensions
12454 * (such as gvfs 2.26 compiled with FUSE support), is available and
12455 * operational; if this is not the case, the URI will be passed
12456 * unmodified to the application. Some URIs, such as
12457 * <literal>mailto:</literal>, of course cannot be mapped to a POSIX
12458 * path (in gvfs there's no FUSE mount for it); such URIs will be
12459 * passed unmodified to the application.
12461 * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
12462 * back to the GIO URI in the #GFile constructors (since gvfs
12463 * implements the #GVfs extension point). As such, if the application
12464 * needs to examine the URI, it needs to use g_file_get_uri() or
12465 * similar on #GFile. In other words, an application cannot assume
12466 * that the URI passed to e.g. g_file_new_for_commandline_arg() is
12467 * equal to the result of g_file_get_uri(). The following snippet
12468 * illustrates this:
12474 * file = g_file_new_for_commandline_arg (uri_from_commandline);
12476 * uri = g_file_get_uri (file);
12477 * strcmp (uri, uri_from_commandline) == 0; // FALSE
12480 * if (g_file_has_uri_scheme (file, "cdda"))
12482 * // do something special with uri
12484 * g_object_unref (file);
12485 * </programlisting>
12487 * This code will work when both <literal>cdda://sr0/Track
12488 * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track
12489 * 1.wav</literal> is passed to the application. It should be noted
12490 * that it's generally not safe for applications to rely on the format
12491 * of a particular URIs. Different launcher applications (e.g. file
12492 * managers) may have different ideas of what a given URI means.
12497 * SECTION:gapplication
12498 * @title: GApplication
12499 * @short_description: Core application class
12501 * A #GApplication is the foundation of an application, unique for a
12502 * given application identifier. The GApplication class wraps some
12503 * low-level platform-specific services and is intended to act as the
12504 * foundation for higher-level application classes such as
12505 * #GtkApplication or #MxApplication. In general, you should not use
12506 * this class outside of a higher level framework.
12508 * One of the core features that GApplication provides is process
12509 * uniqueness, in the context of a "session". The session concept is
12510 * platform-dependent, but corresponds roughly to a graphical desktop
12511 * login. When your application is launched again, its arguments
12512 * are passed through platform communication to the already running
12513 * program. The already running instance of the program is called the
12514 * <firstterm>primary instance</firstterm>. On Linux, the D-Bus session
12515 * bus is used for communication.
12517 * GApplication provides convenient life cycle management by maintaining
12518 * a <firstterm>use count</firstterm> for the primary application instance.
12519 * The use count can be changed using g_application_hold() and
12520 * g_application_release(). If it drops to zero, the application exits.
12521 * Higher-level classes such as #GtkApplication employ the use count to
12522 * ensure that the application stays alive as long as it has any opened
12525 * Before using GApplication, you must choose an "application identifier".
12526 * The expected form of an application identifier is very close to that of
12527 * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
12528 * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
12529 * For details on valid application identifiers, see g_application_id_is_valid().
12531 * On Linux, the application identifier is claimed as a well-known bus name
12532 * on the user's session bus. This means that the uniqueness of your
12533 * application is scoped to the current session. It also means that your
12534 * application may provide additional services (through registration of other
12535 * object paths) at that bus name. The registration of these object paths
12536 * should be done with the shared GDBus session bus. Note that due to the
12537 * internal architecture of GDBus, method calls can be dispatched at any time
12538 * (even if a main loop is not running). For this reason, you must ensure that
12539 * any object paths that you wish to register are registered before #GApplication
12540 * attempts to acquire the bus name of your application (which happens in
12541 * g_application_register()). Unfortunately, this means that you cannot use
12542 * g_application_get_is_remote() to decide if you want to register object paths.
12544 * GApplication also implements the #GActionGroup and #GActionMap
12545 * interfaces and lets you easily export actions by adding them with
12546 * g_action_map_add_action(). When invoking an action by calling
12547 * g_action_group_activate_action() on the application, it is always
12548 * invoked in the primary instance. The actions are also exported on
12549 * the session bus, and GIO provides the #GDBusActionGroup wrapper to
12550 * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
12551 * for remote access to exported #GMenuModels.
12553 * There is a number of different entry points into a GApplication:
12555 * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
12556 * <listitem>via 'Open' (i.e. opening some files)</listitem>
12557 * <listitem>by handling a command-line</listitem>
12558 * <listitem>via activating an action</listitem>
12560 * The #GApplication::startup signal lets you handle the application
12561 * initialization for all of these in a single place.
12563 * Regardless of which of these entry points is used to start the application,
12564 * GApplication passes some <firstterm id="platform-data">platform
12565 * data</firstterm> from the launching instance to the primary instance,
12566 * in the form of a #GVariant dictionary mapping strings to variants.
12567 * To use platform data, override the @before_emit or @after_emit virtual
12568 * functions in your #GApplication subclass. When dealing with
12569 * #GApplicationCommandLine objects, the platform data is directly
12570 * available via g_application_command_line_get_cwd(),
12571 * g_application_command_line_get_environ() and
12572 * g_application_command_line_get_platform_data().
12574 * As the name indicates, the platform data may vary depending on the
12575 * operating system, but it always includes the current directory (key
12576 * "cwd"), and optionally the environment (ie the set of environment
12577 * variables and their values) of the calling process (key "environ").
12578 * The environment is only added to the platform data if the
12579 * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
12580 * can add their own platform data by overriding the @add_platform_data
12581 * virtual function. For instance, #GtkApplication adds startup notification
12582 * data in this way.
12584 * To parse commandline arguments you may handle the
12585 * #GApplication::command-line signal or override the local_command_line()
12586 * vfunc, to parse them in either the primary instance or the local instance,
12589 * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
12591 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-open.c">
12592 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
12594 * </programlisting>
12597 * <example id="gapplication-example-actions"><title>A GApplication with actions</title>
12599 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-actions.c">
12600 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
12602 * </programlisting>
12605 * <example id="gapplication-example-menu"><title>A GApplication with menus</title>
12607 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-menu.c">
12608 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
12610 * </programlisting>
12616 * SECTION:gapplicationcommandline
12617 * @title: GApplicationCommandLine
12618 * @short_description: A command-line invocation of an application
12619 * @see_also: #GApplication
12621 * #GApplicationCommandLine represents a command-line invocation of
12622 * an application. It is created by #GApplication and emitted
12623 * in the #GApplication::command-line signal and virtual function.
12625 * The class contains the list of arguments that the program was invoked
12626 * with. It is also possible to query if the commandline invocation was
12627 * local (ie: the current process is running in direct response to the
12628 * invocation) or remote (ie: some other process forwarded the
12629 * commandline to this process).
12631 * The GApplicationCommandLine object can provide the @argc and @argv
12632 * parameters for use with the #GOptionContext command-line parsing API,
12633 * with the g_application_command_line_get_arguments() function. See
12634 * <xref linkend="gapplication-example-cmdline3"/> for an example.
12636 * The exit status of the originally-invoked process may be set and
12637 * messages can be printed to stdout or stderr of that process. The
12638 * lifecycle of the originally-invoked process is tied to the lifecycle
12639 * of this object (ie: the process exits when the last reference is
12642 * The main use for #GApplicationCommandLine (and the
12643 * #GApplication::command-line signal) is 'Emacs server' like use cases:
12644 * You can set the <envar>EDITOR</envar> environment variable to have
12645 * e.g. git use your favourite editor to edit commit messages, and if you
12646 * already have an instance of the editor running, the editing will happen
12647 * in the running instance, instead of opening a new one. An important
12648 * aspect of this use case is that the process that gets started by git
12649 * does not return until the editing is done.
12651 * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
12653 * A simple example where the commandline is completely handled
12654 * in the #GApplication::command-line handler. The launching instance exits
12655 * once the signal handler in the primary instance has returned, and the
12656 * return value of the signal handler becomes the exit status of the launching
12660 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
12661 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
12663 * </programlisting>
12666 * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title>
12668 * An example of split commandline handling. Options that start with
12669 * <literal>--local-</literal> are handled locally, all other options are
12670 * passed to the #GApplication::command-line handler which runs in the primary
12674 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
12675 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
12677 * </programlisting>
12680 * <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
12682 * An example of deferred commandline handling. Here, the commandline is
12683 * not completely handled before the #GApplication::command-line handler
12684 * returns. Instead, we keep a reference to the GApplicationCommandLine
12685 * object and handle it later(in this example, in an idle). Note that it
12686 * is necessary to hold the application until you are done with the
12690 * This example also shows how to use #GOptionContext for parsing the
12691 * commandline arguments. Note that it is necessary to disable the
12692 * built-in help-handling of #GOptionContext, since it calls exit()
12693 * after printing help, which is not what you want to happen in
12694 * the primary instance.
12697 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c">
12698 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
12700 * </programlisting>
12706 * SECTION:gasyncinitable
12707 * @short_description: Asynchronously failable object initialization interface
12708 * @include: gio/gio.h
12709 * @see_also: #GInitable
12711 * This is the asynchronous version of #GInitable; it behaves the same
12712 * in all ways except that initialization is asynchronous. For more details
12713 * see the descriptions on #GInitable.
12715 * A class may implement both the #GInitable and #GAsyncInitable interfaces.
12717 * Users of objects implementing this are not intended to use the interface
12718 * method directly; instead it will be used automatically in various ways.
12719 * For C applications you generally just call g_async_initable_new_async()
12720 * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
12721 * g_async_initable_init_async() under the cover, calling back with %NULL and
12722 * a set %GError on failure.
12724 * A typical implementation might look something like this:
12734 * _foo_ready_cb (Foo *self)
12738 * self->priv->state = INITIALIZED;
12740 * for (l = self->priv->init_results; l != NULL; l = l->next)
12742 * GSimpleAsyncResult *simple = l->data;
12744 * if (!self->priv->success)
12745 * g_simple_async_result_set_error (simple, ...);
12747 * g_simple_async_result_complete (simple);
12748 * g_object_unref (simple);
12751 * g_list_free (self->priv->init_results);
12752 * self->priv->init_results = NULL;
12756 * foo_init_async (GAsyncInitable *initable,
12758 * GCancellable *cancellable,
12759 * GAsyncReadyCallback callback,
12760 * gpointer user_data)
12762 * Foo *self = FOO (initable);
12763 * GSimpleAsyncResult *simple;
12765 * simple = g_simple_async_result_new (G_OBJECT (initable)
12770 * switch (self->priv->state)
12772 * case NOT_INITIALIZED:
12773 * _foo_get_ready (self);
12774 * self->priv->init_results = g_list_append (self->priv->init_results,
12776 * self->priv->state = INITIALIZING;
12778 * case INITIALIZING:
12779 * self->priv->init_results = g_list_append (self->priv->init_results,
12782 * case INITIALIZED:
12783 * if (!self->priv->success)
12784 * g_simple_async_result_set_error (simple, ...);
12786 * g_simple_async_result_complete_in_idle (simple);
12787 * g_object_unref (simple);
12793 * foo_init_finish (GAsyncInitable *initable,
12794 * GAsyncResult *result,
12797 * g_return_val_if_fail (g_simple_async_result_is_valid (result,
12798 * G_OBJECT (initable), foo_init_async), FALSE);
12800 * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
12808 * foo_async_initable_iface_init (gpointer g_iface,
12811 * GAsyncInitableIface *iface = g_iface;
12813 * iface->init_async = foo_init_async;
12814 * iface->init_finish = foo_init_finish;
12821 * SECTION:gasyncresult
12822 * @short_description: Asynchronous Function Results
12823 * @include: gio/gio.h
12824 * @see_also: #GSimpleAsyncResult
12826 * Provides a base class for implementing asynchronous function results.
12828 * Asynchronous operations are broken up into two separate operations
12829 * which are chained together by a #GAsyncReadyCallback. To begin
12830 * an asynchronous operation, provide a #GAsyncReadyCallback to the
12831 * asynchronous function. This callback will be triggered when the
12832 * operation has completed, and will be passed a #GAsyncResult instance
12833 * filled with the details of the operation's success or failure, the
12834 * object the asynchronous function was started for and any error codes
12835 * returned. The asynchronous callback function is then expected to call
12836 * the corresponding "_finish()" function, passing the object the
12837 * function was called for, the #GAsyncResult instance, and (optionally)
12838 * an @error to grab any error conditions that may have occurred.
12840 * The "_finish()" function for an operation takes the generic result
12841 * (of type #GAsyncResult) and returns the specific result that the
12842 * operation in question yields (e.g. a #GFileEnumerator for a
12843 * "enumerate children" operation). If the result or error status of the
12844 * operation is not needed, there is no need to call the "_finish()"
12845 * function; GIO will take care of cleaning up the result and error
12846 * information after the #GAsyncReadyCallback returns. You can pass
12847 * %NULL for the #GAsyncReadyCallback if you don't need to take any
12848 * action at all after the operation completes. Applications may also
12849 * take a reference to the #GAsyncResult and call "_finish()" later;
12850 * however, the "_finish()" function may be called at most once.
12852 * Example of a typical asynchronous operation flow:
12854 * void _theoretical_frobnitz_async (Theoretical *t,
12856 * GAsyncReadyCallback *cb,
12859 * gboolean _theoretical_frobnitz_finish (Theoretical *t,
12860 * GAsyncResult *res,
12864 * frobnitz_result_func (GObject *source_object,
12865 * GAsyncResult *res,
12866 * gpointer user_data)
12868 * gboolean success = FALSE;
12870 * success = _theoretical_frobnitz_finish (source_object, res, NULL);
12873 * g_printf ("Hurray!\n");
12875 * g_printf ("Uh oh!\n");
12877 * /<!-- -->* ... *<!-- -->/
12881 * int main (int argc, void *argv[])
12883 * /<!-- -->* ... *<!-- -->/
12885 * _theoretical_frobnitz_async (theoretical_data,
12887 * frobnitz_result_func,
12890 * /<!-- -->* ... *<!-- -->/
12894 * The callback for an asynchronous operation is called only once, and is
12895 * always called, even in the case of a cancelled operation. On cancellation
12896 * the result is a %G_IO_ERROR_CANCELLED error.
12901 * SECTION:gbufferedinputstream
12902 * @short_description: Buffered Input Stream
12903 * @include: gio/gio.h
12904 * @see_also: #GFilterInputStream, #GInputStream
12906 * Buffered input stream implements #GFilterInputStream and provides
12907 * for buffered reads.
12909 * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
12911 * To create a buffered input stream, use g_buffered_input_stream_new(),
12912 * or g_buffered_input_stream_new_sized() to specify the buffer's size at
12915 * To get the size of a buffer within a buffered input stream, use
12916 * g_buffered_input_stream_get_buffer_size(). To change the size of a
12917 * buffered input stream's buffer, use
12918 * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
12919 * cannot be reduced below the size of the data within the buffer.
12924 * SECTION:gbufferedoutputstream
12925 * @short_description: Buffered Output Stream
12926 * @include: gio/gio.h
12927 * @see_also: #GFilterOutputStream, #GOutputStream
12929 * Buffered output stream implements #GFilterOutputStream and provides
12930 * for buffered writes.
12932 * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
12934 * To create a buffered output stream, use g_buffered_output_stream_new(),
12935 * or g_buffered_output_stream_new_sized() to specify the buffer's size
12938 * To get the size of a buffer within a buffered input stream, use
12939 * g_buffered_output_stream_get_buffer_size(). To change the size of a
12940 * buffered output stream's buffer, use
12941 * g_buffered_output_stream_set_buffer_size(). Note that the buffer's
12942 * size cannot be reduced below the size of the data within the buffer.
12947 * SECTION:gcancellable
12948 * @short_description: Thread-safe Operation Cancellation Stack
12949 * @include: gio/gio.h
12951 * GCancellable is a thread-safe operation cancellation stack used
12952 * throughout GIO to allow for cancellation of synchronous and
12953 * asynchronous operations.
12958 * SECTION:gcharsetconverter
12959 * @short_description: Convert between charsets
12960 * @include: gio/gio.h
12962 * #GCharsetConverter is an implementation of #GConverter based on
12968 * SECTION:gcontenttype
12969 * @short_description: Platform-specific content typing
12970 * @include: gio/gio.h
12972 * A content type is a platform specific string that defines the type
12973 * of a file. On UNIX it is a <ulink url="http://www.wikipedia.org/wiki/Internet_media_type">mime type</ulink> like "text/plain" or "image/png".
12974 * On Win32 it is an extension string like ".doc", ".txt" or a perceived
12975 * string like "audio". Such strings can be looked up in the registry at
12976 * HKEY_CLASSES_ROOT.
12981 * SECTION:gconverter
12982 * @short_description: Data conversion interface
12983 * @include: gio/gio.h
12984 * @see_also: #GInputStream, #GOutputStream
12986 * #GConverter is implemented by objects that convert
12987 * binary data in various ways. The conversion can be
12988 * stateful and may fail at any place.
12990 * Some example conversions are: character set conversion,
12991 * compression, decompression and regular expression
12999 * SECTION:gconverterinputstream
13000 * @short_description: Converter Input Stream
13001 * @include: gio/gio.h
13002 * @see_also: #GInputStream, #GConverter
13004 * Converter input stream implements #GInputStream and allows
13005 * conversion of data of various types during reading.
13010 * SECTION:gconverteroutputstream
13011 * @short_description: Converter Output Stream
13012 * @include: gio/gio.h
13013 * @see_also: #GOutputStream, #GConverter
13015 * Converter output stream implements #GOutputStream and allows
13016 * conversion of data of various types during reading.
13021 * SECTION:gcredentials
13022 * @short_description: An object containing credentials
13023 * @include: gio/gio.h
13025 * The #GCredentials type is a reference-counted wrapper for native
13026 * credentials. This information is typically used for identifying,
13027 * authenticating and authorizing other processes.
13029 * Some operating systems supports looking up the credentials of the
13030 * remote peer of a communication endpoint - see e.g.
13031 * g_socket_get_credentials().
13033 * Some operating systems supports securely sending and receiving
13034 * credentials over a Unix Domain Socket, see
13035 * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
13036 * g_unix_connection_receive_credentials() for details.
13038 * On Linux, the native credential type is a <type>struct ucred</type>
13040 * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
13041 * man page for details. This corresponds to
13042 * %G_CREDENTIALS_TYPE_LINUX_UCRED.
13044 * On FreeBSD, the native credential type is a <type>struct cmsgcred</type>.
13045 * This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
13047 * On OpenBSD, the native credential type is a <type>struct sockpeercred</type>.
13048 * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
13053 * SECTION:gdatainputstream
13054 * @short_description: Data Input Stream
13055 * @include: gio/gio.h
13056 * @see_also: #GInputStream
13058 * Data input stream implements #GInputStream and includes functions for
13059 * reading structured data directly from a binary input stream.
13064 * SECTION:gdataoutputstream
13065 * @short_description: Data Output Stream
13066 * @include: gio/gio.h
13067 * @see_also: #GOutputStream
13069 * Data output stream implements #GOutputStream and includes functions for
13070 * writing data directly to an output stream.
13075 * SECTION:gdbusactiongroup
13076 * @title: GDBusActionGroup
13077 * @short_description: A D-Bus GActionGroup implementation
13078 * @see_also: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
13080 * #GDBusActionGroup is an implementation of the #GActionGroup
13081 * interface that can be used as a proxy for an action group
13082 * that is exported over D-Bus with g_dbus_connection_export_action_group().
13087 * SECTION:gdbusaddress
13088 * @title: D-Bus Addresses
13089 * @short_description: D-Bus connection endpoints
13090 * @include: gio/gio.h
13092 * Routines for working with D-Bus addresses. A D-Bus address is a string
13093 * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
13094 * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">D-Bus specification</link>.
13099 * SECTION:gdbusauthobserver
13100 * @short_description: Object used for authenticating connections
13101 * @include: gio/gio.h
13103 * The #GDBusAuthObserver type provides a mechanism for participating
13104 * in how a #GDBusServer (or a #GDBusConnection) authenticates remote
13105 * peers. Simply instantiate a #GDBusAuthObserver and connect to the
13106 * signals you are interested in. Note that new signals may be added
13109 * For example, if you only want to allow D-Bus connections from
13110 * processes owned by the same uid as the server, you would use a
13111 * signal handler like the following:
13112 * <example id="auth-observer"><title>Controlling Authentication</title><programlisting>
13114 * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
13115 * GIOStream *stream,
13116 * GCredentials *credentials,
13117 * gpointer user_data)
13119 * gboolean authorized;
13121 * authorized = FALSE;
13122 * if (credentials != NULL)
13124 * GCredentials *own_credentials;
13125 * own_credentials = g_credentials_new ();
13126 * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
13127 * authorized = TRUE;
13128 * g_object_unref (own_credentials);
13131 * return authorized;
13133 * </programlisting></example>
13138 * SECTION:gdbusconnection
13139 * @short_description: D-Bus Connections
13140 * @include: gio/gio.h
13142 * The #GDBusConnection type is used for D-Bus connections to remote
13143 * peers such as a message buses. It is a low-level API that offers a
13144 * lot of flexibility. For instance, it lets you establish a connection
13145 * over any transport that can by represented as an #GIOStream.
13147 * This class is rarely used directly in D-Bus clients. If you are writing
13148 * an D-Bus client, it is often easier to use the g_bus_own_name(),
13149 * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
13151 * As an exception to the usual GLib rule that a particular object must not be
13152 * used by two threads at the same time, #GDBusConnection's methods may be
13153 * called from any thread<footnote>
13155 * This is so that g_bus_get() and g_bus_get_sync() can safely return the
13156 * same #GDBusConnection when called from any thread.
13160 * Most of the ways to obtain a #GDBusConnection automatically initialize it
13161 * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
13162 * g_bus_get(), and the synchronous versions of those methods, give you an
13163 * initialized connection. Language bindings for GIO should use
13164 * g_initable_new() or g_async_initable_new_async(), which also initialize the
13167 * If you construct an uninitialized #GDBusConnection, such as via
13168 * g_object_new(), you must initialize it via g_initable_init() or
13169 * g_async_initable_init_async() before using its methods or properties.
13170 * Calling methods or accessing properties on a #GDBusConnection that has not
13171 * completed initialization successfully is considered to be invalid, and leads
13172 * to undefined behaviour. In particular, if initialization fails with a
13173 * #GError, the only valid thing you can do with that #GDBusConnection is to
13174 * free it with g_object_unref().
13176 * <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>
13178 * <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>
13180 * <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>
13182 * <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>
13187 * SECTION:gdbuserror
13188 * @title: GDBusError
13189 * @short_description: Mapping D-Bus errors to and from GError
13190 * @include: gio/gio.h
13192 * All facilities that return errors from remote methods (such as
13193 * g_dbus_connection_call_sync()) use #GError to represent both D-Bus
13194 * errors (e.g. errors returned from the other peer) and locally
13195 * in-process generated errors.
13197 * To check if a returned #GError is an error from a remote peer, use
13198 * g_dbus_error_is_remote_error(). To get the actual D-Bus error name,
13199 * use g_dbus_error_get_remote_error(). Before presenting an error,
13200 * always use g_dbus_error_strip_remote_error().
13202 * In addition, facilities used to return errors to a remote peer also
13203 * use #GError. See g_dbus_method_invocation_return_error() for
13204 * discussion about how the D-Bus error name is set.
13206 * Applications can associate a #GError error domain with a set of D-Bus errors in order to
13207 * automatically map from D-Bus errors to #GError and back. This
13208 * is typically done in the function returning the #GQuark for the
13210 * <example id="error-registration"><title>Error Registration</title><programlisting>
13211 * /<!-- -->* foo-bar-error.h: *<!-- -->/
13213 * #define FOO_BAR_ERROR (foo_bar_error_quark ())
13214 * GQuark foo_bar_error_quark (void);
13218 * FOO_BAR_ERROR_FAILED,
13219 * FOO_BAR_ERROR_ANOTHER_ERROR,
13220 * FOO_BAR_ERROR_SOME_THIRD_ERROR,
13223 * /<!-- -->* foo-bar-error.c: *<!-- -->/
13225 * static const GDBusErrorEntry foo_bar_error_entries[] =
13227 * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
13228 * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
13229 * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
13233 * foo_bar_error_quark (void)
13235 * static volatile gsize quark_volatile = 0;
13236 * g_dbus_error_register_error_domain ("foo-bar-error-quark",
13238 * foo_bar_error_entries,
13239 * G_N_ELEMENTS (foo_bar_error_entries));
13240 * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) - 1 == FOO_BAR_ERROR_SOME_THIRD_ERROR);
13241 * return (GQuark) quark_volatile;
13243 * </programlisting></example>
13244 * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
13245 * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>.
13246 * If the other peer is using GDBus, the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
13247 * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
13248 * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error().
13250 * Note that errors in the %G_DBUS_ERROR error domain is intended only
13251 * for returning errors from a remote message bus process. Errors
13252 * generated locally in-process by e.g. #GDBusConnection is from the
13253 * %G_IO_ERROR domain.
13258 * SECTION:gdbusinterface
13259 * @short_description: Base type for D-Bus interfaces
13260 * @include: gio/gio.h
13262 * The #GDBusInterface type is the base type for D-Bus interfaces both
13263 * on the service side (see #GDBusInterfaceSkeleton) and client side
13264 * (see #GDBusProxy).
13269 * SECTION:gdbusinterfaceskeleton
13270 * @short_description: Service-side D-Bus interface
13271 * @include: gio/gio.h
13273 * Abstract base class for D-Bus interfaces on the service side.
13278 * SECTION:gdbusintrospection
13279 * @title: D-Bus Introspection Data
13280 * @short_description: Node and interface description data structures
13281 * @include: gio/gio.h
13283 * Various data structures and convenience routines to parse and
13284 * generate D-Bus introspection XML. Introspection information is
13285 * used when registering objects with g_dbus_connection_register_object().
13287 * The format of D-Bus introspection XML is specified in the
13288 * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</ulink>.
13293 * SECTION:gdbusmenumodel
13294 * @title: GDBusMenuModel
13295 * @short_description: A D-Bus GMenuModel implementation
13296 * @see_also: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link>
13298 * #GDBusMenuModel is an implementation of #GMenuModel that can be used
13299 * as a proxy for a menu model that is exported over D-Bus with
13300 * g_dbus_connection_export_menu_model().
13305 * SECTION:gdbusmessage
13306 * @short_description: D-Bus Message
13307 * @include: gio/gio.h
13309 * A type for representing D-Bus messages that can be sent or received
13310 * on a #GDBusConnection.
13315 * SECTION:gdbusmethodinvocation
13316 * @short_description: Object for handling remote calls
13317 * @include: gio/gio.h
13319 * Instances of the #GDBusMethodInvocation class are used when
13320 * handling D-Bus method calls. It provides a way to asynchronously
13321 * return results and errors.
13323 * The normal way to obtain a #GDBusMethodInvocation object is to receive
13324 * it as an argument to the handle_method_call() function in a
13325 * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
13330 * SECTION:gdbusnameowning
13331 * @title: Owning Bus Names
13332 * @short_description: Simple API for owning bus names
13333 * @include: gio/gio.h
13335 * Convenience API for owning bus names.
13337 * <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>
13342 * SECTION:gdbusnamewatching
13343 * @title: Watching Bus Names
13344 * @short_description: Simple API for watching bus names
13345 * @include: gio/gio.h
13347 * Convenience API for watching bus names.
13349 * <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>
13354 * SECTION:gdbusobject
13355 * @short_description: Base type for D-Bus objects
13356 * @include: gio/gio.h
13358 * The #GDBusObject type is the base type for D-Bus objects on both
13359 * the service side (see #GDBusObjectSkeleton) and the client side
13360 * (see #GDBusObjectProxy). It is essentially just a container of
13366 * SECTION:gdbusobjectmanager
13367 * @short_description: Base type for D-Bus object managers
13368 * @include: gio/gio.h
13370 * The #GDBusObjectManager type is the base type for service- and
13371 * client-side implementations of the standardized <ulink
13372 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
13375 * See #GDBusObjectManagerClient for the client-side implementation
13376 * and #GDBusObjectManagerServer for the service-side implementation.
13381 * SECTION:gdbusobjectmanagerclient
13382 * @short_description: Client-side object manager
13383 * @include: gio/gio.h
13385 * #GDBusObjectManagerClient is used to create, monitor and delete object
13386 * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
13387 * code implementing the <ulink
13388 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
13391 * Once an instance of this type has been created, you can connect to
13392 * the #GDBusObjectManager::object-added and
13393 * #GDBusObjectManager::object-removed signals and inspect the
13394 * #GDBusObjectProxy objects returned by
13395 * g_dbus_object_manager_get_objects().
13397 * If the name for a #GDBusObjectManagerClient is not owned by anyone at
13398 * object construction time, the default behavior is to request the
13399 * message bus to launch an owner for the name. This behavior can be
13400 * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
13401 * flag. It's also worth noting that this only works if the name of
13402 * interest is activatable in the first place. E.g. in some cases it
13403 * is not possible to launch an owner for the requested name. In this
13404 * case, #GDBusObjectManagerClient object construction still succeeds but
13405 * there will be no object proxies
13406 * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
13407 * the #GDBusObjectManagerClient:name-owner property is %NULL.
13409 * The owner of the requested name can come and go (for example
13410 * consider a system service being restarted) – #GDBusObjectManagerClient
13411 * handles this case too; simply connect to the #GObject::notify
13412 * signal to watch for changes on the #GDBusObjectManagerClient:name-owner
13413 * property. When the name owner vanishes, the behavior is that
13414 * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
13415 * emission of the #GObject::notify signal) and then
13416 * #GDBusObjectManager::object-removed signals are synthesized
13417 * for all currently existing object proxies. Since
13418 * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
13419 * use this information to disambiguate a synthesized signal from a
13420 * genuine signal caused by object removal on the remote
13421 * #GDBusObjectManager. Similarly, when a new name owner appears,
13422 * #GDBusObjectManager::object-added signals are synthesized
13423 * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
13424 * object proxies have been added, the #GDBusObjectManagerClient:name-owner
13425 * is set to the new name owner (this includes emission of the
13426 * #GObject::notify signal). Furthermore, you are guaranteed that
13427 * #GDBusObjectManagerClient:name-owner will alternate between a name owner
13428 * (e.g. <literal>:1.42</literal>) and %NULL even in the case where
13429 * the name of interest is atomically replaced
13431 * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
13432 * instances. All signals (including the
13433 * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
13434 * signal) delivered to #GDBusProxy instances are guaranteed to
13435 * originate from the name owner. This guarantee along with the
13436 * behavior described above, means that certain race conditions
13437 * including the <emphasis><quote>half the proxy is from the old owner
13438 * and the other half is from the new owner</quote></emphasis> problem
13441 * To avoid having the application connect to signals on the returned
13442 * #GDBusObjectProxy and #GDBusProxy objects, the
13443 * #GDBusObject::interface-added,
13444 * #GDBusObject::interface-removed,
13445 * #GDBusProxy::g-properties-changed and
13446 * #GDBusProxy::g-signal signals
13447 * are also emitted on the #GDBusObjectManagerClient instance managing these
13448 * objects. The signals emitted are
13449 * #GDBusObjectManager::interface-added,
13450 * #GDBusObjectManager::interface-removed,
13451 * #GDBusObjectManagerClient::interface-proxy-properties-changed and
13452 * #GDBusObjectManagerClient::interface-proxy-signal.
13454 * Note that all callbacks and signals are emitted in the
13455 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
13456 * that the #GDBusObjectManagerClient object was constructed
13457 * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
13458 * originating from the #GDBusObjectManagerClient object will be created in
13459 * the same context and, consequently, will deliver signals in the
13465 * SECTION:gdbusobjectmanagerserver
13466 * @short_description: Service-side object manager
13467 * @include: gio/gio.h
13469 * #GDBusObjectManagerServer is used to export #GDBusObject instances using
13470 * the standardized <ulink
13471 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
13472 * interface. For example, remote D-Bus clients can get all objects
13473 * and properties in a single call. Additionally, any change in the
13474 * object hierarchy is broadcast using signals. This means that D-Bus
13475 * clients can keep caches up to date by only listening to D-Bus
13478 * See #GDBusObjectManagerClient for the client-side code that is
13479 * intended to be used with #GDBusObjectManagerServer or any D-Bus
13480 * object implementing the org.freedesktop.DBus.ObjectManager
13486 * SECTION:gdbusobjectproxy
13487 * @short_description: Client-side D-Bus object
13488 * @include: gio/gio.h
13490 * A #GDBusObjectProxy is an object used to represent a remote object
13491 * with one or more D-Bus interfaces. Normally, you don't instantiate
13492 * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
13493 * is used to obtain it.
13500 * SECTION:gdbusobjectskeleton
13501 * @short_description: Service-side D-Bus object
13502 * @include: gio/gio.h
13504 * A #GDBusObjectSkeleton instance is essentially a group of D-Bus
13505 * interfaces. The set of exported interfaces on the object may be
13506 * dynamic and change at runtime.
13508 * This type is intended to be used with #GDBusObjectManager.
13513 * SECTION:gdbusproxy
13514 * @short_description: Client-side D-Bus interface proxy
13515 * @include: gio/gio.h
13517 * #GDBusProxy is a base class used for proxies to access a D-Bus
13518 * interface on a remote object. A #GDBusProxy can be constructed for
13519 * both well-known and unique names.
13521 * By default, #GDBusProxy will cache all properties (and listen to
13522 * changes) of the remote object, and proxy all signals that gets
13523 * emitted. This behaviour can be changed by passing suitable
13524 * #GDBusProxyFlags when the proxy is created. If the proxy is for a
13525 * well-known name, the property cache is flushed when the name owner
13526 * vanishes and reloaded when a name owner appears.
13528 * If a #GDBusProxy is used for a well-known name, the owner of the
13529 * name is tracked and can be read from
13530 * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
13531 * get notified of changes. Additionally, only signals and property
13532 * changes emitted from the current name owner are considered and
13533 * calls are always sent to the current name owner. This avoids a
13534 * number of race conditions when the name is lost by one owner and
13535 * claimed by another. However, if no name owner currently exists,
13536 * then calls will be sent to the well-known name which may result in
13537 * the message bus launching an owner (unless
13538 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
13540 * The generic #GDBusProxy::g-properties-changed and
13541 * #GDBusProxy::g-signal signals are not very convenient to work
13542 * with. Therefore, the recommended way of working with proxies is to
13543 * subclass #GDBusProxy, and have more natural properties and signals
13544 * in your derived class. See <xref linkend="gdbus-example-gdbus-codegen"/>
13545 * for how this can easily be done using the
13546 * <command><link linkend="gdbus-codegen">gdbus-codegen</link></command>
13549 * A #GDBusProxy instance can be used from multiple threads but note
13550 * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
13551 * and #GObject::notify) are emitted in the
13552 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
13553 * of the thread where the instance was constructed.
13555 * <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>
13560 * SECTION:gdbusserver
13561 * @short_description: Helper for accepting connections
13562 * @include: gio/gio.h
13564 * #GDBusServer is a helper for listening to and accepting D-Bus
13565 * connections. This can be used to create a new D-Bus server, allowing two
13566 * peers to use the D-Bus protocol for their own specialized communication.
13567 * A server instance provided in this way will not perform message routing or
13568 * implement the org.freedesktop.DBus interface.
13570 * To just export an object on a well-known name on a message bus, such as the
13571 * session or system bus, you should instead use g_bus_own_name().
13573 * <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>
13578 * SECTION:gdbusutils
13579 * @title: D-Bus Utilities
13580 * @short_description: Various utilities related to D-Bus.
13581 * @include: gio/gio.h
13583 * Various utility routines related to D-Bus.
13588 * SECTION:gdesktopappinfo
13589 * @title: GDesktopAppInfo
13590 * @short_description: Application information from desktop files
13591 * @include: gio/gdesktopappinfo.h
13593 * #GDesktopAppInfo is an implementation of #GAppInfo based on
13596 * Note that <filename><gio/gdesktopappinfo.h></filename> belongs to
13597 * the UNIX-specific GIO interfaces, thus you have to use the
13598 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
13604 * @short_description: Drive management
13605 * @include: gio/gio.h
13607 * #GDrive - this represent a piece of hardware connected to the machine.
13608 * It's generally only created for removable hardware or hardware with
13611 * #GDrive is a container class for #GVolume objects that stem from
13612 * the same piece of media. As such, #GDrive abstracts a drive with
13613 * (or without) removable media and provides operations for querying
13614 * whether media is available, determing whether media change is
13615 * automatically detected and ejecting the media.
13617 * If the #GDrive reports that media isn't automatically detected, one
13618 * can poll for media; typically one should not do this periodically
13619 * as a poll for media operation is potententially expensive and may
13620 * spin up the drive creating noise.
13622 * #GDrive supports starting and stopping drives with authentication
13623 * support for the former. This can be used to support a diverse set
13624 * of use cases including connecting/disconnecting iSCSI devices,
13625 * powering down external disk enclosures and starting/stopping
13626 * multi-disk devices such as RAID devices. Note that the actual
13627 * semantics and side-effects of starting/stopping a #GDrive may vary
13628 * according to implementation. To choose the correct verbs in e.g. a
13629 * file manager, use g_drive_get_start_stop_type().
13631 * For porting from GnomeVFS note that there is no equivalent of
13632 * #GDrive in that API.
13638 * @short_description: An object for emblems
13639 * @include: gio/gio.h
13640 * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
13642 * #GEmblem is an implementation of #GIcon that supports
13643 * having an emblem, which is an icon with additional properties.
13644 * It can than be added to a #GEmblemedIcon.
13646 * Currently, only metainformation about the emblem's origin is
13647 * supported. More may be added in the future.
13652 * SECTION:gemblemedicon
13653 * @short_description: Icon with emblems
13654 * @include: gio/gio.h
13655 * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
13657 * #GEmblemedIcon is an implementation of #GIcon that supports
13658 * adding an emblem to an icon. Adding multiple emblems to an
13659 * icon is ensured via g_emblemed_icon_add_emblem().
13661 * Note that #GEmblemedIcon allows no control over the position
13662 * of the emblems. See also #GEmblem for more information.
13668 * @short_description: File and Directory Handling
13669 * @include: gio/gio.h
13670 * @see_also: #GFileInfo, #GFileEnumerator
13672 * #GFile is a high level abstraction for manipulating files on a
13673 * virtual file system. #GFile<!-- -->s are lightweight, immutable
13674 * objects that do no I/O upon creation. It is necessary to understand that
13675 * #GFile objects do not represent files, merely an identifier for a file. All
13676 * file content I/O is implemented as streaming operations (see #GInputStream and
13679 * To construct a #GFile, you can use:
13680 * g_file_new_for_path() if you have a path.
13681 * g_file_new_for_uri() if you have a URI.
13682 * g_file_new_for_commandline_arg() for a command line argument.
13683 * g_file_new_tmp() to create a temporary file from a template.
13684 * g_file_parse_name() from a utf8 string gotten from g_file_get_parse_name().
13686 * One way to think of a #GFile is as an abstraction of a pathname. For normal
13687 * files the system pathname is what is stored internally, but as #GFile<!-- -->s
13688 * are extensible it could also be something else that corresponds to a pathname
13689 * in a userspace implementation of a filesystem.
13691 * #GFile<!-- -->s make up hierarchies of directories and files that correspond to the
13692 * files on a filesystem. You can move through the file system with #GFile using
13693 * g_file_get_parent() to get an identifier for the parent directory, g_file_get_child()
13694 * to get a child within a directory, g_file_resolve_relative_path() to resolve a relative
13695 * path between two #GFile<!-- -->s. There can be multiple hierarchies, so you may not
13696 * end up at the same root if you repeatedly call g_file_get_parent() on two different
13699 * All #GFile<!-- -->s have a basename (get with g_file_get_basename()). These names
13700 * are byte strings that are used to identify the file on the filesystem (relative to
13701 * its parent directory) and there is no guarantees that they have any particular charset
13702 * encoding or even make any sense at all. If you want to use filenames in a user
13703 * interface you should use the display name that you can get by requesting the
13704 * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().
13705 * This is guaranteed to be in utf8 and can be used in a user interface. But always
13706 * store the real basename or the #GFile to use to actually access the file, because
13707 * there is no way to go from a display name to the actual name.
13709 * Using #GFile as an identifier has the same weaknesses as using a path in that
13710 * there may be multiple aliases for the same file. For instance, hard or
13711 * soft links may cause two different #GFile<!-- -->s to refer to the same file.
13712 * Other possible causes for aliases are: case insensitive filesystems, short
13713 * and long names on Fat/NTFS, or bind mounts in Linux. If you want to check if
13714 * two #GFile<!-- -->s point to the same file you can query for the
13715 * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial
13716 * canonicalization of pathnames passed in, so that trivial differences in the
13717 * path string used at creation (duplicated slashes, slash at end of path, "."
13718 * or ".." path segments, etc) does not create different #GFile<!-- -->s.
13720 * Many #GFile operations have both synchronous and asynchronous versions
13721 * to suit your application. Asynchronous versions of synchronous functions
13722 * simply have _async() appended to their function names. The asynchronous
13723 * I/O functions call a #GAsyncReadyCallback which is then used to finalize
13724 * the operation, producing a GAsyncResult which is then passed to the
13725 * function's matching _finish() operation.
13727 * Some #GFile operations do not have synchronous analogs, as they may
13728 * take a very long time to finish, and blocking may leave an application
13729 * unusable. Notable cases include:
13730 * g_file_mount_mountable() to mount a mountable file.
13731 * g_file_unmount_mountable_with_operation() to unmount a mountable file.
13732 * g_file_eject_mountable_with_operation() to eject a mountable file.
13734 * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
13735 * One notable feature of #GFile<!-- -->s are entity tags, or "etags" for
13736 * short. Entity tags are somewhat like a more abstract version of the
13737 * traditional mtime, and can be used to quickly determine if the file has
13738 * been modified from the version on the file system. See the HTTP 1.1
13739 * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink>
13740 * for HTTP Etag headers, which are a very similar concept.
13746 * SECTION:gfileattribute
13747 * @short_description: Key-Value Paired File Attributes
13748 * @include: gio/gio.h
13749 * @see_also: #GFile, #GFileInfo
13751 * File attributes in GIO consist of a list of key-value pairs.
13753 * Keys are strings that contain a key namespace and a key name, separated
13754 * by a colon, e.g. "namespace:keyname". Namespaces are included to sort
13755 * key-value pairs by namespaces for relevance. Keys can be retrived
13756 * using wildcards, e.g. "standard::*" will return all of the keys in the
13757 * "standard" namespace.
13759 * The list of possible attributes for a filesystem (pointed to by a #GFile) is
13760 * available as a #GFileAttributeInfoList. This list is queryable by key names
13761 * as indicated earlier.
13763 * Information is stored within the list in #GFileAttributeInfo structures.
13764 * The info structure can store different types, listed in the enum
13765 * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
13766 * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
13768 * Classes that implement #GFileIface will create a #GFileAttributeInfoList and
13769 * install default keys and values for their given file system, architecture,
13770 * and other possible implementation details (e.g., on a UNIX system, a file
13771 * attribute key will be registered for the user id for a given file).
13775 * <title>GFileAttributes Default Namespaces</title>
13776 * <tgroup cols='2' align='left'><thead>
13777 * <row><entry>Namspace</entry><entry>Description</entry></row>
13780 * <row><entry>"standard"</entry><entry>The "Standard" namespace. General file
13781 * information that any application may need should be put in this namespace.
13782 * Examples include the file's name, type, and size.</entry></row>
13783 * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link>
13784 * namespace. Currently, the only key in this namespace is "value", which contains
13785 * the value of the current entity tag.</entry></row>
13786 * <row><entry>"id"</entry><entry>The "Identification" namespace. This
13787 * namespace is used by file managers and applications that list directories
13788 * to check for loops and to uniquely identify files.</entry></row>
13789 * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check
13790 * if a user has the proper privilidges to access files and perform
13791 * file operations. Keys in this namespace are made to be generic
13792 * and easily understood, e.g. the "can_read" key is %TRUE if
13793 * the current user has permission to read the file. UNIX permissions and
13794 * NTFS ACLs in Windows should be mapped to these values.</entry></row>
13795 * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes
13796 * simple boolean keys for checking if a file or path supports mount operations, e.g.
13797 * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row>
13798 * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file
13799 * access, changed, created times. </entry></row>
13800 * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific
13801 * information and may not be available for all files. Examples include
13802 * the UNIX "UID", "GID", etc.</entry></row>
13803 * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific
13804 * information and may not be available for all files. Examples include
13805 * "is_system" for checking if a file is marked as a system file, and "is_archive"
13806 * for checking if a file is marked as an archive file.</entry></row>
13807 * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information
13808 * about who owns a file. May not be available for all file systems. Examples include
13809 * "user" for getting the user name of the file owner. This information is often mapped from
13810 * some backend specific data such as a unix UID.</entry></row>
13811 * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes
13812 * information about file thumbnails and their location within the file system. Examples of
13813 * keys in this namespace include "path" to get the location of a thumbnail, and "failed"
13814 * to check if thumbnailing of the file failed.</entry></row>
13815 * <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information
13816 * about the file system where a file is located, such as its type, how much
13817 * space is left available, and the overall size of the file system.</entry></row>
13818 * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace
13819 * contain information about the current GVFS backend in use. </entry></row>
13820 * <row><entry>"xattr"</entry><entry>The "xattr" namespace. Gets information
13821 * about extended user attributes. See attr(5). The "user." prefix of the
13822 * extended user attribute name is stripped away when constructing keys in
13823 * this namespace, e.g. "xattr::mime_type" for the extended attribute with
13824 * the name "user.mime_type". Note that this information is only available
13825 * if GLib has been built with extended attribute support.</entry></row>
13826 * <row><entry>"xattr-sys"</entry><entry>The "xattr-sys" namespace.
13827 * Gets information about extended attributes which are not user-specific.
13828 * See attr(5). Note that this information is only available if GLib
13829 * has been built with extended attribute support.</entry></row>
13830 * <row><entry>"selinux"</entry><entry>The "SELinux" namespace. Includes
13831 * information about the SELinux context of files. Note that this information
13832 * is only available if GLib has been built with SELinux support.</entry></row>
13838 * Please note that these are not all of the possible namespaces.
13839 * More namespaces can be added from GIO modules or by individual applications.
13840 * For more information about writing GIO modules, see #GIOModule.
13842 * <!-- TODO: Implementation note about using extended attributes on supported
13846 * <title>GFileAttributes Built-in Keys and Value Types</title>
13847 * <tgroup cols='3' align='left'><thead>
13848 * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row>
13850 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row>
13851 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row>
13852 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row>
13853 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row>
13854 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row>
13855 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte string</entry></row>
13856 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row>
13857 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row>
13858 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object (#GIcon)</entry></row>
13859 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row>
13860 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row>
13861 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row>
13862 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row>
13863 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte string</entry></row>
13864 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row>
13865 * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row>
13866 * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row>
13867 * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row>
13868 * <row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row>
13869 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row>
13870 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row>
13871 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row>
13872 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row>
13873 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row>
13874 * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row>
13875 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row>
13876 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row>
13877 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row>
13878 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row>
13879 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row>
13880 * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row>
13881 * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row>
13882 * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row>
13883 * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row>
13884 * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row>
13885 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row>
13886 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row>
13887 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row>
13888 * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row>
13889 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row>
13890 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row>
13891 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row>
13892 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row>
13893 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row>
13894 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row>
13895 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row>
13896 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row>
13897 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row>
13898 * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row>
13899 * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row>
13900 * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row>
13901 * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row>
13902 * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row>
13903 * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row>
13904 * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row>
13905 * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row>
13906 * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object (#GIcon)</entry></row>
13907 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row>
13908 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row>
13909 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_USED</entry><entry>filesystem::used</entry><entry>uint64</entry></row>
13910 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row>
13911 * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row>
13912 * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row>
13913 * <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row>
13914 * </tbody></tgroup></table></para>
13916 * Note that there are no predefined keys in the "xattr" and "xattr-sys"
13917 * namespaces. Keys for the "xattr" namespace are constructed by stripping
13918 * away the "user." prefix from the extended user attribute, and prepending
13919 * "xattr::". Keys for the "xattr-sys" namespace are constructed by
13920 * concatenating "xattr-sys::" with the extended attribute name. All extended
13921 * attribute values are returned as hex-encoded strings in which bytes outside
13922 * the ASCII range are encoded as hexadecimal escape sequences of the form
13923 * \x<replaceable>nn</replaceable>.
13928 * SECTION:gfiledescriptorbased
13929 * @short_description: Interface for file descriptor based IO
13930 * @include: gio/gfiledescriptorbased.h
13931 * @see_also: #GInputStream, #GOutputStream
13933 * #GFileDescriptorBased is implemented by streams (implementations of
13934 * #GInputStream or #GOutputStream) that are based on file descriptors.
13936 * Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to
13937 * the UNIX-specific GIO interfaces, thus you have to use the
13938 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
13945 * SECTION:gfileenumerator
13946 * @short_description: Enumerated Files Routines
13947 * @include: gio/gio.h
13949 * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
13950 * returning a #GFileInfo structure for each file enumerated (e.g.
13951 * g_file_enumerate_children() will return a #GFileEnumerator for each
13952 * of the children within a directory).
13954 * To get the next file's information from a #GFileEnumerator, use
13955 * g_file_enumerator_next_file() or its asynchronous version,
13956 * g_file_enumerator_next_files_async(). Note that the asynchronous
13957 * version will return a list of #GFileInfo<!---->s, whereas the
13958 * synchronous will only return the next file in the enumerator.
13960 * To close a #GFileEnumerator, use g_file_enumerator_close(), or
13961 * its asynchronous version, g_file_enumerator_close_async(). Once
13962 * a #GFileEnumerator is closed, no further actions may be performed
13963 * on it, and it should be freed with g_object_unref().
13968 * SECTION:gfileicon
13969 * @short_description: Icons pointing to an image file
13970 * @include: gio/gio.h
13971 * @see_also: #GIcon, #GLoadableIcon
13973 * #GFileIcon specifies an icon by pointing to an image file
13974 * to be used as icon.
13979 * SECTION:gfileinfo
13980 * @short_description: File Information and Attributes
13981 * @include: gio/gio.h
13982 * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link>
13984 * Functionality for manipulating basic metadata for files. #GFileInfo
13985 * implements methods for getting information that all files should
13986 * contain, and allows for manipulation of extended attributes.
13988 * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more
13989 * information on how GIO handles file attributes.
13991 * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its
13992 * async variant). To obtain a #GFileInfo for a file input or output
13993 * stream, use g_file_input_stream_query_info() or
13994 * g_file_output_stream_query_info() (or their async variants).
13996 * To change the actual attributes of a file, you should then set the
13997 * attribute in the #GFileInfo and call g_file_set_attributes_from_info()
13998 * or g_file_set_attributes_async() on a GFile.
14000 * However, not all attributes can be changed in the file. For instance,
14001 * the actual size of a file cannot be changed via g_file_info_set_size().
14002 * You may call g_file_query_settable_attributes() and
14003 * g_file_query_writable_namespaces() to discover the settable attributes
14004 * of a particular file at runtime.
14006 * #GFileAttributeMatcher allows for searching through a #GFileInfo for
14012 * SECTION:gfileinputstream
14013 * @short_description: File input streaming operations
14014 * @include: gio/gio.h
14015 * @see_also: #GInputStream, #GDataInputStream, #GSeekable
14017 * GFileInputStream provides input streams that take their
14018 * content from a file.
14020 * GFileInputStream implements #GSeekable, which allows the input
14021 * stream to jump to arbitrary positions in the file, provided the
14022 * filesystem of the file allows it. To find the position of a file
14023 * input stream, use g_seekable_tell(). To find out if a file input
14024 * stream supports seeking, use g_seekable_can_seek().
14025 * To position a file input stream, use g_seekable_seek().
14030 * SECTION:gfileiostream
14031 * @short_description: File read and write streaming operations
14032 * @include: gio/gio.h
14033 * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
14035 * GFileIOStream provides io streams that both read and write to the same
14038 * GFileIOStream implements #GSeekable, which allows the io
14039 * stream to jump to arbitrary positions in the file and to truncate
14040 * the file, provided the filesystem of the file supports these
14043 * To find the position of a file io stream, use
14044 * g_seekable_tell().
14046 * To find out if a file io stream supports seeking, use g_seekable_can_seek().
14047 * To position a file io stream, use g_seekable_seek().
14048 * To find out if a file io stream supports truncating, use
14049 * g_seekable_can_truncate(). To truncate a file io
14050 * stream, use g_seekable_truncate().
14052 * The default implementation of all the #GFileIOStream operations
14053 * and the implementation of #GSeekable just call into the same operations
14054 * on the output stream.
14061 * SECTION:gfilemonitor
14062 * @short_description: File Monitor
14063 * @include: gio/gio.h
14065 * Monitors a file or directory for changes.
14067 * To obtain a #GFileMonitor for a file or directory, use
14068 * g_file_monitor(), g_file_monitor_file(), or
14069 * g_file_monitor_directory().
14071 * To get informed about changes to the file or directory you are
14072 * monitoring, connect to the #GFileMonitor::changed signal. The
14073 * signal will be emitted in the <link
14074 * linkend="g-main-context-push-thread-default">thread-default main
14075 * context</link> of the thread that the monitor was created in
14076 * (though if the global default main context is blocked, this may
14077 * cause notifications to be blocked even if the thread-default
14078 * context is still running).
14083 * SECTION:gfilenamecompleter
14084 * @short_description: Filename Completer
14085 * @include: gio/gio.h
14087 * Completes partial file and directory names given a partial string by
14088 * looking in the file system for clues. Can return a list of possible
14089 * completion strings for widget implementations.
14094 * SECTION:gfileoutputstream
14095 * @short_description: File output streaming operations
14096 * @include: gio/gio.h
14097 * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
14099 * GFileOutputStream provides output streams that write their
14100 * content to a file.
14102 * GFileOutputStream implements #GSeekable, which allows the output
14103 * stream to jump to arbitrary positions in the file and to truncate
14104 * the file, provided the filesystem of the file supports these
14107 * To find the position of a file output stream, use g_seekable_tell().
14108 * To find out if a file output stream supports seeking, use
14109 * g_seekable_can_seek().To position a file output stream, use
14110 * g_seekable_seek(). To find out if a file output stream supports
14111 * truncating, use g_seekable_can_truncate(). To truncate a file output
14112 * stream, use g_seekable_truncate().
14117 * SECTION:gfilterinputstream
14118 * @short_description: Filter Input Stream
14119 * @include: gio/gio.h
14121 * Base class for input stream implementations that perform some
14122 * kind of filtering operation on a base stream. Typical examples
14123 * of filtering operations are character set conversion, compression
14124 * and byte order flipping.
14129 * SECTION:gfilteroutputstream
14130 * @short_description: Filter Output Stream
14131 * @include: gio/gio.h
14133 * Base class for output stream implementations that perform some
14134 * kind of filtering operation on a base stream. Typical examples
14135 * of filtering operations are character set conversion, compression
14136 * and byte order flipping.
14142 * @short_description: Interface for icons
14143 * @include: gio/gio.h
14145 * #GIcon is a very minimal interface for icons. It provides functions
14146 * for checking the equality of two icons, hashing of icons and
14147 * serializing an icon to and from strings.
14149 * #GIcon does not provide the actual pixmap for the icon as this is out
14150 * of GIO's scope, however implementations of #GIcon may contain the name
14151 * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
14153 * To obtain a hash of a #GIcon, see g_icon_hash().
14155 * To check if two #GIcons are equal, see g_icon_equal().
14157 * For serializing a #GIcon, use g_icon_to_string() and
14158 * g_icon_new_for_string().
14160 * If your application or library provides one or more #GIcon
14161 * implementations you need to ensure that each #GType is registered
14162 * with the type system prior to calling g_icon_new_for_string().
14167 * SECTION:ginetaddress
14168 * @short_description: An IPv4/IPv6 address
14170 * #GInetAddress represents an IPv4 or IPv6 internet address. Use
14171 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to
14172 * look up the #GInetAddress for a hostname. Use
14173 * g_resolver_lookup_by_address() or
14174 * g_resolver_lookup_by_address_async() to look up the hostname for a
14177 * To actually connect to a remote host, you will need a
14178 * #GInetSocketAddress (which includes a #GInetAddress as well as a
14184 * SECTION:ginetaddressmask
14185 * @short_description: An IPv4/IPv6 address mask
14187 * #GInetAddressMask represents a range of IPv4 or IPv6 addresses
14188 * described by a base address and a length indicating how many bits
14189 * of the base address are relevant for matching purposes. These are
14190 * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10".
14195 * SECTION:ginetsocketaddress
14196 * @short_description: Internet GSocketAddress
14198 * An IPv4 or IPv6 socket address; that is, the combination of a
14199 * #GInetAddress and a port number.
14204 * SECTION:ginitable
14205 * @short_description: Failable object initialization interface
14206 * @include: gio/gio.h
14207 * @see_also: #GAsyncInitable
14209 * #GInitable is implemented by objects that can fail during
14210 * initialization. If an object implements this interface then
14211 * it must be initialized as the first thing after construction,
14212 * either via g_initable_init() or g_async_initable_init_async()
14213 * (the latter is only available if it also implements #GAsyncInitable).
14215 * If the object is not initialized, or initialization returns with an
14216 * error, then all operations on the object except g_object_ref() and
14217 * g_object_unref() are considered to be invalid, and have undefined
14218 * behaviour. They will often fail with g_critical() or g_warning(), but
14219 * this must not be relied on.
14221 * Users of objects implementing this are not intended to use
14222 * the interface method directly, instead it will be used automatically
14223 * in various ways. For C applications you generally just call
14224 * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper.
14225 * This will call g_initable_init() under the cover, returning %NULL and
14226 * setting a #GError on failure (at which point the instance is
14229 * For bindings in languages where the native constructor supports
14230 * exceptions the binding could check for objects implemention %GInitable
14231 * during normal construction and automatically initialize them, throwing
14232 * an exception on failure.
14237 * SECTION:ginputstream
14238 * @short_description: Base class for implementing streaming input
14239 * @include: gio/gio.h
14241 * GInputStream has functions to read from a stream (g_input_stream_read()),
14242 * to close a stream (g_input_stream_close()) and to skip some content
14243 * (g_input_stream_skip()).
14245 * To copy the content of an input stream to an output stream without
14246 * manually handling the reads and writes, use g_output_stream_splice().
14248 * All of these functions have async variants too.
14254 * @short_description: Error helper functions
14255 * @include: gio/gio.h
14257 * Contains helper functions for reporting errors to the user.
14262 * SECTION:giomodule
14263 * @short_description: Loadable GIO Modules
14264 * @include: gio/gio.h
14266 * Provides an interface and default functions for loading and unloading
14267 * modules. This is used internally to make GIO extensible, but can also
14268 * be used by others to implement module loading.
14273 * SECTION:gioscheduler
14274 * @short_description: I/O Scheduler
14275 * @include: gio/gio.h
14277 * Schedules asynchronous I/O operations. #GIOScheduler integrates
14278 * into the main event loop (#GMainLoop) and uses threads.
14280 * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm>
14281 * Each I/O operation has a priority, and the scheduler uses the priorities
14282 * to determine the order in which operations are executed. They are
14283 * <emphasis>not</emphasis> used to determine system-wide I/O scheduling.
14284 * Priorities are integers, with lower numbers indicating higher priority.
14285 * It is recommended to choose priorities between %G_PRIORITY_LOW and
14286 * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default.
14292 * SECTION:giostream
14293 * @short_description: Base class for implementing read/write streams
14294 * @include: gio/gio.h
14295 * @see_also: #GInputStream, #GOutputStream
14297 * GIOStream represents an object that has both read and write streams.
14298 * Generally the two streams acts as separate input and output streams,
14299 * but they share some common resources and state. For instance, for
14300 * seekable streams they may use the same position in both streams.
14302 * Examples of #GIOStream objects are #GSocketConnection which represents
14303 * a two-way network connection, and #GFileIOStream which represent a
14304 * file handle opened in read-write mode.
14306 * To do the actual reading and writing you need to get the substreams
14307 * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
14309 * The #GIOStream object owns the input and the output streams, not the other
14310 * way around, so keeping the substreams alive will not keep the #GIOStream
14311 * object alive. If the #GIOStream object is freed it will be closed, thus
14312 * closing the substream, so even if the substreams stay alive they will
14313 * always just return a %G_IO_ERROR_CLOSED for all operations.
14315 * To close a stream use g_io_stream_close() which will close the common
14316 * stream object and also the individual substreams. You can also close
14317 * the substreams themselves. In most cases this only marks the
14318 * substream as closed, so further I/O on it fails. However, some streams
14319 * may support "half-closed" states where one direction of the stream
14320 * is actually shut down.
14327 * SECTION:gloadableicon
14328 * @short_description: Loadable Icons
14329 * @include: gio/gio.h
14330 * @see_also: #GIcon, #GThemedIcon
14332 * Extends the #GIcon interface and adds the ability to
14333 * load icons from streams.
14338 * SECTION:gmemoryinputstream
14339 * @short_description: Streaming input operations on memory chunks
14340 * @include: gio/gio.h
14341 * @see_also: #GMemoryOutputStream
14343 * #GMemoryInputStream is a class for using arbitrary
14344 * memory chunks as input for GIO streaming input operations.
14349 * SECTION:gmemoryoutputstream
14350 * @short_description: Streaming output operations on memory chunks
14351 * @include: gio/gio.h
14352 * @see_also: #GMemoryInputStream
14354 * #GMemoryOutputStream is a class for using arbitrary
14355 * memory chunks as output for GIO streaming output operations.
14362 * @short_description: A simple implementation of GMenuModel
14364 * #GMenu is a simple implementation of #GMenuModel.
14365 * You populate a #GMenu by adding #GMenuItem instances to it.
14367 * There are some convenience functions to allow you to directly
14368 * add items (avoiding #GMenuItem) for the common cases. To add
14369 * a regular item, use g_menu_insert(). To add a section, use
14370 * g_menu_insert_section(). To add a submenu, use
14371 * g_menu_insert_submenu().
14376 * SECTION:gmenuexporter
14377 * @title: GMenuModel exporter
14378 * @short_description: Export GMenuModels on D-Bus
14379 * @see_also: #GMenuModel, #GDBusMenuModel
14381 * These functions support exporting a #GMenuModel on D-Bus.
14382 * The D-Bus interface that is used is a private implementation
14385 * To access an exported #GMenuModel remotely, use
14386 * g_dbus_menu_model_get() to obtain a #GDBusMenuModel.
14391 * SECTION:gmenumodel
14392 * @title: GMenuModel
14393 * @short_description: An abstract class representing the contents of a menu
14394 * @see_also: #GActionGroup
14396 * #GMenuModel represents the contents of a menu -- an ordered list of
14397 * menu items. The items are associated with actions, which can be
14398 * activated through them. Items can be grouped in sections, and may
14399 * have submenus associated with them. Both items and sections usually
14400 * have some representation data, such as labels or icons. The type of
14401 * the associated action (ie whether it is stateful, and what kind of
14402 * state it has) can influence the representation of the item.
14404 * The conceptual model of menus in #GMenuModel is hierarchical:
14405 * sections and submenus are again represented by #GMenuModels.
14406 * Menus themselves do not define their own roles. Rather, the role
14407 * of a particular #GMenuModel is defined by the item that references
14408 * it (or, in the case of the 'root' menu, is defined by the context
14409 * in which it is used).
14411 * As an example, consider the visible portions of the menu in
14412 * <xref linkend="menu-example"/>.
14414 * <figure id="menu-example">
14415 * <title>An example menu</title>
14416 * <graphic fileref="menu-example.png" format="PNG"></graphic>
14419 * There are 8 "menus" visible in the screenshot: one menubar, two
14420 * submenus and 5 sections:
14422 * <listitem>the toplevel menubar (containing 4 items)</listitem>
14423 * <listitem>the View submenu (containing 3 sections)</listitem>
14424 * <listitem>the first section of the View submenu (containing 2 items)</listitem>
14425 * <listitem>the second section of the View submenu (containing 1 item)</listitem>
14426 * <listitem>the final section of the View submenu (containing 1 item)</listitem>
14427 * <listitem>the Highlight Mode submenu (containing 2 sections)</listitem>
14428 * <listitem>the Sources section (containing 2 items)</listitem>
14429 * <listitem>the Markup section (containing 2 items)</listitem>
14432 * <xref linkend="menu-model"/> illustrates the conceptual connection between
14433 * these 8 menus. Each large block in the figure represents a menu and the
14434 * smaller blocks within the large block represent items in that menu. Some
14435 * items contain references to other menus.
14437 * <figure id="menu-model">
14438 * <title>A menu model</title>
14439 * <graphic fileref="menu-model.png" format="PNG"></graphic>
14442 * Notice that the separators visible in <xref linkend="menu-example"/>
14443 * appear nowhere in <xref linkend="menu-model"/>. This is because
14444 * separators are not explicitly represented in the menu model. Instead,
14445 * a separator is inserted between any two non-empty sections of a menu.
14446 * Section items can have labels just like any other item. In that case,
14447 * a display system may show a section header instead of a separator.
14449 * The motivation for this abstract model of application controls is
14450 * that modern user interfaces tend to make these controls available
14451 * outside the application. Examples include global menus, jumplists,
14452 * dash boards, etc. To support such uses, it is necessary to 'export'
14453 * information about actions and their representation in menus, which
14454 * is exactly what the
14455 * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
14457 * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link>
14458 * do for #GActionGroup and #GMenuModel. The client-side counterparts
14459 * to make use of the exported information are #GDBusActionGroup and
14462 * The API of #GMenuModel is very generic, with iterators for the
14463 * attributes and links of an item, see g_menu_model_iterate_item_attributes()
14464 * and g_menu_model_iterate_item_links(). The 'standard' attributes and
14465 * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
14466 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
14467 * and %G_MENU_LINK_SUBMENU.
14469 * Items in a #GMenuModel represent active controls if they refer to
14470 * an action that can get activated when the user interacts with the
14471 * menu item. The reference to the action is encoded by the string id
14472 * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely
14473 * identifies an action in an action group. Which action group(s) provide
14474 * actions depends on the context in which the menu model is used.
14475 * E.g. when the model is exported as the application menu of a
14476 * #GtkApplication, actions can be application-wide or window-specific
14477 * (and thus come from two different action groups). By convention, the
14478 * application-wide actions have names that start with "app.", while the
14479 * names of window-specific actions start with "win.".
14481 * While a wide variety of stateful actions is possible, the following
14482 * is the minimum that is expected to be supported by all users of exported
14483 * menu information:
14485 * <listitem>an action with no parameter type and no state</listitem>
14486 * <listitem>an action with no parameter type and boolean state</listitem>
14487 * <listitem>an action with string parameter type and string state</listitem>
14490 * <formalpara><title>Stateless</title>
14492 * A stateless action typically corresponds to an ordinary menu item.
14495 * Selecting such a menu item will activate the action (with no parameter).
14499 * <formalpara><title>Boolean State</title>
14501 * An action with a boolean state will most typically be used with a "toggle"
14502 * or "switch" menu item. The state can be set directly, but activating the
14503 * action (with no parameter) results in the state being toggled.
14506 * Selecting a toggle menu item will activate the action. The menu item should
14507 * be rendered as "checked" when the state is true.
14511 * <formalpara><title>String Parameter and State</title>
14513 * Actions with string parameters and state will most typically be used to
14514 * represent an enumerated choice over the items available for a group of
14515 * radio menu items. Activating the action with a string parameter is
14516 * equivalent to setting that parameter as the state.
14519 * Radio menu items, in addition to being associated with the action, will
14520 * have a target value. Selecting that menu item will result in activation
14521 * of the action with the target value as the parameter. The menu item should
14522 * be rendered as "selected" when the state of the action is equal to the
14523 * target value of the menu item.
14531 * @short_description: Mount management
14532 * @include: gio/gio.h
14533 * @see_also: GVolume, GUnixMountEntry, GUnixMountPoint
14535 * The #GMount interface represents user-visible mounts. Note, when
14536 * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume.
14538 * #GMount is a "mounted" filesystem that you can access. Mounted is in
14539 * quotes because it's not the same as a unix mount, it might be a gvfs
14540 * mount, but you can still access the files on it if you use GIO. Might or
14541 * might not be related to a volume object.
14543 * Unmounting a #GMount instance is an asynchronous operation. For
14544 * more information about asynchronous operations, see #GAsyncResult
14545 * and #GSimpleAsyncResult. To unmount a #GMount instance, first call
14546 * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
14547 * #GAsyncReadyCallback. The callback will be fired when the
14548 * operation has resolved (either with success or failure), and a
14549 * #GAsyncReady structure will be passed to the callback. That
14550 * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
14551 * and the #GAsyncReady data to see if the operation was completed
14552 * successfully. If an @error is present when g_mount_unmount_with_operation_finish()
14553 * is called, then it will be filled with any error information.
14558 * SECTION:gmountoperation
14559 * @short_description: Object used for authentication and user interaction
14560 * @include: gio/gio.h
14562 * #GMountOperation provides a mechanism for interacting with the user.
14563 * It can be used for authenticating mountable operations, such as loop
14564 * mounting files, hard drive partitions or server locations. It can
14565 * also be used to ask the user questions or show a list of applications
14566 * preventing unmount or eject operations from completing.
14568 * Note that #GMountOperation is used for more than just #GMount
14569 * objects – for example it is also used in g_drive_start() and
14572 * Users should instantiate a subclass of this that implements all the
14573 * various callbacks to show the required dialogs, such as
14574 * #GtkMountOperation. If no user interaction is desired (for example
14575 * when automounting filesystems at login time), usually %NULL can be
14576 * passed, see each method taking a #GMountOperation for details.
14581 * SECTION:gnetworkaddress
14582 * @short_description: A GSocketConnectable for resolving hostnames
14583 * @include: gio/gio.h
14585 * #GNetworkAddress provides an easy way to resolve a hostname and
14586 * then attempt to connect to that host, handling the possibility of
14587 * multiple IP addresses and multiple address families.
14589 * See #GSocketConnectable for and example of using the connectable
14595 * SECTION:gnetworkmonitor
14596 * @title: GNetworkMonitor
14597 * @short_description: Network status monitor
14598 * @include: gio/gio.h
14600 * #GNetworkMonitor provides an easy-to-use cross-platform API
14601 * for monitoring network connectivity. On Linux, the implementation
14602 * is based on the kernels netlink interface.
14607 * SECTION:gnetworkservice
14608 * @short_description: A GSocketConnectable for resolving SRV records
14609 * @include: gio/gio.h
14611 * Like #GNetworkAddress does with hostnames, #GNetworkService
14612 * provides an easy way to resolve a SRV record, and then attempt to
14613 * connect to one of the hosts that implements that service, handling
14614 * service priority/weighting, multiple IP addresses, and multiple
14615 * address families.
14617 * See #GSrvTarget for more information about SRV records, and see
14618 * #GSocketConnectable for and example of using the connectable
14624 * SECTION:goutputstream
14625 * @short_description: Base class for implementing streaming output
14626 * @include: gio/gio.h
14628 * GOutputStream has functions to write to a stream (g_output_stream_write()),
14629 * to close a stream (g_output_stream_close()) and to flush pending writes
14630 * (g_output_stream_flush()).
14632 * To copy the content of an input stream to an output stream without
14633 * manually handling the reads and writes, use g_output_stream_splice().
14635 * All of these functions have async variants too.
14640 * SECTION:gpermission
14641 * @title: GPermission
14642 * @short_description: An object representing the permission to perform a certain action
14644 * A #GPermission represents the status of the caller's permission to
14645 * perform a certain action.
14647 * You can query if the action is currently allowed and if it is
14648 * possible to acquire the permission so that the action will be allowed
14651 * There is also an API to actually acquire the permission and one to
14654 * As an example, a #GPermission might represent the ability for the
14655 * user to write to a #GSettings object. This #GPermission object could
14656 * then be used to decide if it is appropriate to show a "Click here to
14657 * unlock" button in a dialog and to provide the mechanism to invoke
14658 * when that button is clicked.
14663 * SECTION:gpollableinputstream
14664 * @short_description: Interface for pollable input streams
14665 * @include: gio/gio.h
14666 * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
14668 * #GPollableInputStream is implemented by #GInputStream<!-- -->s that
14669 * can be polled for readiness to read. This can be used when
14670 * interfacing with a non-GIO API that expects
14671 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
14678 * SECTION:gpollableoutputstream
14679 * @short_description: Interface for pollable output streams
14680 * @include: gio/gio.h
14681 * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
14683 * #GPollableOutputStream is implemented by #GOutputStream<!-- -->s that
14684 * can be polled for readiness to write. This can be used when
14685 * interfacing with a non-GIO API that expects
14686 * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
14694 * @short_description: Interface for proxy handling
14696 * A #GProxy handles connecting to a remote host via a given type of
14697 * proxy server. It is implemented by the 'gio-proxy' extension point.
14698 * The extensions are named after their proxy protocol name. As an
14699 * example, a SOCKS5 proxy implementation can be retrieved with the
14700 * name 'socks5' using the function
14701 * g_io_extension_point_get_extension_by_name().
14708 * SECTION:gproxyaddress
14709 * @short_description: An internet address with proxy information
14711 * Support for proxied #GInetSocketAddress.
14716 * SECTION:gproxyresolver
14717 * @short_description: Asynchronous and cancellable network proxy resolver
14718 * @include: gio/gio.h
14720 * #GProxyResolver provides synchronous and asynchronous network proxy
14721 * resolution. #GProxyResolver is used within #GSocketClient through
14722 * the method g_socket_connectable_proxy_enumerate().
14727 * SECTION:gremoteactiongroup
14728 * @title: GRemoteActionGroup
14729 * @short_description: a #GActionGroup that interacts with other processes
14731 * The GRemoteActionGroup interface is implemented by #GActionGroup
14732 * instances that either transmit action invocations to other processes
14733 * or receive action invocations in the local process from other
14736 * The interface has <literal>_full</literal> variants of the two
14737 * methods on #GActionGroup used to activate actions:
14738 * g_action_group_activate_action() and
14739 * g_action_group_change_action_state(). These variants allow a
14740 * "platform data" #GVariant to be specified: a dictionary providing
14741 * context for the action invocation (for example: timestamps, startup
14742 * notification IDs, etc).
14744 * #GDBusActionGroup implements #GRemoteActionGroup. This provides a
14745 * mechanism to send platform data for action invocations over D-Bus.
14747 * Additionally, g_dbus_connection_export_action_group() will check if
14748 * the exported #GActionGroup implements #GRemoteActionGroup and use the
14749 * <literal>_full</literal> variants of the calls if available. This
14750 * provides a mechanism by which to receive platform data for action
14751 * invocations that arrive by way of D-Bus.
14758 * SECTION:gresolver
14759 * @short_description: Asynchronous and cancellable DNS resolver
14760 * @include: gio/gio.h
14762 * #GResolver provides cancellable synchronous and asynchronous DNS
14763 * resolution, for hostnames (g_resolver_lookup_by_address(),
14764 * g_resolver_lookup_by_name() and their async variants) and SRV
14765 * (service) records (g_resolver_lookup_service()).
14767 * #GNetworkAddress and #GNetworkService provide wrappers around
14768 * #GResolver functionality that also implement #GSocketConnectable,
14769 * making it easy to connect to a remote host/service.
14774 * SECTION:gresource
14775 * @short_description: Resource framework
14776 * @include: gio/gio.h
14778 * Applications and libraries often contain binary or textual data that is really part of the
14779 * application, rather than user data. For instance #GtkBuilder .ui files, splashscreen images,
14780 * GMenu markup xml, CSS files, icons, etc. These are often shipped as files in <filename>$datadir/appname</filename>, or
14781 * manually included as literal strings in the code.
14783 * The #GResource API and the <link linkend="glib-compile-resources">glib-compile-resources</link> program
14784 * provide a convenient and efficient alternative to this which has some nice properties. You
14785 * maintain the files as normal files, so its easy to edit them, but during the build the files
14786 * are combined into a binary bundle that is linked into the executable. This means that loading
14787 * the resource files are efficient (as they are already in memory, shared with other instances) and
14788 * simple (no need to check for things like I/O errors or locate the files in the filesystem). It
14789 * also makes it easier to create relocatable applications.
14791 * Resource files can also be marked as compresses. Such files will be included in the resource bundle
14792 * in a compressed form, but will be automatically uncompressed when the resource is used. This
14793 * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
14795 * Resource files can also be marked to be preprocessed, by setting the value of the
14796 * <literal>preprocess</literal> attribute to a comma-separated list of preprocessing options.
14797 * The only options currently supported are:
14799 * <literal>xml-stripblanks</literal> which will use <command>xmllint</command> to strip
14800 * ignorable whitespace from the xml file. For this to work, the <envar>XMLLINT</envar>
14801 * environment variable must be set to the full path to the xmllint executable, or xmllint
14802 * must be in the PATH; otherwise the preprocessing step is skipped.
14804 * <literal>to-pixdata</literal> which will use <command>gdk-pixbuf-pixdata</command> to convert
14805 * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
14806 * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
14807 * program must be in the PATH, or the <envar>GDK_PIXBUF_PIXDATA</envar> environment variable must be
14808 * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
14811 * Resource bundles are created by the <link linkend="glib-compile-resources">glib-compile-resources</link> program
14812 * which takes an xml file that describes the bundle, and a set of files that the xml references. These
14813 * are combined into a binary resource bundle.
14815 * <example id="resource-example"><title>Example resource description</title>
14816 * <programlisting><![CDATA[
14817 * <?xml version="1.0" encoding="UTF-8"?>
14819 * <gresource prefix="/org/gtk/Example">
14820 * <file>data/splashscreen.png</file>
14821 * <file compressed="true">dialog.ui</file>
14822 * <file preprocess="xml-stripblanks">menumarkup.xml</file>
14825 * ]]></programlisting></example>
14827 * This will create a resource bundle with the following files:
14828 * <programlisting><![CDATA[
14829 * /org/gtk/Example/data/splashscreen.png
14830 * /org/gtk/Example/dialog.ui
14831 * /org/gtk/Example/menumarkup.xml
14832 * ]]></programlisting>
14834 * Note that all resources in the process share the same namespace, so use java-style
14835 * path prefixes (like in the above example) to avoid conflicts.
14837 * You can then use <link linkend="glib-compile-resources">glib-compile-resources</link> to compile the xml to a
14838 * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and
14839 * --generate-header arguments to create a source file and header to link directly into your application.
14841 * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by
14842 * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer
14843 * to the data. You can also use uris like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access
14844 * the resource data.
14846 * There are two forms of the generated source, the default version uses the compiler support for constructor
14847 * and destructor functions (where availible) to automatically create and register the #GResource on startup
14848 * or library load time. If you pass --manual-register two functions to register/unregister the resource is instead
14849 * created. This requires an explicit initialization call in your application/library, but it works on all platforms,
14850 * even on the minor ones where this is not availible. (Constructor support is availible for at least Win32, MacOS and Linux.)
14852 * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries
14853 * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away
14854 * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses
14855 * is for your own resources, and resource data is often used once, during parsing, and then released.
14862 * SECTION:gseekable
14863 * @short_description: Stream seeking interface
14864 * @include: gio/gio.h
14865 * @see_also: #GInputStream, #GOutputStream
14867 * #GSeekable is implemented by streams (implementations of
14868 * #GInputStream or #GOutputStream) that support seeking.
14873 * SECTION:gsettings
14874 * @short_description: High-level API for application settings
14876 * The #GSettings class provides a convenient API for storing and retrieving
14877 * application settings.
14879 * Reads and writes can be considered to be non-blocking. Reading
14880 * settings with #GSettings is typically extremely fast: on
14881 * approximately the same order of magnitude (but slower than) a
14882 * #GHashTable lookup. Writing settings is also extremely fast in terms
14883 * of time to return to your application, but can be extremely expensive
14884 * for other threads and other processes. Many settings backends
14885 * (including dconf) have lazy initialisation which means in the common
14886 * case of the user using their computer without modifying any settings
14887 * a lot of work can be avoided. For dconf, the D-Bus service doesn't
14888 * even need to be started in this case. For this reason, you should
14889 * only ever modify #GSettings keys in response to explicit user action.
14890 * Particular care should be paid to ensure that modifications are not
14891 * made during startup -- for example, when setting the initial value
14892 * of preferences widgets. The built-in g_settings_bind() functionality
14893 * is careful not to write settings in response to notify signals as a
14894 * result of modifications that it makes to widgets.
14896 * When creating a GSettings instance, you have to specify a schema
14897 * that describes the keys in your settings and their types and default
14898 * values, as well as some other information.
14900 * Normally, a schema has as fixed path that determines where the settings
14901 * are stored in the conceptual global tree of settings. However, schemas
14902 * can also be 'relocatable', i.e. not equipped with a fixed path. This is
14903 * useful e.g. when the schema describes an 'account', and you want to be
14904 * able to store a arbitrary number of accounts.
14906 * Unlike other configuration systems (like GConf), GSettings does not
14907 * restrict keys to basic types like strings and numbers. GSettings stores
14908 * values as #GVariant, and allows any #GVariantType for keys. Key names
14909 * are restricted to lowercase characters, numbers and '-'. Furthermore,
14910 * the names must begin with a lowercase character, must not end
14911 * with a '-', and must not contain consecutive dashes.
14913 * Similar to GConf, the default values in GSettings schemas can be
14914 * localized, but the localized values are stored in gettext catalogs
14915 * and looked up with the domain that is specified in the
14916 * <tag class="attribute">gettext-domain</tag> attribute of the
14917 * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
14918 * elements and the category that is specified in the l10n attribute of the
14919 * <tag class="starttag">key</tag> element.
14921 * GSettings uses schemas in a compact binary form that is created
14922 * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
14923 * utility. The input is a schema description in an XML format that can be
14924 * described by the following DTD:
14925 * |[<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>]|
14927 * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename>
14929 * At runtime, schemas are identified by their id (as specified
14930 * in the <tag class="attribute">id</tag> attribute of the
14931 * <tag class="starttag">schema</tag> element). The
14932 * convention for schema ids is to use a dotted name, similar in
14933 * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
14934 * if the settings are for a specific service that owns a D-Bus bus name,
14935 * the D-Bus bus name and schema id should match. For schemas which deal
14936 * with settings not associated with one named application, the id should
14937 * not use StudlyCaps, e.g. "org.gnome.font-rendering".
14939 * In addition to #GVariant types, keys can have types that have enumerated
14940 * types. These can be described by a <tag class="starttag">choice</tag>,
14941 * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
14942 * <xref linkend="schema-enumerated"/>. The underlying type of
14943 * such a key is string, but you can use g_settings_get_enum(),
14944 * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
14945 * access the numeric values corresponding to the string value of enum
14948 * <example id="schema-default-values"><title>Default values</title>
14949 * <programlisting><![CDATA[
14951 * <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
14953 * <key name="greeting" type="s">
14954 * <default l10n="messages">"Hello, earthlings"</default>
14955 * <summary>A greeting</summary>
14957 * Greeting of the invading martians
14961 * <key name="box" type="(ii)">
14962 * <default>(20,30)</default>
14967 * ]]></programlisting></example>
14969 * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
14970 * <programlisting><![CDATA[
14973 * <enum id="org.gtk.Test.myenum">
14974 * <value nick="first" value="1"/>
14975 * <value nick="second" value="2"/>
14978 * <flags id="org.gtk.Test.myflags">
14979 * <value nick="flag1" value="1"/>
14980 * <value nick="flag2" value="2"/>
14981 * <value nick="flag3" value="4"/>
14984 * <schema id="org.gtk.Test">
14986 * <key name="key-with-range" type="i">
14987 * <range min="1" max="100"/>
14988 * <default>10</default>
14991 * <key name="key-with-choices" type="s">
14993 * <choice value='Elisabeth'/>
14994 * <choice value='Annabeth'/>
14995 * <choice value='Joe'/>
14998 * <alias value='Anna' target='Annabeth'/>
14999 * <alias value='Beth' target='Elisabeth'/>
15001 * <default>'Joe'</default>
15004 * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
15005 * <default>'first'</default>
15008 * <key name='flags-key' flags='org.gtk.Test.myflags'>
15009 * <default>["flag1",flag2"]</default>
15013 * ]]></programlisting></example>
15016 * <title>Vendor overrides</title>
15018 * Default values are defined in the schemas that get installed by
15019 * an application. Sometimes, it is necessary for a vendor or distributor
15020 * to adjust these defaults. Since patching the XML source for the schema
15021 * is inconvenient and error-prone,
15022 * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
15023 * so-called 'vendor override' files. These are keyfiles in the same
15024 * directory as the XML schema sources which can override default values.
15025 * The schema id serves as the group name in the key file, and the values
15026 * are expected in serialized GVariant form, as in the following example:
15027 * <informalexample><programlisting>
15028 * [org.gtk.Example]
15031 * </programlisting></informalexample>
15034 * glib-compile-schemas expects schema files to have the extension
15035 * <filename>.gschema.override</filename>
15040 * <title>Binding</title>
15042 * A very convenient feature of GSettings lets you bind #GObject properties
15043 * directly to settings, using g_settings_bind(). Once a GObject property
15044 * has been bound to a setting, changes on either side are automatically
15045 * propagated to the other side. GSettings handles details like
15046 * mapping between GObject and GVariant types, and preventing infinite
15050 * This makes it very easy to hook up a preferences dialog to the
15051 * underlying settings. To make this even more convenient, GSettings
15052 * looks for a boolean property with the name "sensitivity" and
15053 * automatically binds it to the writability of the bound setting.
15054 * If this 'magic' gets in the way, it can be suppressed with the
15055 * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
15062 * SECTION:gsettingsbackend
15063 * @title: GSettingsBackend
15064 * @short_description: Interface for settings backend implementations
15065 * @include: gio/gsettingsbackend.h
15066 * @see_also: #GSettings, #GIOExtensionPoint
15068 * The #GSettingsBackend interface defines a generic interface for
15069 * non-strictly-typed data that is stored in a hierarchy. To implement
15070 * an alternative storage backend for #GSettings, you need to implement
15071 * the #GSettingsBackend interface and then make it implement the
15072 * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
15074 * The interface defines methods for reading and writing values, a
15075 * method for determining if writing of certain values will fail
15076 * (lockdown) and a change notification mechanism.
15078 * The semantics of the interface are very precisely defined and
15079 * implementations must carefully adhere to the expectations of
15080 * callers that are documented on each of the interface methods.
15082 * Some of the GSettingsBackend functions accept or return a #GTree.
15083 * These trees always have strings as keys and #GVariant as values.
15084 * g_settings_backend_create_tree() is a convenience function to create
15088 * The #GSettingsBackend API is exported to allow third-party
15089 * implementations, but does not carry the same stability guarantees
15090 * as the public GIO API. For this reason, you have to define the
15091 * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including
15092 * <filename>gio/gsettingsbackend.h</filename>
15098 * SECTION:gsettingsschema
15099 * @short_description: introspecting and controlling the loading of #GSettings schemas
15101 * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
15102 * mechanism for advanced control over the loading of schemas and a
15103 * mechanism for introspecting their content.
15105 * Plugin loading systems that wish to provide plugins a way to access
15106 * settings face the problem of how to make the schemas for these
15107 * settings visible to GSettings. Typically, a plugin will want to ship
15108 * the schema along with itself and it won't be installed into the
15109 * standard system directories for schemas.
15111 * #GSettingsSchemaSource provides a mechanism for dealing with this by
15112 * allowing the creation of a new 'schema source' from which schemas can
15113 * be acquired. This schema source can then become part of the metadata
15114 * associated with the plugin and queried whenever the plugin requires
15115 * access to some settings.
15117 * Consider the following example:
15123 * GSettingsSchemaSource *schema_source;
15128 * initialise_plugin (const gchar *dir)
15134 * plugin->schema_source =
15135 * g_settings_new_schema_source_from_directory (dir,
15136 * g_settings_schema_source_get_default (), FALSE, NULL);
15146 * plugin_get_settings (Plugin *plugin,
15147 * const gchar *schema_id)
15149 * GSettingsSchema *schema;
15151 * if (schema_id == NULL)
15152 * schema_id = plugin->identifier;
15154 * schema = g_settings_schema_source_lookup (plugin->schema_source,
15155 * schema_id, FALSE);
15157 * if (schema == NULL)
15159 * ... disable the plugin or abort, etc ...
15162 * return g_settings_new_full (schema, NULL, NULL);
15166 * The code above shows how hooks should be added to the code that
15167 * initialises (or enables) the plugin to create the schema source and
15168 * how an API can be added to the plugin system to provide a convenient
15169 * way for the plugin to access its settings, using the schemas that it
15172 * From the standpoint of the plugin, it would need to ensure that it
15173 * ships a gschemas.compiled file as part of itself, and then simply do
15178 * GSettings *settings;
15181 * settings = plugin_get_settings (self, NULL);
15182 * some_value = g_settings_get_int (settings, "some-value");
15187 * It's also possible that the plugin system expects the schema source
15188 * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
15189 * In that case, the plugin loading system must compile the schemas for
15190 * itself before attempting to create the settings source.
15197 * SECTION:gsimpleaction
15198 * @title: GSimpleAction
15199 * @short_description: A simple GAction implementation
15201 * A #GSimpleAction is the obvious simple implementation of the #GAction
15202 * interface. This is the easiest way to create an action for purposes of
15203 * adding it to a #GSimpleActionGroup.
15205 * See also #GtkAction.
15210 * SECTION:gsimpleactiongroup
15211 * @title: GSimpleActionGroup
15212 * @short_description: A simple GActionGroup implementation
15214 * #GSimpleActionGroup is a hash table filled with #GAction objects,
15215 * implementing the #GActionGroup and #GActionMap interfaces.
15220 * SECTION:gsimpleasyncresult
15221 * @short_description: Simple asynchronous results implementation
15222 * @include: gio/gio.h
15223 * @see_also: #GAsyncResult
15225 * Implements #GAsyncResult for simple cases. Most of the time, this
15226 * will be all an application needs, and will be used transparently.
15227 * Because of this, #GSimpleAsyncResult is used throughout GIO for
15228 * handling asynchronous functions.
15230 * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
15231 * reporting, operation cancellation and the final state of an operation,
15232 * completely transparent to the application. Results can be returned
15233 * as a pointer e.g. for functions that return data that is collected
15234 * asynchronously, a boolean value for checking the success or failure
15235 * of an operation, or a #gssize for operations which return the number
15236 * of bytes modified by the operation; all of the simple return cases
15239 * Most of the time, an application will not need to know of the details
15240 * of this API; it is handled transparently, and any necessary operations
15241 * are handled by #GAsyncResult's interface. However, if implementing a
15242 * new GIO module, for writing language bindings, or for complex
15243 * applications that need better control of how asynchronous operations
15244 * are completed, it is important to understand this functionality.
15246 * GSimpleAsyncResults are tagged with the calling function to ensure
15247 * that asynchronous functions and their finishing functions are used
15248 * together correctly.
15250 * To create a new #GSimpleAsyncResult, call g_simple_async_result_new().
15251 * If the result needs to be created for a #GError, use
15252 * g_simple_async_result_new_from_error() or
15253 * g_simple_async_result_new_take_error(). If a #GError is not available
15254 * (e.g. the asynchronous operation's doesn't take a #GError argument),
15255 * but the result still needs to be created for an error condition, use
15256 * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
15257 * if your application or binding requires passing a variable argument list
15258 * directly), and the error can then be propagated through the use of
15259 * g_simple_async_result_propagate_error().
15261 * An asynchronous operation can be made to ignore a cancellation event by
15262 * calling g_simple_async_result_set_handle_cancellation() with a
15263 * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
15264 * operations that are dangerous to cancel, such as close (which would
15265 * cause a leak if cancelled before being run).
15267 * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
15268 * or it can use #GThread<!-- -->s.
15269 * g_simple_async_result_complete() will finish an I/O task directly
15270 * from the point where it is called. g_simple_async_result_complete_in_idle()
15271 * will finish it from an idle handler in the <link
15272 * linkend="g-main-context-push-thread-default">thread-default main
15273 * context</link>. g_simple_async_result_run_in_thread() will run the
15274 * job in a separate thread and then deliver the result to the
15275 * thread-default main context.
15277 * To set the results of an asynchronous function,
15278 * g_simple_async_result_set_op_res_gpointer(),
15279 * g_simple_async_result_set_op_res_gboolean(), and
15280 * g_simple_async_result_set_op_res_gssize()
15281 * are provided, setting the operation's result to a gpointer, gboolean, or
15282 * gssize, respectively.
15284 * Likewise, to get the result of an asynchronous function,
15285 * g_simple_async_result_get_op_res_gpointer(),
15286 * g_simple_async_result_get_op_res_gboolean(), and
15287 * g_simple_async_result_get_op_res_gssize() are
15288 * provided, getting the operation's result as a gpointer, gboolean, and
15289 * gssize, respectively.
15291 * For the details of the requirements implementations must respect, see
15292 * #GAsyncResult. A typical implementation of an asynchronous operation
15293 * using GSimpleAsyncResult looks something like this:
15297 * baked_cb (Cake *cake,
15298 * gpointer user_data)
15300 * /* In this example, this callback is not given a reference to the cake, so
15301 * * the GSimpleAsyncResult has to take a reference to it.
15303 * GSimpleAsyncResult *result = user_data;
15305 * if (cake == NULL)
15306 * g_simple_async_result_set_error (result,
15308 * BAKER_ERROR_NO_FLOUR,
15309 * "Go to the supermarket");
15311 * g_simple_async_result_set_op_res_gpointer (result,
15312 * g_object_ref (cake),
15316 * /* In this example, we assume that baked_cb is called as a callback from
15317 * * the mainloop, so it's safe to complete the operation synchronously here.
15318 * * If, however, _baker_prepare_cake () might call its callback without
15319 * * first returning to the mainloop — inadvisable, but some APIs do so —
15320 * * we would need to use g_simple_async_result_complete_in_idle().
15322 * g_simple_async_result_complete (result);
15323 * g_object_unref (result);
15327 * baker_bake_cake_async (Baker *self,
15329 * GAsyncReadyCallback callback,
15330 * gpointer user_data)
15332 * GSimpleAsyncResult *simple;
15337 * g_simple_async_report_error_in_idle (G_OBJECT (self),
15341 * BAKER_ERROR_TOO_SMALL,
15342 * "%ucm radius cakes are silly",
15347 * simple = g_simple_async_result_new (G_OBJECT (self),
15350 * baker_bake_cake_async);
15351 * cake = _baker_get_cached_cake (self, radius);
15353 * if (cake != NULL)
15355 * g_simple_async_result_set_op_res_gpointer (simple,
15356 * g_object_ref (cake),
15358 * g_simple_async_result_complete_in_idle (simple);
15359 * g_object_unref (simple);
15360 * /* Drop the reference returned by _baker_get_cached_cake(); the
15361 * * GSimpleAsyncResult has taken its own reference.
15363 * g_object_unref (cake);
15367 * _baker_prepare_cake (self, radius, baked_cb, simple);
15371 * baker_bake_cake_finish (Baker *self,
15372 * GAsyncResult *result,
15375 * GSimpleAsyncResult *simple;
15378 * g_return_val_if_fail (g_simple_async_result_is_valid (result,
15380 * baker_bake_cake_async),
15383 * simple = (GSimpleAsyncResult *) result;
15385 * if (g_simple_async_result_propagate_error (simple, error))
15388 * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
15389 * return g_object_ref (cake);
15396 * SECTION:gsimplepermission
15397 * @title: GSimplePermission
15398 * @short_description: A GPermission that doesn't change value
15400 * #GSimplePermission is a trivial implementation of #GPermission that
15401 * represents a permission that is either always or never allowed. The
15402 * value is given at construction and doesn't change.
15404 * Calling request or release will result in errors.
15410 * @short_description: Low-level socket object
15411 * @include: gio/gio.h
15412 * @see_also: #GInitable
15414 * A #GSocket is a low-level networking primitive. It is a more or less
15415 * direct mapping of the BSD socket API in a portable GObject based API.
15416 * It supports both the UNIX socket implementations and winsock2 on Windows.
15418 * #GSocket is the platform independent base upon which the higher level
15419 * network primitives are based. Applications are not typically meant to
15420 * use it directly, but rather through classes like #GSocketClient,
15421 * #GSocketService and #GSocketConnection. However there may be cases where
15422 * direct use of #GSocket is useful.
15424 * #GSocket implements the #GInitable interface, so if it is manually constructed
15425 * by e.g. g_object_new() you must call g_initable_init() and check the
15426 * results before using the object. This is done automatically in
15427 * g_socket_new() and g_socket_new_from_fd(), so these functions can return
15430 * Sockets operate in two general modes, blocking or non-blocking. When
15431 * in blocking mode all operations block until the requested operation
15432 * is finished or there is an error. In non-blocking mode all calls that
15433 * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error.
15434 * To know when a call would successfully run you can call g_socket_condition_check(),
15435 * or g_socket_condition_wait(). You can also use g_socket_create_source() and
15436 * attach it to a #GMainContext to get callbacks when I/O is possible.
15437 * Note that all sockets are always set to non blocking mode in the system, and
15438 * blocking mode is emulated in GSocket.
15440 * When working in non-blocking mode applications should always be able to
15441 * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other
15442 * function said that I/O was possible. This can easily happen in case
15443 * of a race condition in the application, but it can also happen for other
15444 * reasons. For instance, on Windows a socket is always seen as writable
15445 * until a write returns %G_IO_ERROR_WOULD_BLOCK.
15447 * #GSocket<!-- -->s can be either connection oriented or datagram based.
15448 * For connection oriented types you must first establish a connection by
15449 * either connecting to an address or accepting a connection from another
15450 * address. For connectionless socket types the target/source address is
15451 * specified or received in each I/O operation.
15453 * All socket file descriptors are set to be close-on-exec.
15455 * Note that creating a #GSocket causes the signal %SIGPIPE to be
15456 * ignored for the remainder of the program. If you are writing a
15457 * command-line utility that uses #GSocket, you may need to take into
15458 * account the fact that your program will not automatically be killed
15459 * if it tries to write to %stdout after it has been closed.
15466 * SECTION:gsocketaddress
15467 * @short_description: Abstract base class representing endpoints for socket communication
15469 * #GSocketAddress is the equivalent of <type>struct sockaddr</type>
15470 * in the BSD sockets API. This is an abstract class; use
15471 * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress
15472 * for UNIX domain sockets.
15477 * SECTION:gsocketclient
15478 * @short_description: Helper for connecting to a network service
15479 * @include: gio/gio.h
15480 * @see_also: #GSocketConnection, #GSocketListener
15482 * #GSocketClient is a lightweight high-level utility class for connecting to
15483 * a network host using a connection oriented socket type.
15485 * You create a #GSocketClient object, set any options you want, and then
15486 * call a sync or async connect operation, which returns a #GSocketConnection
15487 * subclass on success.
15489 * The type of the #GSocketConnection object returned depends on the type of
15490 * the underlying socket that is in use. For instance, for a TCP/IP connection
15491 * it will be a #GTcpConnection.
15493 * As #GSocketClient is a lightweight object, you don't need to cache it. You
15494 * can just create a new one any time you need one.
15501 * SECTION:gsocketconnectable
15502 * @short_description: Interface for potential socket endpoints
15504 * Objects that describe one or more potential socket endpoints
15505 * implement #GSocketConnectable. Callers can then use
15506 * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
15507 * to try out each socket address in turn until one succeeds, as shown
15508 * in the sample code below.
15511 * MyConnectionType *
15512 * connect_to_host (const char *hostname,
15514 * GCancellable *cancellable,
15517 * MyConnection *conn = NULL;
15518 * GSocketConnectable *addr;
15519 * GSocketAddressEnumerator *enumerator;
15520 * GSocketAddress *sockaddr;
15521 * GError *conn_error = NULL;
15523 * addr = g_network_address_new ("www.gnome.org", 80);
15524 * enumerator = g_socket_connectable_enumerate (addr);
15525 * g_object_unref (addr);
15527 * /<!-- -->* Try each sockaddr until we succeed. Record the first
15528 * * connection error, but not any further ones (since they'll probably
15529 * * be basically the same as the first).
15531 * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
15533 * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
15534 * g_object_unref (sockaddr);
15536 * g_object_unref (enumerator);
15542 * /<!-- -->* We couldn't connect to the first address, but we succeeded
15543 * * in connecting to a later address.
15545 * g_error_free (conn_error);
15551 * /<!-- -->* Either the initial lookup failed, or else the caller
15555 * g_error_free (conn_error);
15560 * g_error_propagate (error, conn_error);
15569 * SECTION:gsocketconnection
15570 * @short_description: A socket connection
15571 * @include: gio/gio.h
15572 * @see_also: #GIOStream, #GSocketClient, #GSocketListener
15574 * #GSocketConnection is a #GIOStream for a connected socket. They
15575 * can be created either by #GSocketClient when connecting to a host,
15576 * or by #GSocketListener when accepting a new client.
15578 * The type of the #GSocketConnection object returned from these calls
15579 * depends on the type of the underlying socket that is in use. For
15580 * instance, for a TCP/IP connection it will be a #GTcpConnection.
15582 * Choosing what type of object to construct is done with the socket
15583 * connection factory, and it is possible for 3rd parties to register
15584 * custom socket connection types for specific combination of socket
15585 * family/type/protocol using g_socket_connection_factory_register_type().
15592 * SECTION:gsocketcontrolmessage
15593 * @title: GSocketControlMessage
15594 * @short_description: A GSocket control message
15595 * @see_also: #GSocket.
15597 * A #GSocketControlMessage is a special-purpose utility message that
15598 * can be sent to or received from a #GSocket. These types of
15599 * messages are often called "ancillary data".
15601 * The message can represent some sort of special instruction to or
15602 * information from the socket or can represent a special kind of
15603 * transfer to the peer (for example, sending a file description over
15606 * These messages are sent with g_socket_send_message() and received
15607 * with g_socket_receive_message().
15609 * To extend the set of control message that can be sent, subclass this
15610 * class and override the get_size, get_level, get_type and serialize
15613 * To extend the set of control messages that can be received, subclass
15614 * this class and implement the deserialize method. Also, make sure your
15615 * class is registered with the GType typesystem before calling
15616 * g_socket_receive_message() to read such a message.
15623 * SECTION:gsocketlistener
15624 * @title: GSocketListener
15625 * @short_description: Helper for accepting network client connections
15626 * @see_also: #GThreadedSocketService, #GSocketService.
15628 * A #GSocketListener is an object that keeps track of a set
15629 * of server sockets and helps you accept sockets from any of the
15630 * socket, either sync or async.
15632 * If you want to implement a network server, also look at #GSocketService
15633 * and #GThreadedSocketService which are subclass of #GSocketListener
15634 * that makes this even easier.
15641 * SECTION:gsocketservice
15642 * @title: GSocketService
15643 * @short_description: Make it easy to implement a network service
15644 * @see_also: #GThreadedSocketService, #GSocketListener.
15646 * A #GSocketService is an object that represents a service that
15647 * is provided to the network or over local sockets. When a new
15648 * connection is made to the service the #GSocketService::incoming
15649 * signal is emitted.
15651 * A #GSocketService is a subclass of #GSocketListener and you need
15652 * to add the addresses you want to accept connections on with the
15653 * #GSocketListener APIs.
15655 * There are two options for implementing a network service based on
15656 * #GSocketService. The first is to create the service using
15657 * g_socket_service_new() and to connect to the #GSocketService::incoming
15658 * signal. The second is to subclass #GSocketService and override the
15659 * default signal handler implementation.
15661 * In either case, the handler must immediately return, or else it
15662 * will block additional incoming connections from being serviced.
15663 * If you are interested in writing connection handlers that contain
15664 * blocking code then see #GThreadedSocketService.
15666 * The socket service runs on the main loop of the <link
15667 * linkend="g-main-context-push-thread-default-context">thread-default
15668 * context</link> of the thread it is created in, and is not
15669 * threadsafe in general. However, the calls to start and stop the
15670 * service are thread-safe so these can be used from threads that
15671 * handle incoming clients.
15678 * SECTION:gsrvtarget
15679 * @short_description: DNS SRV record target
15680 * @include: gio/gio.h
15682 * SRV (service) records are used by some network protocols to provide
15683 * service-specific aliasing and load-balancing. For example, XMPP
15684 * (Jabber) uses SRV records to locate the XMPP server for a domain;
15685 * rather than connecting directly to "example.com" or assuming a
15686 * specific server hostname like "xmpp.example.com", an XMPP client
15687 * would look up the "xmpp-client" SRV record for "example.com", and
15688 * then connect to whatever host was pointed to by that record.
15690 * You can use g_resolver_lookup_service() or
15691 * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s
15692 * for a given service. However, if you are simply planning to connect
15693 * to the remote service, you can use #GNetworkService's
15694 * #GSocketConnectable interface and not need to worry about
15695 * #GSrvTarget at all.
15700 * SECTION:gtcpconnection
15701 * @title: GTcpConnection
15702 * @short_description: A TCP GSocketConnection
15703 * @see_also: #GSocketConnection.
15705 * This is the subclass of #GSocketConnection that is created
15706 * for TCP/IP sockets.
15713 * SECTION:gtcpwrapperconnection
15714 * @title: GTcpWrapperConnection
15715 * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
15716 * @see_also: #GSocketConnection.
15718 * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is
15719 * based on a #GSocket, but which is not actually a
15720 * #GSocketConnection. This is used by #GSocketClient so that it can
15721 * always return a #GSocketConnection, even when the connection it has
15722 * actually created is not directly a #GSocketConnection.
15729 * SECTION:gthemedicon
15730 * @short_description: Icon theming support
15731 * @include: gio/gio.h
15732 * @see_also: #GIcon, #GLoadableIcon
15734 * #GThemedIcon is an implementation of #GIcon that supports icon themes.
15735 * #GThemedIcon contains a list of all of the icons present in an icon
15736 * theme, so that icons can be looked up quickly. #GThemedIcon does
15737 * not provide actual pixmaps for icons, just the icon names.
15738 * Ideally something like gtk_icon_theme_choose_icon() should be used to
15739 * resolve the list of names so that fallback icons work nicely with
15740 * themes that inherit other themes.
15745 * SECTION:gthreadedsocketservice
15746 * @title: GThreadedSocketService
15747 * @short_description: A threaded GSocketService
15748 * @see_also: #GSocketService.
15750 * A #GThreadedSocketService is a simple subclass of #GSocketService
15751 * that handles incoming connections by creating a worker thread and
15752 * dispatching the connection to it by emitting the
15753 * #GThreadedSocketService::run signal in the new thread.
15755 * The signal handler may perform blocking IO and need not return
15756 * until the connection is closed.
15758 * The service is implemented using a thread pool, so there is a
15759 * limited amount of threads available to serve incoming requests.
15760 * The service automatically stops the #GSocketService from accepting
15761 * new connections when all threads are busy.
15763 * As with #GSocketService, you may connect to #GThreadedSocketService::run,
15764 * or subclass and override the default handler.
15770 * @title: TLS Overview
15771 * @short_description: TLS (aka SSL) support for GSocketConnection
15772 * @include: gio/gio.h
15774 * #GTlsConnection and related classes provide TLS (Transport Layer
15775 * Security, previously known as SSL, Secure Sockets Layer) support for
15776 * gio-based network streams.
15778 * In the simplest case, for a client connection, you can just set the
15779 * #GSocketClient:tls flag on a #GSocketClient, and then any
15780 * connections created by that client will have TLS negotiated
15781 * automatically, using appropriate default settings, and rejecting
15782 * any invalid or self-signed certificates (unless you change that
15783 * default by setting the #GSocketClient:tls-validation-flags
15784 * property). The returned object will be a #GTcpWrapperConnection,
15785 * which wraps the underlying #GTlsClientConnection.
15787 * For greater control, you can create your own #GTlsClientConnection,
15788 * wrapping a #GSocketConnection (or an arbitrary #GIOStream with
15789 * pollable input and output streams) and then connect to its signals,
15790 * such as #GTlsConnection::accept-certificate, before starting the
15793 * Server-side TLS is similar, using #GTlsServerConnection. At the
15794 * moment, there is no support for automatically wrapping server-side
15795 * connections in the way #GSocketClient does for client-side
15801 * SECTION:gtlsbackend
15802 * @title: GTlsBackend
15803 * @short_description: TLS backend implementation
15804 * @include: gio/gio.h
15811 * SECTION:gtlscertificate
15812 * @title: GTlsCertificate
15813 * @short_description: TLS certificate
15814 * @see_also: #GTlsConnection
15816 * A certificate used for TLS authentication and encryption.
15817 * This can represent either a public key only (eg, the certificate
15818 * received by a client from a server), or the combination of
15819 * a public key and a private key (which is needed when acting as a
15820 * #GTlsServerConnection).
15827 * SECTION:gtlsclientconnection
15828 * @short_description: TLS client-side connection
15829 * @include: gio/gio.h
15831 * #GTlsClientConnection is the client-side subclass of
15832 * #GTlsConnection, representing a client-side TLS connection.
15837 * SECTION:gtlsconnection
15838 * @short_description: TLS connection type
15839 * @include: gio/gio.h
15841 * #GTlsConnection is the base TLS connection class type, which wraps
15842 * a #GIOStream and provides TLS encryption on top of it. Its
15843 * subclasses, #GTlsClientConnection and #GTlsServerConnection,
15844 * implement client-side and server-side TLS, respectively.
15851 * SECTION:gtlsdatabase
15852 * @short_description: TLS database type
15853 * @include: gio/gio.h
15855 * #GTlsDatabase is used to lookup certificates and other information
15856 * from a certificate or key store. It is an abstract base class which
15857 * TLS library specific subtypes override.
15859 * Most common client applications will not directly interact with
15860 * #GTlsDatabase. It is used internally by #GTlsConnection.
15867 * SECTION:gtlsfiledatabase
15868 * @short_description: TLS file based database type
15869 * @include: gio/gio.h
15871 * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load
15872 * their certificate information from a file. It is in interface which
15873 * TLS library specific subtypes implement.
15880 * SECTION:gtlsinteraction
15881 * @short_description: Interaction with the user during TLS operations.
15882 * @include: gio/gio.h
15884 * #GTlsInteraction provides a mechanism for the TLS connection and database
15885 * code to interact with the user. It can be used to ask the user for passwords.
15887 * To use a #GTlsInteraction with a TLS connection use
15888 * g_tls_connection_set_interaction().
15890 * Callers should instantiate a derived class that implements the various
15891 * interaction methods to show the required dialogs.
15893 * Callers should use the 'invoke' functions like
15894 * g_tls_interaction_invoke_ask_password() to run interaction methods. These
15895 * functions make sure that the interaction is invoked in the main loop
15896 * and not in the current thread, if the current thread is not running the
15899 * Derived classes can choose to implement whichever interactions methods they'd
15900 * like to support by overriding those virtual methods in their class
15901 * initialization function. Any interactions not implemented will return
15902 * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method,
15903 * it must also implement the corresponding finish method.
15908 * SECTION:gtlspassword
15909 * @title: GTlsPassword
15910 * @short_description: TLS Passwords for prompting
15911 * @include: gio/gio.h
15913 * Holds a password used in TLS.
15918 * SECTION:gtlsserverconnection
15919 * @short_description: TLS server-side connection
15920 * @include: gio/gio.h
15922 * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
15923 * representing a server-side TLS connection.
15930 * SECTION:gunixconnection
15931 * @title: GUnixConnection
15932 * @short_description: A UNIX domain GSocketConnection
15933 * @include: gio/gunixconnection.h
15934 * @see_also: #GSocketConnection.
15936 * This is the subclass of #GSocketConnection that is created
15937 * for UNIX domain sockets.
15939 * It contains functions to do some of the UNIX socket specific
15940 * functionality like passing file descriptors.
15942 * Note that <filename><gio/gunixconnection.h></filename> belongs to
15943 * the UNIX-specific GIO interfaces, thus you have to use the
15944 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
15951 * SECTION:gunixcredentialsmessage
15952 * @title: GUnixCredentialsMessage
15953 * @short_description: A GSocketControlMessage containing credentials
15954 * @include: gio/gunixcredentialsmessage.h
15955 * @see_also: #GUnixConnection, #GSocketControlMessage
15957 * This #GSocketControlMessage contains a #GCredentials instance. It
15958 * may be sent using g_socket_send_message() and received using
15959 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
15960 * %G_SOCKET_FAMILY_UNIX family).
15962 * For an easier way to send and receive credentials over
15963 * stream-oriented UNIX sockets, see
15964 * g_unix_connection_send_credentials() and
15965 * g_unix_connection_receive_credentials(). To receive credentials of
15966 * a foreign process connected to a socket, use
15967 * g_socket_get_credentials().
15972 * SECTION:gunixfdlist
15973 * @title: GUnixFDList
15974 * @short_description: An object containing a set of UNIX file descriptors
15975 * @include: gio/gunixfdlist.h
15976 * @see_also: #GUnixFDMessage
15978 * A #GUnixFDList contains a list of file descriptors. It owns the file
15979 * descriptors that it contains, closing them when finalized.
15981 * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
15982 * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
15983 * and received using g_socket_receive_message().
15985 * Note that <filename><gio/gunixfdlist.h></filename> belongs to
15986 * the UNIX-specific GIO interfaces, thus you have to use the
15987 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
15992 * SECTION:gunixfdmessage
15993 * @title: GUnixFDMessage
15994 * @short_description: A GSocketControlMessage containing a GUnixFDList
15995 * @include: gio/gunixfdmessage.h
15996 * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage
15998 * This #GSocketControlMessage contains a #GUnixFDList.
15999 * It may be sent using g_socket_send_message() and received using
16000 * g_socket_receive_message() over UNIX sockets (ie: sockets in the
16001 * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
16002 * between processes by the kernel.
16004 * For an easier way to send and receive file descriptors over
16005 * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
16006 * g_unix_connection_receive_fd().
16008 * Note that <filename><gio/gunixfdmessage.h></filename> belongs to
16009 * the UNIX-specific GIO interfaces, thus you have to use the
16010 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
16015 * SECTION:gunixinputstream
16016 * @short_description: Streaming input operations for UNIX file descriptors
16017 * @include: gio/gunixinputstream.h
16018 * @see_also: #GInputStream
16020 * #GUnixInputStream implements #GInputStream for reading from a UNIX
16021 * file descriptor, including asynchronous operations. (If the file
16022 * descriptor refers to a socket or pipe, this will use poll() to do
16023 * asynchronous I/O. If it refers to a regular file, it will fall back
16024 * to doing asynchronous I/O in another thread.)
16026 * Note that <filename><gio/gunixinputstream.h></filename> belongs
16027 * to the UNIX-specific GIO interfaces, thus you have to use the
16028 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
16033 * SECTION:gunixmounts
16034 * @include: gio/gunixmounts.h
16035 * @short_description: UNIX mounts
16037 * Routines for managing mounted UNIX mount points and paths.
16039 * Note that <filename><gio/gunixmounts.h></filename> belongs to the
16040 * UNIX-specific GIO interfaces, thus you have to use the
16041 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
16046 * SECTION:gunixoutputstream
16047 * @short_description: Streaming output operations for UNIX file descriptors
16048 * @include: gio/gunixoutputstream.h
16049 * @see_also: #GOutputStream
16051 * #GUnixOutputStream implements #GOutputStream for writing to a UNIX
16052 * file descriptor, including asynchronous operations. (If the file
16053 * descriptor refers to a socket or pipe, this will use poll() to do
16054 * asynchronous I/O. If it refers to a regular file, it will fall back
16055 * to doing asynchronous I/O in another thread.)
16057 * Note that <filename><gio/gunixoutputstream.h></filename> belongs
16058 * to the UNIX-specific GIO interfaces, thus you have to use the
16059 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
16064 * SECTION:gunixsocketaddress
16065 * @short_description: UNIX GSocketAddress
16066 * @include: gio/gunixsocketaddress.h
16068 * Support for UNIX-domain (also known as local) sockets.
16070 * UNIX domain sockets are generally visible in the filesystem.
16071 * However, some systems support abstract socket names which are not
16072 * visible in the filesystem and not affected by the filesystem
16073 * permissions, visibility, etc. Currently this is only supported
16074 * under Linux. If you attempt to use abstract sockets on other
16075 * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
16076 * errors. You can use g_unix_socket_address_abstract_names_supported()
16077 * to see if abstract names are supported.
16079 * Note that <filename><gio/gunixsocketaddress.h></filename> belongs to
16080 * the UNIX-specific GIO interfaces, thus you have to use the
16081 * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
16087 * @short_description: Virtual File System
16088 * @include: gio/gio.h
16090 * Entry point for using GIO functionality.
16096 * @short_description: Volume management
16097 * @include: gio/gio.h
16099 * The #GVolume interface represents user-visible objects that can be
16100 * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
16101 * equivalent of #GnomeVFSDrive.
16103 * Mounting a #GVolume instance is an asynchronous operation. For more
16104 * information about asynchronous operations, see #GAsyncResult and
16105 * #GSimpleAsyncResult. To mount a #GVolume, first call
16106 * g_volume_mount() with (at least) the #GVolume instance, optionally
16107 * a #GMountOperation object and a #GAsyncReadyCallback.
16109 * Typically, one will only want to pass %NULL for the
16110 * #GMountOperation if automounting all volumes when a desktop session
16111 * starts since it's not desirable to put up a lot of dialogs asking
16114 * The callback will be fired when the operation has resolved (either
16115 * with success or failure), and a #GAsyncReady structure will be
16116 * passed to the callback. That callback should then call
16117 * g_volume_mount_finish() with the #GVolume instance and the
16118 * #GAsyncReady data to see if the operation was completed
16119 * successfully. If an @error is present when g_volume_mount_finish()
16120 * is called, then it will be filled with any error information.
16122 * <para id="volume-identifier">
16123 * It is sometimes necessary to directly access the underlying
16124 * operating system object behind a volume (e.g. for passing a volume
16125 * to an application via the commandline). For this purpose, GIO
16126 * allows to obtain an 'identifier' for the volume. There can be
16127 * different kinds of identifiers, such as Hal UDIs, filesystem labels,
16128 * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
16129 * uuids. GIO uses predefind strings as names for the different kinds
16130 * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
16131 * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
16132 * to obtain an identifier for a volume.
16135 * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
16136 * when the gvfs hal volume monitor is in use. Other volume monitors
16137 * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
16138 * identifier, which can be used to obtain a hal device by means of
16139 * libhal_manager_find_device_string_match().
16144 * SECTION:gvolumemonitor
16145 * @short_description: Volume Monitor
16146 * @include: gio/gio.h
16147 * @see_also: #GFileMonitor
16149 * #GVolumeMonitor is for listing the user interesting devices and volumes
16150 * on the computer. In other words, what a file selector or file manager
16151 * would show in a sidebar.
16153 * #GVolumeMonitor is not <link
16154 * linkend="g-main-context-push-thread-default">thread-default-context
16155 * aware</link>, and so should not be used other than from the main
16156 * thread, with no thread-default-context active.
16161 * SECTION:gwin32inputstream
16162 * @short_description: Streaming input operations for Windows file handles
16163 * @include: gio/gwin32inputstream.h
16164 * @see_also: #GInputStream
16166 * #GWin32InputStream implements #GInputStream for reading from a
16167 * Windows file handle.
16169 * Note that <filename><gio/gwin32inputstream.h></filename> belongs
16170 * to the Windows-specific GIO interfaces, thus you have to use the
16171 * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
16176 * SECTION:gwin32outputstream
16177 * @short_description: Streaming output operations for Windows file handles
16178 * @include: gio/gwin32outputstream.h
16179 * @see_also: #GOutputStream
16181 * #GWin32OutputStream implements #GOutputStream for writing to a
16182 * Windows file handle.
16184 * Note that <filename><gio/gwin32outputstream.h></filename> belongs
16185 * to the Windows-specific GIO interfaces, thus you have to use the
16186 * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
16191 * SECTION:gzcompressor
16192 * @short_description: Zlib compressor
16193 * @include: gio/gio.h
16195 * #GZlibCompressor is an implementation of #GConverter that
16196 * compresses data using zlib.
16201 * SECTION:gzdecompressor
16202 * @short_description: Zlib decompressor
16203 * @include: gio/gio.h
16205 * #GZlibDecompressor is an implementation of #GConverter that
16206 * decompresses data compressed with zlib.
16211 * The string info map is an efficient data structure designed to be:
16213 * 1) Implement <choices> with a list of valid strings
16215 * 2) Implement <alias> by mapping one string to another
16217 * 3) Implement enumerated types by mapping strings to integer values
16220 * The map is made out of an array of uint32s. Each entry in the array
16221 * is an integer value, followed by a specially formatted string value:
16223 * The string starts with the byte 0xff or 0xfe, followed by the
16224 * content of the string, followed by a nul byte, followed by
16225 * additional nul bytes for padding, followed by a 0xff byte.
16227 * Padding is added so that the entire formatted string takes up a
16228 * multiple of 4 bytes, and not less than 8 bytes. The requirement
16229 * for a string to take up 8 bytes is so that the scanner doesn't lose
16230 * synch and mistake a string for an integer value.
16232 * The first byte of the formatted string depends on if the integer is
16233 * an enum value (0xff) or an alias (0xfe). If it is an alias then the
16234 * number refers to the word offset within the info map at which the
16235 * integer corresponding to the "target" value is stored.
16237 * For example, consider the case of the string info map representing an
16238 * enumerated type of 'foo' (value 1) and 'bar' (value 2) and 'baz'
16239 * (alias for 'bar'). Note that string info maps are always little
16242 * x01 x00 x00 x00 xff 'f' 'o' 'o' x00 x00 x00 xff x02 x00 x00 x00
16243 * xff 'b' 'a' 'r' x00 x00 x00 xff x03 x00 x00 x00 xfe 'b' 'a' 'z'
16247 * The operations that someone may want to perform with the map:
16249 * - lookup if a string is valid (and not an alias)
16250 * - lookup the integer value for a enum 'nick'
16251 * - lookup the integer value for the target of an alias
16252 * - lookup an alias and convert it to its target string
16253 * - lookup the enum nick for a given value
16255 * In order to lookup if a string is valid, it is padded on either side
16256 * (as described) and scanned for in the array. For example, you might
16259 * xff 'f' 'o' 'o' x00 x00 x00 xff
16261 * In order to lookup the integer value for a nick, the string is padded
16262 * on either side and scanned for in the array, as above. Instead of
16263 * merely succeeding, we look at the integer value to the left of the
16264 * match. This is the enum value.
16266 * In order to lookup an alias and convert it to its target enum value,
16267 * the string is padded on either side (as described, with 0xfe) and
16268 * scanned for. For example, you might look for "baz":
16270 * xfe 'b' 'a' 'z' x00 x00 x00 xff
16272 * The integer immediately preceding the match then contains the offset
16273 * of the integer value of the target. In our example, that's '3'.
16274 * This index is dereferenced to find the enum value of '2'.
16276 * To convert the alias to its target string, 5 bytes just need to be
16277 * added past the start of the integer value to find the start of the
16280 * To lookup the enum nick for a given value, the value is searched for
16281 * in the array. To ensure that the value isn't matching the inside of a
16282 * string, we must check that it is either the first item in the array or
16283 * immediately preceded by the byte 0xff. It must also be immediately
16284 * followed by the byte 0xff.
16286 * Because strings always take up a minimum of 2 words, because 0xff or
16287 * 0xfe never appear inside of a utf-8 string and because no two integer
16288 * values ever appear in sequence, the only way we can have the
16291 * xff __ __ __ __ xff (or 0xfe)
16293 * is in the event of an integer nested between two strings.
16295 * For implementation simplicity/efficiency, strings may not be more
16296 * than 65 characters in length (ie: 17 32bit words after padding).
16298 * In the event that we are doing <choices> (ie: not an enum type) then
16299 * the value of each choice is set to zero and ignored.
16304 * _g_io_module_get_default:
16305 * @extension_point: the name of an extension point
16306 * @envvar: (allow-none): the name of an environment variable to override the default implementation.
16307 * @verify_func: (allow-none): a function to call to verify that a given implementation is usable in the current environment.
16309 * Retrieves the default object implementing @extension_point.
16311 * If @envvar is not %NULL, and the environment variable with that
16312 * name is set, then the implementation it specifies will be tried
16313 * first. After that, or if @envvar is not set, all other
16314 * implementations will be tried in order of decreasing priority.
16316 * If an extension point implementation implements #GInitable, then
16317 * that implementation will only be used if it initializes
16318 * successfully. Otherwise, if @verify_func is not %NULL, then it will
16319 * be called on each candidate implementation after construction, to
16320 * check if it is actually usable or not.
16322 * The result is cached after it is generated the first time, and
16323 * the function is thread-safe.
16325 * @extension_point, or %NULL if there are no usable
16328 * Returns: (transfer none): an object implementing
16333 * g_action_activate:
16334 * @action: a #GAction
16335 * @parameter: (allow-none): the parameter to the activation
16337 * Activates the action.
16339 * @parameter must be the correct type of parameter for the action (ie:
16340 * the parameter type given at construction time). If the parameter
16341 * type was %NULL then @parameter must also be %NULL.
16348 * g_action_change_state:
16349 * @action: a #GAction
16350 * @value: the new state
16352 * Request for the state of @action to be changed to @value.
16354 * The action must be stateful and @value must be of the correct type.
16355 * See g_action_get_state_type().
16357 * This call merely requests a change. The action may refuse to change
16358 * its state or may change its state to something other than @value.
16359 * See g_action_get_state_hint().
16361 * If the @value GVariant is floating, it is consumed.
16368 * g_action_get_enabled:
16369 * @action: a #GAction
16371 * Checks if @action is currently enabled.
16373 * An action must be enabled in order to be activated or in order to
16374 * have its state changed from outside callers.
16376 * Returns: whether the action is enabled
16382 * g_action_get_name:
16383 * @action: a #GAction
16385 * Queries the name of @action.
16387 * Returns: the name of the action
16393 * g_action_get_parameter_type:
16394 * @action: a #GAction
16396 * Queries the type of the parameter that must be given when activating
16399 * When activating the action using g_action_activate(), the #GVariant
16400 * given to that function must be of the type returned by this function.
16402 * In the case that this function returns %NULL, you must not give any
16403 * #GVariant, but %NULL instead.
16405 * Returns: (allow-none): the parameter type
16411 * g_action_get_state:
16412 * @action: a #GAction
16414 * Queries the current state of @action.
16416 * If the action is not stateful then %NULL will be returned. If the
16417 * action is stateful then the type of the return value is the type
16418 * given by g_action_get_state_type().
16420 * The return value (if non-%NULL) should be freed with
16421 * g_variant_unref() when it is no longer required.
16423 * Returns: (transfer full): the current state of the action
16429 * g_action_get_state_hint:
16430 * @action: a #GAction
16432 * Requests a hint about the valid range of values for the state of
16435 * If %NULL is returned it either means that the action is not stateful
16436 * or that there is no hint about the valid range of values for the
16437 * state of the action.
16439 * If a #GVariant array is returned then each item in the array is a
16440 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
16441 * returned then the tuple specifies the inclusive lower and upper bound
16442 * of valid values for the state.
16444 * In any case, the information is merely a hint. It may be possible to
16445 * have a state value outside of the hinted range and setting a value
16446 * within the range may fail.
16448 * The return value (if non-%NULL) should be freed with
16449 * g_variant_unref() when it is no longer required.
16451 * Returns: (transfer full): the state range hint
16457 * g_action_get_state_type:
16458 * @action: a #GAction
16460 * Queries the type of the state of @action.
16462 * If the action is stateful (e.g. created with
16463 * g_simple_action_new_stateful()) then this function returns the
16464 * #GVariantType of the state. This is the type of the initial value
16465 * given as the state. All calls to g_action_change_state() must give a
16466 * #GVariant of this type and g_action_get_state() will return a
16467 * #GVariant of the same type.
16469 * If the action is not stateful (e.g. created with g_simple_action_new())
16470 * then this function will return %NULL. In that case, g_action_get_state()
16471 * will return %NULL and you must not call g_action_change_state().
16473 * Returns: (allow-none): the state type, if the action is stateful
16479 * g_action_group_action_added:
16480 * @action_group: a #GActionGroup
16481 * @action_name: the name of an action in the group
16483 * Emits the #GActionGroup::action-added signal on @action_group.
16485 * This function should only be called by #GActionGroup implementations.
16492 * g_action_group_action_enabled_changed:
16493 * @action_group: a #GActionGroup
16494 * @action_name: the name of an action in the group
16495 * @enabled: whether or not the action is now enabled
16497 * Emits the #GActionGroup::action-enabled-changed signal on @action_group.
16499 * This function should only be called by #GActionGroup implementations.
16506 * g_action_group_action_removed:
16507 * @action_group: a #GActionGroup
16508 * @action_name: the name of an action in the group
16510 * Emits the #GActionGroup::action-removed signal on @action_group.
16512 * This function should only be called by #GActionGroup implementations.
16519 * g_action_group_action_state_changed:
16520 * @action_group: a #GActionGroup
16521 * @action_name: the name of an action in the group
16522 * @state: the new state of the named action
16524 * Emits the #GActionGroup::action-state-changed signal on @action_group.
16526 * This function should only be called by #GActionGroup implementations.
16533 * g_action_group_activate_action:
16534 * @action_group: a #GActionGroup
16535 * @action_name: the name of the action to activate
16536 * @parameter: (allow-none): parameters to the activation
16538 * Activate the named action within @action_group.
16540 * If the action is expecting a parameter, then the correct type of
16541 * parameter must be given as @parameter. If the action is expecting no
16542 * parameters then @parameter must be %NULL. See
16543 * g_action_group_get_action_parameter_type().
16550 * g_action_group_change_action_state:
16551 * @action_group: a #GActionGroup
16552 * @action_name: the name of the action to request the change on
16553 * @value: the new state
16555 * Request for the state of the named action within @action_group to be
16556 * changed to @value.
16558 * The action must be stateful and @value must be of the correct type.
16559 * See g_action_group_get_action_state_type().
16561 * This call merely requests a change. The action may refuse to change
16562 * its state or may change its state to something other than @value.
16563 * See g_action_group_get_action_state_hint().
16565 * If the @value GVariant is floating, it is consumed.
16572 * g_action_group_get_action_enabled:
16573 * @action_group: a #GActionGroup
16574 * @action_name: the name of the action to query
16576 * Checks if the named action within @action_group is currently enabled.
16578 * An action must be enabled in order to be activated or in order to
16579 * have its state changed from outside callers.
16581 * Returns: whether or not the action is currently enabled
16587 * g_action_group_get_action_parameter_type:
16588 * @action_group: a #GActionGroup
16589 * @action_name: the name of the action to query
16591 * Queries the type of the parameter that must be given when activating
16592 * the named action within @action_group.
16594 * When activating the action using g_action_group_activate_action(),
16595 * the #GVariant given to that function must be of the type returned
16596 * by this function.
16598 * In the case that this function returns %NULL, you must not give any
16599 * #GVariant, but %NULL instead.
16601 * The parameter type of a particular action will never change but it is
16602 * possible for an action to be removed and for a new action to be added
16603 * with the same name but a different parameter type.
16605 * Returns: the parameter type
16611 * g_action_group_get_action_state:
16612 * @action_group: a #GActionGroup
16613 * @action_name: the name of the action to query
16615 * Queries the current state of the named action within @action_group.
16617 * If the action is not stateful then %NULL will be returned. If the
16618 * action is stateful then the type of the return value is the type
16619 * given by g_action_group_get_action_state_type().
16621 * The return value (if non-%NULL) should be freed with
16622 * g_variant_unref() when it is no longer required.
16624 * Returns: (allow-none): the current state of the action
16630 * g_action_group_get_action_state_hint:
16631 * @action_group: a #GActionGroup
16632 * @action_name: the name of the action to query
16634 * Requests a hint about the valid range of values for the state of the
16635 * named action within @action_group.
16637 * If %NULL is returned it either means that the action is not stateful
16638 * or that there is no hint about the valid range of values for the
16639 * state of the action.
16641 * If a #GVariant array is returned then each item in the array is a
16642 * possible value for the state. If a #GVariant pair (ie: two-tuple) is
16643 * returned then the tuple specifies the inclusive lower and upper bound
16644 * of valid values for the state.
16646 * In any case, the information is merely a hint. It may be possible to
16647 * have a state value outside of the hinted range and setting a value
16648 * within the range may fail.
16650 * The return value (if non-%NULL) should be freed with
16651 * g_variant_unref() when it is no longer required.
16653 * Returns: (transfer full): the state range hint
16659 * g_action_group_get_action_state_type:
16660 * @action_group: a #GActionGroup
16661 * @action_name: the name of the action to query
16663 * Queries the type of the state of the named action within
16666 * If the action is stateful then this function returns the
16667 * #GVariantType of the state. All calls to
16668 * g_action_group_change_action_state() must give a #GVariant of this
16669 * type and g_action_group_get_action_state() will return a #GVariant
16670 * of the same type.
16672 * If the action is not stateful then this function will return %NULL.
16673 * In that case, g_action_group_get_action_state() will return %NULL
16674 * and you must not call g_action_group_change_action_state().
16676 * The state type of a particular action will never change but it is
16677 * possible for an action to be removed and for a new action to be added
16678 * with the same name but a different state type.
16680 * Returns: (transfer full): the state type, if the action is stateful
16686 * g_action_group_has_action:
16687 * @action_group: a #GActionGroup
16688 * @action_name: the name of the action to check for
16690 * Checks if the named action exists within @action_group.
16692 * Returns: whether the named action exists
16698 * g_action_group_list_actions:
16699 * @action_group: a #GActionGroup
16701 * Lists the actions contained within @action_group.
16703 * The caller is responsible for freeing the list with g_strfreev() when
16704 * it is no longer required.
16706 * actions in the groupb
16708 * Returns: (transfer full): a %NULL-terminated array of the names of the
16714 * g_action_group_query_action:
16715 * @action_group: a #GActionGroup
16716 * @action_name: the name of an action in the group
16717 * @enabled: (out): if the action is presently enabled
16718 * @parameter_type: (out): the parameter type, or %NULL if none needed
16719 * @state_type: (out): the state type, or %NULL if stateless
16720 * @state_hint: (out): the state hint, or %NULL if none
16721 * @state: (out): the current state, or %NULL if stateless
16723 * Queries all aspects of the named action within an @action_group.
16725 * This function acquires the information available from
16726 * g_action_group_has_action(), g_action_group_get_action_enabled(),
16727 * g_action_group_get_action_parameter_type(),
16728 * g_action_group_get_action_state_type(),
16729 * g_action_group_get_action_state_hint() and
16730 * g_action_group_get_action_state() with a single function call.
16732 * This provides two main benefits.
16734 * The first is the improvement in efficiency that comes with not having
16735 * to perform repeated lookups of the action in order to discover
16736 * different things about it. The second is that implementing
16737 * #GActionGroup can now be done by only overriding this one virtual
16740 * The interface provides a default implementation of this function that
16741 * calls the individual functions, as required, to fetch the
16742 * information. The interface also provides default implementations of
16743 * those functions that call this function. All implementations,
16744 * therefore, must override either this function or all of the others.
16746 * If the action exists, %TRUE is returned and any of the requested
16747 * fields (as indicated by having a non-%NULL reference passed in) are
16748 * filled. If the action doesn't exist, %FALSE is returned and the
16749 * fields may or may not have been modified.
16751 * Returns: %TRUE if the action exists, else %FALSE
16757 * g_action_map_add_action:
16758 * @action_map: a #GActionMap
16759 * @action: a #GAction
16761 * Adds an action to the @action_map.
16763 * If the action map already contains an action with the same name
16764 * as @action then the old action is dropped from the action map.
16766 * The action map takes its own reference on @action.
16773 * g_action_map_add_action_entries:
16774 * @action_map: a #GActionMap
16775 * @entries: a pointer to the first item in an array of #GActionEntry structs
16776 * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
16777 * @user_data: the user data for signal connections
16779 * A convenience function for creating multiple #GSimpleAction instances
16780 * and adding them to a #GActionMap.
16782 * Each action is constructed as per one #GActionEntry.
16785 * <title>Using g_action_map_add_action_entries()</title>
16788 * activate_quit (GSimpleAction *simple,
16789 * GVariant *parameter,
16790 * gpointer user_data)
16796 * activate_print_string (GSimpleAction *simple,
16797 * GVariant *parameter,
16798 * gpointer user_data)
16800 * g_print ("%s\n", g_variant_get_string (parameter, NULL));
16803 * static GActionGroup *
16804 * create_action_group (void)
16806 * const GActionEntry entries[] = {
16807 * { "quit", activate_quit },
16808 * { "print-string", activate_print_string, "s" }
16810 * GSimpleActionGroup *group;
16812 * group = g_simple_action_group_new ();
16813 * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
16815 * return G_ACTION_GROUP (group);
16817 * </programlisting>
16825 * g_action_map_lookup_action:
16826 * @action_map: a #GActionMap
16827 * @action_name: the name of an action
16829 * Looks up the action with the name @action_name in @action_map.
16831 * If no such action exists, returns %NULL.
16833 * Returns: (transfer none): a #GAction, or %NULL
16839 * g_action_map_remove_action:
16840 * @action_map: a #GActionMap
16841 * @action_name: the name of the action
16843 * Removes the named action from the action map.
16845 * If no action of this name is in the map then nothing happens.
16853 * @size: number of bytes to allocate.
16855 * Allocates @size bytes on the stack; these bytes will be freed when the current
16856 * stack frame is cleaned up. This macro essentially just wraps the alloca()
16857 * function present on most UNIX variants.
16858 * Thus it provides the same advantages and pitfalls as alloca():
16860 * <varlistentry><term></term><listitem><para>
16861 * + alloca() is very fast, as on most systems it's implemented by just adjusting
16862 * the stack pointer register.
16863 * </para></listitem></varlistentry>
16864 * <varlistentry><term></term><listitem><para>
16865 * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
16866 * blocks just build up and are released together at function end.
16867 * </para></listitem></varlistentry>
16868 * <varlistentry><term></term><listitem><para>
16869 * - Allocation sizes have to fit into the current stack frame. For instance in a
16870 * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
16871 * so be sparse with alloca() uses.
16872 * </para></listitem></varlistentry>
16873 * <varlistentry><term></term><listitem><para>
16874 * - Allocation failure due to insufficient stack space is not indicated with a %NULL
16875 * return like e.g. with malloc(). Instead, most systems probably handle it the same
16876 * way as out of stack space situations from infinite function recursion, i.e.
16877 * with a segmentation fault.
16878 * </para></listitem></varlistentry>
16879 * <varlistentry><term></term><listitem><para>
16880 * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
16881 * Stack space allocated with alloca() in the same scope as a variable sized array
16882 * will be freed together with the variable sized array upon exit of that scope, and
16883 * not upon exit of the enclosing function scope.
16884 * </para></listitem></varlistentry>
16887 * Returns: space for @size bytes, allocated on the stack
16892 * g_app_info_add_supports_type:
16893 * @appinfo: a #GAppInfo.
16894 * @content_type: a string.
16895 * @error: a #GError.
16897 * Adds a content type to the application information to indicate the
16898 * application is capable of opening files with the given content type.
16900 * Returns: %TRUE on success, %FALSE on error.
16905 * g_app_info_can_delete:
16906 * @appinfo: a #GAppInfo
16908 * Obtains the information whether the #GAppInfo can be deleted.
16909 * See g_app_info_delete().
16911 * Returns: %TRUE if @appinfo can be deleted
16917 * g_app_info_can_remove_supports_type:
16918 * @appinfo: a #GAppInfo.
16920 * Checks if a supported content type can be removed from an application.
16922 * content types from a given @appinfo, %FALSE if not.
16924 * Returns: %TRUE if it is possible to remove supported
16929 * g_app_info_create_from_commandline:
16930 * @commandline: the commandline to use
16931 * @application_name: (allow-none): the application name, or %NULL to use @commandline
16932 * @flags: flags that can specify details of the created #GAppInfo
16933 * @error: a #GError location to store the error occurring, %NULL to ignore.
16935 * Creates a new #GAppInfo from the given information.
16937 * Returns: (transfer full): new #GAppInfo for given command.
16942 * g_app_info_delete:
16943 * @appinfo: a #GAppInfo
16945 * Tries to delete a #GAppInfo.
16947 * On some platforms, there may be a difference between user-defined
16948 * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
16949 * cannot. See g_app_info_can_delete().
16951 * Virtual: do_delete
16952 * Returns: %TRUE if @appinfo has been deleted
16959 * @appinfo: a #GAppInfo.
16961 * Creates a duplicate of a #GAppInfo.
16963 * Returns: (transfer full): a duplicate of @appinfo.
16968 * g_app_info_equal:
16969 * @appinfo1: the first #GAppInfo.
16970 * @appinfo2: the second #GAppInfo.
16972 * Checks if two #GAppInfo<!-- -->s are equal.
16974 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
16979 * g_app_info_get_all:
16981 * Gets a list of all of the applications currently registered
16984 * For desktop files, this includes applications that have
16985 * <literal>NoDisplay=true</literal> set or are excluded from
16986 * display by means of <literal>OnlyShowIn</literal> or
16987 * <literal>NotShowIn</literal>. See g_app_info_should_show().
16988 * The returned list does not include applications which have
16989 * the <literal>Hidden</literal> key set.
16991 * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s.
16996 * g_app_info_get_all_for_type:
16997 * @content_type: the content type to find a #GAppInfo for
16999 * Gets a list of all #GAppInfos for a given content type,
17000 * including the recommended and fallback #GAppInfos. See
17001 * g_app_info_get_recommended_for_type() and
17002 * g_app_info_get_fallback_for_type().
17004 * for given @content_type or %NULL on error.
17006 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
17011 * g_app_info_get_commandline:
17012 * @appinfo: a #GAppInfo
17014 * Gets the commandline with which the application will be
17017 * or %NULL if this information is not available
17019 * Returns: a string containing the @appinfo's commandline,
17025 * g_app_info_get_default_for_type:
17026 * @content_type: the content type to find a #GAppInfo for
17027 * @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs
17029 * Gets the default #GAppInfo for a given content type.
17033 * Returns: (transfer full): #GAppInfo for given @content_type or
17038 * g_app_info_get_default_for_uri_scheme:
17039 * @uri_scheme: a string containing a URI scheme.
17041 * Gets the default application for handling URIs with
17042 * the given URI scheme. A URI scheme is the initial part
17043 * of the URI, up to but not including the ':', e.g. "http",
17046 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
17051 * g_app_info_get_description:
17052 * @appinfo: a #GAppInfo.
17054 * Gets a human-readable description of an installed application.
17056 * application @appinfo, or %NULL if none.
17058 * Returns: a string containing a description of the
17063 * g_app_info_get_display_name:
17064 * @appinfo: a #GAppInfo.
17066 * Gets the display name of the application. The display name is often more
17067 * descriptive to the user than the name itself.
17069 * no display name is available.
17071 * Returns: the display name of the application for @appinfo, or the name if
17077 * g_app_info_get_executable:
17078 * @appinfo: a #GAppInfo
17080 * Gets the executable's name for the installed application.
17084 * Returns: a string containing the @appinfo's application
17089 * g_app_info_get_fallback_for_type:
17090 * @content_type: the content type to find a #GAppInfo for
17092 * Gets a list of fallback #GAppInfos for a given content type, i.e.
17093 * those applications which claim to support the given content type
17094 * by MIME type subclassing and not directly.
17096 * for given @content_type or %NULL on error.
17098 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
17104 * g_app_info_get_icon:
17105 * @appinfo: a #GAppInfo.
17107 * Gets the icon for the application.
17109 * if there is no default icon.
17111 * Returns: (transfer none): the default #GIcon for @appinfo or %NULL
17116 * g_app_info_get_id:
17117 * @appinfo: a #GAppInfo.
17119 * Gets the ID of an application. An id is a string that
17120 * identifies the application. The exact format of the id is
17121 * platform dependent. For instance, on Unix this is the
17122 * desktop file id from the xdg menu specification.
17124 * Note that the returned ID may be %NULL, depending on how
17125 * the @appinfo has been constructed.
17127 * Returns: a string containing the application's ID.
17132 * g_app_info_get_name:
17133 * @appinfo: a #GAppInfo.
17135 * Gets the installed name of the application.
17137 * Returns: the name of the application for @appinfo.
17142 * g_app_info_get_recommended_for_type:
17143 * @content_type: the content type to find a #GAppInfo for
17145 * Gets a list of recommended #GAppInfos for a given content type, i.e.
17146 * those applications which claim to support the given content type exactly,
17147 * and not by MIME type subclassing.
17148 * Note that the first application of the list is the last used one, i.e.
17149 * the last one for which g_app_info_set_as_last_used_for_type() has been
17152 * for given @content_type or %NULL on error.
17154 * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
17160 * g_app_info_launch:
17161 * @appinfo: a #GAppInfo
17162 * @files: (element-type GFile): a #GList of #GFile objects
17163 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
17164 * @error: a #GError
17166 * Launches the application. Passes @files to the launched application
17167 * as arguments, using the optional @launch_context to get information
17168 * about the details of the launcher (like what screen it is on).
17169 * On error, @error will be set accordingly.
17171 * To launch the application without arguments pass a %NULL @files list.
17173 * Note that even if the launch is successful the application launched
17174 * can fail to start if it runs into problems during startup. There is
17175 * no way to detect this.
17177 * Some URIs can be changed when passed through a GFile (for instance
17178 * unsupported URIs with strange formats like mailto:), so if you have
17179 * a textual URI you want to pass in as argument, consider using
17180 * g_app_info_launch_uris() instead.
17182 * The launched application inherits the environment of the launching
17183 * process, but it can be modified with g_app_launch_context_setenv() and
17184 * g_app_launch_context_unsetenv().
17186 * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
17187 * environment variable with the path of the launched desktop file and
17188 * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
17189 * id of the launched process. This can be used to ignore
17190 * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
17191 * by further processes. The <envar>DISPLAY</envar> and
17192 * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also
17193 * set, based on information provided in @launch_context.
17195 * Returns: %TRUE on successful launch, %FALSE otherwise.
17200 * g_app_info_launch_default_for_uri:
17201 * @uri: the uri to show
17202 * @launch_context: (allow-none): an optional #GAppLaunchContext.
17203 * @error: a #GError.
17205 * Utility function that launches the default application
17206 * registered to handle the specified uri. Synchronous I/O
17207 * is done on the uri to detect the type of the file if
17210 * Returns: %TRUE on success, %FALSE on error.
17215 * g_app_info_launch_uris:
17216 * @appinfo: a #GAppInfo
17217 * @uris: (element-type utf8): a #GList containing URIs to launch.
17218 * @launch_context: (allow-none): a #GAppLaunchContext or %NULL
17219 * @error: a #GError
17221 * Launches the application. This passes the @uris to the launched application
17222 * as arguments, using the optional @launch_context to get information
17223 * about the details of the launcher (like what screen it is on).
17224 * On error, @error will be set accordingly.
17226 * To launch the application without arguments pass a %NULL @uris list.
17228 * Note that even if the launch is successful the application launched
17229 * can fail to start if it runs into problems during startup. There is
17230 * no way to detect this.
17232 * Returns: %TRUE on successful launch, %FALSE otherwise.
17237 * g_app_info_remove_supports_type:
17238 * @appinfo: a #GAppInfo.
17239 * @content_type: a string.
17240 * @error: a #GError.
17242 * Removes a supported type from an application, if possible.
17244 * Returns: %TRUE on success, %FALSE on error.
17249 * g_app_info_reset_type_associations:
17250 * @content_type: a content type
17252 * Removes all changes to the type associations done by
17253 * g_app_info_set_as_default_for_type(),
17254 * g_app_info_set_as_default_for_extension(),
17255 * g_app_info_add_supports_type() or
17256 * g_app_info_remove_supports_type().
17263 * g_app_info_set_as_default_for_extension:
17264 * @appinfo: a #GAppInfo.
17265 * @extension: a string containing the file extension (without the dot).
17266 * @error: a #GError.
17268 * Sets the application as the default handler for the given file extension.
17270 * Returns: %TRUE on success, %FALSE on error.
17275 * g_app_info_set_as_default_for_type:
17276 * @appinfo: a #GAppInfo.
17277 * @content_type: the content type.
17278 * @error: a #GError.
17280 * Sets the application as the default handler for a given type.
17282 * Returns: %TRUE on success, %FALSE on error.
17287 * g_app_info_set_as_last_used_for_type:
17288 * @appinfo: a #GAppInfo.
17289 * @content_type: the content type.
17290 * @error: a #GError.
17292 * Sets the application as the last used application for a given type.
17293 * This will make the application appear as first in the list returned
17294 * by g_app_info_get_recommended_for_type(), regardless of the default
17295 * application for that content type.
17297 * Returns: %TRUE on success, %FALSE on error.
17302 * g_app_info_should_show:
17303 * @appinfo: a #GAppInfo.
17305 * Checks if the application info should be shown in menus that
17306 * list available applications.
17308 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
17313 * g_app_info_supports_files:
17314 * @appinfo: a #GAppInfo.
17316 * Checks if the application accepts files as arguments.
17318 * Returns: %TRUE if the @appinfo supports files.
17323 * g_app_info_supports_uris:
17324 * @appinfo: a #GAppInfo.
17326 * Checks if the application supports reading files and directories from URIs.
17328 * Returns: %TRUE if the @appinfo supports URIs.
17333 * g_app_launch_context_get_display:
17334 * @context: a #GAppLaunchContext
17335 * @info: a #GAppInfo
17336 * @files: (element-type GFile): a #GList of #GFile objects
17338 * Gets the display string for the @context. This is used to ensure new
17339 * applications are started on the same display as the launching
17340 * application, by setting the <envar>DISPLAY</envar> environment variable.
17342 * Returns: a display string for the display.
17347 * g_app_launch_context_get_environment:
17348 * @context: a #GAppLaunchContext
17350 * Gets the complete environment variable list to be passed to
17351 * the child process when @context is used to launch an application.
17352 * This is a %NULL-terminated array of strings, where each string has
17353 * the form <literal>KEY=VALUE</literal>.
17355 * child's environment
17357 * Returns: (array zero-terminated=1) (transfer full): the
17363 * g_app_launch_context_get_startup_notify_id:
17364 * @context: a #GAppLaunchContext
17365 * @info: a #GAppInfo
17366 * @files: (element-type GFile): a #GList of of #GFile objects
17368 * Initiates startup notification for the application and returns the
17369 * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
17372 * Startup notification IDs are defined in the <ulink
17373 * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
17374 * FreeDesktop.Org Startup Notifications standard</ulink>.
17378 * Returns: a startup notification ID for the application, or %NULL if
17383 * g_app_launch_context_launch_failed:
17384 * @context: a #GAppLaunchContext.
17385 * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
17387 * Called when an application has failed to launch, so that it can cancel
17388 * the application startup notification started in g_app_launch_context_get_startup_notify_id().
17393 * g_app_launch_context_new:
17395 * Creates a new application launch context. This is not normally used,
17396 * instead you instantiate a subclass of this, such as #GdkAppLaunchContext.
17398 * Returns: a #GAppLaunchContext.
17403 * g_app_launch_context_setenv:
17404 * @context: a #GAppLaunchContext
17405 * @variable: the environment variable to set
17406 * @value: the value for to set the variable to.
17408 * Arranges for @variable to be set to @value in the child's
17409 * environment when @context is used to launch an application.
17416 * g_app_launch_context_unsetenv:
17417 * @context: a #GAppLaunchContext
17418 * @variable: the environment variable to remove
17420 * Arranges for @variable to be unset in the child's environment
17421 * when @context is used to launch an application.
17428 * g_application_activate:
17429 * @application: a #GApplication
17431 * Activates the application.
17433 * In essence, this results in the #GApplication::activate signal being
17434 * emitted in the primary instance.
17436 * The application must be registered before calling this function.
17443 * g_application_command_line_get_arguments:
17444 * @cmdline: a #GApplicationCommandLine
17445 * @argc: (out): the length of the arguments array, or %NULL
17447 * Gets the list of arguments that was passed on the command line.
17449 * The strings in the array may contain non-utf8 data.
17451 * The return value is %NULL-terminated and should be freed using
17454 * containing the arguments (the argv)
17456 * Returns: (array length=argc) (transfer full): the string array
17462 * g_application_command_line_get_cwd:
17463 * @cmdline: a #GApplicationCommandLine
17465 * Gets the working directory of the command line invocation.
17466 * The string may contain non-utf8 data.
17468 * It is possible that the remote application did not send a working
17469 * directory, so this may be %NULL.
17471 * The return value should not be modified or freed and is valid for as
17472 * long as @cmdline exists.
17474 * Returns: the current directory, or %NULL
17480 * g_application_command_line_get_environ:
17481 * @cmdline: a #GApplicationCommandLine
17483 * Gets the contents of the 'environ' variable of the command line
17484 * invocation, as would be returned by g_get_environ(), ie as a
17485 * %NULL-terminated list of strings in the form 'NAME=VALUE'.
17486 * The strings may contain non-utf8 data.
17488 * The remote application usually does not send an environment. Use
17489 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
17490 * set it is possible that the environment is still not available (due
17491 * to invocation messages from other applications).
17493 * The return value should not be modified or freed and is valid for as
17494 * long as @cmdline exists.
17496 * See g_application_command_line_getenv() if you are only interested
17497 * in the value of a single environment variable.
17499 * strings, or %NULL if they were not sent
17501 * Returns: (array zero-terminated=1) (transfer none): the environment
17507 * g_application_command_line_get_exit_status:
17508 * @cmdline: a #GApplicationCommandLine
17510 * Gets the exit status of @cmdline. See
17511 * g_application_command_line_set_exit_status() for more information.
17513 * Returns: the exit status
17519 * g_application_command_line_get_is_remote:
17520 * @cmdline: a #GApplicationCommandLine
17522 * Determines if @cmdline represents a remote invocation.
17524 * Returns: %TRUE if the invocation was remote
17530 * g_application_command_line_get_platform_data:
17531 * @cmdline: #GApplicationCommandLine
17533 * Gets the platform data associated with the invocation of @cmdline.
17535 * This is a #GVariant dictionary containing information about the
17536 * context in which the invocation occurred. It typically contains
17537 * information like the current working directory and the startup
17540 * For local invocation, it will be %NULL.
17542 * Returns: (allow-none): the platform data, or %NULL
17548 * g_application_command_line_getenv:
17549 * @cmdline: a #GApplicationCommandLine
17550 * @name: the environment variable to get
17552 * Gets the value of a particular environment variable of the command
17553 * line invocation, as would be returned by g_getenv(). The strings may
17554 * contain non-utf8 data.
17556 * The remote application usually does not send an environment. Use
17557 * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag
17558 * set it is possible that the environment is still not available (due
17559 * to invocation messages from other applications).
17561 * The return value should not be modified or freed and is valid for as
17562 * long as @cmdline exists.
17564 * Returns: the value of the variable, or %NULL if unset or unsent
17570 * g_application_command_line_print:
17571 * @cmdline: a #GApplicationCommandLine
17572 * @format: a printf-style format string
17573 * @...: arguments, as per @format
17575 * Formats a message and prints it using the stdout print handler in the
17576 * invoking process.
17578 * If @cmdline is a local invocation then this is exactly equivalent to
17579 * g_print(). If @cmdline is remote then this is equivalent to calling
17580 * g_print() in the invoking process.
17587 * g_application_command_line_printerr:
17588 * @cmdline: a #GApplicationCommandLine
17589 * @format: a printf-style format string
17590 * @...: arguments, as per @format
17592 * Formats a message and prints it using the stderr print handler in the
17593 * invoking process.
17595 * If @cmdline is a local invocation then this is exactly equivalent to
17596 * g_printerr(). If @cmdline is remote then this is equivalent to
17597 * calling g_printerr() in the invoking process.
17604 * g_application_command_line_set_exit_status:
17605 * @cmdline: a #GApplicationCommandLine
17606 * @exit_status: the exit status
17608 * Sets the exit status that will be used when the invoking process
17611 * The return value of the #GApplication::command-line signal is
17612 * passed to this function when the handler returns. This is the usual
17613 * way of setting the exit status.
17615 * In the event that you want the remote invocation to continue running
17616 * and want to decide on the exit status in the future, you can use this
17617 * call. For the case of a remote invocation, the remote process will
17618 * typically exit when the last reference is dropped on @cmdline. The
17619 * exit status of the remote process will be equal to the last value
17620 * that was set with this function.
17622 * In the case that the commandline invocation is local, the situation
17623 * is slightly more complicated. If the commandline invocation results
17624 * in the mainloop running (ie: because the use-count of the application
17625 * increased to a non-zero value) then the application is considered to
17626 * have been 'successful' in a certain sense, and the exit status is
17627 * always zero. If the application use count is zero, though, the exit
17628 * status of the local #GApplicationCommandLine is used.
17635 * g_application_get_application_id:
17636 * @application: a #GApplication
17638 * Gets the unique identifier for @application.
17640 * Returns: the identifier for @application, owned by @application
17646 * g_application_get_default:
17648 * Returns the default #GApplication instance for this process.
17650 * Normally there is only one #GApplication per process and it becomes
17651 * the default when it is created. You can exercise more control over
17652 * this by using g_application_set_default().
17654 * If there is no default application then %NULL is returned.
17656 * Returns: (transfer none): the default application for this process, or %NULL
17662 * g_application_get_flags:
17663 * @application: a #GApplication
17665 * Gets the flags for @application.
17667 * See #GApplicationFlags.
17669 * Returns: the flags for @application
17675 * g_application_get_inactivity_timeout:
17676 * @application: a #GApplication
17678 * Gets the current inactivity timeout for the application.
17680 * This is the amount of time (in milliseconds) after the last call to
17681 * g_application_release() before the application stops running.
17683 * Returns: the timeout, in milliseconds
17689 * g_application_get_is_registered:
17690 * @application: a #GApplication
17692 * Checks if @application is registered.
17694 * An application is registered if g_application_register() has been
17695 * successfully called.
17697 * Returns: %TRUE if @application is registered
17703 * g_application_get_is_remote:
17704 * @application: a #GApplication
17706 * Checks if @application is remote.
17708 * If @application is remote then it means that another instance of
17709 * application already exists (the 'primary' instance). Calls to
17710 * perform actions on @application will result in the actions being
17711 * performed by the primary instance.
17713 * The value of this property cannot be accessed before
17714 * g_application_register() has been called. See
17715 * g_application_get_is_registered().
17717 * Returns: %TRUE if @application is remote
17723 * g_application_hold:
17724 * @application: a #GApplication
17726 * Increases the use count of @application.
17728 * Use this function to indicate that the application has a reason to
17729 * continue to run. For example, g_application_hold() is called by GTK+
17730 * when a toplevel window is on the screen.
17732 * To cancel the hold, call g_application_release().
17737 * g_application_id_is_valid:
17738 * @application_id: a potential application identifier
17740 * Checks if @application_id is a valid application identifier.
17742 * A valid ID is required for calls to g_application_new() and
17743 * g_application_set_application_id().
17745 * For convenience, the restrictions on application identifiers are
17748 * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem>
17749 * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem>
17750 * <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem>
17751 * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
17752 * <listitem>Application identifiers must not exceed 255 characters.</listitem>
17755 * Returns: %TRUE if @application_id is valid
17760 * g_application_new:
17761 * @application_id: the application id
17762 * @flags: the application flags
17764 * Creates a new #GApplication instance.
17766 * This function calls g_type_init() for you.
17768 * The application id must be valid. See g_application_id_is_valid().
17770 * Returns: a new #GApplication instance
17775 * g_application_open:
17776 * @application: a #GApplication
17777 * @files: (array length=n_files): an array of #GFiles to open
17778 * @n_files: the length of the @files array
17779 * @hint: a hint (or ""), but never %NULL
17781 * Opens the given files.
17783 * In essence, this results in the #GApplication::open signal being emitted
17784 * in the primary instance.
17786 * @n_files must be greater than zero.
17788 * @hint is simply passed through to the ::open signal. It is
17789 * intended to be used by applications that have multiple modes for
17790 * opening files (eg: "view" vs "edit", etc). Unless you have a need
17791 * for this functionality, you should use "".
17793 * The application must be registered before calling this function
17794 * and it must have the %G_APPLICATION_HANDLES_OPEN flag set.
17801 * g_application_quit:
17802 * @application: a #GApplication
17804 * Immediately quits the application.
17806 * Upon return to the mainloop, g_application_run() will return,
17807 * calling only the 'shutdown' function before doing so.
17809 * The hold count is ignored.
17811 * The result of calling g_application_run() again after it returns is
17819 * g_application_register:
17820 * @application: a #GApplication
17821 * @cancellable: a #GCancellable, or %NULL
17822 * @error: a pointer to a NULL #GError, or %NULL
17824 * Attempts registration of the application.
17826 * This is the point at which the application discovers if it is the
17827 * primary instance or merely acting as a remote for an already-existing
17828 * primary instance. This is implemented by attempting to acquire the
17829 * application identifier as a unique bus name on the session bus using
17832 * Due to the internal architecture of GDBus, method calls can be
17833 * dispatched at any time (even if a main loop is not running). For
17834 * this reason, you must ensure that any object paths that you wish to
17835 * register are registered before calling this function.
17837 * If the application has already been registered then %TRUE is
17838 * returned with no work performed.
17840 * The #GApplication::startup signal is emitted if registration succeeds
17841 * and @application is the primary instance.
17843 * In the event of an error (such as @cancellable being cancelled, or a
17844 * failure to connect to the session bus), %FALSE is returned and @error
17845 * is set appropriately.
17847 * Note: the return value of this function is not an indicator that this
17848 * instance is or is not the primary instance of the application. See
17849 * g_application_get_is_remote() for that.
17851 * Returns: %TRUE if registration succeeded
17857 * g_application_release:
17858 * @application: a #GApplication
17860 * Decrease the use count of @application.
17862 * When the use count reaches zero, the application will stop running.
17864 * Never call this function except to cancel the effect of a previous
17865 * call to g_application_hold().
17870 * g_application_run:
17871 * @application: a #GApplication
17872 * @argc: the argc from main() (or 0 if @argv is %NULL)
17873 * @argv: (array length=argc) (allow-none): the argv from main(), or %NULL
17875 * Runs the application.
17877 * This function is intended to be run from main() and its return value
17878 * is intended to be returned by main(). Although you are expected to pass
17879 * the @argc, @argv parameters from main() to this function, it is possible
17880 * to pass %NULL if @argv is not available or commandline handling is not
17883 * First, the local_command_line() virtual function is invoked.
17884 * This function always runs on the local instance. It gets passed a pointer
17885 * to a %NULL-terminated copy of @argv and is expected to remove the arguments
17886 * that it handled (shifting up remaining arguments). See
17887 * <xref linkend="gapplication-example-cmdline2"/> for an example of
17888 * parsing @argv manually. Alternatively, you may use the #GOptionContext API,
17889 * after setting <literal>argc = g_strv_length (argv);</literal>.
17891 * The last argument to local_command_line() is a pointer to the @status
17892 * variable which can used to set the exit status that is returned from
17893 * g_application_run().
17895 * If local_command_line() returns %TRUE, the command line is expected
17896 * to be completely handled, including possibly registering as the primary
17897 * instance, calling g_application_activate() or g_application_open(), etc.
17899 * If local_command_line() returns %FALSE then the application is registered
17900 * and the #GApplication::command-line signal is emitted in the primary
17901 * instance (which may or may not be this instance). The signal handler
17902 * gets passed a #GApplicationCommandLine object that (among other things)
17903 * contains the remaining commandline arguments that have not been handled
17904 * by local_command_line().
17906 * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
17907 * flag set then the default implementation of local_command_line()
17908 * always returns %FALSE immediately, resulting in the commandline
17909 * always being handled in the primary instance.
17911 * Otherwise, the default implementation of local_command_line() tries
17912 * to do a couple of things that are probably reasonable for most
17913 * applications. First, g_application_register() is called to attempt
17914 * to register the application. If that works, then the command line
17915 * arguments are inspected. If no commandline arguments are given, then
17916 * g_application_activate() is called. If commandline arguments are
17917 * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
17918 * are assumed to be filenames and g_application_open() is called.
17920 * If you need to handle commandline arguments that are not filenames,
17921 * and you don't mind commandline handling to happen in the primary
17922 * instance, you should set %G_APPLICATION_HANDLES_COMMAND_LINE and
17923 * process the commandline arguments in your #GApplication::command-line
17924 * signal handler, either manually or using the #GOptionContext API.
17926 * If you are interested in doing more complicated local handling of the
17927 * commandline then you should implement your own #GApplication subclass
17928 * and override local_command_line(). In this case, you most likely want
17929 * to return %TRUE from your local_command_line() implementation to
17930 * suppress the default handling. See
17931 * <xref linkend="gapplication-example-cmdline2"/> for an example.
17933 * If, after the above is done, the use count of the application is zero
17934 * then the exit status is returned immediately. If the use count is
17935 * non-zero then the default main context is iterated until the use count
17936 * falls to zero, at which point 0 is returned.
17938 * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at
17939 * use count of zero is delayed for a while (ie: the instance stays
17940 * around to provide its <emphasis>service</emphasis> to others).
17942 * Returns: the exit status
17948 * g_application_set_action_group:
17949 * @application: a #GApplication
17950 * @action_group: (allow-none): a #GActionGroup, or %NULL
17952 * This used to be how actions were associated with a #GApplication.
17953 * Now there is #GActionMap for that.
17956 * Deprecated:2.32:Use the #GActionMap interface instead. Never ever
17957 * mix use of this API with use of #GActionMap on the same @application
17958 * or things will go very badly wrong. This function is known to
17959 * introduce buggy behaviour (ie: signals not emitted on changes to the
17960 * action group), so you should really use #GActionMap instead.
17967 * g_application_set_application_id:
17968 * @application: a #GApplication
17969 * @application_id: the identifier for @application
17971 * Sets the unique identifier for @application.
17973 * The application id can only be modified if @application has not yet
17976 * The application id must be valid. See g_application_id_is_valid().
17983 * g_application_set_default:
17984 * @application: the application to set as default, or %NULL
17986 * Sets or unsets the default application for the process, as returned
17987 * by g_application_get_default().
17989 * This function does not take its own reference on @application. If
17990 * @application is destroyed then the default application will revert
17998 * g_application_set_flags:
17999 * @application: a #GApplication
18000 * @flags: the flags for @application
18002 * Sets the flags for @application.
18004 * The flags can only be modified if @application has not yet been
18007 * See #GApplicationFlags.
18014 * g_application_set_inactivity_timeout:
18015 * @application: a #GApplication
18016 * @inactivity_timeout: the timeout, in milliseconds
18018 * Sets the current inactivity timeout for the application.
18020 * This is the amount of time (in milliseconds) after the last call to
18021 * g_application_release() before the application stops running.
18023 * This call has no side effects of its own. The value set here is only
18024 * used for next time g_application_release() drops the use count to
18025 * zero. Any timeouts currently in progress are not impacted.
18032 * g_async_initable_init_async:
18033 * @initable: a #GAsyncInitable.
18034 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
18035 * @cancellable: optional #GCancellable object, %NULL to ignore.
18036 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
18037 * @user_data: the data to pass to callback function
18039 * Starts asynchronous initialization of the object implementing the
18040 * interface. This must be done before any real use of the object after
18041 * initial construction. If the object also implements #GInitable you can
18042 * optionally call g_initable_init() instead.
18044 * When the initialization is finished, @callback will be called. You can
18045 * then call g_async_initable_init_finish() to get the result of the
18048 * Implementations may also support cancellation. If @cancellable is not
18049 * %NULL, then initialization can be cancelled by triggering the cancellable
18050 * object from another thread. If the operation was cancelled, the error
18051 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and
18052 * the object doesn't support cancellable initialization, the error
18053 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
18055 * As with #GInitable, if the object is not initialized, or initialization
18056 * returns with an error, then all operations on the object except
18057 * g_object_ref() and g_object_unref() are considered to be invalid, and
18058 * have undefined behaviour. They will often fail with g_critical() or
18059 * g_warning(), but this must not be relied on.
18061 * Implementations of this method must be idempotent: i.e. multiple calls
18062 * to this function with the same argument should return the same results.
18063 * Only the first call initializes the object; further calls return the result
18064 * of the first call. This is so that it's safe to implement the singleton
18065 * pattern in the GObject constructor function.
18067 * For classes that also support the #GInitable interface, the default
18068 * implementation of this method will run the g_initable_init() function
18069 * in a thread, so if you want to support asynchronous initialization via
18070 * threads, just implement the #GAsyncInitable interface without overriding
18071 * any interface methods.
18078 * g_async_initable_init_finish:
18079 * @initable: a #GAsyncInitable.
18080 * @res: a #GAsyncResult.
18081 * @error: a #GError location to store the error occurring, or %NULL to ignore.
18083 * Finishes asynchronous initialization and returns the result.
18084 * See g_async_initable_init_async().
18086 * will return %FALSE and set @error appropriately if present.
18088 * Returns: %TRUE if successful. If an error has occurred, this function
18094 * g_async_initable_new_async:
18095 * @object_type: a #GType supporting #GAsyncInitable.
18096 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
18097 * @cancellable: optional #GCancellable object, %NULL to ignore.
18098 * @callback: a #GAsyncReadyCallback to call when the initialization is finished
18099 * @user_data: the data to pass to callback function
18100 * @first_property_name: the name of the first property, or %NULL if no properties
18101 * @...: the value of the first property, followed by other property value pairs, and ended by %NULL.
18103 * Helper function for constructing #GAsyncInitable object. This is
18104 * similar to g_object_new() but also initializes the object asynchronously.
18106 * When the initialization is finished, @callback will be called. You can
18107 * then call g_async_initable_new_finish() to get the new object and check
18115 * g_async_initable_new_finish:
18116 * @initable: the #GAsyncInitable from the callback
18117 * @res: the #GAsyncResult from the callback
18118 * @error: return location for errors, or %NULL to ignore
18120 * Finishes the async construction for the various g_async_initable_new
18121 * calls, returning the created object or %NULL on error.
18123 * Free with g_object_unref().
18125 * Returns: (transfer full): a newly created #GObject, or %NULL on error.
18131 * g_async_initable_new_valist_async:
18132 * @object_type: a #GType supporting #GAsyncInitable.
18133 * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL.
18134 * @var_args: The var args list generated from @first_property_name.
18135 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
18136 * @cancellable: optional #GCancellable object, %NULL to ignore.
18137 * @callback: a #GAsyncReadyCallback to call when the initialization is finished
18138 * @user_data: the data to pass to callback function
18140 * Helper function for constructing #GAsyncInitable object. This is
18141 * similar to g_object_new_valist() but also initializes the object
18144 * When the initialization is finished, @callback will be called. You can
18145 * then call g_async_initable_new_finish() to get the new object and check
18153 * g_async_initable_newv_async:
18154 * @object_type: a #GType supporting #GAsyncInitable.
18155 * @n_parameters: the number of parameters in @parameters
18156 * @parameters: the parameters to use to construct the object
18157 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation.
18158 * @cancellable: optional #GCancellable object, %NULL to ignore.
18159 * @callback: a #GAsyncReadyCallback to call when the initialization is finished
18160 * @user_data: the data to pass to callback function
18162 * Helper function for constructing #GAsyncInitable object. This is
18163 * similar to g_object_newv() but also initializes the object asynchronously.
18165 * When the initialization is finished, @callback will be called. You can
18166 * then call g_async_initable_new_finish() to get the new object and check
18174 * g_async_result_get_source_object:
18175 * @res: a #GAsyncResult
18177 * Gets the source object from a #GAsyncResult.
18179 * or %NULL if there is none.
18181 * Returns: (transfer full): a new reference to the source object for the @res,
18186 * g_async_result_get_user_data:
18187 * @res: a #GAsyncResult.
18189 * Gets the user data from a #GAsyncResult.
18191 * Returns: (transfer full): the user data for @res.
18196 * g_buffered_input_stream_fill:
18197 * @stream: a #GBufferedInputStream
18198 * @count: the number of bytes that will be read from the stream
18199 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18200 * @error: location to store the error occurring, or %NULL to ignore
18202 * Tries to read @count bytes from the stream into the buffer.
18203 * Will block during this read.
18205 * If @count is zero, returns zero and does nothing. A value of @count
18206 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
18208 * On success, the number of bytes read into the buffer is returned.
18209 * It is not an error if this is not the same as the requested size, as it
18210 * can happen e.g. near the end of a file. Zero is returned on end of file
18211 * (or if @count is zero), but never otherwise.
18213 * If @count is -1 then the attempted read size is equal to the number of
18214 * bytes that are required to fill the buffer.
18216 * If @cancellable is not %NULL, then the operation can be cancelled by
18217 * triggering the cancellable object from another thread. If the operation
18218 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
18219 * operation was partially finished when the operation was cancelled the
18220 * partial result will be returned, without an error.
18222 * On error -1 is returned and @error is set accordingly.
18224 * For the asynchronous, non-blocking, version of this function, see
18225 * g_buffered_input_stream_fill_async().
18229 * Returns: the number of bytes read into @stream's buffer, up to @count,
18234 * g_buffered_input_stream_fill_async:
18235 * @stream: a #GBufferedInputStream
18236 * @count: the number of bytes that will be read from the stream
18237 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
18238 * @cancellable: (allow-none): optional #GCancellable object
18239 * @callback: (scope async): a #GAsyncReadyCallback
18240 * @user_data: (closure): a #gpointer
18242 * Reads data into @stream's buffer asynchronously, up to @count size.
18243 * @io_priority can be used to prioritize reads. For the synchronous
18244 * version of this function, see g_buffered_input_stream_fill().
18246 * If @count is -1 then the attempted read size is equal to the number
18247 * of bytes that are required to fill the buffer.
18252 * g_buffered_input_stream_fill_finish:
18253 * @stream: a #GBufferedInputStream
18254 * @result: a #GAsyncResult
18255 * @error: a #GError
18257 * Finishes an asynchronous read.
18259 * Returns: a #gssize of the read stream, or %-1 on an error.
18264 * g_buffered_input_stream_get_available:
18265 * @stream: #GBufferedInputStream
18267 * Gets the size of the available data within the stream.
18269 * Returns: size of the available stream.
18274 * g_buffered_input_stream_get_buffer_size:
18275 * @stream: a #GBufferedInputStream
18277 * Gets the size of the input buffer.
18279 * Returns: the current buffer size.
18284 * g_buffered_input_stream_new:
18285 * @base_stream: a #GInputStream
18287 * Creates a new #GInputStream from the given @base_stream, with
18288 * a buffer set to the default size (4 kilobytes).
18290 * Returns: a #GInputStream for the given @base_stream.
18295 * g_buffered_input_stream_new_sized:
18296 * @base_stream: a #GInputStream
18299 * Creates a new #GBufferedInputStream from the given @base_stream,
18300 * with a buffer set to @size.
18302 * Returns: a #GInputStream.
18307 * g_buffered_input_stream_peek:
18308 * @stream: a #GBufferedInputStream
18309 * @buffer: (array length=count) (element-type guint8): a pointer to an allocated chunk of memory
18310 * @offset: a #gsize
18313 * Peeks in the buffer, copying data of size @count into @buffer,
18314 * offset @offset bytes.
18316 * Returns: a #gsize of the number of bytes peeked, or -1 on error.
18321 * g_buffered_input_stream_peek_buffer:
18322 * @stream: a #GBufferedInputStream
18323 * @count: (out): a #gsize to get the number of bytes available in the buffer
18325 * Returns the buffer with the currently available bytes. The returned
18326 * buffer must not be modified and will become invalid when reading from
18327 * the stream or filling the buffer.
18331 * Returns: (array length=count) (element-type guint8) (transfer none):
18336 * g_buffered_input_stream_read_byte:
18337 * @stream: a #GBufferedInputStream
18338 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
18339 * @error: location to store the error occurring, or %NULL to ignore
18341 * Tries to read a single byte from the stream or the buffer. Will block
18342 * during this read.
18344 * On success, the byte read from the stream is returned. On end of stream
18345 * -1 is returned but it's not an exceptional error and @error is not set.
18347 * If @cancellable is not %NULL, then the operation can be cancelled by
18348 * triggering the cancellable object from another thread. If the operation
18349 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
18350 * operation was partially finished when the operation was cancelled the
18351 * partial result will be returned, without an error.
18353 * On error -1 is returned and @error is set accordingly.
18355 * Returns: the byte read from the @stream, or -1 on end of stream or error.
18360 * g_buffered_input_stream_set_buffer_size:
18361 * @stream: a #GBufferedInputStream
18364 * Sets the size of the internal buffer of @stream to @size, or to the
18365 * size of the contents of the buffer. The buffer can never be resized
18366 * smaller than its current contents.
18371 * g_buffered_output_stream_get_auto_grow:
18372 * @stream: a #GBufferedOutputStream.
18374 * Checks if the buffer automatically grows as data is added.
18376 * %FALSE otherwise.
18378 * Returns: %TRUE if the @stream's buffer automatically grows,
18383 * g_buffered_output_stream_get_buffer_size:
18384 * @stream: a #GBufferedOutputStream.
18386 * Gets the size of the buffer in the @stream.
18388 * Returns: the current size of the buffer.
18393 * g_buffered_output_stream_new:
18394 * @base_stream: a #GOutputStream.
18396 * Creates a new buffered output stream for a base stream.
18398 * Returns: a #GOutputStream for the given @base_stream.
18403 * g_buffered_output_stream_new_sized:
18404 * @base_stream: a #GOutputStream.
18407 * Creates a new buffered output stream with a given buffer size.
18409 * Returns: a #GOutputStream with an internal buffer set to @size.
18414 * g_buffered_output_stream_set_auto_grow:
18415 * @stream: a #GBufferedOutputStream.
18416 * @auto_grow: a #gboolean.
18418 * Sets whether or not the @stream's buffer should automatically grow.
18419 * If @auto_grow is true, then each write will just make the buffer
18420 * larger, and you must manually flush the buffer to actually write out
18421 * the data to the underlying stream.
18426 * g_buffered_output_stream_set_buffer_size:
18427 * @stream: a #GBufferedOutputStream.
18430 * Sets the size of the internal buffer to @size.
18436 * @bus_type: A #GBusType.
18437 * @cancellable: A #GCancellable or %NULL.
18438 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
18439 * @user_data: The data to pass to @callback.
18441 * Asynchronously connects to the message bus specified by @bus_type.
18443 * When the operation is finished, @callback will be invoked. You can
18444 * then call g_bus_get_finish() to get the result of the operation.
18446 * This is a asynchronous failable function. See g_bus_get_sync() for
18447 * the synchronous version.
18454 * g_bus_get_finish:
18455 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get().
18456 * @error: Return location for error or %NULL.
18458 * Finishes an operation started with g_bus_get().
18460 * The returned object is a singleton, that is, shared with other
18461 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
18462 * event that you need a private message bus connection, use
18463 * g_dbus_address_get_for_bus_sync() and
18464 * g_dbus_connection_new_for_address().
18466 * Note that the returned #GDBusConnection object will (usually) have
18467 * the #GDBusConnection:exit-on-close property set to %TRUE.
18469 * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
18476 * @bus_type: A #GBusType.
18477 * @cancellable: A #GCancellable or %NULL.
18478 * @error: Return location for error or %NULL.
18480 * Synchronously connects to the message bus specified by @bus_type.
18481 * Note that the returned object may shared with other callers,
18482 * e.g. if two separate parts of a process calls this function with
18483 * the same @bus_type, they will share the same object.
18485 * This is a synchronous failable function. See g_bus_get() and
18486 * g_bus_get_finish() for the asynchronous version.
18488 * The returned object is a singleton, that is, shared with other
18489 * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the
18490 * event that you need a private message bus connection, use
18491 * g_dbus_address_get_for_bus_sync() and
18492 * g_dbus_connection_new_for_address().
18494 * Note that the returned #GDBusConnection object will (usually) have
18495 * the #GDBusConnection:exit-on-close property set to %TRUE.
18497 * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
18504 * @bus_type: The type of bus to own a name on.
18505 * @name: The well-known name to own.
18506 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
18507 * @bus_acquired_handler: Handler to invoke when connected to the bus of type @bus_type or %NULL.
18508 * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL.
18509 * @name_lost_handler: Handler to invoke when @name is lost or %NULL.
18510 * @user_data: User data to pass to handlers.
18511 * @user_data_free_func: Function for freeing @user_data or %NULL.
18513 * Starts acquiring @name on the bus specified by @bus_type and calls
18514 * @name_acquired_handler and @name_lost_handler when the name is
18515 * acquired respectively lost. Callbacks will be invoked in the <link
18516 * linkend="g-main-context-push-thread-default">thread-default main
18517 * loop</link> of the thread you are calling this function from.
18519 * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
18520 * callbacks will be invoked after calling this function - there are three
18524 * @name_lost_handler with a %NULL connection (if a connection to the bus can't be made).
18525 * </para></listitem>
18527 * @bus_acquired_handler then @name_lost_handler (if the name can't be obtained)
18528 * </para></listitem>
18530 * @bus_acquired_handler then @name_acquired_handler (if the name was obtained).
18531 * </para></listitem>
18533 * When you are done owning the name, just call g_bus_unown_name()
18534 * with the owner id this function returns.
18536 * If the name is acquired or lost (for example another application
18537 * could acquire the name if you allow replacement or the application
18538 * currently owning the name exits), the handlers are also invoked. If the
18539 * #GDBusConnection that is used for attempting to own the name
18540 * closes, then @name_lost_handler is invoked since it is no
18541 * longer possible for other processes to access the process.
18543 * You cannot use g_bus_own_name() several times for the same name (unless
18544 * interleaved with calls to g_bus_unown_name()) - only the first call
18547 * Another guarantee is that invocations of @name_acquired_handler
18548 * and @name_lost_handler are guaranteed to alternate; that
18549 * is, if @name_acquired_handler is invoked then you are
18550 * guaranteed that the next time one of the handlers is invoked, it
18551 * will be @name_lost_handler. The reverse is also true.
18553 * If you plan on exporting objects (using e.g.
18554 * g_dbus_connection_register_object()), note that it is generally too late
18555 * to export the objects in @name_acquired_handler. Instead, you can do this
18556 * in @bus_acquired_handler since you are guaranteed that this will run
18557 * before @name is requested from the bus.
18559 * This behavior makes it very simple to write applications that wants
18560 * to own names and export objects, see <xref linkend="gdbus-owning-names"/>.
18561 * Simply register objects to be exported in @bus_acquired_handler and
18562 * unregister the objects (if any) in @name_lost_handler.
18564 * g_bus_unown_name() to stop owning the name.
18566 * Returns: An identifier (never 0) that an be used with
18572 * g_bus_own_name_on_connection:
18573 * @connection: A #GDBusConnection.
18574 * @name: The well-known name to own.
18575 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
18576 * @name_acquired_handler: Handler to invoke when @name is acquired or %NULL.
18577 * @name_lost_handler: Handler to invoke when @name is lost or %NULL.
18578 * @user_data: User data to pass to handlers.
18579 * @user_data_free_func: Function for freeing @user_data or %NULL.
18581 * Like g_bus_own_name() but takes a #GDBusConnection instead of a
18584 * g_bus_unown_name() to stop owning the name.
18586 * Returns: An identifier (never 0) that an be used with
18592 * g_bus_own_name_on_connection_with_closures:
18593 * @connection: A #GDBusConnection.
18594 * @name: The well-known name to own.
18595 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
18596 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL.
18597 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL.
18599 * Version of g_bus_own_name_on_connection() using closures instead of callbacks for
18600 * easier binding in other languages.
18602 * g_bus_unown_name() to stop owning the name.
18604 * Returns: An identifier (never 0) that an be used with
18605 * Rename to: g_bus_own_name_on_connection
18611 * g_bus_own_name_with_closures:
18612 * @bus_type: The type of bus to own a name on.
18613 * @name: The well-known name to own.
18614 * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
18615 * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to the bus of type @bus_type or %NULL.
18616 * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL.
18617 * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL.
18619 * Version of g_bus_own_name() using closures instead of callbacks for
18620 * easier binding in other languages.
18622 * g_bus_unown_name() to stop owning the name.
18624 * Returns: An identifier (never 0) that an be used with
18625 * Rename to: g_bus_own_name
18631 * g_bus_unown_name:
18632 * @owner_id: An identifier obtained from g_bus_own_name()
18634 * Stops owning a name.
18641 * g_bus_unwatch_name:
18642 * @watcher_id: An identifier obtained from g_bus_watch_name()
18644 * Stops watching a name.
18651 * g_bus_watch_name:
18652 * @bus_type: The type of bus to watch a name on.
18653 * @name: The name (well-known or unique) to watch.
18654 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
18655 * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
18656 * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
18657 * @user_data: User data to pass to handlers.
18658 * @user_data_free_func: Function for freeing @user_data or %NULL.
18660 * Starts watching @name on the bus specified by @bus_type and calls
18661 * @name_appeared_handler and @name_vanished_handler when the name is
18662 * known to have a owner respectively known to lose its
18663 * owner. Callbacks will be invoked in the <link
18664 * linkend="g-main-context-push-thread-default">thread-default main
18665 * loop</link> of the thread you are calling this function from.
18667 * You are guaranteed that one of the handlers will be invoked after
18668 * calling this function. When you are done watching the name, just
18669 * call g_bus_unwatch_name() with the watcher id this function
18672 * If the name vanishes or appears (for example the application owning
18673 * the name could restart), the handlers are also invoked. If the
18674 * #GDBusConnection that is used for watching the name disconnects, then
18675 * @name_vanished_handler is invoked since it is no longer
18676 * possible to access the name.
18678 * Another guarantee is that invocations of @name_appeared_handler
18679 * and @name_vanished_handler are guaranteed to alternate; that
18680 * is, if @name_appeared_handler is invoked then you are
18681 * guaranteed that the next time one of the handlers is invoked, it
18682 * will be @name_vanished_handler. The reverse is also true.
18684 * This behavior makes it very simple to write applications that wants
18685 * to take action when a certain name exists, see <xref
18686 * linkend="gdbus-watching-names"/>. Basically, the application
18687 * should create object proxies in @name_appeared_handler and destroy
18688 * them again (if any) in @name_vanished_handler.
18690 * g_bus_unwatch_name() to stop watching the name.
18692 * Returns: An identifier (never 0) that an be used with
18698 * g_bus_watch_name_on_connection:
18699 * @connection: A #GDBusConnection.
18700 * @name: The name (well-known or unique) to watch.
18701 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
18702 * @name_appeared_handler: Handler to invoke when @name is known to exist or %NULL.
18703 * @name_vanished_handler: Handler to invoke when @name is known to not exist or %NULL.
18704 * @user_data: User data to pass to handlers.
18705 * @user_data_free_func: Function for freeing @user_data or %NULL.
18707 * Like g_bus_watch_name() but takes a #GDBusConnection instead of a
18710 * g_bus_unwatch_name() to stop watching the name.
18712 * Returns: An identifier (never 0) that an be used with
18718 * g_bus_watch_name_on_connection_with_closures:
18719 * @connection: A #GDBusConnection.
18720 * @name: The name (well-known or unique) to watch.
18721 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
18722 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL.
18723 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL.
18725 * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
18726 * easier binding in other languages.
18728 * g_bus_unwatch_name() to stop watching the name.
18730 * Returns: An identifier (never 0) that an be used with
18731 * Rename to: g_bus_watch_name_on_connection
18737 * g_bus_watch_name_with_closures:
18738 * @bus_type: The type of bus to watch a name on.
18739 * @name: The name (well-known or unique) to watch.
18740 * @flags: Flags from the #GBusNameWatcherFlags enumeration.
18741 * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL.
18742 * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL.
18744 * Version of g_bus_watch_name() using closures instead of callbacks for
18745 * easier binding in other languages.
18747 * g_bus_unwatch_name() to stop watching the name.
18749 * Returns: An identifier (never 0) that an be used with
18750 * Rename to: g_bus_watch_name
18756 * g_cancellable_cancel:
18757 * @cancellable: a #GCancellable object.
18759 * Will set @cancellable to cancelled, and will emit the
18760 * #GCancellable::cancelled signal. (However, see the warning about
18761 * race conditions in the documentation for that signal if you are
18762 * planning to connect to it.)
18764 * This function is thread-safe. In other words, you can safely call
18765 * it from a thread other than the one running the operation that was
18766 * passed the @cancellable.
18768 * The convention within gio is that cancelling an asynchronous
18769 * operation causes it to complete asynchronously. That is, if you
18770 * cancel the operation from the same thread in which it is running,
18771 * then the operation's #GAsyncReadyCallback will not be invoked until
18772 * the application returns to the main loop.
18777 * g_cancellable_connect:
18778 * @cancellable: A #GCancellable.
18779 * @callback: The #GCallback to connect.
18780 * @data: Data to pass to @callback.
18781 * @data_destroy_func: Free function for @data or %NULL.
18783 * Convenience function to connect to the #GCancellable::cancelled
18784 * signal. Also handles the race condition that may happen
18785 * if the cancellable is cancelled right before connecting.
18787 * @callback is called at most once, either directly at the
18788 * time of the connect if @cancellable is already cancelled,
18789 * or when @cancellable is cancelled in some thread.
18791 * @data_destroy_func will be called when the handler is
18792 * disconnected, or immediately if the cancellable is already
18795 * See #GCancellable::cancelled for details on how to use this.
18799 * Returns: The id of the signal handler or 0 if @cancellable has already
18805 * g_cancellable_disconnect:
18806 * @cancellable: A #GCancellable or %NULL.
18807 * @handler_id: Handler id of the handler to be disconnected, or %0.
18809 * Disconnects a handler from a cancellable instance similar to
18810 * g_signal_handler_disconnect(). Additionally, in the event that a
18811 * signal handler is currently running, this call will block until the
18812 * handler has finished. Calling this function from a
18813 * #GCancellable::cancelled signal handler will therefore result in a
18816 * This avoids a race condition where a thread cancels at the
18817 * same time as the cancellable operation is finished and the
18818 * signal handler is removed. See #GCancellable::cancelled for
18819 * details on how to use this.
18821 * If @cancellable is %NULL or @handler_id is %0 this function does
18829 * g_cancellable_get_current:
18831 * Gets the top cancellable from the stack.
18833 * if the stack is empty.
18835 * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
18840 * g_cancellable_get_fd:
18841 * @cancellable: a #GCancellable.
18843 * Gets the file descriptor for a cancellable job. This can be used to
18844 * implement cancellable operations on Unix systems. The returned fd will
18845 * turn readable when @cancellable is cancelled.
18847 * You are not supposed to read from the fd yourself, just check for
18848 * readable status. Reading to unset the readable status is done
18849 * with g_cancellable_reset().
18851 * After a successful return from this function, you should use
18852 * g_cancellable_release_fd() to free up resources allocated for
18853 * the returned file descriptor.
18855 * See also g_cancellable_make_pollfd().
18857 * is not supported, or on errors.
18859 * Returns: A valid file descriptor. %-1 if the file descriptor
18864 * g_cancellable_is_cancelled:
18865 * @cancellable: (allow-none): a #GCancellable or %NULL
18867 * Checks if a cancellable job has been cancelled.
18869 * FALSE if called with %NULL or if item is not cancelled.
18871 * Returns: %TRUE if @cancellable is cancelled,
18876 * g_cancellable_make_pollfd:
18877 * @cancellable: a #GCancellable or %NULL
18878 * @pollfd: a pointer to a #GPollFD
18880 * Creates a #GPollFD corresponding to @cancellable; this can be passed
18881 * to g_poll() and used to poll for cancellation. This is useful both
18882 * for unix systems without a native poll and for portability to
18885 * When this function returns %TRUE, you should use
18886 * g_cancellable_release_fd() to free up resources allocated for the
18887 * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
18889 * If this function returns %FALSE, either no @cancellable was given or
18890 * resource limits prevent this function from allocating the necessary
18891 * structures for polling. (On Linux, you will likely have reached
18892 * the maximum number of file descriptors.) The suggested way to handle
18893 * these cases is to ignore the @cancellable.
18895 * You are not supposed to read from the fd yourself, just check for
18896 * readable status. Reading to unset the readable status is done
18897 * with g_cancellable_reset().
18899 * failure to prepare the cancellable.
18901 * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
18907 * g_cancellable_new:
18909 * Creates a new #GCancellable object.
18911 * Applications that want to start one or more operations
18912 * that should be cancellable should create a #GCancellable
18913 * and pass it to the operations.
18915 * One #GCancellable can be used in multiple consecutive
18916 * operations or in multiple concurrent operations.
18918 * Returns: a #GCancellable.
18923 * g_cancellable_pop_current:
18924 * @cancellable: a #GCancellable object
18926 * Pops @cancellable off the cancellable stack (verifying that @cancellable
18927 * is on the top of the stack).
18932 * g_cancellable_push_current:
18933 * @cancellable: a #GCancellable object
18935 * Pushes @cancellable onto the cancellable stack. The current
18936 * cancellable can then be received using g_cancellable_get_current().
18938 * This is useful when implementing cancellable operations in
18939 * code that does not allow you to pass down the cancellable object.
18941 * This is typically called automatically by e.g. #GFile operations,
18942 * so you rarely have to call this yourself.
18947 * g_cancellable_release_fd:
18948 * @cancellable: a #GCancellable
18950 * Releases a resources previously allocated by g_cancellable_get_fd()
18951 * or g_cancellable_make_pollfd().
18953 * For compatibility reasons with older releases, calling this function
18954 * is not strictly required, the resources will be automatically freed
18955 * when the @cancellable is finalized. However, the @cancellable will
18956 * block scarce file descriptors until it is finalized if this function
18957 * is not called. This can cause the application to run out of file
18958 * descriptors when many #GCancellables are used at the same time.
18965 * g_cancellable_reset:
18966 * @cancellable: a #GCancellable object.
18968 * Resets @cancellable to its uncancelled state.
18970 * If cancellable is currently in use by any cancellable operation
18971 * then the behavior of this function is undefined.
18976 * g_cancellable_set_error_if_cancelled:
18977 * @cancellable: (allow-none): a #GCancellable or %NULL
18978 * @error: #GError to append error state to
18980 * If the @cancellable is cancelled, sets the error to notify
18981 * that the operation was cancelled.
18983 * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not
18988 * g_cancellable_source_new: (skip)
18989 * @cancellable: a #GCancellable, or %NULL
18991 * Creates a source that triggers if @cancellable is cancelled and
18992 * calls its callback of type #GCancellableSourceFunc. This is
18993 * primarily useful for attaching to another (non-cancellable) source
18994 * with g_source_add_child_source() to add cancellability to it.
18996 * For convenience, you can call this with a %NULL #GCancellable,
18997 * in which case the source will never trigger.
18999 * Returns: (transfer full): the new #GSource.
19005 * g_charset_converter_get_num_fallbacks:
19006 * @converter: a #GCharsetConverter
19008 * Gets the number of fallbacks that @converter has applied so far.
19010 * Returns: the number of fallbacks that @converter has applied
19016 * g_charset_converter_get_use_fallback:
19017 * @converter: a #GCharsetConverter
19019 * Gets the #GCharsetConverter:use-fallback property.
19021 * Returns: %TRUE if fallbacks are used by @converter
19027 * g_charset_converter_new:
19028 * @to_charset: destination charset
19029 * @from_charset: source charset
19030 * @error: #GError for error reporting, or %NULL to ignore.
19032 * Creates a new #GCharsetConverter.
19034 * Returns: a new #GCharsetConverter or %NULL on error.
19040 * g_charset_converter_set_use_fallback:
19041 * @converter: a #GCharsetConverter
19042 * @use_fallback: %TRUE to use fallbacks
19044 * Sets the #GCharsetConverter:use-fallback property.
19051 * g_content_type_can_be_executable:
19052 * @type: a content type string
19054 * Checks if a content type can be executable. Note that for instance
19055 * things like text files can be executables (i.e. scripts and batch files).
19057 * can be executable, %FALSE otherwise.
19059 * Returns: %TRUE if the file type corresponds to a type that
19064 * g_content_type_equals:
19065 * @type1: a content type string
19066 * @type2: a content type string
19068 * Compares two content types for equality.
19070 * %FALSE otherwise.
19072 * Returns: %TRUE if the two strings are identical or equivalent,
19077 * g_content_type_from_mime_type:
19078 * @mime_type: a mime type string
19080 * Tries to find a content type based on the mime type name.
19082 * or %NULL. Free with g_free()
19084 * Returns: (allow-none): Newly allocated string with content type
19090 * g_content_type_get_description:
19091 * @type: a content type string
19093 * Gets the human readable description of the content type.
19095 * returned string with g_free()
19097 * Returns: a short description of the content type @type. Free the
19102 * g_content_type_get_icon:
19103 * @type: a content type string
19105 * Gets the icon for a content type.
19107 * object with g_object_unref()
19109 * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
19114 * g_content_type_get_mime_type:
19115 * @type: a content type string
19117 * Gets the mime type for the content type, if one is registered.
19119 * or %NULL if unknown.
19121 * Returns: (allow-none): the registered mime type for the given @type,
19126 * g_content_type_guess:
19127 * @filename: (allow-none): a string, or %NULL
19128 * @data: (allow-none) (array length=data_size): a stream of data, or %NULL
19129 * @data_size: the size of @data
19130 * @result_uncertain: (allow-none) (out): return location for the certainty of the result, or %NULL
19132 * Guesses the content type based on example data. If the function is
19133 * uncertain, @result_uncertain will be set to %TRUE. Either @filename
19134 * or @data may be %NULL, in which case the guess will be based solely
19135 * on the other argument.
19137 * given data. Free with g_free()
19139 * Returns: a string indicating a guessed content type for the
19144 * g_content_type_guess_for_tree:
19145 * @root: the root of the tree to guess a type for
19147 * Tries to guess the type of the tree with root @root, by
19148 * looking at the files it contains. The result is an array
19149 * of content types, with the best guess coming first.
19151 * The types returned all have the form x-content/foo, e.g.
19152 * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
19153 * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
19154 * specification for more on x-content types.
19156 * This function is useful in the implementation of
19157 * g_mount_guess_content_type().
19159 * array of zero or more content types. Free with g_strfreev()
19161 * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
19167 * g_content_type_is_a:
19168 * @type: a content type string
19169 * @supertype: a content type string
19171 * Determines if @type is a subset of @supertype.
19173 * %FALSE otherwise.
19175 * Returns: %TRUE if @type is a kind of @supertype,
19180 * g_content_type_is_unknown:
19181 * @type: a content type string
19183 * Checks if the content type is the generic "unknown" type.
19184 * On UNIX this is the "application/octet-stream" mimetype,
19185 * while on win32 it is "*".
19187 * Returns: %TRUE if the type is the unknown type.
19192 * g_content_types_get_registered:
19194 * Gets a list of strings containing all the registered content types
19195 * known to the system. The list and its data should be freed using
19197 * g_list_free_full (list, g_free);
19198 * </programlisting>
19200 * Returns: (element-type utf8) (transfer full): #GList of the registered content types
19205 * g_converter_convert:
19206 * @converter: a #GConverter.
19207 * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer containing the data to convert.
19208 * @inbuf_size: the number of bytes in @inbuf
19209 * @outbuf: a buffer to write converted data in.
19210 * @outbuf_size: the number of bytes in @outbuf, must be at least one
19211 * @flags: a #GConverterFlags controlling the conversion details
19212 * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
19213 * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
19214 * @error: location to store the error occurring, or %NULL to ignore
19216 * This is the main operation used when converting data. It is to be called
19217 * multiple times in a loop, and each time it will do some work, i.e.
19218 * producing some output (in @outbuf) or consuming some input (from @inbuf) or
19219 * both. If its not possible to do any work an error is returned.
19221 * Note that a single call may not consume all input (or any input at all).
19222 * Also a call may produce output even if given no input, due to state stored
19223 * in the converter producing output.
19225 * If any data was either produced or consumed, and then an error happens, then
19226 * only the successful conversion is reported and the error is returned on the
19229 * A full conversion loop involves calling this method repeatedly, each time
19230 * giving it new input and space output space. When there is no more input
19231 * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
19232 * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
19233 * each time until all data is consumed and all output is produced, then
19234 * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
19235 * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
19236 * in a decompression converter where the end of data is detectable from the
19237 * data (and there might even be other data after the end of the compressed data).
19239 * When some data has successfully been converted @bytes_read and is set to
19240 * the number of bytes read from @inbuf, and @bytes_written is set to indicate
19241 * how many bytes was written to @outbuf. If there are more data to output
19242 * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
19243 * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
19244 * then %G_CONVERTER_FINISHED is returned.
19246 * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
19247 * Some errors need special handling:
19249 * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
19250 * to write the resulting converted data, the application should
19251 * call the function again with a larger @outbuf to continue.
19253 * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
19254 * input to fully determine what the conversion should produce,
19255 * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
19256 * example with an incomplete multibyte sequence when converting text,
19257 * or when a regexp matches up to the end of the input (and may match
19258 * further input). It may also happen when @inbuf_size is zero and
19259 * there is no more data to produce.
19261 * When this happens the application should read more input and then
19262 * call the function again. If further input shows that there is no
19263 * more data call the function again with the same data but with
19264 * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
19265 * to finish as e.g. in the regexp match case (or, to fail again with
19266 * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
19267 * input is actually partial).
19269 * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
19270 * converter object is in an invalid state where its not allowed
19271 * to call g_converter_convert() anymore. At this time you can only
19272 * free the object or call g_converter_reset() to reset it to the
19275 * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
19276 * to try to write out all internal state to the output. The application
19277 * has to call the function multiple times with the flag set, and when
19278 * the available input has been consumed and all internal state has
19279 * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
19280 * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
19281 * This is somewhat similar to what happens at the end of the input stream,
19282 * but done in the middle of the data.
19284 * This has different meanings for different conversions. For instance
19285 * in a compression converter it would mean that we flush all the
19286 * compression state into output such that if you uncompress the
19287 * compressed data you get back all the input data. Doing this may
19288 * make the final file larger due to padding though. Another example
19289 * is a regexp conversion, where if you at the end of the flushed data
19290 * have a match, but there is also a potential longer match. In the
19291 * non-flushed case we would ask for more input, but when flushing we
19292 * treat this as the end of input and do the match.
19294 * Flushing is not always possible (like if a charset converter flushes
19295 * at a partial multibyte sequence). Converters are supposed to try
19296 * to produce as much output as possible and then return an error
19297 * (typically %G_IO_ERROR_PARTIAL_INPUT).
19299 * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
19305 * g_converter_input_stream_get_converter:
19306 * @converter_stream: a #GConverterInputStream
19308 * Gets the #GConverter that is used by @converter_stream.
19310 * Returns: (transfer none): the converter of the converter input stream
19316 * g_converter_input_stream_new:
19317 * @base_stream: a #GInputStream
19318 * @converter: a #GConverter
19320 * Creates a new converter input stream for the @base_stream.
19322 * Returns: a new #GInputStream.
19327 * g_converter_output_stream_get_converter:
19328 * @converter_stream: a #GConverterOutputStream
19330 * Gets the #GConverter that is used by @converter_stream.
19332 * Returns: (transfer none): the converter of the converter output stream
19338 * g_converter_output_stream_new:
19339 * @base_stream: a #GOutputStream
19340 * @converter: a #GConverter
19342 * Creates a new converter output stream for the @base_stream.
19344 * Returns: a new #GOutputStream.
19349 * g_converter_reset:
19350 * @converter: a #GConverter.
19352 * Resets all internal state in the converter, making it behave
19353 * as if it was just created. If the converter has any internal
19354 * state that would produce output then that output is lost.
19361 * g_credentials_get_native: (skip)
19362 * @credentials: A #GCredentials.
19363 * @native_type: The type of native credentials to get.
19365 * Gets a pointer to native credentials of type @native_type from
19368 * It is a programming error (which will cause an warning to be
19369 * logged) to use this method if there is no #GCredentials support for
19370 * the OS or if @native_type isn't supported by the OS.
19372 * operation there is no #GCredentials support for the OS or if
19373 * @native_type isn't supported by the OS. Do not free the returned
19374 * data, it is owned by @credentials.
19376 * Returns: The pointer to native credentials or %NULL if the
19382 * g_credentials_get_unix_user:
19383 * @credentials: A #GCredentials
19384 * @error: Return location for error or %NULL.
19386 * Tries to get the UNIX user identifier from @credentials. This
19387 * method is only available on UNIX platforms.
19389 * This operation can fail if #GCredentials is not supported on the
19390 * OS or if the native credentials type does not contain information
19391 * about the UNIX user.
19393 * Returns: The UNIX user identifier or -1 if @error is set.
19399 * g_credentials_is_same_user:
19400 * @credentials: A #GCredentials.
19401 * @other_credentials: A #GCredentials.
19402 * @error: Return location for error or %NULL.
19404 * Checks if @credentials and @other_credentials is the same user.
19406 * This operation can fail if #GCredentials is not supported on the
19409 * user, %FALSE otherwise or if @error is set.
19411 * Returns: %TRUE if @credentials and @other_credentials has the same
19417 * g_credentials_new:
19419 * Creates a new #GCredentials object with credentials matching the
19420 * the current process.
19422 * Returns: A #GCredentials. Free with g_object_unref().
19428 * g_credentials_set_native:
19429 * @credentials: A #GCredentials.
19430 * @native_type: The type of native credentials to set.
19431 * @native: A pointer to native credentials.
19433 * Copies the native credentials of type @native_type from @native
19434 * into @credentials.
19436 * It is a programming error (which will cause an warning to be
19437 * logged) to use this method if there is no #GCredentials support for
19438 * the OS or if @native_type isn't supported by the OS.
19445 * g_credentials_set_unix_user:
19446 * @credentials: A #GCredentials.
19447 * @uid: The UNIX user identifier to set.
19448 * @error: Return location for error or %NULL.
19450 * Tries to set the UNIX user identifier on @credentials. This method
19451 * is only available on UNIX platforms.
19453 * This operation can fail if #GCredentials is not supported on the
19454 * OS or if the native credentials type does not contain information
19455 * about the UNIX user.
19457 * Returns: %TRUE if @uid was set, %FALSE if error is set.
19463 * g_credentials_to_string:
19464 * @credentials: A #GCredentials object.
19466 * Creates a human-readable textual representation of @credentials
19467 * that can be used in logging and debug messages. The format of the
19468 * returned string may change in future GLib release.
19470 * Returns: A string that should be freed with g_free().
19476 * g_data_input_stream_get_byte_order:
19477 * @stream: a given #GDataInputStream.
19479 * Gets the byte order for the data input stream.
19481 * Returns: the @stream's current #GDataStreamByteOrder.
19486 * g_data_input_stream_get_newline_type:
19487 * @stream: a given #GDataInputStream.
19489 * Gets the current newline type for the @stream.
19491 * Returns: #GDataStreamNewlineType for the given @stream.
19496 * g_data_input_stream_new:
19497 * @base_stream: a #GInputStream.
19499 * Creates a new data input stream for the @base_stream.
19501 * Returns: a new #GDataInputStream.
19506 * g_data_input_stream_read_byte:
19507 * @stream: a given #GDataInputStream.
19508 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19509 * @error: #GError for error reporting.
19511 * Reads an unsigned 8-bit/1-byte value from @stream.
19513 * if an error occurred.
19515 * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
19520 * g_data_input_stream_read_int16:
19521 * @stream: a given #GDataInputStream.
19522 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19523 * @error: #GError for error reporting.
19525 * Reads a 16-bit/2-byte value from @stream.
19527 * In order to get the correct byte order for this read operation,
19528 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
19530 * an error occurred.
19532 * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
19537 * g_data_input_stream_read_int32:
19538 * @stream: a given #GDataInputStream.
19539 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19540 * @error: #GError for error reporting.
19542 * Reads a signed 32-bit/4-byte value from @stream.
19544 * In order to get the correct byte order for this read operation,
19545 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
19547 * If @cancellable is not %NULL, then the operation can be cancelled by
19548 * triggering the cancellable object from another thread. If the operation
19549 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19551 * an error occurred.
19553 * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
19558 * g_data_input_stream_read_int64:
19559 * @stream: a given #GDataInputStream.
19560 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19561 * @error: #GError for error reporting.
19563 * Reads a 64-bit/8-byte value from @stream.
19565 * In order to get the correct byte order for this read operation,
19566 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
19568 * If @cancellable is not %NULL, then the operation can be cancelled by
19569 * triggering the cancellable object from another thread. If the operation
19570 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19572 * an error occurred.
19574 * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
19579 * g_data_input_stream_read_line:
19580 * @stream: a given #GDataInputStream.
19581 * @length: (out): a #gsize to get the length of the data read in.
19582 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19583 * @error: #GError for error reporting.
19585 * Reads a line from the data input stream. Note that no encoding
19586 * checks or conversion is performed; the input is not guaranteed to
19587 * be UTF-8, and may in fact have embedded NUL characters.
19589 * If @cancellable is not %NULL, then the operation can be cancelled by
19590 * triggering the cancellable object from another thread. If the operation
19591 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19593 * NUL terminated byte array with the line that was read in (without
19594 * the newlines). Set @length to a #gsize to get the length of the
19595 * read line. On an error, it will return %NULL and @error will be
19596 * set. If there's no content to read, it will still return %NULL,
19597 * but @error won't be set.
19599 * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
19604 * g_data_input_stream_read_line_async:
19605 * @stream: a given #GDataInputStream.
19606 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
19607 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19608 * @callback: (scope async): callback to call when the request is satisfied.
19609 * @user_data: (closure): the data to pass to callback function.
19611 * The asynchronous version of g_data_input_stream_read_line(). It is
19612 * an error to have two outstanding calls to this function.
19614 * When the operation is finished, @callback will be called. You
19615 * can then call g_data_input_stream_read_line_finish() to get
19616 * the result of the operation.
19623 * g_data_input_stream_read_line_finish:
19624 * @stream: a given #GDataInputStream.
19625 * @result: the #GAsyncResult that was provided to the callback.
19626 * @length: (out): a #gsize to get the length of the data read in.
19627 * @error: #GError for error reporting.
19629 * Finish an asynchronous call started by
19630 * g_data_input_stream_read_line_async(). Note the warning about
19631 * string encoding in g_data_input_stream_read_line() applies here as
19634 * NUL-terminated byte array with the line that was read in
19635 * (without the newlines). Set @length to a #gsize to get the
19636 * length of the read line. On an error, it will return %NULL and
19637 * @error will be set. If there's no content to read, it will
19638 * still return %NULL, but @error won't be set.
19640 * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
19646 * g_data_input_stream_read_line_finish_utf8:
19647 * @stream: a given #GDataInputStream.
19648 * @result: the #GAsyncResult that was provided to the callback.
19649 * @length: (out): a #gsize to get the length of the data read in.
19650 * @error: #GError for error reporting.
19652 * Finish an asynchronous call started by
19653 * g_data_input_stream_read_line_async().
19655 * (without the newlines). Set @length to a #gsize to get the length
19656 * of the read line. On an error, it will return %NULL and @error
19657 * will be set. For UTF-8 conversion errors, the set error domain is
19658 * %G_CONVERT_ERROR. If there's no content to read, it will still
19659 * return %NULL, but @error won't be set.
19661 * Returns: (transfer full): a string with the line that was read in
19667 * g_data_input_stream_read_line_utf8:
19668 * @stream: a given #GDataInputStream.
19669 * @length: (out): a #gsize to get the length of the data read in.
19670 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19671 * @error: #GError for error reporting.
19673 * Reads a UTF-8 encoded line from the data input stream.
19675 * If @cancellable is not %NULL, then the operation can be cancelled by
19676 * triggering the cancellable object from another thread. If the operation
19677 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19679 * line that was read in (without the newlines). Set @length to a
19680 * #gsize to get the length of the read line. On an error, it will
19681 * return %NULL and @error will be set. For UTF-8 conversion errors,
19682 * the set error domain is %G_CONVERT_ERROR. If there's no content to
19683 * read, it will still return %NULL, but @error won't be set.
19685 * Returns: (transfer full): a NUL terminated UTF-8 string with the
19691 * g_data_input_stream_read_uint16:
19692 * @stream: a given #GDataInputStream.
19693 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19694 * @error: #GError for error reporting.
19696 * Reads an unsigned 16-bit/2-byte value from @stream.
19698 * In order to get the correct byte order for this read operation,
19699 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
19701 * an error occurred.
19703 * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
19708 * g_data_input_stream_read_uint32:
19709 * @stream: a given #GDataInputStream.
19710 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19711 * @error: #GError for error reporting.
19713 * Reads an unsigned 32-bit/4-byte value from @stream.
19715 * In order to get the correct byte order for this read operation,
19716 * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
19718 * If @cancellable is not %NULL, then the operation can be cancelled by
19719 * triggering the cancellable object from another thread. If the operation
19720 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19722 * an error occurred.
19724 * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
19729 * g_data_input_stream_read_uint64:
19730 * @stream: a given #GDataInputStream.
19731 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19732 * @error: #GError for error reporting.
19734 * Reads an unsigned 64-bit/8-byte value from @stream.
19736 * In order to get the correct byte order for this read operation,
19737 * see g_data_input_stream_get_byte_order().
19739 * If @cancellable is not %NULL, then the operation can be cancelled by
19740 * triggering the cancellable object from another thread. If the operation
19741 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
19743 * an error occurred.
19745 * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
19750 * g_data_input_stream_read_until:
19751 * @stream: a given #GDataInputStream.
19752 * @stop_chars: characters to terminate the read.
19753 * @length: (out): a #gsize to get the length of the data read in.
19754 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19755 * @error: #GError for error reporting.
19757 * Reads a string from the data input stream, up to the first
19758 * occurrence of any of the stop characters.
19760 * Note that, in contrast to g_data_input_stream_read_until_async(),
19761 * this function consumes the stop character that it finds.
19763 * Don't use this function in new code. Its functionality is
19764 * inconsistent with g_data_input_stream_read_until_async(). Both
19765 * functions will be marked as deprecated in a future release. Use
19766 * g_data_input_stream_read_upto() instead, but note that that function
19767 * does not consume the stop character.
19769 * before encountering any of the stop characters. Set @length to
19770 * a #gsize to get the length of the string. This function will
19771 * return %NULL on an error.
19773 * Returns: (transfer full): a string with the data that was read
19778 * g_data_input_stream_read_until_async:
19779 * @stream: a given #GDataInputStream.
19780 * @stop_chars: characters to terminate the read.
19781 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
19782 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19783 * @callback: (scope async): callback to call when the request is satisfied.
19784 * @user_data: (closure): the data to pass to callback function.
19786 * The asynchronous version of g_data_input_stream_read_until().
19787 * It is an error to have two outstanding calls to this function.
19789 * Note that, in contrast to g_data_input_stream_read_until(),
19790 * this function does not consume the stop character that it finds. You
19791 * must read it for yourself.
19793 * When the operation is finished, @callback will be called. You
19794 * can then call g_data_input_stream_read_until_finish() to get
19795 * the result of the operation.
19797 * Don't use this function in new code. Its functionality is
19798 * inconsistent with g_data_input_stream_read_until(). Both functions
19799 * will be marked as deprecated in a future release. Use
19800 * g_data_input_stream_read_upto_async() instead.
19807 * g_data_input_stream_read_until_finish:
19808 * @stream: a given #GDataInputStream.
19809 * @result: the #GAsyncResult that was provided to the callback.
19810 * @length: (out): a #gsize to get the length of the data read in.
19811 * @error: #GError for error reporting.
19813 * Finish an asynchronous call started by
19814 * g_data_input_stream_read_until_async().
19817 * before encountering any of the stop characters. Set @length to
19818 * a #gsize to get the length of the string. This function will
19819 * return %NULL on an error.
19822 * Returns: (transfer full): a string with the data that was read
19827 * g_data_input_stream_read_upto:
19828 * @stream: a #GDataInputStream
19829 * @stop_chars: characters to terminate the read
19830 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated
19831 * @length: (out): a #gsize to get the length of the data read in
19832 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19833 * @error: #GError for error reporting
19835 * Reads a string from the data input stream, up to the first
19836 * occurrence of any of the stop characters.
19838 * In contrast to g_data_input_stream_read_until(), this function
19839 * does <emphasis>not</emphasis> consume the stop character. You have
19840 * to use g_data_input_stream_read_byte() to get it before calling
19841 * g_data_input_stream_read_upto() again.
19843 * Note that @stop_chars may contain '\0' if @stop_chars_len is
19846 * before encountering any of the stop characters. Set @length to
19847 * a #gsize to get the length of the string. This function will
19848 * return %NULL on an error
19850 * Returns: (transfer full): a string with the data that was read
19856 * g_data_input_stream_read_upto_async:
19857 * @stream: a #GDataInputStream
19858 * @stop_chars: characters to terminate the read
19859 * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated
19860 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
19861 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
19862 * @callback: (scope async): callback to call when the request is satisfied
19863 * @user_data: (closure): the data to pass to callback function
19865 * The asynchronous version of g_data_input_stream_read_upto().
19866 * It is an error to have two outstanding calls to this function.
19868 * In contrast to g_data_input_stream_read_until(), this function
19869 * does <emphasis>not</emphasis> consume the stop character. You have
19870 * to use g_data_input_stream_read_byte() to get it before calling
19871 * g_data_input_stream_read_upto() again.
19873 * Note that @stop_chars may contain '\0' if @stop_chars_len is
19876 * When the operation is finished, @callback will be called. You
19877 * can then call g_data_input_stream_read_upto_finish() to get
19878 * the result of the operation.
19885 * g_data_input_stream_read_upto_finish:
19886 * @stream: a #GDataInputStream
19887 * @result: the #GAsyncResult that was provided to the callback
19888 * @length: (out): a #gsize to get the length of the data read in
19889 * @error: #GError for error reporting
19891 * Finish an asynchronous call started by
19892 * g_data_input_stream_read_upto_async().
19894 * Note that this function does <emphasis>not</emphasis> consume the
19895 * stop character. You have to use g_data_input_stream_read_byte() to
19896 * get it before calling g_data_input_stream_read_upto_async() again.
19898 * before encountering any of the stop characters. Set @length to
19899 * a #gsize to get the length of the string. This function will
19900 * return %NULL on an error.
19902 * Returns: (transfer full): a string with the data that was read
19908 * g_data_input_stream_set_byte_order:
19909 * @stream: a given #GDataInputStream.
19910 * @order: a #GDataStreamByteOrder to set.
19912 * This function sets the byte order for the given @stream. All subsequent
19913 * reads from the @stream will be read in the given @order.
19918 * g_data_input_stream_set_newline_type:
19919 * @stream: a #GDataInputStream.
19920 * @type: the type of new line return as #GDataStreamNewlineType.
19922 * Sets the newline type for the @stream.
19924 * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
19925 * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
19926 * "CR LF", and this might block if there is no more data available.
19931 * g_data_output_stream_get_byte_order:
19932 * @stream: a #GDataOutputStream.
19934 * Gets the byte order for the stream.
19936 * Returns: the #GDataStreamByteOrder for the @stream.
19941 * g_data_output_stream_new:
19942 * @base_stream: a #GOutputStream.
19944 * Creates a new data output stream for @base_stream.
19946 * Returns: #GDataOutputStream.
19951 * g_data_output_stream_put_byte:
19952 * @stream: a #GDataOutputStream.
19953 * @data: a #guchar.
19954 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19955 * @error: a #GError, %NULL to ignore.
19957 * Puts a byte into the output stream.
19959 * Returns: %TRUE if @data was successfully added to the @stream.
19964 * g_data_output_stream_put_int16:
19965 * @stream: a #GDataOutputStream.
19966 * @data: a #gint16.
19967 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19968 * @error: a #GError, %NULL to ignore.
19970 * Puts a signed 16-bit integer into the output stream.
19972 * Returns: %TRUE if @data was successfully added to the @stream.
19977 * g_data_output_stream_put_int32:
19978 * @stream: a #GDataOutputStream.
19979 * @data: a #gint32.
19980 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19981 * @error: a #GError, %NULL to ignore.
19983 * Puts a signed 32-bit integer into the output stream.
19985 * Returns: %TRUE if @data was successfully added to the @stream.
19990 * g_data_output_stream_put_int64:
19991 * @stream: a #GDataOutputStream.
19992 * @data: a #gint64.
19993 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
19994 * @error: a #GError, %NULL to ignore.
19996 * Puts a signed 64-bit integer into the stream.
19998 * Returns: %TRUE if @data was successfully added to the @stream.
20003 * g_data_output_stream_put_string:
20004 * @stream: a #GDataOutputStream.
20006 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20007 * @error: a #GError, %NULL to ignore.
20009 * Puts a string into the output stream.
20011 * Returns: %TRUE if @string was successfully added to the @stream.
20016 * g_data_output_stream_put_uint16:
20017 * @stream: a #GDataOutputStream.
20018 * @data: a #guint16.
20019 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20020 * @error: a #GError, %NULL to ignore.
20022 * Puts an unsigned 16-bit integer into the output stream.
20024 * Returns: %TRUE if @data was successfully added to the @stream.
20029 * g_data_output_stream_put_uint32:
20030 * @stream: a #GDataOutputStream.
20031 * @data: a #guint32.
20032 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20033 * @error: a #GError, %NULL to ignore.
20035 * Puts an unsigned 32-bit integer into the stream.
20037 * Returns: %TRUE if @data was successfully added to the @stream.
20042 * g_data_output_stream_put_uint64:
20043 * @stream: a #GDataOutputStream.
20044 * @data: a #guint64.
20045 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
20046 * @error: a #GError, %NULL to ignore.
20048 * Puts an unsigned 64-bit integer into the stream.
20050 * Returns: %TRUE if @data was successfully added to the @stream.
20055 * g_data_output_stream_set_byte_order:
20056 * @stream: a #GDataOutputStream.
20057 * @order: a %GDataStreamByteOrder.
20059 * Sets the byte order of the data output stream to @order.
20064 * g_dbus_action_group_get:
20065 * @connection: A #GDBusConnection
20066 * @bus_name: the bus name which exports the action group
20067 * @object_path: the object path at which the action group is exported
20069 * Obtains a #GDBusActionGroup for the action group which is exported at
20070 * the given @bus_name and @object_path.
20072 * The thread default main context is taken at the time of this call.
20073 * All signals on the menu model (and any linked models) are reported
20074 * with respect to this context. All calls on the returned menu model
20075 * (and linked models) must also originate from this same context, with
20076 * the thread default main context unchanged.
20078 * This call is non-blocking. The returned action group may or may not
20079 * already be filled in. The correct thing to do is connect the signals
20080 * for the action group to monitor for changes and then to call
20081 * g_action_group_list_actions() to get the initial list.
20083 * Returns: (transfer full): a #GDBusActionGroup
20089 * g_dbus_address_get_for_bus_sync:
20090 * @bus_type: A #GBusType.
20091 * @cancellable: A #GCancellable or %NULL.
20092 * @error: Return location for error or %NULL.
20094 * Synchronously looks up the D-Bus address for the well-known message
20095 * bus instance specified by @bus_type. This may involve using various
20096 * platform specific mechanisms.
20098 * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set.
20104 * g_dbus_address_get_stream:
20105 * @address: A valid D-Bus address.
20106 * @cancellable: A #GCancellable or %NULL.
20107 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
20108 * @user_data: Data to pass to @callback.
20110 * Asynchronously connects to an endpoint specified by @address and
20111 * sets up the connection so it is in a state to run the client-side
20112 * of the D-Bus authentication conversation.
20114 * When the operation is finished, @callback will be invoked. You can
20115 * then call g_dbus_address_get_stream_finish() to get the result of
20118 * This is an asynchronous failable function. See
20119 * g_dbus_address_get_stream_sync() for the synchronous version.
20126 * g_dbus_address_get_stream_finish:
20127 * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
20128 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
20129 * @error: Return location for error or %NULL.
20131 * Finishes an operation started with g_dbus_address_get_stream().
20133 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
20139 * g_dbus_address_get_stream_sync:
20140 * @address: A valid D-Bus address.
20141 * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
20142 * @cancellable: A #GCancellable or %NULL.
20143 * @error: Return location for error or %NULL.
20145 * Synchronously connects to an endpoint specified by @address and
20146 * sets up the connection so it is in a state to run the client-side
20147 * of the D-Bus authentication conversation.
20149 * This is a synchronous failable function. See
20150 * g_dbus_address_get_stream() for the asynchronous version.
20152 * Returns: (transfer full): A #GIOStream or %NULL if @error is set.
20158 * g_dbus_annotation_info_lookup:
20159 * @annotations: (array zero-terminated=1): A %NULL-terminated array of annotations or %NULL.
20160 * @name: The name of the annotation to look up.
20162 * Looks up the value of an annotation.
20164 * This cost of this function is O(n) in number of annotations.
20166 * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations.
20172 * g_dbus_annotation_info_ref:
20173 * @info: A #GDBusNodeInfo
20175 * If @info is statically allocated does nothing. Otherwise increases
20176 * the reference count.
20178 * Returns: The same @info.
20184 * g_dbus_annotation_info_unref:
20185 * @info: A #GDBusAnnotationInfo.
20187 * If @info is statically allocated, does nothing. Otherwise decreases
20188 * the reference count of @info. When its reference count drops to 0,
20189 * the memory used is freed.
20196 * g_dbus_arg_info_ref:
20197 * @info: A #GDBusArgInfo
20199 * If @info is statically allocated does nothing. Otherwise increases
20200 * the reference count.
20202 * Returns: The same @info.
20208 * g_dbus_arg_info_unref:
20209 * @info: A #GDBusArgInfo.
20211 * If @info is statically allocated, does nothing. Otherwise decreases
20212 * the reference count of @info. When its reference count drops to 0,
20213 * the memory used is freed.
20220 * g_dbus_auth_observer_authorize_authenticated_peer:
20221 * @observer: A #GDBusAuthObserver.
20222 * @stream: A #GIOStream for the #GDBusConnection.
20223 * @credentials: Credentials received from the peer or %NULL.
20225 * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer.
20227 * Returns: %TRUE if the peer is authorized, %FALSE if not.
20233 * g_dbus_auth_observer_new:
20235 * Creates a new #GDBusAuthObserver object.
20237 * Returns: A #GDBusAuthObserver. Free with g_object_unref().
20243 * g_dbus_connection_add_filter:
20244 * @connection: A #GDBusConnection.
20245 * @filter_function: A filter function.
20246 * @user_data: User data to pass to @filter_function.
20247 * @user_data_free_func: Function to free @user_data with when filter is removed or %NULL.
20249 * Adds a message filter. Filters are handlers that are run on all
20250 * incoming and outgoing messages, prior to standard dispatch. Filters
20251 * are run in the order that they were added. The same handler can be
20252 * added as a filter more than once, in which case it will be run more
20253 * than once. Filters added during a filter callback won't be run on
20254 * the message being processed. Filter functions are allowed to modify
20255 * and even drop messages.
20257 * Note that filters are run in a dedicated message handling thread so
20258 * they can't block and, generally, can't do anything but signal a
20259 * worker thread. Also note that filters are rarely needed - use API
20260 * such as g_dbus_connection_send_message_with_reply(),
20261 * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.
20263 * If a filter consumes an incoming message the message is not
20264 * dispatched anywhere else - not even the standard dispatch machinery
20265 * (that API such as g_dbus_connection_signal_subscribe() and
20266 * g_dbus_connection_send_message_with_reply() relies on) will see the
20267 * message. Similary, if a filter consumes an outgoing message, the
20268 * message will not be sent to the other peer.
20270 * g_dbus_connection_remove_filter().
20272 * Returns: A filter identifier that can be used with
20278 * g_dbus_connection_call:
20279 * @connection: A #GDBusConnection.
20280 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection.
20281 * @object_path: Path of remote object.
20282 * @interface_name: D-Bus interface to invoke method on.
20283 * @method_name: The name of the method to invoke.
20284 * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
20285 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
20286 * @flags: Flags from the #GDBusCallFlags enumeration.
20287 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
20288 * @cancellable: A #GCancellable or %NULL.
20289 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation.
20290 * @user_data: The data to pass to @callback.
20292 * Asynchronously invokes the @method_name method on the
20293 * @interface_name D-Bus interface on the remote object at
20294 * @object_path owned by @bus_name.
20296 * If @connection is closed then the operation will fail with
20297 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
20298 * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value
20299 * not compatible with the D-Bus protocol, the operation fails with
20300 * %G_IO_ERROR_INVALID_ARGUMENT.
20302 * If @reply_type is non-%NULL then the reply will be checked for having this type and an
20303 * error will be raised if it does not match. Said another way, if you give a @reply_type
20304 * then any non-%NULL return value will be of this type.
20306 * If the @parameters #GVariant is floating, it is consumed. This allows
20307 * convenient 'inline' use of g_variant_new(), e.g.:
20309 * g_dbus_connection_call (connection,
20310 * "org.freedesktop.StringThings",
20311 * "/org/freedesktop/StringThings",
20312 * "org.freedesktop.StringThings",
20314 * g_variant_new ("(ss)",
20318 * G_DBUS_CALL_FLAGS_NONE,
20321 * (GAsyncReadyCallback) two_strings_done,
20325 * This is an asynchronous method. When the operation is finished, @callback will be invoked
20326 * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
20327 * of the thread you are calling this method from. You can then call
20328 * g_dbus_connection_call_finish() to get the result of the operation.
20329 * See g_dbus_connection_call_sync() for the synchronous version of this
20332 * If @callback is %NULL then the D-Bus method call message will be sent with
20333 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
20340 * g_dbus_connection_call_finish:
20341 * @connection: A #GDBusConnection.
20342 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call().
20343 * @error: Return location for error or %NULL.
20345 * Finishes an operation started with g_dbus_connection_call().
20347 * return values. Free with g_variant_unref().
20349 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
20355 * g_dbus_connection_call_sync:
20356 * @connection: A #GDBusConnection.
20357 * @bus_name: A unique or well-known bus name.
20358 * @object_path: Path of remote object.
20359 * @interface_name: D-Bus interface to invoke method on.
20360 * @method_name: The name of the method to invoke.
20361 * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
20362 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
20363 * @flags: Flags from the #GDBusCallFlags enumeration.
20364 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
20365 * @cancellable: A #GCancellable or %NULL.
20366 * @error: Return location for error or %NULL.
20368 * Synchronously invokes the @method_name method on the
20369 * @interface_name D-Bus interface on the remote object at
20370 * @object_path owned by @bus_name.
20372 * If @connection is closed then the operation will fail with
20373 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the
20374 * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
20375 * contains a value not compatible with the D-Bus protocol, the operation
20376 * fails with %G_IO_ERROR_INVALID_ARGUMENT.
20377 * If @reply_type is non-%NULL then the reply will be checked for having
20378 * this type and an error will be raised if it does not match. Said
20379 * another way, if you give a @reply_type then any non-%NULL return
20380 * value will be of this type.
20382 * If the @parameters #GVariant is floating, it is consumed.
20383 * This allows convenient 'inline' use of g_variant_new(), e.g.:
20385 * g_dbus_connection_call_sync (connection,
20386 * "org.freedesktop.StringThings",
20387 * "/org/freedesktop/StringThings",
20388 * "org.freedesktop.StringThings",
20390 * g_variant_new ("(ss)",
20394 * G_DBUS_CALL_FLAGS_NONE,
20400 * The calling thread is blocked until a reply is received. See
20401 * g_dbus_connection_call() for the asynchronous version of
20404 * return values. Free with g_variant_unref().
20406 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
20412 * g_dbus_connection_call_with_unix_fd_list:
20413 * @connection: A #GDBusConnection.
20414 * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection.
20415 * @object_path: Path of remote object.
20416 * @interface_name: D-Bus interface to invoke method on.
20417 * @method_name: The name of the method to invoke.
20418 * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
20419 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
20420 * @flags: Flags from the #GDBusCallFlags enumeration.
20421 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
20422 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
20423 * @cancellable: A #GCancellable or %NULL.
20424 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't * care about the result of the method invocation.
20425 * @user_data: The data to pass to @callback.
20427 * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
20429 * This method is only available on UNIX.
20436 * g_dbus_connection_call_with_unix_fd_list_finish:
20437 * @connection: A #GDBusConnection.
20438 * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
20439 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call_with_unix_fd_list().
20440 * @error: Return location for error or %NULL.
20442 * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
20444 * return values. Free with g_variant_unref().
20446 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
20452 * g_dbus_connection_call_with_unix_fd_list_sync:
20453 * @connection: A #GDBusConnection.
20454 * @bus_name: A unique or well-known bus name.
20455 * @object_path: Path of remote object.
20456 * @interface_name: D-Bus interface to invoke method on.
20457 * @method_name: The name of the method to invoke.
20458 * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters.
20459 * @reply_type: (allow-none): The expected type of the reply, or %NULL.
20460 * @flags: Flags from the #GDBusCallFlags enumeration.
20461 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
20462 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
20463 * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
20464 * @cancellable: A #GCancellable or %NULL.
20465 * @error: Return location for error or %NULL.
20467 * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
20469 * This method is only available on UNIX.
20471 * return values. Free with g_variant_unref().
20473 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
20479 * g_dbus_connection_close:
20480 * @connection: A #GDBusConnection.
20481 * @cancellable: A #GCancellable or %NULL.
20482 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
20483 * @user_data: The data to pass to @callback.
20485 * Closes @connection. Note that this never causes the process to
20486 * exit (this might only happen if the other end of a shared message
20487 * bus connection disconnects, see #GDBusConnection:exit-on-close).
20489 * Once the connection is closed, operations such as sending a message
20490 * will return with the error %G_IO_ERROR_CLOSED. Closing a connection
20491 * will not automatically flush the connection so queued messages may
20492 * be lost. Use g_dbus_connection_flush() if you need such guarantees.
20494 * If @connection is already closed, this method fails with
20495 * %G_IO_ERROR_CLOSED.
20497 * When @connection has been closed, the #GDBusConnection::closed
20498 * signal is emitted in the <link
20499 * linkend="g-main-context-push-thread-default">thread-default main
20500 * loop</link> of the thread that @connection was constructed in.
20502 * This is an asynchronous method. When the operation is finished,
20503 * @callback will be invoked in the <link
20504 * linkend="g-main-context-push-thread-default">thread-default main
20505 * loop</link> of the thread you are calling this method from. You can
20506 * then call g_dbus_connection_close_finish() to get the result of the
20507 * operation. See g_dbus_connection_close_sync() for the synchronous
20515 * g_dbus_connection_close_finish:
20516 * @connection: A #GDBusConnection.
20517 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close().
20518 * @error: Return location for error or %NULL.
20520 * Finishes an operation started with g_dbus_connection_close().
20522 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
20528 * g_dbus_connection_close_sync:
20529 * @connection: A #GDBusConnection.
20530 * @cancellable: A #GCancellable or %NULL.
20531 * @error: Return location for error or %NULL.
20533 * Synchronously closees @connection. The calling thread is blocked
20534 * until this is done. See g_dbus_connection_close() for the
20535 * asynchronous version of this method and more details about what it
20538 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
20544 * g_dbus_connection_emit_signal:
20545 * @connection: A #GDBusConnection.
20546 * @destination_bus_name: (allow-none): The unique bus name for the destination for the signal or %NULL to emit to all listeners.
20547 * @object_path: Path of remote object.
20548 * @interface_name: D-Bus interface to emit a signal on.
20549 * @signal_name: The name of the signal to emit.
20550 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
20551 * @error: Return location for error or %NULL.
20555 * If the parameters GVariant is floating, it is consumed.
20557 * This can only fail if @parameters is not compatible with the D-Bus protocol.
20559 * Returns: %TRUE unless @error is set.
20565 * g_dbus_connection_export_action_group:
20566 * @connection: a #GDBusConnection
20567 * @object_path: a D-Bus object path
20568 * @action_group: a #GActionGroup
20569 * @error: a pointer to a %NULL #GError, or %NULL
20571 * Exports @action_group on @connection at @object_path.
20573 * The implemented D-Bus API should be considered private. It is
20574 * subject to change in the future.
20576 * A given object path can only have one action group exported on it.
20577 * If this constraint is violated, the export will fail and 0 will be
20578 * returned (with @error set accordingly).
20580 * You can unexport the action group using
20581 * g_dbus_connection_unexport_action_group() with the return value of
20584 * The thread default main context is taken at the time of this call.
20585 * All incoming action activations and state change requests are
20586 * reported from this context. Any changes on the action group that
20587 * cause it to emit signals must also come from this same context.
20588 * Since incoming action activations and state change requests are
20589 * rather likely to cause changes on the action group, this effectively
20590 * limits a given action group to being exported from only one main
20593 * Returns: the ID of the export (never zero), or 0 in case of failure
20599 * g_dbus_connection_export_menu_model:
20600 * @connection: a #GDBusConnection
20601 * @object_path: a D-Bus object path
20602 * @menu: a #GMenuModel
20603 * @error: return location for an error, or %NULL
20605 * Exports @menu on @connection at @object_path.
20607 * The implemented D-Bus API should be considered private.
20608 * It is subject to change in the future.
20610 * An object path can only have one action group exported on it. If this
20611 * constraint is violated, the export will fail and 0 will be
20612 * returned (with @error set accordingly).
20614 * You can unexport the menu model using
20615 * g_dbus_connection_unexport_menu_model() with the return value of
20618 * Returns: the ID of the export (never zero), or 0 in case of failure
20624 * g_dbus_connection_flush:
20625 * @connection: A #GDBusConnection.
20626 * @cancellable: A #GCancellable or %NULL.
20627 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
20628 * @user_data: The data to pass to @callback.
20630 * Asynchronously flushes @connection, that is, writes all queued
20631 * outgoing message to the transport and then flushes the transport
20632 * (using g_output_stream_flush_async()). This is useful in programs
20633 * that wants to emit a D-Bus signal and then exit
20634 * immediately. Without flushing the connection, there is no guarantee
20635 * that the message has been sent to the networking buffers in the OS
20638 * This is an asynchronous method. When the operation is finished,
20639 * @callback will be invoked in the <link
20640 * linkend="g-main-context-push-thread-default">thread-default main
20641 * loop</link> of the thread you are calling this method from. You can
20642 * then call g_dbus_connection_flush_finish() to get the result of the
20643 * operation. See g_dbus_connection_flush_sync() for the synchronous
20651 * g_dbus_connection_flush_finish:
20652 * @connection: A #GDBusConnection.
20653 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush().
20654 * @error: Return location for error or %NULL.
20656 * Finishes an operation started with g_dbus_connection_flush().
20658 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
20664 * g_dbus_connection_flush_sync:
20665 * @connection: A #GDBusConnection.
20666 * @cancellable: A #GCancellable or %NULL.
20667 * @error: Return location for error or %NULL.
20669 * Synchronously flushes @connection. The calling thread is blocked
20670 * until this is done. See g_dbus_connection_flush() for the
20671 * asynchronous version of this method and more details about what it
20674 * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
20680 * g_dbus_connection_get_capabilities:
20681 * @connection: A #GDBusConnection.
20683 * Gets the capabilities negotiated with the remote peer
20685 * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration.
20691 * g_dbus_connection_get_exit_on_close:
20692 * @connection: A #GDBusConnection.
20694 * Gets whether the process is terminated when @connection is
20695 * closed by the remote peer. See
20696 * #GDBusConnection:exit-on-close for more details.
20698 * closed by the remote peer.
20700 * Returns: Whether the process is terminated when @connection is
20706 * g_dbus_connection_get_guid:
20707 * @connection: A #GDBusConnection.
20709 * The GUID of the peer performing the role of server when
20710 * authenticating. See #GDBusConnection:guid for more details.
20714 * Returns: The GUID. Do not free this string, it is owned by
20720 * g_dbus_connection_get_peer_credentials:
20721 * @connection: A #GDBusConnection.
20723 * Gets the credentials of the authenticated peer. This will always
20724 * return %NULL unless @connection acted as a server
20725 * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed)
20726 * when set up and the client passed credentials as part of the
20727 * authentication process.
20729 * In a message bus setup, the message bus is always the server and
20730 * each application is a client. So this method will always return
20731 * %NULL for message bus clients.
20733 * this object, it is owned by @connection.
20735 * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free
20741 * g_dbus_connection_get_stream:
20742 * @connection: a #GDBusConnection
20744 * Gets the underlying stream used for IO.
20746 * While the #GDBusConnection is active, it will interact with this
20747 * stream from a worker thread, so it is not safe to interact with
20748 * the stream directly.
20750 * Returns: (transfer none): the stream used for IO
20756 * g_dbus_connection_get_unique_name:
20757 * @connection: A #GDBusConnection.
20759 * Gets the unique name of @connection as assigned by the message
20760 * bus. This can also be used to figure out if @connection is a
20761 * message bus connection.
20763 * bus connection. Do not free this string, it is owned by
20766 * Returns: The unique name or %NULL if @connection is not a message
20772 * g_dbus_connection_is_closed:
20773 * @connection: A #GDBusConnection.
20775 * Gets whether @connection is closed.
20777 * Returns: %TRUE if the connection is closed, %FALSE otherwise.
20783 * g_dbus_connection_new:
20784 * @stream: A #GIOStream.
20785 * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
20786 * @flags: Flags describing how to make the connection.
20787 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
20788 * @cancellable: A #GCancellable or %NULL.
20789 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
20790 * @user_data: The data to pass to @callback.
20792 * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
20793 * with the end represented by @stream.
20795 * If @stream is a #GSocketConnection, then the corresponding #GSocket
20796 * will be put into non-blocking mode.
20798 * The D-Bus connection will interact with @stream from a worker thread.
20799 * As a result, the caller should not interact with @stream after this
20800 * method has been called, except by calling g_object_unref() on it.
20802 * If @observer is not %NULL it may be used to control the
20803 * authentication process.
20805 * When the operation is finished, @callback will be invoked. You can
20806 * then call g_dbus_connection_new_finish() to get the result of the
20809 * This is a asynchronous failable constructor. See
20810 * g_dbus_connection_new_sync() for the synchronous
20818 * g_dbus_connection_new_finish:
20819 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
20820 * @error: Return location for error or %NULL.
20822 * Finishes an operation started with g_dbus_connection_new().
20824 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
20830 * g_dbus_connection_new_for_address:
20831 * @address: A D-Bus address.
20832 * @flags: Flags describing how to make the connection.
20833 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
20834 * @cancellable: A #GCancellable or %NULL.
20835 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
20836 * @user_data: The data to pass to @callback.
20838 * Asynchronously connects and sets up a D-Bus client connection for
20839 * exchanging D-Bus messages with an endpoint specified by @address
20840 * which must be in the D-Bus address format.
20842 * This constructor can only be used to initiate client-side
20843 * connections - use g_dbus_connection_new() if you need to act as the
20844 * server. In particular, @flags cannot contain the
20845 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
20846 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
20848 * When the operation is finished, @callback will be invoked. You can
20849 * then call g_dbus_connection_new_finish() to get the result of the
20852 * If @observer is not %NULL it may be used to control the
20853 * authentication process.
20855 * This is a asynchronous failable constructor. See
20856 * g_dbus_connection_new_for_address_sync() for the synchronous
20864 * g_dbus_connection_new_for_address_finish:
20865 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
20866 * @error: Return location for error or %NULL.
20868 * Finishes an operation started with g_dbus_connection_new_for_address().
20870 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
20876 * g_dbus_connection_new_for_address_sync:
20877 * @address: A D-Bus address.
20878 * @flags: Flags describing how to make the connection.
20879 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
20880 * @cancellable: A #GCancellable or %NULL.
20881 * @error: Return location for error or %NULL.
20883 * Synchronously connects and sets up a D-Bus client connection for
20884 * exchanging D-Bus messages with an endpoint specified by @address
20885 * which must be in the D-Bus address format.
20887 * This constructor can only be used to initiate client-side
20888 * connections - use g_dbus_connection_new_sync() if you need to act
20889 * as the server. In particular, @flags cannot contain the
20890 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or
20891 * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.
20893 * This is a synchronous failable constructor. See
20894 * g_dbus_connection_new_for_address() for the asynchronous version.
20896 * If @observer is not %NULL it may be used to control the
20897 * authentication process.
20899 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
20905 * g_dbus_connection_new_sync:
20906 * @stream: A #GIOStream.
20907 * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
20908 * @flags: Flags describing how to make the connection.
20909 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
20910 * @cancellable: A #GCancellable or %NULL.
20911 * @error: Return location for error or %NULL.
20913 * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
20914 * with the end represented by @stream.
20916 * If @stream is a #GSocketConnection, then the corresponding #GSocket
20917 * will be put into non-blocking mode.
20919 * The D-Bus connection will interact with @stream from a worker thread.
20920 * As a result, the caller should not interact with @stream after this
20921 * method has been called, except by calling g_object_unref() on it.
20923 * If @observer is not %NULL it may be used to control the
20924 * authentication process.
20926 * This is a synchronous failable constructor. See
20927 * g_dbus_connection_new() for the asynchronous version.
20929 * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
20935 * g_dbus_connection_register_object:
20936 * @connection: A #GDBusConnection.
20937 * @object_path: The object path to register at.
20938 * @interface_info: Introspection data for the interface.
20939 * @vtable: (allow-none): A #GDBusInterfaceVTable to call into or %NULL.
20940 * @user_data: (allow-none): Data to pass to functions in @vtable.
20941 * @user_data_free_func: Function to call when the object path is unregistered.
20942 * @error: Return location for error or %NULL.
20944 * Registers callbacks for exported objects at @object_path with the
20945 * D-Bus interface that is described in @interface_info.
20947 * Calls to functions in @vtable (and @user_data_free_func) will
20948 * happen in the <link linkend="g-main-context-push-thread-default">thread-default main
20949 * loop</link> of the thread you are calling this method from.
20951 * Note that all #GVariant values passed to functions in @vtable will match
20952 * the signature given in @interface_info - if a remote caller passes
20953 * incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal>
20954 * is returned to the remote caller.
20956 * Additionally, if the remote caller attempts to invoke methods or
20957 * access properties not mentioned in @interface_info the
20958 * <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp.
20959 * <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors
20960 * are returned to the caller.
20962 * It is considered a programming error if the
20963 * #GDBusInterfaceGetPropertyFunc function in @vtable returns a
20964 * #GVariant of incorrect type.
20966 * If an existing callback is already registered at @object_path and
20967 * @interface_name, then @error is set to #G_IO_ERROR_EXISTS.
20969 * GDBus automatically implements the standard D-Bus interfaces
20970 * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
20971 * and org.freedesktop.Peer, so you don't have to implement those for
20972 * the objects you export. You <emphasis>can</emphasis> implement
20973 * org.freedesktop.DBus.Properties yourself, e.g. to handle getting
20974 * and setting of properties asynchronously.
20976 * Note that the reference count on @interface_info will be
20977 * incremented by 1 (unless allocated statically, e.g. if the
20978 * reference count is -1, see g_dbus_interface_info_ref()) for as long
20979 * as the object is exported. Also note that @vtable will be copied.
20981 * See <xref linkend="gdbus-server"/> for an example of how to use this method.
20983 * that can be used with g_dbus_connection_unregister_object() .
20985 * Returns: 0 if @error is set, otherwise a registration id (never 0)
20991 * g_dbus_connection_register_subtree:
20992 * @connection: A #GDBusConnection.
20993 * @object_path: The object path to register the subtree at.
20994 * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree.
20995 * @flags: Flags used to fine tune the behavior of the subtree.
20996 * @user_data: Data to pass to functions in @vtable.
20997 * @user_data_free_func: Function to call when the subtree is unregistered.
20998 * @error: Return location for error or %NULL.
21000 * Registers a whole subtree of <quote>dynamic</quote> objects.
21002 * The @enumerate and @introspection functions in @vtable are used to
21003 * convey, to remote callers, what nodes exist in the subtree rooted
21006 * When handling remote calls into any node in the subtree, first the
21007 * @enumerate function is used to check if the node exists. If the node exists
21008 * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set
21009 * the @introspection function is used to check if the node supports the
21010 * requested method. If so, the @dispatch function is used to determine
21011 * where to dispatch the call. The collected #GDBusInterfaceVTable and
21012 * #gpointer will be used to call into the interface vtable for processing
21015 * All calls into user-provided code will be invoked in the <link
21016 * linkend="g-main-context-push-thread-default">thread-default main
21017 * loop</link> of the thread you are calling this method from.
21019 * If an existing subtree is already registered at @object_path or
21020 * then @error is set to #G_IO_ERROR_EXISTS.
21022 * Note that it is valid to register regular objects (using
21023 * g_dbus_connection_register_object()) in a subtree registered with
21024 * g_dbus_connection_register_subtree() - if so, the subtree handler
21025 * is tried as the last resort. One way to think about a subtree
21026 * handler is to consider it a <quote>fallback handler</quote>
21027 * for object paths not registered via g_dbus_connection_register_object()
21028 * or other bindings.
21030 * Note that @vtable will be copied so you cannot change it after
21033 * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method.
21035 * that can be used with g_dbus_connection_unregister_subtree() .
21037 * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
21043 * g_dbus_connection_remove_filter:
21044 * @connection: a #GDBusConnection
21045 * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
21047 * Removes a filter.
21054 * g_dbus_connection_send_message:
21055 * @connection: A #GDBusConnection.
21056 * @message: A #GDBusMessage
21057 * @flags: Flags affecting how the message is sent.
21058 * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL.
21059 * @error: Return location for error or %NULL.
21061 * Asynchronously sends @message to the peer represented by @connection.
21063 * Unless @flags contain the
21064 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
21065 * will be assigned by @connection and set on @message via
21066 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
21067 * serial number used will be written to this location prior to
21068 * submitting the message to the underlying transport.
21070 * If @connection is closed then the operation will fail with
21071 * %G_IO_ERROR_CLOSED. If @message is not well-formed,
21072 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
21074 * See <xref linkend="gdbus-server"/> and <xref
21075 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
21076 * low-level API to send and receive UNIX file descriptors.
21078 * Note that @message must be unlocked, unless @flags contain the
21079 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
21081 * transmission, %FALSE if @error is set.
21083 * Returns: %TRUE if the message was well-formed and queued for
21089 * g_dbus_connection_send_message_with_reply:
21090 * @connection: A #GDBusConnection.
21091 * @message: A #GDBusMessage.
21092 * @flags: Flags affecting how the message is sent.
21093 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
21094 * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL.
21095 * @cancellable: A #GCancellable or %NULL.
21096 * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result.
21097 * @user_data: The data to pass to @callback.
21099 * Asynchronously sends @message to the peer represented by @connection.
21101 * Unless @flags contain the
21102 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
21103 * will be assigned by @connection and set on @message via
21104 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
21105 * serial number used will be written to this location prior to
21106 * submitting the message to the underlying transport.
21108 * If @connection is closed then the operation will fail with
21109 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
21110 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
21111 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
21113 * This is an asynchronous method. When the operation is finished, @callback will be invoked
21114 * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
21115 * of the thread you are calling this method from. You can then call
21116 * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
21117 * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
21119 * Note that @message must be unlocked, unless @flags contain the
21120 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
21122 * See <xref linkend="gdbus-server"/> and <xref
21123 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
21124 * low-level API to send and receive UNIX file descriptors.
21131 * g_dbus_connection_send_message_with_reply_finish:
21132 * @connection: a #GDBusConnection
21133 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply().
21134 * @error: Return location for error or %NULL.
21136 * Finishes an operation started with g_dbus_connection_send_message_with_reply().
21138 * Note that @error is only set if a local in-process error
21139 * occurred. That is to say that the returned #GDBusMessage object may
21140 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
21141 * g_dbus_message_to_gerror() to transcode this to a #GError.
21143 * See <xref linkend="gdbus-server"/> and <xref
21144 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
21145 * low-level API to send and receive UNIX file descriptors.
21147 * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set.
21153 * g_dbus_connection_send_message_with_reply_sync:
21154 * @connection: A #GDBusConnection.
21155 * @message: A #GDBusMessage.
21156 * @flags: Flags affecting how the message is sent.
21157 * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout.
21158 * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL.
21159 * @cancellable: A #GCancellable or %NULL.
21160 * @error: Return location for error or %NULL.
21162 * Synchronously sends @message to the peer represented by @connection
21163 * and blocks the calling thread until a reply is received or the
21164 * timeout is reached. See g_dbus_connection_send_message_with_reply()
21165 * for the asynchronous version of this method.
21167 * Unless @flags contain the
21168 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number
21169 * will be assigned by @connection and set on @message via
21170 * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
21171 * serial number used will be written to this location prior to
21172 * submitting the message to the underlying transport.
21174 * If @connection is closed then the operation will fail with
21175 * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
21176 * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
21177 * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
21179 * Note that @error is only set if a local in-process error
21180 * occurred. That is to say that the returned #GDBusMessage object may
21181 * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
21182 * g_dbus_message_to_gerror() to transcode this to a #GError.
21184 * See <xref linkend="gdbus-server"/> and <xref
21185 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
21186 * low-level API to send and receive UNIX file descriptors.
21188 * Note that @message must be unlocked, unless @flags contain the
21189 * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
21191 * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set.
21197 * g_dbus_connection_set_exit_on_close:
21198 * @connection: A #GDBusConnection.
21199 * @exit_on_close: Whether the process should be terminated when @connection is closed by the remote peer.
21201 * Sets whether the process should be terminated when @connection is
21202 * closed by the remote peer. See #GDBusConnection:exit-on-close for
21205 * Note that this function should be used with care. Most modern UNIX
21206 * desktops tie the notion of a user session the session bus, and expect
21207 * all of a users applications to quit when their bus connection goes away.
21208 * If you are setting @exit_on_close to %FALSE for the shared session
21209 * bus connection, you should make sure that your application exits
21210 * when the user session ends.
21217 * g_dbus_connection_signal_subscribe:
21218 * @connection: A #GDBusConnection.
21219 * @sender: (allow-none): Sender name to match on (unique or well-known name) or %NULL to listen from all senders.
21220 * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to match on all interfaces.
21221 * @member: (allow-none): D-Bus signal name to match on or %NULL to match on all signals.
21222 * @object_path: (allow-none): Object path to match on or %NULL to match on all object paths.
21223 * @arg0: (allow-none): Contents of first string argument to match on or %NULL to match on all kinds of arguments.
21224 * @flags: Flags describing how to subscribe to the signal (currently unused).
21225 * @callback: Callback to invoke when there is a signal matching the requested data.
21226 * @user_data: User data to pass to @callback.
21227 * @user_data_free_func: (allow-none): Function to free @user_data with when subscription is removed or %NULL.
21229 * Subscribes to signals on @connection and invokes @callback with a
21230 * whenever the signal is received. Note that @callback
21231 * will be invoked in the <link
21232 * linkend="g-main-context-push-thread-default">thread-default main
21233 * loop</link> of the thread you are calling this method from.
21235 * If @connection is not a message bus connection, @sender must be
21238 * If @sender is a well-known name note that @callback is invoked with
21239 * the unique name for the owner of @sender, not the well-known name
21240 * as one would expect. This is because the message bus rewrites the
21241 * name. As such, to avoid certain race conditions, users should be
21242 * tracking the name owner of the well-known name and use that when
21243 * processing the received signal.
21245 * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().
21251 * g_dbus_connection_signal_unsubscribe:
21252 * @connection: A #GDBusConnection.
21253 * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe().
21255 * Unsubscribes from signals.
21262 * g_dbus_connection_start_message_processing:
21263 * @connection: A #GDBusConnection.
21265 * If @connection was created with
21266 * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
21267 * starts processing messages. Does nothing on if @connection wasn't
21268 * created with this flag or if the method has already been called.
21275 * g_dbus_connection_unexport_action_group:
21276 * @connection: a #GDBusConnection
21277 * @export_id: the ID from g_dbus_connection_export_action_group()
21279 * Reverses the effect of a previous call to
21280 * g_dbus_connection_export_action_group().
21282 * It is an error to call this function with an ID that wasn't returned
21283 * from g_dbus_connection_export_action_group() or to call it with the
21284 * same ID more than once.
21291 * g_dbus_connection_unexport_menu_model:
21292 * @connection: a #GDBusConnection
21293 * @export_id: the ID from g_dbus_connection_export_menu_model()
21295 * Reverses the effect of a previous call to
21296 * g_dbus_connection_export_menu_model().
21298 * It is an error to call this function with an ID that wasn't returned
21299 * from g_dbus_connection_export_menu_model() or to call it with the
21300 * same ID more than once.
21307 * g_dbus_connection_unregister_object:
21308 * @connection: A #GDBusConnection.
21309 * @registration_id: A registration id obtained from g_dbus_connection_register_object().
21311 * Unregisters an object.
21313 * Returns: %TRUE if the object was unregistered, %FALSE otherwise.
21319 * g_dbus_connection_unregister_subtree:
21320 * @connection: A #GDBusConnection.
21321 * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree().
21323 * Unregisters a subtree.
21325 * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise.
21331 * g_dbus_error_encode_gerror:
21332 * @error: A #GError.
21334 * Creates a D-Bus error name to use for @error. If @error matches
21335 * a registered error (cf. g_dbus_error_register_error()), the corresponding
21336 * D-Bus error name will be returned.
21338 * Otherwise the a name of the form
21339 * <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal>
21340 * will be used. This allows other GDBus applications to map the error
21341 * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
21343 * This function is typically only used in object mappings to put a
21344 * #GError on the wire. Regular applications should not use it.
21346 * Returns: A D-Bus error name (never %NULL). Free with g_free().
21352 * g_dbus_error_get_remote_error:
21353 * @error: A #GError.
21355 * Gets the D-Bus error name used for @error, if any.
21357 * This function is guaranteed to return a D-Bus error name for all
21358 * #GError<!-- -->s returned from functions handling remote method
21359 * calls (e.g. g_dbus_connection_call_finish()) unless
21360 * g_dbus_error_strip_remote_error() has been used on @error.
21362 * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free().
21368 * g_dbus_error_is_remote_error:
21369 * @error: A #GError.
21371 * Checks if @error represents an error received via D-Bus from a remote peer. If so,
21372 * use g_dbus_error_get_remote_error() to get the name of the error.
21374 * %FALSE otherwise.
21376 * Returns: %TRUE if @error represents an error from a remote peer,
21382 * g_dbus_error_new_for_dbus_error:
21383 * @dbus_error_name: D-Bus error name.
21384 * @dbus_error_message: D-Bus error message.
21386 * Creates a #GError based on the contents of @dbus_error_name and
21387 * @dbus_error_message.
21389 * Errors registered with g_dbus_error_register_error() will be looked
21390 * up using @dbus_error_name and if a match is found, the error domain
21391 * and code is used. Applications can use g_dbus_error_get_remote_error()
21392 * to recover @dbus_error_name.
21394 * If a match against a registered error is not found and the D-Bus
21395 * error name is in a form as returned by g_dbus_error_encode_gerror()
21396 * the error domain and code encoded in the name is used to
21397 * create the #GError. Also, @dbus_error_name is added to the error message
21398 * such that it can be recovered with g_dbus_error_get_remote_error().
21400 * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR
21401 * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is
21402 * added to the error message such that it can be recovered with
21403 * g_dbus_error_get_remote_error().
21405 * In all three cases, @dbus_error_name can always be recovered from the
21406 * returned #GError using the g_dbus_error_get_remote_error() function
21407 * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).
21409 * This function is typically only used in object mappings to prepare
21410 * #GError instances for applications. Regular applications should not use
21413 * Returns: An allocated #GError. Free with g_error_free().
21419 * g_dbus_error_register_error:
21420 * @error_domain: A #GQuark for a error domain.
21421 * @error_code: An error code.
21422 * @dbus_error_name: A D-Bus error name.
21424 * Creates an association to map between @dbus_error_name and
21425 * #GError<!-- -->s specified by @error_domain and @error_code.
21427 * This is typically done in the routine that returns the #GQuark for
21432 * Returns: %TRUE if the association was created, %FALSE if it already
21438 * g_dbus_error_register_error_domain:
21439 * @error_domain_quark_name: The error domain name.
21440 * @quark_volatile: A pointer where to store the #GQuark.
21441 * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
21442 * @num_entries: Number of items to register.
21444 * Helper function for associating a #GError error domain with D-Bus error names.
21451 * g_dbus_error_set_dbus_error:
21452 * @error: A pointer to a #GError or %NULL.
21453 * @dbus_error_name: D-Bus error name.
21454 * @dbus_error_message: D-Bus error message.
21455 * @format: printf()-style format to prepend to @dbus_error_message or %NULL.
21456 * @...: Arguments for @format.
21458 * Does nothing if @error is %NULL. Otherwise sets *@error to
21459 * a new #GError created with g_dbus_error_new_for_dbus_error()
21460 * with @dbus_error_message prepend with @format (unless %NULL).
21467 * g_dbus_error_set_dbus_error_valist:
21468 * @error: A pointer to a #GError or %NULL.
21469 * @dbus_error_name: D-Bus error name.
21470 * @dbus_error_message: D-Bus error message.
21471 * @format: printf()-style format to prepend to @dbus_error_message or %NULL.
21472 * @var_args: Arguments for @format.
21474 * Like g_dbus_error_set_dbus_error() but intended for language bindings.
21481 * g_dbus_error_strip_remote_error:
21482 * @error: A #GError.
21484 * Looks for extra information in the error message used to recover
21485 * the D-Bus error name and strips it if found. If stripped, the
21486 * message field in @error will correspond exactly to what was
21487 * received on the wire.
21489 * This is typically used when presenting errors to the end user.
21491 * Returns: %TRUE if information was stripped, %FALSE otherwise.
21497 * g_dbus_error_unregister_error:
21498 * @error_domain: A #GQuark for a error domain.
21499 * @error_code: An error code.
21500 * @dbus_error_name: A D-Bus error name.
21502 * Destroys an association previously set up with g_dbus_error_register_error().
21504 * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found.
21510 * g_dbus_generate_guid:
21512 * Generate a D-Bus GUID that can be used with
21513 * e.g. g_dbus_connection_new().
21515 * See the D-Bus specification regarding what strings are valid D-Bus
21516 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
21518 * Returns: A valid D-Bus GUID. Free with g_free().
21524 * g_dbus_gvalue_to_gvariant:
21525 * @gvalue: A #GValue to convert to a #GVariant.
21526 * @type: A #GVariantType.
21528 * Converts a #GValue to a #GVariant of the type indicated by the @type parameter.
21530 * The conversion is using the following rules:
21531 * <table frame='all'>
21532 * <title>#GValue / #GVariant conversion rules</title>
21533 * <tgroup cols='2' align='left' colsep='1' rowsep='1'>
21536 * <entry>If the #GType for @gvalue is...</entry>
21537 * <entry>... then @type must be</entry>
21542 * <entry>#G_TYPE_STRING</entry>
21543 * <entry><link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>, <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link>, <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link> or <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link></entry>
21546 * <entry>#G_TYPE_STRV</entry>
21547 * <entry><link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>, <link linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> or <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link></entry>
21550 * <entry>#G_TYPE_BOOLEAN</entry>
21551 * <entry><link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link></entry>
21554 * <entry>#G_TYPE_UCHAR</entry>
21555 * <entry><link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link></entry>
21558 * <entry>#G_TYPE_INT</entry>
21559 * <entry><link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link> or <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link></entry>
21562 * <entry>#G_TYPE_UINT</entry>
21563 * <entry><link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link> or <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link></entry>
21566 * <entry>#G_TYPE_INT64</entry>
21567 * <entry><link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link></entry>
21570 * <entry>#G_TYPE_UINT64</entry>
21571 * <entry><link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link></entry>
21574 * <entry>#G_TYPE_DOUBLE</entry>
21575 * <entry><link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link></entry>
21578 * <entry>#G_TYPE_VARIANT</entry>
21579 * <entry>Any #GVariantType</entry>
21584 * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
21585 * is <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>. It will
21586 * also fail for any #GType (including e.g. #G_TYPE_OBJECT and
21587 * #G_TYPE_BOXED derived-types) not in the table above.
21589 * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
21590 * %NULL, the <emphasis>empty</emphasis> #GVariant instance (never
21591 * %NULL) for @type is returned (e.g. 0 for scalar types, the empty
21592 * string for string types, <literal>'/'</literal> for object path
21593 * types, the empty array for any array type and so on).
21595 * See the g_dbus_gvariant_to_gvalue() function for how to convert a
21596 * #GVariant to a #GValue.
21598 * @type holding the data from @gvalue or %NULL in case of
21599 * failure. Free with g_variant_unref().
21601 * Returns: A #GVariant (never floating) of #GVariantType
21607 * g_dbus_gvariant_to_gvalue:
21608 * @value: A #GVariant.
21609 * @out_gvalue: Return location pointing to a zero-filled (uninitialized) #GValue.
21611 * Converts a #GVariant to a #GValue. If @value is floating, it is consumed.
21613 * The rules specified in the g_dbus_gvalue_to_gvariant() function are
21614 * used - this function is essentially its reverse form.
21616 * The conversion never fails - a valid #GValue is always returned in
21624 * g_dbus_interface_dup_object:
21625 * @interface_: An exported D-Bus interface.
21627 * Gets the #GDBusObject that @interface_ belongs to, if any.
21629 * reference should be freed with g_object_unref().
21631 * Returns: (transfer full): A #GDBusObject or %NULL. The returned
21633 * Rename to: g_dbus_interface_get_object
21638 * g_dbus_interface_get_info:
21639 * @interface_: An exported D-Bus interface.
21641 * Gets D-Bus introspection information for the D-Bus interface
21642 * implemented by @interface_.
21644 * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free.
21650 * g_dbus_interface_get_object: (skip)
21651 * @interface_: An exported D-Bus interface.
21653 * Gets the #GDBusObject that @interface_ belongs to, if any.
21655 * <warning>It is not safe to use the returned object if @interface_
21656 * or the returned object is being used from other threads. See
21657 * g_dbus_interface_dup_object() for a thread-safe
21658 * alternative.</warning>
21660 * reference belongs to @interface_ and should not be freed.
21662 * Returns: (transfer none): A #GDBusObject or %NULL. The returned
21668 * g_dbus_interface_info_cache_build:
21669 * @info: A #GDBusInterfaceInfo.
21671 * Builds a lookup-cache to speed up
21672 * g_dbus_interface_info_lookup_method(),
21673 * g_dbus_interface_info_lookup_signal() and
21674 * g_dbus_interface_info_lookup_property().
21676 * If this has already been called with @info, the existing cache is
21677 * used and its use count is increased.
21679 * Note that @info cannot be modified until
21680 * g_dbus_interface_info_cache_release() is called.
21687 * g_dbus_interface_info_cache_release:
21688 * @info: A GDBusInterfaceInfo
21690 * Decrements the usage count for the cache for @info built by
21691 * g_dbus_interface_info_cache_build() (if any) and frees the
21692 * resources used by the cache if the usage count drops to zero.
21699 * g_dbus_interface_info_generate_xml:
21700 * @info: A #GDBusNodeInfo
21701 * @indent: Indentation level.
21702 * @string_builder: (out): A #GString to to append XML data to.
21704 * Appends an XML representation of @info (and its children) to @string_builder.
21706 * This function is typically used for generating introspection XML
21707 * documents at run-time for handling the
21708 * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>
21716 * g_dbus_interface_info_lookup_method:
21717 * @info: A #GDBusInterfaceInfo.
21718 * @name: A D-Bus method name (typically in CamelCase)
21720 * Looks up information about a method.
21722 * This cost of this function is O(n) in number of methods unless
21723 * g_dbus_interface_info_cache_build() has been used on @info.
21725 * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info.
21731 * g_dbus_interface_info_lookup_property:
21732 * @info: A #GDBusInterfaceInfo.
21733 * @name: A D-Bus property name (typically in CamelCase).
21735 * Looks up information about a property.
21737 * This cost of this function is O(n) in number of properties unless
21738 * g_dbus_interface_info_cache_build() has been used on @info.
21740 * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info.
21746 * g_dbus_interface_info_lookup_signal:
21747 * @info: A #GDBusInterfaceInfo.
21748 * @name: A D-Bus signal name (typically in CamelCase)
21750 * Looks up information about a signal.
21752 * This cost of this function is O(n) in number of signals unless
21753 * g_dbus_interface_info_cache_build() has been used on @info.
21755 * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info.
21761 * g_dbus_interface_info_ref:
21762 * @info: A #GDBusInterfaceInfo
21764 * If @info is statically allocated does nothing. Otherwise increases
21765 * the reference count.
21767 * Returns: The same @info.
21773 * g_dbus_interface_info_unref:
21774 * @info: A #GDBusInterfaceInfo.
21776 * If @info is statically allocated, does nothing. Otherwise decreases
21777 * the reference count of @info. When its reference count drops to 0,
21778 * the memory used is freed.
21785 * g_dbus_interface_set_object:
21786 * @interface_: An exported D-Bus interface.
21787 * @object: A #GDBusObject or %NULL.
21789 * Sets the #GDBusObject for @interface_ to @object.
21791 * Note that @interface_ will hold a weak reference to @object.
21798 * g_dbus_interface_skeleton_export:
21799 * @interface_: The D-Bus interface to export.
21800 * @connection: A #GDBusConnection to export @interface_ on.
21801 * @object_path: The path to export the interface at.
21802 * @error: Return location for error or %NULL.
21804 * Exports @interface_ at @object_path on @connection.
21806 * This can be called multiple times to export the same @interface_
21807 * onto multiple connections however the @object_path provided must be
21808 * the same for all connections.
21810 * Use g_dbus_interface_skeleton_unexport() to unexport the object.
21814 * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
21820 * g_dbus_interface_skeleton_flush:
21821 * @interface_: A #GDBusInterfaceSkeleton.
21823 * If @interface_ has outstanding changes, request for these changes to be
21824 * emitted immediately.
21826 * For example, an exported D-Bus interface may queue up property
21827 * changes and emit the
21828 * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
21829 * signal later (e.g. in an idle handler). This technique is useful
21830 * for collapsing multiple property changes into one.
21837 * g_dbus_interface_skeleton_get_connection:
21838 * @interface_: A #GDBusInterfaceSkeleton.
21840 * Gets the first connection that @interface_ is exported on, if any.
21842 * not exported anywhere. Do not free, the object belongs to @interface_.
21844 * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
21850 * g_dbus_interface_skeleton_get_connections:
21851 * @interface_: A #GDBusInterfaceSkeleton.
21853 * Gets a list of the connections that @interface_ is exported on.
21855 * all the connections that @interface_ is exported on. The returned
21856 * list should be freed with g_list_free() after each element has
21857 * been freed with g_object_unref().
21859 * Returns: (element-type GDBusConnection) (transfer full): A list of
21865 * g_dbus_interface_skeleton_get_flags:
21866 * @interface_: A #GDBusInterfaceSkeleton.
21868 * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior
21871 * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration.
21877 * g_dbus_interface_skeleton_get_info:
21878 * @interface_: A #GDBusInterfaceSkeleton.
21880 * Gets D-Bus introspection information for the D-Bus interface
21881 * implemented by @interface_.
21883 * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free.
21889 * g_dbus_interface_skeleton_get_object_path:
21890 * @interface_: A #GDBusInterfaceSkeleton.
21892 * Gets the object path that @interface_ is exported on, if any.
21894 * anywhere. Do not free, the string belongs to @interface_.
21896 * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported
21902 * g_dbus_interface_skeleton_get_properties:
21903 * @interface_: A #GDBusInterfaceSkeleton.
21905 * Gets all D-Bus properties for @interface_.
21907 * Returns: (transfer full): A #GVariant of type <link linkend="G-VARIANT-TYPE-VARDICT:CAPS">'a{sv}'</link>. Free with g_variant_unref().
21913 * g_dbus_interface_skeleton_get_vtable: (skip)
21914 * @interface_: A #GDBusInterfaceSkeleton.
21916 * Gets the interface vtable for the D-Bus interface implemented by
21917 * @interface_. The returned function pointers should expect @interface_
21918 * itself to be passed as @user_data.
21920 * Returns: A #GDBusInterfaceVTable (never %NULL).
21926 * g_dbus_interface_skeleton_has_connection:
21927 * @interface_: A #GDBusInterfaceSkeleton.
21928 * @connection: A #GDBusConnection.
21930 * Checks if @interface_ is export on @connection.
21932 * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise.
21938 * g_dbus_interface_skeleton_set_flags:
21939 * @interface_: A #GDBusInterfaceSkeleton.
21940 * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration.
21942 * Sets flags describing what the behavior of @skeleton should be.
21949 * g_dbus_interface_skeleton_unexport:
21950 * @interface_: A #GDBusInterfaceSkeleton.
21952 * Stops exporting @interface_ on all connections it is exported on.
21954 * To unexport @interface_ from only a single connection, use
21955 * g_dbus_interface_skeleton_unexport_from_connection()
21962 * g_dbus_interface_skeleton_unexport_from_connection:
21963 * @interface_: A #GDBusInterfaceSkeleton.
21964 * @connection: A #GDBusConnection.
21966 * Stops exporting @interface_ on @connection.
21968 * To stop exporting on all connections the interface is exported on,
21969 * use g_dbus_interface_skeleton_unexport().
21976 * g_dbus_is_address:
21977 * @string: A string.
21979 * Checks if @string is a D-Bus address.
21981 * This doesn't check if @string is actually supported by #GDBusServer
21982 * or #GDBusConnection - use g_dbus_is_supported_address() to do more
21985 * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise.
21992 * @string: The string to check.
21994 * Checks if @string is a D-Bus GUID.
21996 * See the D-Bus specification regarding what strings are valid D-Bus
21997 * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
21999 * Returns: %TRUE if @string is a guid, %FALSE otherwise.
22005 * g_dbus_is_interface_name:
22006 * @string: The string to check.
22008 * Checks if @string is a valid D-Bus interface name.
22010 * Returns: %TRUE if valid, %FALSE otherwise.
22016 * g_dbus_is_member_name:
22017 * @string: The string to check.
22019 * Checks if @string is a valid D-Bus member (e.g. signal or method) name.
22021 * Returns: %TRUE if valid, %FALSE otherwise.
22028 * @string: The string to check.
22030 * Checks if @string is a valid D-Bus bus name (either unique or well-known).
22032 * Returns: %TRUE if valid, %FALSE otherwise.
22038 * g_dbus_is_supported_address:
22039 * @string: A string.
22040 * @error: Return location for error or %NULL.
22042 * Like g_dbus_is_address() but also checks if the library suppors the
22043 * transports in @string and that key/value pairs for each transport
22046 * supported by this library, %FALSE if @error is set.
22048 * Returns: %TRUE if @string is a valid D-Bus address that is
22054 * g_dbus_is_unique_name:
22055 * @string: The string to check.
22057 * Checks if @string is a valid D-Bus unique bus name.
22059 * Returns: %TRUE if valid, %FALSE otherwise.
22065 * g_dbus_menu_model_get:
22066 * @connection: a #GDBusConnection
22067 * @bus_name: the bus name which exports the menu model
22068 * @object_path: the object path at which the menu model is exported
22070 * Obtains a #GDBusMenuModel for the menu model which is exported
22071 * at the given @bus_name and @object_path.
22073 * The thread default main context is taken at the time of this call.
22074 * All signals on the menu model (and any linked models) are reported
22075 * with respect to this context. All calls on the returned menu model
22076 * (and linked models) must also originate from this same context, with
22077 * the thread default main context unchanged.
22079 * g_object_unref().
22081 * Returns: (transfer full): a #GDBusMenuModel object. Free with
22087 * g_dbus_message_bytes_needed:
22088 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
22089 * @blob_len: The length of @blob (must be at least 16).
22090 * @error: Return location for error or %NULL.
22092 * Utility function to calculate how many bytes are needed to
22093 * completely deserialize the D-Bus message stored at @blob.
22095 * @blob contains invalid data or not enough data is available to
22096 * determine the size).
22098 * Returns: Number of bytes needed or -1 if @error is set (e.g. if
22104 * g_dbus_message_copy:
22105 * @message: A #GDBusMessage.
22106 * @error: Return location for error or %NULL.
22108 * Copies @message. The copy is a deep copy and the returned
22109 * #GDBusMessage is completely identical except that it is guaranteed
22110 * to not be locked.
22112 * This operation can fail if e.g. @message contains file descriptors
22113 * and the per-process or system-wide open files limit is reached.
22115 * Free with g_object_unref().
22117 * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
22123 * g_dbus_message_get_arg0:
22124 * @message: A #GDBusMessage.
22126 * Convenience to get the first item in the body of @message.
22128 * @message is not a string.
22130 * Returns: The string item or %NULL if the first item in the body of
22136 * g_dbus_message_get_body:
22137 * @message: A #GDBusMessage.
22139 * Gets the body of a message.
22141 * Returns: A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message.
22147 * g_dbus_message_get_byte_order:
22148 * @message: A #GDBusMessage.
22150 * Gets the byte order of @message.
22152 * Returns: The byte order.
22157 * g_dbus_message_get_destination:
22158 * @message: A #GDBusMessage.
22160 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
22162 * Returns: The value.
22168 * g_dbus_message_get_error_name:
22169 * @message: A #GDBusMessage.
22171 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
22173 * Returns: The value.
22179 * g_dbus_message_get_flags:
22180 * @message: A #GDBusMessage.
22182 * Gets the flags for @message.
22184 * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
22190 * g_dbus_message_get_header:
22191 * @message: A #GDBusMessage.
22192 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
22194 * Gets a header field on @message.
22196 * otherwise. Do not free, it is owned by @message.
22198 * Returns: A #GVariant with the value if the header was found, %NULL
22204 * g_dbus_message_get_header_fields:
22205 * @message: A #GDBusMessage.
22207 * Gets an array of all header fields on @message that are set.
22209 * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element
22210 * is a #guchar. Free with g_free().
22212 * Returns: (array zero-terminated=1): An array of header fields
22218 * g_dbus_message_get_interface:
22219 * @message: A #GDBusMessage.
22221 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
22223 * Returns: The value.
22229 * g_dbus_message_get_locked:
22230 * @message: A #GDBusMessage.
22232 * Checks whether @message is locked. To monitor changes to this
22233 * value, conncet to the #GObject::notify signal to listen for changes
22234 * on the #GDBusMessage:locked property.
22236 * Returns: %TRUE if @message is locked, %FALSE otherwise.
22242 * g_dbus_message_get_member:
22243 * @message: A #GDBusMessage.
22245 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
22247 * Returns: The value.
22253 * g_dbus_message_get_message_type:
22254 * @message: A #GDBusMessage.
22256 * Gets the type of @message.
22258 * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
22264 * g_dbus_message_get_num_unix_fds:
22265 * @message: A #GDBusMessage.
22267 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
22269 * Returns: The value.
22275 * g_dbus_message_get_path:
22276 * @message: A #GDBusMessage.
22278 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
22280 * Returns: The value.
22286 * g_dbus_message_get_reply_serial:
22287 * @message: A #GDBusMessage.
22289 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
22291 * Returns: The value.
22297 * g_dbus_message_get_sender:
22298 * @message: A #GDBusMessage.
22300 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
22302 * Returns: The value.
22308 * g_dbus_message_get_serial:
22309 * @message: A #GDBusMessage.
22311 * Gets the serial for @message.
22313 * Returns: A #guint32.
22319 * g_dbus_message_get_signature:
22320 * @message: A #GDBusMessage.
22322 * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
22324 * Returns: The value.
22330 * g_dbus_message_get_unix_fd_list:
22331 * @message: A #GDBusMessage.
22333 * Gets the UNIX file descriptors associated with @message, if any.
22335 * This method is only available on UNIX.
22337 * associated. Do not free, this object is owned by @message.
22339 * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
22345 * g_dbus_message_lock:
22346 * @message: A #GDBusMessage.
22348 * If @message is locked, does nothing. Otherwise locks the message.
22355 * g_dbus_message_new:
22357 * Creates a new empty #GDBusMessage.
22359 * Returns: A #GDBusMessage. Free with g_object_unref().
22365 * g_dbus_message_new_from_blob:
22366 * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
22367 * @blob_len: The length of @blob.
22368 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
22369 * @error: Return location for error or %NULL.
22371 * Creates a new #GDBusMessage from the data stored at @blob. The byte
22372 * order that the message was in can be retrieved using
22373 * g_dbus_message_get_byte_order().
22375 * g_object_unref().
22377 * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
22383 * g_dbus_message_new_method_call:
22384 * @name: A valid D-Bus name or %NULL.
22385 * @path: A valid object path.
22386 * @interface_: A valid D-Bus interface name or %NULL.
22387 * @method: A valid method name.
22389 * Creates a new #GDBusMessage for a method call.
22391 * Returns: A #GDBusMessage. Free with g_object_unref().
22397 * g_dbus_message_new_method_error:
22398 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
22399 * @error_name: A valid D-Bus error name.
22400 * @error_message_format: The D-Bus error message in a printf() format.
22401 * @...: Arguments for @error_message_format.
22403 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
22405 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
22411 * g_dbus_message_new_method_error_literal:
22412 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
22413 * @error_name: A valid D-Bus error name.
22414 * @error_message: The D-Bus error message.
22416 * Creates a new #GDBusMessage that is an error reply to @method_call_message.
22418 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
22424 * g_dbus_message_new_method_error_valist:
22425 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
22426 * @error_name: A valid D-Bus error name.
22427 * @error_message_format: The D-Bus error message in a printf() format.
22428 * @var_args: Arguments for @error_message_format.
22430 * Like g_dbus_message_new_method_error() but intended for language bindings.
22432 * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref().
22438 * g_dbus_message_new_method_reply:
22439 * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.
22441 * Creates a new #GDBusMessage that is a reply to @method_call_message.
22443 * Returns: (transfer full): #GDBusMessage. Free with g_object_unref().
22449 * g_dbus_message_new_signal:
22450 * @path: A valid object path.
22451 * @interface_: A valid D-Bus interface name.
22452 * @signal: A valid signal name.
22454 * Creates a new #GDBusMessage for a signal emission.
22456 * Returns: A #GDBusMessage. Free with g_object_unref().
22462 * g_dbus_message_print:
22463 * @message: A #GDBusMessage.
22464 * @indent: Indentation level.
22466 * Produces a human-readable multi-line description of @message.
22468 * The contents of the description has no ABI guarantees, the contents
22469 * and formatting is subject to change at any time. Typical output
22470 * looks something like this:
22476 * path -> objectpath '/org/gtk/GDBus/TestObject'
22477 * interface -> 'org.gtk.GDBus.TestInterface'
22478 * member -> 'GimmeStdout'
22479 * destination -> ':1.146'
22481 * UNIX File Descriptors:
22483 * </programlisting>
22486 * Flags: no-reply-expected
22490 * reply-serial -> uint32 4
22491 * destination -> ':1.159'
22492 * sender -> ':1.146'
22493 * num-unix-fds -> uint32 1
22495 * UNIX File Descriptors:
22496 * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
22497 * </programlisting>
22499 * Type: method-return
22500 * Returns: A string that should be freed with g_free().
22506 * g_dbus_message_set_body:
22507 * @message: A #GDBusMessage.
22508 * @body: Either %NULL or a #GVariant that is a tuple.
22510 * Sets the body @message. As a side-effect the
22511 * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the
22512 * type string of @body (or cleared if @body is %NULL).
22514 * If @body is floating, @message assumes ownership of @body.
22521 * g_dbus_message_set_byte_order:
22522 * @message: A #GDBusMessage.
22523 * @byte_order: The byte order.
22525 * Sets the byte order of @message.
22530 * g_dbus_message_set_destination:
22531 * @message: A #GDBusMessage.
22532 * @value: The value to set.
22534 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
22541 * g_dbus_message_set_error_name:
22542 * @message: A #GDBusMessage.
22543 * @value: The value to set.
22545 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
22552 * g_dbus_message_set_flags:
22553 * @message: A #GDBusMessage.
22554 * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together).
22556 * Sets the flags to set on @message.
22563 * g_dbus_message_set_header:
22564 * @message: A #GDBusMessage.
22565 * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration)
22566 * @value: A #GVariant to set the header field or %NULL to clear the header field.
22568 * Sets a header field on @message.
22570 * If @value is floating, @message assumes ownership of @value.
22577 * g_dbus_message_set_interface:
22578 * @message: A #GDBusMessage.
22579 * @value: The value to set.
22581 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
22588 * g_dbus_message_set_member:
22589 * @message: A #GDBusMessage.
22590 * @value: The value to set.
22592 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
22599 * g_dbus_message_set_message_type:
22600 * @message: A #GDBusMessage.
22601 * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration).
22603 * Sets @message to be of @type.
22610 * g_dbus_message_set_num_unix_fds:
22611 * @message: A #GDBusMessage.
22612 * @value: The value to set.
22614 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
22621 * g_dbus_message_set_path:
22622 * @message: A #GDBusMessage.
22623 * @value: The value to set.
22625 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.
22632 * g_dbus_message_set_reply_serial:
22633 * @message: A #GDBusMessage.
22634 * @value: The value to set.
22636 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
22643 * g_dbus_message_set_sender:
22644 * @message: A #GDBusMessage.
22645 * @value: The value to set.
22647 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
22654 * g_dbus_message_set_serial:
22655 * @message: A #GDBusMessage.
22656 * @serial: A #guint32.
22658 * Sets the serial for @message.
22665 * g_dbus_message_set_signature:
22666 * @message: A #GDBusMessage.
22667 * @value: The value to set.
22669 * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
22676 * g_dbus_message_set_unix_fd_list:
22677 * @message: A #GDBusMessage.
22678 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
22680 * Sets the UNIX file descriptors associated with @message. As a
22681 * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header
22682 * field is set to the number of fds in @fd_list (or cleared if
22683 * @fd_list is %NULL).
22685 * This method is only available on UNIX.
22692 * g_dbus_message_to_blob:
22693 * @message: A #GDBusMessage.
22694 * @out_size: Return location for size of generated blob.
22695 * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported.
22696 * @error: Return location for error.
22698 * Serializes @message to a blob. The byte order returned by
22699 * g_dbus_message_get_byte_order() will be used.
22701 * valid binary D-Bus message of @out_size bytes generated by @message
22702 * or %NULL if @error is set. Free with g_free().
22704 * Returns: (array length=out_size) (transfer full): A pointer to a
22710 * g_dbus_message_to_gerror:
22711 * @message: A #GDBusMessage.
22712 * @error: The #GError to set.
22714 * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does
22715 * nothing and returns %FALSE.
22717 * Otherwise this method encodes the error in @message as a #GError
22718 * using g_dbus_error_set_dbus_error() using the information in the
22719 * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as
22720 * well as the first string item in @message's body.
22722 * Returns: %TRUE if @error was set, %FALSE otherwise.
22728 * g_dbus_method_info_ref:
22729 * @info: A #GDBusMethodInfo
22731 * If @info is statically allocated does nothing. Otherwise increases
22732 * the reference count.
22734 * Returns: The same @info.
22740 * g_dbus_method_info_unref:
22741 * @info: A #GDBusMethodInfo.
22743 * If @info is statically allocated, does nothing. Otherwise decreases
22744 * the reference count of @info. When its reference count drops to 0,
22745 * the memory used is freed.
22752 * g_dbus_method_invocation_get_connection:
22753 * @invocation: A #GDBusMethodInvocation.
22755 * Gets the #GDBusConnection the method was invoked on.
22757 * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation.
22763 * g_dbus_method_invocation_get_interface_name:
22764 * @invocation: A #GDBusMethodInvocation.
22766 * Gets the name of the D-Bus interface the method was invoked on.
22768 * Returns: A string. Do not free, it is owned by @invocation.
22774 * g_dbus_method_invocation_get_message:
22775 * @invocation: A #GDBusMethodInvocation.
22777 * Gets the #GDBusMessage for the method invocation. This is useful if
22778 * you need to use low-level protocol features, such as UNIX file
22779 * descriptor passing, that cannot be properly expressed in the
22782 * See <xref linkend="gdbus-server"/> and <xref
22783 * linkend="gdbus-unix-fd-client"/> for an example of how to use this
22784 * low-level API to send and receive UNIX file descriptors.
22786 * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation.
22792 * g_dbus_method_invocation_get_method_info:
22793 * @invocation: A #GDBusMethodInvocation.
22795 * Gets information about the method call, if any.
22797 * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation.
22803 * g_dbus_method_invocation_get_method_name:
22804 * @invocation: A #GDBusMethodInvocation.
22806 * Gets the name of the method that was invoked.
22808 * Returns: A string. Do not free, it is owned by @invocation.
22814 * g_dbus_method_invocation_get_object_path:
22815 * @invocation: A #GDBusMethodInvocation.
22817 * Gets the object path the method was invoked on.
22819 * Returns: A string. Do not free, it is owned by @invocation.
22825 * g_dbus_method_invocation_get_parameters:
22826 * @invocation: A #GDBusMethodInvocation.
22828 * Gets the parameters of the method invocation. If there are no input
22829 * parameters then this will return a GVariant with 0 children rather than NULL.
22831 * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation.
22837 * g_dbus_method_invocation_get_sender:
22838 * @invocation: A #GDBusMethodInvocation.
22840 * Gets the bus name that invoked the method.
22842 * Returns: A string. Do not free, it is owned by @invocation.
22848 * g_dbus_method_invocation_get_user_data: (skip)
22849 * @invocation: A #GDBusMethodInvocation.
22851 * Gets the @user_data #gpointer passed to g_dbus_connection_register_object().
22853 * Returns: A #gpointer.
22859 * g_dbus_method_invocation_return_dbus_error:
22860 * @invocation: (transfer full): A #GDBusMethodInvocation.
22861 * @error_name: A valid D-Bus error name.
22862 * @error_message: A valid D-Bus error message.
22864 * Finishes handling a D-Bus method call by returning an error.
22866 * This method will free @invocation, you cannot use it afterwards.
22873 * g_dbus_method_invocation_return_error:
22874 * @invocation: (transfer full): A #GDBusMethodInvocation.
22875 * @domain: A #GQuark for the #GError error domain.
22876 * @code: The error code.
22877 * @format: printf()-style format.
22878 * @...: Parameters for @format.
22880 * Finishes handling a D-Bus method call by returning an error.
22882 * See g_dbus_error_encode_gerror() for details about what error name
22883 * will be returned on the wire. In a nutshell, if the given error is
22884 * registered using g_dbus_error_register_error() the name given
22885 * during registration is used. Otherwise, a name of the form
22886 * <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is
22887 * used. This provides transparent mapping of #GError between
22888 * applications using GDBus.
22890 * If you are writing an application intended to be portable,
22891 * <emphasis>always</emphasis> register errors with g_dbus_error_register_error()
22892 * or use g_dbus_method_invocation_return_dbus_error().
22894 * This method will free @invocation, you cannot use it afterwards.
22901 * g_dbus_method_invocation_return_error_literal:
22902 * @invocation: (transfer full): A #GDBusMethodInvocation.
22903 * @domain: A #GQuark for the #GError error domain.
22904 * @code: The error code.
22905 * @message: The error message.
22907 * Like g_dbus_method_invocation_return_error() but without printf()-style formatting.
22909 * This method will free @invocation, you cannot use it afterwards.
22916 * g_dbus_method_invocation_return_error_valist:
22917 * @invocation: (transfer full): A #GDBusMethodInvocation.
22918 * @domain: A #GQuark for the #GError error domain.
22919 * @code: The error code.
22920 * @format: printf()-style format.
22921 * @var_args: #va_list of parameters for @format.
22923 * Like g_dbus_method_invocation_return_error() but intended for
22924 * language bindings.
22926 * This method will free @invocation, you cannot use it afterwards.
22933 * g_dbus_method_invocation_return_gerror:
22934 * @invocation: (transfer full): A #GDBusMethodInvocation.
22935 * @error: A #GError.
22937 * Like g_dbus_method_invocation_return_error() but takes a #GError
22938 * instead of the error domain, error code and message.
22940 * This method will free @invocation, you cannot use it afterwards.
22947 * g_dbus_method_invocation_return_value:
22948 * @invocation: (transfer full): A #GDBusMethodInvocation.
22949 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
22951 * Finishes handling a D-Bus method call by returning @parameters.
22952 * If the @parameters GVariant is floating, it is consumed.
22954 * It is an error if @parameters is not of the right format.
22956 * This method will free @invocation, you cannot use it afterwards.
22963 * g_dbus_method_invocation_return_value_with_unix_fd_list:
22964 * @invocation: (transfer full): A #GDBusMethodInvocation.
22965 * @parameters: (allow-none): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters.
22966 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
22968 * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList.
22970 * This method is only available on UNIX.
22972 * This method will free @invocation, you cannot use it afterwards.
22979 * g_dbus_method_invocation_take_error: (skip)
22980 * @invocation: (transfer full): A #GDBusMethodInvocation.
22981 * @error: (transfer full): A #GError.
22983 * Like g_dbus_method_invocation_return_gerror() but takes ownership
22984 * of @error so the caller does not need to free it.
22986 * This method will free @invocation, you cannot use it afterwards.
22993 * g_dbus_node_info_generate_xml:
22994 * @info: A #GDBusNodeInfo.
22995 * @indent: Indentation level.
22996 * @string_builder: (out): A #GString to to append XML data to.
22998 * Appends an XML representation of @info (and its children) to @string_builder.
23000 * This function is typically used for generating introspection XML documents at run-time for
23001 * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.
23008 * g_dbus_node_info_lookup_interface:
23009 * @info: A #GDBusNodeInfo.
23010 * @name: A D-Bus interface name.
23012 * Looks up information about an interface.
23014 * This cost of this function is O(n) in number of interfaces.
23016 * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info.
23022 * g_dbus_node_info_new_for_xml:
23023 * @xml_data: Valid D-Bus introspection XML.
23024 * @error: Return location for error.
23026 * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
23028 * Note that this routine is using a
23029 * <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based
23030 * parser that only accepts a subset of valid XML documents.
23032 * with g_dbus_node_info_unref().
23034 * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
23040 * g_dbus_node_info_ref:
23041 * @info: A #GDBusNodeInfo
23043 * If @info is statically allocated does nothing. Otherwise increases
23044 * the reference count.
23046 * Returns: The same @info.
23052 * g_dbus_node_info_unref:
23053 * @info: A #GDBusNodeInfo.
23055 * If @info is statically allocated, does nothing. Otherwise decreases
23056 * the reference count of @info. When its reference count drops to 0,
23057 * the memory used is freed.
23064 * g_dbus_object_get_interface:
23065 * @object: A #GDBusObject.
23066 * @interface_name: A D-Bus interface name.
23068 * Gets the D-Bus interface with name @interface_name associated with
23071 * #GDBusInterface that must be freed with g_object_unref().
23073 * Returns: (transfer full): %NULL if not found, otherwise a
23079 * g_dbus_object_get_interfaces:
23080 * @object: A #GDBusObject.
23082 * Gets the D-Bus interfaces associated with @object.
23084 * The returned list must be freed by g_list_free() after each element has been freed
23085 * with g_object_unref().
23087 * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances.
23093 * g_dbus_object_get_object_path:
23094 * @object: A #GDBusObject.
23096 * Gets the object path for @object.
23098 * Returns: A string owned by @object. Do not free.
23104 * g_dbus_object_manager_client_get_connection:
23105 * @manager: A #GDBusObjectManagerClient
23107 * Gets the #GDBusConnection used by @manager.
23109 * the object belongs to @manager.
23111 * Returns: (transfer none): A #GDBusConnection object. Do not free,
23117 * g_dbus_object_manager_client_get_flags:
23118 * @manager: A #GDBusObjectManagerClient
23120 * Gets the flags that @manager was constructed with.
23124 * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
23130 * g_dbus_object_manager_client_get_name:
23131 * @manager: A #GDBusObjectManagerClient
23133 * Gets the name that @manager is for.
23135 * belongs to @manager.
23137 * Returns: A unique or well-known name. Do not free, the string
23143 * g_dbus_object_manager_client_get_name_owner:
23144 * @manager: A #GDBusObjectManagerClient.
23146 * The unique name that owns the name that @manager is for or %NULL if
23147 * no-one currently owns that name. You can connect to the
23148 * #GObject::notify signal to track changes to the
23149 * #GDBusObjectManagerClient:name-owner property.
23153 * Returns: The name owner or %NULL if no name owner exists. Free with
23159 * g_dbus_object_manager_client_new:
23160 * @connection: A #GDBusConnection.
23161 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
23162 * @name: The owner of the control object (unique or well-known name).
23163 * @object_path: The object path of the control object.
23164 * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
23165 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
23166 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
23167 * @cancellable: A #GCancellable or %NULL
23168 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
23169 * @user_data: The data to pass to @callback.
23171 * Asynchronously creates a new #GDBusObjectManagerClient object.
23173 * This is an asynchronous failable constructor. When the result is
23174 * ready, @callback will be invoked in the
23175 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
23176 * of the thread you are calling this method from. You can
23177 * then call g_dbus_object_manager_client_new_finish() to get the result. See
23178 * g_dbus_object_manager_client_new_sync() for the synchronous version.
23185 * g_dbus_object_manager_client_new_finish:
23186 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new().
23187 * @error: Return location for error or %NULL.
23189 * Finishes an operation started with g_dbus_object_manager_client_new().
23191 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
23192 * with g_object_unref().
23194 * Returns: (transfer full) (type GDBusObjectManagerClient): A
23200 * g_dbus_object_manager_client_new_for_bus:
23201 * @bus_type: A #GBusType.
23202 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
23203 * @name: The owner of the control object (unique or well-known name).
23204 * @object_path: The object path of the control object.
23205 * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
23206 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
23207 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
23208 * @cancellable: A #GCancellable or %NULL
23209 * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
23210 * @user_data: The data to pass to @callback.
23212 * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
23213 * #GDBusConnection.
23215 * This is an asynchronous failable constructor. When the result is
23216 * ready, @callback will be invoked in the
23217 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
23218 * of the thread you are calling this method from. You can
23219 * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
23220 * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
23227 * g_dbus_object_manager_client_new_for_bus_finish:
23228 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus().
23229 * @error: Return location for error or %NULL.
23231 * Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
23233 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
23234 * with g_object_unref().
23236 * Returns: (transfer full) (type GDBusObjectManagerClient): A
23242 * g_dbus_object_manager_client_new_for_bus_sync:
23243 * @bus_type: A #GBusType.
23244 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
23245 * @name: The owner of the control object (unique or well-known name).
23246 * @object_path: The object path of the control object.
23247 * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
23248 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
23249 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
23250 * @cancellable: A #GCancellable or %NULL
23251 * @error: Return location for error or %NULL.
23253 * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead
23254 * of a #GDBusConnection.
23256 * This is a synchronous failable constructor - the calling thread is
23257 * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
23258 * for the asynchronous version.
23260 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
23261 * with g_object_unref().
23263 * Returns: (transfer full) (type GDBusObjectManagerClient): A
23269 * g_dbus_object_manager_client_new_sync:
23270 * @connection: A #GDBusConnection.
23271 * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration.
23272 * @name: The owner of the control object (unique or well-known name).
23273 * @object_path: The object path of the control object.
23274 * @get_proxy_type_func: A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies.
23275 * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func.
23276 * @get_proxy_type_destroy_notify: (allow-none): Free function for @get_proxy_type_user_data or %NULL.
23277 * @cancellable: A #GCancellable or %NULL
23278 * @error: Return location for error or %NULL.
23280 * Creates a new #GDBusObjectManagerClient object.
23282 * This is a synchronous failable constructor - the calling thread is
23283 * blocked until a reply is received. See g_dbus_object_manager_client_new()
23284 * for the asynchronous version.
23286 * #GDBusObjectManagerClient object or %NULL if @error is set. Free
23287 * with g_object_unref().
23289 * Returns: (transfer full) (type GDBusObjectManagerClient): A
23295 * g_dbus_object_manager_get_interface:
23296 * @manager: A #GDBusObjectManager.
23297 * @object_path: Object path to lookup.
23298 * @interface_name: D-Bus interface name to lookup.
23300 * Gets the interface proxy for @interface_name at @object_path, if
23303 * with g_object_unref().
23305 * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
23311 * g_dbus_object_manager_get_object:
23312 * @manager: A #GDBusObjectManager.
23313 * @object_path: Object path to lookup.
23315 * Gets the #GDBusObjectProxy at @object_path, if any.
23317 * g_object_unref().
23319 * Returns: (transfer full): A #GDBusObject or %NULL. Free with
23325 * g_dbus_object_manager_get_object_path:
23326 * @manager: A #GDBusObjectManager.
23328 * Gets the object path that @manager is for.
23330 * Returns: A string owned by @manager. Do not free.
23336 * g_dbus_object_manager_get_objects:
23337 * @manager: A #GDBusObjectManager.
23339 * Gets all #GDBusObject objects known to @manager.
23341 * #GDBusObject objects. The returned list should be freed with
23342 * g_list_free() after each element has been freed with
23343 * g_object_unref().
23345 * Returns: (transfer full) (element-type GDBusObject): A list of
23351 * g_dbus_object_manager_server_export:
23352 * @manager: A #GDBusObjectManagerServer.
23353 * @object: A #GDBusObjectSkeleton.
23355 * Exports @object on @manager.
23357 * If there is already a #GDBusObject exported at the object path,
23358 * then the old object is removed.
23360 * The object path for @object must be in the hierarchy rooted by the
23361 * object path for @manager.
23363 * Note that @manager will take a reference on @object for as long as
23371 * g_dbus_object_manager_server_export_uniquely:
23372 * @manager: A #GDBusObjectManagerServer.
23373 * @object: An object.
23375 * Like g_dbus_object_manager_server_export() but appends a string of
23376 * the form <literal>_N</literal> (with N being a natural number) to
23377 * @object<!-- -->'s object path if an object with the given path
23378 * already exists. As such, the #GDBusObjectProxy:g-object-path property
23379 * of @object may be modified.
23386 * g_dbus_object_manager_server_get_connection:
23387 * @manager: A #GDBusObjectManagerServer
23389 * Gets the #GDBusConnection used by @manager.
23391 * @manager isn't exported on a connection. The returned object should
23392 * be freed with g_object_unref().
23394 * Returns: (transfer full): A #GDBusConnection object or %NULL if
23400 * g_dbus_object_manager_server_new:
23401 * @object_path: The object path to export the manager object at.
23403 * Creates a new #GDBusObjectManagerServer object.
23405 * The returned server isn't yet exported on any connection. To do so,
23406 * use g_dbus_object_manager_server_set_connection(). Normally you
23407 * want to export all of your objects before doing so to avoid <ulink
23408 * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">InterfacesAdded</ulink>
23409 * signals being emitted.
23411 * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref().
23417 * g_dbus_object_manager_server_set_connection:
23418 * @manager: A #GDBusObjectManagerServer.
23419 * @connection: (allow-none): A #GDBusConnection or %NULL.
23421 * Exports all objects managed by @manager on @connection. If
23422 * @connection is %NULL, stops exporting objects.
23427 * g_dbus_object_manager_server_unexport:
23428 * @manager: A #GDBusObjectManagerServer.
23429 * @object_path: An object path.
23431 * If @manager has an object at @path, removes the object. Otherwise
23434 * Note that @object_path must be in the hierarchy rooted by the
23435 * object path for @manager.
23437 * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise.
23443 * g_dbus_object_proxy_get_connection:
23444 * @proxy: a #GDBusObjectProxy
23446 * Gets the connection that @proxy is for.
23448 * object is owned by @proxy.
23450 * Returns: (transfer none): A #GDBusConnection. Do not free, the
23456 * g_dbus_object_proxy_new:
23457 * @connection: a #GDBusConnection
23458 * @object_path: the object path
23460 * Creates a new #GDBusObjectProxy for the given connection and
23463 * Returns: a new #GDBusObjectProxy
23469 * g_dbus_object_skeleton_add_interface:
23470 * @object: A #GDBusObjectSkeleton.
23471 * @interface_: A #GDBusInterfaceSkeleton.
23473 * Adds @interface_ to @object.
23475 * If @object already contains a #GDBusInterfaceSkeleton with the same
23476 * interface name, it is removed before @interface_ is added.
23478 * Note that @object takes its own reference on @interface_ and holds
23479 * it until removed.
23486 * g_dbus_object_skeleton_flush:
23487 * @object: A #GDBusObjectSkeleton.
23489 * This method simply calls g_dbus_interface_skeleton_flush() on all
23490 * interfaces belonging to @object. See that method for when flushing
23498 * g_dbus_object_skeleton_new:
23499 * @object_path: An object path.
23501 * Creates a new #GDBusObjectSkeleton.
23503 * Returns: A #GDBusObjectSkeleton. Free with g_object_unref().
23509 * g_dbus_object_skeleton_remove_interface:
23510 * @object: A #GDBusObjectSkeleton.
23511 * @interface_: A #GDBusInterfaceSkeleton.
23513 * Removes @interface_ from @object.
23520 * g_dbus_object_skeleton_remove_interface_by_name:
23521 * @object: A #GDBusObjectSkeleton.
23522 * @interface_name: A D-Bus interface name.
23524 * Removes the #GDBusInterface with @interface_name from @object.
23526 * If no D-Bus interface of the given interface exists, this function
23534 * g_dbus_object_skeleton_set_object_path:
23535 * @object: A #GDBusObjectSkeleton.
23536 * @object_path: A valid D-Bus object path.
23538 * Sets the object path for @object.
23545 * g_dbus_property_info_ref:
23546 * @info: A #GDBusPropertyInfo
23548 * If @info is statically allocated does nothing. Otherwise increases
23549 * the reference count.
23551 * Returns: The same @info.
23557 * g_dbus_property_info_unref:
23558 * @info: A #GDBusPropertyInfo.
23560 * If @info is statically allocated, does nothing. Otherwise decreases
23561 * the reference count of @info. When its reference count drops to 0,
23562 * the memory used is freed.
23569 * g_dbus_proxy_call:
23570 * @proxy: A #GDBusProxy.
23571 * @method_name: Name of method to invoke.
23572 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
23573 * @flags: Flags from the #GDBusCallFlags enumeration.
23574 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
23575 * @cancellable: A #GCancellable or %NULL.
23576 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation.
23577 * @user_data: The data to pass to @callback.
23579 * Asynchronously invokes the @method_name method on @proxy.
23581 * If @method_name contains any dots, then @name is split into interface and
23582 * method name parts. This allows using @proxy for invoking methods on
23583 * other interfaces.
23585 * If the #GDBusConnection associated with @proxy is closed then
23586 * the operation will fail with %G_IO_ERROR_CLOSED. If
23587 * @cancellable is canceled, the operation will fail with
23588 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
23589 * compatible with the D-Bus protocol, the operation fails with
23590 * %G_IO_ERROR_INVALID_ARGUMENT.
23592 * If the @parameters #GVariant is floating, it is consumed. This allows
23593 * convenient 'inline' use of g_variant_new(), e.g.:
23595 * g_dbus_proxy_call (proxy,
23597 * g_variant_new ("(ss)",
23600 * G_DBUS_CALL_FLAGS_NONE,
23603 * (GAsyncReadyCallback) two_strings_done,
23607 * If @proxy has an expected interface (see
23608 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
23609 * then the return value is checked against the return type.
23611 * This is an asynchronous method. When the operation is finished,
23612 * @callback will be invoked in the
23613 * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
23614 * of the thread you are calling this method from.
23615 * You can then call g_dbus_proxy_call_finish() to get the result of
23616 * the operation. See g_dbus_proxy_call_sync() for the synchronous
23617 * version of this method.
23619 * If @callback is %NULL then the D-Bus method call message will be sent with
23620 * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.
23627 * g_dbus_proxy_call_finish:
23628 * @proxy: A #GDBusProxy.
23629 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call().
23630 * @error: Return location for error or %NULL.
23632 * Finishes an operation started with g_dbus_proxy_call().
23634 * return values. Free with g_variant_unref().
23636 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
23642 * g_dbus_proxy_call_sync:
23643 * @proxy: A #GDBusProxy.
23644 * @method_name: Name of method to invoke.
23645 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
23646 * @flags: Flags from the #GDBusCallFlags enumeration.
23647 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
23648 * @cancellable: A #GCancellable or %NULL.
23649 * @error: Return location for error or %NULL.
23651 * Synchronously invokes the @method_name method on @proxy.
23653 * If @method_name contains any dots, then @name is split into interface and
23654 * method name parts. This allows using @proxy for invoking methods on
23655 * other interfaces.
23657 * If the #GDBusConnection associated with @proxy is disconnected then
23658 * the operation will fail with %G_IO_ERROR_CLOSED. If
23659 * @cancellable is canceled, the operation will fail with
23660 * %G_IO_ERROR_CANCELLED. If @parameters contains a value not
23661 * compatible with the D-Bus protocol, the operation fails with
23662 * %G_IO_ERROR_INVALID_ARGUMENT.
23664 * If the @parameters #GVariant is floating, it is consumed. This allows
23665 * convenient 'inline' use of g_variant_new(), e.g.:
23667 * g_dbus_proxy_call_sync (proxy,
23669 * g_variant_new ("(ss)",
23672 * G_DBUS_CALL_FLAGS_NONE,
23678 * The calling thread is blocked until a reply is received. See
23679 * g_dbus_proxy_call() for the asynchronous version of this
23682 * If @proxy has an expected interface (see
23683 * #GDBusProxy:g-interface-info) and @method_name is referenced by it,
23684 * then the return value is checked against the return type.
23686 * return values. Free with g_variant_unref().
23688 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
23694 * g_dbus_proxy_call_with_unix_fd_list:
23695 * @proxy: A #GDBusProxy.
23696 * @method_name: Name of method to invoke.
23697 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
23698 * @flags: Flags from the #GDBusCallFlags enumeration.
23699 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
23700 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
23701 * @cancellable: A #GCancellable or %NULL.
23702 * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation.
23703 * @user_data: The data to pass to @callback.
23705 * Like g_dbus_proxy_call() but also takes a #GUnixFDList object.
23707 * This method is only available on UNIX.
23714 * g_dbus_proxy_call_with_unix_fd_list_finish:
23715 * @proxy: A #GDBusProxy.
23716 * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
23717 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().
23718 * @error: Return location for error or %NULL.
23720 * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
23722 * return values. Free with g_variant_unref().
23724 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
23730 * g_dbus_proxy_call_with_unix_fd_list_sync:
23731 * @proxy: A #GDBusProxy.
23732 * @method_name: Name of method to invoke.
23733 * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters.
23734 * @flags: Flags from the #GDBusCallFlags enumeration.
23735 * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
23736 * @fd_list: (allow-none): A #GUnixFDList or %NULL.
23737 * @out_fd_list: (out): Return location for a #GUnixFDList or %NULL.
23738 * @cancellable: A #GCancellable or %NULL.
23739 * @error: Return location for error or %NULL.
23741 * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects.
23743 * This method is only available on UNIX.
23745 * return values. Free with g_variant_unref().
23747 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
23753 * g_dbus_proxy_get_cached_property:
23754 * @proxy: A #GDBusProxy.
23755 * @property_name: Property name.
23757 * Looks up the value for a property from the cache. This call does no
23760 * If @proxy has an expected interface (see
23761 * #GDBusProxy:g-interface-info) and @property_name is referenced by
23762 * it, then @value is checked against the type of the property.
23764 * for @property_name or %NULL if the value is not in the cache. The
23765 * returned reference must be freed with g_variant_unref().
23767 * Returns: A reference to the #GVariant instance that holds the value
23773 * g_dbus_proxy_get_cached_property_names:
23774 * @proxy: A #GDBusProxy.
23776 * Gets the names of all cached properties on @proxy.
23778 * @proxy has no cached properties. Free the returned array with
23781 * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
23787 * g_dbus_proxy_get_connection:
23788 * @proxy: A #GDBusProxy.
23790 * Gets the connection @proxy is for.
23792 * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
23798 * g_dbus_proxy_get_default_timeout:
23799 * @proxy: A #GDBusProxy.
23801 * Gets the timeout to use if -1 (specifying default timeout) is
23802 * passed as @timeout_msec in the g_dbus_proxy_call() and
23803 * g_dbus_proxy_call_sync() functions.
23805 * See the #GDBusProxy:g-default-timeout property for more details.
23807 * Returns: Timeout to use for @proxy.
23813 * g_dbus_proxy_get_flags:
23814 * @proxy: A #GDBusProxy.
23816 * Gets the flags that @proxy was constructed with.
23818 * Returns: Flags from the #GDBusProxyFlags enumeration.
23824 * g_dbus_proxy_get_interface_info:
23825 * @proxy: A #GDBusProxy
23827 * Returns the #GDBusInterfaceInfo, if any, specifying the interface
23828 * that @proxy conforms to. See the #GDBusProxy:g-interface-info
23829 * property for more details.
23831 * object, it is owned by @proxy.
23833 * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
23839 * g_dbus_proxy_get_interface_name:
23840 * @proxy: A #GDBusProxy.
23842 * Gets the D-Bus interface name @proxy is for.
23844 * Returns: A string owned by @proxy. Do not free.
23850 * g_dbus_proxy_get_name:
23851 * @proxy: A #GDBusProxy.
23853 * Gets the name that @proxy was constructed for.
23855 * Returns: A string owned by @proxy. Do not free.
23861 * g_dbus_proxy_get_name_owner:
23862 * @proxy: A #GDBusProxy.
23864 * The unique name that owns the name that @proxy is for or %NULL if
23865 * no-one currently owns that name. You may connect to the
23866 * #GObject::notify signal to track changes to the
23867 * #GDBusProxy:g-name-owner property.
23869 * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
23875 * g_dbus_proxy_get_object_path:
23876 * @proxy: A #GDBusProxy.
23878 * Gets the object path @proxy is for.
23880 * Returns: A string owned by @proxy. Do not free.
23886 * g_dbus_proxy_new:
23887 * @connection: A #GDBusConnection.
23888 * @flags: Flags used when constructing the proxy.
23889 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
23890 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
23891 * @object_path: An object path.
23892 * @interface_name: A D-Bus interface name.
23893 * @cancellable: A #GCancellable or %NULL.
23894 * @callback: Callback function to invoke when the proxy is ready.
23895 * @user_data: User data to pass to @callback.
23897 * Creates a proxy for accessing @interface_name on the remote object
23898 * at @object_path owned by @name at @connection and asynchronously
23899 * loads D-Bus properties unless the
23900 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to
23901 * the #GDBusProxy::g-properties-changed signal to get notified about
23902 * property changes.
23904 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
23905 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
23906 * to handle signals from the remote object.
23908 * If @name is a well-known name and the
23909 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name
23910 * owner currently exists, the message bus will be requested to launch
23911 * a name owner for the name.
23913 * This is a failable asynchronous constructor - when the proxy is
23914 * ready, @callback will be invoked and you can use
23915 * g_dbus_proxy_new_finish() to get the result.
23917 * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
23919 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
23926 * g_dbus_proxy_new_finish:
23927 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new().
23928 * @error: Return location for error or %NULL.
23930 * Finishes creating a #GDBusProxy.
23932 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
23938 * g_dbus_proxy_new_for_bus:
23939 * @bus_type: A #GBusType.
23940 * @flags: Flags used when constructing the proxy.
23941 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
23942 * @name: A bus name (well-known or unique).
23943 * @object_path: An object path.
23944 * @interface_name: A D-Bus interface name.
23945 * @cancellable: A #GCancellable or %NULL.
23946 * @callback: Callback function to invoke when the proxy is ready.
23947 * @user_data: User data to pass to @callback.
23949 * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
23951 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
23958 * g_dbus_proxy_new_for_bus_finish:
23959 * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().
23960 * @error: Return location for error or %NULL.
23962 * Finishes creating a #GDBusProxy.
23964 * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
23970 * g_dbus_proxy_new_for_bus_sync:
23971 * @bus_type: A #GBusType.
23972 * @flags: Flags used when constructing the proxy.
23973 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
23974 * @name: A bus name (well-known or unique).
23975 * @object_path: An object path.
23976 * @interface_name: A D-Bus interface name.
23977 * @cancellable: A #GCancellable or %NULL.
23978 * @error: Return location for error or %NULL.
23980 * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
23982 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
23984 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
23990 * g_dbus_proxy_new_sync:
23991 * @connection: A #GDBusConnection.
23992 * @flags: Flags used when constructing the proxy.
23993 * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL.
23994 * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
23995 * @object_path: An object path.
23996 * @interface_name: A D-Bus interface name.
23997 * @cancellable: (allow-none): A #GCancellable or %NULL.
23998 * @error: (allow-none): Return location for error or %NULL.
24000 * Creates a proxy for accessing @interface_name on the remote object
24001 * at @object_path owned by @name at @connection and synchronously
24002 * loads D-Bus properties unless the
24003 * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.
24005 * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up
24006 * match rules for signals. Connect to the #GDBusProxy::g-signal signal
24007 * to handle signals from the remote object.
24009 * If @name is a well-known name and the
24010 * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name
24011 * owner currently exists, the message bus will be requested to launch
24012 * a name owner for the name.
24014 * This is a synchronous failable constructor. See g_dbus_proxy_new()
24015 * and g_dbus_proxy_new_finish() for the asynchronous version.
24017 * See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
24019 * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
24025 * g_dbus_proxy_set_cached_property:
24026 * @proxy: A #GDBusProxy
24027 * @property_name: Property name.
24028 * @value: (allow-none): Value for the property or %NULL to remove it from the cache.
24030 * If @value is not %NULL, sets the cached value for the property with
24031 * name @property_name to the value in @value.
24033 * If @value is %NULL, then the cached value is removed from the
24036 * If @proxy has an expected interface (see
24037 * #GDBusProxy:g-interface-info) and @property_name is referenced by
24038 * it, then @value is checked against the type of the property.
24040 * If the @value #GVariant is floating, it is consumed. This allows
24041 * convenient 'inline' use of g_variant_new(), e.g.
24043 * g_dbus_proxy_set_cached_property (proxy,
24045 * g_variant_new ("(si)",
24050 * Normally you will not need to use this method since @proxy is
24051 * tracking changes using the
24052 * <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
24053 * D-Bus signal. However, for performance reasons an object may decide
24054 * to not use this signal for some properties and instead use a
24055 * proprietary out-of-band mechanism to transmit changes.
24057 * As a concrete example, consider an object with a property
24058 * <literal>ChatroomParticipants</literal> which is an array of
24059 * strings. Instead of transmitting the same (long) array every time
24060 * the property changes, it is more efficient to only transmit the
24061 * delta using e.g. signals <literal>ChatroomParticipantJoined(String
24062 * name)</literal> and <literal>ChatroomParticipantParted(String
24070 * g_dbus_proxy_set_default_timeout:
24071 * @proxy: A #GDBusProxy.
24072 * @timeout_msec: Timeout in milliseconds.
24074 * Sets the timeout to use if -1 (specifying default timeout) is
24075 * passed as @timeout_msec in the g_dbus_proxy_call() and
24076 * g_dbus_proxy_call_sync() functions.
24078 * See the #GDBusProxy:g-default-timeout property for more details.
24085 * g_dbus_proxy_set_interface_info:
24086 * @proxy: A #GDBusProxy
24087 * @info: (allow-none): Minimum interface this proxy conforms to or %NULL to unset.
24089 * Ensure that interactions with @proxy conform to the given
24090 * interface. See the #GDBusProxy:g-interface-info property for more
24098 * g_dbus_server_get_client_address:
24099 * @server: A #GDBusServer.
24101 * Gets a D-Bus address string that can be used by clients to connect
24106 * Returns: A D-Bus address string. Do not free, the string is owned
24112 * g_dbus_server_get_flags:
24113 * @server: A #GDBusServer.
24115 * Gets the flags for @server.
24117 * Returns: A set of flags from the #GDBusServerFlags enumeration.
24123 * g_dbus_server_get_guid:
24124 * @server: A #GDBusServer.
24126 * Gets the GUID for @server.
24128 * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
24134 * g_dbus_server_is_active:
24135 * @server: A #GDBusServer.
24137 * Gets whether @server is active.
24139 * Returns: %TRUE if server is active, %FALSE otherwise.
24145 * g_dbus_server_new_sync:
24146 * @address: A D-Bus address.
24147 * @flags: Flags from the #GDBusServerFlags enumeration.
24148 * @guid: A D-Bus GUID.
24149 * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
24150 * @cancellable: A #GCancellable or %NULL.
24151 * @error: Return location for server or %NULL.
24153 * Creates a new D-Bus server that listens on the first address in
24154 * @address that works.
24156 * Once constructed, you can use g_dbus_server_get_client_address() to
24157 * get a D-Bus address string that clients can use to connect.
24159 * Connect to the #GDBusServer::new-connection signal to handle
24160 * incoming connections.
24162 * The returned #GDBusServer isn't active - you have to start it with
24163 * g_dbus_server_start().
24165 * See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can
24168 * This is a synchronous failable constructor. See
24169 * g_dbus_server_new() for the asynchronous version.
24171 * g_object_unref().
24173 * Returns: A #GDBusServer or %NULL if @error is set. Free with
24179 * g_dbus_server_start:
24180 * @server: A #GDBusServer.
24189 * g_dbus_server_stop:
24190 * @server: A #GDBusServer.
24199 * g_dbus_signal_info_ref:
24200 * @info: A #GDBusSignalInfo
24202 * If @info is statically allocated does nothing. Otherwise increases
24203 * the reference count.
24205 * Returns: The same @info.
24211 * g_dbus_signal_info_unref:
24212 * @info: A #GDBusSignalInfo.
24214 * If @info is statically allocated, does nothing. Otherwise decreases
24215 * the reference count of @info. When its reference count drops to 0,
24216 * the memory used is freed.
24223 * g_desktop_app_info_get_categories:
24224 * @info: a #GDesktopAppInfo
24226 * Gets the categories from the desktop file.
24228 * i.e. no attempt is made to split it by ';' or validate it.
24230 * Returns: The unparsed Categories key from the desktop file;
24235 * g_desktop_app_info_get_filename:
24236 * @info: a #GDesktopAppInfo
24238 * When @info was created from a known filename, return it. In some
24239 * situations such as the #GDesktopAppInfo returned from
24240 * g_desktop_app_info_new_from_keyfile(), this function will return %NULL.
24242 * Returns: The full path to the file for @info, or %NULL if not known.
24248 * g_desktop_app_info_get_generic_name:
24249 * @info: a #GDesktopAppInfo
24251 * Gets the generic name from the destkop file.
24253 * Returns: The value of the GenericName key
24258 * g_desktop_app_info_get_is_hidden:
24259 * @info: a #GDesktopAppInfo.
24261 * A desktop file is hidden if the Hidden key in it is
24264 * Returns: %TRUE if hidden, %FALSE otherwise.
24269 * g_desktop_app_info_get_keywords:
24270 * @info: a #GDesktopAppInfo
24272 * Gets the keywords from the desktop file.
24274 * Returns: (transfer none): The value of the Keywords key
24280 * g_desktop_app_info_get_nodisplay:
24281 * @info: a #GDesktopAppInfo
24283 * Gets the value of the NoDisplay key, which helps determine if the
24284 * application info should be shown in menus. See
24285 * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show().
24287 * Returns: The value of the NoDisplay key
24293 * g_desktop_app_info_get_show_in:
24294 * @info: a #GDesktopAppInfo
24295 * @desktop_env: a string specifying a desktop name
24297 * Checks if the application info should be shown in menus that list available
24298 * applications for a specific name of the desktop, based on the
24299 * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys.
24301 * If @desktop_env is %NULL, then the name of the desktop set with
24302 * g_desktop_app_info_set_desktop_env() is used.
24304 * Note that g_app_info_should_show() for @info will include this check (with
24305 * %NULL for @desktop_env) as well as additional checks.
24307 * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE
24310 * Returns: %TRUE if the @info should be shown in @desktop_env according to the
24316 * g_desktop_app_info_launch_uris_as_manager:
24317 * @appinfo: a #GDesktopAppInfo
24318 * @uris: (element-type utf8): List of URIs
24319 * @launch_context: a #GAppLaunchContext
24320 * @spawn_flags: #GSpawnFlags, used for each process
24321 * @user_setup: (scope call): a #GSpawnChildSetupFunc, used once for each process.
24322 * @user_setup_data: (closure user_setup): User data for @user_setup
24323 * @pid_callback: (scope call): Callback for child processes
24324 * @pid_callback_data: (closure pid_callback): User data for @callback
24325 * @error: return location for a #GError, or %NULL
24327 * This function performs the equivalent of g_app_info_launch_uris(),
24328 * but is intended primarily for operating system components that
24329 * launch applications. Ordinary applications should use
24330 * g_app_info_launch_uris().
24332 * In contrast to g_app_info_launch_uris(), all processes created will
24333 * always be run directly as children as if by the UNIX fork()/exec()
24336 * This guarantee allows additional control over the exact environment
24337 * of the child processes, which is provided via a setup function
24338 * @user_setup, as well as the process identifier of each child process
24339 * via @pid_callback. See g_spawn_async() for more information about the
24340 * semantics of the @user_setup function.
24342 * Returns: %TRUE on successful launch, %FALSE otherwise.
24347 * g_desktop_app_info_lookup_get_default_for_uri_scheme:
24348 * @lookup: a #GDesktopAppInfoLookup
24349 * @uri_scheme: a string containing a URI scheme.
24351 * Gets the default application for launching applications
24352 * using this URI scheme for a particular GDesktopAppInfoLookup
24355 * The GDesktopAppInfoLookup interface and this function is used
24356 * to implement g_app_info_get_default_for_uri_scheme() backends
24357 * in a GIO module. There is no reason for applications to use it
24358 * directly. Applications should use g_app_info_get_default_for_uri_scheme().
24360 * Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
24361 * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio.
24366 * g_desktop_app_info_new:
24367 * @desktop_id: the desktop file id
24369 * Creates a new #GDesktopAppInfo based on a desktop file id.
24371 * A desktop file id is the basename of the desktop file, including the
24372 * .desktop extension. GIO is looking for a desktop file with this name
24373 * in the <filename>applications</filename> subdirectories of the XDG data
24374 * directories (i.e. the directories specified in the
24375 * <envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment
24376 * variables). GIO also supports the prefix-to-subdirectory mapping that is
24377 * described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu Spec</ulink>
24378 * (i.e. a desktop id of kde-foo.desktop will match
24379 * <filename>/usr/share/applications/kde/foo.desktop</filename>).
24381 * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
24386 * g_desktop_app_info_new_from_filename:
24387 * @filename: the path of a desktop file, in the GLib filename encoding
24389 * Creates a new #GDesktopAppInfo.
24391 * Returns: a new #GDesktopAppInfo or %NULL on error.
24396 * g_desktop_app_info_new_from_keyfile:
24397 * @key_file: an opened #GKeyFile
24399 * Creates a new #GDesktopAppInfo.
24401 * Returns: a new #GDesktopAppInfo or %NULL on error.
24407 * g_desktop_app_info_set_desktop_env:
24408 * @desktop_env: a string specifying what desktop this is
24410 * Sets the name of the desktop that the application is running in.
24411 * This is used by g_app_info_should_show() and
24412 * g_desktop_app_info_get_show_in() to evaluate the
24413 * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal>
24414 * desktop entry fields.
24416 * The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop
24417 * Menu specification</ulink> recognizes the following:
24419 * <member>GNOME</member>
24420 * <member>KDE</member>
24421 * <member>ROX</member>
24422 * <member>XFCE</member>
24423 * <member>LXDE</member>
24424 * <member>Unity</member>
24425 * <member>Old</member>
24428 * Should be called only once; subsequent calls are ignored.
24433 * g_drive_can_eject:
24434 * @drive: a #GDrive.
24436 * Checks if a drive can be ejected.
24438 * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise.
24443 * g_drive_can_poll_for_media:
24444 * @drive: a #GDrive.
24446 * Checks if a drive can be polled for media changes.
24448 * %FALSE otherwise.
24450 * Returns: %TRUE if the @drive can be polled for media changes,
24455 * g_drive_can_start:
24456 * @drive: a #GDrive.
24458 * Checks if a drive can be started.
24460 * Returns: %TRUE if the @drive can be started, %FALSE otherwise.
24466 * g_drive_can_start_degraded:
24467 * @drive: a #GDrive.
24469 * Checks if a drive can be started degraded.
24471 * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise.
24477 * g_drive_can_stop:
24478 * @drive: a #GDrive.
24480 * Checks if a drive can be stopped.
24482 * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise.
24489 * @drive: a #GDrive.
24490 * @flags: flags affecting the unmount if required for eject
24491 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24492 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24493 * @user_data: user data to pass to @callback
24495 * Asynchronously ejects a drive.
24497 * When the operation is finished, @callback will be called.
24498 * You can then call g_drive_eject_finish() to obtain the
24499 * result of the operation.
24501 * Deprecated: 2.22: Use g_drive_eject_with_operation() instead.
24506 * g_drive_eject_finish:
24507 * @drive: a #GDrive.
24508 * @result: a #GAsyncResult.
24509 * @error: a #GError, or %NULL
24511 * Finishes ejecting a drive.
24513 * %FALSE otherwise.
24515 * Returns: %TRUE if the drive has been ejected successfully,
24516 * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
24521 * g_drive_eject_with_operation:
24522 * @drive: a #GDrive.
24523 * @flags: flags affecting the unmount if required for eject
24524 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
24525 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24526 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24527 * @user_data: user data passed to @callback.
24529 * Ejects a drive. This is an asynchronous operation, and is
24530 * finished by calling g_drive_eject_with_operation_finish() with the @drive
24531 * and #GAsyncResult data returned in the @callback.
24538 * g_drive_eject_with_operation_finish:
24539 * @drive: a #GDrive.
24540 * @result: a #GAsyncResult.
24541 * @error: a #GError location to store the error occurring, or %NULL to ignore.
24543 * Finishes ejecting a drive. If any errors occurred during the operation,
24544 * @error will be set to contain the errors and %FALSE will be returned.
24546 * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise.
24552 * g_drive_enumerate_identifiers:
24553 * @drive: a #GDrive
24555 * Gets the kinds of identifiers that @drive has.
24556 * Use g_drive_get_identifier() to obtain the identifiers
24559 * array of strings containing kinds of identifiers. Use g_strfreev()
24562 * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
24567 * g_drive_get_icon:
24568 * @drive: a #GDrive.
24570 * Gets the icon for @drive.
24572 * Free the returned object with g_object_unref().
24574 * Returns: (transfer full): #GIcon for the @drive.
24579 * g_drive_get_identifier:
24580 * @drive: a #GDrive
24581 * @kind: the kind of identifier to return
24583 * Gets the identifier of the given kind for @drive.
24585 * requested identfier, or %NULL if the #GDrive
24586 * doesn't have this kind of identifier.
24588 * Returns: a newly allocated string containing the
24593 * g_drive_get_name:
24594 * @drive: a #GDrive.
24596 * Gets the name of @drive.
24598 * string should be freed when no longer needed.
24600 * Returns: a string containing @drive's name. The returned
24605 * g_drive_get_sort_key:
24606 * @drive: A #GDrive.
24608 * Gets the sort key for @drive, if any.
24610 * Returns: Sorting key for @drive or %NULL if no such key is available.
24616 * g_drive_get_start_stop_type:
24617 * @drive: a #GDrive.
24619 * Gets a hint about how a drive can be started/stopped.
24621 * Returns: A value from the #GDriveStartStopType enumeration.
24627 * g_drive_get_volumes:
24628 * @drive: a #GDrive.
24630 * Get a list of mountable volumes for @drive.
24632 * The returned list should be freed with g_list_free(), after
24633 * its elements have been unreffed with g_object_unref().
24635 * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive.
24640 * g_drive_has_media:
24641 * @drive: a #GDrive.
24643 * Checks if the @drive has media. Note that the OS may not be polling
24644 * the drive for media changes; see g_drive_is_media_check_automatic()
24645 * for more details.
24647 * Returns: %TRUE if @drive has media, %FALSE otherwise.
24652 * g_drive_has_volumes:
24653 * @drive: a #GDrive.
24655 * Check if @drive has any mountable volumes.
24657 * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise.
24662 * g_drive_is_media_check_automatic:
24663 * @drive: a #GDrive.
24665 * Checks if @drive is capabable of automatically detecting media changes.
24667 * media changes, %FALSE otherwise.
24669 * Returns: %TRUE if the @drive is capabable of automatically detecting
24674 * g_drive_is_media_removable:
24675 * @drive: a #GDrive.
24677 * Checks if the @drive supports removable media.
24679 * Returns: %TRUE if @drive supports removable media, %FALSE otherwise.
24684 * g_drive_poll_for_media:
24685 * @drive: a #GDrive.
24686 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24687 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24688 * @user_data: user data to pass to @callback
24690 * Asynchronously polls @drive to see if media has been inserted or removed.
24692 * When the operation is finished, @callback will be called.
24693 * You can then call g_drive_poll_for_media_finish() to obtain the
24694 * result of the operation.
24699 * g_drive_poll_for_media_finish:
24700 * @drive: a #GDrive.
24701 * @result: a #GAsyncResult.
24702 * @error: a #GError, or %NULL
24704 * Finishes an operation started with g_drive_poll_for_media() on a drive.
24706 * %FALSE otherwise.
24708 * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
24714 * @drive: a #GDrive.
24715 * @flags: flags affecting the start operation.
24716 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
24717 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24718 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24719 * @user_data: user data to pass to @callback
24721 * Asynchronously starts a drive.
24723 * When the operation is finished, @callback will be called.
24724 * You can then call g_drive_start_finish() to obtain the
24725 * result of the operation.
24732 * g_drive_start_finish:
24733 * @drive: a #GDrive.
24734 * @result: a #GAsyncResult.
24735 * @error: a #GError, or %NULL
24737 * Finishes starting a drive.
24739 * %FALSE otherwise.
24741 * Returns: %TRUE if the drive has been started successfully,
24748 * @drive: a #GDrive.
24749 * @flags: flags affecting the unmount if required for stopping.
24750 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
24751 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24752 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
24753 * @user_data: user data to pass to @callback
24755 * Asynchronously stops a drive.
24757 * When the operation is finished, @callback will be called.
24758 * You can then call g_drive_stop_finish() to obtain the
24759 * result of the operation.
24766 * g_drive_stop_finish:
24767 * @drive: a #GDrive.
24768 * @result: a #GAsyncResult.
24769 * @error: a #GError, or %NULL
24771 * Finishes stopping a drive.
24773 * %FALSE otherwise.
24775 * Returns: %TRUE if the drive has been stopped successfully,
24781 * g_emblem_get_icon:
24782 * @emblem: a #GEmblem from which the icon should be extracted.
24784 * Gives back the icon from @emblem.
24786 * the emblem and should not be modified or freed.
24788 * Returns: (transfer none): a #GIcon. The returned object belongs to
24794 * g_emblem_get_origin:
24795 * @emblem: a #GEmblem
24797 * Gets the origin of the emblem.
24799 * Returns: (transfer none): the origin of the emblem
24806 * @icon: a GIcon containing the icon.
24808 * Creates a new emblem for @icon.
24810 * Returns: a new #GEmblem.
24816 * g_emblem_new_with_origin:
24817 * @icon: a GIcon containing the icon.
24818 * @origin: a GEmblemOrigin enum defining the emblem's origin
24820 * Creates a new emblem for @icon.
24822 * Returns: a new #GEmblem.
24828 * g_emblemed_icon_add_emblem:
24829 * @emblemed: a #GEmblemedIcon
24830 * @emblem: a #GEmblem
24832 * Adds @emblem to the #GList of #GEmblem <!-- -->s.
24839 * g_emblemed_icon_clear_emblems:
24840 * @emblemed: a #GEmblemedIcon
24842 * Removes all the emblems from @icon.
24849 * g_emblemed_icon_get_emblems:
24850 * @emblemed: a #GEmblemedIcon
24852 * Gets the list of emblems for the @icon.
24854 * #GEmblem <!-- -->s that is owned by @emblemed
24856 * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
24862 * g_emblemed_icon_get_icon:
24863 * @emblemed: a #GEmblemedIcon
24865 * Gets the main icon for @emblemed.
24867 * Returns: (transfer none): a #GIcon that is owned by @emblemed
24873 * g_emblemed_icon_new:
24875 * @emblem: (allow-none): a #GEmblem, or %NULL
24877 * Creates a new emblemed icon for @icon with the emblem @emblem.
24879 * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon
24885 * g_file_append_to:
24886 * @file: input #GFile.
24887 * @flags: a set of #GFileCreateFlags.
24888 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24889 * @error: a #GError, or %NULL
24891 * Gets an output stream for appending data to the file. If
24892 * the file doesn't already exist it is created.
24894 * By default files created are generally readable by everyone,
24895 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
24896 * will be made readable only to the current user, to the level that
24897 * is supported on the target filesystem.
24899 * If @cancellable is not %NULL, then the operation can be cancelled by
24900 * triggering the cancellable object from another thread. If the operation
24901 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
24903 * Some file systems don't allow all file names, and may
24904 * return an %G_IO_ERROR_INVALID_FILENAME error.
24905 * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will be
24906 * returned. Other errors are possible too, and depend on what kind of
24907 * filesystem the file is on.
24909 * Free the returned object with g_object_unref().
24911 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
24916 * g_file_append_to_async:
24917 * @file: input #GFile.
24918 * @flags: a set of #GFileCreateFlags.
24919 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
24920 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
24921 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
24922 * @user_data: (closure): the data to pass to callback function
24924 * Asynchronously opens @file for appending.
24926 * For more details, see g_file_append_to() which is
24927 * the synchronous version of this call.
24929 * When the operation is finished, @callback will be called. You can then call
24930 * g_file_append_to_finish() to get the result of the operation.
24935 * g_file_append_to_finish:
24936 * @file: input #GFile.
24937 * @res: #GAsyncResult
24938 * @error: a #GError, or %NULL
24940 * Finishes an asynchronous file append operation started with
24941 * g_file_append_to_async().
24943 * Free the returned object with g_object_unref().
24945 * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error.
24950 * g_file_attribute_info_list_add:
24951 * @list: a #GFileAttributeInfoList.
24952 * @name: the name of the attribute to add.
24953 * @type: the #GFileAttributeType for the attribute.
24954 * @flags: #GFileAttributeInfoFlags for the attribute.
24956 * Adds a new attribute with @name to the @list, setting
24957 * its @type and @flags.
24962 * g_file_attribute_info_list_dup:
24963 * @list: a #GFileAttributeInfoList to duplicate.
24965 * Makes a duplicate of a file attribute info list.
24967 * Returns: a copy of the given @list.
24972 * g_file_attribute_info_list_lookup:
24973 * @list: a #GFileAttributeInfoList.
24974 * @name: the name of the attribute to lookup.
24976 * Gets the file attribute with the name @name from @list.
24978 * attribute isn't found.
24980 * Returns: a #GFileAttributeInfo for the @name, or %NULL if an
24985 * g_file_attribute_info_list_new:
24987 * Creates a new file attribute info list.
24989 * Returns: a #GFileAttributeInfoList.
24994 * g_file_attribute_info_list_ref:
24995 * @list: a #GFileAttributeInfoList to reference.
24997 * References a file attribute info list.
24999 * Returns: #GFileAttributeInfoList or %NULL on error.
25004 * g_file_attribute_info_list_unref:
25005 * @list: The #GFileAttributeInfoList to unreference.
25007 * Removes a reference from the given @list. If the reference count
25008 * falls to zero, the @list is deleted.
25013 * g_file_attribute_matcher_enumerate_namespace:
25014 * @matcher: a #GFileAttributeMatcher.
25015 * @ns: a string containing a file attribute namespace.
25017 * Checks if the matcher will match all of the keys in a given namespace.
25018 * This will always return %TRUE if a wildcard character is in use (e.g. if
25019 * matcher was created with "standard::*" and @ns is "standard", or if matcher was created
25020 * using "*" and namespace is anything.)
25022 * TODO: this is awkwardly worded.
25024 * in the given @ns, %FALSE otherwise.
25026 * Returns: %TRUE if the matcher matches all of the entries
25031 * g_file_attribute_matcher_enumerate_next:
25032 * @matcher: a #GFileAttributeMatcher.
25034 * Gets the next matched attribute from a #GFileAttributeMatcher.
25036 * no more attribute exist.
25038 * Returns: a string containing the next attribute or %NULL if
25043 * g_file_attribute_matcher_matches:
25044 * @matcher: a #GFileAttributeMatcher.
25045 * @attribute: a file attribute key.
25047 * Checks if an attribute will be matched by an attribute matcher. If
25048 * the matcher was created with the "*" matching string, this function
25049 * will always return %TRUE.
25051 * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
25056 * g_file_attribute_matcher_matches_only:
25057 * @matcher: a #GFileAttributeMatcher.
25058 * @attribute: a file attribute key.
25060 * Checks if a attribute matcher only matches a given attribute. Always
25061 * returns %FALSE if "*" was used when creating the matcher.
25063 * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
25068 * g_file_attribute_matcher_new:
25069 * @attributes: an attribute string to match.
25071 * Creates a new file attribute matcher, which matches attributes
25072 * against a given string. #GFileAttributeMatcher<!-- -->s are reference
25073 * counted structures, and are created with a reference count of 1. If
25074 * the number of references falls to 0, the #GFileAttributeMatcher is
25075 * automatically destroyed.
25077 * The @attribute string should be formatted with specific keys separated
25078 * from namespaces with a double colon. Several "namespace::key" strings may be
25079 * concatenated with a single comma (e.g. "standard::type,standard::is-hidden").
25080 * The wildcard "*" may be used to match all keys and namespaces, or
25081 * "namespace::*" will match all keys in a given namespace.
25083 * Examples of strings to use:
25085 * <title>File Attribute Matcher strings and results</title>
25086 * <tgroup cols='2' align='left'><thead>
25087 * <row><entry> Matcher String </entry><entry> Matches </entry></row></thead>
25089 * <row><entry>"*"</entry><entry>matches all attributes.</entry></row>
25090 * <row><entry>"standard::is-hidden"</entry><entry>matches only the key is-hidden in the standard namespace.</entry></row>
25091 * <row><entry>"standard::type,unix::*"</entry><entry>matches the type key in the standard namespace and
25092 * all keys in the unix namespace.</entry></row>
25093 * </tbody></tgroup>
25096 * Returns: a #GFileAttributeMatcher.
25101 * g_file_attribute_matcher_ref:
25102 * @matcher: a #GFileAttributeMatcher.
25104 * References a file attribute matcher.
25106 * Returns: a #GFileAttributeMatcher.
25111 * g_file_attribute_matcher_subtract:
25112 * @matcher: Matcher to subtract from
25113 * @subtract: The matcher to subtract
25115 * Subtracts all attributes of @subtract from @matcher and returns
25116 * a matcher that supports those attributes.
25118 * Note that currently it is not possible to remove a single
25119 * attribute when the @matcher matches the whole namespace - or remove
25120 * a namespace or attribute when the matcher matches everything. This
25121 * is a limitation of the current implementation, but may be fixed
25124 * @matcher that are not matched by @subtract
25126 * Returns: A file attribute matcher matching all attributes of
25131 * g_file_attribute_matcher_to_string:
25132 * @matcher: (allow-none): a #GFileAttributeMatcher.
25134 * Prints what the matcher is matching against. The format will be
25135 * equal to the format passed to g_file_attribute_matcher_new().
25136 * The output however, might not be identical, as the matcher may
25137 * decide to use a different order or omit needless parts.
25139 * against or %NULL if @matcher was %NULL.
25141 * Returns: a string describing the attributes the matcher matches
25147 * g_file_attribute_matcher_unref:
25148 * @matcher: a #GFileAttributeMatcher.
25150 * Unreferences @matcher. If the reference count falls below 1,
25151 * the @matcher is automatically freed.
25157 * @source: input #GFile.
25158 * @destination: destination #GFile
25159 * @flags: set of #GFileCopyFlags
25160 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
25161 * @progress_callback: (allow-none) (scope call): function to callback with progress information, or %NULL if progress information is not needed
25162 * @progress_callback_data: (closure): user data to pass to @progress_callback
25163 * @error: #GError to set on error, or %NULL
25165 * Copies the file @source to the location specified by @destination.
25166 * Can not handle recursive copies of directories.
25168 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
25169 * existing @destination file is overwritten.
25171 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
25172 * will be copied as symlinks, otherwise the target of the
25173 * @source symlink will be copied.
25175 * If @cancellable is not %NULL, then the operation can be cancelled by
25176 * triggering the cancellable object from another thread. If the operation
25177 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25179 * If @progress_callback is not %NULL, then the operation can be monitored by
25180 * setting this to a #GFileProgressCallback function. @progress_callback_data
25181 * will be passed to this function. It is guaranteed that this callback will
25182 * be called after all data has been transferred with the total number of bytes
25183 * copied during the operation.
25185 * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND
25186 * error is returned, independent on the status of the @destination.
25188 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the
25189 * error G_IO_ERROR_EXISTS is returned.
25191 * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY
25192 * error is returned. If trying to overwrite a directory with a directory the
25193 * G_IO_ERROR_WOULD_MERGE error is returned.
25195 * If the source is a directory and the target does not exist, or
25196 * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the
25197 * G_IO_ERROR_WOULD_RECURSE error is returned.
25199 * If you are interested in copying the #GFile object itself (not the on-disk
25200 * file), see g_file_dup().
25202 * Returns: %TRUE on success, %FALSE otherwise.
25207 * g_file_copy_async: (skip)
25208 * @source: input #GFile.
25209 * @destination: destination #GFile
25210 * @flags: set of #GFileCopyFlags
25211 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
25212 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
25213 * @progress_callback: (allow-none): function to callback with progress information, or %NULL if progress information is not needed
25214 * @progress_callback_data: (closure): user data to pass to @progress_callback
25215 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
25216 * @user_data: the data to pass to callback function
25218 * Copies the file @source to the location specified by @destination
25219 * asynchronously. For details of the behaviour, see g_file_copy().
25221 * If @progress_callback is not %NULL, then that function that will be called
25222 * just like in g_file_copy(), however the callback will run in the main loop,
25223 * not in the thread that is doing the I/O operation.
25225 * When the operation is finished, @callback will be called. You can then call
25226 * g_file_copy_finish() to get the result of the operation.
25231 * g_file_copy_attributes:
25232 * @source: a #GFile with attributes.
25233 * @destination: a #GFile to copy attributes to.
25234 * @flags: a set of #GFileCopyFlags.
25235 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25236 * @error: a #GError, %NULL to ignore.
25238 * Copies the file attributes from @source to @destination.
25240 * Normally only a subset of the file attributes are copied,
25241 * those that are copies in a normal file copy operation
25242 * (which for instance does not include e.g. owner). However
25243 * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then
25244 * all the metadata that is possible to copy is copied. This
25245 * is useful when implementing move by copy + delete source.
25247 * Returns: %TRUE if the attributes were copied successfully, %FALSE otherwise.
25252 * g_file_copy_finish:
25253 * @file: input #GFile.
25254 * @res: a #GAsyncResult.
25255 * @error: a #GError, or %NULL
25257 * Finishes copying the file started with
25258 * g_file_copy_async().
25260 * Returns: a %TRUE on success, %FALSE on error.
25266 * @file: input #GFile.
25267 * @flags: a set of #GFileCreateFlags.
25268 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25269 * @error: a #GError, or %NULL
25271 * Creates a new file and returns an output stream for writing to it.
25272 * The file must not already exist.
25274 * By default files created are generally readable by everyone,
25275 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
25276 * will be made readable only to the current user, to the level that
25277 * is supported on the target filesystem.
25279 * If @cancellable is not %NULL, then the operation can be cancelled by
25280 * triggering the cancellable object from another thread. If the operation
25281 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25283 * If a file or directory with this name already exists the G_IO_ERROR_EXISTS
25284 * error will be returned.
25285 * Some file systems don't allow all file names, and may
25286 * return an G_IO_ERROR_INVALID_FILENAME error, and if the name
25287 * is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned.
25288 * Other errors are possible too, and depend on what kind of
25289 * filesystem the file is on.
25292 * Free the returned object with g_object_unref().
25294 * Returns: (transfer full): a #GFileOutputStream for the newly created file, or
25299 * g_file_create_async:
25300 * @file: input #GFile.
25301 * @flags: a set of #GFileCreateFlags.
25302 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
25303 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25304 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
25305 * @user_data: (closure): the data to pass to callback function
25307 * Asynchronously creates a new file and returns an output stream for writing to it.
25308 * The file must not already exist.
25310 * For more details, see g_file_create() which is
25311 * the synchronous version of this call.
25313 * When the operation is finished, @callback will be called. You can then call
25314 * g_file_create_finish() to get the result of the operation.
25319 * g_file_create_finish:
25320 * @file: input #GFile.
25321 * @res: a #GAsyncResult.
25322 * @error: a #GError, or %NULL
25324 * Finishes an asynchronous file create operation started with
25325 * g_file_create_async().
25327 * Free the returned object with g_object_unref().
25329 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
25334 * g_file_create_readwrite:
25336 * @flags: a set of #GFileCreateFlags
25337 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
25338 * @error: return location for a #GError, or %NULL
25340 * Creates a new file and returns a stream for reading and writing to it.
25341 * The file must not already exist.
25343 * By default files created are generally readable by everyone,
25344 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
25345 * will be made readable only to the current user, to the level that
25346 * is supported on the target filesystem.
25348 * If @cancellable is not %NULL, then the operation can be cancelled by
25349 * triggering the cancellable object from another thread. If the operation
25350 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25352 * If a file or directory with this name already exists the %G_IO_ERROR_EXISTS
25353 * error will be returned. Some file systems don't allow all file names,
25354 * and may return an %G_IO_ERROR_INVALID_FILENAME error, and if the name
25355 * is too long, %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors
25356 * are possible too, and depend on what kind of filesystem the file is on.
25358 * Note that in many non-local file cases read and write streams are not
25359 * supported, so make sure you really need to do read and write streaming,
25360 * rather than just opening for reading or writing.
25362 * Free the returned object with g_object_unref().
25364 * Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error.
25370 * g_file_create_readwrite_async:
25371 * @file: input #GFile
25372 * @flags: a set of #GFileCreateFlags
25373 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request
25374 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
25375 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
25376 * @user_data: (closure): the data to pass to callback function
25378 * Asynchronously creates a new file and returns a stream for reading and
25379 * writing to it. The file must not already exist.
25381 * For more details, see g_file_create_readwrite() which is
25382 * the synchronous version of this call.
25384 * When the operation is finished, @callback will be called. You can then
25385 * call g_file_create_readwrite_finish() to get the result of the operation.
25392 * g_file_create_readwrite_finish:
25393 * @file: input #GFile
25394 * @res: a #GAsyncResult
25395 * @error: a #GError, or %NULL
25397 * Finishes an asynchronous file create operation started with
25398 * g_file_create_readwrite_async().
25400 * Free the returned object with g_object_unref().
25402 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
25409 * @file: input #GFile.
25410 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25411 * @error: a #GError, or %NULL
25413 * Deletes a file. If the @file is a directory, it will only be deleted if it
25416 * If @cancellable is not %NULL, then the operation can be cancelled by
25417 * triggering the cancellable object from another thread. If the operation
25418 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25420 * Virtual: delete_file
25421 * Returns: %TRUE if the file was deleted. %FALSE otherwise.
25426 * g_file_descriptor_based_get_fd:
25427 * @fd_based: a #GFileDescriptorBased.
25429 * Gets the underlying file descriptor.
25431 * Returns: The file descriptor
25438 * @file: input #GFile.
25440 * Duplicates a #GFile handle. This operation does not duplicate
25441 * the actual file or directory represented by the #GFile; see
25442 * g_file_copy() if attempting to copy a file.
25444 * This call does no blocking i/o.
25446 * Returns: (transfer full): a new #GFile that is a duplicate of the given #GFile.
25451 * g_file_eject_mountable:
25452 * @file: input #GFile.
25453 * @flags: flags affecting the operation
25454 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25455 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
25456 * @user_data: (closure): the data to pass to callback function
25458 * Starts an asynchronous eject on a mountable.
25459 * When this operation has completed, @callback will be called with
25460 * @user_user data, and the operation can be finalized with
25461 * g_file_eject_mountable_finish().
25463 * If @cancellable is not %NULL, then the operation can be cancelled by
25464 * triggering the cancellable object from another thread. If the operation
25465 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25467 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead.
25472 * g_file_eject_mountable_finish:
25473 * @file: input #GFile.
25474 * @result: a #GAsyncResult.
25475 * @error: a #GError, or %NULL
25477 * Finishes an asynchronous eject operation started by
25478 * g_file_eject_mountable().
25482 * Returns: %TRUE if the @file was ejected successfully. %FALSE
25483 * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead.
25488 * g_file_eject_mountable_with_operation:
25489 * @file: input #GFile.
25490 * @flags: flags affecting the operation
25491 * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
25492 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25493 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
25494 * @user_data: (closure): the data to pass to callback function
25496 * Starts an asynchronous eject on a mountable.
25497 * When this operation has completed, @callback will be called with
25498 * @user_user data, and the operation can be finalized with
25499 * g_file_eject_mountable_with_operation_finish().
25501 * If @cancellable is not %NULL, then the operation can be cancelled by
25502 * triggering the cancellable object from another thread. If the operation
25503 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25510 * g_file_eject_mountable_with_operation_finish:
25511 * @file: input #GFile.
25512 * @result: a #GAsyncResult.
25513 * @error: a #GError, or %NULL
25515 * Finishes an asynchronous eject operation started by
25516 * g_file_eject_mountable_with_operation().
25520 * Returns: %TRUE if the @file was ejected successfully. %FALSE
25526 * g_file_enumerate_children:
25527 * @file: input #GFile.
25528 * @attributes: an attribute query string.
25529 * @flags: a set of #GFileQueryInfoFlags.
25530 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25531 * @error: #GError for error reporting.
25533 * Gets the requested information about the files in a directory. The result
25534 * is a #GFileEnumerator object that will give out #GFileInfo objects for
25535 * all the files in the directory.
25537 * The @attributes value is a string that specifies the file attributes that
25538 * should be gathered. It is not an error if it's not possible to read a particular
25539 * requested attribute from a file - it just won't be set. @attributes should
25540 * be a comma-separated list of attributes or attribute wildcards. The wildcard "*"
25541 * means all attributes, and a wildcard like "standard::*" means all attributes in the standard
25542 * namespace. An example attribute query be "standard::*,owner::user".
25543 * The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME.
25545 * If @cancellable is not %NULL, then the operation can be cancelled by
25546 * triggering the cancellable object from another thread. If the operation
25547 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25549 * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
25550 * If the file is not a directory, the G_FILE_ERROR_NOTDIR error will be returned.
25551 * Other errors are possible too.
25553 * Free the returned object with g_object_unref().
25555 * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error.
25560 * g_file_enumerate_children_async:
25561 * @file: input #GFile.
25562 * @attributes: an attribute query string.
25563 * @flags: a set of #GFileQueryInfoFlags.
25564 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
25565 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25566 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
25567 * @user_data: (closure): the data to pass to callback function
25569 * Asynchronously gets the requested information about the files in a directory. The result
25570 * is a #GFileEnumerator object that will give out #GFileInfo objects for
25571 * all the files in the directory.
25573 * For more details, see g_file_enumerate_children() which is
25574 * the synchronous version of this call.
25576 * When the operation is finished, @callback will be called. You can then call
25577 * g_file_enumerate_children_finish() to get the result of the operation.
25582 * g_file_enumerate_children_finish:
25583 * @file: input #GFile.
25584 * @res: a #GAsyncResult.
25585 * @error: a #GError.
25587 * Finishes an async enumerate children operation.
25588 * See g_file_enumerate_children_async().
25590 * Free the returned object with g_object_unref().
25592 * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred.
25597 * g_file_enumerator_close:
25598 * @enumerator: a #GFileEnumerator.
25599 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25600 * @error: location to store the error occurring, or %NULL to ignore
25602 * Releases all resources used by this enumerator, making the
25603 * enumerator return %G_IO_ERROR_CLOSED on all calls.
25605 * This will be automatically called when the last reference
25606 * is dropped, but you might want to call this function to make
25607 * sure resources are released as early as possible.
25609 * Returns: #TRUE on success or #FALSE on error.
25614 * g_file_enumerator_close_async:
25615 * @enumerator: a #GFileEnumerator.
25616 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
25617 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25618 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
25619 * @user_data: (closure): the data to pass to callback function
25621 * Asynchronously closes the file enumerator.
25623 * If @cancellable is not %NULL, then the operation can be cancelled by
25624 * triggering the cancellable object from another thread. If the operation
25625 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
25626 * g_file_enumerator_close_finish().
25631 * g_file_enumerator_close_finish:
25632 * @enumerator: a #GFileEnumerator.
25633 * @result: a #GAsyncResult.
25634 * @error: a #GError location to store the error occurring, or %NULL to ignore.
25636 * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
25638 * If the file enumerator was already closed when g_file_enumerator_close_async()
25639 * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
25640 * return %FALSE. If the file enumerator had pending operation when the close
25641 * operation was started, then this function will report %G_IO_ERROR_PENDING, and
25642 * return %FALSE. If @cancellable was not %NULL, then the operation may have been
25643 * cancelled by triggering the cancellable object from another thread. If the operation
25644 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
25647 * Returns: %TRUE if the close operation has finished successfully.
25652 * g_file_enumerator_get_container:
25653 * @enumerator: a #GFileEnumerator
25655 * Get the #GFile container which is being enumerated.
25657 * Returns: (transfer none): the #GFile which is being enumerated.
25663 * g_file_enumerator_has_pending:
25664 * @enumerator: a #GFileEnumerator.
25666 * Checks if the file enumerator has pending operations.
25668 * Returns: %TRUE if the @enumerator has pending operations.
25673 * g_file_enumerator_is_closed:
25674 * @enumerator: a #GFileEnumerator.
25676 * Checks if the file enumerator has been closed.
25678 * Returns: %TRUE if the @enumerator is closed.
25683 * g_file_enumerator_next_file:
25684 * @enumerator: a #GFileEnumerator.
25685 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25686 * @error: location to store the error occurring, or %NULL to ignore
25688 * Returns information for the next file in the enumerated object.
25689 * Will block until the information is available. The #GFileInfo
25690 * returned from this function will contain attributes that match the
25691 * attribute string that was passed when the #GFileEnumerator was created.
25693 * On error, returns %NULL and sets @error to the error. If the
25694 * enumerator is at the end, %NULL will be returned and @error will
25697 * Free the returned object with g_object_unref() when no longer needed.
25699 * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
25704 * g_file_enumerator_next_files_async:
25705 * @enumerator: a #GFileEnumerator.
25706 * @num_files: the number of file info objects to request
25707 * @io_priority: the <link linkend="gioscheduler">io priority</link> of the request.
25708 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25709 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
25710 * @user_data: (closure): the data to pass to callback function
25712 * Request information for a number of files from the enumerator asynchronously.
25713 * When all i/o for the operation is finished the @callback will be called with
25714 * the requested information.
25716 * The callback can be called with less than @num_files files in case of error
25717 * or at the end of the enumerator. In case of a partial error the callback will
25718 * be called with any succeeding items and no error, and on the next request the
25719 * error will be reported. If a request is cancelled the callback will be called
25720 * with %G_IO_ERROR_CANCELLED.
25722 * During an async request no other sync and async calls are allowed, and will
25723 * result in %G_IO_ERROR_PENDING errors.
25725 * Any outstanding i/o request with higher priority (lower numerical value) will
25726 * be executed before an outstanding request with lower priority. Default
25727 * priority is %G_PRIORITY_DEFAULT.
25732 * g_file_enumerator_next_files_finish:
25733 * @enumerator: a #GFileEnumerator.
25734 * @result: a #GAsyncResult.
25735 * @error: a #GError location to store the error occurring, or %NULL to ignore.
25737 * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
25739 * g_list_free() and unref the infos with g_object_unref() when you're
25742 * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
25747 * g_file_enumerator_set_pending:
25748 * @enumerator: a #GFileEnumerator.
25749 * @pending: a boolean value.
25751 * Sets the file enumerator as having pending operations.
25757 * @file1: the first #GFile.
25758 * @file2: the second #GFile.
25760 * Checks equality of two given #GFile<!-- -->s. Note that two
25761 * #GFile<!-- -->s that differ can still refer to the same
25762 * file on the filesystem due to various forms of filename
25765 * This call does no blocking i/o.
25767 * %FALSE if either is not a #GFile.
25769 * Returns: %TRUE if @file1 and @file2 are equal.
25774 * g_file_find_enclosing_mount:
25775 * @file: input #GFile.
25776 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25777 * @error: a #GError.
25779 * Gets a #GMount for the #GFile.
25781 * If the #GFileIface for @file does not have a mount (e.g. possibly a
25782 * remote share), @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL
25783 * will be returned.
25785 * If @cancellable is not %NULL, then the operation can be cancelled by
25786 * triggering the cancellable object from another thread. If the operation
25787 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
25789 * Free the returned object with g_object_unref().
25791 * Returns: (transfer full): a #GMount where the @file is located or %NULL on error.
25796 * g_file_find_enclosing_mount_async:
25798 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
25799 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
25800 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
25801 * @user_data: (closure): the data to pass to callback function
25803 * Asynchronously gets the mount for the file.
25805 * For more details, see g_file_find_enclosing_mount() which is
25806 * the synchronous version of this call.
25808 * When the operation is finished, @callback will be called. You can then call
25809 * g_file_find_enclosing_mount_finish() to get the result of the operation.
25814 * g_file_find_enclosing_mount_finish:
25816 * @res: a #GAsyncResult
25817 * @error: a #GError
25819 * Finishes an asynchronous find mount request.
25820 * See g_file_find_enclosing_mount_async().
25822 * Free the returned object with g_object_unref().
25824 * Returns: (transfer full): #GMount for given @file or %NULL on error.
25829 * g_file_get_basename:
25830 * @file: input #GFile.
25832 * Gets the base name (the last component of the path) for a given #GFile.
25834 * If called for the top level of a system (such as the filesystem root
25835 * or a uri like sftp://host/) it will return a single directory separator
25836 * (and on Windows, possibly a drive letter).
25838 * The base name is a byte string (*not* UTF-8). It has no defined encoding
25839 * or rules other than it may not contain zero bytes. If you want to use
25840 * filenames in a user interface you should use the display name that you
25841 * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME
25842 * attribute with g_file_query_info().
25844 * This call does no blocking i/o.
25846 * if given #GFile is invalid. The returned string should be
25847 * freed with g_free() when no longer needed.
25849 * Returns: string containing the #GFile's base name, or %NULL
25854 * g_file_get_child:
25855 * @file: input #GFile.
25856 * @name: string containing the child's basename.
25858 * Gets a child of @file with basename equal to @name.
25860 * Note that the file with that specific name might not exist, but
25861 * you can still have a #GFile that points to it. You can use this
25862 * for instance to create that file.
25864 * This call does no blocking i/o.
25866 * Free the returned object with g_object_unref().
25868 * Returns: (transfer full): a #GFile to a child specified by @name.
25873 * g_file_get_child_for_display_name:
25874 * @file: input #GFile.
25875 * @display_name: string to a possible child.
25878 * Gets the child of @file for a given @display_name (i.e. a UTF8
25879 * version of the name). If this function fails, it returns %NULL and @error will be
25880 * set. This is very useful when constructing a GFile for a new file
25881 * and the user entered the filename in the user interface, for instance
25882 * when you select a directory and type a filename in the file selector.
25884 * This call does no blocking i/o.
25886 * %NULL if the display name couldn't be converted.
25887 * Free the returned object with g_object_unref().
25889 * Returns: (transfer full): a #GFile to the specified child, or
25894 * g_file_get_parent:
25895 * @file: input #GFile.
25897 * Gets the parent directory for the @file.
25898 * If the @file represents the root directory of the
25899 * file system, then %NULL will be returned.
25901 * This call does no blocking i/o.
25903 * #GFile or %NULL if there is no parent.
25904 * Free the returned object with g_object_unref().
25906 * Returns: (transfer full): a #GFile structure to the parent of the given
25911 * g_file_get_parse_name:
25912 * @file: input #GFile.
25914 * Gets the parse name of the @file.
25915 * A parse name is a UTF-8 string that describes the
25916 * file such that one can get the #GFile back using
25917 * g_file_parse_name().
25919 * This is generally used to show the #GFile as a nice
25920 * full-pathname kind of string in a user interface,
25921 * like in a location entry.
25923 * For local files with names that can safely be converted
25924 * to UTF8 the pathname is used, otherwise the IRI is used
25925 * (a form of URI that allows UTF8 characters unescaped).
25927 * This call does no blocking i/o.
25929 * string should be freed with g_free() when no longer needed.
25931 * Returns: a string containing the #GFile's parse name. The returned
25937 * @file: input #GFile.
25939 * Gets the local pathname for #GFile, if one exists.
25941 * This call does no blocking i/o.
25943 * no such path exists. The returned string should be
25944 * freed with g_free() when no longer needed.
25946 * Returns: string containing the #GFile's path, or %NULL if
25951 * g_file_get_relative_path:
25952 * @parent: input #GFile.
25953 * @descendant: input #GFile.
25955 * Gets the path for @descendant relative to @parent.
25957 * This call does no blocking i/o.
25959 * to @parent, or %NULL if @descendant doesn't have @parent as prefix.
25960 * The returned string should be freed with g_free() when no longer needed.
25962 * Returns: string with the relative path from @descendant
25968 * @file: input #GFile.
25970 * Gets the URI for the @file.
25972 * This call does no blocking i/o.
25974 * The returned string should be freed with g_free() when no longer needed.
25976 * Returns: a string containing the #GFile's URI.
25981 * g_file_get_uri_scheme:
25982 * @file: input #GFile.
25984 * Gets the URI scheme for a #GFile.
25985 * RFC 3986 decodes the scheme as:
25987 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
25988 * </programlisting>
25989 * Common schemes include "file", "http", "ftp", etc.
25991 * This call does no blocking i/o.
25993 * #GFile. The returned string should be freed with g_free()
25994 * when no longer needed.
25996 * Returns: a string containing the URI scheme for the given
26001 * g_file_has_parent:
26002 * @file: input #GFile
26003 * @parent: (allow-none): the parent to check for, or %NULL
26005 * Checks if @file has a parent, and optionally, if it is @parent.
26007 * If @parent is %NULL then this function returns %TRUE if @file has any
26008 * parent at all. If @parent is non-%NULL then %TRUE is only returned
26009 * if @file is a child of @parent.
26011 * case that @parent is %NULL).
26013 * Returns: %TRUE if @file is a child of @parent (or any parent in the
26019 * g_file_has_prefix:
26020 * @file: input #GFile.
26021 * @prefix: input #GFile.
26023 * Checks whether @file has the prefix specified by @prefix. In other word,
26024 * if the names of initial elements of @file<!-- -->s pathname match @prefix.
26025 * Only full pathname elements are matched, so a path like /foo is not
26026 * considered a prefix of /foobar, only of /foo/bar.
26028 * This call does no i/o, as it works purely on names. As such it can
26029 * sometimes return %FALSE even if @file is inside a @prefix (from a
26030 * filesystem point of view), because the prefix of @file is an alias
26033 * %FALSE otherwise.
26035 * Virtual: prefix_matches
26036 * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix.
26041 * g_file_has_uri_scheme:
26042 * @file: input #GFile.
26043 * @uri_scheme: a string containing a URI scheme.
26045 * Checks to see if a #GFile has a given URI scheme.
26047 * This call does no blocking i/o.
26049 * given URI scheme, %FALSE if URI scheme is %NULL,
26050 * not supported, or #GFile is invalid.
26052 * Returns: %TRUE if #GFile's backend supports the
26058 * @file: (type GFile): #gconstpointer to a #GFile.
26060 * Creates a hash value for a #GFile.
26062 * This call does no blocking i/o.
26064 * integer that can be used as hash value for the #GFile.
26065 * This function is intended for easily hashing a #GFile to
26066 * add to a #GHashTable or similar data structure.
26069 * Returns: 0 if @file is not a valid #GFile, otherwise an
26074 * g_file_icon_get_file:
26077 * Gets the #GFile associated with the given @icon.
26079 * Returns: (transfer none): a #GFile, or %NULL.
26087 * Creates a new icon for a file.
26089 * @file, or %NULL on error.
26091 * Returns: (transfer full) (type GFileIcon): a #GIcon for the given
26096 * g_file_info_clear_status:
26097 * @info: a #GFileInfo.
26099 * Clears the status information from @info.
26104 * g_file_info_copy_into:
26105 * @src_info: source to copy attributes from.
26106 * @dest_info: destination to copy attributes to.
26108 * Copies all of the <link linkend="gio-GFileAttribute">GFileAttribute</link>s
26109 * from @src_info to @dest_info.
26115 * @other: a #GFileInfo.
26117 * Duplicates a file info structure.
26119 * Returns: (transfer full): a duplicate #GFileInfo of @other.
26124 * g_file_info_get_attribute_as_string:
26125 * @info: a #GFileInfo.
26126 * @attribute: a file attribute key.
26128 * Gets the value of a attribute, formated as a string.
26129 * This escapes things as needed to make the string valid
26132 * When you're done with the string it must be freed with g_free().
26134 * Returns: a UTF-8 string associated with the given @attribute.
26139 * g_file_info_get_attribute_boolean:
26140 * @info: a #GFileInfo.
26141 * @attribute: a file attribute key.
26143 * Gets the value of a boolean attribute. If the attribute does not
26144 * contain a boolean value, %FALSE will be returned.
26146 * Returns: the boolean value contained within the attribute.
26151 * g_file_info_get_attribute_byte_string:
26152 * @info: a #GFileInfo.
26153 * @attribute: a file attribute key.
26155 * Gets the value of a byte string attribute. If the attribute does
26156 * not contain a byte string, %NULL will be returned.
26160 * Returns: the contents of the @attribute value as a byte string, or
26165 * g_file_info_get_attribute_data:
26166 * @info: a #GFileInfo
26167 * @attribute: a file attribute key
26168 * @type: (out) (allow-none): return location for the attribute type, or %NULL
26169 * @value_pp: (out) (allow-none): return location for the attribute value, or %NULL
26170 * @status: (out) (allow-none): return location for the attribute status, or %NULL
26172 * Gets the attribute type, value and status for an attribute key.
26174 * %FALSE otherwise.
26176 * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
26181 * g_file_info_get_attribute_int32:
26182 * @info: a #GFileInfo.
26183 * @attribute: a file attribute key.
26185 * Gets a signed 32-bit integer contained within the attribute. If the
26186 * attribute does not contain a signed 32-bit integer, or is invalid,
26187 * 0 will be returned.
26189 * Returns: a signed 32-bit integer from the attribute.
26194 * g_file_info_get_attribute_int64:
26195 * @info: a #GFileInfo.
26196 * @attribute: a file attribute key.
26198 * Gets a signed 64-bit integer contained within the attribute. If the
26199 * attribute does not contain an signed 64-bit integer, or is invalid,
26200 * 0 will be returned.
26202 * Returns: a signed 64-bit integer from the attribute.
26207 * g_file_info_get_attribute_object:
26208 * @info: a #GFileInfo.
26209 * @attribute: a file attribute key.
26211 * Gets the value of a #GObject attribute. If the attribute does
26212 * not contain a #GObject, %NULL will be returned.
26216 * Returns: (transfer none): a #GObject associated with the given @attribute, or
26221 * g_file_info_get_attribute_status:
26222 * @info: a #GFileInfo
26223 * @attribute: a file attribute key
26225 * Gets the attribute status for an attribute key.
26227 * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
26229 * Returns: a #GFileAttributeStatus for the given @attribute, or
26234 * g_file_info_get_attribute_string:
26235 * @info: a #GFileInfo.
26236 * @attribute: a file attribute key.
26238 * Gets the value of a string attribute. If the attribute does
26239 * not contain a string, %NULL will be returned.
26243 * Returns: the contents of the @attribute value as a UTF-8 string, or
26248 * g_file_info_get_attribute_stringv:
26249 * @info: a #GFileInfo.
26250 * @attribute: a file attribute key.
26252 * Gets the value of a stringv attribute. If the attribute does
26253 * not contain a stringv, %NULL will be returned.
26255 * %NULL otherwise. Do not free. These returned strings are UTF-8.
26257 * Returns: (transfer none): the contents of the @attribute value as a stringv, or
26263 * g_file_info_get_attribute_type:
26264 * @info: a #GFileInfo.
26265 * @attribute: a file attribute key.
26267 * Gets the attribute type for an attribute key.
26269 * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
26271 * Returns: a #GFileAttributeType for the given @attribute, or
26276 * g_file_info_get_attribute_uint32:
26277 * @info: a #GFileInfo.
26278 * @attribute: a file attribute key.
26280 * Gets an unsigned 32-bit integer contained within the attribute. If the
26281 * attribute does not contain an unsigned 32-bit integer, or is invalid,
26282 * 0 will be returned.
26284 * Returns: an unsigned 32-bit integer from the attribute.
26289 * g_file_info_get_attribute_uint64:
26290 * @info: a #GFileInfo.
26291 * @attribute: a file attribute key.
26293 * Gets a unsigned 64-bit integer contained within the attribute. If the
26294 * attribute does not contain an unsigned 64-bit integer, or is invalid,
26295 * 0 will be returned.
26297 * Returns: a unsigned 64-bit integer from the attribute.
26302 * g_file_info_get_content_type:
26303 * @info: a #GFileInfo.
26305 * Gets the file's content type.
26307 * Returns: a string containing the file's content type.
26312 * g_file_info_get_display_name:
26313 * @info: a #GFileInfo.
26315 * Gets a display name for a file.
26317 * Returns: a string containing the display name.
26322 * g_file_info_get_edit_name:
26323 * @info: a #GFileInfo.
26325 * Gets the edit name for a file.
26327 * Returns: a string containing the edit name.
26332 * g_file_info_get_etag:
26333 * @info: a #GFileInfo.
26335 * Gets the <link linkend="gfile-etag">entity tag</link> for a given
26336 * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
26338 * Returns: a string containing the value of the "etag:value" attribute.
26343 * g_file_info_get_file_type:
26344 * @info: a #GFileInfo.
26346 * Gets a file's type (whether it is a regular file, symlink, etc).
26347 * This is different from the file's content type, see g_file_info_get_content_type().
26349 * Returns: a #GFileType for the given file.
26354 * g_file_info_get_icon:
26355 * @info: a #GFileInfo.
26357 * Gets the icon for a file.
26359 * Returns: (transfer none): #GIcon for the given @info.
26364 * g_file_info_get_is_backup:
26365 * @info: a #GFileInfo.
26367 * Checks if a file is a backup file.
26369 * Returns: %TRUE if file is a backup file, %FALSE otherwise.
26374 * g_file_info_get_is_hidden:
26375 * @info: a #GFileInfo.
26377 * Checks if a file is hidden.
26379 * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
26384 * g_file_info_get_is_symlink:
26385 * @info: a #GFileInfo.
26387 * Checks if a file is a symlink.
26389 * Returns: %TRUE if the given @info is a symlink.
26394 * g_file_info_get_modification_time:
26395 * @info: a #GFileInfo.
26396 * @result: (out caller-allocates): a #GTimeVal.
26398 * Gets the modification time of the current @info and sets it
26404 * g_file_info_get_name:
26405 * @info: a #GFileInfo.
26407 * Gets the name for a file.
26409 * Returns: a string containing the file name.
26414 * g_file_info_get_size:
26415 * @info: a #GFileInfo.
26417 * Gets the file's size.
26419 * Returns: a #goffset containing the file's size.
26424 * g_file_info_get_sort_order:
26425 * @info: a #GFileInfo.
26427 * Gets the value of the sort_order attribute from the #GFileInfo.
26428 * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
26430 * Returns: a #gint32 containing the value of the "standard::sort_order" attribute.
26435 * g_file_info_get_symlink_target:
26436 * @info: a #GFileInfo.
26438 * Gets the symlink target for a given #GFileInfo.
26440 * Returns: a string containing the symlink target.
26445 * g_file_info_has_attribute:
26446 * @info: a #GFileInfo.
26447 * @attribute: a file attribute key.
26449 * Checks if a file info structure has an attribute named @attribute.
26451 * %FALSE otherwise.
26453 * Returns: %TRUE if @Ginfo has an attribute named @attribute,
26458 * g_file_info_has_namespace:
26459 * @info: a #GFileInfo.
26460 * @name_space: a file attribute namespace.
26462 * Checks if a file info structure has an attribute in the
26463 * specified @name_space.
26465 * %FALSE otherwise.
26467 * Returns: %TRUE if @Ginfo has an attribute in @name_space,
26473 * g_file_info_list_attributes:
26474 * @info: a #GFileInfo.
26475 * @name_space: a file attribute key's namespace.
26477 * Lists the file info structure's attributes.
26479 * possible attribute types for the given @name_space, or
26482 * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the
26489 * Creates a new file info structure.
26491 * Returns: a #GFileInfo.
26496 * g_file_info_remove_attribute:
26497 * @info: a #GFileInfo.
26498 * @attribute: a file attribute key.
26500 * Removes all cases of @attribute from @info if it exists.
26505 * g_file_info_set_attribute:
26506 * @info: a #GFileInfo.
26507 * @attribute: a file attribute key.
26508 * @type: a #GFileAttributeType
26509 * @value_p: pointer to the value
26511 * Sets the @attribute to contain the given value, if possible. To unset the
26512 * attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type.
26517 * g_file_info_set_attribute_boolean:
26518 * @info: a #GFileInfo.
26519 * @attribute: a file attribute key.
26520 * @attr_value: a boolean value.
26522 * Sets the @attribute to contain the given @attr_value,
26528 * g_file_info_set_attribute_byte_string:
26529 * @info: a #GFileInfo.
26530 * @attribute: a file attribute key.
26531 * @attr_value: a byte string.
26533 * Sets the @attribute to contain the given @attr_value,
26539 * g_file_info_set_attribute_int32:
26540 * @info: a #GFileInfo.
26541 * @attribute: a file attribute key.
26542 * @attr_value: a signed 32-bit integer
26544 * Sets the @attribute to contain the given @attr_value,
26550 * g_file_info_set_attribute_int64:
26551 * @info: a #GFileInfo.
26552 * @attribute: attribute name to set.
26553 * @attr_value: int64 value to set attribute to.
26555 * Sets the @attribute to contain the given @attr_value,
26561 * g_file_info_set_attribute_mask:
26562 * @info: a #GFileInfo.
26563 * @mask: a #GFileAttributeMatcher.
26565 * Sets @mask on @info to match specific attribute types.
26570 * g_file_info_set_attribute_object:
26571 * @info: a #GFileInfo.
26572 * @attribute: a file attribute key.
26573 * @attr_value: a #GObject.
26575 * Sets the @attribute to contain the given @attr_value,
26581 * g_file_info_set_attribute_status:
26582 * @info: a #GFileInfo
26583 * @attribute: a file attribute key
26584 * @status: a #GFileAttributeStatus
26586 * Sets the attribute status for an attribute key. This is only
26587 * needed by external code that implement g_file_set_attributes_from_info()
26588 * or similar functions.
26590 * The attribute must exist in @info for this to work. Otherwise %FALSE
26591 * is returned and @info is unchanged.
26593 * Returns: %TRUE if the status was changed, %FALSE if the key was not set.
26599 * g_file_info_set_attribute_string:
26600 * @info: a #GFileInfo.
26601 * @attribute: a file attribute key.
26602 * @attr_value: a UTF-8 string.
26604 * Sets the @attribute to contain the given @attr_value,
26610 * g_file_info_set_attribute_stringv:
26611 * @info: a #GFileInfo.
26612 * @attribute: a file attribute key
26613 * @attr_value: (array) (element-type utf8): a %NULL terminated array of UTF-8 strings.
26615 * Sets the @attribute to contain the given @attr_value,
26623 * g_file_info_set_attribute_uint32:
26624 * @info: a #GFileInfo.
26625 * @attribute: a file attribute key.
26626 * @attr_value: an unsigned 32-bit integer.
26628 * Sets the @attribute to contain the given @attr_value,
26634 * g_file_info_set_attribute_uint64:
26635 * @info: a #GFileInfo.
26636 * @attribute: a file attribute key.
26637 * @attr_value: an unsigned 64-bit integer.
26639 * Sets the @attribute to contain the given @attr_value,
26645 * g_file_info_set_content_type:
26646 * @info: a #GFileInfo.
26647 * @content_type: a content type. See <link linkend="gio-GContentType">GContentType</link>.
26649 * Sets the content type attribute for a given #GFileInfo.
26650 * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
26655 * g_file_info_set_display_name:
26656 * @info: a #GFileInfo.
26657 * @display_name: a string containing a display name.
26659 * Sets the display name for the current #GFileInfo.
26660 * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
26665 * g_file_info_set_edit_name:
26666 * @info: a #GFileInfo.
26667 * @edit_name: a string containing an edit name.
26669 * Sets the edit name for the current file.
26670 * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
26675 * g_file_info_set_file_type:
26676 * @info: a #GFileInfo.
26677 * @type: a #GFileType.
26679 * Sets the file type in a #GFileInfo to @type.
26680 * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
26685 * g_file_info_set_icon:
26686 * @info: a #GFileInfo.
26689 * Sets the icon for a given #GFileInfo.
26690 * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
26695 * g_file_info_set_is_hidden:
26696 * @info: a #GFileInfo.
26697 * @is_hidden: a #gboolean.
26699 * Sets the "is_hidden" attribute in a #GFileInfo according to @is_symlink.
26700 * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
26705 * g_file_info_set_is_symlink:
26706 * @info: a #GFileInfo.
26707 * @is_symlink: a #gboolean.
26709 * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
26710 * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
26715 * g_file_info_set_modification_time:
26716 * @info: a #GFileInfo.
26717 * @mtime: a #GTimeVal.
26719 * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file
26720 * info to the given time value.
26725 * g_file_info_set_name:
26726 * @info: a #GFileInfo.
26727 * @name: a string containing a name.
26729 * Sets the name attribute for the current #GFileInfo.
26730 * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
26735 * g_file_info_set_size:
26736 * @info: a #GFileInfo.
26737 * @size: a #goffset containing the file's size.
26739 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
26740 * to the given size.
26745 * g_file_info_set_sort_order:
26746 * @info: a #GFileInfo.
26747 * @sort_order: a sort order integer.
26749 * Sets the sort order attribute in the file info structure. See
26750 * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
26755 * g_file_info_set_symlink_target:
26756 * @info: a #GFileInfo.
26757 * @symlink_target: a static string containing a path to a symlink target.
26759 * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
26760 * to the given symlink target.
26765 * g_file_info_unset_attribute_mask:
26766 * @info: #GFileInfo.
26768 * Unsets a mask set by g_file_info_set_attribute_mask(), if one
26774 * g_file_input_stream_query_info:
26775 * @stream: a #GFileInputStream.
26776 * @attributes: a file attribute query string.
26777 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26778 * @error: a #GError location to store the error occurring, or %NULL to ignore.
26780 * Queries a file input stream the given @attributes. This function blocks
26781 * while querying the stream. For the asynchronous (non-blocking) version
26782 * of this function, see g_file_input_stream_query_info_async(). While the
26783 * stream is blocked, the stream will set the pending flag internally, and
26784 * any other operations on the stream will fail with %G_IO_ERROR_PENDING.
26786 * Returns: (transfer full): a #GFileInfo, or %NULL on error.
26791 * g_file_input_stream_query_info_async:
26792 * @stream: a #GFileInputStream.
26793 * @attributes: a file attribute query string.
26794 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
26795 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26796 * @callback: (scope async): callback to call when the request is satisfied
26797 * @user_data: (closure): the data to pass to callback function
26799 * Queries the stream information asynchronously.
26800 * When the operation is finished @callback will be called.
26801 * You can then call g_file_input_stream_query_info_finish()
26802 * to get the result of the operation.
26804 * For the synchronous version of this function,
26805 * see g_file_input_stream_query_info().
26807 * If @cancellable is not %NULL, then the operation can be cancelled by
26808 * triggering the cancellable object from another thread. If the operation
26809 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set
26814 * g_file_input_stream_query_info_finish:
26815 * @stream: a #GFileInputStream.
26816 * @result: a #GAsyncResult.
26817 * @error: a #GError location to store the error occurring, or %NULL to ignore.
26819 * Finishes an asynchronous info query operation.
26821 * Returns: (transfer full): #GFileInfo.
26826 * g_file_io_stream_get_etag:
26827 * @stream: a #GFileIOStream.
26829 * Gets the entity tag for the file when it has been written.
26830 * This must be called after the stream has been written
26831 * and closed, as the etag can change while writing.
26833 * Returns: the entity tag for the stream.
26839 * g_file_io_stream_query_info:
26840 * @stream: a #GFileIOStream.
26841 * @attributes: a file attribute query string.
26842 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26843 * @error: a #GError, %NULL to ignore.
26845 * Queries a file io stream for the given @attributes.
26846 * This function blocks while querying the stream. For the asynchronous
26847 * version of this function, see g_file_io_stream_query_info_async().
26848 * While the stream is blocked, the stream will set the pending flag
26849 * internally, and any other operations on the stream will fail with
26850 * %G_IO_ERROR_PENDING.
26852 * Can fail if the stream was already closed (with @error being set to
26853 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
26854 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
26855 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I
26856 * all cases of failure, %NULL will be returned.
26858 * If @cancellable is not %NULL, then the operation can be cancelled by
26859 * triggering the cancellable object from another thread. If the operation
26860 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
26863 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
26869 * g_file_io_stream_query_info_async:
26870 * @stream: a #GFileIOStream.
26871 * @attributes: a file attribute query string.
26872 * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request.
26873 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
26874 * @callback: (scope async): callback to call when the request is satisfied
26875 * @user_data: (closure): the data to pass to callback function
26877 * Asynchronously queries the @stream for a #GFileInfo. When completed,
26878 * @callback will be called with a #GAsyncResult which can be used to
26879 * finish the operation with g_file_io_stream_query_info_finish().
26881 * For the synchronous version of this function, see
26882 * g_file_io_stream_query_info().
26889 * g_file_io_stream_query_info_finish:
26890 * @stream: a #GFileIOStream.
26891 * @result: a #GAsyncResult.
26892 * @error: a #GError, %NULL to ignore.
26894 * Finalizes the asynchronous query started
26895 * by g_file_io_stream_query_info_async().
26897 * Returns: (transfer full): A #GFileInfo for the finished query.
26903 * g_file_is_native:
26904 * @file: input #GFile.
26906 * Checks to see if a file is native to the platform.
26908 * A native file s one expressed in the platform-native filename format,
26909 * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local,
26910 * as it might be on a locally mounted remote filesystem.
26912 * On some systems non-native files may be available using
26913 * the native filesystem via a userspace filesystem (FUSE), in
26914 * these cases this call will return %FALSE, but g_file_get_path()
26915 * will still return a native path.
26917 * This call does no blocking i/o.
26919 * Returns: %TRUE if file is native.
26924 * g_file_load_contents:
26925 * @file: input #GFile.
26926 * @cancellable: optional #GCancellable object, %NULL to ignore.
26927 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file.
26928 * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
26929 * @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
26930 * @error: a #GError, or %NULL
26932 * Loads the content of the file into memory. The data is always
26933 * zero-terminated, but this is not included in the resultant @length.
26934 * The returned @content should be freed with g_free() when no longer
26937 * If @cancellable is not %NULL, then the operation can be cancelled by
26938 * triggering the cancellable object from another thread. If the operation
26939 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
26941 * %FALSE if there were errors.
26943 * Returns: %TRUE if the @file's contents were successfully loaded.
26948 * g_file_load_contents_async:
26949 * @file: input #GFile.
26950 * @cancellable: optional #GCancellable object, %NULL to ignore.
26951 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
26952 * @user_data: the data to pass to callback function
26954 * Starts an asynchronous load of the @file's contents.
26956 * For more details, see g_file_load_contents() which is
26957 * the synchronous version of this call.
26959 * When the load operation has completed, @callback will be called
26960 * with @user data. To finish the operation, call
26961 * g_file_load_contents_finish() with the #GAsyncResult returned by
26964 * If @cancellable is not %NULL, then the operation can be cancelled by
26965 * triggering the cancellable object from another thread. If the operation
26966 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
26971 * g_file_load_contents_finish:
26972 * @file: input #GFile.
26973 * @res: a #GAsyncResult.
26974 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file.
26975 * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
26976 * @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
26977 * @error: a #GError, or %NULL
26979 * Finishes an asynchronous load of the @file's contents.
26980 * The contents are placed in @contents, and @length is set to the
26981 * size of the @contents string. The @content should be freed with
26982 * g_free() when no longer needed. If @etag_out is present, it will be
26983 * set to the new entity tag for the @file.
26985 * present, it will be set appropriately.
26987 * Returns: %TRUE if the load was successful. If %FALSE and @error is
26992 * g_file_load_partial_contents_async: (skip)
26993 * @file: input #GFile.
26994 * @cancellable: optional #GCancellable object, %NULL to ignore.
26995 * @read_more_callback: a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read.
26996 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
26997 * @user_data: the data to pass to the callback functions.
26999 * Reads the partial contents of a file. A #GFileReadMoreCallback should be
27000 * used to stop reading from the file when appropriate, else this function
27001 * will behave exactly as g_file_load_contents_async(). This operation
27002 * can be finished by g_file_load_partial_contents_finish().
27004 * Users of this function should be aware that @user_data is passed to
27005 * both the @read_more_callback and the @callback.
27007 * If @cancellable is not %NULL, then the operation can be cancelled by
27008 * triggering the cancellable object from another thread. If the operation
27009 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27014 * g_file_load_partial_contents_finish:
27015 * @file: input #GFile.
27016 * @res: a #GAsyncResult.
27017 * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file.
27018 * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
27019 * @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
27020 * @error: a #GError, or %NULL
27022 * Finishes an asynchronous partial load operation that was started
27023 * with g_file_load_partial_contents_async(). The data is always
27024 * zero-terminated, but this is not included in the resultant @length.
27025 * The returned @content should be freed with g_free() when no longer
27028 * present, it will be set appropriately.
27030 * Returns: %TRUE if the load was successful. If %FALSE and @error is
27035 * g_file_make_directory:
27036 * @file: input #GFile.
27037 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27038 * @error: a #GError, or %NULL
27040 * Creates a directory. Note that this will only create a child directory of
27041 * the immediate parent directory of the path or URI given by the #GFile. To
27042 * recursively create directories, see g_file_make_directory_with_parents().
27043 * This function will fail if the parent directory does not exist, setting
27044 * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support creating
27045 * directories, this function will fail, setting @error to
27046 * %G_IO_ERROR_NOT_SUPPORTED.
27048 * For a local #GFile the newly created directory will have the default
27049 * (current) ownership and permissions of the current process.
27051 * If @cancellable is not %NULL, then the operation can be cancelled by
27052 * triggering the cancellable object from another thread. If the operation
27053 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27055 * Returns: %TRUE on successful creation, %FALSE otherwise.
27060 * g_file_make_directory_with_parents:
27061 * @file: input #GFile.
27062 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27063 * @error: a #GError, or %NULL
27065 * Creates a directory and any parent directories that may not exist similar to
27066 * 'mkdir -p'. If the file system does not support creating directories, this
27067 * function will fail, setting @error to %G_IO_ERROR_NOT_SUPPORTED. If the
27068 * directory itself already exists, this function will fail setting @error
27069 * to %G_IO_ERROR_EXISTS, unlike the similar g_mkdir_with_parents().
27071 * For a local #GFile the newly created directories will have the default
27072 * (current) ownership and permissions of the current process.
27074 * If @cancellable is not %NULL, then the operation can be cancelled by
27075 * triggering the cancellable object from another thread. If the operation
27076 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27080 * Returns: %TRUE if all directories have been successfully created, %FALSE
27086 * g_file_make_symbolic_link:
27087 * @file: a #GFile with the name of the symlink to create
27088 * @symlink_value: a string with the path for the target of the new symlink
27089 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27090 * @error: a #GError.
27092 * Creates a symbolic link named @file which contains the string
27095 * If @cancellable is not %NULL, then the operation can be cancelled by
27096 * triggering the cancellable object from another thread. If the operation
27097 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27099 * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
27105 * @file: input #GFile
27106 * @flags: a set of #GFileMonitorFlags
27107 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
27108 * @error: a #GError, or %NULL
27110 * Obtains a file or directory monitor for the given file, depending
27111 * on the type of the file.
27113 * If @cancellable is not %NULL, then the operation can be cancelled by
27114 * triggering the cancellable object from another thread. If the operation
27115 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27117 * Free the returned object with g_object_unref().
27119 * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
27125 * g_file_monitor_cancel:
27126 * @monitor: a #GFileMonitor.
27128 * Cancels a file monitor.
27130 * Returns: %TRUE if monitor was cancelled.
27135 * g_file_monitor_directory:
27136 * @file: input #GFile.
27137 * @flags: a set of #GFileMonitorFlags.
27138 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27139 * @error: a #GError, or %NULL.
27141 * Obtains a directory monitor for the given file.
27142 * This may fail if directory monitoring is not supported.
27144 * If @cancellable is not %NULL, then the operation can be cancelled by
27145 * triggering the cancellable object from another thread. If the operation
27146 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27148 * Free the returned object with g_object_unref().
27150 * Virtual: monitor_dir
27151 * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
27156 * g_file_monitor_emit_event:
27157 * @monitor: a #GFileMonitor.
27158 * @child: a #GFile.
27159 * @other_file: a #GFile.
27160 * @event_type: a set of #GFileMonitorEvent flags.
27162 * Emits the #GFileMonitor::changed signal if a change
27163 * has taken place. Should be called from file monitor
27164 * implementations only.
27166 * The signal will be emitted from an idle handler (in the <link
27167 * linkend="g-main-context-push-thread-default">thread-default main
27173 * g_file_monitor_file:
27174 * @file: input #GFile.
27175 * @flags: a set of #GFileMonitorFlags.
27176 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27177 * @error: a #GError, or %NULL.
27179 * Obtains a file monitor for the given file. If no file notification
27180 * mechanism exists, then regular polling of the file is used.
27182 * If @cancellable is not %NULL, then the operation can be cancelled by
27183 * triggering the cancellable object from another thread. If the operation
27184 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27186 * Free the returned object with g_object_unref().
27188 * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
27193 * g_file_monitor_is_cancelled:
27194 * @monitor: a #GFileMonitor
27196 * Returns whether the monitor is canceled.
27198 * Returns: %TRUE if monitor is canceled. %FALSE otherwise.
27203 * g_file_monitor_set_rate_limit:
27204 * @monitor: a #GFileMonitor.
27205 * @limit_msecs: a non-negative integer with the limit in milliseconds to poll for changes
27207 * Sets the rate limit to which the @monitor will report
27208 * consecutive change events to the same file.
27213 * g_file_mount_enclosing_volume:
27214 * @location: input #GFile.
27215 * @flags: flags affecting the operation
27216 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
27217 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27218 * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
27219 * @user_data: the data to pass to callback function
27221 * Starts a @mount_operation, mounting the volume that contains the file @location.
27223 * When this operation has completed, @callback will be called with
27224 * @user_user data, and the operation can be finalized with
27225 * g_file_mount_enclosing_volume_finish().
27227 * If @cancellable is not %NULL, then the operation can be cancelled by
27228 * triggering the cancellable object from another thread. If the operation
27229 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27234 * g_file_mount_enclosing_volume_finish:
27235 * @location: input #GFile.
27236 * @result: a #GAsyncResult.
27237 * @error: a #GError, or %NULL
27239 * Finishes a mount operation started by g_file_mount_enclosing_volume().
27241 * has occurred, this function will return %FALSE and set @error
27242 * appropriately if present.
27244 * Returns: %TRUE if successful. If an error
27249 * g_file_mount_mountable:
27250 * @file: input #GFile.
27251 * @flags: flags affecting the operation
27252 * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
27253 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27254 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
27255 * @user_data: (closure): the data to pass to callback function
27257 * Mounts a file of type G_FILE_TYPE_MOUNTABLE.
27258 * Using @mount_operation, you can request callbacks when, for instance,
27259 * passwords are needed during authentication.
27261 * If @cancellable is not %NULL, then the operation can be cancelled by
27262 * triggering the cancellable object from another thread. If the operation
27263 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27265 * When the operation is finished, @callback will be called. You can then call
27266 * g_file_mount_mountable_finish() to get the result of the operation.
27271 * g_file_mount_mountable_finish:
27272 * @file: input #GFile.
27273 * @result: a #GAsyncResult.
27274 * @error: a #GError, or %NULL
27276 * Finishes a mount operation. See g_file_mount_mountable() for details.
27278 * Finish an asynchronous mount operation that was started
27279 * with g_file_mount_mountable().
27281 * Free the returned object with g_object_unref().
27283 * Returns: (transfer full): a #GFile or %NULL on error.
27289 * @source: #GFile pointing to the source location.
27290 * @destination: #GFile pointing to the destination location.
27291 * @flags: set of #GFileCopyFlags.
27292 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27293 * @progress_callback: (allow-none) (scope call): #GFileProgressCallback function for updates.
27294 * @progress_callback_data: (closure): gpointer to user data for the callback function.
27295 * @error: #GError for returning error conditions, or %NULL
27297 * Tries to move the file or directory @source to the location specified by @destination.
27298 * If native move operations are supported then this is used, otherwise a copy + delete
27299 * fallback is used. The native implementation may support moving directories (for instance
27300 * on moves inside the same filesystem), but the fallback code does not.
27302 * If the flag #G_FILE_COPY_OVERWRITE is specified an already
27303 * existing @destination file is overwritten.
27305 * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks
27306 * will be copied as symlinks, otherwise the target of the
27307 * @source symlink will be copied.
27309 * If @cancellable is not %NULL, then the operation can be cancelled by
27310 * triggering the cancellable object from another thread. If the operation
27311 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27313 * If @progress_callback is not %NULL, then the operation can be monitored by
27314 * setting this to a #GFileProgressCallback function. @progress_callback_data
27315 * will be passed to this function. It is guaranteed that this callback will
27316 * be called after all data has been transferred with the total number of bytes
27317 * copied during the operation.
27319 * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND
27320 * error is returned, independent on the status of the @destination.
27322 * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the
27323 * error G_IO_ERROR_EXISTS is returned.
27325 * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY
27326 * error is returned. If trying to overwrite a directory with a directory the
27327 * G_IO_ERROR_WOULD_MERGE error is returned.
27329 * If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is
27330 * specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error
27331 * may be returned (if the native move operation isn't available).
27333 * Returns: %TRUE on successful move, %FALSE otherwise.
27338 * g_file_new_for_commandline_arg:
27339 * @arg: a command line string.
27341 * Creates a #GFile with the given argument from the command line. The value of
27342 * @arg can be either a URI, an absolute path or a relative path resolved
27343 * relative to the current working directory.
27344 * This operation never fails, but the returned object might not support any
27345 * I/O operation if @arg points to a malformed path.
27347 * Free the returned object with g_object_unref().
27349 * Returns: (transfer full): a new #GFile.
27354 * g_file_new_for_path:
27355 * @path: a string containing a relative or absolute path. The string must be encoded in the glib filename encoding.
27357 * Constructs a #GFile for a given path. This operation never
27358 * fails, but the returned object might not support any I/O
27359 * operation if @path is malformed.
27361 * Free the returned object with g_object_unref().
27363 * Returns: (transfer full): a new #GFile for the given @path.
27368 * g_file_new_for_uri:
27369 * @uri: a UTF8 string containing a URI.
27371 * Constructs a #GFile for a given URI. This operation never
27372 * fails, but the returned object might not support any I/O
27373 * operation if @uri is malformed or if the uri type is
27376 * Free the returned object with g_object_unref().
27378 * Returns: (transfer full): a new #GFile for the given @uri.
27384 * @tmpl: (type filename) (allow-none): Template for the file name, as in g_file_open_tmp(), or %NULL for a default template.
27385 * @iostream: (out): on return, a #GFileIOStream for the created file.
27386 * @error: a #GError, or %NULL
27388 * Opens a file in the preferred directory for temporary files (as
27389 * returned by g_get_tmp_dir()) and returns a #GFile and
27390 * #GFileIOStream pointing to it.
27392 * @tmpl should be a string in the GLib file name encoding
27393 * containing a sequence of six 'X' characters, and containing no
27394 * directory components. If it is %NULL, a default template is used.
27396 * Unlike the other #GFile constructors, this will return %NULL if
27397 * a temporary file could not be created.
27399 * Free the returned object with g_object_unref().
27401 * Returns: (transfer full): a new #GFile.
27407 * g_file_open_readwrite:
27408 * @file: #GFile to open
27409 * @cancellable: (allow-none): a #GCancellable
27410 * @error: a #GError, or %NULL
27412 * Opens an existing file for reading and writing. The result is
27413 * a #GFileIOStream that can be used to read and write the contents of the file.
27415 * If @cancellable is not %NULL, then the operation can be cancelled by
27416 * triggering the cancellable object from another thread. If the operation
27417 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27419 * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
27420 * If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned.
27421 * Other errors are possible too, and depend on what kind of filesystem the file is on.
27422 * Note that in many non-local file cases read and write streams are not supported,
27423 * so make sure you really need to do read and write streaming, rather than
27424 * just opening for reading or writing.
27426 * Free the returned object with g_object_unref().
27428 * Returns: (transfer full): #GFileIOStream or %NULL on error.
27434 * g_file_open_readwrite_async:
27435 * @file: input #GFile.
27436 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
27437 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27438 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
27439 * @user_data: (closure): the data to pass to callback function
27441 * Asynchronously opens @file for reading and writing.
27443 * For more details, see g_file_open_readwrite() which is
27444 * the synchronous version of this call.
27446 * When the operation is finished, @callback will be called. You can then call
27447 * g_file_open_readwrite_finish() to get the result of the operation.
27454 * g_file_open_readwrite_finish:
27455 * @file: input #GFile.
27456 * @res: a #GAsyncResult.
27457 * @error: a #GError, or %NULL
27459 * Finishes an asynchronous file read operation started with
27460 * g_file_open_readwrite_async().
27462 * Free the returned object with g_object_unref().
27464 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
27470 * g_file_output_stream_get_etag:
27471 * @stream: a #GFileOutputStream.
27473 * Gets the entity tag for the file when it has been written.
27474 * This must be called after the stream has been written
27475 * and closed, as the etag can change while writing.
27477 * Returns: the entity tag for the stream.
27482 * g_file_output_stream_query_info:
27483 * @stream: a #GFileOutputStream.
27484 * @attributes: a file attribute query string.
27485 * @cancellable: optional #GCancellable object, %NULL to ignore.
27486 * @error: a #GError, %NULL to ignore.
27488 * Queries a file output stream for the given @attributes.
27489 * This function blocks while querying the stream. For the asynchronous
27490 * version of this function, see g_file_output_stream_query_info_async().
27491 * While the stream is blocked, the stream will set the pending flag
27492 * internally, and any other operations on the stream will fail with
27493 * %G_IO_ERROR_PENDING.
27495 * Can fail if the stream was already closed (with @error being set to
27496 * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
27497 * set to %G_IO_ERROR_PENDING), or if querying info is not supported for
27498 * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
27499 * all cases of failure, %NULL will be returned.
27501 * If @cancellable is not %NULL, then the operation can be cancelled by
27502 * triggering the cancellable object from another thread. If the operation
27503 * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will
27506 * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error.
27511 * g_file_output_stream_query_info_async:
27512 * @stream: a #GFileOutputStream.
27513 * @attributes: a file attribute query string.
27514 * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request.
27515 * @cancellable: optional #GCancellable object, %NULL to ignore.
27516 * @callback: callback to call when the request is satisfied
27517 * @user_data: the data to pass to callback function
27519 * Asynchronously queries the @stream for a #GFileInfo. When completed,
27520 * @callback will be called with a #GAsyncResult which can be used to
27521 * finish the operation with g_file_output_stream_query_info_finish().
27523 * For the synchronous version of this function, see
27524 * g_file_output_stream_query_info().
27529 * g_file_output_stream_query_info_finish:
27530 * @stream: a #GFileOutputStream.
27531 * @result: a #GAsyncResult.
27532 * @error: a #GError, %NULL to ignore.
27534 * Finalizes the asynchronous query started
27535 * by g_file_output_stream_query_info_async().
27537 * Returns: (transfer full): A #GFileInfo for the finished query.
27542 * g_file_parse_name:
27543 * @parse_name: a file name or path to be parsed.
27545 * Constructs a #GFile with the given @parse_name (i.e. something given by g_file_get_parse_name()).
27546 * This operation never fails, but the returned object might not support any I/O
27547 * operation if the @parse_name cannot be parsed.
27549 * Returns: (transfer full): a new #GFile.
27554 * g_file_poll_mountable:
27555 * @file: input #GFile.
27556 * @cancellable: optional #GCancellable object, %NULL to ignore.
27557 * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
27558 * @user_data: the data to pass to callback function
27560 * Polls a file of type G_FILE_TYPE_MOUNTABLE.
27562 * If @cancellable is not %NULL, then the operation can be cancelled by
27563 * triggering the cancellable object from another thread. If the operation
27564 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27566 * When the operation is finished, @callback will be called. You can then call
27567 * g_file_mount_mountable_finish() to get the result of the operation.
27574 * g_file_poll_mountable_finish:
27575 * @file: input #GFile.
27576 * @result: a #GAsyncResult.
27577 * @error: a #GError, or %NULL
27579 * Finishes a poll operation. See g_file_poll_mountable() for details.
27581 * Finish an asynchronous poll operation that was polled
27582 * with g_file_poll_mountable().
27586 * Returns: %TRUE if the operation finished successfully. %FALSE
27592 * g_file_query_default_handler:
27593 * @file: a #GFile to open.
27594 * @cancellable: optional #GCancellable object, %NULL to ignore.
27595 * @error: a #GError, or %NULL
27597 * Returns the #GAppInfo that is registered as the default
27598 * application to handle the file specified by @file.
27600 * If @cancellable is not %NULL, then the operation can be cancelled by
27601 * triggering the cancellable object from another thread. If the operation
27602 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27604 * When you are done with it, release it with g_object_unref()
27606 * Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors.
27611 * g_file_query_exists:
27612 * @file: input #GFile.
27613 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27615 * Utility function to check if a particular file exists. This is
27616 * implemented using g_file_query_info() and as such does blocking I/O.
27618 * Note that in many cases it is racy to first check for file existence
27619 * and then execute something based on the outcome of that, because the
27620 * file might have been created or removed in between the operations. The
27621 * general approach to handling that is to not check, but just do the
27622 * operation and handle the errors as they come.
27624 * As an example of race-free checking, take the case of reading a file, and
27625 * if it doesn't exist, creating it. There are two racy versions: read it, and
27626 * on error create it; and: check if it exists, if not create it. These
27627 * can both result in two processes creating the file (with perhaps a partially
27628 * written file as the result). The correct approach is to always try to create
27629 * the file with g_file_create() which will either atomically create the file
27630 * or fail with a G_IO_ERROR_EXISTS error.
27632 * However, in many cases an existence check is useful in a user
27633 * interface, for instance to make a menu item sensitive/insensitive, so that
27634 * you don't have to fool users that something is possible and then just show
27635 * and error dialog. If you do this, you should make sure to also handle the
27636 * errors that can happen due to races when you execute the operation.
27638 * Returns: %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled).
27643 * g_file_query_file_type:
27644 * @file: input #GFile.
27645 * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info().
27646 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27648 * Utility function to inspect the #GFileType of a file. This is
27649 * implemented using g_file_query_info() and as such does blocking I/O.
27651 * The primary use case of this method is to check if a file is a regular file,
27652 * directory, or symlink.
27656 * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file
27662 * g_file_query_filesystem_info:
27663 * @file: input #GFile.
27664 * @attributes: an attribute query string.
27665 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27666 * @error: a #GError.
27668 * Similar to g_file_query_info(), but obtains information
27669 * about the filesystem the @file is on, rather than the file itself.
27670 * For instance the amount of space available and the type of
27673 * The @attributes value is a string that specifies the file attributes that
27674 * should be gathered. It is not an error if it's not possible to read a particular
27675 * requested attribute from a file - it just won't be set. @attributes should
27676 * be a comma-separated list of attributes or attribute wildcards. The wildcard "*"
27677 * means all attributes, and a wildcard like "filesystem::*" means all attributes in the
27678 * filesystem namespace. The standard namespace for filesystem attributes is "filesystem".
27679 * Common attributes of interest are #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE
27680 * (the total size of the filesystem in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of
27681 * bytes available), and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).
27683 * If @cancellable is not %NULL, then the operation can be cancelled by
27684 * triggering the cancellable object from another thread. If the operation
27685 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27687 * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
27688 * Other errors are possible too, and depend on what kind of filesystem the file is on.
27690 * Free the returned object with g_object_unref().
27692 * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
27697 * g_file_query_filesystem_info_async:
27698 * @file: input #GFile.
27699 * @attributes: an attribute query string.
27700 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
27701 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27702 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
27703 * @user_data: (closure): the data to pass to callback function
27705 * Asynchronously gets the requested information about the filesystem
27706 * that the specified @file is on. The result is a #GFileInfo object
27707 * that contains key-value attributes (such as type or size for the
27710 * For more details, see g_file_query_filesystem_info() which is the
27711 * synchronous version of this call.
27713 * When the operation is finished, @callback will be called. You can
27714 * then call g_file_query_info_finish() to get the result of the
27720 * g_file_query_filesystem_info_finish:
27721 * @file: input #GFile.
27722 * @res: a #GAsyncResult.
27723 * @error: a #GError.
27725 * Finishes an asynchronous filesystem info query. See
27726 * g_file_query_filesystem_info_async().
27728 * Free the returned object with g_object_unref().
27730 * Returns: (transfer full): #GFileInfo for given @file or %NULL on error.
27735 * g_file_query_info:
27736 * @file: input #GFile.
27737 * @attributes: an attribute query string.
27738 * @flags: a set of #GFileQueryInfoFlags.
27739 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27740 * @error: a #GError.
27742 * Gets the requested information about specified @file. The result
27743 * is a #GFileInfo object that contains key-value attributes (such as
27744 * the type or size of the file).
27746 * The @attributes value is a string that specifies the file attributes that
27747 * should be gathered. It is not an error if it's not possible to read a particular
27748 * requested attribute from a file - it just won't be set. @attributes should
27749 * be a comma-separated list of attributes or attribute wildcards. The wildcard "*"
27750 * means all attributes, and a wildcard like "standard::*" means all attributes in the standard
27751 * namespace. An example attribute query be "standard::*,owner::user".
27752 * The standard attributes are available as defines, like #G_FILE_ATTRIBUTE_STANDARD_NAME.
27754 * If @cancellable is not %NULL, then the operation can be cancelled by
27755 * triggering the cancellable object from another thread. If the operation
27756 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27758 * For symlinks, normally the information about the target of the
27759 * symlink is returned, rather than information about the symlink itself.
27760 * However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in @flags the
27761 * information about the symlink itself will be returned. Also, for symlinks
27762 * that point to non-existing files the information about the symlink itself
27763 * will be returned.
27765 * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
27766 * Other errors are possible too, and depend on what kind of filesystem the file is on.
27768 * Free the returned object with g_object_unref().
27770 * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error.
27775 * g_file_query_info_async:
27776 * @file: input #GFile.
27777 * @attributes: an attribute query string.
27778 * @flags: a set of #GFileQueryInfoFlags.
27779 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
27780 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27781 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
27782 * @user_data: (closure): the data to pass to callback function
27784 * Asynchronously gets the requested information about specified @file. The result
27785 * is a #GFileInfo object that contains key-value attributes (such as type or size
27788 * For more details, see g_file_query_info() which is
27789 * the synchronous version of this call.
27791 * When the operation is finished, @callback will be called. You can then call
27792 * g_file_query_info_finish() to get the result of the operation.
27797 * g_file_query_info_finish:
27798 * @file: input #GFile.
27799 * @res: a #GAsyncResult.
27800 * @error: a #GError.
27802 * Finishes an asynchronous file info query.
27803 * See g_file_query_info_async().
27805 * Free the returned object with g_object_unref().
27807 * Returns: (transfer full): #GFileInfo for given @file or %NULL on error.
27812 * g_file_query_settable_attributes:
27813 * @file: input #GFile.
27814 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27815 * @error: a #GError, or %NULL
27817 * Obtain the list of settable attributes for the file.
27819 * Returns the type and full attribute name of all the attributes
27820 * that can be set on this file. This doesn't mean setting it will always
27821 * succeed though, you might get an access failure, or some specific
27822 * file may not support a specific attribute.
27824 * If @cancellable is not %NULL, then the operation can be cancelled by
27825 * triggering the cancellable object from another thread. If the operation
27826 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27828 * When you are done with it, release it with g_file_attribute_info_list_unref()
27830 * Returns: a #GFileAttributeInfoList describing the settable attributes.
27835 * g_file_query_writable_namespaces:
27836 * @file: input #GFile.
27837 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27838 * @error: a #GError, or %NULL
27840 * Obtain the list of attribute namespaces where new attributes
27841 * can be created by a user. An example of this is extended
27842 * attributes (in the "xattr" namespace).
27844 * If @cancellable is not %NULL, then the operation can be cancelled by
27845 * triggering the cancellable object from another thread. If the operation
27846 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27848 * When you are done with it, release it with g_file_attribute_info_list_unref()
27850 * Returns: a #GFileAttributeInfoList describing the writable namespaces.
27856 * @file: #GFile to read.
27857 * @cancellable: (allow-none): a #GCancellable
27858 * @error: a #GError, or %NULL
27860 * Opens a file for reading. The result is a #GFileInputStream that
27861 * can be used to read the contents of the file.
27863 * If @cancellable is not %NULL, then the operation can be cancelled by
27864 * triggering the cancellable object from another thread. If the operation
27865 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27867 * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
27868 * If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned.
27869 * Other errors are possible too, and depend on what kind of filesystem the file is on.
27871 * Free the returned object with g_object_unref().
27874 * Returns: (transfer full): #GFileInputStream or %NULL on error.
27879 * g_file_read_async:
27880 * @file: input #GFile
27881 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
27882 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27883 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
27884 * @user_data: (closure): the data to pass to callback function
27886 * Asynchronously opens @file for reading.
27888 * For more details, see g_file_read() which is
27889 * the synchronous version of this call.
27891 * When the operation is finished, @callback will be called. You can then call
27892 * g_file_read_finish() to get the result of the operation.
27897 * g_file_read_finish:
27898 * @file: input #GFile.
27899 * @res: a #GAsyncResult.
27900 * @error: a #GError, or %NULL
27902 * Finishes an asynchronous file read operation started with
27903 * g_file_read_async().
27905 * Free the returned object with g_object_unref().
27907 * Returns: (transfer full): a #GFileInputStream or %NULL on error.
27913 * @file: input #GFile.
27914 * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore.
27915 * @make_backup: %TRUE if a backup should be created.
27916 * @flags: a set of #GFileCreateFlags.
27917 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27918 * @error: a #GError, or %NULL
27920 * Returns an output stream for overwriting the file, possibly
27921 * creating a backup copy of the file first. If the file doesn't exist,
27922 * it will be created.
27924 * This will try to replace the file in the safest way possible so
27925 * that any errors during the writing will not affect an already
27926 * existing copy of the file. For instance, for local files it
27927 * may write to a temporary file and then atomically rename over
27928 * the destination when the stream is closed.
27930 * By default files created are generally readable by everyone,
27931 * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file
27932 * will be made readable only to the current user, to the level that
27933 * is supported on the target filesystem.
27935 * If @cancellable is not %NULL, then the operation can be cancelled by
27936 * triggering the cancellable object from another thread. If the operation
27937 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
27939 * If you pass in a non-#NULL @etag value, then this value is
27940 * compared to the current entity tag of the file, and if they differ
27941 * an G_IO_ERROR_WRONG_ETAG error is returned. This generally means
27942 * that the file has been changed since you last read it. You can get
27943 * the new etag from g_file_output_stream_get_etag() after you've
27944 * finished writing and closed the #GFileOutputStream. When you load
27945 * a new file you can use g_file_input_stream_query_info() to get
27946 * the etag of the file.
27948 * If @make_backup is %TRUE, this function will attempt to make a backup
27949 * of the current file before overwriting it. If this fails a G_IO_ERROR_CANT_CREATE_BACKUP
27950 * error will be returned. If you want to replace anyway, try again with
27951 * @make_backup set to %FALSE.
27953 * If the file is a directory the G_IO_ERROR_IS_DIRECTORY error will be returned,
27954 * and if the file is some other form of non-regular file then a
27955 * G_IO_ERROR_NOT_REGULAR_FILE error will be returned.
27956 * Some file systems don't allow all file names, and may
27957 * return an G_IO_ERROR_INVALID_FILENAME error, and if the name
27958 * is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned.
27959 * Other errors are possible too, and depend on what kind of
27960 * filesystem the file is on.
27962 * Free the returned object with g_object_unref().
27964 * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
27969 * g_file_replace_async:
27970 * @file: input #GFile.
27971 * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore.
27972 * @make_backup: %TRUE if a backup should be created.
27973 * @flags: a set of #GFileCreateFlags.
27974 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
27975 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
27976 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
27977 * @user_data: (closure): the data to pass to callback function
27979 * Asynchronously overwrites the file, replacing the contents, possibly
27980 * creating a backup copy of the file first.
27982 * For more details, see g_file_replace() which is
27983 * the synchronous version of this call.
27985 * When the operation is finished, @callback will be called. You can then call
27986 * g_file_replace_finish() to get the result of the operation.
27991 * g_file_replace_contents:
27992 * @file: input #GFile.
27993 * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file.
27994 * @length: the length of @contents in bytes.
27995 * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link> for the document, or %NULL
27996 * @make_backup: %TRUE if a backup should be created.
27997 * @flags: a set of #GFileCreateFlags.
27998 * @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
27999 * @cancellable: optional #GCancellable object, %NULL to ignore.
28000 * @error: a #GError, or %NULL
28002 * Replaces the contents of @file with @contents of @length bytes.
28003 * If @etag is specified (not %NULL) any existing file must have that etag, or
28004 * the error %G_IO_ERROR_WRONG_ETAG will be returned.
28006 * If @make_backup is %TRUE, this function will attempt to make a backup of @file.
28008 * If @cancellable is not %NULL, then the operation can be cancelled by
28009 * triggering the cancellable object from another thread. If the operation
28010 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28012 * The returned @new_etag can be used to verify that the file hasn't changed the
28013 * next time it is saved over.
28015 * has occurred, this function will return %FALSE and set @error
28016 * appropriately if present.
28018 * Returns: %TRUE if successful. If an error
28023 * g_file_replace_contents_async:
28024 * @file: input #GFile.
28025 * @contents: (element-type guint8) (array length=length): string of contents to replace the file with.
28026 * @length: the length of @contents in bytes.
28027 * @etag: (allow-none): a new <link linkend="gfile-etag">entity tag</link> for the @file, or %NULL
28028 * @make_backup: %TRUE if a backup should be created.
28029 * @flags: a set of #GFileCreateFlags.
28030 * @cancellable: optional #GCancellable object, %NULL to ignore.
28031 * @callback: a #GAsyncReadyCallback to call when the request is satisfied
28032 * @user_data: the data to pass to callback function
28034 * Starts an asynchronous replacement of @file with the given
28035 * @contents of @length bytes. @etag will replace the document's
28036 * current entity tag.
28038 * When this operation has completed, @callback will be called with
28039 * @user_user data, and the operation can be finalized with
28040 * g_file_replace_contents_finish().
28042 * If @cancellable is not %NULL, then the operation can be cancelled by
28043 * triggering the cancellable object from another thread. If the operation
28044 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28046 * If @make_backup is %TRUE, this function will attempt to
28047 * make a backup of @file.
28052 * g_file_replace_contents_finish:
28053 * @file: input #GFile.
28054 * @res: a #GAsyncResult.
28055 * @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
28056 * @error: a #GError, or %NULL
28058 * Finishes an asynchronous replace of the given @file. See
28059 * g_file_replace_contents_async(). Sets @new_etag to the new entity
28060 * tag for the document, if present.
28062 * Returns: %TRUE on success, %FALSE on failure.
28067 * g_file_replace_finish:
28068 * @file: input #GFile.
28069 * @res: a #GAsyncResult.
28070 * @error: a #GError, or %NULL
28072 * Finishes an asynchronous file replace operation started with
28073 * g_file_replace_async().
28075 * Free the returned object with g_object_unref().
28077 * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
28082 * g_file_replace_readwrite:
28084 * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore
28085 * @make_backup: %TRUE if a backup should be created
28086 * @flags: a set of #GFileCreateFlags
28087 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
28088 * @error: return location for a #GError, or %NULL
28090 * Returns an output stream for overwriting the file in readwrite mode,
28091 * possibly creating a backup copy of the file first. If the file doesn't
28092 * exist, it will be created.
28094 * For details about the behaviour, see g_file_replace() which does the same
28095 * thing but returns an output stream only.
28097 * Note that in many non-local file cases read and write streams are not
28098 * supported, so make sure you really need to do read and write streaming,
28099 * rather than just opening for reading or writing.
28101 * Free the returned object with g_object_unref().
28103 * Returns: (transfer full): a #GFileIOStream or %NULL on error.
28109 * g_file_replace_readwrite_async:
28110 * @file: input #GFile.
28111 * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore.
28112 * @make_backup: %TRUE if a backup should be created.
28113 * @flags: a set of #GFileCreateFlags.
28114 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
28115 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28116 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
28117 * @user_data: (closure): the data to pass to callback function
28119 * Asynchronously overwrites the file in read-write mode, replacing the
28120 * contents, possibly creating a backup copy of the file first.
28122 * For more details, see g_file_replace_readwrite() which is
28123 * the synchronous version of this call.
28125 * When the operation is finished, @callback will be called. You can then
28126 * call g_file_replace_readwrite_finish() to get the result of the operation.
28133 * g_file_replace_readwrite_finish:
28134 * @file: input #GFile.
28135 * @res: a #GAsyncResult.
28136 * @error: a #GError, or %NULL
28138 * Finishes an asynchronous file replace operation started with
28139 * g_file_replace_readwrite_async().
28141 * Free the returned object with g_object_unref().
28143 * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
28149 * g_file_resolve_relative_path:
28150 * @file: input #GFile.
28151 * @relative_path: a given relative path string.
28153 * Resolves a relative path for @file to an absolute path.
28155 * This call does no blocking i/o.
28157 * is %NULL or if @file is invalid.
28158 * Free the returned object with g_object_unref().
28160 * Returns: (transfer full): #GFile to the resolved path. %NULL if @relative_path
28165 * g_file_set_attribute:
28166 * @file: input #GFile.
28167 * @attribute: a string containing the attribute's name.
28168 * @type: The type of the attribute
28169 * @value_p: (allow-none): a pointer to the value (or the pointer itself if the type is a pointer type)
28170 * @flags: a set of #GFileQueryInfoFlags.
28171 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28172 * @error: a #GError, or %NULL
28174 * Sets an attribute in the file with attribute name @attribute to @value.
28176 * Some attributes can be unset by setting @attribute to
28177 * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
28179 * If @cancellable is not %NULL, then the operation can be cancelled by
28180 * triggering the cancellable object from another thread. If the operation
28181 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28183 * Returns: %TRUE if the attribute was set, %FALSE otherwise.
28188 * g_file_set_attribute_byte_string:
28189 * @file: input #GFile.
28190 * @attribute: a string containing the attribute's name.
28191 * @value: a string containing the attribute's new value.
28192 * @flags: a #GFileQueryInfoFlags.
28193 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28194 * @error: a #GError, or %NULL
28196 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value.
28197 * If @attribute is of a different type, this operation will fail,
28198 * returning %FALSE.
28200 * If @cancellable is not %NULL, then the operation can be cancelled by
28201 * triggering the cancellable object from another thread. If the operation
28202 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28204 * in the @file, %FALSE otherwise.
28206 * Returns: %TRUE if the @attribute was successfully set to @value
28211 * g_file_set_attribute_int32:
28212 * @file: input #GFile.
28213 * @attribute: a string containing the attribute's name.
28214 * @value: a #gint32 containing the attribute's new value.
28215 * @flags: a #GFileQueryInfoFlags.
28216 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28217 * @error: a #GError, or %NULL
28219 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value.
28220 * If @attribute is of a different type, this operation will fail.
28222 * If @cancellable is not %NULL, then the operation can be cancelled by
28223 * triggering the cancellable object from another thread. If the operation
28224 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28226 * in the @file, %FALSE otherwise.
28228 * Returns: %TRUE if the @attribute was successfully set to @value
28233 * g_file_set_attribute_int64:
28234 * @file: input #GFile.
28235 * @attribute: a string containing the attribute's name.
28236 * @value: a #guint64 containing the attribute's new value.
28237 * @flags: a #GFileQueryInfoFlags.
28238 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28239 * @error: a #GError, or %NULL
28241 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value.
28242 * If @attribute is of a different type, this operation will fail.
28244 * If @cancellable is not %NULL, then the operation can be cancelled by
28245 * triggering the cancellable object from another thread. If the operation
28246 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28248 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
28253 * g_file_set_attribute_string:
28254 * @file: input #GFile.
28255 * @attribute: a string containing the attribute's name.
28256 * @value: a string containing the attribute's value.
28257 * @flags: #GFileQueryInfoFlags.
28258 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28259 * @error: a #GError, or %NULL
28261 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value.
28262 * If @attribute is of a different type, this operation will fail.
28264 * If @cancellable is not %NULL, then the operation can be cancelled by
28265 * triggering the cancellable object from another thread. If the operation
28266 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28268 * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
28273 * g_file_set_attribute_uint32:
28274 * @file: input #GFile.
28275 * @attribute: a string containing the attribute's name.
28276 * @value: a #guint32 containing the attribute's new value.
28277 * @flags: a #GFileQueryInfoFlags.
28278 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28279 * @error: a #GError, or %NULL
28281 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value.
28282 * If @attribute is of a different type, this operation will fail.
28284 * If @cancellable is not %NULL, then the operation can be cancelled by
28285 * triggering the cancellable object from another thread. If the operation
28286 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28288 * in the @file, %FALSE otherwise.
28290 * Returns: %TRUE if the @attribute was successfully set to @value
28295 * g_file_set_attribute_uint64:
28296 * @file: input #GFile.
28297 * @attribute: a string containing the attribute's name.
28298 * @value: a #guint64 containing the attribute's new value.
28299 * @flags: a #GFileQueryInfoFlags.
28300 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28301 * @error: a #GError, or %NULL
28303 * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value.
28304 * If @attribute is of a different type, this operation will fail.
28306 * If @cancellable is not %NULL, then the operation can be cancelled by
28307 * triggering the cancellable object from another thread. If the operation
28308 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28310 * in the @file, %FALSE otherwise.
28312 * Returns: %TRUE if the @attribute was successfully set to @value
28317 * g_file_set_attributes_async:
28318 * @file: input #GFile.
28319 * @info: a #GFileInfo.
28320 * @flags: a #GFileQueryInfoFlags.
28321 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
28322 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28323 * @callback: (scope async): a #GAsyncReadyCallback.
28324 * @user_data: (closure): a #gpointer.
28326 * Asynchronously sets the attributes of @file with @info.
28328 * For more details, see g_file_set_attributes_from_info() which is
28329 * the synchronous version of this call.
28331 * When the operation is finished, @callback will be called. You can then call
28332 * g_file_set_attributes_finish() to get the result of the operation.
28337 * g_file_set_attributes_finish:
28338 * @file: input #GFile.
28339 * @result: a #GAsyncResult.
28340 * @info: (out) (transfer full): a #GFileInfo.
28341 * @error: a #GError, or %NULL
28343 * Finishes setting an attribute started in g_file_set_attributes_async().
28345 * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
28350 * g_file_set_attributes_from_info:
28351 * @file: input #GFile.
28352 * @info: a #GFileInfo.
28353 * @flags: #GFileQueryInfoFlags
28354 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28355 * @error: a #GError, or %NULL
28357 * Tries to set all attributes in the #GFileInfo on the target values,
28358 * not stopping on the first error.
28360 * If there is any error during this operation then @error will be set to
28361 * the first error. Error on particular fields are flagged by setting
28362 * the "status" field in the attribute value to
28363 * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect
28366 * If @cancellable is not %NULL, then the operation can be cancelled by
28367 * triggering the cancellable object from another thread. If the operation
28368 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28370 * Returns: %TRUE if there was any error, %FALSE otherwise.
28375 * g_file_set_display_name:
28376 * @file: input #GFile.
28377 * @display_name: a string.
28378 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28379 * @error: a #GError, or %NULL
28381 * Renames @file to the specified display name.
28383 * The display name is converted from UTF8 to the correct encoding for the target
28384 * filesystem if possible and the @file is renamed to this.
28386 * If you want to implement a rename operation in the user interface the edit name
28387 * (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename
28388 * widget, and then the result after editing should be passed to g_file_set_display_name().
28390 * On success the resulting converted filename is returned.
28392 * If @cancellable is not %NULL, then the operation can be cancelled by
28393 * triggering the cancellable object from another thread. If the operation
28394 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28396 * if there was an error.
28397 * Free the returned object with g_object_unref().
28399 * Returns: (transfer full): a #GFile specifying what @file was renamed to, or %NULL
28404 * g_file_set_display_name_async:
28405 * @file: input #GFile.
28406 * @display_name: a string.
28407 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
28408 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28409 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
28410 * @user_data: (closure): the data to pass to callback function
28412 * Asynchronously sets the display name for a given #GFile.
28414 * For more details, see g_file_set_display_name() which is
28415 * the synchronous version of this call.
28417 * When the operation is finished, @callback will be called. You can then call
28418 * g_file_set_display_name_finish() to get the result of the operation.
28423 * g_file_set_display_name_finish:
28424 * @file: input #GFile.
28425 * @res: a #GAsyncResult.
28426 * @error: a #GError, or %NULL
28428 * Finishes setting a display name started with
28429 * g_file_set_display_name_async().
28431 * Free the returned object with g_object_unref().
28433 * Returns: (transfer full): a #GFile or %NULL on error.
28438 * g_file_start_mountable:
28439 * @file: input #GFile.
28440 * @flags: flags affecting the operation
28441 * @start_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
28442 * @cancellable: optional #GCancellable object, %NULL to ignore.
28443 * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
28444 * @user_data: the data to pass to callback function
28446 * Starts a file of type G_FILE_TYPE_MOUNTABLE.
28447 * Using @start_operation, you can request callbacks when, for instance,
28448 * passwords are needed during authentication.
28450 * If @cancellable is not %NULL, then the operation can be cancelled by
28451 * triggering the cancellable object from another thread. If the operation
28452 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28454 * When the operation is finished, @callback will be called. You can then call
28455 * g_file_mount_mountable_finish() to get the result of the operation.
28462 * g_file_start_mountable_finish:
28463 * @file: input #GFile.
28464 * @result: a #GAsyncResult.
28465 * @error: a #GError, or %NULL
28467 * Finishes a start operation. See g_file_start_mountable() for details.
28469 * Finish an asynchronous start operation that was started
28470 * with g_file_start_mountable().
28474 * Returns: %TRUE if the operation finished successfully. %FALSE
28480 * g_file_stop_mountable:
28481 * @file: input #GFile.
28482 * @flags: flags affecting the operation
28483 * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
28484 * @cancellable: optional #GCancellable object, %NULL to ignore.
28485 * @callback: a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
28486 * @user_data: the data to pass to callback function
28488 * Stops a file of type G_FILE_TYPE_MOUNTABLE.
28490 * If @cancellable is not %NULL, then the operation can be cancelled by
28491 * triggering the cancellable object from another thread. If the operation
28492 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28494 * When the operation is finished, @callback will be called. You can then call
28495 * g_file_stop_mountable_finish() to get the result of the operation.
28502 * g_file_stop_mountable_finish:
28503 * @file: input #GFile.
28504 * @result: a #GAsyncResult.
28505 * @error: a #GError, or %NULL
28507 * Finishes an stop operation, see g_file_stop_mountable() for details.
28509 * Finish an asynchronous stop operation that was started
28510 * with g_file_stop_mountable().
28514 * Returns: %TRUE if the operation finished successfully. %FALSE
28520 * g_file_supports_thread_contexts:
28523 * Checks if @file supports <link
28524 * linkend="g-main-context-push-thread-default-context">thread-default
28525 * contexts</link>. If this returns %FALSE, you cannot perform
28526 * asynchronous operations on @file in a thread that has a
28527 * thread-default context.
28529 * Returns: Whether or not @file supports thread-default contexts.
28536 * @file: #GFile to send to trash.
28537 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28538 * @error: a #GError, or %NULL
28540 * Sends @file to the "Trashcan", if possible. This is similar to
28541 * deleting it, but the user can recover it before emptying the trashcan.
28542 * Not all file systems support trashing, so this call can return the
28543 * %G_IO_ERROR_NOT_SUPPORTED error.
28546 * If @cancellable is not %NULL, then the operation can be cancelled by
28547 * triggering the cancellable object from another thread. If the operation
28548 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28550 * Returns: %TRUE on successful trash, %FALSE otherwise.
28555 * g_file_unmount_mountable:
28556 * @file: input #GFile.
28557 * @flags: flags affecting the operation
28558 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28559 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
28560 * @user_data: (closure): the data to pass to callback function
28562 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
28564 * If @cancellable is not %NULL, then the operation can be cancelled by
28565 * triggering the cancellable object from another thread. If the operation
28566 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28568 * When the operation is finished, @callback will be called. You can then call
28569 * g_file_unmount_mountable_finish() to get the result of the operation.
28571 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead.
28576 * g_file_unmount_mountable_finish:
28577 * @file: input #GFile.
28578 * @result: a #GAsyncResult.
28579 * @error: a #GError, or %NULL
28581 * Finishes an unmount operation, see g_file_unmount_mountable() for details.
28583 * Finish an asynchronous unmount operation that was started
28584 * with g_file_unmount_mountable().
28588 * Returns: %TRUE if the operation finished successfully. %FALSE
28589 * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead.
28594 * g_file_unmount_mountable_with_operation:
28595 * @file: input #GFile.
28596 * @flags: flags affecting the operation
28597 * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction.
28598 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
28599 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL.
28600 * @user_data: (closure): the data to pass to callback function
28602 * Unmounts a file of type G_FILE_TYPE_MOUNTABLE.
28604 * If @cancellable is not %NULL, then the operation can be cancelled by
28605 * triggering the cancellable object from another thread. If the operation
28606 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
28608 * When the operation is finished, @callback will be called. You can then call
28609 * g_file_unmount_mountable_finish() to get the result of the operation.
28616 * g_file_unmount_mountable_with_operation_finish:
28617 * @file: input #GFile.
28618 * @result: a #GAsyncResult.
28619 * @error: a #GError, or %NULL
28621 * Finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details.
28623 * Finish an asynchronous unmount operation that was started
28624 * with g_file_unmount_mountable_with_operation().
28628 * Returns: %TRUE if the operation finished successfully. %FALSE
28634 * g_filename_completer_get_completion_suffix:
28635 * @completer: the filename completer.
28636 * @initial_text: text to be completed.
28638 * Obtains a completion for @initial_text from @completer.
28640 * This string is not owned by GIO, so remember to g_free() it
28643 * Returns: a completed string, or %NULL if no completion exists.
28648 * g_filename_completer_get_completions:
28649 * @completer: the filename completer.
28650 * @initial_text: text to be completed.
28652 * Gets an array of completion strings for a given initial text.
28654 * This array must be freed by g_strfreev() when finished.
28656 * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text.
28661 * g_filename_completer_new:
28663 * Creates a new filename completer.
28665 * Returns: a #GFilenameCompleter.
28670 * g_filename_completer_set_dirs_only:
28671 * @completer: the filename completer.
28672 * @dirs_only: a #gboolean.
28674 * If @dirs_only is %TRUE, @completer will only
28675 * complete directory names, and not file names.
28680 * g_filter_input_stream_get_base_stream:
28681 * @stream: a #GFilterInputStream.
28683 * Gets the base stream for the filter stream.
28685 * Returns: (transfer none): a #GInputStream.
28690 * g_filter_input_stream_get_close_base_stream:
28691 * @stream: a #GFilterInputStream.
28693 * Returns whether the base stream will be closed when @stream is
28696 * Returns: %TRUE if the base stream will be closed.
28701 * g_filter_input_stream_set_close_base_stream:
28702 * @stream: a #GFilterInputStream.
28703 * @close_base: %TRUE to close the base stream.
28705 * Sets whether the base stream will be closed when @stream is closed.
28710 * g_filter_output_stream_get_base_stream:
28711 * @stream: a #GFilterOutputStream.
28713 * Gets the base stream for the filter stream.
28715 * Returns: (transfer none): a #GOutputStream.
28720 * g_filter_output_stream_get_close_base_stream:
28721 * @stream: a #GFilterOutputStream.
28723 * Returns whether the base stream will be closed when @stream is
28726 * Returns: %TRUE if the base stream will be closed.
28731 * g_filter_output_stream_set_close_base_stream:
28732 * @stream: a #GFilterOutputStream.
28733 * @close_base: %TRUE to close the base stream.
28735 * Sets whether the base stream will be closed when @stream is closed.
28741 * @icon1: (allow-none): pointer to the first #GIcon.
28742 * @icon2: (allow-none): pointer to the second #GIcon.
28744 * Checks if two icons are equal.
28746 * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
28752 * @icon: #gconstpointer to an icon object.
28754 * Gets a hash for an icon.
28756 * use in a #GHashTable or similar data structure.
28759 * Returns: a #guint containing a hash for the @icon, suitable for
28764 * g_icon_new_for_string:
28765 * @str: A string obtained via g_icon_to_string().
28766 * @error: Return location for error.
28768 * Generate a #GIcon instance from @str. This function can fail if
28769 * @str is not valid - see g_icon_to_string() for discussion.
28771 * If your application or library provides one or more #GIcon
28772 * implementations you need to ensure that each #GType is registered
28773 * with the type system prior to calling g_icon_new_for_string().
28775 * interface or %NULL if @error is set.
28777 * Returns: (transfer full): An object implementing the #GIcon
28783 * g_icon_to_string:
28786 * Generates a textual representation of @icon that can be used for
28787 * serialization such as when passing @icon to a different process or
28788 * saving it to persistent storage. Use g_icon_new_for_string() to
28789 * get @icon back from the returned string.
28791 * The encoding of the returned string is proprietary to #GIcon except
28792 * in the following two cases
28796 * If @icon is a #GFileIcon, the returned string is a native path
28797 * (such as <literal>/path/to/my icon.png</literal>) without escaping
28798 * if the #GFile for @icon is a native file. If the file is not
28799 * native, the returned string is the result of g_file_get_uri()
28800 * (such as <literal>sftp://path/to/my%20icon.png</literal>).
28801 * </para></listitem>
28803 * If @icon is a #GThemedIcon with exactly one name, the encoding is
28804 * simply the name (such as <literal>network-server</literal>).
28805 * </para></listitem>
28808 * be serialized. Use g_free() to free.
28810 * Virtual: to_tokens
28811 * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
28817 * g_inet_address_equal:
28818 * @address: A #GInetAddress.
28819 * @other_address: Another #GInetAddress.
28821 * Checks if two #GInetAddress instances are equal, e.g. the same address.
28823 * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise.
28829 * g_inet_address_get_family:
28830 * @address: a #GInetAddress
28832 * Gets @address's family
28834 * Returns: @address's family
28840 * g_inet_address_get_is_any:
28841 * @address: a #GInetAddress
28843 * Tests whether @address is the "any" address for its family.
28845 * Returns: %TRUE if @address is the "any" address for its family.
28851 * g_inet_address_get_is_link_local:
28852 * @address: a #GInetAddress
28854 * Tests whether @address is a link-local address (that is, if it
28855 * identifies a host on a local network that is not connected to the
28858 * Returns: %TRUE if @address is a link-local address.
28864 * g_inet_address_get_is_loopback:
28865 * @address: a #GInetAddress
28867 * Tests whether @address is the loopback address for its family.
28869 * Returns: %TRUE if @address is the loopback address for its family.
28875 * g_inet_address_get_is_mc_global:
28876 * @address: a #GInetAddress
28878 * Tests whether @address is a global multicast address.
28880 * Returns: %TRUE if @address is a global multicast address.
28886 * g_inet_address_get_is_mc_link_local:
28887 * @address: a #GInetAddress
28889 * Tests whether @address is a link-local multicast address.
28891 * Returns: %TRUE if @address is a link-local multicast address.
28897 * g_inet_address_get_is_mc_node_local:
28898 * @address: a #GInetAddress
28900 * Tests whether @address is a node-local multicast address.
28902 * Returns: %TRUE if @address is a node-local multicast address.
28908 * g_inet_address_get_is_mc_org_local:
28909 * @address: a #GInetAddress
28911 * Tests whether @address is an organization-local multicast address.
28913 * Returns: %TRUE if @address is an organization-local multicast address.
28919 * g_inet_address_get_is_mc_site_local:
28920 * @address: a #GInetAddress
28922 * Tests whether @address is a site-local multicast address.
28924 * Returns: %TRUE if @address is a site-local multicast address.
28930 * g_inet_address_get_is_multicast:
28931 * @address: a #GInetAddress
28933 * Tests whether @address is a multicast address.
28935 * Returns: %TRUE if @address is a multicast address.
28941 * g_inet_address_get_is_site_local:
28942 * @address: a #GInetAddress
28944 * Tests whether @address is a site-local address such as 10.0.0.1
28945 * (that is, the address identifies a host on a local network that can
28946 * not be reached directly from the Internet, but which may have
28947 * outgoing Internet connectivity via a NAT or firewall).
28949 * Returns: %TRUE if @address is a site-local address.
28955 * g_inet_address_get_native_size:
28956 * @address: a #GInetAddress
28958 * Gets the size of the native raw binary address for @address. This
28959 * is the size of the data that you get from g_inet_address_to_bytes().
28961 * Returns: the number of bytes used for the native version of @address.
28967 * g_inet_address_mask_equal:
28968 * @mask: a #GInetAddressMask
28969 * @mask2: another #GInetAddressMask
28971 * Tests if @mask and @mask2 are the same mask.
28973 * Returns: whether @mask and @mask2 are the same mask
28979 * g_inet_address_mask_get_address:
28980 * @mask: a #GInetAddressMask
28982 * Gets @mask's base address
28984 * Returns: (transfer none): @mask's base address
28990 * g_inet_address_mask_get_family:
28991 * @mask: a #GInetAddressMask
28993 * Gets the #GSocketFamily of @mask's address
28995 * Returns: the #GSocketFamily of @mask's address
29001 * g_inet_address_mask_get_length:
29002 * @mask: a #GInetAddressMask
29004 * Gets @mask's length
29006 * Returns: @mask's length
29012 * g_inet_address_mask_matches:
29013 * @mask: a #GInetAddressMask
29014 * @address: a #GInetAddress
29016 * Tests if @address falls within the range described by @mask.
29020 * Returns: whether @address falls within the range described by
29026 * g_inet_address_mask_new:
29027 * @addr: a #GInetAddress
29028 * @length: number of bits of @addr to use
29029 * @error: return location for #GError, or %NULL
29031 * Creates a new #GInetAddressMask representing all addresses whose
29032 * first @length bits match @addr.
29034 * Returns: a new #GInetAddressMask, or %NULL on error
29040 * g_inet_address_mask_new_from_string:
29041 * @mask_string: an IP address or address/length string
29042 * @error: return location for #GError, or %NULL
29044 * Parses @mask_string as an IP address and (optional) length, and
29045 * creates a new #GInetAddressMask. The length, if present, is
29046 * delimited by a "/". If it is not present, then the length is
29047 * assumed to be the full length of the address.
29051 * Returns: a new #GInetAddressMask corresponding to @string, or %NULL
29057 * g_inet_address_mask_to_string:
29058 * @mask: a #GInetAddressMask
29060 * Converts @mask back to its corresponding string form.
29062 * Returns: a string corresponding to @mask.
29068 * g_inet_address_new_any:
29069 * @family: the address family
29071 * Creates a #GInetAddress for the "any" address (unassigned/"don't
29072 * care") for @family.
29076 * Returns: a new #GInetAddress corresponding to the "any" address
29082 * g_inet_address_new_from_bytes:
29083 * @bytes: (array) (element-type guint8): raw address data
29084 * @family: the address family of @bytes
29086 * Creates a new #GInetAddress from the given @family and @bytes.
29087 * @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for
29088 * %G_SOCKET_FAMILY_IPV6.
29090 * Returns: a new #GInetAddress corresponding to @family and @bytes.
29096 * g_inet_address_new_from_string:
29097 * @string: a string representation of an IP address
29099 * Parses @string as an IP address and creates a new #GInetAddress.
29101 * @string could not be parsed.
29103 * Returns: a new #GInetAddress corresponding to @string, or %NULL if
29109 * g_inet_address_new_loopback:
29110 * @family: the address family
29112 * Creates a #GInetAddress for the loopback address for @family.
29116 * Returns: a new #GInetAddress corresponding to the loopback address
29122 * g_inet_address_to_bytes: (skip)
29123 * @address: a #GInetAddress
29125 * Gets the raw binary address data from @address.
29127 * which should not be modified, stored, or freed. The size of this
29128 * array can be gotten with g_inet_address_get_native_size().
29130 * Returns: a pointer to an internal array of the bytes in @address,
29136 * g_inet_address_to_string:
29137 * @address: a #GInetAddress
29139 * Converts @address to string form.
29143 * Returns: a representation of @address as a string, which should be
29149 * g_inet_socket_address_get_address:
29150 * @address: a #GInetSocketAddress
29152 * Gets @address's #GInetAddress.
29154 * g_object_ref()'d if it will be stored
29156 * Returns: (transfer none): the #GInetAddress for @address, which must be
29162 * g_inet_socket_address_get_flowinfo:
29163 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
29165 * Gets the <literal>sin6_flowinfo</literal> field from @address,
29166 * which must be an IPv6 address.
29168 * Returns: the flowinfo field
29174 * g_inet_socket_address_get_port:
29175 * @address: a #GInetSocketAddress
29177 * Gets @address's port.
29179 * Returns: the port for @address
29185 * g_inet_socket_address_get_scope_id:
29186 * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
29188 * Gets the <literal>sin6_scope_id</literal> field from @address,
29189 * which must be an IPv6 address.
29191 * Returns: the scope id field
29197 * g_inet_socket_address_new:
29198 * @address: a #GInetAddress
29199 * @port: a port number
29201 * Creates a new #GInetSocketAddress for @address and @port.
29203 * Returns: a new #GInetSocketAddress
29210 * @initable: a #GInitable.
29211 * @cancellable: optional #GCancellable object, %NULL to ignore.
29212 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29214 * Initializes the object implementing the interface.
29216 * The object must be initialized before any real use after initial
29217 * construction, either with this function or g_async_initable_init_async().
29219 * Implementations may also support cancellation. If @cancellable is not %NULL,
29220 * then initialization can be cancelled by triggering the cancellable object
29221 * from another thread. If the operation was cancelled, the error
29222 * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and
29223 * the object doesn't support cancellable initialization the error
29224 * %G_IO_ERROR_NOT_SUPPORTED will be returned.
29226 * If the object is not initialized, or initialization returns with an
29227 * error, then all operations on the object except g_object_ref() and
29228 * g_object_unref() are considered to be invalid, and have undefined
29229 * behaviour. See the <xref linkend="ginitable"/> section introduction
29230 * for more details.
29232 * Implementations of this method must be idempotent, i.e. multiple calls
29233 * to this function with the same argument should return the same results.
29234 * Only the first call initializes the object, further calls return the result
29235 * of the first call. This is so that it's safe to implement the singleton
29236 * pattern in the GObject constructor function.
29238 * return %FALSE and set @error appropriately if present.
29240 * Returns: %TRUE if successful. If an error has occurred, this function will
29247 * @object_type: a #GType supporting #GInitable.
29248 * @cancellable: optional #GCancellable object, %NULL to ignore.
29249 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29250 * @first_property_name: the name of the first property, or %NULL if no properties
29251 * @...: the value if the first property, followed by and other property value pairs, and ended by %NULL.
29253 * Helper function for constructing #GInitable object. This is
29254 * similar to g_object_new() but also initializes the object
29255 * and returns %NULL, setting an error on failure.
29257 * Returns: (transfer full): a newly allocated #GObject, or %NULL on error
29263 * g_initable_new_valist:
29264 * @object_type: a #GType supporting #GInitable.
29265 * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL.
29266 * @var_args: The var args list generated from @first_property_name.
29267 * @cancellable: optional #GCancellable object, %NULL to ignore.
29268 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29270 * Helper function for constructing #GInitable object. This is
29271 * similar to g_object_new_valist() but also initializes the object
29272 * and returns %NULL, setting an error on failure.
29274 * Returns: (transfer full): a newly allocated #GObject, or %NULL on error
29281 * @object_type: a #GType supporting #GInitable.
29282 * @n_parameters: the number of parameters in @parameters
29283 * @parameters: (array length=n_parameters): the parameters to use to construct the object
29284 * @cancellable: optional #GCancellable object, %NULL to ignore.
29285 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29287 * Helper function for constructing #GInitable object. This is
29288 * similar to g_object_newv() but also initializes the object
29289 * and returns %NULL, setting an error on failure.
29291 * Returns: (transfer full): a newly allocated #GObject, or %NULL on error
29297 * g_input_stream_clear_pending:
29298 * @stream: input stream
29300 * Clears the pending flag on @stream.
29305 * g_input_stream_close:
29306 * @stream: A #GInputStream.
29307 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29308 * @error: location to store the error occurring, or %NULL to ignore
29310 * Closes the stream, releasing resources related to it.
29312 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
29313 * Closing a stream multiple times will not return an error.
29315 * Streams will be automatically closed when the last reference
29316 * is dropped, but you might want to call this function to make sure
29317 * resources are released as early as possible.
29319 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
29320 * open after the stream is closed. See the documentation for the individual
29321 * stream for details.
29323 * On failure the first error that happened will be reported, but the close
29324 * operation will finish as much as possible. A stream that failed to
29325 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
29326 * is important to check and report the error to the user.
29328 * If @cancellable is not NULL, then the operation can be cancelled by
29329 * triggering the cancellable object from another thread. If the operation
29330 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
29331 * Cancelling a close will still leave the stream closed, but some streams
29332 * can use a faster close that doesn't block to e.g. check errors.
29334 * Returns: %TRUE on success, %FALSE on failure
29339 * g_input_stream_close_async:
29340 * @stream: A #GInputStream.
29341 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
29342 * @cancellable: (allow-none): optional cancellable object
29343 * @callback: (scope async): callback to call when the request is satisfied
29344 * @user_data: (closure): the data to pass to callback function
29346 * Requests an asynchronous closes of the stream, releasing resources related to it.
29347 * When the operation is finished @callback will be called.
29348 * You can then call g_input_stream_close_finish() to get the result of the
29351 * For behaviour details see g_input_stream_close().
29353 * The asyncronous methods have a default fallback that uses threads to implement
29354 * asynchronicity, so they are optional for inheriting classes. However, if you
29355 * override one you must override all.
29360 * g_input_stream_close_finish:
29361 * @stream: a #GInputStream.
29362 * @result: a #GAsyncResult.
29363 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29365 * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
29367 * Returns: %TRUE if the stream was closed successfully.
29372 * g_input_stream_has_pending:
29373 * @stream: input stream.
29375 * Checks if an input stream has pending actions.
29377 * Returns: %TRUE if @stream has pending actions.
29382 * g_input_stream_is_closed:
29383 * @stream: input stream.
29385 * Checks if an input stream is closed.
29387 * Returns: %TRUE if the stream is closed.
29392 * g_input_stream_read:
29393 * @stream: a #GInputStream.
29394 * @buffer: a buffer to read data into (which should be at least count bytes long).
29395 * @count: the number of bytes that will be read from the stream
29396 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29397 * @error: location to store the error occurring, or %NULL to ignore
29399 * Tries to read @count bytes from the stream into the buffer starting at
29400 * @buffer. Will block during this read.
29402 * If count is zero returns zero and does nothing. A value of @count
29403 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
29405 * On success, the number of bytes read into the buffer is returned.
29406 * It is not an error if this is not the same as the requested size, as it
29407 * can happen e.g. near the end of a file. Zero is returned on end of file
29408 * (or if @count is zero), but never otherwise.
29410 * If @cancellable is not NULL, then the operation can be cancelled by
29411 * triggering the cancellable object from another thread. If the operation
29412 * was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an
29413 * operation was partially finished when the operation was cancelled the
29414 * partial result will be returned, without an error.
29416 * On error -1 is returned and @error is set accordingly.
29418 * Returns: Number of bytes read, or -1 on error
29423 * g_input_stream_read_all:
29424 * @stream: a #GInputStream.
29425 * @buffer: a buffer to read data into (which should be at least count bytes long).
29426 * @count: the number of bytes that will be read from the stream
29427 * @bytes_read: (out): location to store the number of bytes that was read from the stream
29428 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29429 * @error: location to store the error occurring, or %NULL to ignore
29431 * Tries to read @count bytes from the stream into the buffer starting at
29432 * @buffer. Will block during this read.
29434 * This function is similar to g_input_stream_read(), except it tries to
29435 * read as many bytes as requested, only stopping on an error or end of stream.
29437 * On a successful read of @count bytes, or if we reached the end of the
29438 * stream, %TRUE is returned, and @bytes_read is set to the number of bytes
29439 * read into @buffer.
29441 * If there is an error during the operation %FALSE is returned and @error
29442 * is set to indicate the error status, @bytes_read is updated to contain
29443 * the number of bytes read into @buffer before the error occurred.
29445 * Returns: %TRUE on success, %FALSE if there was an error
29450 * g_input_stream_read_async:
29451 * @stream: A #GInputStream.
29452 * @buffer: a buffer to read data into (which should be at least count bytes long).
29453 * @count: the number of bytes that will be read from the stream
29454 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
29455 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29456 * @callback: (scope async): callback to call when the request is satisfied
29457 * @user_data: (closure): the data to pass to callback function
29459 * Request an asynchronous read of @count bytes from the stream into the buffer
29460 * starting at @buffer. When the operation is finished @callback will be called.
29461 * You can then call g_input_stream_read_finish() to get the result of the
29464 * During an async request no other sync and async calls are allowed on @stream, and will
29465 * result in %G_IO_ERROR_PENDING errors.
29467 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
29469 * On success, the number of bytes read into the buffer will be passed to the
29470 * callback. It is not an error if this is not the same as the requested size, as it
29471 * can happen e.g. near the end of a file, but generally we try to read
29472 * as many bytes as requested. Zero is returned on end of file
29473 * (or if @count is zero), but never otherwise.
29475 * Any outstanding i/o request with higher priority (lower numerical value) will
29476 * be executed before an outstanding request with lower priority. Default
29477 * priority is %G_PRIORITY_DEFAULT.
29479 * The asyncronous methods have a default fallback that uses threads to implement
29480 * asynchronicity, so they are optional for inheriting classes. However, if you
29481 * override one you must override all.
29486 * g_input_stream_read_finish:
29487 * @stream: a #GInputStream.
29488 * @result: a #GAsyncResult.
29489 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29491 * Finishes an asynchronous stream read operation.
29493 * Returns: number of bytes read in, or -1 on error.
29498 * g_input_stream_set_pending:
29499 * @stream: input stream
29500 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29502 * Sets @stream to have actions pending. If the pending flag is
29503 * already set or @stream is closed, it will return %FALSE and set
29506 * Returns: %TRUE if pending was previously unset and is now set.
29511 * g_input_stream_skip:
29512 * @stream: a #GInputStream.
29513 * @count: the number of bytes that will be skipped from the stream
29514 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29515 * @error: location to store the error occurring, or %NULL to ignore
29517 * Tries to skip @count bytes from the stream. Will block during the operation.
29519 * This is identical to g_input_stream_read(), from a behaviour standpoint,
29520 * but the bytes that are skipped are not returned to the user. Some
29521 * streams have an implementation that is more efficient than reading the data.
29523 * This function is optional for inherited classes, as the default implementation
29524 * emulates it using read.
29526 * If @cancellable is not %NULL, then the operation can be cancelled by
29527 * triggering the cancellable object from another thread. If the operation
29528 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
29529 * operation was partially finished when the operation was cancelled the
29530 * partial result will be returned, without an error.
29532 * Returns: Number of bytes skipped, or -1 on error
29537 * g_input_stream_skip_async:
29538 * @stream: A #GInputStream.
29539 * @count: the number of bytes that will be skipped from the stream
29540 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
29541 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
29542 * @callback: (scope async): callback to call when the request is satisfied
29543 * @user_data: (closure): the data to pass to callback function
29545 * Request an asynchronous skip of @count bytes from the stream.
29546 * When the operation is finished @callback will be called.
29547 * You can then call g_input_stream_skip_finish() to get the result
29548 * of the operation.
29550 * During an async request no other sync and async calls are allowed,
29551 * and will result in %G_IO_ERROR_PENDING errors.
29553 * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
29555 * On success, the number of bytes skipped will be passed to the callback.
29556 * It is not an error if this is not the same as the requested size, as it
29557 * can happen e.g. near the end of a file, but generally we try to skip
29558 * as many bytes as requested. Zero is returned on end of file
29559 * (or if @count is zero), but never otherwise.
29561 * Any outstanding i/o request with higher priority (lower numerical value)
29562 * will be executed before an outstanding request with lower priority.
29563 * Default priority is %G_PRIORITY_DEFAULT.
29565 * The asynchronous methods have a default fallback that uses threads to
29566 * implement asynchronicity, so they are optional for inheriting classes.
29567 * However, if you override one, you must override all.
29572 * g_input_stream_skip_finish:
29573 * @stream: a #GInputStream.
29574 * @result: a #GAsyncResult.
29575 * @error: a #GError location to store the error occurring, or %NULL to ignore.
29577 * Finishes a stream skip operation.
29579 * Returns: the size of the bytes skipped, or %-1 on error.
29584 * g_io_error_from_errno:
29585 * @err_no: Error number as defined in errno.h.
29587 * Converts errno.h error codes into GIO error codes.
29589 * Returns: #GIOErrorEnum value for the given errno.h error number.
29594 * g_io_error_from_win32_error:
29595 * @error_code: Windows error number.
29597 * Converts some common error codes into GIO error codes. The
29598 * fallback value G_IO_ERROR_FAILED is returned for error codes not
29601 * Returns: #GIOErrorEnum value for the given error number.
29607 * g_io_error_quark:
29609 * Gets the GIO Error Quark.
29611 * Returns: a #GQuark.
29616 * g_io_extension_get_name:
29617 * @extension: a #GIOExtension
29619 * Gets the name under which @extension was registered.
29621 * Note that the same type may be registered as extension
29622 * for multiple extension points, under different names.
29624 * Returns: the name of @extension.
29629 * g_io_extension_get_priority:
29630 * @extension: a #GIOExtension
29632 * Gets the priority with which @extension was registered.
29634 * Returns: the priority of @extension
29639 * g_io_extension_get_type:
29640 * @extension: a #GIOExtension
29642 * Gets the type associated with @extension.
29644 * Returns: the type of @extension
29649 * g_io_extension_point_get_extension_by_name:
29650 * @extension_point: a #GIOExtensionPoint
29651 * @name: the name of the extension to get
29653 * Finds a #GIOExtension for an extension point by name.
29655 * given name, or %NULL if there is no extension with that name
29657 * Returns: (transfer none): the #GIOExtension for @extension_point that has the
29662 * g_io_extension_point_get_extensions:
29663 * @extension_point: a #GIOExtensionPoint
29665 * Gets a list of all extensions that implement this extension point.
29666 * The list is sorted by priority, beginning with the highest priority.
29668 * #GIOExtension<!-- -->s. The list is owned by GIO and should not be
29671 * Returns: (element-type GIOExtension) (transfer none): a #GList of
29676 * g_io_extension_point_get_required_type:
29677 * @extension_point: a #GIOExtensionPoint
29679 * Gets the required type for @extension_point.
29681 * or #G_TYPE_INVALID if the extension point has no required type
29683 * Returns: the #GType that all implementations must have,
29688 * g_io_extension_point_implement:
29689 * @extension_point_name: the name of the extension point
29690 * @type: the #GType to register as extension
29691 * @extension_name: the name for the extension
29692 * @priority: the priority for the extension
29694 * Registers @type as extension for the extension point with name
29695 * @extension_point_name.
29697 * If @type has already been registered as an extension for this
29698 * extension point, the existing #GIOExtension object is returned.
29700 * Returns: (transfer none): a #GIOExtension object for #GType
29705 * g_io_extension_point_lookup:
29706 * @name: the name of the extension point
29708 * Looks up an existing extension point.
29710 * is no registered extension point with the given name.
29712 * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there
29717 * g_io_extension_point_register:
29718 * @name: The name of the extension point
29720 * Registers an extension point.
29722 * owned by GIO and should not be freed.
29724 * Returns: (transfer none): the new #GIOExtensionPoint. This object is
29729 * g_io_extension_point_set_required_type:
29730 * @extension_point: a #GIOExtensionPoint
29731 * @type: the #GType to require
29733 * Sets the required type for @extension_point to @type.
29734 * All implementations must henceforth have this type.
29739 * g_io_extension_ref_class:
29740 * @extension: a #GIOExtension
29742 * Gets a reference to the class for the type that is
29743 * associated with @extension.
29745 * Returns: (transfer full): the #GTypeClass for the type of @extension
29750 * g_io_module_load:
29751 * @module: a #GIOModule.
29753 * Required API for GIO modules to implement.
29754 * This function is ran after the module has been loaded into GIO,
29755 * to initialize the module.
29761 * @filename: filename of the shared library module.
29763 * Creates a new GIOModule that will load the specific
29764 * shared library when in use.
29766 * or %NULL on error.
29768 * Returns: a #GIOModule from given @filename,
29773 * g_io_module_query:
29775 * Optional API for GIO modules to implement.
29777 * Should return a list of all the extension points that may be
29778 * implemented in this module.
29780 * This method will not be called in normal use, however it may be
29781 * called when probing existing modules and recording which extension
29782 * points that this model is used for. This means we won't have to
29783 * load and initialze this module unless its needed.
29785 * If this function is not implemented by the module the module will
29786 * always be loaded, initialized and then unloaded on application startup
29787 * so that it can register its extension points during init.
29789 * Note that a module need not actually implement all the extension points
29790 * that g_io_module_query returns, since the exact list of extension may
29791 * depend on runtime issues. However all extension points actually implemented
29792 * must be returned by g_io_module_query() (if defined).
29794 * When installing a module that implements g_io_module_query you must
29795 * run gio-querymodules in order to build the cache files required for
29798 * extension points of the module. The array must be suitable for
29799 * freeing with g_strfreev().
29801 * Returns: (transfer full): A %NULL-terminated array of strings, listing the supported
29807 * g_io_module_scope_block:
29808 * @scope: a module loading scope
29809 * @basename: the basename to block
29811 * Block modules with the given @basename from being loaded when
29812 * this scope is used with g_io_modules_scan_all_in_directory_with_scope()
29813 * or g_io_modules_load_all_in_directory_with_scope().
29820 * g_io_module_scope_free:
29821 * @scope: a module loading scope
29823 * Free a module scope.
29830 * g_io_module_scope_new:
29831 * @flags: flags for the new scope
29833 * Create a new scope for loading of IO modules. A scope can be used for
29834 * blocking duplicate modules, or blocking a module you don't want to load.
29836 * Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules
29837 * which have the same base name as a module that has already been seen
29840 * Returns: (transfer full): the new module scope
29846 * g_io_module_unload:
29847 * @module: a #GIOModule.
29849 * Required API for GIO modules to implement.
29850 * This function is ran when the module is being unloaded from GIO,
29851 * to finalize the module.
29856 * g_io_modules_load_all_in_directory:
29857 * @dirname: pathname for a directory containing modules to load.
29859 * Loads all the modules in the specified directory.
29861 * If don't require all modules to be initialized (and thus registering
29862 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
29863 * which allows delayed/lazy loading of modules.
29865 * from the directory,
29866 * All the modules are loaded into memory, if you want to
29867 * unload them (enabling on-demand loading) you must call
29868 * g_type_module_unuse() on all the modules. Free the list
29869 * with g_list_free().
29871 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
29876 * g_io_modules_load_all_in_directory_with_scope:
29877 * @dirname: pathname for a directory containing modules to load.
29878 * @scope: a scope to use when scanning the modules.
29880 * Loads all the modules in the specified directory.
29882 * If don't require all modules to be initialized (and thus registering
29883 * all gtypes) then you can use g_io_modules_scan_all_in_directory()
29884 * which allows delayed/lazy loading of modules.
29886 * from the directory,
29887 * All the modules are loaded into memory, if you want to
29888 * unload them (enabling on-demand loading) you must call
29889 * g_type_module_unuse() on all the modules. Free the list
29890 * with g_list_free().
29892 * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
29898 * g_io_modules_scan_all_in_directory:
29899 * @dirname: pathname for a directory containing modules to scan.
29901 * Scans all the modules in the specified directory, ensuring that
29902 * any extension point implemented by a module is registered.
29904 * This may not actually load and initialize all the types in each
29905 * module, some modules may be lazily loaded and initialized when
29906 * an extension point it implementes is used with e.g.
29907 * g_io_extension_point_get_extensions() or
29908 * g_io_extension_point_get_extension_by_name().
29910 * If you need to guarantee that all types are loaded in all the modules,
29911 * use g_io_modules_load_all_in_directory().
29918 * g_io_modules_scan_all_in_directory_with_scope:
29919 * @dirname: pathname for a directory containing modules to scan.
29920 * @scope: a scope to use when scanning the modules
29922 * Scans all the modules in the specified directory, ensuring that
29923 * any extension point implemented by a module is registered.
29925 * This may not actually load and initialize all the types in each
29926 * module, some modules may be lazily loaded and initialized when
29927 * an extension point it implementes is used with e.g.
29928 * g_io_extension_point_get_extensions() or
29929 * g_io_extension_point_get_extension_by_name().
29931 * If you need to guarantee that all types are loaded in all the modules,
29932 * use g_io_modules_load_all_in_directory().
29939 * g_io_scheduler_cancel_all_jobs:
29941 * Cancels all cancellable I/O jobs.
29943 * A job is cancellable if a #GCancellable was passed into
29944 * g_io_scheduler_push_job().
29949 * g_io_scheduler_job_send_to_mainloop:
29950 * @job: a #GIOSchedulerJob
29951 * @func: a #GSourceFunc callback that will be called in the original thread
29952 * @user_data: data to pass to @func
29953 * @notify: a #GDestroyNotify for @user_data, or %NULL
29955 * Used from an I/O job to send a callback to be run in the thread
29956 * that the job was started from, waiting for the result (and thus
29957 * blocking the I/O job).
29959 * Returns: The return value of @func
29964 * g_io_scheduler_job_send_to_mainloop_async:
29965 * @job: a #GIOSchedulerJob
29966 * @func: a #GSourceFunc callback that will be called in the original thread
29967 * @user_data: data to pass to @func
29968 * @notify: a #GDestroyNotify for @user_data, or %NULL
29970 * Used from an I/O job to send a callback to be run asynchronously in
29971 * the thread that the job was started from. The callback will be run
29972 * when the main loop is available, but at that time the I/O job might
29973 * have finished. The return value from the callback is ignored.
29975 * Note that if you are passing the @user_data from g_io_scheduler_push_job()
29976 * on to this function you have to ensure that it is not freed before
29977 * @func is called, either by passing %NULL as @notify to
29978 * g_io_scheduler_push_job() or by using refcounting for @user_data.
29983 * g_io_scheduler_push_job:
29984 * @job_func: a #GIOSchedulerJobFunc.
29985 * @user_data: data to pass to @job_func
29986 * @notify: a #GDestroyNotify for @user_data, or %NULL
29987 * @io_priority: the <link linkend="gioscheduler">I/O priority</link> of the request.
29988 * @cancellable: optional #GCancellable object, %NULL to ignore.
29990 * Schedules the I/O job to run in another thread.
29992 * @notify will be called on @user_data after @job_func has returned,
29993 * regardless whether the job was cancelled or has run to completion.
29995 * If @cancellable is not %NULL, it can be used to cancel the I/O job
29996 * by calling g_cancellable_cancel() or by calling
29997 * g_io_scheduler_cancel_all_jobs().
30002 * g_io_stream_clear_pending:
30003 * @stream: a #GIOStream
30005 * Clears the pending flag on @stream.
30012 * g_io_stream_close:
30013 * @stream: a #GIOStream
30014 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
30015 * @error: location to store the error occurring, or %NULL to ignore
30017 * Closes the stream, releasing resources related to it. This will also
30018 * closes the individual input and output streams, if they are not already
30021 * Once the stream is closed, all other operations will return
30022 * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not
30025 * Closing a stream will automatically flush any outstanding buffers
30028 * Streams will be automatically closed when the last reference
30029 * is dropped, but you might want to call this function to make sure
30030 * resources are released as early as possible.
30032 * Some streams might keep the backing store of the stream (e.g. a file
30033 * descriptor) open after the stream is closed. See the documentation for
30034 * the individual stream for details.
30036 * On failure the first error that happened will be reported, but the
30037 * close operation will finish as much as possible. A stream that failed
30038 * to close will still return %G_IO_ERROR_CLOSED for all operations.
30039 * Still, it is important to check and report the error to the user,
30040 * otherwise there might be a loss of data as all data might not be written.
30042 * If @cancellable is not NULL, then the operation can be cancelled by
30043 * triggering the cancellable object from another thread. If the operation
30044 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
30045 * Cancelling a close will still leave the stream closed, but some streams
30046 * can use a faster close that doesn't block to e.g. check errors.
30048 * The default implementation of this method just calls close on the
30049 * individual input/output streams.
30051 * Returns: %TRUE on success, %FALSE on failure
30057 * g_io_stream_close_async:
30058 * @stream: a #GIOStream
30059 * @io_priority: the io priority of the request
30060 * @cancellable: (allow-none): optional cancellable object
30061 * @callback: (scope async): callback to call when the request is satisfied
30062 * @user_data: (closure): the data to pass to callback function
30064 * Requests an asynchronous close of the stream, releasing resources
30065 * related to it. When the operation is finished @callback will be
30066 * called. You can then call g_io_stream_close_finish() to get
30067 * the result of the operation.
30069 * For behaviour details see g_io_stream_close().
30071 * The asynchronous methods have a default fallback that uses threads
30072 * to implement asynchronicity, so they are optional for inheriting
30073 * classes. However, if you override one you must override all.
30080 * g_io_stream_close_finish:
30081 * @stream: a #GIOStream
30082 * @result: a #GAsyncResult
30083 * @error: a #GError location to store the error occurring, or %NULL to ignore
30087 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
30093 * g_io_stream_get_input_stream:
30094 * @stream: a #GIOStream
30096 * Gets the input stream for this object. This is used
30101 * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
30107 * g_io_stream_get_output_stream:
30108 * @stream: a #GIOStream
30110 * Gets the output stream for this object. This is used for
30115 * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
30121 * g_io_stream_has_pending:
30122 * @stream: a #GIOStream
30124 * Checks if a stream has pending actions.
30126 * Returns: %TRUE if @stream has pending actions.
30132 * g_io_stream_is_closed:
30133 * @stream: a #GIOStream
30135 * Checks if a stream is closed.
30137 * Returns: %TRUE if the stream is closed.
30143 * g_io_stream_set_pending:
30144 * @stream: a #GIOStream
30145 * @error: a #GError location to store the error occurring, or %NULL to ignore
30147 * Sets @stream to have actions pending. If the pending flag is
30148 * already set or @stream is closed, it will return %FALSE and set
30151 * Returns: %TRUE if pending was previously unset and is now set.
30157 * g_io_stream_splice_async:
30158 * @stream1: a #GIOStream.
30159 * @stream2: a #GIOStream.
30160 * @flags: a set of #GIOStreamSpliceFlags.
30161 * @io_priority: the io priority of the request.
30162 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30163 * @callback: (scope async): a #GAsyncReadyCallback.
30164 * @user_data: (closure): user data passed to @callback.
30166 * Asyncronously splice the output stream of @stream1 to the input stream of
30167 * @stream2, and splice the output stream of @stream2 to the input stream of
30170 * When the operation is finished @callback will be called.
30171 * You can then call g_io_stream_splice_finish() to get the
30172 * result of the operation.
30179 * g_io_stream_splice_finish:
30180 * @result: a #GAsyncResult.
30181 * @error: a #GError location to store the error occurring, or %NULL to ignore.
30183 * Finishes an asynchronous io stream splice operation.
30185 * Returns: %TRUE on success, %FALSE otherwise.
30191 * g_keyfile_settings_backend_new:
30192 * @filename: the filename of the keyfile
30193 * @root_path: the path under which all settings keys appear
30194 * @root_group: (allow-none): the group name corresponding to @root_path, or %NULL
30196 * Creates a keyfile-backed #GSettingsBackend.
30198 * The filename of the keyfile to use is given by @filename.
30200 * All settings read to or written from the backend must fall under the
30201 * path given in @root_path (which must start and end with a slash and
30202 * not contain two consecutive slashes). @root_path may be "/".
30204 * If @root_group is non-%NULL then it specifies the name of the keyfile
30205 * group used for keys that are written directly below @root_path. For
30206 * example, if @root_path is "/apps/example/" and @root_group is
30207 * "toplevel", then settings the key "/apps/example/enabled" to a value
30208 * of %TRUE will cause the following to appear in the keyfile:
30215 * If @root_group is %NULL then it is not permitted to store keys
30216 * directly below the @root_path.
30218 * For keys not stored directly below @root_path (ie: in a sub-path),
30219 * the name of the subpath (with the final slash stripped) is used as
30220 * the name of the keyfile group. To continue the example, if
30221 * "/apps/example/profiles/default/font-size" were set to
30222 * 12 then the following would appear in the keyfile:
30225 * [profiles/default]
30229 * The backend will refuse writes (and return writability as being
30230 * %FALSE) for keys outside of @root_path and, in the event that
30231 * @root_group is %NULL, also for keys directly under @root_path.
30232 * Writes will also be refused if the backend detects that it has the
30233 * inability to rewrite the keyfile (ie: the containing directory is not
30236 * There is no checking done for your key namespace clashing with the
30237 * syntax of the key file format. For example, if you have '[' or ']'
30238 * characters in your path names or '=' in your key names you may be in
30241 * Returns: (transfer full): a keyfile-backed #GSettingsBackend
30246 * g_loadable_icon_load:
30247 * @icon: a #GLoadableIcon.
30248 * @size: an integer.
30249 * @type: (out) (allow-none): a location to store the type of the loaded icon, %NULL to ignore.
30250 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30251 * @error: a #GError location to store the error occurring, or %NULL to ignore.
30253 * Loads a loadable icon. For the asynchronous version of this function,
30254 * see g_loadable_icon_load_async().
30256 * Returns: (transfer full): a #GInputStream to read the icon from.
30261 * g_loadable_icon_load_async:
30262 * @icon: a #GLoadableIcon.
30263 * @size: an integer.
30264 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
30265 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
30266 * @user_data: (closure): the data to pass to callback function
30268 * Loads an icon asynchronously. To finish this function, see
30269 * g_loadable_icon_load_finish(). For the synchronous, blocking
30270 * version of this function, see g_loadable_icon_load().
30275 * g_loadable_icon_load_finish:
30276 * @icon: a #GLoadableIcon.
30277 * @res: a #GAsyncResult.
30278 * @type: a location to store the type of the loaded icon, %NULL to ignore.
30279 * @error: a #GError location to store the error occurring, or %NULL to ignore.
30281 * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
30283 * Returns: (transfer full): a #GInputStream to read the icon from.
30290 * Returns a new #GVfs handle for a local vfs.
30292 * Returns: a new #GVfs handle.
30298 * @loop: a #GMainLoop
30300 * Frees the memory allocated for the #GMainLoop.
30302 * Deprecated: 2.2: Use g_main_loop_unref() instead
30307 * g_main_is_running:
30308 * @loop: a #GMainLoop
30310 * Checks if the main loop is running.
30312 * Returns: %TRUE if the main loop is running
30313 * Deprecated: 2.2: Use g_main_loop_is_running() instead
30318 * g_main_iteration:
30319 * @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.
30321 * Runs a single iteration for the default #GMainContext.
30323 * Returns: %TRUE if more events are pending.
30324 * Deprecated: 2.2: Use g_main_context_iteration() instead.
30330 * @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.
30332 * Creates a new #GMainLoop for th default main context.
30334 * Returns: a new #GMainLoop
30335 * Deprecated: 2.2: Use g_main_loop_new() instead
30342 * Checks if any events are pending for the default #GMainContext
30343 * (i.e. ready to be processed).
30346 * Deprected: 2.2: Use g_main_context_pending() instead.
30348 * Returns: %TRUE if any events are pending.
30354 * @loop: a #GMainLoop
30356 * Stops the #GMainLoop.
30357 * If g_main_run() was called to run the #GMainLoop, it will now return.
30359 * Deprecated: 2.2: Use g_main_loop_quit() instead
30365 * @loop: a #GMainLoop
30367 * Runs a main loop until it stops running.
30369 * Deprecated: 2.2: Use g_main_loop_run() instead
30374 * g_main_set_poll_func:
30375 * @func: the function to call to poll all file descriptors
30377 * Sets the function to use for the handle polling of file descriptors
30378 * for the default main context.
30380 * Deprecated: 2.2: Use g_main_context_set_poll_func() again
30385 * g_memory_input_stream_add_data:
30386 * @stream: a #GMemoryInputStream
30387 * @data: (array length=len) (element-type guint8) (transfer full): input data
30388 * @len: length of the data, may be -1 if @data is a nul-terminated string
30389 * @destroy: (allow-none): function that is called to free @data, or %NULL
30391 * Appends @data to data that can be read from the input stream
30396 * g_memory_input_stream_new:
30398 * Creates a new empty #GMemoryInputStream.
30400 * Returns: a new #GInputStream
30405 * g_memory_input_stream_new_from_data:
30406 * @data: (array length=len) (element-type guint8) (transfer full): input data
30407 * @len: length of the data, may be -1 if @data is a nul-terminated string
30408 * @destroy: (allow-none): function that is called to free @data, or %NULL
30410 * Creates a new #GMemoryInputStream with data in memory of a given size.
30412 * Returns: new #GInputStream read from @data of @len bytes.
30417 * g_memory_output_stream_get_data:
30418 * @ostream: a #GMemoryOutputStream
30420 * Gets any loaded data from the @ostream.
30422 * Note that the returned pointer may become invalid on the next
30423 * write or truncate operation on the stream.
30425 * Returns: (transfer none): pointer to the stream's data
30430 * g_memory_output_stream_get_data_size:
30431 * @ostream: a #GMemoryOutputStream
30433 * Returns the number of bytes from the start up
30434 * to including the last byte written in the stream
30435 * that has not been truncated away.
30437 * Returns: the number of bytes written to the stream
30443 * g_memory_output_stream_get_size:
30444 * @ostream: a #GMemoryOutputStream
30446 * Gets the size of the currently allocated data area (available from
30447 * g_memory_output_stream_get_data()). If the stream isn't
30448 * growable (no realloc was passed to g_memory_output_stream_new()) then
30449 * this is the maximum size of the stream and further writes
30450 * will return %G_IO_ERROR_NO_SPACE.
30452 * Note that for growable streams the returned size may become invalid on
30453 * the next write or truncate operation on the stream.
30455 * If you want the number of bytes currently written to the stream, use
30456 * g_memory_output_stream_get_data_size().
30458 * Returns: the number of bytes allocated for the data buffer
30463 * g_memory_output_stream_new: (skip)
30464 * @data: pointer to a chunk of memory to use, or %NULL
30465 * @size: the size of @data
30466 * @realloc_function: a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL
30467 * @destroy_function: a function to be called on @data when the stream is finalized, or %NULL
30469 * Creates a new #GMemoryOutputStream.
30471 * If @data is non-%NULL, the stream will use that for its internal storage.
30472 * If @realloc_fn is non-%NULL, it will be used for resizing the internal
30473 * storage when necessary. To construct a fixed-size output stream,
30474 * pass %NULL as @realloc_fn.
30477 * /* a stream that can grow */
30478 * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
30480 * /* another stream that can grow */
30481 * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
30483 * /* a fixed-size stream */
30484 * data = malloc (200);
30485 * stream3 = g_memory_output_stream_new (data, 200, NULL, free);
30488 * Returns: A newly created #GMemoryOutputStream object.
30493 * g_memory_output_stream_steal_data:
30494 * @ostream: a #GMemoryOutputStream
30496 * Gets any loaded data from the @ostream. Ownership of the data
30497 * is transferred to the caller; when no longer needed it must be
30498 * freed using the free function set in @ostream's
30499 * #GMemoryOutputStream:destroy-function property.
30501 * @ostream must be closed before calling this function.
30503 * Returns: (transfer full): the stream's data
30509 * g_memory_settings_backend_new:
30511 * Creates a memory-backed #GSettingsBackend.
30513 * This backend allows changes to settings, but does not write them
30514 * to any backing storage, so the next time you run your application,
30515 * the memory backend will start out with the default values again.
30517 * Returns: (transfer full): a newly created #GSettingsBackend
30525 * @label: (allow-none): the section label, or %NULL
30526 * @detailed_action: (allow-none): the detailed action string, or %NULL
30528 * Convenience function for appending a normal menu item to the end of
30529 * @menu. Combine g_menu_new() and g_menu_insert_item() for a more
30530 * flexible alternative.
30537 * g_menu_append_item:
30539 * @item: a #GMenuItem to append
30541 * Appends @item to the end of @menu.
30543 * See g_menu_insert_item() for more information.
30550 * g_menu_append_section:
30552 * @label: (allow-none): the section label, or %NULL
30553 * @section: a #GMenuModel with the items of the section
30555 * Convenience function for appending a section menu item to the end of
30556 * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a
30557 * more flexible alternative.
30564 * g_menu_append_submenu:
30566 * @label: (allow-none): the section label, or %NULL
30567 * @submenu: a #GMenuModel with the items of the submenu
30569 * Convenience function for appending a submenu menu item to the end of
30570 * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a
30571 * more flexible alternative.
30578 * g_menu_attribute_iter_get_name:
30579 * @iter: a #GMenuAttributeIter
30581 * Gets the name of the attribute at the current iterator position, as
30584 * The iterator is not advanced.
30586 * Returns: the name of the attribute
30592 * g_menu_attribute_iter_get_next:
30593 * @iter: a #GMenuAttributeIter
30594 * @out_name: (out) (allow-none) (transfer none): the type of the attribute
30595 * @value: (out) (allow-none) (transfer full): the attribute value
30597 * This function combines g_menu_attribute_iter_next() with
30598 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
30600 * First the iterator is advanced to the next (possibly first) attribute.
30601 * If that fails, then %FALSE is returned and there are no other
30604 * If successful, @name and @value are set to the name and value of the
30605 * attribute that has just been advanced to. At this point,
30606 * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will
30607 * return the same values again.
30609 * The value returned in @name remains valid for as long as the iterator
30610 * remains at the current position. The value returned in @value must
30611 * be unreffed using g_variant_unref() when it is no longer in use.
30615 * Returns: %TRUE on success, or %FALSE if there is no additional
30621 * g_menu_attribute_iter_get_value:
30622 * @iter: a #GMenuAttributeIter
30624 * Gets the value of the attribute at the current iterator position.
30626 * The iterator is not advanced.
30628 * Returns: (transfer full): the value of the current attribute
30634 * g_menu_attribute_iter_next:
30635 * @iter: a #GMenuAttributeIter
30637 * Attempts to advance the iterator to the next (possibly first)
30640 * %TRUE is returned on success, or %FALSE if there are no more
30643 * You must call this function when you first acquire the iterator
30644 * to advance it to the first attribute (and determine if the first
30645 * attribute exists at all).
30647 * Returns: %TRUE on success, or %FALSE when there are no more attributes
30656 * Marks @menu as frozen.
30658 * After the menu is frozen, it is an error to attempt to make any
30659 * changes to it. In effect this means that the #GMenu API must no
30662 * This function causes g_menu_model_is_mutable() to begin returning
30663 * %FALSE, which has some positive performance implications.
30672 * @position: the position at which to insert the item
30673 * @label: (allow-none): the section label, or %NULL
30674 * @detailed_action: (allow-none): the detailed action string, or %NULL
30676 * Convenience function for inserting a normal menu item into @menu.
30677 * Combine g_menu_new() and g_menu_insert_item() for a more flexible
30685 * g_menu_insert_item:
30687 * @position: the position at which to insert the item
30688 * @item: the #GMenuItem to insert
30690 * Inserts @item into @menu.
30692 * The "insertion" is actually done by copying all of the attribute and
30693 * link values of @item and using them to form a new item within @menu.
30694 * As such, @item itself is not really inserted, but rather, a menu item
30695 * that is exactly the same as the one presently described by @item.
30697 * This means that @item is essentially useless after the insertion
30698 * occurs. Any changes you make to it are ignored unless it is inserted
30699 * again (at which point its updated values will be copied).
30701 * You should probably just free @item once you're done.
30703 * There are many convenience functions to take care of common cases.
30704 * See g_menu_insert(), g_menu_insert_section() and
30705 * g_menu_insert_submenu() as well as "prepend" and "append" variants of
30706 * each of these functions.
30713 * g_menu_insert_section:
30715 * @position: the position at which to insert the item
30716 * @label: (allow-none): the section label, or %NULL
30717 * @section: a #GMenuModel with the items of the section
30719 * Convenience function for inserting a section menu item into @menu.
30720 * Combine g_menu_item_new_section() and g_menu_insert_item() for a more
30721 * flexible alternative.
30728 * g_menu_insert_submenu:
30730 * @position: the position at which to insert the item
30731 * @label: (allow-none): the section label, or %NULL
30732 * @submenu: a #GMenuModel with the items of the submenu
30734 * Convenience function for inserting a submenu menu item into @menu.
30735 * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more
30736 * flexible alternative.
30744 * @label: (allow-none): the section label, or %NULL
30745 * @detailed_action: (allow-none): the detailed action string, or %NULL
30747 * Creates a new #GMenuItem.
30749 * If @label is non-%NULL it is used to set the "label" attribute of the
30752 * If @detailed_action is non-%NULL it is used to set the "action" and
30753 * possibly the "target" attribute of the new item. See
30754 * g_menu_item_set_detailed_action() for more information.
30756 * Returns: a new #GMenuItem
30762 * g_menu_item_new_section:
30763 * @label: (allow-none): the section label, or %NULL
30764 * @section: a #GMenuModel with the items of the section
30766 * Creates a new #GMenuItem representing a section.
30768 * This is a convenience API around g_menu_item_new() and
30769 * g_menu_item_set_section().
30771 * The effect of having one menu appear as a section of another is
30772 * exactly as it sounds: the items from @section become a direct part of
30773 * the menu that @menu_item is added to.
30775 * Visual separation is typically displayed between two non-empty
30776 * sections. If @label is non-%NULL then it will be encorporated into
30777 * this visual indication. This allows for labeled subsections of a
30780 * As a simple example, consider a typical "Edit" menu from a simple
30781 * program. It probably contains an "Undo" and "Redo" item, followed by
30782 * a separator, followed by "Cut", "Copy" and "Paste".
30784 * This would be accomplished by creating three #GMenu instances. The
30785 * first would be populated with the "Undo" and "Redo" items, and the
30786 * second with the "Cut", "Copy" and "Paste" items. The first and
30787 * second menus would then be added as submenus of the third. In XML
30788 * format, this would look something like the following:
30790 * <informalexample><programlisting><![CDATA[
30791 * <menu id='edit-menu'>
30793 * <item label='Undo'/>
30794 * <item label='Redo'/>
30797 * <item label='Cut'/>
30798 * <item label='Copy'/>
30799 * <item label='Paste'/>
30802 * ]]></programlisting></informalexample>
30804 * The following example is exactly equivalent. It is more illustrative
30805 * of the exact relationship between the menus and items (keeping in
30806 * mind that the 'link' element defines a new menu that is linked to the
30807 * containing one). The style of the second example is more verbose and
30808 * difficult to read (and therefore not recommended except for the
30809 * purpose of understanding what is really going on).
30811 * <informalexample><programlisting><![CDATA[
30812 * <menu id='edit-menu'>
30814 * <link name='section'>
30815 * <item label='Undo'/>
30816 * <item label='Redo'/>
30820 * <link name='section'>
30821 * <item label='Cut'/>
30822 * <item label='Copy'/>
30823 * <item label='Paste'/>
30827 * ]]></programlisting></informalexample>
30829 * Returns: a new #GMenuItem
30835 * g_menu_item_new_submenu:
30836 * @label: (allow-none): the section label, or %NULL
30837 * @submenu: a #GMenuModel with the items of the submenu
30839 * Creates a new #GMenuItem representing a submenu.
30841 * This is a convenience API around g_menu_item_new() and
30842 * g_menu_item_set_submenu().
30844 * Returns: a new #GMenuItem
30850 * g_menu_item_set_action_and_target:
30851 * @menu_item: a #GMenuItem
30852 * @action: (allow-none): the name of the action for this item
30853 * @format_string: (allow-none): a GVariant format string
30854 * @...: positional parameters, as per @format_string
30856 * Sets or unsets the "action" and "target" attributes of @menu_item.
30858 * If @action is %NULL then both the "action" and "target" attributes
30859 * are unset (and @format_string is ignored along with the positional
30862 * If @action is non-%NULL then the "action" attribute is set.
30863 * @format_string is then inspected. If it is non-%NULL then the proper
30864 * position parameters are collected to create a #GVariant instance to
30865 * use as the target value. If it is %NULL then the positional
30866 * parameters are ignored and the "target" attribute is unset.
30868 * See also g_menu_item_set_action_and_target_value() for an equivalent
30869 * call that directly accepts a #GVariant. See
30870 * g_menu_item_set_detailed_action() for a more convenient version that
30871 * works with string-typed targets.
30873 * See also g_menu_item_set_action_and_target_value() for a
30874 * description of the semantics of the action and target attributes.
30881 * g_menu_item_set_action_and_target_value:
30882 * @menu_item: a #GMenuItem
30883 * @action: (allow-none): the name of the action for this item
30884 * @target_value: (allow-none): a #GVariant to use as the action target
30886 * Sets or unsets the "action" and "target" attributes of @menu_item.
30888 * If @action is %NULL then both the "action" and "target" attributes
30889 * are unset (and @target_value is ignored).
30891 * If @action is non-%NULL then the "action" attribute is set. The
30892 * "target" attribute is then set to the value of @target_value if it is
30893 * non-%NULL or unset otherwise.
30895 * Normal menu items (ie: not submenu, section or other custom item
30896 * types) are expected to have the "action" attribute set to identify
30897 * the action that they are associated with. The state type of the
30898 * action help to determine the disposition of the menu item. See
30899 * #GAction and #GActionGroup for an overview of actions.
30901 * In general, clicking on the menu item will result in activation of
30902 * the named action with the "target" attribute given as the parameter
30903 * to the action invocation. If the "target" attribute is not set then
30904 * the action is invoked with no parameter.
30906 * If the action has no state then the menu item is usually drawn as a
30907 * plain menu item (ie: with no additional decoration).
30909 * If the action has a boolean state then the menu item is usually drawn
30910 * as a toggle menu item (ie: with a checkmark or equivalent
30911 * indication). The item should be marked as 'toggled' or 'checked'
30912 * when the boolean state is %TRUE.
30914 * If the action has a string state then the menu item is usually drawn
30915 * as a radio menu item (ie: with a radio bullet or equivalent
30916 * indication). The item should be marked as 'selected' when the string
30917 * state is equal to the value of the @target property.
30919 * See g_menu_item_set_action_and_target() or
30920 * g_menu_item_set_detailed_action() for two equivalent calls that are
30921 * probably more convenient for most uses.
30928 * g_menu_item_set_attribute:
30929 * @menu_item: a #GMenuItem
30930 * @attribute: the attribute to set
30931 * @format_string: (allow-none): a #GVariant format string, or %NULL
30932 * @...: positional parameters, as per @format_string
30934 * Sets or unsets an attribute on @menu_item.
30936 * The attribute to set or unset is specified by @attribute. This
30937 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
30938 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
30940 * Attribute names are restricted to lowercase characters, numbers
30941 * and '-'. Furthermore, the names must begin with a lowercase character,
30942 * must not end with a '-', and must not contain consecutive dashes.
30944 * If @format_string is non-%NULL then the proper position parameters
30945 * are collected to create a #GVariant instance to use as the attribute
30946 * value. If it is %NULL then the positional parameterrs are ignored
30947 * and the named attribute is unset.
30949 * See also g_menu_item_set_attribute_value() for an equivalent call
30950 * that directly accepts a #GVariant.
30957 * g_menu_item_set_attribute_value:
30958 * @menu_item: a #GMenuItem
30959 * @attribute: the attribute to set
30960 * @value: (allow-none): a #GVariant to use as the value, or %NULL
30962 * Sets or unsets an attribute on @menu_item.
30964 * The attribute to set or unset is specified by @attribute. This
30965 * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL,
30966 * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom
30968 * Attribute names are restricted to lowercase characters, numbers
30969 * and '-'. Furthermore, the names must begin with a lowercase character,
30970 * must not end with a '-', and must not contain consecutive dashes.
30972 * must consist only of lowercase
30973 * ASCII characters, digits and '-'.
30975 * If @value is non-%NULL then it is used as the new value for the
30976 * attribute. If @value is %NULL then the attribute is unset. If
30977 * the @value #GVariant is floating, it is consumed.
30979 * See also g_menu_item_set_attribute() for a more convenient way to do
30987 * g_menu_item_set_detailed_action:
30988 * @menu_item: a #GMenuItem
30989 * @detailed_action: the "detailed" action string
30991 * Sets the "action" and possibly the "target" attribute of @menu_item.
30993 * If @detailed_action contains a double colon ("::") then it is used as
30994 * a separator between an action name and a target string. In this
30995 * case, this call is equivalent to calling
30996 * g_menu_item_set_action_and_target() with the part before the "::" and
30997 * with a string-type #GVariant containing the part following the "::".
30999 * If @detailed_action doesn't contain "::" then the action is set to
31000 * the given string (verbatim) and the target value is unset.
31002 * See g_menu_item_set_action_and_target() or
31003 * g_menu_item_set_action_and_target_value() for more flexible (but
31004 * slightly less convenient) alternatives.
31006 * See also g_menu_item_set_action_and_target_value() for a description of
31007 * the semantics of the action and target attributes.
31014 * g_menu_item_set_label:
31015 * @menu_item: a #GMenuItem
31016 * @label: (allow-none): the label to set, or %NULL to unset
31018 * Sets or unsets the "label" attribute of @menu_item.
31020 * If @label is non-%NULL it is used as the label for the menu item. If
31021 * it is %NULL then the label attribute is unset.
31028 * g_menu_item_set_link:
31029 * @menu_item: a #GMenuItem
31030 * @link: type of link to establish or unset
31031 * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
31033 * Creates a link from @menu_item to @model if non-%NULL, or unsets it.
31035 * Links are used to establish a relationship between a particular menu
31036 * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to
31037 * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION
31038 * is used to create a section. Other types of link can be used, but there
31039 * is no guarantee that clients will be able to make sense of them.
31040 * Link types are restricted to lowercase characters, numbers
31041 * and '-'. Furthermore, the names must begin with a lowercase character,
31042 * must not end with a '-', and must not contain consecutive dashes.
31049 * g_menu_item_set_section:
31050 * @menu_item: a #GMenuItem
31051 * @section: (allow-none): a #GMenuModel, or %NULL
31053 * Sets or unsets the "section" link of @menu_item to @section.
31055 * The effect of having one menu appear as a section of another is
31056 * exactly as it sounds: the items from @section become a direct part of
31057 * the menu that @menu_item is added to. See g_menu_item_new_section()
31058 * for more information about what it means for a menu item to be a
31066 * g_menu_item_set_submenu:
31067 * @menu_item: a #GMenuItem
31068 * @submenu: (allow-none): a #GMenuModel, or %NULL
31070 * Sets or unsets the "submenu" link of @menu_item to @submenu.
31072 * If @submenu is non-%NULL, it is linked to. If it is %NULL then the
31075 * The effect of having one menu appear as a submenu of another is
31076 * exactly as it sounds.
31083 * g_menu_link_iter_get_name:
31084 * @iter: a #GMenuLinkIter
31086 * Gets the name of the link at the current iterator position.
31088 * The iterator is not advanced.
31090 * Returns: the type of the link
31096 * g_menu_link_iter_get_next:
31097 * @iter: a #GMenuLinkIter
31098 * @out_link: (out) (allow-none) (transfer none): the name of the link
31099 * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
31101 * This function combines g_menu_link_iter_next() with
31102 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
31104 * First the iterator is advanced to the next (possibly first) link.
31105 * If that fails, then %FALSE is returned and there are no other effects.
31107 * If successful, @out_link and @value are set to the name and #GMenuModel
31108 * of the link that has just been advanced to. At this point,
31109 * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the
31110 * same values again.
31112 * The value returned in @out_link remains valid for as long as the iterator
31113 * remains at the current position. The value returned in @value must
31114 * be unreffed using g_object_unref() when it is no longer in use.
31116 * Returns: %TRUE on success, or %FALSE if there is no additional link
31122 * g_menu_link_iter_get_value:
31123 * @iter: a #GMenuLinkIter
31125 * Gets the linked #GMenuModel at the current iterator position.
31127 * The iterator is not advanced.
31129 * Returns: (transfer full): the #GMenuModel that is linked to
31135 * g_menu_link_iter_next:
31136 * @iter: a #GMenuLinkIter
31138 * Attempts to advance the iterator to the next (possibly first)
31141 * %TRUE is returned on success, or %FALSE if there are no more links.
31143 * You must call this function when you first acquire the iterator to
31144 * advance it to the first link (and determine if the first link exists
31147 * Returns: %TRUE on success, or %FALSE when there are no more links
31153 * g_menu_model_get_item_attribute:
31154 * @model: a #GMenuModel
31155 * @item_index: the index of the item
31156 * @attribute: the attribute to query
31157 * @format_string: a #GVariant format string
31158 * @...: positional parameters, as per @format_string
31160 * Queries item at position @item_index in @model for the attribute
31161 * specified by @attribute.
31163 * If the attribute exists and matches the #GVariantType corresponding
31164 * to @format_string then @format_string is used to deconstruct the
31165 * value into the positional parameters and %TRUE is returned.
31167 * If the attribute does not exist, or it does exist but has the wrong
31168 * type, then the positional parameters are ignored and %FALSE is
31173 * Returns: %TRUE if the named attribute was found with the expected
31179 * g_menu_model_get_item_attribute_value:
31180 * @model: a #GMenuModel
31181 * @item_index: the index of the item
31182 * @attribute: the attribute to query
31183 * @expected_type: (allow-none): the expected type of the attribute, or %NULL
31185 * Queries the item at position @item_index in @model for the attribute
31186 * specified by @attribute.
31188 * If @expected_type is non-%NULL then it specifies the expected type of
31189 * the attribute. If it is %NULL then any type will be accepted.
31191 * If the attribute exists and matches @expected_type (or if the
31192 * expected type is unspecified) then the value is returned.
31194 * If the attribute does not exist, or does not match the expected type
31195 * then %NULL is returned.
31197 * Returns: (transfer full): the value of the attribute
31203 * g_menu_model_get_item_link:
31204 * @model: a #GMenuModel
31205 * @item_index: the index of the item
31206 * @link: the link to query
31208 * Queries the item at position @item_index in @model for the link
31209 * specified by @link.
31211 * If the link exists, the linked #GMenuModel is returned. If the link
31212 * does not exist, %NULL is returned.
31214 * Returns: (transfer full): the linked #GMenuModel, or %NULL
31220 * g_menu_model_get_n_items:
31221 * @model: a #GMenuModel
31223 * Query the number of items in @model.
31225 * Returns: the number of items
31231 * g_menu_model_is_mutable:
31232 * @model: a #GMenuModel
31234 * Queries if @model is mutable.
31236 * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
31237 * signal. Consumers of the model may make optimisations accordingly.
31241 * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
31247 * g_menu_model_items_changed:
31248 * @model: a #GMenuModel
31249 * @position: the position of the change
31250 * @removed: the number of items removed
31251 * @added: the number of items added
31253 * Requests emission of the #GMenuModel::items-changed signal on @model.
31255 * This function should never be called except by #GMenuModel
31256 * subclasses. Any other calls to this function will very likely lead
31257 * to a violation of the interface of the model.
31259 * The implementation should update its internal representation of the
31260 * menu before emitting the signal. The implementation should further
31261 * expect to receive queries about the new state of the menu (and
31262 * particularly added menu items) while signal handlers are running.
31264 * The implementation must dispatch this call directly from a mainloop
31265 * entry and not in response to calls -- particularly those from the
31266 * #GMenuModel API. Said another way: the menu must not change while
31267 * user code is running without returning to the mainloop.
31274 * g_menu_model_iterate_item_attributes:
31275 * @model: a #GMenuModel
31276 * @item_index: the index of the item
31278 * Creates a #GMenuAttributeIter to iterate over the attributes of
31279 * the item at position @item_index in @model.
31281 * You must free the iterator with g_object_unref() when you are done.
31283 * Returns: (transfer full): a new #GMenuAttributeIter
31289 * g_menu_model_iterate_item_links:
31290 * @model: a #GMenuModel
31291 * @item_index: the index of the item
31293 * Creates a #GMenuLinkIter to iterate over the links of the item at
31294 * position @item_index in @model.
31296 * You must free the iterator with g_object_unref() when you are done.
31298 * Returns: (transfer full): a new #GMenuLinkIter
31306 * Creates a new #GMenu.
31308 * The new menu has no items.
31310 * Returns: a new #GMenu
31318 * @label: (allow-none): the section label, or %NULL
31319 * @detailed_action: (allow-none): the detailed action string, or %NULL
31321 * Convenience function for prepending a normal menu item to the start
31322 * of @menu. Combine g_menu_new() and g_menu_insert_item() for a more
31323 * flexible alternative.
31330 * g_menu_prepend_item:
31332 * @item: a #GMenuItem to prepend
31334 * Prepends @item to the start of @menu.
31336 * See g_menu_insert_item() for more information.
31343 * g_menu_prepend_section:
31345 * @label: (allow-none): the section label, or %NULL
31346 * @section: a #GMenuModel with the items of the section
31348 * Convenience function for prepending a section menu item to the start
31349 * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for
31350 * a more flexible alternative.
31357 * g_menu_prepend_submenu:
31359 * @label: (allow-none): the section label, or %NULL
31360 * @submenu: a #GMenuModel with the items of the submenu
31362 * Convenience function for prepending a submenu menu item to the start
31363 * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for
31364 * a more flexible alternative.
31373 * @position: the position of the item to remove
31375 * Removes an item from the menu.
31377 * @position gives the index of the item to remove.
31379 * It is an error if position is not in range the range from 0 to one
31380 * less than the number of items in the menu.
31382 * It is not possible to remove items by identity since items are added
31383 * to the menu simply by copying their links and attributes (ie:
31384 * identity of the item itself is not preserved).
31391 * g_mount_can_eject:
31392 * @mount: a #GMount.
31394 * Checks if @mount can be eject.
31396 * Returns: %TRUE if the @mount can be ejected.
31401 * g_mount_can_unmount:
31402 * @mount: a #GMount.
31404 * Checks if @mount can be mounted.
31406 * Returns: %TRUE if the @mount can be unmounted.
31412 * @mount: a #GMount.
31413 * @flags: flags affecting the unmount if required for eject
31414 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31415 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
31416 * @user_data: user data passed to @callback.
31418 * Ejects a mount. This is an asynchronous operation, and is
31419 * finished by calling g_mount_eject_finish() with the @mount
31420 * and #GAsyncResult data returned in the @callback.
31422 * Deprecated: 2.22: Use g_mount_eject_with_operation() instead.
31427 * g_mount_eject_finish:
31428 * @mount: a #GMount.
31429 * @result: a #GAsyncResult.
31430 * @error: a #GError location to store the error occurring, or %NULL to ignore.
31432 * Finishes ejecting a mount. If any errors occurred during the operation,
31433 * @error will be set to contain the errors and %FALSE will be returned.
31435 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
31436 * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead.
31441 * g_mount_eject_with_operation:
31442 * @mount: a #GMount.
31443 * @flags: flags affecting the unmount if required for eject
31444 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
31445 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31446 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
31447 * @user_data: user data passed to @callback.
31449 * Ejects a mount. This is an asynchronous operation, and is
31450 * finished by calling g_mount_eject_with_operation_finish() with the @mount
31451 * and #GAsyncResult data returned in the @callback.
31458 * g_mount_eject_with_operation_finish:
31459 * @mount: a #GMount.
31460 * @result: a #GAsyncResult.
31461 * @error: a #GError location to store the error occurring, or %NULL to ignore.
31463 * Finishes ejecting a mount. If any errors occurred during the operation,
31464 * @error will be set to contain the errors and %FALSE will be returned.
31466 * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
31472 * g_mount_get_default_location:
31473 * @mount: a #GMount.
31475 * Gets the default location of @mount. The default location of the given
31476 * @mount is a path that reflects the main entry point for the user (e.g.
31477 * the home directory, or the root of the volume).
31479 * The returned object should be unreffed with
31480 * g_object_unref() when no longer needed.
31482 * Returns: (transfer full): a #GFile.
31487 * g_mount_get_drive:
31488 * @mount: a #GMount.
31490 * Gets the drive for the @mount.
31492 * This is a convenience method for getting the #GVolume and then
31493 * using that object to get the #GDrive.
31495 * The returned object should be unreffed with
31496 * g_object_unref() when no longer needed.
31498 * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive.
31503 * g_mount_get_icon:
31504 * @mount: a #GMount.
31506 * Gets the icon for @mount.
31508 * The returned object should be unreffed with
31509 * g_object_unref() when no longer needed.
31511 * Returns: (transfer full): a #GIcon.
31516 * g_mount_get_name:
31517 * @mount: a #GMount.
31519 * Gets the name of @mount.
31521 * The returned string should be freed with g_free()
31522 * when no longer needed.
31524 * Returns: the name for the given @mount.
31529 * g_mount_get_root:
31530 * @mount: a #GMount.
31532 * Gets the root directory on @mount.
31534 * The returned object should be unreffed with
31535 * g_object_unref() when no longer needed.
31537 * Returns: (transfer full): a #GFile.
31542 * g_mount_get_sort_key:
31543 * @mount: A #GMount.
31545 * Gets the sort key for @mount, if any.
31547 * Returns: Sorting key for @mount or %NULL if no such key is available.
31553 * g_mount_get_uuid:
31554 * @mount: a #GMount.
31556 * Gets the UUID for the @mount. The reference is typically based on
31557 * the file system UUID for the mount in question and should be
31558 * considered an opaque string. Returns %NULL if there is no UUID
31561 * The returned string should be freed with g_free()
31562 * when no longer needed.
31564 * Returns: the UUID for @mount or %NULL if no UUID can be computed.
31569 * g_mount_get_volume:
31570 * @mount: a #GMount.
31572 * Gets the volume for the @mount.
31574 * The returned object should be unreffed with
31575 * g_object_unref() when no longer needed.
31577 * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume.
31582 * g_mount_guess_content_type:
31583 * @mount: a #GMount
31584 * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available
31585 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
31586 * @callback: a #GAsyncReadyCallback
31587 * @user_data: user data passed to @callback
31589 * Tries to guess the type of content stored on @mount. Returns one or
31590 * more textual identifiers of well-known content types (typically
31591 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
31592 * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
31593 * specification for more on x-content types.
31595 * This is an asynchronous operation (see
31596 * g_mount_guess_content_type_sync() for the synchronous version), and
31597 * is finished by calling g_mount_guess_content_type_finish() with the
31598 * @mount and #GAsyncResult data returned in the @callback.
31605 * g_mount_guess_content_type_finish:
31606 * @mount: a #GMount
31607 * @result: a #GAsyncResult
31608 * @error: a #GError location to store the error occurring, or %NULL to ignore
31610 * Finishes guessing content types of @mount. If any errors occurred
31611 * during the operation, @error will be set to contain the errors and
31612 * %FALSE will be returned. In particular, you may get an
31613 * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
31616 * Caller should free this array with g_strfreev() when done with it.
31618 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
31624 * g_mount_guess_content_type_sync:
31625 * @mount: a #GMount
31626 * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available
31627 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
31628 * @error: a #GError location to store the error occurring, or %NULL to ignore
31630 * Tries to guess the type of content stored on @mount. Returns one or
31631 * more textual identifiers of well-known content types (typically
31632 * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
31633 * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
31634 * specification for more on x-content types.
31636 * This is an synchronous operation and as such may block doing IO;
31637 * see g_mount_guess_content_type() for the asynchronous version.
31639 * Caller should free this array with g_strfreev() when done with it.
31641 * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
31647 * g_mount_is_shadowed:
31648 * @mount: A #GMount.
31650 * Determines if @mount is shadowed. Applications or libraries should
31651 * avoid displaying @mount in the user interface if it is shadowed.
31653 * A mount is said to be shadowed if there exists one or more user
31654 * visible objects (currently #GMount objects) with a root that is
31655 * inside the root of @mount.
31657 * One application of shadow mounts is when exposing a single file
31658 * system that is used to address several logical volumes. In this
31659 * situation, a #GVolumeMonitor implementation would create two
31660 * #GVolume objects (for example, one for the camera functionality of
31661 * the device and one for a SD card reader on the device) with
31662 * activation URIs <literal>gphoto2://[usb:001,002]/store1/</literal>
31663 * and <literal>gphoto2://[usb:001,002]/store2/</literal>. When the
31664 * underlying mount (with root
31665 * <literal>gphoto2://[usb:001,002]/</literal>) is mounted, said
31666 * #GVolumeMonitor implementation would create two #GMount objects
31667 * (each with their root matching the corresponding volume activation
31668 * root) that would shadow the original mount.
31670 * The proxy monitor in GVfs 2.26 and later, automatically creates and
31671 * manage shadow mounts (and shadows the underlying mount) if the
31672 * activation root on a #GVolume is set.
31674 * Returns: %TRUE if @mount is shadowed.
31680 * g_mount_operation_get_anonymous:
31681 * @op: a #GMountOperation.
31683 * Check to see whether the mount operation is being used
31684 * for an anonymous user.
31686 * Returns: %TRUE if mount operation is anonymous.
31691 * g_mount_operation_get_choice:
31692 * @op: a #GMountOperation.
31694 * Gets a choice from the mount operation.
31696 * the choice's list, or %0.
31698 * Returns: an integer containing an index of the user's choice from
31703 * g_mount_operation_get_domain:
31704 * @op: a #GMountOperation.
31706 * Gets the domain of the mount operation.
31708 * Returns: a string set to the domain.
31713 * g_mount_operation_get_password:
31714 * @op: a #GMountOperation.
31716 * Gets a password from the mount operation.
31718 * Returns: a string containing the password within @op.
31723 * g_mount_operation_get_password_save:
31724 * @op: a #GMountOperation.
31726 * Gets the state of saving passwords for the mount operation.
31728 * Returns: a #GPasswordSave flag.
31733 * g_mount_operation_get_username:
31734 * @op: a #GMountOperation.
31736 * Get the user name from the mount operation.
31738 * Returns: a string containing the user name.
31743 * g_mount_operation_new:
31745 * Creates a new mount operation.
31747 * Returns: a #GMountOperation.
31752 * g_mount_operation_reply:
31753 * @op: a #GMountOperation
31754 * @result: a #GMountOperationResult
31756 * Emits the #GMountOperation::reply signal.
31761 * g_mount_operation_set_anonymous:
31762 * @op: a #GMountOperation.
31763 * @anonymous: boolean value.
31765 * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
31770 * g_mount_operation_set_choice:
31771 * @op: a #GMountOperation.
31772 * @choice: an integer.
31774 * Sets a default choice for the mount operation.
31779 * g_mount_operation_set_domain:
31780 * @op: a #GMountOperation.
31781 * @domain: the domain to set.
31783 * Sets the mount operation's domain.
31788 * g_mount_operation_set_password:
31789 * @op: a #GMountOperation.
31790 * @password: password to set.
31792 * Sets the mount operation's password to @password.
31797 * g_mount_operation_set_password_save:
31798 * @op: a #GMountOperation.
31799 * @save: a set of #GPasswordSave flags.
31801 * Sets the state of saving passwords for the mount operation.
31806 * g_mount_operation_set_username:
31807 * @op: a #GMountOperation.
31808 * @username: input username.
31810 * Sets the user name within @op to @username.
31816 * @mount: a #GMount.
31817 * @flags: flags affecting the operation
31818 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
31819 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31820 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
31821 * @user_data: user data passed to @callback.
31823 * Remounts a mount. This is an asynchronous operation, and is
31824 * finished by calling g_mount_remount_finish() with the @mount
31825 * and #GAsyncResults data returned in the @callback.
31827 * Remounting is useful when some setting affecting the operation
31828 * of the volume has been changed, as these may need a remount to
31829 * take affect. While this is semantically equivalent with unmounting
31830 * and then remounting not all backends might need to actually be
31836 * g_mount_remount_finish:
31837 * @mount: a #GMount.
31838 * @result: a #GAsyncResult.
31839 * @error: a #GError location to store the error occurring, or %NULL to ignore.
31841 * Finishes remounting a mount. If any errors occurred during the operation,
31842 * @error will be set to contain the errors and %FALSE will be returned.
31844 * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
31850 * @mount: A #GMount.
31852 * Increments the shadow count on @mount. Usually used by
31853 * #GVolumeMonitor implementations when creating a shadow mount for
31854 * @mount, see g_mount_is_shadowed() for more information. The caller
31855 * will need to emit the #GMount::changed signal on @mount manually.
31863 * @mount: a #GMount.
31864 * @flags: flags affecting the operation
31865 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31866 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
31867 * @user_data: user data passed to @callback.
31869 * Unmounts a mount. This is an asynchronous operation, and is
31870 * finished by calling g_mount_unmount_finish() with the @mount
31871 * and #GAsyncResult data returned in the @callback.
31873 * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead.
31878 * g_mount_unmount_finish:
31879 * @mount: a #GMount.
31880 * @result: a #GAsyncResult.
31881 * @error: a #GError location to store the error occurring, or %NULL to ignore.
31883 * Finishes unmounting a mount. If any errors occurred during the operation,
31884 * @error will be set to contain the errors and %FALSE will be returned.
31886 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
31887 * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead.
31892 * g_mount_unmount_with_operation:
31893 * @mount: a #GMount.
31894 * @flags: flags affecting the operation
31895 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
31896 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
31897 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
31898 * @user_data: user data passed to @callback.
31900 * Unmounts a mount. This is an asynchronous operation, and is
31901 * finished by calling g_mount_unmount_with_operation_finish() with the @mount
31902 * and #GAsyncResult data returned in the @callback.
31909 * g_mount_unmount_with_operation_finish:
31910 * @mount: a #GMount.
31911 * @result: a #GAsyncResult.
31912 * @error: a #GError location to store the error occurring, or %NULL to ignore.
31914 * Finishes unmounting a mount. If any errors occurred during the operation,
31915 * @error will be set to contain the errors and %FALSE will be returned.
31917 * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
31923 * g_mount_unshadow:
31924 * @mount: A #GMount.
31926 * Decrements the shadow count on @mount. Usually used by
31927 * #GVolumeMonitor implementations when destroying a shadow mount for
31928 * @mount, see g_mount_is_shadowed() for more information. The caller
31929 * will need to emit the #GMount::changed signal on @mount manually.
31936 * g_network_address_get_hostname:
31937 * @addr: a #GNetworkAddress
31939 * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded,
31940 * depending on what @addr was created with.
31942 * Returns: @addr's hostname
31948 * g_network_address_get_port:
31949 * @addr: a #GNetworkAddress
31951 * Gets @addr's port number
31953 * Returns: @addr's port (which may be 0)
31959 * g_network_address_get_scheme:
31960 * @addr: a #GNetworkAddress
31962 * Gets @addr's scheme
31964 * Returns: @addr's scheme (%NULL if not built from URI)
31970 * g_network_address_new:
31971 * @hostname: the hostname
31974 * Creates a new #GSocketConnectable for connecting to the given
31975 * @hostname and @port.
31977 * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
31983 * g_network_address_parse:
31984 * @host_and_port: the hostname and optionally a port
31985 * @default_port: the default port if not in @host_and_port
31986 * @error: a pointer to a #GError, or %NULL
31988 * Creates a new #GSocketConnectable for connecting to the given
31989 * @hostname and @port. May fail and return %NULL in case
31990 * parsing @host_and_port fails.
31992 * @host_and_port may be in any of a number of recognised formats; an IPv6
31993 * address, an IPv4 address, or a domain name (in which case a DNS
31994 * lookup is performed). Quoting with [] is supported for all address
31995 * types. A port override may be specified in the usual way with a
31998 * If no port is specified in @host_and_port then @default_port will be
31999 * used as the port number to connect to.
32001 * In general, @host_and_port is expected to be provided by the user
32002 * (allowing them to give the hostname, and a port overide if necessary)
32003 * and @default_port is expected to be provided by the application.
32005 * (The port component of @host_and_port can also be specified as a
32006 * service name rather than as a numeric port, but this functionality
32007 * is deprecated, because it depends on the contents of /etc/services,
32008 * which is generally quite sparse on platforms other than Linux.)
32010 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
32016 * g_network_address_parse_uri:
32017 * @uri: the hostname and optionally a port
32018 * @default_port: The default port if none is found in the URI
32019 * @error: a pointer to a #GError, or %NULL
32021 * Creates a new #GSocketConnectable for connecting to the given
32022 * @uri. May fail and return %NULL in case parsing @uri fails.
32024 * Using this rather than g_network_address_new() or
32025 * g_network_address_parse() allows #GSocketClient to determine
32026 * when to use application-specific proxy protocols.
32028 * Returns: (transfer full): the new #GNetworkAddress, or %NULL on error
32034 * g_network_monitor_base_add_network:
32035 * @monitor: the #GNetworkMonitorBase
32036 * @network: a #GInetAddressMask
32038 * Adds @network to @monitor's list of available networks.
32045 * g_network_monitor_base_remove_network:
32046 * @monitor: the #GNetworkMonitorBase
32047 * @network: a #GInetAddressMask
32049 * Removes @network from @monitor's list of available networks.
32056 * g_network_monitor_base_set_networks:
32057 * @monitor: the #GNetworkMonitorBase
32058 * @networks: (array length=length): an array of #GInetAddressMask
32059 * @length: length of @networks
32061 * Drops @monitor's current list of available networks and replaces
32062 * it with @networks.
32067 * g_network_monitor_can_reach:
32068 * @monitor: a #GNetworkMonitor
32069 * @connectable: a #GSocketConnectable
32070 * @cancellable: a #GCancellable, or %NULL
32071 * @error: return location for a #GError, or %NULL
32073 * Attempts to determine whether or not the host pointed to by
32074 * @connectable can be reached, without actually trying to connect to
32077 * This may return %TRUE even when #GNetworkMonitor:network-available
32078 * is %FALSE, if, for example, @monitor can determine that
32079 * @connectable refers to a host on a local network.
32081 * If @monitor believes that an attempt to connect to @connectable
32082 * will succeed, it will return %TRUE. Otherwise, it will return
32083 * %FALSE and set @error to an appropriate error (such as
32084 * %G_IO_ERROR_HOST_UNREACHABLE).
32086 * Note that although this does not attempt to connect to
32087 * @connectable, it may still block for a brief period of time (eg,
32088 * trying to do multicast DNS on the local network), so if you do not
32089 * want to block, you should use g_network_monitor_can_reach_async().
32091 * Returns: %TRUE if @connectable is reachable, %FALSE if not.
32097 * g_network_monitor_can_reach_async:
32098 * @monitor: a #GNetworkMonitor
32099 * @connectable: a #GSocketConnectable
32100 * @cancellable: a #GCancellable, or %NULL
32101 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
32102 * @user_data: (closure): the data to pass to callback function
32104 * Asynchronously attempts to determine whether or not the host
32105 * pointed to by @connectable can be reached, without actually
32106 * trying to connect to it.
32108 * For more details, see g_network_monitor_can_reach().
32110 * When the operation is finished, @callback will be called.
32111 * You can then call g_network_monitor_can_reach_finish()
32112 * to get the result of the operation.
32117 * g_network_monitor_can_reach_finish:
32118 * @monitor: a #GNetworkMonitor
32119 * @result: a #GAsyncResult
32120 * @error: return location for errors, or %NULL
32122 * Finishes an async network connectivity test.
32123 * See g_network_monitor_can_reach_async().
32125 * Returns: %TRUE if network is reachable, %FALSE if not.
32130 * g_network_monitor_get_default:
32132 * Gets the default #GNetworkMonitor for the system.
32134 * Returns: (transfer none): a #GNetworkMonitor
32140 * g_network_monitor_get_network_available:
32141 * @monitor: the #GNetworkMonitor
32143 * Checks if the network is available. "Available" here means that the
32144 * system has a default route available for at least one of IPv4 or
32145 * IPv6. It does not necessarily imply that the public Internet is
32146 * reachable. See #GNetworkMonitor:network-available for more details.
32148 * Returns: whether the network is available
32154 * g_network_service_get_domain:
32155 * @srv: a #GNetworkService
32157 * Gets the domain that @srv serves. This might be either UTF-8 or
32158 * ASCII-encoded, depending on what @srv was created with.
32160 * Returns: @srv's domain name
32166 * g_network_service_get_protocol:
32167 * @srv: a #GNetworkService
32169 * Gets @srv's protocol name (eg, "tcp").
32171 * Returns: @srv's protocol name
32177 * g_network_service_get_scheme:
32178 * @srv: a #GNetworkService
32180 * Get's the URI scheme used to resolve proxies. By default, the service name
32181 * is used as scheme.
32183 * Returns: @srv's scheme name
32189 * g_network_service_get_service:
32190 * @srv: a #GNetworkService
32192 * Gets @srv's service name (eg, "ldap").
32194 * Returns: @srv's service name
32200 * g_network_service_new:
32201 * @service: the service type to look up (eg, "ldap")
32202 * @protocol: the networking protocol to use for @service (eg, "tcp")
32203 * @domain: the DNS domain to look up the service in
32205 * Creates a new #GNetworkService representing the given @service,
32206 * @protocol, and @domain. This will initially be unresolved; use the
32207 * #GSocketConnectable interface to resolve it.
32209 * Returns: (transfer full) (type GNetworkService): a new #GNetworkService
32215 * g_network_service_set_scheme:
32216 * @srv: a #GNetworkService
32217 * @scheme: a URI scheme
32219 * Set's the URI scheme used to resolve proxies. By default, the service name
32220 * is used as scheme.
32228 * @struct_type: the type of the elements to allocate
32229 * @n_structs: the number of elements to allocate
32231 * Allocates @n_structs elements of type @struct_type.
32232 * The returned pointer is cast to a pointer to the given type.
32233 * If @n_structs is 0 it returns %NULL.
32234 * Care is taken to avoid overflow when calculating the size of the allocated block.
32236 * Since the returned pointer is already casted to the right type,
32237 * it is normally unnecessary to cast it explicitly, and doing
32238 * so might hide memory allocation errors.
32240 * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
32246 * @struct_type: the type of the elements to allocate.
32247 * @n_structs: the number of elements to allocate.
32249 * Allocates @n_structs elements of type @struct_type, initialized to 0's.
32250 * The returned pointer is cast to a pointer to the given type.
32251 * If @n_structs is 0 it returns %NULL.
32252 * Care is taken to avoid overflow when calculating the size of the allocated block.
32254 * Since the returned pointer is already casted to the right type,
32255 * it is normally unnecessary to cast it explicitly, and doing
32256 * so might hide memory allocation errors.
32258 * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
32264 * @struct_type: Type of memory chunks to be allocated
32265 * @n_structs: Number of chunks to be allocated
32267 * Wraps g_alloca() in a more typesafe manner.
32269 * Returns: Pointer to stack space for @n_structs chunks of type @struct_type
32275 * @parent: the #GNode to place the new #GNode under
32276 * @node: the #GNode to insert
32278 * Inserts a #GNode as the last child of the given parent.
32280 * Returns: the inserted #GNode
32285 * g_node_append_data:
32286 * @parent: the #GNode to place the new #GNode under
32287 * @data: the data for the new #GNode
32289 * Inserts a new #GNode as the last child of the given parent.
32291 * Returns: the new #GNode
32296 * g_node_first_child:
32299 * Gets the first child of a #GNode.
32301 * or has no children
32303 * Returns: the first child of @node, or %NULL if @node is %NULL
32308 * g_node_insert_data:
32309 * @parent: the #GNode to place the new #GNode under
32310 * @position: the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent
32311 * @data: the data for the new #GNode
32313 * Inserts a new #GNode at the given position.
32315 * Returns: the new #GNode
32320 * g_node_insert_data_after:
32321 * @parent: the #GNode to place the new #GNode under
32322 * @sibling: the sibling #GNode to place the new #GNode after
32323 * @data: the data for the new #GNode
32325 * Inserts a new #GNode after the given sibling.
32327 * Returns: the new #GNode
32332 * g_node_insert_data_before:
32333 * @parent: the #GNode to place the new #GNode under
32334 * @sibling: the sibling #GNode to place the new #GNode before
32335 * @data: the data for the new #GNode
32337 * Inserts a new #GNode before the given sibling.
32339 * Returns: the new #GNode
32344 * g_node_next_sibling:
32347 * Gets the next sibling of a #GNode.
32351 * Returns: the next sibling of @node, or %NULL if @node is the last node
32356 * g_node_prepend_data:
32357 * @parent: the #GNode to place the new #GNode under
32358 * @data: the data for the new #GNode
32360 * Inserts a new #GNode as the first child of the given parent.
32362 * Returns: the new #GNode
32367 * g_node_prev_sibling:
32370 * Gets the previous sibling of a #GNode.
32374 * Returns: the previous sibling of @node, or %NULL if @node is the first
32379 * g_null_settings_backend_new:
32381 * Creates a readonly #GSettingsBackend.
32383 * This backend does not allow changes to settings, so all settings
32384 * will always have their default values.
32386 * Returns: (transfer full): a newly created #GSettingsBackend
32392 * g_output_stream_clear_pending:
32393 * @stream: output stream
32395 * Clears the pending flag on @stream.
32400 * g_output_stream_close:
32401 * @stream: A #GOutputStream.
32402 * @cancellable: (allow-none): optional cancellable object
32403 * @error: location to store the error occurring, or %NULL to ignore
32405 * Closes the stream, releasing resources related to it.
32407 * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED.
32408 * Closing a stream multiple times will not return an error.
32410 * Closing a stream will automatically flush any outstanding buffers in the
32413 * Streams will be automatically closed when the last reference
32414 * is dropped, but you might want to call this function to make sure
32415 * resources are released as early as possible.
32417 * Some streams might keep the backing store of the stream (e.g. a file descriptor)
32418 * open after the stream is closed. See the documentation for the individual
32419 * stream for details.
32421 * On failure the first error that happened will be reported, but the close
32422 * operation will finish as much as possible. A stream that failed to
32423 * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it
32424 * is important to check and report the error to the user, otherwise
32425 * there might be a loss of data as all data might not be written.
32427 * If @cancellable is not NULL, then the operation can be cancelled by
32428 * triggering the cancellable object from another thread. If the operation
32429 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
32430 * Cancelling a close will still leave the stream closed, but there some streams
32431 * can use a faster close that doesn't block to e.g. check errors. On
32432 * cancellation (as with any error) there is no guarantee that all written
32433 * data will reach the target.
32435 * Returns: %TRUE on success, %FALSE on failure
32440 * g_output_stream_close_async:
32441 * @stream: A #GOutputStream.
32442 * @io_priority: the io priority of the request.
32443 * @cancellable: (allow-none): optional cancellable object
32444 * @callback: (scope async): callback to call when the request is satisfied
32445 * @user_data: (closure): the data to pass to callback function
32447 * Requests an asynchronous close of the stream, releasing resources
32448 * related to it. When the operation is finished @callback will be
32449 * called. You can then call g_output_stream_close_finish() to get
32450 * the result of the operation.
32452 * For behaviour details see g_output_stream_close().
32454 * The asyncronous methods have a default fallback that uses threads
32455 * to implement asynchronicity, so they are optional for inheriting
32456 * classes. However, if you override one you must override all.
32461 * g_output_stream_close_finish:
32462 * @stream: a #GOutputStream.
32463 * @result: a #GAsyncResult.
32464 * @error: a #GError location to store the error occurring, or %NULL to ignore.
32466 * Closes an output stream.
32468 * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
32473 * g_output_stream_flush:
32474 * @stream: a #GOutputStream.
32475 * @cancellable: (allow-none): optional cancellable object
32476 * @error: location to store the error occurring, or %NULL to ignore
32478 * Forces a write of all user-space buffered data for the given
32479 * @stream. Will block during the operation. Closing the stream will
32480 * implicitly cause a flush.
32482 * This function is optional for inherited classes.
32484 * If @cancellable is not %NULL, then the operation can be cancelled by
32485 * triggering the cancellable object from another thread. If the operation
32486 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
32488 * Returns: %TRUE on success, %FALSE on error
32493 * g_output_stream_flush_async:
32494 * @stream: a #GOutputStream.
32495 * @io_priority: the io priority of the request.
32496 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32497 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
32498 * @user_data: (closure): the data to pass to callback function
32500 * Forces an asynchronous write of all user-space buffered data for
32501 * the given @stream.
32502 * For behaviour details see g_output_stream_flush().
32504 * When the operation is finished @callback will be
32505 * called. You can then call g_output_stream_flush_finish() to get the
32506 * result of the operation.
32511 * g_output_stream_flush_finish:
32512 * @stream: a #GOutputStream.
32513 * @result: a GAsyncResult.
32514 * @error: a #GError location to store the error occurring, or %NULL to ignore.
32516 * Finishes flushing an output stream.
32518 * Returns: %TRUE if flush operation succeeded, %FALSE otherwise.
32523 * g_output_stream_has_pending:
32524 * @stream: a #GOutputStream.
32526 * Checks if an ouput stream has pending actions.
32528 * Returns: %TRUE if @stream has pending actions.
32533 * g_output_stream_is_closed:
32534 * @stream: a #GOutputStream.
32536 * Checks if an output stream has already been closed.
32538 * Returns: %TRUE if @stream is closed. %FALSE otherwise.
32543 * g_output_stream_is_closing:
32544 * @stream: a #GOutputStream.
32546 * Checks if an output stream is being closed. This can be
32547 * used inside e.g. a flush implementation to see if the
32548 * flush (or other i/o operation) is called from within
32549 * the closing operation.
32551 * Returns: %TRUE if @stream is being closed. %FALSE otherwise.
32557 * g_output_stream_set_pending:
32558 * @stream: a #GOutputStream.
32559 * @error: a #GError location to store the error occurring, or %NULL to ignore.
32561 * Sets @stream to have actions pending. If the pending flag is
32562 * already set or @stream is closed, it will return %FALSE and set
32565 * Returns: %TRUE if pending was previously unset and is now set.
32570 * g_output_stream_splice:
32571 * @stream: a #GOutputStream.
32572 * @source: a #GInputStream.
32573 * @flags: a set of #GOutputStreamSpliceFlags.
32574 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32575 * @error: a #GError location to store the error occurring, or %NULL to ignore.
32577 * Splices an input stream into an output stream.
32579 * -1 if an error occurred. Note that if the number of bytes
32580 * spliced is greater than %G_MAXSSIZE, then that will be
32581 * returned, and there is no way to determine the actual number
32582 * of bytes spliced.
32584 * Returns: a #gssize containing the size of the data spliced, or
32589 * g_output_stream_splice_async:
32590 * @stream: a #GOutputStream.
32591 * @source: a #GInputStream.
32592 * @flags: a set of #GOutputStreamSpliceFlags.
32593 * @io_priority: the io priority of the request.
32594 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32595 * @callback: (scope async): a #GAsyncReadyCallback.
32596 * @user_data: (closure): user data passed to @callback.
32598 * Splices a stream asynchronously.
32599 * When the operation is finished @callback will be called.
32600 * You can then call g_output_stream_splice_finish() to get the
32601 * result of the operation.
32603 * For the synchronous, blocking version of this function, see
32604 * g_output_stream_splice().
32609 * g_output_stream_splice_finish:
32610 * @stream: a #GOutputStream.
32611 * @result: a #GAsyncResult.
32612 * @error: a #GError location to store the error occurring, or %NULL to ignore.
32614 * Finishes an asynchronous stream splice operation.
32616 * number of bytes spliced is greater than %G_MAXSSIZE, then that
32617 * will be returned, and there is no way to determine the actual
32618 * number of bytes spliced.
32620 * Returns: a #gssize of the number of bytes spliced. Note that if the
32625 * g_output_stream_write:
32626 * @stream: a #GOutputStream.
32627 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
32628 * @count: the number of bytes to write
32629 * @cancellable: (allow-none): optional cancellable object
32630 * @error: location to store the error occurring, or %NULL to ignore
32632 * Tries to write @count bytes from @buffer into the stream. Will block
32633 * during the operation.
32635 * If count is 0, returns 0 and does nothing. A value of @count
32636 * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error.
32638 * On success, the number of bytes written to the stream is returned.
32639 * It is not an error if this is not the same as the requested size, as it
32640 * can happen e.g. on a partial I/O error, or if there is not enough
32641 * storage in the stream. All writes block until at least one byte
32642 * is written or an error occurs; 0 is never returned (unless
32645 * If @cancellable is not NULL, then the operation can be cancelled by
32646 * triggering the cancellable object from another thread. If the operation
32647 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
32648 * operation was partially finished when the operation was cancelled the
32649 * partial result will be returned, without an error.
32651 * On error -1 is returned and @error is set accordingly.
32653 * Virtual: write_fn
32654 * Returns: Number of bytes written, or -1 on error
32659 * g_output_stream_write_all:
32660 * @stream: a #GOutputStream.
32661 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
32662 * @count: the number of bytes to write
32663 * @bytes_written: (out): location to store the number of bytes that was written to the stream
32664 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32665 * @error: location to store the error occurring, or %NULL to ignore
32667 * Tries to write @count bytes from @buffer into the stream. Will block
32668 * during the operation.
32670 * This function is similar to g_output_stream_write(), except it tries to
32671 * write as many bytes as requested, only stopping on an error.
32673 * On a successful write of @count bytes, %TRUE is returned, and @bytes_written
32674 * is set to @count.
32676 * If there is an error during the operation FALSE is returned and @error
32677 * is set to indicate the error status, @bytes_written is updated to contain
32678 * the number of bytes written into the stream before the error occurred.
32680 * Returns: %TRUE on success, %FALSE if there was an error
32685 * g_output_stream_write_async:
32686 * @stream: A #GOutputStream.
32687 * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
32688 * @count: the number of bytes to write
32689 * @io_priority: the io priority of the request.
32690 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
32691 * @callback: (scope async): callback to call when the request is satisfied
32692 * @user_data: (closure): the data to pass to callback function
32694 * Request an asynchronous write of @count bytes from @buffer into
32695 * the stream. When the operation is finished @callback will be called.
32696 * You can then call g_output_stream_write_finish() to get the result of the
32699 * During an async request no other sync and async calls are allowed,
32700 * and will result in %G_IO_ERROR_PENDING errors.
32702 * A value of @count larger than %G_MAXSSIZE will cause a
32703 * %G_IO_ERROR_INVALID_ARGUMENT error.
32705 * On success, the number of bytes written will be passed to the
32706 * @callback. It is not an error if this is not the same as the
32707 * requested size, as it can happen e.g. on a partial I/O error,
32708 * but generally we try to write as many bytes as requested.
32710 * You are guaranteed that this method will never fail with
32711 * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the
32712 * method will just wait until this changes.
32714 * Any outstanding I/O request with higher priority (lower numerical
32715 * value) will be executed before an outstanding request with lower
32716 * priority. Default priority is %G_PRIORITY_DEFAULT.
32718 * The asyncronous methods have a default fallback that uses threads
32719 * to implement asynchronicity, so they are optional for inheriting
32720 * classes. However, if you override one you must override all.
32722 * For the synchronous, blocking version of this function, see
32723 * g_output_stream_write().
32728 * g_output_stream_write_finish:
32729 * @stream: a #GOutputStream.
32730 * @result: a #GAsyncResult.
32731 * @error: a #GError location to store the error occurring, or %NULL to ignore.
32733 * Finishes a stream write operation.
32735 * Returns: a #gssize containing the number of bytes written to the stream.
32740 * g_permission_acquire:
32741 * @permission: a #GPermission instance
32742 * @cancellable: a #GCancellable, or %NULL
32743 * @error: a pointer to a %NULL #GError, or %NULL
32745 * Attempts to acquire the permission represented by @permission.
32747 * The precise method by which this happens depends on the permission
32748 * and the underlying authentication mechanism. A simple example is
32749 * that a dialog may appear asking the user to enter their password.
32751 * You should check with g_permission_get_can_acquire() before calling
32754 * If the permission is acquired then %TRUE is returned. Otherwise,
32755 * %FALSE is returned and @error is set appropriately.
32757 * This call is blocking, likely for a very long time (in the case that
32758 * user interaction is required). See g_permission_acquire_async() for
32759 * the non-blocking version.
32761 * Returns: %TRUE if the permission was successfully acquired
32767 * g_permission_acquire_async:
32768 * @permission: a #GPermission instance
32769 * @cancellable: a #GCancellable, or %NULL
32770 * @callback: the #GAsyncReadyCallback to call when done
32771 * @user_data: the user data to pass to @callback
32773 * Attempts to acquire the permission represented by @permission.
32775 * This is the first half of the asynchronous version of
32776 * g_permission_acquire().
32783 * g_permission_acquire_finish:
32784 * @permission: a #GPermission instance
32785 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
32786 * @error: a pointer to a %NULL #GError, or %NULL
32788 * Collects the result of attempting to acquire the permission
32789 * represented by @permission.
32791 * This is the second half of the asynchronous version of
32792 * g_permission_acquire().
32794 * Returns: %TRUE if the permission was successfully acquired
32800 * g_permission_get_allowed:
32801 * @permission: a #GPermission instance
32803 * Gets the value of the 'allowed' property. This property is %TRUE if
32804 * the caller currently has permission to perform the action that
32805 * @permission represents the permission to perform.
32807 * Returns: the value of the 'allowed' property
32813 * g_permission_get_can_acquire:
32814 * @permission: a #GPermission instance
32816 * Gets the value of the 'can-acquire' property. This property is %TRUE
32817 * if it is generally possible to acquire the permission by calling
32818 * g_permission_acquire().
32820 * Returns: the value of the 'can-acquire' property
32826 * g_permission_get_can_release:
32827 * @permission: a #GPermission instance
32829 * Gets the value of the 'can-release' property. This property is %TRUE
32830 * if it is generally possible to release the permission by calling
32831 * g_permission_release().
32833 * Returns: the value of the 'can-release' property
32839 * g_permission_impl_update:
32840 * @permission: a #GPermission instance
32841 * @allowed: the new value for the 'allowed' property
32842 * @can_acquire: the new value for the 'can-acquire' property
32843 * @can_release: the new value for the 'can-release' property
32845 * This function is called by the #GPermission implementation to update
32846 * the properties of the permission. You should never call this
32847 * function except from a #GPermission implementation.
32849 * GObject notify signals are generated, as appropriate.
32856 * g_permission_release:
32857 * @permission: a #GPermission instance
32858 * @cancellable: a #GCancellable, or %NULL
32859 * @error: a pointer to a %NULL #GError, or %NULL
32861 * Attempts to release the permission represented by @permission.
32863 * The precise method by which this happens depends on the permission
32864 * and the underlying authentication mechanism. In most cases the
32865 * permission will be dropped immediately without further action.
32867 * You should check with g_permission_get_can_release() before calling
32870 * If the permission is released then %TRUE is returned. Otherwise,
32871 * %FALSE is returned and @error is set appropriately.
32873 * This call is blocking, likely for a very long time (in the case that
32874 * user interaction is required). See g_permission_release_async() for
32875 * the non-blocking version.
32877 * Returns: %TRUE if the permission was successfully released
32883 * g_permission_release_async:
32884 * @permission: a #GPermission instance
32885 * @cancellable: a #GCancellable, or %NULL
32886 * @callback: the #GAsyncReadyCallback to call when done
32887 * @user_data: the user data to pass to @callback
32889 * Attempts to release the permission represented by @permission.
32891 * This is the first half of the asynchronous version of
32892 * g_permission_release().
32899 * g_permission_release_finish:
32900 * @permission: a #GPermission instance
32901 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
32902 * @error: a pointer to a %NULL #GError, or %NULL
32904 * Collects the result of attempting to release the permission
32905 * represented by @permission.
32907 * This is the second half of the asynchronous version of
32908 * g_permission_release().
32910 * Returns: %TRUE if the permission was successfully released
32916 * g_poll_file_monitor_new:
32919 * Polls @file for changes.
32921 * Returns: a new #GFileMonitor for the given #GFile.
32926 * g_pollable_input_stream_can_poll:
32927 * @stream: a #GPollableInputStream.
32929 * Checks if @stream is actually pollable. Some classes may implement
32930 * #GPollableInputStream but have only certain instances of that class
32931 * be pollable. If this method returns %FALSE, then the behavior of
32932 * other #GPollableInputStream methods is undefined.
32934 * For any given stream, the value returned by this method is constant;
32935 * a stream cannot switch from pollable to non-pollable or vice versa.
32937 * Returns: %TRUE if @stream is pollable, %FALSE if not.
32943 * g_pollable_input_stream_create_source:
32944 * @stream: a #GPollableInputStream.
32945 * @cancellable: (allow-none): a #GCancellable, or %NULL
32947 * Creates a #GSource that triggers when @stream can be read, or
32948 * @cancellable is triggered or an error occurs. The callback on the
32949 * source is of the #GPollableSourceFunc type.
32951 * As with g_pollable_input_stream_is_readable(), it is possible that
32952 * the stream may not actually be readable even after the source
32953 * triggers, so you should use g_pollable_input_stream_read_nonblocking()
32954 * rather than g_input_stream_read() from the callback.
32956 * Returns: (transfer full): a new #GSource
32962 * g_pollable_input_stream_is_readable:
32963 * @stream: a #GPollableInputStream.
32965 * Checks if @stream can be read.
32967 * Note that some stream types may not be able to implement this 100%
32968 * reliably, and it is possible that a call to g_input_stream_read()
32969 * after this returns %TRUE would still block. To guarantee
32970 * non-blocking behavior, you should always use
32971 * g_pollable_input_stream_read_nonblocking(), which will return a
32972 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
32974 * has occurred on @stream, this will result in
32975 * g_pollable_input_stream_is_readable() returning %TRUE, and the
32976 * next attempt to read will return the error.
32978 * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
32984 * g_pollable_input_stream_read_nonblocking:
32985 * @stream: a #GPollableInputStream
32986 * @buffer: a buffer to read data into (which should be at least @size bytes long).
32987 * @size: the number of bytes you want to read
32988 * @cancellable: (allow-none): a #GCancellable, or %NULL
32989 * @error: #GError for error reporting, or %NULL to ignore.
32991 * Attempts to read up to @size bytes from @stream into @buffer, as
32992 * with g_input_stream_read(). If @stream is not currently readable,
32993 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
32994 * use g_pollable_input_stream_create_source() to create a #GSource
32995 * that will be triggered when @stream is readable.
32997 * Note that since this method never blocks, you cannot actually
32998 * use @cancellable to cancel it. However, it will return an error
32999 * if @cancellable has already been cancelled when you call, which
33000 * may happen if you call this method after a source triggers due
33001 * to having been cancelled.
33003 * %G_IO_ERROR_WOULD_BLOCK).
33005 * Virtual: read_nonblocking
33006 * Returns: the number of bytes read, or -1 on error (including
33011 * g_pollable_output_stream_can_poll:
33012 * @stream: a #GPollableOutputStream.
33014 * Checks if @stream is actually pollable. Some classes may implement
33015 * #GPollableOutputStream but have only certain instances of that
33016 * class be pollable. If this method returns %FALSE, then the behavior
33017 * of other #GPollableOutputStream methods is undefined.
33019 * For any given stream, the value returned by this method is constant;
33020 * a stream cannot switch from pollable to non-pollable or vice versa.
33022 * Returns: %TRUE if @stream is pollable, %FALSE if not.
33028 * g_pollable_output_stream_create_source:
33029 * @stream: a #GPollableOutputStream.
33030 * @cancellable: (allow-none): a #GCancellable, or %NULL
33032 * Creates a #GSource that triggers when @stream can be written, or
33033 * @cancellable is triggered or an error occurs. The callback on the
33034 * source is of the #GPollableSourceFunc type.
33036 * As with g_pollable_output_stream_is_writable(), it is possible that
33037 * the stream may not actually be writable even after the source
33038 * triggers, so you should use g_pollable_output_stream_write_nonblocking()
33039 * rather than g_output_stream_write() from the callback.
33041 * Returns: (transfer full): a new #GSource
33047 * g_pollable_output_stream_is_writable:
33048 * @stream: a #GPollableOutputStream.
33050 * Checks if @stream can be written.
33052 * Note that some stream types may not be able to implement this 100%
33053 * reliably, and it is possible that a call to g_output_stream_write()
33054 * after this returns %TRUE would still block. To guarantee
33055 * non-blocking behavior, you should always use
33056 * g_pollable_output_stream_write_nonblocking(), which will return a
33057 * %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
33059 * has occurred on @stream, this will result in
33060 * g_pollable_output_stream_is_writable() returning %TRUE, and the
33061 * next attempt to write will return the error.
33063 * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
33069 * g_pollable_output_stream_write_nonblocking:
33070 * @stream: a #GPollableOutputStream
33071 * @buffer: (array length=size) (element-type guint8): a buffer to write data from
33072 * @size: the number of bytes you want to write
33073 * @cancellable: (allow-none): a #GCancellable, or %NULL
33074 * @error: #GError for error reporting, or %NULL to ignore.
33076 * Attempts to write up to @size bytes from @buffer to @stream, as
33077 * with g_output_stream_write(). If @stream is not currently writable,
33078 * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can
33079 * use g_pollable_output_stream_create_source() to create a #GSource
33080 * that will be triggered when @stream is writable.
33082 * Note that since this method never blocks, you cannot actually
33083 * use @cancellable to cancel it. However, it will return an error
33084 * if @cancellable has already been cancelled when you call, which
33085 * may happen if you call this method after a source triggers due
33086 * to having been cancelled.
33088 * %G_IO_ERROR_WOULD_BLOCK).
33090 * Virtual: write_nonblocking
33091 * Returns: the number of bytes written, or -1 on error (including
33096 * g_pollable_source_new:
33097 * @pollable_stream: the stream associated with the new source
33099 * Utility method for #GPollableInputStream and #GPollableOutputStream
33100 * implementations. Creates a new #GSource that expects a callback of
33101 * type #GPollableSourceFunc. The new source does not actually do
33102 * anything on its own; use g_source_add_child_source() to add other
33103 * sources to it to cause it to trigger.
33105 * Returns: (transfer full): the new #GSource.
33111 * g_proxy_address_get_destination_hostname:
33112 * @proxy: a #GProxyAddress
33114 * Gets @proxy's destination hostname.
33116 * Returns: the @proxy's destination hostname
33122 * g_proxy_address_get_destination_port:
33123 * @proxy: a #GProxyAddress
33125 * Gets @proxy's destination port.
33127 * Returns: the @proxy's destination port
33133 * g_proxy_address_get_password:
33134 * @proxy: a #GProxyAddress
33136 * Gets @proxy's password.
33138 * Returns: the @proxy's password
33144 * g_proxy_address_get_protocol:
33145 * @proxy: a #GProxyAddress
33147 * Gets @proxy's protocol.
33149 * Returns: the @proxy's protocol
33155 * g_proxy_address_get_username:
33156 * @proxy: a #GProxyAddress
33158 * Gets @proxy's username.
33160 * Returns: the @proxy's username
33166 * g_proxy_address_new:
33167 * @inetaddr: The proxy server #GInetAddress.
33168 * @port: The proxy server port.
33169 * @protocol: The proxy protocol to support, in lower case (e.g. socks, http).
33170 * @dest_hostname: The destination hostname the the proxy should tunnel to.
33171 * @dest_port: The destination port to tunnel to.
33172 * @username: (allow-none): The username to authenticate to the proxy server (or %NULL).
33173 * @password: (allow-none): The password to authenticate to the proxy server (or %NULL).
33175 * Creates a new #GProxyAddress for @inetaddr with @protocol that should
33176 * tunnel through @dest_hostname and @dest_port.
33178 * Returns: a new #GProxyAddress
33185 * @proxy: a #GProxy
33186 * @connection: a #GIOStream
33187 * @proxy_address: a #GProxyAddress
33188 * @cancellable: (allow-none): a #GCancellable
33189 * @error: return #GError
33191 * Given @connection to communicate with a proxy (eg, a
33192 * #GSocketConnection that is connected to the proxy server), this
33193 * does the necessary handshake to connect to @proxy_address, and if
33194 * required, wraps the #GIOStream to handle proxy payload.
33196 * be the same as @connection, in which case a reference
33199 * Returns: (transfer full): a #GIOStream that will replace @connection. This might
33205 * g_proxy_connect_async:
33206 * @proxy: a #GProxy
33207 * @connection: a #GIOStream
33208 * @proxy_address: a #GProxyAddress
33209 * @cancellable: (allow-none): a #GCancellable
33210 * @callback: (scope async): a #GAsyncReadyCallback
33211 * @user_data: (closure): callback data
33213 * Asynchronous version of g_proxy_connect().
33220 * g_proxy_connect_finish:
33221 * @proxy: a #GProxy
33222 * @result: a #GAsyncResult
33223 * @error: return #GError
33225 * See g_proxy_connect().
33227 * Returns: (transfer full): a #GIOStream.
33233 * g_proxy_get_default_for_protocol:
33234 * @protocol: the proxy protocol name (e.g. http, socks, etc)
33236 * Lookup "gio-proxy" extension point for a proxy implementation that supports
33237 * specified protocol.
33239 * is not supported.
33241 * Returns: (transfer full): return a #GProxy or NULL if protocol
33247 * g_proxy_resolver_get_default:
33249 * Gets the default #GProxyResolver for the system.
33251 * Returns: (transfer none): the default #GProxyResolver.
33257 * g_proxy_resolver_is_supported:
33258 * @resolver: a #GProxyResolver
33260 * Checks if @resolver can be used on this system. (This is used
33261 * internally; g_proxy_resolver_get_default() will only return a proxy
33262 * resolver that returns %TRUE for this method.)
33264 * Returns: %TRUE if @resolver is supported.
33270 * g_proxy_resolver_lookup:
33271 * @resolver: a #GProxyResolver
33272 * @uri: a URI representing the destination to connect to
33273 * @cancellable: (allow-none): a #GCancellable, or %NULL
33274 * @error: return location for a #GError, or %NULL
33276 * Looks into the system proxy configuration to determine what proxy,
33277 * if any, to use to connect to @uri. The returned proxy URIs are of the
33278 * form <literal><protocol>://[user[:password]@]host:port</literal>
33279 * or <literal>direct://</literal>, where <protocol> could be
33280 * http, rtsp, socks or other proxying protocol.
33282 * If you don't know what network protocol is being used on the
33283 * socket, you should use <literal>none</literal> as the URI protocol.
33284 * In this case, the resolver might still return a generic proxy type
33285 * (such as SOCKS), but would not return protocol-specific proxy types
33288 * <literal>direct://</literal> is used when no proxy is needed.
33289 * Direct connection should not be attempted unless it is part of the
33290 * returned array of proxies.
33292 * NULL-terminated array of proxy URIs. Must be freed
33293 * with g_strfreev().
33295 * Returns: (transfer full) (array zero-terminated=1): A
33301 * g_proxy_resolver_lookup_async:
33302 * @resolver: a #GProxyResolver
33303 * @uri: a URI representing the destination to connect to
33304 * @cancellable: (allow-none): a #GCancellable, or %NULL
33305 * @callback: (scope async): callback to call after resolution completes
33306 * @user_data: (closure): data for @callback
33308 * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
33316 * g_proxy_resolver_lookup_finish:
33317 * @resolver: a #GProxyResolver
33318 * @result: the result passed to your #GAsyncReadyCallback
33319 * @error: return location for a #GError, or %NULL
33321 * Call this function to obtain the array of proxy URIs when
33322 * g_proxy_resolver_lookup_async() is complete. See
33323 * g_proxy_resolver_lookup() for more details.
33325 * NULL-terminated array of proxy URIs. Must be freed
33326 * with g_strfreev().
33328 * Returns: (transfer full) (array zero-terminated=1): A
33334 * g_proxy_supports_hostname:
33335 * @proxy: a #GProxy
33337 * Some proxy protocols expect to be passed a hostname, which they
33338 * will resolve to an IP address themselves. Others, like SOCKS4, do
33339 * not allow this. This function will return %FALSE if @proxy is
33340 * implementing such a protocol. When %FALSE is returned, the caller
33341 * should resolve the destination hostname first, and then pass a
33342 * #GProxyAddress containing the stringified IP address to
33343 * g_proxy_connect() or g_proxy_connect_async().
33345 * Returns: %TRUE if hostname resolution is supported.
33351 * g_remote_action_group_activate_action_full:
33352 * @remote: a #GDBusActionGroup
33353 * @action_name: the name of the action to activate
33354 * @parameter: (allow none): the optional parameter to the activation
33355 * @platform_data: the platform data to send
33357 * Activates the remote action.
33359 * This is the same as g_action_group_activate_action() except that it
33360 * allows for provision of "platform data" to be sent along with the
33361 * activation request. This typically contains details such as the user
33362 * interaction timestamp or startup notification information.
33364 * @platform_data must be non-%NULL and must have the type
33365 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
33372 * g_remote_action_group_change_action_state_full:
33373 * @remote: a #GRemoteActionGroup
33374 * @action_name: the name of the action to change the state of
33375 * @value: the new requested value for the state
33376 * @platform_data: the platform data to send
33378 * Changes the state of a remote action.
33380 * This is the same as g_action_group_change_action_state() except that
33381 * it allows for provision of "platform data" to be sent along with the
33382 * state change request. This typically contains details such as the
33383 * user interaction timestamp or startup notification information.
33385 * @platform_data must be non-%NULL and must have the type
33386 * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.
33394 * @struct_type: the type of the elements to allocate
33395 * @mem: the currently allocated memory
33396 * @n_structs: the number of elements to allocate
33398 * Reallocates the memory pointed to by @mem, so that it now has space for
33399 * @n_structs elements of type @struct_type. It returns the new address of
33400 * the memory, which may have been moved.
33401 * Care is taken to avoid overflow when calculating the size of the allocated block.
33403 * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
33408 * g_resolver_error_quark:
33410 * Gets the #GResolver Error Quark.
33412 * Returns: a #GQuark.
33418 * g_resolver_free_addresses: (skip)
33419 * @addresses: a #GList of #GInetAddress
33421 * Frees @addresses (which should be the return value from
33422 * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
33423 * (This is a convenience method; you can also simply free the results
33431 * g_resolver_free_targets: (skip)
33432 * @targets: a #GList of #GSrvTarget
33434 * Frees @targets (which should be the return value from
33435 * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
33436 * (This is a convenience method; you can also simply free the
33437 * results by hand.)
33444 * g_resolver_get_default:
33446 * Gets the default #GResolver. You should unref it when you are done
33447 * with it. #GResolver may use its reference count as a hint about how
33448 * many threads it should allocate for concurrent DNS resolutions.
33450 * Returns: (transfer full): the default #GResolver.
33456 * g_resolver_lookup_by_address:
33457 * @resolver: a #GResolver
33458 * @address: the address to reverse-resolve
33459 * @cancellable: (allow-none): a #GCancellable, or %NULL
33460 * @error: return location for a #GError, or %NULL
33462 * Synchronously reverse-resolves @address to determine its
33463 * associated hostname.
33465 * If the DNS resolution fails, @error (if non-%NULL) will be set to
33466 * a value from #GResolverError.
33468 * If @cancellable is non-%NULL, it can be used to cancel the
33469 * operation, in which case @error (if non-%NULL) will be set to
33470 * %G_IO_ERROR_CANCELLED.
33472 * form), or %NULL on error.
33474 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
33480 * g_resolver_lookup_by_address_async:
33481 * @resolver: a #GResolver
33482 * @address: the address to reverse-resolve
33483 * @cancellable: (allow-none): a #GCancellable, or %NULL
33484 * @callback: (scope async): callback to call after resolution completes
33485 * @user_data: (closure): data for @callback
33487 * Begins asynchronously reverse-resolving @address to determine its
33488 * associated hostname, and eventually calls @callback, which must
33489 * call g_resolver_lookup_by_address_finish() to get the final result.
33496 * g_resolver_lookup_by_address_finish:
33497 * @resolver: a #GResolver
33498 * @result: the result passed to your #GAsyncReadyCallback
33499 * @error: return location for a #GError, or %NULL
33501 * Retrieves the result of a previous call to
33502 * g_resolver_lookup_by_address_async().
33504 * If the DNS resolution failed, @error (if non-%NULL) will be set to
33505 * a value from #GResolverError. If the operation was cancelled,
33506 * @error will be set to %G_IO_ERROR_CANCELLED.
33508 * form), or %NULL on error.
33510 * Returns: a hostname (either ASCII-only, or in ASCII-encoded
33516 * g_resolver_lookup_by_name:
33517 * @resolver: a #GResolver
33518 * @hostname: the hostname to look up
33519 * @cancellable: (allow-none): a #GCancellable, or %NULL
33520 * @error: return location for a #GError, or %NULL
33522 * Synchronously resolves @hostname to determine its associated IP
33523 * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
33524 * the textual form of an IP address (in which case this just becomes
33525 * a wrapper around g_inet_address_new_from_string()).
33527 * On success, g_resolver_lookup_by_name() will return a #GList of
33528 * #GInetAddress, sorted in order of preference and guaranteed to not
33529 * contain duplicates. That is, if using the result to connect to
33530 * @hostname, you should attempt to connect to the first address
33531 * first, then the second if the first fails, etc. If you are using
33532 * the result to listen on a socket, it is appropriate to add each
33533 * result using e.g. g_socket_listener_add_address().
33535 * If the DNS resolution fails, @error (if non-%NULL) will be set to a
33536 * value from #GResolverError.
33538 * If @cancellable is non-%NULL, it can be used to cancel the
33539 * operation, in which case @error (if non-%NULL) will be set to
33540 * %G_IO_ERROR_CANCELLED.
33542 * If you are planning to connect to a socket on the resolved IP
33543 * address, it may be easier to create a #GNetworkAddress and use its
33544 * #GSocketConnectable interface.
33546 * of #GInetAddress, or %NULL on error. You
33547 * must unref each of the addresses and free the list when you are
33548 * done with it. (You can use g_resolver_free_addresses() to do this.)
33550 * Returns: (element-type GInetAddress) (transfer full): a #GList
33556 * g_resolver_lookup_by_name_async:
33557 * @resolver: a #GResolver
33558 * @hostname: the hostname to look up the address of
33559 * @cancellable: (allow-none): a #GCancellable, or %NULL
33560 * @callback: (scope async): callback to call after resolution completes
33561 * @user_data: (closure): data for @callback
33563 * Begins asynchronously resolving @hostname to determine its
33564 * associated IP address(es), and eventually calls @callback, which
33565 * must call g_resolver_lookup_by_name_finish() to get the result.
33566 * See g_resolver_lookup_by_name() for more details.
33573 * g_resolver_lookup_by_name_finish:
33574 * @resolver: a #GResolver
33575 * @result: the result passed to your #GAsyncReadyCallback
33576 * @error: return location for a #GError, or %NULL
33578 * Retrieves the result of a call to
33579 * g_resolver_lookup_by_name_async().
33581 * If the DNS resolution failed, @error (if non-%NULL) will be set to
33582 * a value from #GResolverError. If the operation was cancelled,
33583 * @error will be set to %G_IO_ERROR_CANCELLED.
33585 * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
33586 * for more details.
33588 * Returns: (element-type GInetAddress) (transfer full): a #GList
33594 * g_resolver_lookup_service:
33595 * @resolver: a #GResolver
33596 * @service: the service type to look up (eg, "ldap")
33597 * @protocol: the networking protocol to use for @service (eg, "tcp")
33598 * @domain: the DNS domain to look up the service in
33599 * @cancellable: (allow-none): a #GCancellable, or %NULL
33600 * @error: return location for a #GError, or %NULL
33602 * Synchronously performs a DNS SRV lookup for the given @service and
33603 * @protocol in the given @domain and returns an array of #GSrvTarget.
33604 * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
33605 * @service and @protocol arguments <emphasis>do not</emphasis>
33606 * include the leading underscore that appears in the actual DNS
33609 * On success, g_resolver_lookup_service() will return a #GList of
33610 * #GSrvTarget, sorted in order of preference. (That is, you should
33611 * attempt to connect to the first target first, then the second if
33612 * the first fails, etc.)
33614 * If the DNS resolution fails, @error (if non-%NULL) will be set to
33615 * a value from #GResolverError.
33617 * If @cancellable is non-%NULL, it can be used to cancel the
33618 * operation, in which case @error (if non-%NULL) will be set to
33619 * %G_IO_ERROR_CANCELLED.
33621 * If you are planning to connect to the service, it is usually easier
33622 * to create a #GNetworkService and use its #GSocketConnectable
33625 * or %NULL on error. You must free each of the targets and the list when you are
33626 * done with it. (You can use g_resolver_free_targets() to do this.)
33628 * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
33634 * g_resolver_lookup_service_async:
33635 * @resolver: a #GResolver
33636 * @service: the service type to look up (eg, "ldap")
33637 * @protocol: the networking protocol to use for @service (eg, "tcp")
33638 * @domain: the DNS domain to look up the service in
33639 * @cancellable: (allow-none): a #GCancellable, or %NULL
33640 * @callback: (scope async): callback to call after resolution completes
33641 * @user_data: (closure): data for @callback
33643 * Begins asynchronously performing a DNS SRV lookup for the given
33644 * @service and @protocol in the given @domain, and eventually calls
33645 * @callback, which must call g_resolver_lookup_service_finish() to
33646 * get the final result. See g_resolver_lookup_service() for more
33654 * g_resolver_lookup_service_finish:
33655 * @resolver: a #GResolver
33656 * @result: the result passed to your #GAsyncReadyCallback
33657 * @error: return location for a #GError, or %NULL
33659 * Retrieves the result of a previous call to
33660 * g_resolver_lookup_service_async().
33662 * If the DNS resolution failed, @error (if non-%NULL) will be set to
33663 * a value from #GResolverError. If the operation was cancelled,
33664 * @error will be set to %G_IO_ERROR_CANCELLED.
33666 * or %NULL on error. See g_resolver_lookup_service() for more details.
33668 * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
33674 * g_resolver_set_default:
33675 * @resolver: the new default #GResolver
33677 * Sets @resolver to be the application's default resolver (reffing
33678 * @resolver, and unreffing the previous default resolver, if any).
33679 * Future calls to g_resolver_get_default() will return this resolver.
33681 * This can be used if an application wants to perform any sort of DNS
33682 * caching or "pinning"; it can implement its own #GResolver that
33683 * calls the original default resolver for DNS operations, and
33684 * implements its own cache policies on top of that, and then set
33685 * itself as the default resolver for all later code to use.
33692 * g_resource_enumerate_children:
33693 * @resource: A #GResource.
33694 * @path: A pathname inside the resource.
33695 * @lookup_flags: A #GResourceLookupFlags.
33696 * @error: return location for a #GError, or %NULL.
33698 * Returns all the names of children at the specified @path in the resource.
33699 * The return result is a %NULL terminated list of strings which should
33700 * be released with g_strfreev().
33702 * @lookup_flags controls the behaviour of the lookup.
33704 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
33710 * g_resource_error_quark:
33712 * Gets the #GResource Error Quark.
33714 * Returns: a #GQuark.
33720 * g_resource_get_info:
33721 * @resource: A #GResource.
33722 * @path: A pathname inside the resource.
33723 * @lookup_flags: A #GResourceLookupFlags.
33724 * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
33725 * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed
33726 * @error: return location for a #GError, or %NULL.
33728 * Looks for a file at the specified @path in the resource and
33729 * if found returns information about it.
33731 * @lookup_flags controls the behaviour of the lookup.
33733 * Returns: %TRUE if the file was found. %FALSE if there were errors.
33740 * @filename: (type filename): the path of a filename to load, in the GLib filename encoding.
33741 * @error: return location for a #GError, or %NULL.
33743 * Loads a binary resource bundle and creates a #GResource representation of it, allowing
33744 * you to query it for data.
33746 * If you want to use this resource in the global resource namespace you need
33747 * to register it with g_resources_register().
33749 * Returns: (transfer full): a new #GResource, or %NULL on error.
33755 * g_resource_lookup_data:
33756 * @resource: A #GResource.
33757 * @path: A pathname inside the resource.
33758 * @lookup_flags: A #GResourceLookupFlags.
33759 * @error: return location for a #GError, or %NULL.
33761 * Looks for a file at the specified @path in the resource and
33762 * returns a #GBytes that lets you directly access the data in
33765 * The data is always followed by a zero byte, so you
33766 * can safely use the data as a C string. However, that byte
33767 * is not included in the size of the GBytes.
33769 * For uncompressed resource files this is a pointer directly into
33770 * the resource bundle, which is typically in some readonly data section
33771 * in the program binary. For compressed files we allocate memory on
33772 * the heap and automatically uncompress the data.
33774 * @lookup_flags controls the behaviour of the lookup.
33776 * Free the returned object with g_bytes_unref().
33778 * Returns: (transfer full): #GBytes or %NULL on error.
33784 * g_resource_new_from_data:
33785 * @data: A #GBytes.
33786 * @error: return location for a #GError, or %NULL.
33788 * Creates a GResource from a reference to the binary resource bundle.
33789 * This will keep a reference to @data while the resource lives, so
33790 * the data should not be modified or freed.
33792 * If you want to use this resource in the global resource namespace you need
33793 * to register it with g_resources_register().
33795 * Returns: (transfer full): a new #GResource, or %NULL on error.
33801 * g_resource_open_stream:
33802 * @resource: A #GResource.
33803 * @path: A pathname inside the resource.
33804 * @lookup_flags: A #GResourceLookupFlags.
33805 * @error: return location for a #GError, or %NULL.
33807 * Looks for a file at the specified @path in the resource and
33808 * returns a #GInputStream that lets you read the data.
33810 * @lookup_flags controls the behaviour of the lookup.
33812 * Free the returned object with g_object_unref().
33814 * Returns: (transfer full): #GInputStream or %NULL on error.
33821 * @resource: A #GResource.
33823 * Atomically increments the reference count of @array by one. This
33824 * function is MT-safe and may be called from any thread.
33826 * Returns: The passed in #GResource.
33832 * g_resource_unref:
33833 * @resource: A #GResource.
33835 * Atomically decrements the reference count of @resource by one. If the
33836 * reference count drops to 0, all memory allocated by the array is
33837 * released. This function is MT-safe and may be called from any
33845 * g_resources_enumerate_children:
33846 * @path: A pathname inside the resource.
33847 * @lookup_flags: A #GResourceLookupFlags.
33848 * @error: return location for a #GError, or %NULL.
33850 * Returns all the names of children at the specified @path in the set of
33851 * globally registred resources.
33852 * The return result is a %NULL terminated list of strings which should
33853 * be released with g_strfreev().
33855 * @lookup_flags controls the behaviour of the lookup.
33857 * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
33863 * g_resources_get_info:
33864 * @path: A pathname inside the resource.
33865 * @lookup_flags: A #GResourceLookupFlags.
33866 * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed
33867 * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed
33868 * @error: return location for a #GError, or %NULL.
33870 * Looks for a file at the specified @path in the set of
33871 * globally registred resources and if found returns information about it.
33873 * @lookup_flags controls the behaviour of the lookup.
33875 * Returns: %TRUE if the file was found. %FALSE if there were errors.
33881 * g_resources_lookup_data:
33882 * @path: A pathname inside the resource.
33883 * @lookup_flags: A #GResourceLookupFlags.
33884 * @error: return location for a #GError, or %NULL.
33886 * Looks for a file at the specified @path in the set of
33887 * globally registred resources and returns a #GBytes that
33888 * lets you directly access the data in memory.
33890 * The data is always followed by a zero byte, so you
33891 * can safely use the data as a C string. However, that byte
33892 * is not included in the size of the GBytes.
33894 * For uncompressed resource files this is a pointer directly into
33895 * the resource bundle, which is typically in some readonly data section
33896 * in the program binary. For compressed files we allocate memory on
33897 * the heap and automatically uncompress the data.
33899 * @lookup_flags controls the behaviour of the lookup.
33901 * Free the returned object with g_bytes_unref().
33903 * Returns: (transfer full): #GBytes or %NULL on error.
33909 * g_resources_open_stream:
33910 * @path: A pathname inside the resource.
33911 * @lookup_flags: A #GResourceLookupFlags.
33912 * @error: return location for a #GError, or %NULL.
33914 * Looks for a file at the specified @path in the set of
33915 * globally registred resources and returns a #GInputStream
33916 * that lets you read the data.
33918 * @lookup_flags controls the behaviour of the lookup.
33920 * Free the returned object with g_object_unref().
33922 * Returns: (transfer full): #GInputStream or %NULL on error.
33928 * g_resources_register:
33929 * @resource: A #GResource.
33931 * Registers the resource with the process-global set of resources.
33932 * Once a resource is registered the files in it can be accessed
33933 * with the global resource lookup functions like g_resources_lookup_data().
33940 * g_resources_unregister:
33941 * @resource: A #GResource.
33943 * Unregisters the resource from the process-global set of resources.
33950 * g_seekable_can_seek:
33951 * @seekable: a #GSeekable.
33953 * Tests if the stream supports the #GSeekableIface.
33955 * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
33960 * g_seekable_can_truncate:
33961 * @seekable: a #GSeekable.
33963 * Tests if the stream can be truncated.
33965 * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
33971 * @seekable: a #GSeekable.
33972 * @offset: a #goffset.
33973 * @type: a #GSeekType.
33974 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
33975 * @error: a #GError location to store the error occurring, or %NULL to ignore.
33977 * Seeks in the stream by the given @offset, modified by @type.
33979 * If @cancellable is not %NULL, then the operation can be cancelled by
33980 * triggering the cancellable object from another thread. If the operation
33981 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
33983 * has occurred, this function will return %FALSE and set @error
33984 * appropriately if present.
33986 * Returns: %TRUE if successful. If an error
33992 * @seekable: a #GSeekable.
33994 * Tells the current position within the stream.
33996 * Returns: the offset from the beginning of the buffer.
34001 * g_seekable_truncate:
34002 * @seekable: a #GSeekable.
34003 * @offset: a #goffset.
34004 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
34005 * @error: a #GError location to store the error occurring, or %NULL to ignore.
34007 * Truncates a stream with a given #offset.
34009 * If @cancellable is not %NULL, then the operation can be cancelled by
34010 * triggering the cancellable object from another thread. If the operation
34011 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
34012 * operation was partially finished when the operation was cancelled the
34013 * partial result will be returned, without an error.
34015 * has occurred, this function will return %FALSE and set @error
34016 * appropriately if present.
34018 * Virtual: truncate_fn
34019 * Returns: %TRUE if successful. If an error
34024 * g_settings_apply:
34025 * @settings: a #GSettings instance
34027 * Applies any changes that have been made to the settings. This
34028 * function does nothing unless @settings is in 'delay-apply' mode;
34029 * see g_settings_delay(). In the normal case settings are always
34030 * applied immediately.
34035 * g_settings_backend_changed:
34036 * @backend: a #GSettingsBackend implementation
34037 * @key: the name of the key
34038 * @origin_tag: the origin tag
34040 * Signals that a single key has possibly changed. Backend
34041 * implementations should call this if a key has possibly changed its
34044 * @key must be a valid key (ie starting with a slash, not containing
34045 * '//', and not ending with a slash).
34047 * The implementation must call this function during any call to
34048 * g_settings_backend_write(), before the call returns (except in the
34049 * case that no keys are actually changed and it cares to detect this
34050 * fact). It may not rely on the existence of a mainloop for
34051 * dispatching the signal later.
34053 * The implementation may call this function at any other time it likes
34054 * in response to other events (such as changes occurring outside of the
34055 * program). These calls may originate from a mainloop or may originate
34056 * in response to any other action (including from calls to
34057 * g_settings_backend_write()).
34059 * In the case that this call is in response to a call to
34060 * g_settings_backend_write() then @origin_tag must be set to the same
34061 * value that was passed to that call.
34068 * g_settings_backend_changed_tree:
34069 * @backend: a #GSettingsBackend implementation
34070 * @tree: a #GTree containing the changes
34071 * @origin_tag: the origin tag
34073 * This call is a convenience wrapper. It gets the list of changes from
34074 * @tree, computes the longest common prefix and calls
34075 * g_settings_backend_changed().
34082 * g_settings_backend_flatten_tree:
34083 * @tree: a #GTree containing the changes
34084 * @path: (out): the location to save the path
34085 * @keys: (out) (transfer container) (array zero-terminated=1): the location to save the relative keys
34086 * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): the location to save the values, or %NULL
34088 * Calculate the longest common prefix of all keys in a tree and write
34089 * out an array of the key names relative to that prefix and,
34090 * optionally, the value to store at each of those keys.
34092 * You must free the value returned in @path, @keys and @values using
34093 * g_free(). You should not attempt to free or unref the contents of
34094 * @keys or @values.
34101 * g_settings_backend_get_default:
34103 * Returns the default #GSettingsBackend. It is possible to override
34104 * the default by setting the <envar>GSETTINGS_BACKEND</envar>
34105 * environment variable to the name of a settings backend.
34107 * The user gets a reference to the backend.
34109 * Returns: (transfer full): the default #GSettingsBackend
34115 * g_settings_backend_keys_changed:
34116 * @backend: a #GSettingsBackend implementation
34117 * @path: the path containing the changes
34118 * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
34119 * @origin_tag: the origin tag
34121 * Signals that a list of keys have possibly changed. Backend
34122 * implementations should call this if keys have possibly changed their
34125 * @path must be a valid path (ie starting and ending with a slash and
34126 * not containing '//'). Each string in @items must form a valid key
34127 * name when @path is prefixed to it (ie: each item must not start or
34128 * end with '/' and must not contain '//').
34130 * The meaning of this signal is that any of the key names resulting
34131 * from the contatenation of @path with each item in @items may have
34134 * The same rules for when notifications must occur apply as per
34135 * g_settings_backend_changed(). These two calls can be used
34136 * interchangeably if exactly one item has changed (although in that
34137 * case g_settings_backend_changed() is definitely preferred).
34139 * For efficiency reasons, the implementation should strive for @path to
34140 * be as long as possible (ie: the longest common prefix of all of the
34141 * keys that were changed) but this is not strictly required.
34148 * g_settings_backend_path_changed:
34149 * @backend: a #GSettingsBackend implementation
34150 * @path: the path containing the changes
34151 * @origin_tag: the origin tag
34153 * Signals that all keys below a given path may have possibly changed.
34154 * Backend implementations should call this if an entire path of keys
34155 * have possibly changed their values.
34157 * @path must be a valid path (ie starting and ending with a slash and
34158 * not containing '//').
34160 * The meaning of this signal is that any of the key which has a name
34161 * starting with @path may have changed.
34163 * The same rules for when notifications must occur apply as per
34164 * g_settings_backend_changed(). This call might be an appropriate
34165 * reasponse to a 'reset' call but implementations are also free to
34166 * explicitly list the keys that were affected by that call if they can
34169 * For efficiency reasons, the implementation should strive for @path to
34170 * be as long as possible (ie: the longest common prefix of all of the
34171 * keys that were changed) but this is not strictly required. As an
34172 * example, if this function is called with the path of "/" then every
34173 * single key in the application will be notified of a possible change.
34180 * g_settings_backend_path_writable_changed:
34181 * @backend: a #GSettingsBackend implementation
34182 * @path: the name of the path
34184 * Signals that the writability of all keys below a given path may have
34187 * Since GSettings performs no locking operations for itself, this call
34188 * will always be made in response to external events.
34195 * g_settings_backend_writable_changed:
34196 * @backend: a #GSettingsBackend implementation
34197 * @key: the name of the key
34199 * Signals that the writability of a single key has possibly changed.
34201 * Since GSettings performs no locking operations for itself, this call
34202 * will always be made in response to external events.
34210 * @settings: a #GSettings object
34211 * @key: the key to bind
34212 * @object: (type GObject.Object): a #GObject
34213 * @property: the name of the property to bind
34214 * @flags: flags for the binding
34216 * Create a binding between the @key in the @settings object
34217 * and the property @property of @object.
34219 * The binding uses the default GIO mapping functions to map
34220 * between the settings and property values. These functions
34221 * handle booleans, numeric types and string types in a
34222 * straightforward way. Use g_settings_bind_with_mapping() if
34223 * you need a custom mapping, or map between types that are not
34224 * supported by the default mapping functions.
34226 * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this
34227 * function also establishes a binding between the writability of
34228 * @key and the "sensitive" property of @object (if @object has
34229 * a boolean property by that name). See g_settings_bind_writable()
34230 * for more details about writable bindings.
34232 * Note that the lifecycle of the binding is tied to the object,
34233 * and that you can have only one binding per object property.
34234 * If you bind the same property twice on the same object, the second
34235 * binding overrides the first one.
34242 * g_settings_bind_with_mapping: (skip)
34243 * @settings: a #GSettings object
34244 * @key: the key to bind
34245 * @object: (type GObject.Object): a #GObject
34246 * @property: the name of the property to bind
34247 * @flags: flags for the binding
34248 * @get_mapping: a function that gets called to convert values from @settings to @object, or %NULL to use the default GIO mapping
34249 * @set_mapping: a function that gets called to convert values from @object to @settings, or %NULL to use the default GIO mapping
34250 * @user_data: data that gets passed to @get_mapping and @set_mapping
34251 * @destroy: #GDestroyNotify function for @user_data
34253 * Create a binding between the @key in the @settings object
34254 * and the property @property of @object.
34256 * The binding uses the provided mapping functions to map between
34257 * settings and property values.
34259 * Note that the lifecycle of the binding is tied to the object,
34260 * and that you can have only one binding per object property.
34261 * If you bind the same property twice on the same object, the second
34262 * binding overrides the first one.
34269 * g_settings_bind_writable:
34270 * @settings: a #GSettings object
34271 * @key: the key to bind
34272 * @object: (type GObject.Object): a #GObject
34273 * @property: the name of a boolean property to bind
34274 * @inverted: whether to 'invert' the value
34276 * Create a binding between the writability of @key in the
34277 * @settings object and the property @property of @object.
34278 * The property must be boolean; "sensitive" or "visible"
34279 * properties of widgets are the most likely candidates.
34281 * Writable bindings are always uni-directional; changes of the
34282 * writability of the setting will be propagated to the object
34283 * property, not the other way.
34285 * When the @inverted argument is %TRUE, the binding inverts the
34286 * value as it passes from the setting to the object, i.e. @property
34287 * will be set to %TRUE if the key is <emphasis>not</emphasis>
34290 * Note that the lifecycle of the binding is tied to the object,
34291 * and that you can have only one binding per object property.
34292 * If you bind the same property twice on the same object, the second
34293 * binding overrides the first one.
34300 * g_settings_create_action:
34301 * @settings: a #GSettings
34302 * @key: the name of a key in @settings
34304 * Creates a #GAction corresponding to a given #GSettings key.
34306 * The action has the same name as the key.
34308 * The value of the key becomes the state of the action and the action
34309 * is enabled when the key is writable. Changing the state of the
34310 * action results in the key being written to. Changes to the value or
34311 * writability of the key cause appropriate change notifications to be
34312 * emitted for the action.
34314 * For boolean-valued keys, action activations take no parameter and
34315 * result in the toggling of the value. For all other types,
34316 * activations take the new value for the key (which must have the
34319 * Returns: (transfer full): a new #GAction
34325 * g_settings_delay:
34326 * @settings: a #GSettings object
34328 * Changes the #GSettings object into 'delay-apply' mode. In this
34329 * mode, changes to @settings are not immediately propagated to the
34330 * backend, but kept locally until g_settings_apply() is called.
34338 * @settings: a #GSettings object
34339 * @key: the key to get the value for
34340 * @format: a #GVariant format string
34341 * @...: arguments as per @format
34343 * Gets the value that is stored at @key in @settings.
34345 * A convenience function that combines g_settings_get_value() with
34348 * It is a programmer error to give a @key that isn't contained in the
34349 * schema for @settings or for the #GVariantType of @format to mismatch
34350 * the type given in the schema.
34357 * g_settings_get_boolean:
34358 * @settings: a #GSettings object
34359 * @key: the key to get the value for
34361 * Gets the value that is stored at @key in @settings.
34363 * A convenience variant of g_settings_get() for booleans.
34365 * It is a programmer error to give a @key that isn't specified as
34366 * having a boolean type in the schema for @settings.
34368 * Returns: a boolean
34374 * g_settings_get_child:
34375 * @settings: a #GSettings object
34376 * @name: the name of the 'child' schema
34378 * Creates a 'child' settings object which has a base path of
34379 * <replaceable>base-path</replaceable>/@name, where
34380 * <replaceable>base-path</replaceable> is the base path of @settings.
34382 * The schema for the child settings object must have been declared
34383 * in the schema of @settings using a <tag class="starttag">child</tag> element.
34385 * Returns: (transfer full): a 'child' settings object
34391 * g_settings_get_double:
34392 * @settings: a #GSettings object
34393 * @key: the key to get the value for
34395 * Gets the value that is stored at @key in @settings.
34397 * A convenience variant of g_settings_get() for doubles.
34399 * It is a programmer error to give a @key that isn't specified as
34400 * having a 'double' type in the schema for @settings.
34402 * Returns: a double
34408 * g_settings_get_enum:
34409 * @settings: a #GSettings object
34410 * @key: the key to get the value for
34412 * Gets the value that is stored in @settings for @key and converts it
34413 * to the enum value that it represents.
34415 * In order to use this function the type of the value must be a string
34416 * and it must be marked in the schema file as an enumerated type.
34418 * It is a programmer error to give a @key that isn't contained in the
34419 * schema for @settings or is not marked as an enumerated type.
34421 * If the value stored in the configuration database is not a valid
34422 * value for the enumerated type then this function will return the
34425 * Returns: the enum value
34431 * g_settings_get_flags:
34432 * @settings: a #GSettings object
34433 * @key: the key to get the value for
34435 * Gets the value that is stored in @settings for @key and converts it
34436 * to the flags value that it represents.
34438 * In order to use this function the type of the value must be an array
34439 * of strings and it must be marked in the schema file as an flags type.
34441 * It is a programmer error to give a @key that isn't contained in the
34442 * schema for @settings or is not marked as a flags type.
34444 * If the value stored in the configuration database is not a valid
34445 * value for the flags type then this function will return the default
34448 * Returns: the flags value
34454 * g_settings_get_has_unapplied:
34455 * @settings: a #GSettings object
34457 * Returns whether the #GSettings object has any unapplied
34458 * changes. This can only be the case if it is in 'delayed-apply' mode.
34460 * Returns: %TRUE if @settings has unapplied changes
34466 * g_settings_get_int:
34467 * @settings: a #GSettings object
34468 * @key: the key to get the value for
34470 * Gets the value that is stored at @key in @settings.
34472 * A convenience variant of g_settings_get() for 32-bit integers.
34474 * It is a programmer error to give a @key that isn't specified as
34475 * having a int32 type in the schema for @settings.
34477 * Returns: an integer
34483 * g_settings_get_mapped:
34484 * @settings: a #GSettings object
34485 * @key: the key to get the value for
34486 * @mapping: (scope call): the function to map the value in the settings database to the value used by the application
34487 * @user_data: user data for @mapping
34489 * Gets the value that is stored at @key in @settings, subject to
34490 * application-level validation/mapping.
34492 * You should use this function when the application needs to perform
34493 * some processing on the value of the key (for example, parsing). The
34494 * @mapping function performs that processing. If the function
34495 * indicates that the processing was unsuccessful (due to a parse error,
34496 * for example) then the mapping is tried again with another value.
34498 * This allows a robust 'fall back to defaults' behaviour to be
34499 * implemented somewhat automatically.
34501 * The first value that is tried is the user's setting for the key. If
34502 * the mapping function fails to map this value, other values may be
34503 * tried in an unspecified order (system or site defaults, translated
34504 * schema default values, untranslated schema default values, etc).
34506 * If the mapping function fails for all possible values, one additional
34507 * attempt is made: the mapping function is called with a %NULL value.
34508 * If the mapping function still indicates failure at this point then
34509 * the application will be aborted.
34511 * The result parameter for the @mapping function is pointed to a
34512 * #gpointer which is initially set to %NULL. The same pointer is given
34513 * to each invocation of @mapping. The final value of that #gpointer is
34514 * what is returned by this function. %NULL is valid; it is returned
34515 * just as any other value would be.
34517 * Returns: (transfer full): the result, which may be %NULL
34522 * g_settings_get_range:
34523 * @settings: a #GSettings
34524 * @key: the key to query the range of
34526 * Queries the range of a key.
34528 * This function will return a #GVariant that fully describes the range
34529 * of values that are valid for @key.
34531 * The type of #GVariant returned is <literal>(sv)</literal>. The
34532 * string describes the type of range restriction in effect. The type
34533 * and meaning of the value contained in the variant depends on the
34536 * If the string is <literal>'type'</literal> then the variant contains
34537 * an empty array. The element type of that empty array is the expected
34538 * type of value and all values of that type are valid.
34540 * If the string is <literal>'enum'</literal> then the variant contains
34541 * an array enumerating the possible values. Each item in the array is
34542 * a possible valid value and no other values are valid.
34544 * If the string is <literal>'flags'</literal> then the variant contains
34545 * an array. Each item in the array is a value that may appear zero or
34546 * one times in an array to be used as the value for this key. For
34547 * example, if the variant contained the array <literal>['x',
34548 * 'y']</literal> then the valid values for the key would be
34549 * <literal>[]</literal>, <literal>['x']</literal>,
34550 * <literal>['y']</literal>, <literal>['x', 'y']</literal> and
34551 * <literal>['y', 'x']</literal>.
34553 * Finally, if the string is <literal>'range'</literal> then the variant
34554 * contains a pair of like-typed values -- the minimum and maximum
34555 * permissible values for this key.
34557 * This information should not be used by normal programs. It is
34558 * considered to be a hint for introspection purposes. Normal programs
34559 * should already know what is permitted by their own schema. The
34560 * format may change in any way in the future -- but particularly, new
34561 * forms may be added to the possibilities described above.
34563 * It is a programmer error to give a @key that isn't contained in the
34564 * schema for @settings.
34566 * You should free the returned value with g_variant_unref() when it is
34567 * no longer needed.
34569 * Returns: a #GVariant describing the range
34575 * g_settings_get_string:
34576 * @settings: a #GSettings object
34577 * @key: the key to get the value for
34579 * Gets the value that is stored at @key in @settings.
34581 * A convenience variant of g_settings_get() for strings.
34583 * It is a programmer error to give a @key that isn't specified as
34584 * having a string type in the schema for @settings.
34586 * Returns: a newly-allocated string
34592 * g_settings_get_strv:
34593 * @settings: a #GSettings object
34594 * @key: the key to get the value for
34596 * A convenience variant of g_settings_get() for string arrays.
34598 * It is a programmer error to give a @key that isn't specified as
34599 * having an array of strings type in the schema for @settings.
34601 * newly-allocated, %NULL-terminated array of strings, the value that
34602 * is stored at @key in @settings.
34604 * Returns: (array zero-terminated=1) (transfer full): a
34610 * g_settings_get_uint:
34611 * @settings: a #GSettings object
34612 * @key: the key to get the value for
34614 * Gets the value that is stored at @key in @settings.
34616 * A convenience variant of g_settings_get() for 32-bit unsigned
34619 * It is a programmer error to give a @key that isn't specified as
34620 * having a uint32 type in the schema for @settings.
34622 * Returns: an unsigned integer
34628 * g_settings_get_value:
34629 * @settings: a #GSettings object
34630 * @key: the key to get the value for
34632 * Gets the value that is stored in @settings for @key.
34634 * It is a programmer error to give a @key that isn't contained in the
34635 * schema for @settings.
34637 * Returns: a new #GVariant
34643 * g_settings_is_writable:
34644 * @settings: a #GSettings object
34645 * @name: the name of a key
34647 * Finds out if a key can be written or not
34649 * Returns: %TRUE if the key @name is writable
34655 * g_settings_list_children:
34656 * @settings: a #GSettings object
34658 * Gets the list of children on @settings.
34660 * The list is exactly the list of strings for which it is not an error
34661 * to call g_settings_get_child().
34663 * For GSettings objects that are lists, this value can change at any
34664 * time and you should connect to the "children-changed" signal to watch
34665 * for those changes. Note that there is a race condition here: you may
34666 * request a child after listing it only for it to have been destroyed
34667 * in the meantime. For this reason, g_settings_get_child() may return
34668 * %NULL even for a child that was listed by this function.
34670 * For GSettings objects that are not lists, you should probably not be
34671 * calling this function from "normal" code (since you should already
34672 * know what children are in your schema). This function may still be
34673 * useful there for introspection reasons, however.
34675 * You should free the return value with g_strfreev() when you are done
34678 * Returns: (transfer full) (element-type utf8): a list of the children on @settings
34683 * g_settings_list_keys:
34684 * @settings: a #GSettings object
34686 * Introspects the list of keys on @settings.
34688 * You should probably not be calling this function from "normal" code
34689 * (since you should already know what keys are in your schema). This
34690 * function is intended for introspection reasons.
34692 * You should free the return value with g_strfreev() when you are done
34695 * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
34700 * g_settings_list_relocatable_schemas:
34702 * Gets a list of the relocatable #GSettings schemas installed on the
34703 * system. These are schemas that do not provide their own path. It is
34704 * usual to instantiate these schemas directly, but if you want to you
34705 * can use g_settings_new_with_path() to specify the path.
34707 * The output of this function, taken together with the output of
34708 * g_settings_list_schemas() represents the complete list of all
34709 * installed schemas.
34711 * #GSettings schemas that are available. The list must not be
34712 * modified or freed.
34714 * Returns: (element-type utf8) (transfer none): a list of relocatable
34720 * g_settings_list_schemas:
34722 * Gets a list of the #GSettings schemas installed on the system. The
34723 * returned list is exactly the list of schemas for which you may call
34724 * g_settings_new() without adverse effects.
34726 * This function does not list the schemas that do not provide their own
34727 * paths (ie: schemas for which you must use
34728 * g_settings_new_with_path()). See
34729 * g_settings_list_relocatable_schemas() for that.
34731 * schemas that are available. The list must not be modified or
34734 * Returns: (element-type utf8) (transfer none): a list of #GSettings
34741 * @schema_id: the id of the schema
34743 * Creates a new #GSettings object with the schema specified by
34746 * Signals on the newly created #GSettings object will be dispatched
34747 * via the thread-default #GMainContext in effect at the time of the
34748 * call to g_settings_new(). The new #GSettings will hold a reference
34749 * on the context. See g_main_context_push_thread_default().
34751 * Returns: a new #GSettings object
34757 * g_settings_new_full:
34758 * @schema: a #GSettingsSchema
34759 * @backend: (allow-none): a #GSettingsBackend
34760 * @path: (allow-none): the path to use
34762 * Creates a new #GSettings object with a given schema, backend and
34765 * It should be extremely rare that you ever want to use this function.
34766 * It is made available for advanced use-cases (such as plugin systems
34767 * that want to provide access to schemas loaded from custom locations,
34770 * At the most basic level, a #GSettings object is a pure composition of
34771 * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that
34772 * backend, and a #GMainContext to which signals are dispatched.
34774 * This constructor therefore gives you full control over constructing
34775 * #GSettings instances. The first 4 parameters are given directly as
34776 * @schema, @backend and @path, and the main context is taken from the
34777 * thread-default (as per g_settings_new()).
34779 * If @backend is %NULL then the default backend is used.
34781 * If @path is %NULL then the path from the schema is used. It is an
34782 * error f @path is %NULL and the schema has no path of its own or if
34783 * @path is non-%NULL and not equal to the path that the schema does
34786 * Returns: a new #GSettings object
34792 * g_settings_new_with_backend:
34793 * @schema_id: the id of the schema
34794 * @backend: the #GSettingsBackend to use
34796 * Creates a new #GSettings object with the schema specified by
34797 * @schema_id and a given #GSettingsBackend.
34799 * Creating a #GSettings object with a different backend allows accessing
34800 * settings from a database other than the usual one. For example, it may make
34801 * sense to pass a backend corresponding to the "defaults" settings database on
34802 * the system to get a settings object that modifies the system default
34803 * settings instead of the settings for this user.
34805 * Returns: a new #GSettings object
34811 * g_settings_new_with_backend_and_path:
34812 * @schema_id: the id of the schema
34813 * @backend: the #GSettingsBackend to use
34814 * @path: the path to use
34816 * Creates a new #GSettings object with the schema specified by
34817 * @schema_id and a given #GSettingsBackend and path.
34819 * This is a mix of g_settings_new_with_backend() and
34820 * g_settings_new_with_path().
34822 * Returns: a new #GSettings object
34828 * g_settings_new_with_path:
34829 * @schema_id: the id of the schema
34830 * @path: the path to use
34832 * Creates a new #GSettings object with the relocatable schema specified
34833 * by @schema_id and a given path.
34835 * You only need to do this if you want to directly create a settings
34836 * object with a schema that doesn't have a specified path of its own.
34837 * That's quite rare.
34839 * It is a programmer error to call this function for a schema that
34840 * has an explicitly specified path.
34842 * Returns: a new #GSettings object
34848 * g_settings_range_check:
34849 * @settings: a #GSettings
34850 * @key: the key to check
34851 * @value: the value to check
34853 * Checks if the given @value is of the correct type and within the
34854 * permitted range for @key.
34856 * This API is not intended to be used by normal programs -- they should
34857 * already know what is permitted by their own schemas. This API is
34858 * meant to be used by programs such as editors or commandline tools.
34860 * It is a programmer error to give a @key that isn't contained in the
34861 * schema for @settings.
34863 * Returns: %TRUE if @value is valid for @key
34869 * g_settings_reset:
34870 * @settings: a #GSettings object
34871 * @key: the name of a key
34873 * Resets @key to its default value.
34875 * This call resets the key, as much as possible, to its default value.
34876 * That might the value specified in the schema or the one set by the
34882 * g_settings_revert:
34883 * @settings: a #GSettings instance
34885 * Reverts all non-applied changes to the settings. This function
34886 * does nothing unless @settings is in 'delay-apply' mode; see
34887 * g_settings_delay(). In the normal case settings are always applied
34890 * Change notifications will be emitted for affected keys.
34895 * g_settings_schema_get_id:
34896 * @schema: a #GSettingsSchema
34898 * Get the ID of @schema.
34900 * Returns: (transfer none): the ID
34905 * g_settings_schema_get_path:
34906 * @schema: a #GSettingsSchema
34908 * Gets the path associated with @schema, or %NULL.
34910 * Schemas may be single-instance or relocatable. Single-instance
34911 * schemas correspond to exactly one set of keys in the backend
34912 * database: those located at the path returned by this function.
34914 * Relocatable schemas can be referenced by other schemas and can
34915 * threfore describe multiple sets of keys at different locations. For
34916 * relocatable schemas, this function will return %NULL.
34918 * Returns: (transfer none): the path of the schema, or %NULL
34924 * g_settings_schema_ref:
34925 * @schema: a #GSettingsSchema
34927 * Increase the reference count of @schema, returning a new reference.
34929 * Returns: a new reference to @schema
34935 * g_settings_schema_source_get_default:
34937 * Gets the default system schema source.
34939 * This function is not required for normal uses of #GSettings but it
34940 * may be useful to authors of plugin management systems or to those who
34941 * want to introspect the content of schemas.
34943 * If no schemas are installed, %NULL will be returned.
34945 * The returned source may actually consist of multiple schema sources
34946 * from different directories, depending on which directories were given
34947 * in <envar>XDG_DATA_DIRS</envar> and
34948 * <envar>GSETTINGS_SCHEMA_DIR</envar>. For this reason, all lookups
34949 * performed against the default source should probably be done
34952 * Returns: (transfer none): the default schema source
34958 * g_settings_schema_source_lookup:
34959 * @source: a #GSettingsSchemaSource
34960 * @schema_id: a schema ID
34961 * @recursive: %TRUE if the lookup should be recursive
34963 * Looks up a schema with the identifier @schema_id in @source.
34965 * This function is not required for normal uses of #GSettings but it
34966 * may be useful to authors of plugin management systems or to those who
34967 * want to introspect the content of schemas.
34969 * If the schema isn't found directly in @source and @recursive is %TRUE
34970 * then the parent sources will also be checked.
34972 * If the schema isn't found, %NULL is returned.
34974 * Returns: (transfer full): a new #GSettingsSchema
34980 * g_settings_schema_source_new_from_directory:
34981 * @directory: the filename of a directory
34982 * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
34983 * @trusted: %TRUE, if the directory is trusted
34984 * @error: a pointer to a #GError pointer set to %NULL, or %NULL
34986 * Attempts to create a new schema source corresponding to the contents
34987 * of the given directory.
34989 * This function is not required for normal uses of #GSettings but it
34990 * may be useful to authors of plugin management systems.
34992 * The directory should contain a file called
34993 * <filename>gschemas.compiled</filename> as produced by
34994 * <command>glib-compile-schemas</command>.
34996 * If @trusted is %TRUE then <filename>gschemas.compiled</filename> is
34997 * trusted not to be corrupted. This assumption has a performance
34998 * advantage, but can result in crashes or inconsistent behaviour in the
34999 * case of a corrupted file. Generally, you should set @trusted to
35000 * %TRUE for files installed by the system and to %FALSE for files in
35001 * the home directory.
35003 * If @parent is non-%NULL then there are two effects.
35005 * First, if g_settings_schema_source_lookup() is called with the
35006 * @recursive flag set to %TRUE and the schema can not be found in the
35007 * source, the lookup will recurse to the parent.
35009 * Second, any references to other schemas specified within this
35010 * source (ie: <literal>child</literal> or <literal>extents</literal>)
35011 * references may be resolved from the @parent.
35013 * For this second reason, except in very unusual situations, the
35014 * @parent should probably be given as the default schema source, as
35015 * returned by g_settings_schema_source_get_default().
35022 * g_settings_schema_source_ref:
35023 * @source: a #GSettingsSchemaSource
35025 * Increase the reference count of @source, returning a new reference.
35027 * Returns: a new reference to @source
35033 * g_settings_schema_source_unref:
35034 * @source: a #GSettingsSchemaSource
35036 * Decrease the reference count of @source, possibly freeing it.
35043 * g_settings_schema_unref:
35044 * @schema: a #GSettingsSchema
35046 * Decrease the reference count of @schema, possibly freeing it.
35054 * @settings: a #GSettings object
35055 * @key: the name of the key to set
35056 * @format: a #GVariant format string
35057 * @...: arguments as per @format
35059 * Sets @key in @settings to @value.
35061 * A convenience function that combines g_settings_set_value() with
35064 * It is a programmer error to give a @key that isn't contained in the
35065 * schema for @settings or for the #GVariantType of @format to mismatch
35066 * the type given in the schema.
35068 * %FALSE if the key was not writable
35070 * Returns: %TRUE if setting the key succeeded,
35076 * g_settings_set_boolean:
35077 * @settings: a #GSettings object
35078 * @key: the name of the key to set
35079 * @value: the value to set it to
35081 * Sets @key in @settings to @value.
35083 * A convenience variant of g_settings_set() for booleans.
35085 * It is a programmer error to give a @key that isn't specified as
35086 * having a boolean type in the schema for @settings.
35088 * %FALSE if the key was not writable
35090 * Returns: %TRUE if setting the key succeeded,
35096 * g_settings_set_double:
35097 * @settings: a #GSettings object
35098 * @key: the name of the key to set
35099 * @value: the value to set it to
35101 * Sets @key in @settings to @value.
35103 * A convenience variant of g_settings_set() for doubles.
35105 * It is a programmer error to give a @key that isn't specified as
35106 * having a 'double' type in the schema for @settings.
35108 * %FALSE if the key was not writable
35110 * Returns: %TRUE if setting the key succeeded,
35116 * g_settings_set_enum:
35117 * @settings: a #GSettings object
35118 * @key: a key, within @settings
35119 * @value: an enumerated value
35121 * Looks up the enumerated type nick for @value and writes it to @key,
35122 * within @settings.
35124 * It is a programmer error to give a @key that isn't contained in the
35125 * schema for @settings or is not marked as an enumerated type, or for
35126 * @value not to be a valid value for the named type.
35128 * After performing the write, accessing @key directly with
35129 * g_settings_get_string() will return the 'nick' associated with
35132 * Returns: %TRUE, if the set succeeds
35137 * g_settings_set_flags:
35138 * @settings: a #GSettings object
35139 * @key: a key, within @settings
35140 * @value: a flags value
35142 * Looks up the flags type nicks for the bits specified by @value, puts
35143 * them in an array of strings and writes the array to @key, within
35146 * It is a programmer error to give a @key that isn't contained in the
35147 * schema for @settings or is not marked as a flags type, or for @value
35148 * to contain any bits that are not value for the named type.
35150 * After performing the write, accessing @key directly with
35151 * g_settings_get_strv() will return an array of 'nicks'; one for each
35154 * Returns: %TRUE, if the set succeeds
35159 * g_settings_set_int:
35160 * @settings: a #GSettings object
35161 * @key: the name of the key to set
35162 * @value: the value to set it to
35164 * Sets @key in @settings to @value.
35166 * A convenience variant of g_settings_set() for 32-bit integers.
35168 * It is a programmer error to give a @key that isn't specified as
35169 * having a int32 type in the schema for @settings.
35171 * %FALSE if the key was not writable
35173 * Returns: %TRUE if setting the key succeeded,
35179 * g_settings_set_string:
35180 * @settings: a #GSettings object
35181 * @key: the name of the key to set
35182 * @value: the value to set it to
35184 * Sets @key in @settings to @value.
35186 * A convenience variant of g_settings_set() for strings.
35188 * It is a programmer error to give a @key that isn't specified as
35189 * having a string type in the schema for @settings.
35191 * %FALSE if the key was not writable
35193 * Returns: %TRUE if setting the key succeeded,
35199 * g_settings_set_strv:
35200 * @settings: a #GSettings object
35201 * @key: the name of the key to set
35202 * @value: (allow-none) (array zero-terminated=1): the value to set it to, or %NULL
35204 * Sets @key in @settings to @value.
35206 * A convenience variant of g_settings_set() for string arrays. If
35207 * @value is %NULL, then @key is set to be the empty array.
35209 * It is a programmer error to give a @key that isn't specified as
35210 * having an array of strings type in the schema for @settings.
35212 * %FALSE if the key was not writable
35214 * Returns: %TRUE if setting the key succeeded,
35220 * g_settings_set_uint:
35221 * @settings: a #GSettings object
35222 * @key: the name of the key to set
35223 * @value: the value to set it to
35225 * Sets @key in @settings to @value.
35227 * A convenience variant of g_settings_set() for 32-bit unsigned
35230 * It is a programmer error to give a @key that isn't specified as
35231 * having a uint32 type in the schema for @settings.
35233 * %FALSE if the key was not writable
35235 * Returns: %TRUE if setting the key succeeded,
35241 * g_settings_set_value:
35242 * @settings: a #GSettings object
35243 * @key: the name of the key to set
35244 * @value: a #GVariant of the correct type
35246 * Sets @key in @settings to @value.
35248 * It is a programmer error to give a @key that isn't contained in the
35249 * schema for @settings or for @value to have the incorrect type, per
35252 * If @value is floating then this function consumes the reference.
35254 * %FALSE if the key was not writable
35256 * Returns: %TRUE if setting the key succeeded,
35264 * Ensures that all pending operations for the given are complete for
35265 * the default backend.
35267 * Writes made to a #GSettings are handled asynchronously. For this
35268 * reason, it is very unlikely that the changes have it to disk by the
35269 * time g_settings_set() returns.
35271 * This call will block until all of the writes have made it to the
35272 * backend. Since the mainloop is not running, no change notifications
35273 * will be dispatched during this call (but some may be queued by the
35274 * time the call is done).
35279 * g_settings_unbind:
35280 * @object: the object
35281 * @property: the property whose binding is removed
35283 * Removes an existing binding for @property on @object.
35285 * Note that bindings are automatically removed when the
35286 * object is finalized, so it is rarely necessary to call this
35294 * g_signal_connect:
35295 * @instance: the instance to connect to.
35296 * @detailed_signal: a string of the form "signal-name::detail".
35297 * @c_handler: the #GCallback to connect.
35298 * @data: data to pass to @c_handler calls.
35300 * Connects a #GCallback function to a signal for a particular object.
35302 * The handler will be called before the default handler of the signal.
35304 * Returns: the handler id
35309 * g_signal_connect_after:
35310 * @instance: the instance to connect to.
35311 * @detailed_signal: a string of the form "signal-name::detail".
35312 * @c_handler: the #GCallback to connect.
35313 * @data: data to pass to @c_handler calls.
35315 * Connects a #GCallback function to a signal for a particular object.
35317 * The handler will be called after the default handler of the signal.
35319 * Returns: the handler id
35324 * g_signal_connect_swapped:
35325 * @instance: the instance to connect to.
35326 * @detailed_signal: a string of the form "signal-name::detail".
35327 * @c_handler: the #GCallback to connect.
35328 * @data: data to pass to @c_handler calls.
35330 * Connects a #GCallback function to a signal for a particular object.
35332 * The instance on which the signal is emitted and @data will be swapped when
35333 * calling the handler.
35335 * Returns: the handler id
35340 * g_signal_handlers_block_by_func:
35341 * @instance: The instance to block handlers from.
35342 * @func: The C closure callback of the handlers (useless for non-C closures).
35343 * @data: The closure data of the handlers' closures.
35345 * Blocks all handlers on an instance that match @func and @data.
35347 * Returns: The number of handlers that matched.
35352 * g_signal_handlers_disconnect_by_data:
35353 * @instance: The instance to remove handlers from
35354 * @data: the closure data of the handlers' closures
35356 * Disconnects all handlers on an instance that match @data.
35358 * Returns: The number of handlers that matched.
35364 * g_signal_handlers_disconnect_by_func:
35365 * @instance: The instance to remove handlers from.
35366 * @func: The C closure callback of the handlers (useless for non-C closures).
35367 * @data: The closure data of the handlers' closures.
35369 * Disconnects all handlers on an instance that match @func and @data.
35371 * Returns: The number of handlers that matched.
35376 * g_signal_handlers_unblock_by_func:
35377 * @instance: The instance to unblock handlers from.
35378 * @func: The C closure callback of the handlers (useless for non-C closures).
35379 * @data: The closure data of the handlers' closures.
35381 * Unblocks all handlers on an instance that match @func and @data.
35383 * Returns: The number of handlers that matched.
35388 * g_simple_action_group_add_entries:
35389 * @simple: a #GSimpleActionGroup
35390 * @entries: (array length=n_entries): a pointer to the first item in an array of #GActionEntry structs
35391 * @n_entries: the length of @entries, or -1
35392 * @user_data: the user data for signal connections
35394 * A convenience function for creating multiple #GSimpleAction instances
35395 * and adding them to the action group.
35402 * g_simple_action_group_insert:
35403 * @simple: a #GSimpleActionGroup
35404 * @action: a #GAction
35406 * Adds an action to the action group.
35408 * If the action group already contains an action with the same name as
35409 * @action then the old action is dropped from the group.
35411 * The action group takes its own reference on @action.
35418 * g_simple_action_group_lookup:
35419 * @simple: a #GSimpleActionGroup
35420 * @action_name: the name of an action
35422 * Looks up the action with the name @action_name in the group.
35424 * If no such action exists, returns %NULL.
35426 * Returns: (transfer none): a #GAction, or %NULL
35432 * g_simple_action_group_new:
35434 * Creates a new, empty, #GSimpleActionGroup.
35436 * Returns: a new #GSimpleActionGroup
35442 * g_simple_action_group_remove:
35443 * @simple: a #GSimpleActionGroup
35444 * @action_name: the name of the action
35446 * Removes the named action from the action group.
35448 * If no action of this name is in the group then nothing happens.
35455 * g_simple_action_new:
35456 * @name: the name of the action
35457 * @parameter_type: (allow-none): the type of parameter to the activate function
35459 * Creates a new action.
35461 * The created action is stateless. See g_simple_action_new_stateful().
35463 * Returns: a new #GSimpleAction
35469 * g_simple_action_new_stateful:
35470 * @name: the name of the action
35471 * @parameter_type: (allow-none): the type of the parameter to the activate function
35472 * @state: the initial state of the action
35474 * Creates a new stateful action.
35476 * @state is the initial state of the action. All future state values
35477 * must have the same #GVariantType as the initial state.
35479 * If the @state GVariant is floating, it is consumed.
35481 * Returns: a new #GSimpleAction
35487 * g_simple_action_set_enabled:
35488 * @simple: a #GSimpleAction
35489 * @enabled: whether the action is enabled
35491 * Sets the action as enabled or not.
35493 * An action must be enabled in order to be activated or in order to
35494 * have its state changed from outside callers.
35496 * This should only be called by the implementor of the action. Users
35497 * of the action should not attempt to modify its enabled flag.
35504 * g_simple_action_set_state:
35505 * @simple: a #GSimpleAction
35506 * @value: the new #GVariant for the state
35508 * Sets the state of the action.
35510 * This directly updates the 'state' property to the given value.
35512 * This should only be called by the implementor of the action. Users
35513 * of the action should not attempt to directly modify the 'state'
35514 * property. Instead, they should call g_action_change_state() to
35515 * request the change.
35522 * g_simple_async_report_error_in_idle: (skip)
35523 * @object: (allow-none): a #GObject, or %NULL.
35524 * @callback: a #GAsyncReadyCallback.
35525 * @user_data: user data passed to @callback.
35526 * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
35527 * @code: a specific error code.
35528 * @format: a formatted error reporting string.
35529 * @...: a list of variables to fill in @format.
35531 * Reports an error in an asynchronous function in an idle function by
35532 * directly setting the contents of the #GAsyncResult with the given error
35538 * g_simple_async_report_gerror_in_idle:
35539 * @object: (allow-none): a #GObject, or %NULL
35540 * @callback: (scope async): a #GAsyncReadyCallback.
35541 * @user_data: (closure): user data passed to @callback.
35542 * @error: the #GError to report
35544 * Reports an error in an idle function. Similar to
35545 * g_simple_async_report_error_in_idle(), but takes a #GError rather
35546 * than building a new one.
35551 * g_simple_async_report_take_gerror_in_idle: (skip)
35552 * @object: (allow-none): a #GObject, or %NULL
35553 * @callback: a #GAsyncReadyCallback.
35554 * @user_data: user data passed to @callback.
35555 * @error: the #GError to report
35557 * Reports an error in an idle function. Similar to
35558 * g_simple_async_report_gerror_in_idle(), but takes over the caller's
35559 * ownership of @error, so the caller does not have to free it any more.
35566 * g_simple_async_result_complete:
35567 * @simple: a #GSimpleAsyncResult.
35569 * Completes an asynchronous I/O job immediately. Must be called in
35570 * the thread where the asynchronous result was to be delivered, as it
35571 * invokes the callback directly. If you are in a different thread use
35572 * g_simple_async_result_complete_in_idle().
35574 * Calling this function takes a reference to @simple for as long as
35575 * is needed to complete the call.
35580 * g_simple_async_result_complete_in_idle:
35581 * @simple: a #GSimpleAsyncResult.
35583 * Completes an asynchronous function in an idle handler in the <link
35584 * linkend="g-main-context-push-thread-default">thread-default main
35585 * loop</link> of the thread that @simple was initially created in
35586 * (and re-pushes that context around the invocation of the callback).
35588 * Calling this function takes a reference to @simple for as long as
35589 * is needed to complete the call.
35594 * g_simple_async_result_get_op_res_gboolean:
35595 * @simple: a #GSimpleAsyncResult.
35597 * Gets the operation result boolean from within the asynchronous result.
35599 * if the operation's result was %FALSE.
35601 * Returns: %TRUE if the operation's result was %TRUE, %FALSE
35606 * g_simple_async_result_get_op_res_gpointer: (skip)
35607 * @simple: a #GSimpleAsyncResult.
35609 * Gets a pointer result as returned by the asynchronous function.
35611 * Returns: a pointer from the result.
35616 * g_simple_async_result_get_op_res_gssize:
35617 * @simple: a #GSimpleAsyncResult.
35619 * Gets a gssize from the asynchronous result.
35621 * Returns: a gssize returned from the asynchronous function.
35626 * g_simple_async_result_get_source_tag: (skip)
35627 * @simple: a #GSimpleAsyncResult.
35629 * Gets the source tag for the #GSimpleAsyncResult.
35631 * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
35636 * g_simple_async_result_is_valid:
35637 * @result: the #GAsyncResult passed to the _finish function.
35638 * @source: the #GObject passed to the _finish function.
35639 * @source_tag: the asynchronous function.
35641 * Ensures that the data passed to the _finish function of an async
35642 * operation is consistent. Three checks are performed.
35644 * First, @result is checked to ensure that it is really a
35645 * #GSimpleAsyncResult. Second, @source is checked to ensure that it
35646 * matches the source object of @result. Third, @source_tag is
35647 * checked to ensure that it is either %NULL (as it is when the result was
35648 * created by g_simple_async_report_error_in_idle() or
35649 * g_simple_async_report_gerror_in_idle()) or equal to the
35650 * @source_tag argument given to g_simple_async_result_new() (which, by
35651 * convention, is a pointer to the _async function corresponding to the
35652 * _finish function from which this function is called).
35654 * Returns: #TRUE if all checks passed or #FALSE if any failed.
35660 * g_simple_async_result_new:
35661 * @source_object: (allow-none): a #GObject, or %NULL.
35662 * @callback: (scope async): a #GAsyncReadyCallback.
35663 * @user_data: (closure): user data passed to @callback.
35664 * @source_tag: the asynchronous function.
35666 * Creates a #GSimpleAsyncResult.
35668 * The common convention is to create the #GSimpleAsyncResult in the
35669 * function that starts the asynchronous operation and use that same
35670 * function as the @source_tag.
35672 * If your operation supports cancellation with #GCancellable (which it
35673 * probably should) then you should provide the user's cancellable to
35674 * g_simple_async_result_set_check_cancellable() immediately after
35675 * this function returns.
35677 * Returns: a #GSimpleAsyncResult.
35682 * g_simple_async_result_new_error:
35683 * @source_object: (allow-none): a #GObject, or %NULL.
35684 * @callback: (scope async): a #GAsyncReadyCallback.
35685 * @user_data: (closure): user data passed to @callback.
35686 * @domain: a #GQuark.
35687 * @code: an error code.
35688 * @format: a string with format characters.
35689 * @...: a list of values to insert into @format.
35691 * Creates a new #GSimpleAsyncResult with a set error.
35693 * Returns: a #GSimpleAsyncResult.
35698 * g_simple_async_result_new_from_error:
35699 * @source_object: (allow-none): a #GObject, or %NULL.
35700 * @callback: (scope async): a #GAsyncReadyCallback.
35701 * @user_data: (closure): user data passed to @callback.
35702 * @error: a #GError
35704 * Creates a #GSimpleAsyncResult from an error condition.
35706 * Returns: a #GSimpleAsyncResult.
35711 * g_simple_async_result_new_take_error: (skip)
35712 * @source_object: (allow-none): a #GObject, or %NULL
35713 * @callback: (scope async): a #GAsyncReadyCallback
35714 * @user_data: (closure): user data passed to @callback
35715 * @error: a #GError
35717 * Creates a #GSimpleAsyncResult from an error condition, and takes over the
35718 * caller's ownership of @error, so the caller does not need to free it anymore.
35720 * Returns: a #GSimpleAsyncResult
35726 * g_simple_async_result_propagate_error:
35727 * @simple: a #GSimpleAsyncResult.
35728 * @dest: (out): a location to propagate the error to.
35730 * Propagates an error from within the simple asynchronous result to
35731 * a given destination.
35733 * If the #GCancellable given to a prior call to
35734 * g_simple_async_result_set_check_cancellable() is cancelled then this
35735 * function will return %TRUE with @dest set appropriately.
35737 * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise.
35742 * g_simple_async_result_run_in_thread: (skip)
35743 * @simple: a #GSimpleAsyncResult.
35744 * @func: a #GSimpleAsyncThreadFunc.
35745 * @io_priority: the io priority of the request.
35746 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
35748 * Runs the asynchronous job in a separate thread and then calls
35749 * g_simple_async_result_complete_in_idle() on @simple to return
35750 * the result to the appropriate main loop.
35752 * Calling this function takes a reference to @simple for as long as
35753 * is needed to run the job and report its completion.
35758 * g_simple_async_result_set_check_cancellable:
35759 * @simple: a #GSimpleAsyncResult
35760 * @check_cancellable: a #GCancellable to check, or %NULL to unset
35762 * Sets a #GCancellable to check before dispatching results.
35764 * This function has one very specific purpose: the provided cancellable
35765 * is checked at the time of g_simple_async_result_propagate_error() If
35766 * it is cancelled, these functions will return an "Operation was
35767 * cancelled" error (%G_IO_ERROR_CANCELLED).
35769 * Implementors of cancellable asynchronous functions should use this in
35770 * order to provide a guarantee to their callers that cancelling an
35771 * async operation will reliably result in an error being returned for
35772 * that operation (even if a positive result for the operation has
35773 * already been sent as an idle to the main context to be dispatched).
35775 * The checking described above is done regardless of any call to the
35776 * unrelated g_simple_async_result_set_handle_cancellation() function.
35783 * g_simple_async_result_set_error: (skip)
35784 * @simple: a #GSimpleAsyncResult.
35785 * @domain: a #GQuark (usually #G_IO_ERROR).
35786 * @code: an error code.
35787 * @format: a formatted error reporting string.
35788 * @...: a list of variables to fill in @format.
35790 * Sets an error within the asynchronous result without a #GError.
35795 * g_simple_async_result_set_error_va: (skip)
35796 * @simple: a #GSimpleAsyncResult.
35797 * @domain: a #GQuark (usually #G_IO_ERROR).
35798 * @code: an error code.
35799 * @format: a formatted error reporting string.
35800 * @args: va_list of arguments.
35802 * Sets an error within the asynchronous result without a #GError.
35803 * Unless writing a binding, see g_simple_async_result_set_error().
35808 * g_simple_async_result_set_from_error:
35809 * @simple: a #GSimpleAsyncResult.
35812 * Sets the result from a #GError.
35817 * g_simple_async_result_set_handle_cancellation:
35818 * @simple: a #GSimpleAsyncResult.
35819 * @handle_cancellation: a #gboolean.
35821 * Sets whether to handle cancellation within the asynchronous operation.
35823 * This function has nothing to do with
35824 * g_simple_async_result_set_check_cancellable(). It only refers to the
35825 * #GCancellable passed to g_simple_async_result_run_in_thread().
35830 * g_simple_async_result_set_op_res_gboolean:
35831 * @simple: a #GSimpleAsyncResult.
35832 * @op_res: a #gboolean.
35834 * Sets the operation result to a boolean within the asynchronous result.
35839 * g_simple_async_result_set_op_res_gpointer: (skip)
35840 * @simple: a #GSimpleAsyncResult.
35841 * @op_res: a pointer result from an asynchronous function.
35842 * @destroy_op_res: a #GDestroyNotify function.
35844 * Sets the operation result within the asynchronous result to a pointer.
35849 * g_simple_async_result_set_op_res_gssize:
35850 * @simple: a #GSimpleAsyncResult.
35851 * @op_res: a #gssize.
35853 * Sets the operation result within the asynchronous result to
35854 * the given @op_res.
35859 * g_simple_async_result_take_error: (skip)
35860 * @simple: a #GSimpleAsyncResult
35861 * @error: a #GError
35863 * Sets the result from @error, and takes over the caller's ownership
35864 * of @error, so the caller does not need to free it any more.
35871 * g_simple_permission_new:
35872 * @allowed: %TRUE if the action is allowed
35874 * Creates a new #GPermission instance that represents an action that is
35875 * either always or never allowed.
35877 * Returns: the #GSimplePermission, as a #GPermission
35884 * @socket: a #GSocket.
35885 * @cancellable: (allow-none): a %GCancellable or %NULL
35886 * @error: #GError for error reporting, or %NULL to ignore.
35888 * Accept incoming connections on a connection-based socket. This removes
35889 * the first outstanding connection request from the listening socket and
35890 * creates a #GSocket object for it.
35892 * The @socket must be bound to a local address with g_socket_bind() and
35893 * must be listening for incoming connections (g_socket_listen()).
35895 * If there are no outstanding connections then the operation will block
35896 * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
35897 * To be notified of an incoming connection, wait for the %G_IO_IN condition.
35899 * Free the returned object with g_object_unref().
35901 * Returns: (transfer full): a new #GSocket, or %NULL on error.
35907 * g_socket_address_enumerator_next:
35908 * @enumerator: a #GSocketAddressEnumerator
35909 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
35910 * @error: a #GError.
35912 * Retrieves the next #GSocketAddress from @enumerator. Note that this
35913 * may block for some amount of time. (Eg, a #GNetworkAddress may need
35914 * to do a DNS lookup before it can return an address.) Use
35915 * g_socket_address_enumerator_next_async() if you need to avoid
35918 * If @enumerator is expected to yield addresses, but for some reason
35919 * is unable to (eg, because of a DNS error), then the first call to
35920 * g_socket_address_enumerator_next() will return an appropriate error
35921 * in *@error. However, if the first call to
35922 * g_socket_address_enumerator_next() succeeds, then any further
35923 * internal errors (other than @cancellable being triggered) will be
35926 * error (in which case *@error will be set) or if there are no
35929 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
35934 * g_socket_address_enumerator_next_async:
35935 * @enumerator: a #GSocketAddressEnumerator
35936 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
35937 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
35938 * @user_data: (closure): the data to pass to callback function
35940 * Asynchronously retrieves the next #GSocketAddress from @enumerator
35941 * and then calls @callback, which must call
35942 * g_socket_address_enumerator_next_finish() to get the result.
35947 * g_socket_address_enumerator_next_finish:
35948 * @enumerator: a #GSocketAddressEnumerator
35949 * @result: a #GAsyncResult
35950 * @error: a #GError
35952 * Retrieves the result of a completed call to
35953 * g_socket_address_enumerator_next_async(). See
35954 * g_socket_address_enumerator_next() for more information about
35957 * error (in which case *@error will be set) or if there are no
35960 * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
35965 * g_socket_address_get_family:
35966 * @address: a #GSocketAddress
35968 * Gets the socket family type of @address.
35970 * Returns: the socket family type of @address.
35976 * g_socket_address_get_native_size:
35977 * @address: a #GSocketAddress
35979 * Gets the size of @address's native <type>struct sockaddr</type>.
35980 * You can use this to allocate memory to pass to
35981 * g_socket_address_to_native().
35983 * @address represents
35985 * Returns: the size of the native <type>struct sockaddr</type> that
35991 * g_socket_address_new_from_native:
35992 * @native: a pointer to a <type>struct sockaddr</type>
35993 * @len: the size of the memory location pointed to by @native
35995 * Creates a #GSocketAddress subclass corresponding to the native
35996 * <type>struct sockaddr</type> @native.
36000 * Returns: a new #GSocketAddress if @native could successfully be converted,
36006 * g_socket_address_to_native:
36007 * @address: a #GSocketAddress
36008 * @dest: a pointer to a memory location that will contain the native <type>struct sockaddr</type>.
36009 * @destlen: the size of @dest. Must be at least as large as g_socket_address_get_native_size().
36010 * @error: #GError for error reporting, or %NULL to ignore.
36012 * Converts a #GSocketAddress to a native <type>struct
36013 * sockaddr</type>, which can be passed to low-level functions like
36014 * connect() or bind().
36016 * If not enough space is available, a %G_IO_ERROR_NO_SPACE error is
36017 * returned. If the address type is not known on the system
36018 * then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
36020 * Returns: %TRUE if @dest was filled in, %FALSE on error
36027 * @socket: a #GSocket.
36028 * @address: a #GSocketAddress specifying the local address.
36029 * @allow_reuse: whether to allow reusing this address
36030 * @error: #GError for error reporting, or %NULL to ignore.
36032 * When a socket is created it is attached to an address family, but it
36033 * doesn't have an address in this family. g_socket_bind() assigns the
36034 * address (sometimes called name) of the socket.
36036 * It is generally required to bind to a local address before you can
36037 * receive connections. (See g_socket_listen() and g_socket_accept() ).
36038 * In certain situations, you may also want to bind a socket that will be
36039 * used to initiate connections, though this is not normally required.
36041 * @allow_reuse should be %TRUE for server sockets (sockets that you will
36042 * eventually call g_socket_accept() on), and %FALSE for client sockets.
36043 * (Specifically, if it is %TRUE, then g_socket_bind() will set the
36044 * %SO_REUSEADDR flag on the socket, allowing it to bind @address even if
36045 * that address was previously used by another socket that has not yet been
36046 * fully cleaned-up by the kernel. Failing to set this flag on a server
36047 * socket may cause the bind call to return %G_IO_ERROR_ADDRESS_IN_USE if
36048 * the server program is stopped and then immediately restarted.)
36050 * Returns: %TRUE on success, %FALSE on error.
36056 * g_socket_check_connect_result:
36057 * @socket: a #GSocket
36058 * @error: #GError for error reporting, or %NULL to ignore.
36060 * Checks and resets the pending connect error for the socket.
36061 * This is used to check for errors when g_socket_connect() is
36062 * used in non-blocking mode.
36064 * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error
36070 * g_socket_client_add_application_proxy:
36071 * @client: a #GSocketClient
36072 * @protocol: The proxy protocol
36074 * Enable proxy protocols to be handled by the application. When the
36075 * indicated proxy protocol is returned by the #GProxyResolver,
36076 * #GSocketClient will consider this protocol as supported but will
36077 * not try to find a #GProxy instance to handle handshaking. The
36078 * application must check for this case by calling
36079 * g_socket_connection_get_remote_address() on the returned
36080 * #GSocketConnection, and seeing if it's a #GProxyAddress of the
36081 * appropriate type, to determine whether or not it needs to handle
36082 * the proxy handshaking itself.
36084 * This should be used for proxy protocols that are dialects of
36085 * another protocol such as HTTP proxy. It also allows cohabitation of
36086 * proxy protocols that are reused between protocols. A good example
36087 * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also
36088 * be use as generic socket proxy through the HTTP CONNECT method.
36090 * When the proxy is detected as being an application proxy, TLS handshake
36091 * will be skipped. This is required to let the application do the proxy
36092 * specific handshake.
36097 * g_socket_client_connect:
36098 * @client: a #GSocketClient.
36099 * @connectable: a #GSocketConnectable specifying the remote address.
36100 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
36101 * @error: #GError for error reporting, or %NULL to ignore.
36103 * Tries to resolve the @connectable and make a network connection to it.
36105 * Upon a successful connection, a new #GSocketConnection is constructed
36106 * and returned. The caller owns this new object and must drop their
36107 * reference to it when finished with it.
36109 * The type of the #GSocketConnection object returned depends on the type of
36110 * the underlying socket that is used. For instance, for a TCP/IP connection
36111 * it will be a #GTcpConnection.
36113 * The socket created will be the same family as the address that the
36114 * @connectable resolves to, unless family is set with g_socket_client_set_family()
36115 * or indirectly via g_socket_client_set_local_address(). The socket type
36116 * defaults to %G_SOCKET_TYPE_STREAM but can be set with
36117 * g_socket_client_set_socket_type().
36119 * If a local address is specified with g_socket_client_set_local_address() the
36120 * socket will be bound to this address before connecting.
36122 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36128 * g_socket_client_connect_async:
36129 * @client: a #GSocketClient
36130 * @connectable: a #GSocketConnectable specifying the remote address.
36131 * @cancellable: (allow-none): a #GCancellable, or %NULL
36132 * @callback: (scope async): a #GAsyncReadyCallback
36133 * @user_data: (closure): user data for the callback
36135 * This is the asynchronous version of g_socket_client_connect().
36137 * When the operation is finished @callback will be
36138 * called. You can then call g_socket_client_connect_finish() to get
36139 * the result of the operation.
36146 * g_socket_client_connect_finish:
36147 * @client: a #GSocketClient.
36148 * @result: a #GAsyncResult.
36149 * @error: a #GError location to store the error occurring, or %NULL to ignore.
36151 * Finishes an async connect operation. See g_socket_client_connect_async()
36153 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36159 * g_socket_client_connect_to_host:
36160 * @client: a #GSocketClient
36161 * @host_and_port: the name and optionally port of the host to connect to
36162 * @default_port: the default port to connect to
36163 * @cancellable: (allow-none): a #GCancellable, or %NULL
36164 * @error: a pointer to a #GError, or %NULL
36166 * This is a helper function for g_socket_client_connect().
36168 * Attempts to create a TCP connection to the named host.
36170 * @host_and_port may be in any of a number of recognized formats; an IPv6
36171 * address, an IPv4 address, or a domain name (in which case a DNS
36172 * lookup is performed). Quoting with [] is supported for all address
36173 * types. A port override may be specified in the usual way with a
36174 * colon. Ports may be given as decimal numbers or symbolic names (in
36175 * which case an /etc/services lookup is performed).
36177 * If no port override is given in @host_and_port then @default_port will be
36178 * used as the port number to connect to.
36180 * In general, @host_and_port is expected to be provided by the user (allowing
36181 * them to give the hostname, and a port override if necessary) and
36182 * @default_port is expected to be provided by the application.
36184 * In the case that an IP address is given, a single connection
36185 * attempt is made. In the case that a name is given, multiple
36186 * connection attempts may be made, in turn and according to the
36187 * number of address records in DNS, until a connection succeeds.
36189 * Upon a successful connection, a new #GSocketConnection is constructed
36190 * and returned. The caller owns this new object and must drop their
36191 * reference to it when finished with it.
36193 * In the event of any failure (DNS error, service not found, no hosts
36194 * connectable) %NULL is returned and @error (if non-%NULL) is set
36197 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36203 * g_socket_client_connect_to_host_async:
36204 * @client: a #GSocketClient
36205 * @host_and_port: the name and optionally the port of the host to connect to
36206 * @default_port: the default port to connect to
36207 * @cancellable: (allow-none): a #GCancellable, or %NULL
36208 * @callback: (scope async): a #GAsyncReadyCallback
36209 * @user_data: (closure): user data for the callback
36211 * This is the asynchronous version of g_socket_client_connect_to_host().
36213 * When the operation is finished @callback will be
36214 * called. You can then call g_socket_client_connect_to_host_finish() to get
36215 * the result of the operation.
36222 * g_socket_client_connect_to_host_finish:
36223 * @client: a #GSocketClient.
36224 * @result: a #GAsyncResult.
36225 * @error: a #GError location to store the error occurring, or %NULL to ignore.
36227 * Finishes an async connect operation. See g_socket_client_connect_to_host_async()
36229 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36235 * g_socket_client_connect_to_service:
36236 * @client: a #GSocketConnection
36237 * @domain: a domain name
36238 * @service: the name of the service to connect to
36239 * @cancellable: (allow-none): a #GCancellable, or %NULL
36240 * @error: a pointer to a #GError, or %NULL
36242 * Attempts to create a TCP connection to a service.
36244 * This call looks up the SRV record for @service at @domain for the
36245 * "tcp" protocol. It then attempts to connect, in turn, to each of
36246 * the hosts providing the service until either a connection succeeds
36247 * or there are no hosts remaining.
36249 * Upon a successful connection, a new #GSocketConnection is constructed
36250 * and returned. The caller owns this new object and must drop their
36251 * reference to it when finished with it.
36253 * In the event of any failure (DNS error, service not found, no hosts
36254 * connectable) %NULL is returned and @error (if non-%NULL) is set
36257 * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error
36262 * g_socket_client_connect_to_service_async:
36263 * @client: a #GSocketClient
36264 * @domain: a domain name
36265 * @service: the name of the service to connect to
36266 * @cancellable: (allow-none): a #GCancellable, or %NULL
36267 * @callback: (scope async): a #GAsyncReadyCallback
36268 * @user_data: (closure): user data for the callback
36270 * This is the asynchronous version of
36271 * g_socket_client_connect_to_service().
36278 * g_socket_client_connect_to_service_finish:
36279 * @client: a #GSocketClient.
36280 * @result: a #GAsyncResult.
36281 * @error: a #GError location to store the error occurring, or %NULL to ignore.
36283 * Finishes an async connect operation. See g_socket_client_connect_to_service_async()
36285 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36291 * g_socket_client_connect_to_uri:
36292 * @client: a #GSocketClient
36293 * @uri: A network URI
36294 * @default_port: the default port to connect to
36295 * @cancellable: (allow-none): a #GCancellable, or %NULL
36296 * @error: a pointer to a #GError, or %NULL
36298 * This is a helper function for g_socket_client_connect().
36300 * Attempts to create a TCP connection with a network URI.
36302 * @uri may be any valid URI containing an "authority" (hostname/port)
36303 * component. If a port is not specified in the URI, @default_port
36304 * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE.
36305 * (#GSocketClient does not know to automatically assume TLS for
36306 * certain URI schemes.)
36308 * Using this rather than g_socket_client_connect() or
36309 * g_socket_client_connect_to_host() allows #GSocketClient to
36310 * determine when to use application-specific proxy protocols.
36312 * Upon a successful connection, a new #GSocketConnection is constructed
36313 * and returned. The caller owns this new object and must drop their
36314 * reference to it when finished with it.
36316 * In the event of any failure (DNS error, service not found, no hosts
36317 * connectable) %NULL is returned and @error (if non-%NULL) is set
36320 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36326 * g_socket_client_connect_to_uri_async:
36327 * @client: a #GSocketClient
36328 * @uri: a network uri
36329 * @default_port: the default port to connect to
36330 * @cancellable: (allow-none): a #GCancellable, or %NULL
36331 * @callback: (scope async): a #GAsyncReadyCallback
36332 * @user_data: (closure): user data for the callback
36334 * This is the asynchronous version of g_socket_client_connect_to_uri().
36336 * When the operation is finished @callback will be
36337 * called. You can then call g_socket_client_connect_to_uri_finish() to get
36338 * the result of the operation.
36345 * g_socket_client_connect_to_uri_finish:
36346 * @client: a #GSocketClient.
36347 * @result: a #GAsyncResult.
36348 * @error: a #GError location to store the error occurring, or %NULL to ignore.
36350 * Finishes an async connect operation. See g_socket_client_connect_to_uri_async()
36352 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
36358 * g_socket_client_get_enable_proxy:
36359 * @client: a #GSocketClient.
36361 * Gets the proxy enable state; see g_socket_client_set_enable_proxy()
36363 * Returns: whether proxying is enabled
36369 * g_socket_client_get_family:
36370 * @client: a #GSocketClient.
36372 * Gets the socket family of the socket client.
36374 * See g_socket_client_set_family() for details.
36376 * Returns: a #GSocketFamily
36382 * g_socket_client_get_local_address:
36383 * @client: a #GSocketClient.
36385 * Gets the local address of the socket client.
36387 * See g_socket_client_set_local_address() for details.
36389 * Returns: (transfer none): a #GSocketAddress or %NULL. Do not free.
36395 * g_socket_client_get_protocol:
36396 * @client: a #GSocketClient
36398 * Gets the protocol name type of the socket client.
36400 * See g_socket_client_set_protocol() for details.
36402 * Returns: a #GSocketProtocol
36408 * g_socket_client_get_socket_type:
36409 * @client: a #GSocketClient.
36411 * Gets the socket type of the socket client.
36413 * See g_socket_client_set_socket_type() for details.
36415 * Returns: a #GSocketFamily
36421 * g_socket_client_get_timeout:
36422 * @client: a #GSocketClient
36424 * Gets the I/O timeout time for sockets created by @client.
36426 * See g_socket_client_set_timeout() for details.
36428 * Returns: the timeout in seconds
36434 * g_socket_client_get_tls:
36435 * @client: a #GSocketClient.
36437 * Gets whether @client creates TLS connections. See
36438 * g_socket_client_set_tls() for details.
36440 * Returns: whether @client uses TLS
36446 * g_socket_client_get_tls_validation_flags:
36447 * @client: a #GSocketClient.
36449 * Gets the TLS validation flags used creating TLS connections via
36452 * Returns: the TLS validation flags
36458 * g_socket_client_new:
36460 * Creates a new #GSocketClient with the default options.
36462 * Free the returned object with g_object_unref().
36464 * Returns: a #GSocketClient.
36470 * g_socket_client_set_enable_proxy:
36471 * @client: a #GSocketClient.
36472 * @enable: whether to enable proxies
36474 * Sets whether or not @client attempts to make connections via a
36475 * proxy server. When enabled (the default), #GSocketClient will use a
36476 * #GProxyResolver to determine if a proxy protocol such as SOCKS is
36477 * needed, and automatically do the necessary proxy negotiation.
36484 * g_socket_client_set_family:
36485 * @client: a #GSocketClient.
36486 * @family: a #GSocketFamily
36488 * Sets the socket family of the socket client.
36489 * If this is set to something other than %G_SOCKET_FAMILY_INVALID
36490 * then the sockets created by this object will be of the specified
36493 * This might be useful for instance if you want to force the local
36494 * connection to be an ipv4 socket, even though the address might
36495 * be an ipv6 mapped to ipv4 address.
36502 * g_socket_client_set_local_address:
36503 * @client: a #GSocketClient.
36504 * @address: a #GSocketAddress, or %NULL
36506 * Sets the local address of the socket client.
36507 * The sockets created by this object will bound to the
36508 * specified address (if not %NULL) before connecting.
36510 * This is useful if you want to ensure that the local
36511 * side of the connection is on a specific port, or on
36512 * a specific interface.
36519 * g_socket_client_set_protocol:
36520 * @client: a #GSocketClient.
36521 * @protocol: a #GSocketProtocol
36523 * Sets the protocol of the socket client.
36524 * The sockets created by this object will use of the specified
36527 * If @protocol is %0 that means to use the default
36528 * protocol for the socket family and type.
36535 * g_socket_client_set_socket_type:
36536 * @client: a #GSocketClient.
36537 * @type: a #GSocketType
36539 * Sets the socket type of the socket client.
36540 * The sockets created by this object will be of the specified
36543 * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM,
36544 * as GSocketClient is used for connection oriented services.
36551 * g_socket_client_set_timeout:
36552 * @client: a #GSocketClient.
36553 * @timeout: the timeout
36555 * Sets the I/O timeout for sockets created by @client. @timeout is a
36556 * time in seconds, or 0 for no timeout (the default).
36558 * The timeout value affects the initial connection attempt as well,
36559 * so setting this may cause calls to g_socket_client_connect(), etc,
36560 * to fail with %G_IO_ERROR_TIMED_OUT.
36567 * g_socket_client_set_tls:
36568 * @client: a #GSocketClient.
36569 * @tls: whether to use TLS
36571 * Sets whether @client creates TLS (aka SSL) connections. If @tls is
36572 * %TRUE, @client will wrap its connections in a #GTlsClientConnection
36573 * and perform a TLS handshake when connecting.
36575 * Note that since #GSocketClient must return a #GSocketConnection,
36576 * but #GTlsClientConnection is not a #GSocketConnection, this
36577 * actually wraps the resulting #GTlsClientConnection in a
36578 * #GTcpWrapperConnection when returning it. You can use
36579 * g_tcp_wrapper_connection_get_base_io_stream() on the return value
36580 * to extract the #GTlsClientConnection.
36582 * If you need to modify the behavior of the TLS handshake (eg, by
36583 * setting a client-side certificate to use, or connecting to the
36584 * #GTlsConnection::accept-certificate signal), you can connect to
36585 * @client's #GSocketClient::event signal and wait for it to be
36586 * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you
36587 * a chance to see the #GTlsClientConnection before the handshake
36595 * g_socket_client_set_tls_validation_flags:
36596 * @client: a #GSocketClient.
36597 * @flags: the validation flags
36599 * Sets the TLS validation flags used when creating TLS connections
36600 * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL.
36608 * @socket: a #GSocket
36609 * @error: #GError for error reporting, or %NULL to ignore.
36611 * Closes the socket, shutting down any active connection.
36613 * Closing a socket does not wait for all outstanding I/O operations
36614 * to finish, so the caller should not rely on them to be guaranteed
36615 * to complete even if the close returns with no error.
36617 * Once the socket is closed, all other operations will return
36618 * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not
36621 * Sockets will be automatically closed when the last reference
36622 * is dropped, but you might want to call this function to make sure
36623 * resources are released as early as possible.
36625 * Beware that due to the way that TCP works, it is possible for
36626 * recently-sent data to be lost if either you close a socket while the
36627 * %G_IO_IN condition is set, or else if the remote connection tries to
36628 * send something to you after you close the socket but before it has
36629 * finished reading all of the data you sent. There is no easy generic
36630 * way to avoid this problem; the easiest fix is to design the network
36631 * protocol such that the client will never send data "out of turn".
36632 * Another solution is for the server to half-close the connection by
36633 * calling g_socket_shutdown() with only the @shutdown_write flag set,
36634 * and then wait for the client to notice this and close its side of the
36635 * connection, after which the server can safely call g_socket_close().
36636 * (This is what #GTcpConnection does if you call
36637 * g_tcp_connection_set_graceful_disconnect(). But of course, this
36638 * only works if the client will close its connection after the server
36641 * Returns: %TRUE on success, %FALSE on error
36647 * g_socket_condition_check:
36648 * @socket: a #GSocket
36649 * @condition: a #GIOCondition mask to check
36651 * Checks on the readiness of @socket to perform operations.
36652 * The operations specified in @condition are checked for and masked
36653 * against the currently-satisfied conditions on @socket. The result
36656 * Note that on Windows, it is possible for an operation to return
36657 * %G_IO_ERROR_WOULD_BLOCK even immediately after
36658 * g_socket_condition_check() has claimed that the socket is ready for
36659 * writing. Rather than calling g_socket_condition_check() and then
36660 * writing to the socket if it succeeds, it is generally better to
36661 * simply try writing to the socket right away, and try again later if
36662 * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK.
36664 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition;
36665 * these conditions will always be set in the output if they are true.
36667 * This call never blocks.
36669 * Returns: the @GIOCondition mask of the current state
36675 * g_socket_condition_timed_wait:
36676 * @socket: a #GSocket
36677 * @condition: a #GIOCondition mask to wait for
36678 * @timeout: the maximum time (in microseconds) to wait, or -1
36679 * @cancellable: (allow-none): a #GCancellable, or %NULL
36680 * @error: a #GError pointer, or %NULL
36682 * Waits for up to @timeout microseconds for @condition to become true
36683 * on @socket. If the condition is met, %TRUE is returned.
36685 * If @cancellable is cancelled before the condition is met, or if
36686 * @timeout (or the socket's #GSocket:timeout) is reached before the
36687 * condition is met, then %FALSE is returned and @error, if non-%NULL,
36688 * is set to the appropriate value (%G_IO_ERROR_CANCELLED or
36689 * %G_IO_ERROR_TIMED_OUT).
36691 * If you don't want a timeout, use g_socket_condition_wait().
36692 * (Alternatively, you can pass -1 for @timeout.)
36694 * Note that although @timeout is in microseconds for consistency with
36695 * other GLib APIs, this function actually only has millisecond
36696 * resolution, and the behavior is undefined if @timeout is not an
36697 * exact number of milliseconds.
36699 * Returns: %TRUE if the condition was met, %FALSE otherwise
36705 * g_socket_condition_wait:
36706 * @socket: a #GSocket
36707 * @condition: a #GIOCondition mask to wait for
36708 * @cancellable: (allow-none): a #GCancellable, or %NULL
36709 * @error: a #GError pointer, or %NULL
36711 * Waits for @condition to become true on @socket. When the condition
36712 * is met, %TRUE is returned.
36714 * If @cancellable is cancelled before the condition is met, or if the
36715 * socket has a timeout set and it is reached before the condition is
36716 * met, then %FALSE is returned and @error, if non-%NULL, is set to
36717 * the appropriate value (%G_IO_ERROR_CANCELLED or
36718 * %G_IO_ERROR_TIMED_OUT).
36720 * See also g_socket_condition_timed_wait().
36722 * Returns: %TRUE if the condition was met, %FALSE otherwise
36728 * g_socket_connect:
36729 * @socket: a #GSocket.
36730 * @address: a #GSocketAddress specifying the remote address.
36731 * @cancellable: (allow-none): a %GCancellable or %NULL
36732 * @error: #GError for error reporting, or %NULL to ignore.
36734 * Connect the socket to the specified remote address.
36736 * For connection oriented socket this generally means we attempt to make
36737 * a connection to the @address. For a connection-less socket it sets
36738 * the default address for g_socket_send() and discards all incoming datagrams
36739 * from other sources.
36741 * Generally connection oriented sockets can only connect once, but
36742 * connection-less sockets can connect multiple times to change the
36745 * If the connect call needs to do network I/O it will block, unless
36746 * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned
36747 * and the user can be notified of the connection finishing by waiting
36748 * for the G_IO_OUT condition. The result of the connection must then be
36749 * checked with g_socket_check_connect_result().
36751 * Returns: %TRUE if connected, %FALSE on error.
36757 * g_socket_connectable_enumerate:
36758 * @connectable: a #GSocketConnectable
36760 * Creates a #GSocketAddressEnumerator for @connectable.
36762 * Returns: (transfer full): a new #GSocketAddressEnumerator.
36768 * g_socket_connectable_proxy_enumerate:
36769 * @connectable: a #GSocketConnectable
36771 * Creates a #GSocketAddressEnumerator for @connectable that will
36772 * return #GProxyAddress<!-- -->es for addresses that you must connect
36775 * If @connectable does not implement
36776 * g_socket_connectable_proxy_enumerate(), this will fall back to
36777 * calling g_socket_connectable_enumerate().
36779 * Returns: (transfer full): a new #GSocketAddressEnumerator.
36785 * g_socket_connection_connect:
36786 * @connection: a #GSocketConnection
36787 * @address: a #GSocketAddress specifying the remote address.
36788 * @cancellable: (allow-none): a %GCancellable or %NULL
36789 * @error: #GError for error reporting, or %NULL to ignore.
36791 * Connect @connection to the specified remote address.
36793 * Returns: %TRUE if the connection succeeded, %FALSE on error
36799 * g_socket_connection_connect_async:
36800 * @connection: a #GSocketConnection
36801 * @address: a #GSocketAddress specifying the remote address.
36802 * @cancellable: (allow-none): a %GCancellable or %NULL
36803 * @callback: (scope async): a #GAsyncReadyCallback
36804 * @user_data: (closure): user data for the callback
36806 * Asynchronously connect @connection to the specified remote address.
36808 * This clears the #GSocket:blocking flag on @connection's underlying
36809 * socket if it is currently set.
36811 * Use g_socket_connection_connect_finish() to retrieve the result.
36818 * g_socket_connection_connect_finish:
36819 * @connection: a #GSocketConnection
36820 * @result: the #GAsyncResult
36821 * @error: #GError for error reporting, or %NULL to ignore.
36823 * Gets the result of a g_socket_connection_connect_async() call.
36825 * Returns: %TRUE if the connection succeeded, %FALSE on error
36831 * g_socket_connection_factory_create_connection:
36832 * @socket: a #GSocket
36834 * Creates a #GSocketConnection subclass of the right type for
36837 * Returns: (transfer full): a #GSocketConnection
36843 * g_socket_connection_factory_lookup_type:
36844 * @family: a #GSocketFamily
36845 * @type: a #GSocketType
36846 * @protocol_id: a protocol id
36848 * Looks up the #GType to be used when creating socket connections on
36849 * sockets with the specified @family, @type and @protocol_id.
36851 * If no type is registered, the #GSocketConnection base type is returned.
36853 * Returns: a #GType
36859 * g_socket_connection_factory_register_type:
36860 * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION
36861 * @family: a #GSocketFamily
36862 * @type: a #GSocketType
36863 * @protocol: a protocol id
36865 * Looks up the #GType to be used when creating socket connections on
36866 * sockets with the specified @family, @type and @protocol.
36868 * If no type is registered, the #GSocketConnection base type is returned.
36875 * g_socket_connection_get_local_address:
36876 * @connection: a #GSocketConnection
36877 * @error: #GError for error reporting, or %NULL to ignore.
36879 * Try to get the local address of a socket connection.
36881 * Free the returned object with g_object_unref().
36883 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
36889 * g_socket_connection_get_remote_address:
36890 * @connection: a #GSocketConnection
36891 * @error: #GError for error reporting, or %NULL to ignore.
36893 * Try to get the remote address of a socket connection.
36895 * Free the returned object with g_object_unref().
36897 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
36903 * g_socket_connection_get_socket:
36904 * @connection: a #GSocketConnection
36906 * Gets the underlying #GSocket object of the connection.
36907 * This can be useful if you want to do something unusual on it
36908 * not supported by the #GSocketConnection APIs.
36910 * Returns: (transfer none): a #GSocketAddress or %NULL on error.
36916 * g_socket_connection_is_connected:
36917 * @connection: a #GSocketConnection
36919 * Checks if @connection is connected. This is equivalent to calling
36920 * g_socket_is_connected() on @connection's underlying #GSocket.
36922 * Returns: whether @connection is connected
36928 * g_socket_control_message_deserialize:
36929 * @level: a socket level
36930 * @type: a socket control message type for the given @level
36931 * @size: the size of the data in bytes
36932 * @data: (array length=size) (element-type guint8): pointer to the message data
36934 * Tries to deserialize a socket control message of a given
36935 * @level and @type. This will ask all known (to GType) subclasses
36936 * of #GSocketControlMessage if they can understand this kind
36937 * of message and if so deserialize it into a #GSocketControlMessage.
36939 * If there is no implementation for this kind of control message, %NULL
36940 * will be returned.
36942 * Returns: (transfer full): the deserialized message or %NULL
36948 * g_socket_control_message_get_level:
36949 * @message: a #GSocketControlMessage
36951 * Returns the "level" (i.e. the originating protocol) of the control message.
36952 * This is often SOL_SOCKET.
36954 * Returns: an integer describing the level
36960 * g_socket_control_message_get_msg_type:
36961 * @message: a #GSocketControlMessage
36963 * Returns the protocol specific type of the control message.
36964 * For instance, for UNIX fd passing this would be SCM_RIGHTS.
36966 * Returns: an integer describing the type of control message
36972 * g_socket_control_message_get_size:
36973 * @message: a #GSocketControlMessage
36975 * Returns the space required for the control message, not including
36976 * headers or alignment.
36978 * Returns: The number of bytes required.
36984 * g_socket_control_message_serialize:
36985 * @message: a #GSocketControlMessage
36986 * @data: A buffer to write data to
36988 * Converts the data in the message to bytes placed in the
36991 * @data is guaranteed to have enough space to fit the size
36992 * returned by g_socket_control_message_get_size() on this
37000 * g_socket_create_source: (skip)
37001 * @socket: a #GSocket
37002 * @condition: a #GIOCondition mask to monitor
37003 * @cancellable: (allow-none): a %GCancellable or %NULL
37005 * Creates a %GSource that can be attached to a %GMainContext to monitor
37006 * for the availibility of the specified @condition on the socket.
37008 * The callback on the source is of the #GSocketSourceFunc type.
37010 * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition;
37011 * these conditions will always be reported output if they are true.
37013 * @cancellable if not %NULL can be used to cancel the source, which will
37014 * cause the source to trigger, reporting the current condition (which
37015 * is likely 0 unless cancellation happened at the same time as a
37016 * condition change). You can check for this in the callback using
37017 * g_cancellable_is_cancelled().
37019 * If @socket has a timeout set, and it is reached before @condition
37020 * occurs, the source will then trigger anyway, reporting %G_IO_IN or
37021 * %G_IO_OUT depending on @condition. However, @socket will have been
37022 * marked as having had a timeout, and so the next #GSocket I/O method
37023 * you call will then fail with a %G_IO_ERROR_TIMED_OUT.
37025 * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref().
37031 * g_socket_get_available_bytes:
37032 * @socket: a #GSocket
37034 * Get the amount of data pending in the OS input buffer.
37036 * without blocking or -1 on error.
37038 * Returns: the number of bytes that can be read from the socket
37044 * g_socket_get_blocking:
37045 * @socket: a #GSocket.
37047 * Gets the blocking mode of the socket. For details on blocking I/O,
37048 * see g_socket_set_blocking().
37050 * Returns: %TRUE if blocking I/O is used, %FALSE otherwise.
37056 * g_socket_get_broadcast:
37057 * @socket: a #GSocket.
37059 * Gets the broadcast setting on @socket; if %TRUE,
37060 * it is possible to send packets to broadcast
37061 * addresses or receive from broadcast addresses.
37063 * Returns: the broadcast setting on @socket
37069 * g_socket_get_credentials:
37070 * @socket: a #GSocket.
37071 * @error: #GError for error reporting, or %NULL to ignore.
37073 * Returns the credentials of the foreign process connected to this
37074 * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX
37077 * If this operation isn't supported on the OS, the method fails with
37078 * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
37079 * by reading the %SO_PEERCRED option on the underlying socket.
37081 * Other ways to obtain credentials from a foreign peer includes the
37082 * #GUnixCredentialsMessage type and
37083 * g_unix_connection_send_credentials() /
37084 * g_unix_connection_receive_credentials() functions.
37086 * that must be freed with g_object_unref().
37088 * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object
37094 * g_socket_get_family:
37095 * @socket: a #GSocket.
37097 * Gets the socket family of the socket.
37099 * Returns: a #GSocketFamily
37106 * @socket: a #GSocket.
37108 * Returns the underlying OS socket object. On unix this
37109 * is a socket file descriptor, and on windows this is
37110 * a Winsock2 SOCKET handle. This may be useful for
37111 * doing platform specific or otherwise unusual operations
37114 * Returns: the file descriptor of the socket.
37120 * g_socket_get_keepalive:
37121 * @socket: a #GSocket.
37123 * Gets the keepalive mode of the socket. For details on this,
37124 * see g_socket_set_keepalive().
37126 * Returns: %TRUE if keepalive is active, %FALSE otherwise.
37132 * g_socket_get_listen_backlog:
37133 * @socket: a #GSocket.
37135 * Gets the listen backlog setting of the socket. For details on this,
37136 * see g_socket_set_listen_backlog().
37138 * Returns: the maximum number of pending connections.
37144 * g_socket_get_local_address:
37145 * @socket: a #GSocket.
37146 * @error: #GError for error reporting, or %NULL to ignore.
37148 * Try to get the local address of a bound socket. This is only
37149 * useful if the socket has been bound to a local address,
37150 * either explicitly or implicitly when connecting.
37152 * Free the returned object with g_object_unref().
37154 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
37160 * g_socket_get_multicast_loopback:
37161 * @socket: a #GSocket.
37163 * Gets the multicast loopback setting on @socket; if %TRUE (the
37164 * default), outgoing multicast packets will be looped back to
37165 * multicast listeners on the same host.
37167 * Returns: the multicast loopback setting on @socket
37173 * g_socket_get_multicast_ttl:
37174 * @socket: a #GSocket.
37176 * Gets the multicast time-to-live setting on @socket; see
37177 * g_socket_set_multicast_ttl() for more details.
37179 * Returns: the multicast time-to-live setting on @socket
37185 * g_socket_get_protocol:
37186 * @socket: a #GSocket.
37188 * Gets the socket protocol id the socket was created with.
37189 * In case the protocol is unknown, -1 is returned.
37191 * Returns: a protocol id, or -1 if unknown
37197 * g_socket_get_remote_address:
37198 * @socket: a #GSocket.
37199 * @error: #GError for error reporting, or %NULL to ignore.
37201 * Try to get the remove address of a connected socket. This is only
37202 * useful for connection oriented sockets that have been connected.
37204 * Free the returned object with g_object_unref().
37206 * Returns: (transfer full): a #GSocketAddress or %NULL on error.
37212 * g_socket_get_socket_type:
37213 * @socket: a #GSocket.
37215 * Gets the socket type of the socket.
37217 * Returns: a #GSocketType
37223 * g_socket_get_timeout:
37224 * @socket: a #GSocket.
37226 * Gets the timeout setting of the socket. For details on this, see
37227 * g_socket_set_timeout().
37229 * Returns: the timeout in seconds
37235 * g_socket_get_ttl:
37236 * @socket: a #GSocket.
37238 * Gets the unicast time-to-live setting on @socket; see
37239 * g_socket_set_ttl() for more details.
37241 * Returns: the time-to-live setting on @socket
37247 * g_socket_is_closed:
37248 * @socket: a #GSocket
37250 * Checks whether a socket is closed.
37252 * Returns: %TRUE if socket is closed, %FALSE otherwise
37258 * g_socket_is_connected:
37259 * @socket: a #GSocket.
37261 * Check whether the socket is connected. This is only useful for
37262 * connection-oriented sockets.
37264 * Returns: %TRUE if socket is connected, %FALSE otherwise.
37270 * g_socket_join_multicast_group:
37271 * @socket: a #GSocket.
37272 * @group: a #GInetAddress specifying the group address to join.
37273 * @iface: (allow-none): Name of the interface to use, or %NULL
37274 * @source_specific: %TRUE if source-specific multicast should be used
37275 * @error: #GError for error reporting, or %NULL to ignore.
37277 * Registers @socket to receive multicast messages sent to @group.
37278 * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
37279 * been bound to an appropriate interface and port with
37282 * If @iface is %NULL, the system will automatically pick an interface
37283 * to bind to based on @group.
37285 * If @source_specific is %TRUE, source-specific multicast as defined
37286 * in RFC 4604 is used. Note that on older platforms this may fail
37287 * with a %G_IO_ERROR_NOT_SUPPORTED error.
37289 * Returns: %TRUE on success, %FALSE on error.
37295 * g_socket_leave_multicast_group:
37296 * @socket: a #GSocket.
37297 * @group: a #GInetAddress specifying the group address to leave.
37298 * @iface: (allow-none): Interface used
37299 * @source_specific: %TRUE if source-specific multicast was used
37300 * @error: #GError for error reporting, or %NULL to ignore.
37302 * Removes @socket from the multicast group defined by @group, @iface,
37303 * and @source_specific (which must all have the same values they had
37304 * when you joined the group).
37306 * @socket remains bound to its address and port, and can still receive
37307 * unicast messages after calling this.
37309 * Returns: %TRUE on success, %FALSE on error.
37316 * @socket: a #GSocket.
37317 * @error: #GError for error reporting, or %NULL to ignore.
37319 * Marks the socket as a server socket, i.e. a socket that is used
37320 * to accept incoming requests using g_socket_accept().
37322 * Before calling this the socket must be bound to a local address using
37325 * To set the maximum amount of outstanding clients, use
37326 * g_socket_set_listen_backlog().
37328 * Returns: %TRUE on success, %FALSE on error.
37334 * g_socket_listener_accept:
37335 * @listener: a #GSocketListener
37336 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL
37337 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
37338 * @error: #GError for error reporting, or %NULL to ignore.
37340 * Blocks waiting for a client to connect to any of the sockets added
37341 * to the listener. Returns a #GSocketConnection for the socket that was
37344 * If @source_object is not %NULL it will be filled out with the source
37345 * object specified when the corresponding socket or address was added
37348 * If @cancellable is not %NULL, then the operation can be cancelled by
37349 * triggering the cancellable object from another thread. If the operation
37350 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
37352 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
37358 * g_socket_listener_accept_async:
37359 * @listener: a #GSocketListener
37360 * @cancellable: (allow-none): a #GCancellable, or %NULL
37361 * @callback: (scope async): a #GAsyncReadyCallback
37362 * @user_data: (closure): user data for the callback
37364 * This is the asynchronous version of g_socket_listener_accept().
37366 * When the operation is finished @callback will be
37367 * called. You can then call g_socket_listener_accept_socket()
37368 * to get the result of the operation.
37375 * g_socket_listener_accept_finish:
37376 * @listener: a #GSocketListener
37377 * @result: a #GAsyncResult.
37378 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
37379 * @error: a #GError location to store the error occurring, or %NULL to ignore.
37381 * Finishes an async accept operation. See g_socket_listener_accept_async()
37383 * Returns: (transfer full): a #GSocketConnection on success, %NULL on error.
37389 * g_socket_listener_accept_socket:
37390 * @listener: a #GSocketListener
37391 * @source_object: (out) (transfer none) (allow-none): location where #GObject pointer will be stored, or %NULL.
37392 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
37393 * @error: #GError for error reporting, or %NULL to ignore.
37395 * Blocks waiting for a client to connect to any of the sockets added
37396 * to the listener. Returns the #GSocket that was accepted.
37398 * If you want to accept the high-level #GSocketConnection, not a #GSocket,
37399 * which is often the case, then you should use g_socket_listener_accept()
37402 * If @source_object is not %NULL it will be filled out with the source
37403 * object specified when the corresponding socket or address was added
37406 * If @cancellable is not %NULL, then the operation can be cancelled by
37407 * triggering the cancellable object from another thread. If the operation
37408 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
37410 * Returns: (transfer full): a #GSocket on success, %NULL on error.
37416 * g_socket_listener_accept_socket_async:
37417 * @listener: a #GSocketListener
37418 * @cancellable: (allow-none): a #GCancellable, or %NULL
37419 * @callback: (scope async): a #GAsyncReadyCallback
37420 * @user_data: (closure): user data for the callback
37422 * This is the asynchronous version of g_socket_listener_accept_socket().
37424 * When the operation is finished @callback will be
37425 * called. You can then call g_socket_listener_accept_socket_finish()
37426 * to get the result of the operation.
37433 * g_socket_listener_accept_socket_finish:
37434 * @listener: a #GSocketListener
37435 * @result: a #GAsyncResult.
37436 * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source
37437 * @error: a #GError location to store the error occurring, or %NULL to ignore.
37439 * Finishes an async accept operation. See g_socket_listener_accept_socket_async()
37441 * Returns: (transfer full): a #GSocket on success, %NULL on error.
37447 * g_socket_listener_add_address:
37448 * @listener: a #GSocketListener
37449 * @address: a #GSocketAddress
37450 * @type: a #GSocketType
37451 * @protocol: a #GSocketProtocol
37452 * @source_object: (allow-none): Optional #GObject identifying this source
37453 * @effective_address: (out) (allow-none): location to store the address that was bound to, or %NULL.
37454 * @error: #GError for error reporting, or %NULL to ignore.
37456 * Creates a socket of type @type and protocol @protocol, binds
37457 * it to @address and adds it to the set of sockets we're accepting
37460 * Note that adding an IPv6 address, depending on the platform,
37461 * may or may not result in a listener that also accepts IPv4
37462 * connections. For more deterministic behavior, see
37463 * g_socket_listener_add_inet_port().
37465 * @source_object will be passed out in the various calls
37466 * to accept to identify this particular source, which is
37467 * useful if you're listening on multiple addresses and do
37468 * different things depending on what address is connected to.
37470 * If successful and @effective_address is non-%NULL then it will
37471 * be set to the address that the binding actually occurred at. This
37472 * is helpful for determining the port number that was used for when
37473 * requesting a binding to port 0 (ie: "any port"). This address, if
37474 * requested, belongs to the caller and must be freed.
37476 * Returns: %TRUE on success, %FALSE on error.
37482 * g_socket_listener_add_any_inet_port:
37483 * @listener: a #GSocketListener
37484 * @source_object: (allow-none): Optional #GObject identifying this source
37485 * @error: a #GError location to store the error occurring, or %NULL to ignore.
37487 * Listens for TCP connections on any available port number for both
37488 * IPv6 and IPv4 (if each is available).
37490 * This is useful if you need to have a socket for incoming connections
37491 * but don't care about the specific port number.
37493 * @source_object will be passed out in the various calls
37494 * to accept to identify this particular source, which is
37495 * useful if you're listening on multiple addresses and do
37496 * different things depending on what address is connected to.
37498 * Returns: the port number, or 0 in case of failure.
37504 * g_socket_listener_add_inet_port:
37505 * @listener: a #GSocketListener
37506 * @port: an IP port number (non-zero)
37507 * @source_object: (allow-none): Optional #GObject identifying this source
37508 * @error: #GError for error reporting, or %NULL to ignore.
37510 * Helper function for g_socket_listener_add_address() that
37511 * creates a TCP/IP socket listening on IPv4 and IPv6 (if
37512 * supported) on the specified port on all interfaces.
37514 * @source_object will be passed out in the various calls
37515 * to accept to identify this particular source, which is
37516 * useful if you're listening on multiple addresses and do
37517 * different things depending on what address is connected to.
37519 * Returns: %TRUE on success, %FALSE on error.
37525 * g_socket_listener_add_socket:
37526 * @listener: a #GSocketListener
37527 * @socket: a listening #GSocket
37528 * @source_object: (allow-none): Optional #GObject identifying this source
37529 * @error: #GError for error reporting, or %NULL to ignore.
37531 * Adds @socket to the set of sockets that we try to accept
37532 * new clients from. The socket must be bound to a local
37533 * address and listened to.
37535 * @source_object will be passed out in the various calls
37536 * to accept to identify this particular source, which is
37537 * useful if you're listening on multiple addresses and do
37538 * different things depending on what address is connected to.
37540 * Returns: %TRUE on success, %FALSE on error.
37546 * g_socket_listener_close:
37547 * @listener: a #GSocketListener
37549 * Closes all the sockets in the listener.
37556 * g_socket_listener_new:
37558 * Creates a new #GSocketListener with no sockets to listen for.
37559 * New listeners can be added with e.g. g_socket_listener_add_address()
37560 * or g_socket_listener_add_inet_port().
37562 * Returns: a new #GSocketListener.
37568 * g_socket_listener_set_backlog:
37569 * @listener: a #GSocketListener
37570 * @listen_backlog: an integer
37572 * Sets the listen backlog on the sockets in the listener.
37574 * See g_socket_set_listen_backlog() for details
37582 * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4.
37583 * @type: the socket type to use.
37584 * @protocol: the id of the protocol to use, or 0 for default.
37585 * @error: #GError for error reporting, or %NULL to ignore.
37587 * Creates a new #GSocket with the defined family, type and protocol.
37588 * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type
37589 * for the family and type is used.
37591 * The @protocol is a family and type specific int that specifies what
37592 * kind of protocol to use. #GSocketProtocol lists several common ones.
37593 * Many families only support one protocol, and use 0 for this, others
37594 * support several and using 0 means to use the default protocol for
37595 * the family and type.
37597 * The protocol id is passed directly to the operating
37598 * system, so you can use protocols not listed in #GSocketProtocol if you
37599 * know the protocol number used for it.
37601 * Free the returned object with g_object_unref().
37603 * Returns: a #GSocket or %NULL on error.
37609 * g_socket_new_from_fd:
37610 * @fd: a native socket file descriptor.
37611 * @error: #GError for error reporting, or %NULL to ignore.
37613 * Creates a new #GSocket from a native file descriptor
37614 * or winsock SOCKET handle.
37616 * This reads all the settings from the file descriptor so that
37617 * all properties should work. Note that the file descriptor
37618 * will be set to non-blocking mode, independent on the blocking
37619 * mode of the #GSocket.
37621 * Free the returned object with g_object_unref().
37623 * Returns: a #GSocket or %NULL on error.
37629 * g_socket_receive:
37630 * @socket: a #GSocket
37631 * @buffer: a buffer to read data into (which should be at least @size bytes long).
37632 * @size: the number of bytes you want to read from the socket
37633 * @cancellable: (allow-none): a %GCancellable or %NULL
37634 * @error: #GError for error reporting, or %NULL to ignore.
37636 * Receive data (up to @size bytes) from a socket. This is mainly used by
37637 * connection-oriented sockets; it is identical to g_socket_receive_from()
37638 * with @address set to %NULL.
37640 * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets,
37641 * g_socket_receive() will always read either 0 or 1 complete messages from
37642 * the socket. If the received message is too large to fit in @buffer, then
37643 * the data beyond @size bytes will be discarded, without any explicit
37644 * indication that this has occurred.
37646 * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any
37647 * number of bytes, up to @size. If more than @size bytes have been
37648 * received, the additional data will be returned in future calls to
37649 * g_socket_receive().
37651 * If the socket is in blocking mode the call will block until there
37652 * is some data to receive, the connection is closed, or there is an
37653 * error. If there is no data available and the socket is in
37654 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
37655 * returned. To be notified when data is available, wait for the
37656 * %G_IO_IN condition.
37658 * On error -1 is returned and @error is set accordingly.
37660 * the peer, or -1 on error
37662 * Returns: Number of bytes read, or 0 if the connection was closed by
37668 * g_socket_receive_from:
37669 * @socket: a #GSocket
37670 * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL
37671 * @buffer: (array length=size) (element-type guint8): a buffer to read data into (which should be at least @size bytes long).
37672 * @size: the number of bytes you want to read from the socket
37673 * @cancellable: (allow-none): a %GCancellable or %NULL
37674 * @error: #GError for error reporting, or %NULL to ignore.
37676 * Receive data (up to @size bytes) from a socket.
37678 * If @address is non-%NULL then @address will be set equal to the
37679 * source address of the received packet.
37680 * @address is owned by the caller.
37682 * See g_socket_receive() for additional information.
37684 * the peer, or -1 on error
37686 * Returns: Number of bytes read, or 0 if the connection was closed by
37692 * g_socket_receive_message:
37693 * @socket: a #GSocket
37694 * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL
37695 * @vectors: (array length=num_vectors): an array of #GInputVector structs
37696 * @num_vectors: the number of elements in @vectors, or -1
37697 * @messages: (array length=num_messages) (allow-none): a pointer which may be filled with an array of #GSocketControlMessages, or %NULL
37698 * @num_messages: a pointer which will be filled with the number of elements in @messages, or %NULL
37699 * @flags: a pointer to an int containing #GSocketMsgFlags flags
37700 * @cancellable: (allow-none): a %GCancellable or %NULL
37701 * @error: a #GError pointer, or %NULL
37703 * Receive data from a socket. This is the most complicated and
37704 * fully-featured version of this call. For easier use, see
37705 * g_socket_receive() and g_socket_receive_from().
37707 * If @address is non-%NULL then @address will be set equal to the
37708 * source address of the received packet.
37709 * @address is owned by the caller.
37711 * @vector must point to an array of #GInputVector structs and
37712 * @num_vectors must be the length of this array. These structs
37713 * describe the buffers that received data will be scattered into.
37714 * If @num_vectors is -1, then @vectors is assumed to be terminated
37715 * by a #GInputVector with a %NULL buffer pointer.
37717 * As a special case, if @num_vectors is 0 (in which case, @vectors
37718 * may of course be %NULL), then a single byte is received and
37719 * discarded. This is to facilitate the common practice of sending a
37720 * single '\0' byte for the purposes of transferring ancillary data.
37722 * @messages, if non-%NULL, will be set to point to a newly-allocated
37723 * array of #GSocketControlMessage instances or %NULL if no such
37724 * messages was received. These correspond to the control messages
37725 * received from the kernel, one #GSocketControlMessage per message
37726 * from the kernel. This array is %NULL-terminated and must be freed
37727 * by the caller using g_free() after calling g_object_unref() on each
37728 * element. If @messages is %NULL, any control messages received will
37731 * @num_messages, if non-%NULL, will be set to the number of control
37732 * messages received.
37734 * If both @messages and @num_messages are non-%NULL, then
37735 * @num_messages gives the number of #GSocketControlMessage instances
37736 * in @messages (ie: not including the %NULL terminator).
37738 * @flags is an in/out parameter. The commonly available arguments
37739 * for this are available in the #GSocketMsgFlags enum, but the
37740 * values there are the same as the system values, and the flags
37741 * are passed in as-is, so you can pass in system-specific flags too
37742 * (and g_socket_receive_message() may pass system-specific flags out).
37744 * As with g_socket_receive(), data may be discarded if @socket is
37745 * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not
37746 * provide enough buffer space to read a complete message. You can pass
37747 * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without
37748 * removing it from the receive queue, but there is no portable way to find
37749 * out the length of the message other than by reading it into a
37750 * sufficiently-large buffer.
37752 * If the socket is in blocking mode the call will block until there
37753 * is some data to receive, the connection is closed, or there is an
37754 * error. If there is no data available and the socket is in
37755 * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be
37756 * returned. To be notified when data is available, wait for the
37757 * %G_IO_IN condition.
37759 * On error -1 is returned and @error is set accordingly.
37761 * the peer, or -1 on error
37763 * Returns: Number of bytes read, or 0 if the connection was closed by
37769 * g_socket_receive_with_blocking:
37770 * @socket: a #GSocket
37771 * @buffer: a buffer to read data into (which should be at least @size bytes long).
37772 * @size: the number of bytes you want to read from the socket
37773 * @blocking: whether to do blocking or non-blocking I/O
37774 * @cancellable: (allow-none): a %GCancellable or %NULL
37775 * @error: #GError for error reporting, or %NULL to ignore.
37777 * This behaves exactly the same as g_socket_receive(), except that
37778 * the choice of blocking or non-blocking behavior is determined by
37779 * the @blocking argument rather than by @socket's properties.
37781 * the peer, or -1 on error
37783 * Returns: Number of bytes read, or 0 if the connection was closed by
37790 * @socket: a #GSocket
37791 * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send.
37792 * @size: the number of bytes to send
37793 * @cancellable: (allow-none): a %GCancellable or %NULL
37794 * @error: #GError for error reporting, or %NULL to ignore.
37796 * Tries to send @size bytes from @buffer on the socket. This is
37797 * mainly used by connection-oriented sockets; it is identical to
37798 * g_socket_send_to() with @address set to %NULL.
37800 * If the socket is in blocking mode the call will block until there is
37801 * space for the data in the socket queue. If there is no space available
37802 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
37803 * will be returned. To be notified when space is available, wait for the
37804 * %G_IO_OUT condition. Note though that you may still receive
37805 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
37806 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
37807 * very common due to the way the underlying APIs work.)
37809 * On error -1 is returned and @error is set accordingly.
37813 * Returns: Number of bytes written (which may be less than @size), or -1
37819 * g_socket_send_message:
37820 * @socket: a #GSocket
37821 * @address: a #GSocketAddress, or %NULL
37822 * @vectors: (array length=num_vectors): an array of #GOutputVector structs
37823 * @num_vectors: the number of elements in @vectors, or -1
37824 * @messages: (array length=num_messages) (allow-none): a pointer to an array of #GSocketControlMessages, or %NULL.
37825 * @num_messages: number of elements in @messages, or -1.
37826 * @flags: an int containing #GSocketMsgFlags flags
37827 * @cancellable: (allow-none): a %GCancellable or %NULL
37828 * @error: #GError for error reporting, or %NULL to ignore.
37830 * Send data to @address on @socket. This is the most complicated and
37831 * fully-featured version of this call. For easier use, see
37832 * g_socket_send() and g_socket_send_to().
37834 * If @address is %NULL then the message is sent to the default receiver
37835 * (set by g_socket_connect()).
37837 * @vectors must point to an array of #GOutputVector structs and
37838 * @num_vectors must be the length of this array. (If @num_vectors is -1,
37839 * then @vectors is assumed to be terminated by a #GOutputVector with a
37840 * %NULL buffer pointer.) The #GOutputVector structs describe the buffers
37841 * that the sent data will be gathered from. Using multiple
37842 * #GOutputVector<!-- -->s is more memory-efficient than manually copying
37843 * data from multiple sources into a single buffer, and more
37844 * network-efficient than making multiple calls to g_socket_send().
37846 * @messages, if non-%NULL, is taken to point to an array of @num_messages
37847 * #GSocketControlMessage instances. These correspond to the control
37848 * messages to be sent on the socket.
37849 * If @num_messages is -1 then @messages is treated as a %NULL-terminated
37852 * @flags modify how the message is sent. The commonly available arguments
37853 * for this are available in the #GSocketMsgFlags enum, but the
37854 * values there are the same as the system values, and the flags
37855 * are passed in as-is, so you can pass in system-specific flags too.
37857 * If the socket is in blocking mode the call will block until there is
37858 * space for the data in the socket queue. If there is no space available
37859 * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error
37860 * will be returned. To be notified when space is available, wait for the
37861 * %G_IO_OUT condition. Note though that you may still receive
37862 * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously
37863 * notified of a %G_IO_OUT condition. (On Windows in particular, this is
37864 * very common due to the way the underlying APIs work.)
37866 * On error -1 is returned and @error is set accordingly.
37870 * Returns: Number of bytes written (which may be less than @size), or -1
37876 * g_socket_send_to:
37877 * @socket: a #GSocket
37878 * @address: a #GSocketAddress, or %NULL
37879 * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send.
37880 * @size: the number of bytes to send
37881 * @cancellable: (allow-none): a %GCancellable or %NULL
37882 * @error: #GError for error reporting, or %NULL to ignore.
37884 * Tries to send @size bytes from @buffer to @address. If @address is
37885 * %NULL then the message is sent to the default receiver (set by
37886 * g_socket_connect()).
37888 * See g_socket_send() for additional information.
37892 * Returns: Number of bytes written (which may be less than @size), or -1
37898 * g_socket_send_with_blocking:
37899 * @socket: a #GSocket
37900 * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send.
37901 * @size: the number of bytes to send
37902 * @blocking: whether to do blocking or non-blocking I/O
37903 * @cancellable: (allow-none): a %GCancellable or %NULL
37904 * @error: #GError for error reporting, or %NULL to ignore.
37906 * This behaves exactly the same as g_socket_send(), except that
37907 * the choice of blocking or non-blocking behavior is determined by
37908 * the @blocking argument rather than by @socket's properties.
37912 * Returns: Number of bytes written (which may be less than @size), or -1
37918 * g_socket_service_is_active:
37919 * @service: a #GSocketService
37921 * Check whether the service is active or not. An active
37922 * service will accept new clients that connect, while
37923 * a non-active service will let connecting clients queue
37924 * up until the service is started.
37926 * Returns: %TRUE if the service is active, %FALSE otherwise
37932 * g_socket_service_new:
37934 * Creates a new #GSocketService with no sockets to listen for.
37935 * New listeners can be added with e.g. g_socket_listener_add_address()
37936 * or g_socket_listener_add_inet_port().
37938 * Returns: a new #GSocketService.
37944 * g_socket_service_start:
37945 * @service: a #GSocketService
37947 * Starts the service, i.e. start accepting connections
37948 * from the added sockets when the mainloop runs.
37950 * This call is thread-safe, so it may be called from a thread
37951 * handling an incoming client request.
37958 * g_socket_service_stop:
37959 * @service: a #GSocketService
37961 * Stops the service, i.e. stops accepting connections
37962 * from the added sockets when the mainloop runs.
37964 * This call is thread-safe, so it may be called from a thread
37965 * handling an incoming client request.
37972 * g_socket_set_blocking:
37973 * @socket: a #GSocket.
37974 * @blocking: Whether to use blocking I/O or not.
37976 * Sets the blocking mode of the socket. In blocking mode
37977 * all operations block until they succeed or there is an error. In
37978 * non-blocking mode all functions return results immediately or
37979 * with a %G_IO_ERROR_WOULD_BLOCK error.
37981 * All sockets are created in blocking mode. However, note that the
37982 * platform level socket is always non-blocking, and blocking mode
37983 * is a GSocket level feature.
37990 * g_socket_set_broadcast:
37991 * @socket: a #GSocket.
37992 * @broadcast: whether @socket should allow sending to and receiving from broadcast addresses
37994 * Sets whether @socket should allow sending to and receiving from
37995 * broadcast addresses. This is %FALSE by default.
38002 * g_socket_set_keepalive:
38003 * @socket: a #GSocket.
38004 * @keepalive: Value for the keepalive flag
38006 * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When
38007 * this flag is set on a socket, the system will attempt to verify that the
38008 * remote socket endpoint is still present if a sufficiently long period of
38009 * time passes with no data being exchanged. If the system is unable to
38010 * verify the presence of the remote endpoint, it will automatically close
38013 * This option is only functional on certain kinds of sockets. (Notably,
38014 * %G_SOCKET_PROTOCOL_TCP sockets.)
38016 * The exact time between pings is system- and protocol-dependent, but will
38017 * normally be at least two hours. Most commonly, you would set this flag
38018 * on a server socket if you want to allow clients to remain idle for long
38019 * periods of time, but also want to ensure that connections are eventually
38020 * garbage-collected if clients crash or become unreachable.
38027 * g_socket_set_listen_backlog:
38028 * @socket: a #GSocket.
38029 * @backlog: the maximum number of pending connections.
38031 * Sets the maximum number of outstanding connections allowed
38032 * when listening on this socket. If more clients than this are
38033 * connecting to the socket and the application is not handling them
38034 * on time then the new connections will be refused.
38036 * Note that this must be called before g_socket_listen() and has no
38037 * effect if called after that.
38044 * g_socket_set_multicast_loopback:
38045 * @socket: a #GSocket.
38046 * @loopback: whether @socket should receive messages sent to its multicast groups from the local host
38048 * Sets whether outgoing multicast packets will be received by sockets
38049 * listening on that multicast address on the same host. This is %TRUE
38057 * g_socket_set_multicast_ttl:
38058 * @socket: a #GSocket.
38059 * @ttl: the time-to-live value for all multicast datagrams on @socket
38061 * Sets the time-to-live for outgoing multicast datagrams on @socket.
38062 * By default, this is 1, meaning that multicast packets will not leave
38063 * the local network.
38070 * g_socket_set_timeout:
38071 * @socket: a #GSocket.
38072 * @timeout: the timeout for @socket, in seconds, or 0 for none
38074 * Sets the time in seconds after which I/O operations on @socket will
38075 * time out if they have not yet completed.
38077 * On a blocking socket, this means that any blocking #GSocket
38078 * operation will time out after @timeout seconds of inactivity,
38079 * returning %G_IO_ERROR_TIMED_OUT.
38081 * On a non-blocking socket, calls to g_socket_condition_wait() will
38082 * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources
38083 * created with g_socket_create_source() will trigger after
38084 * @timeout seconds of inactivity, with the requested condition
38085 * set, at which point calling g_socket_receive(), g_socket_send(),
38086 * g_socket_check_connect_result(), etc, will fail with
38087 * %G_IO_ERROR_TIMED_OUT.
38089 * If @timeout is 0 (the default), operations will never time out
38092 * Note that if an I/O operation is interrupted by a signal, this may
38093 * cause the timeout to be reset.
38100 * g_socket_set_ttl:
38101 * @socket: a #GSocket.
38102 * @ttl: the time-to-live value for all unicast packets on @socket
38104 * Sets the time-to-live for outgoing unicast packets on @socket.
38105 * By default the platform-specific default value is used.
38112 * g_socket_shutdown:
38113 * @socket: a #GSocket
38114 * @shutdown_read: whether to shut down the read side
38115 * @shutdown_write: whether to shut down the write side
38116 * @error: #GError for error reporting, or %NULL to ignore.
38118 * Shut down part of a full-duplex connection.
38120 * If @shutdown_read is %TRUE then the receiving side of the connection
38121 * is shut down, and further reading is disallowed.
38123 * If @shutdown_write is %TRUE then the sending side of the connection
38124 * is shut down, and further writing is disallowed.
38126 * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE.
38128 * One example where this is used is graceful disconnect for TCP connections
38129 * where you close the sending side, then wait for the other side to close
38130 * the connection, thus ensuring that the other side saw all sent data.
38132 * Returns: %TRUE on success, %FALSE on error
38138 * g_socket_speaks_ipv4:
38139 * @socket: a #GSocket
38141 * Checks if a socket is capable of speaking IPv4.
38143 * IPv4 sockets are capable of speaking IPv4. On some operating systems
38144 * and under some combinations of circumstances IPv6 sockets are also
38145 * capable of speaking IPv4. See RFC 3493 section 3.7 for more
38148 * No other types of sockets are currently considered as being capable
38149 * of speaking IPv4.
38151 * Returns: %TRUE if this socket can be used with IPv4.
38157 * g_srv_target_copy:
38158 * @target: a #GSrvTarget
38162 * Returns: a copy of @target
38168 * g_srv_target_free:
38169 * @target: a #GSrvTarget
38178 * g_srv_target_get_hostname:
38179 * @target: a #GSrvTarget
38181 * Gets @target's hostname (in ASCII form; if you are going to present
38182 * this to the user, you should use g_hostname_is_ascii_encoded() to
38183 * check if it contains encoded Unicode segments, and use
38184 * g_hostname_to_unicode() to convert it if it does.)
38186 * Returns: @target's hostname
38192 * g_srv_target_get_port:
38193 * @target: a #GSrvTarget
38195 * Gets @target's port
38197 * Returns: @target's port
38203 * g_srv_target_get_priority:
38204 * @target: a #GSrvTarget
38206 * Gets @target's priority. You should not need to look at this;
38207 * #GResolver already sorts the targets according to the algorithm in
38210 * Returns: @target's priority
38216 * g_srv_target_get_weight:
38217 * @target: a #GSrvTarget
38219 * Gets @target's weight. You should not need to look at this;
38220 * #GResolver already sorts the targets according to the algorithm in
38223 * Returns: @target's weight
38229 * g_srv_target_list_sort: (skip)
38230 * @targets: a #GList of #GSrvTarget
38232 * Sorts @targets in place according to the algorithm in RFC 2782.
38234 * Returns: (transfer full): the head of the sorted list.
38240 * g_srv_target_new:
38241 * @hostname: the host that the service is running on
38242 * @port: the port that the service is running on
38243 * @priority: the target's priority
38244 * @weight: the target's weight
38246 * Creates a new #GSrvTarget with the given parameters.
38248 * You should not need to use this; normally #GSrvTarget<!-- -->s are
38249 * created by #GResolver.
38251 * Returns: a new #GSrvTarget.
38257 * g_static_resource_fini:
38258 * @static_resource: pointer to a static #GStaticResource.
38260 * Finalized a GResource initialized by g_static_resource_init ().
38262 * This is normally used by code generated by
38263 * <link linkend="glib-compile-resources">glib-compile-resources</link> and is
38264 * not typically used by other code.
38271 * g_static_resource_get_resource:
38272 * @static_resource: pointer to a static #GStaticResource.
38274 * Gets the GResource that was registred by a call to g_static_resource_init ().
38276 * This is normally used by code generated by
38277 * <link linkend="glib-compile-resources">glib-compile-resources</link> and is
38278 * not typically used by other code.
38280 * Returns: (transfer none): a #GResource.
38286 * g_static_resource_init:
38287 * @static_resource: pointer to a static #GStaticResource.
38289 * Initializes a GResource from static data using a
38292 * This is normally used by code generated by
38293 * <link linkend="glib-compile-resources">glib-compile-resources</link> and is
38294 * not typically used by other code.
38301 * g_tcp_connection_get_graceful_disconnect:
38302 * @connection: a #GTcpConnection
38304 * Checks if graceful disconnects are used. See
38305 * g_tcp_connection_set_graceful_disconnect().
38307 * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise
38313 * g_tcp_connection_set_graceful_disconnect:
38314 * @connection: a #GTcpConnection
38315 * @graceful_disconnect: Whether to do graceful disconnects or not
38317 * This enabled graceful disconnects on close. A graceful disconnect
38318 * means that we signal the receiving end that the connection is terminated
38319 * and wait for it to close the connection before closing the connection.
38321 * A graceful disconnect means that we can be sure that we successfully sent
38322 * all the outstanding data to the other end, or get an error reported.
38323 * However, it also means we have to wait for all the data to reach the
38324 * other side and for it to acknowledge this by closing the socket, which may
38325 * take a while. For this reason it is disabled by default.
38332 * g_tcp_wrapper_connection_get_base_io_stream:
38333 * @conn: a #GTcpWrapperConnection
38335 * Get's @conn's base #GIOStream
38337 * Returns: (transfer none): @conn's base #GIOStream
38342 * g_tcp_wrapper_connection_new:
38343 * @base_io_stream: the #GIOStream to wrap
38344 * @socket: the #GSocket associated with @base_io_stream
38346 * Wraps @base_io_stream and @socket together as a #GSocketConnection.
38348 * Returns: the new #GSocketConnection.
38354 * g_themed_icon_append_name:
38355 * @icon: a #GThemedIcon
38356 * @iconname: name of icon to append to list of icons from within @icon.
38358 * Append a name to the list of icons from within @icon.
38361 * Note that doing so invalidates the hash computed by prior calls
38362 * to g_icon_hash().
38368 * g_themed_icon_get_names:
38369 * @icon: a #GThemedIcon.
38371 * Gets the names of icons from within @icon.
38373 * Returns: (transfer none): a list of icon names.
38378 * g_themed_icon_new:
38379 * @iconname: a string containing an icon name.
38381 * Creates a new themed icon for @iconname.
38383 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
38388 * g_themed_icon_new_from_names:
38389 * @iconnames: (array length=len): an array of strings containing icon names.
38390 * @len: the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated
38392 * Creates a new themed icon for @iconnames.
38394 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon
38399 * g_themed_icon_new_with_default_fallbacks:
38400 * @iconname: a string containing an icon name
38402 * Creates a new themed icon for @iconname, and all the names
38403 * that can be created by shortening @iconname at '-' characters.
38405 * In the following example, @icon1 and @icon2 are equivalent:
38407 * const char *names[] = {
38408 * "gnome-dev-cdrom-audio",
38409 * "gnome-dev-cdrom",
38414 * icon1 = g_themed_icon_new_from_names (names, 4);
38415 * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
38418 * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon.
38423 * g_themed_icon_prepend_name:
38424 * @icon: a #GThemedIcon
38425 * @iconname: name of icon to prepend to list of icons from within @icon.
38427 * Prepend a name to the list of icons from within @icon.
38430 * Note that doing so invalidates the hash computed by prior calls
38431 * to g_icon_hash().
38439 * g_threaded_socket_service_new:
38440 * @max_threads: the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit
38442 * Creates a new #GThreadedSocketService with no listeners. Listeners
38443 * must be added with one of the #GSocketListener "add" methods.
38445 * Returns: a new #GSocketService.
38451 * g_tls_backend_get_certificate_type:
38452 * @backend: the #GTlsBackend
38454 * Gets the #GType of @backend's #GTlsCertificate implementation.
38458 * Returns: the #GType of @backend's #GTlsCertificate
38464 * g_tls_backend_get_client_connection_type:
38465 * @backend: the #GTlsBackend
38467 * Gets the #GType of @backend's #GTlsClientConnection implementation.
38471 * Returns: the #GType of @backend's #GTlsClientConnection
38477 * g_tls_backend_get_default:
38479 * Gets the default #GTlsBackend for the system.
38481 * Returns: (transfer none): a #GTlsBackend
38487 * g_tls_backend_get_default_database:
38488 * @backend: the #GTlsBackend
38490 * Gets the default #GTlsDatabase used to verify TLS connections.
38492 * unreffed when done.
38494 * Returns: (transfer full): the default database, which should be
38500 * g_tls_backend_get_file_database_type:
38501 * @backend: the #GTlsBackend
38503 * Gets the #GType of @backend's #GTlsFileDatabase implementation.
38505 * Returns: the #GType of backend's #GTlsFileDatabase implementation.
38511 * g_tls_backend_get_server_connection_type:
38512 * @backend: the #GTlsBackend
38514 * Gets the #GType of @backend's #GTlsServerConnection implementation.
38518 * Returns: the #GType of @backend's #GTlsServerConnection
38524 * g_tls_backend_supports_tls:
38525 * @backend: the #GTlsBackend
38527 * Checks if TLS is supported; if this returns %FALSE for the default
38528 * #GTlsBackend, it means no "real" TLS backend is available.
38530 * Returns: whether or not TLS is supported
38536 * g_tls_certificate_get_issuer:
38537 * @cert: a #GTlsCertificate
38539 * Gets the #GTlsCertificate representing @cert's issuer, if known
38541 * or %NULL if @cert is self-signed or signed with an unknown
38544 * Returns: (transfer none): The certificate of @cert's issuer,
38550 * g_tls_certificate_list_new_from_file:
38551 * @file: file containing PEM-encoded certificates to import
38552 * @error: #GError for error reporting, or %NULL to ignore.
38554 * Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded
38555 * data in @file. If @file cannot be read or parsed, the function will
38556 * return %NULL and set @error. If @file does not contain any
38557 * PEM-encoded certificates, this will return an empty list and not
38560 * #GList containing #GTlsCertificate objects. You must free the list
38561 * and its contents when you are done with it.
38563 * Returns: (element-type Gio.TlsCertificate) (transfer full): a
38569 * g_tls_certificate_new_from_file:
38570 * @file: file containing a PEM-encoded certificate to import
38571 * @error: #GError for error reporting, or %NULL to ignore.
38573 * Creates a #GTlsCertificate from the PEM-encoded data in @file. If
38574 * @file cannot be read or parsed, the function will return %NULL and
38575 * set @error. Otherwise, this behaves like
38576 * g_tls_certificate_new_from_pem().
38578 * Returns: the new certificate, or %NULL on error
38584 * g_tls_certificate_new_from_files:
38585 * @cert_file: file containing a PEM-encoded certificate to import
38586 * @key_file: file containing a PEM-encoded private key to import
38587 * @error: #GError for error reporting, or %NULL to ignore.
38589 * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
38590 * and @key_file. If either file cannot be read or parsed, the
38591 * function will return %NULL and set @error. Otherwise, this behaves
38592 * like g_tls_certificate_new_from_pem().
38594 * Returns: the new certificate, or %NULL on error
38600 * g_tls_certificate_new_from_pem:
38601 * @data: PEM-encoded certificate data
38602 * @length: the length of @data, or -1 if it's 0-terminated.
38603 * @error: #GError for error reporting, or %NULL to ignore.
38605 * Creates a new #GTlsCertificate from the PEM-encoded data in @data.
38606 * If @data includes both a certificate and a private key, then the
38607 * returned certificate will include the private key data as well. (See
38608 * the #GTlsCertificate:private-key-pem property for information about
38609 * supported formats.)
38611 * If @data includes multiple certificates, only the first one will be
38614 * Returns: the new certificate, or %NULL if @data is invalid
38620 * g_tls_certificate_verify:
38621 * @cert: a #GTlsCertificate
38622 * @identity: (allow-none): the expected peer identity
38623 * @trusted_ca: (allow-none): the certificate of a trusted authority
38625 * This verifies @cert and returns a set of #GTlsCertificateFlags
38626 * indicating any problems found with it. This can be used to verify a
38627 * certificate outside the context of making a connection, or to
38628 * check a certificate against a CA that is not part of the system
38631 * If @identity is not %NULL, @cert's name(s) will be compared against
38632 * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
38633 * value if it does not match. If @identity is %NULL, that bit will
38634 * never be set in the return value.
38636 * If @trusted_ca is not %NULL, then @cert (or one of the certificates
38637 * in its chain) must be signed by it, or else
38638 * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
38639 * @trusted_ca is %NULL, that bit will never be set in the return
38642 * (All other #GTlsCertificateFlags values will always be set or unset
38645 * Returns: the appropriate #GTlsCertificateFlags
38651 * g_tls_client_connection_get_accepted_cas:
38652 * @conn: the #GTlsClientConnection
38654 * Gets the list of distinguished names of the Certificate Authorities
38655 * that the server will accept certificates from. This will be set
38656 * during the TLS handshake if the server requests a certificate.
38657 * Otherwise, it will be %NULL.
38659 * Each item in the list is a #GByteArray which contains the complete
38660 * subject DN of the certificate authority.
38662 * CA DNs. You should unref each element with g_byte_array_unref() and then
38663 * the free the list with g_list_free().
38665 * Returns: (element-type GByteArray) (transfer full): the list of
38671 * g_tls_client_connection_get_server_identity:
38672 * @conn: the #GTlsClientConnection
38674 * Gets @conn's expected server identity
38676 * expected server identity, or %NULL if the expected identity is not
38679 * Returns: (transfer none): a #GSocketConnectable describing the
38685 * g_tls_client_connection_get_use_ssl3:
38686 * @conn: the #GTlsClientConnection
38688 * Gets whether @conn will use SSL 3.0 rather than the
38689 * highest-supported version of TLS; see
38690 * g_tls_client_connection_set_use_ssl3().
38692 * Returns: whether @conn will use SSL 3.0
38698 * g_tls_client_connection_get_validation_flags:
38699 * @conn: the #GTlsClientConnection
38701 * Gets @conn's validation flags
38703 * Returns: the validation flags
38709 * g_tls_client_connection_new:
38710 * @base_io_stream: the #GIOStream to wrap
38711 * @server_identity: (allow-none): the expected identity of the server
38712 * @error: #GError for error reporting, or %NULL to ignore.
38714 * Creates a new #GTlsClientConnection wrapping @base_io_stream (which
38715 * must have pollable input and output streams) which is assumed to
38716 * communicate with the server identified by @server_identity.
38718 * #GTlsClientConnection, or %NULL on error
38720 * Returns: (transfer full) (type GTlsClientConnection): the new
38726 * g_tls_client_connection_set_server_identity:
38727 * @conn: the #GTlsClientConnection
38728 * @identity: a #GSocketConnectable describing the expected server identity
38730 * Sets @conn's expected server identity, which is used both to tell
38731 * servers on virtual hosts which certificate to present, and also
38732 * to let @conn know what name to look for in the certificate when
38733 * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
38740 * g_tls_client_connection_set_use_ssl3:
38741 * @conn: the #GTlsClientConnection
38742 * @use_ssl3: whether to use SSL 3.0
38744 * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
38745 * trying to properly negotiate the right version of TLS or SSL to use.
38746 * This can be used when talking to servers that do not implement the
38747 * fallbacks correctly and which will therefore fail to handshake with
38748 * a "modern" TLS handshake attempt.
38755 * g_tls_client_connection_set_validation_flags:
38756 * @conn: the #GTlsClientConnection
38757 * @flags: the #GTlsCertificateFlags to use
38759 * Sets @conn's validation flags, to override the default set of
38760 * checks performed when validating a server certificate. By default,
38761 * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
38768 * g_tls_connection_emit_accept_certificate:
38769 * @conn: a #GTlsConnection
38770 * @peer_cert: the peer's #GTlsCertificate
38771 * @errors: the problems with @peer_cert
38773 * Used by #GTlsConnection implementations to emit the
38774 * #GTlsConnection::accept-certificate signal.
38776 * %TRUE to accept @peer_cert
38778 * Returns: %TRUE if one of the signal handlers has returned
38784 * g_tls_connection_get_certificate:
38785 * @conn: a #GTlsConnection
38787 * Gets @conn's certificate, as set by
38788 * g_tls_connection_set_certificate().
38790 * Returns: (transfer none): @conn's certificate, or %NULL
38796 * g_tls_connection_get_database:
38797 * @conn: a #GTlsConnection
38799 * Gets the certificate database that @conn uses to verify
38800 * peer certificates. See g_tls_connection_set_database().
38802 * Returns: (transfer none): the certificate database that @conn uses or %NULL
38808 * g_tls_connection_get_interaction:
38809 * @conn: a connection
38811 * Get the object that will be used to interact with the user. It will be used
38812 * for things like prompting the user for passwords. If %NULL is returned, then
38813 * no user interaction will occur for this connection.
38815 * Returns: (transfer none): The interaction object.
38821 * g_tls_connection_get_peer_certificate:
38822 * @conn: a #GTlsConnection
38824 * Gets @conn's peer's certificate after the handshake has completed.
38825 * (It is not set during the emission of
38826 * #GTlsConnection::accept-certificate.)
38828 * Returns: (transfer none): @conn's peer's certificate, or %NULL
38834 * g_tls_connection_get_peer_certificate_errors:
38835 * @conn: a #GTlsConnection
38837 * Gets the errors associated with validating @conn's peer's
38838 * certificate, after the handshake has completed. (It is not set
38839 * during the emission of #GTlsConnection::accept-certificate.)
38841 * Returns: @conn's peer's certificate errors
38847 * g_tls_connection_get_rehandshake_mode:
38848 * @conn: a #GTlsConnection
38850 * Gets @conn rehandshaking mode. See
38851 * g_tls_connection_set_rehandshake_mode() for details.
38853 * Returns: @conn's rehandshaking mode
38859 * g_tls_connection_get_require_close_notify:
38860 * @conn: a #GTlsConnection
38862 * Tests whether or not @conn expects a proper TLS close notification
38863 * when the connection is closed. See
38864 * g_tls_connection_set_require_close_notify() for details.
38868 * Returns: %TRUE if @conn requires a proper TLS close
38874 * g_tls_connection_get_use_system_certdb:
38875 * @conn: a #GTlsConnection
38877 * Gets whether @conn uses the system certificate database to verify
38878 * peer certificates. See g_tls_connection_set_use_system_certdb().
38880 * Returns: whether @conn uses the system certificate database
38881 * Deprecated: 2.30: Use g_tls_connection_get_database() instead
38886 * g_tls_connection_handshake:
38887 * @conn: a #GTlsConnection
38888 * @cancellable: a #GCancellable, or %NULL
38889 * @error: a #GError, or %NULL
38891 * Attempts a TLS handshake on @conn.
38893 * On the client side, it is never necessary to call this method;
38894 * although the connection needs to perform a handshake after
38895 * connecting (or after sending a "STARTTLS"-type command) and may
38896 * need to rehandshake later if the server requests it,
38897 * #GTlsConnection will handle this for you automatically when you try
38898 * to send or receive data on the connection. However, you can call
38899 * g_tls_connection_handshake() manually if you want to know for sure
38900 * whether the initial handshake succeeded or failed (as opposed to
38901 * just immediately trying to write to @conn's output stream, in which
38902 * case if it fails, it may not be possible to tell if it failed
38903 * before or after completing the handshake).
38905 * Likewise, on the server side, although a handshake is necessary at
38906 * the beginning of the communication, you do not need to call this
38907 * function explicitly unless you want clearer error reporting.
38908 * However, you may call g_tls_connection_handshake() later on to
38909 * renegotiate parameters (encryption methods, etc) with the client.
38911 * #GTlsConnection::accept_certificate may be emitted during the
38914 * Returns: success or failure
38920 * g_tls_connection_handshake_async:
38921 * @conn: a #GTlsConnection
38922 * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request.
38923 * @cancellable: a #GCancellable, or %NULL
38924 * @callback: callback to call when the handshake is complete
38925 * @user_data: the data to pass to the callback function
38927 * Asynchronously performs a TLS handshake on @conn. See
38928 * g_tls_connection_handshake() for more information.
38935 * g_tls_connection_handshake_finish:
38936 * @conn: a #GTlsConnection
38937 * @result: a #GAsyncResult.
38938 * @error: a #GError pointer, or %NULL
38940 * Finish an asynchronous TLS handshake operation. See
38941 * g_tls_connection_handshake() for more information.
38943 * case @error will be set.
38945 * Returns: %TRUE on success, %FALSE on failure, in which
38951 * g_tls_connection_set_certificate:
38952 * @conn: a #GTlsConnection
38953 * @certificate: the certificate to use for @conn
38955 * This sets the certificate that @conn will present to its peer
38956 * during the TLS handshake. For a #GTlsServerConnection, it is
38957 * mandatory to set this, and that will normally be done at construct
38960 * For a #GTlsClientConnection, this is optional. If a handshake fails
38961 * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server
38962 * requires a certificate, and if you try connecting again, you should
38963 * call this method first. You can call
38964 * g_tls_client_connection_get_accepted_cas() on the failed connection
38965 * to get a list of Certificate Authorities that the server will
38966 * accept certificates from.
38968 * (It is also possible that a server will allow the connection with
38969 * or without a certificate; in that case, if you don't provide a
38970 * certificate, you can tell that the server requested one by the fact
38971 * that g_tls_client_connection_get_accepted_cas() will return
38979 * g_tls_connection_set_database:
38980 * @conn: a #GTlsConnection
38981 * @database: a #GTlsDatabase
38983 * Sets the certificate database that is used to verify peer certificates.
38984 * This is set to the default database by default. See
38985 * g_tls_backend_get_default_database(). If set to %NULL, then
38986 * peer certificate validation will always set the
38987 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
38988 * #GTlsConnection::accept-certificate will always be emitted on
38989 * client-side connections, unless that bit is not set in
38990 * #GTlsClientConnection:validation-flags).
38997 * g_tls_connection_set_interaction:
38998 * @conn: a connection
38999 * @interaction: (allow-none): an interaction object, or %NULL
39001 * Set the object that will be used to interact with the user. It will be used
39002 * for things like prompting the user for passwords.
39004 * The @interaction argument will normally be a derived subclass of
39005 * #GTlsInteraction. %NULL can also be provided if no user interaction
39006 * should occur for this connection.
39013 * g_tls_connection_set_rehandshake_mode:
39014 * @conn: a #GTlsConnection
39015 * @mode: the rehandshaking mode
39017 * Sets how @conn behaves with respect to rehandshaking requests.
39019 * %G_TLS_REHANDSHAKE_NEVER means that it will never agree to
39020 * rehandshake after the initial handshake is complete. (For a client,
39021 * this means it will refuse rehandshake requests from the server, and
39022 * for a server, this means it will close the connection with an error
39023 * if the client attempts to rehandshake.)
39025 * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
39026 * rehandshake only if the other end of the connection supports the
39027 * TLS <literal>renegotiation_info</literal> extension. This is the
39028 * default behavior, but means that rehandshaking will not work
39029 * against older implementations that do not support that extension.
39031 * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
39032 * rehandshaking even without the
39033 * <literal>renegotiation_info</literal> extension. On the server side
39034 * in particular, this is not recommended, since it leaves the server
39035 * open to certain attacks. However, this mode is necessary if you
39036 * need to allow renegotiation with older client software.
39043 * g_tls_connection_set_require_close_notify:
39044 * @conn: a #GTlsConnection
39045 * @require_close_notify: whether or not to require close notification
39047 * Sets whether or not @conn expects a proper TLS close notification
39048 * before the connection is closed. If this is %TRUE (the default),
39049 * then @conn will expect to receive a TLS close notification from its
39050 * peer before the connection is closed, and will return a
39051 * %G_TLS_ERROR_EOF error if the connection is closed without proper
39052 * notification (since this may indicate a network error, or
39053 * man-in-the-middle attack).
39055 * In some protocols, the application will know whether or not the
39056 * connection was closed cleanly based on application-level data
39057 * (because the application-level data includes a length field, or is
39058 * somehow self-delimiting); in this case, the close notify is
39059 * redundant and sometimes omitted. (TLS 1.1 explicitly allows this;
39060 * in TLS 1.0 it is technically an error, but often done anyway.) You
39061 * can use g_tls_connection_set_require_close_notify() to tell @conn
39062 * to allow an "unannounced" connection close, in which case the close
39063 * will show up as a 0-length read, as in a non-TLS
39064 * #GSocketConnection, and it is up to the application to check that
39065 * the data has been fully received.
39067 * Note that this only affects the behavior when the peer closes the
39068 * connection; when the application calls g_io_stream_close() itself
39069 * on @conn, this will send a close notification regardless of the
39070 * setting of this property. If you explicitly want to do an unclean
39071 * close, you can close @conn's #GTlsConnection:base-io-stream rather
39072 * than closing @conn itself.
39079 * g_tls_connection_set_use_system_certdb:
39080 * @conn: a #GTlsConnection
39081 * @use_system_certdb: whether to use the system certificate database
39083 * Sets whether @conn uses the system certificate database to verify
39084 * peer certificates. This is %TRUE by default. If set to %FALSE, then
39085 * peer certificate validation will always set the
39086 * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
39087 * #GTlsConnection::accept-certificate will always be emitted on
39088 * client-side connections, unless that bit is not set in
39089 * #GTlsClientConnection:validation-flags).
39091 * Deprecated: 2.30: Use g_tls_connection_set_database() instead
39096 * g_tls_database_create_certificate_handle:
39097 * @self: a #GTlsDatabase
39098 * @certificate: certificate for which to create a handle.
39100 * Create a handle string for the certificate. The database will only be able
39101 * to create a handle for certificates that originate from the database. In
39102 * cases where the database cannot create a handle for a certificate, %NULL
39103 * will be returned.
39105 * This handle should be stable across various instances of the application,
39106 * and between applications. If a certificate is modified in the database,
39107 * then it is not guaranteed that this handle will continue to point to it.
39109 * Returns: (allow-none): a newly allocated string containing the handle.
39115 * g_tls_database_lookup_certificate_for_handle:
39116 * @self: a #GTlsDatabase
39117 * @handle: a certificate handle
39118 * @interaction: (allow-none): used to interact with the user if necessary
39119 * @flags: Flags which affect the lookup.
39120 * @cancellable: (allow-none): a #GCancellable, or %NULL
39121 * @error: (allow-none): a #GError, or %NULL
39123 * Lookup a certificate by its handle.
39125 * The handle should have been created by calling
39126 * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
39127 * the same TLS backend. The handle is designed to remain valid across
39128 * instantiations of the database.
39130 * If the handle is no longer valid, or does not point to a certificate in
39131 * this database, then %NULL will be returned.
39133 * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
39134 * the lookup operation asynchronously.
39136 * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
39138 * Returns: (transfer full) (allow-none): a newly allocated
39144 * g_tls_database_lookup_certificate_for_handle_async:
39145 * @self: a #GTlsDatabase
39146 * @handle: a certificate handle
39147 * @interaction: (allow-none): used to interact with the user if necessary
39148 * @flags: Flags which affect the lookup.
39149 * @cancellable: (allow-none): a #GCancellable, or %NULL
39150 * @callback: callback to call when the operation completes
39151 * @user_data: the data to pass to the callback function
39153 * Asynchronously lookup a certificate by its handle in the database. See
39154 * g_tls_database_lookup_certificate_for_handle() for more information.
39161 * g_tls_database_lookup_certificate_for_handle_finish:
39162 * @self: a #GTlsDatabase
39163 * @result: a #GAsyncResult.
39164 * @error: a #GError pointer, or %NULL
39166 * Finish an asynchronous lookup of a certificate by its handle. See
39167 * g_tls_database_lookup_certificate_handle() for more information.
39169 * If the handle is no longer valid, or does not point to a certificate in
39170 * this database, then %NULL will be returned.
39172 * Use g_object_unref() to release the certificate.
39174 * Returns: (transfer full): a newly allocated #GTlsCertificate object.
39180 * g_tls_database_lookup_certificate_issuer:
39181 * @self: a #GTlsDatabase
39182 * @certificate: a #GTlsCertificate
39183 * @interaction: (allow-none): used to interact with the user if necessary
39184 * @flags: flags which affect the lookup operation
39185 * @cancellable: (allow-none): a #GCancellable, or %NULL
39186 * @error: (allow-none): a #GError, or %NULL
39188 * Lookup the issuer of @certificate in the database.
39190 * The %issuer property
39191 * of @certificate is not modified, and the two certificates are not hooked
39194 * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
39195 * the lookup operation asynchronously.
39197 * or %NULL. Use g_object_unref() to release the certificate.
39199 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
39205 * g_tls_database_lookup_certificate_issuer_async:
39206 * @self: a #GTlsDatabase
39207 * @certificate: a #GTlsCertificate
39208 * @interaction: (allow-none): used to interact with the user if necessary
39209 * @flags: flags which affect the lookup operation
39210 * @cancellable: (allow-none): a #GCancellable, or %NULL
39211 * @callback: callback to call when the operation completes
39212 * @user_data: the data to pass to the callback function
39214 * Asynchronously lookup the issuer of @certificate in the database. See
39215 * g_tls_database_lookup_certificate_issuer() for more information.
39222 * g_tls_database_lookup_certificate_issuer_finish:
39223 * @self: a #GTlsDatabase
39224 * @result: a #GAsyncResult.
39225 * @error: a #GError pointer, or %NULL
39227 * Finish an asynchronous lookup issuer operation. See
39228 * g_tls_database_lookup_certificate_issuer() for more information.
39230 * or %NULL. Use g_object_unref() to release the certificate.
39232 * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
39238 * g_tls_database_lookup_certificates_issued_by:
39239 * @self: a #GTlsDatabase
39240 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
39241 * @interaction: (allow-none): used to interact with the user if necessary
39242 * @flags: Flags which affect the lookup operation.
39243 * @cancellable: (allow-none): a #GCancellable, or %NULL
39244 * @error: (allow-none): a #GError, or %NULL
39246 * Lookup certificates issued by this issuer in the database.
39248 * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
39249 * the lookup operation asynchronously.
39251 * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
39253 * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
39259 * g_tls_database_lookup_certificates_issued_by_async:
39260 * @self: a #GTlsDatabase
39261 * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN.
39262 * @interaction: (allow-none): used to interact with the user if necessary
39263 * @flags: Flags which affect the lookup operation.
39264 * @cancellable: (allow-none): a #GCancellable, or %NULL
39265 * @callback: callback to call when the operation completes
39266 * @user_data: the data to pass to the callback function
39268 * Asynchronously lookup certificates issued by this issuer in the database. See
39269 * g_tls_database_lookup_certificates_issued_by() for more information.
39271 * The database may choose to hold a reference to the issuer byte array for the duration
39272 * of of this asynchronous operation. The byte array should not be modified during
39280 * g_tls_database_lookup_certificates_issued_by_finish:
39281 * @self: a #GTlsDatabase
39282 * @result: a #GAsyncResult.
39283 * @error: a #GError pointer, or %NULL
39285 * Finish an asynchronous lookup of certificates. See
39286 * g_tls_database_lookup_certificates_issued_by() for more information.
39288 * Use g_object_unref() on each certificate, and g_list_free() on the release the list.
39290 * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects.
39296 * g_tls_database_verify_chain:
39297 * @self: a #GTlsDatabase
39298 * @chain: a #GTlsCertificate chain
39299 * @purpose: the purpose that this certificate chain will be used for.
39300 * @identity: (allow-none): the expected peer identity
39301 * @interaction: (allow-none): used to interact with the user if necessary
39302 * @flags: additional verify flags
39303 * @cancellable: (allow-none): a #GCancellable, or %NULL
39304 * @error: (allow-none): a #GError, or %NULL
39306 * Verify's a certificate chain after looking up and adding any missing
39307 * certificates to the chain.
39309 * @chain is a chain of #GTlsCertificate objects each pointing to the next
39310 * certificate in the chain by its %issuer property. The chain may initially
39311 * consist of one or more certificates. After the verification process is
39312 * complete, @chain may be modified by adding missing certificates, or removing
39313 * extra certificates. If a certificate anchor was found, then it is added to
39316 * @purpose describes the purpose (or usage) for which the certificate
39317 * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
39318 * which means that the certificate is being used to authenticate a server
39319 * (and we are acting as the client).
39321 * The @identity is used to check for pinned certificates (trust exceptions)
39322 * in the database. These will override the normal verification process on a
39323 * host by host basis.
39325 * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
39328 * This function can block, use g_tls_database_verify_chain_async() to perform
39329 * the verification operation asynchronously.
39331 * result of verification.
39333 * Returns: the appropriate #GTlsCertificateFlags which represents the
39339 * g_tls_database_verify_chain_async:
39340 * @self: a #GTlsDatabase
39341 * @chain: a #GTlsCertificate chain
39342 * @purpose: the purpose that this certificate chain will be used for.
39343 * @identity: (allow-none): the expected peer identity
39344 * @interaction: (allow-none): used to interact with the user if necessary
39345 * @flags: additional verify flags
39346 * @cancellable: (allow-none): a #GCancellable, or %NULL
39347 * @callback: callback to call when the operation completes
39348 * @user_data: the data to pass to the callback function
39350 * Asynchronously verify's a certificate chain after looking up and adding
39351 * any missing certificates to the chain. See g_tls_database_verify_chain()
39352 * for more information.
39359 * g_tls_database_verify_chain_finish:
39360 * @self: a #GTlsDatabase
39361 * @result: a #GAsyncResult.
39362 * @error: a #GError pointer, or %NULL
39364 * Finish an asynchronous verify chain operation. See
39365 * g_tls_database_verify_chain() for more information. *
39366 * result of verification.
39368 * Returns: the appropriate #GTlsCertificateFlags which represents the
39374 * g_tls_error_quark:
39376 * Gets the TLS error quark.
39378 * Returns: a #GQuark.
39384 * g_tls_file_database_new:
39385 * @anchors: filename of anchor certificate authorities.
39386 * @error: #GError for error reporting, or %NULL to ignore.
39388 * Creates a new #GTlsFileDatabase which uses anchor certificate authorities
39389 * in @anchors to verify certificate chains.
39391 * The certificates in @anchors must be PEM encoded.
39393 * #GTlsFileDatabase, or %NULL on error
39395 * Returns: (transfer full) (type GTlsFileDatabase): the new
39401 * g_tls_interaction_ask_password:
39402 * @interaction: a #GTlsInteraction object
39403 * @password: a #GTlsPassword object
39404 * @cancellable: an optional #GCancellable cancellation object
39405 * @error: an optional location to place an error on failure
39407 * Run synchronous interaction to ask the user for a password. In general,
39408 * g_tls_interaction_invoke_ask_password() should be used instead of this
39411 * Derived subclasses usually implement a password prompt, although they may
39412 * also choose to provide a password from elsewhere. The @password value will
39413 * be filled in and then @callback will be called. Alternatively the user may
39414 * abort this password request, which will usually abort the TLS connection.
39416 * If the interaction is cancelled by the cancellation object, or by the
39417 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
39418 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
39419 * not support immediate cancellation.
39421 * Returns: The status of the ask password interaction.
39427 * g_tls_interaction_ask_password_async:
39428 * @interaction: a #GTlsInteraction object
39429 * @password: a #GTlsPassword object
39430 * @cancellable: an optional #GCancellable cancellation object
39431 * @callback: (allow-none): will be called when the interaction completes
39432 * @user_data: (allow-none): data to pass to the @callback
39434 * Run asynchronous interaction to ask the user for a password. In general,
39435 * g_tls_interaction_invoke_ask_password() should be used instead of this
39438 * Derived subclasses usually implement a password prompt, although they may
39439 * also choose to provide a password from elsewhere. The @password value will
39440 * be filled in and then @callback will be called. Alternatively the user may
39441 * abort this password request, which will usually abort the TLS connection.
39443 * If the interaction is cancelled by the cancellation object, or by the
39444 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
39445 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
39446 * not support immediate cancellation.
39448 * Certain implementations may not support immediate cancellation.
39455 * g_tls_interaction_ask_password_finish:
39456 * @interaction: a #GTlsInteraction object
39457 * @result: the result passed to the callback
39458 * @error: an optional location to place an error on failure
39460 * Complete an ask password user interaction request. This should be once
39461 * the g_tls_interaction_ask_password_async() completion callback is called.
39463 * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed
39464 * to g_tls_interaction_ask_password() will have its password filled in.
39466 * If the interaction is cancelled by the cancellation object, or by the
39467 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
39468 * contains a %G_IO_ERROR_CANCELLED error code.
39470 * Returns: The status of the ask password interaction.
39476 * g_tls_interaction_invoke_ask_password:
39477 * @interaction: a #GTlsInteraction object
39478 * @password: a #GTlsPassword object
39479 * @cancellable: an optional #GCancellable cancellation object
39480 * @error: an optional location to place an error on failure
39482 * Invoke the interaction to ask the user for a password. It invokes this
39483 * interaction in the main loop, specifically the #GMainContext returned by
39484 * g_main_context_get_thread_default() when the interaction is created. This
39485 * is called by called by #GTlsConnection or #GTlsDatabase to ask the user
39488 * Derived subclasses usually implement a password prompt, although they may
39489 * also choose to provide a password from elsewhere. The @password value will
39490 * be filled in and then @callback will be called. Alternatively the user may
39491 * abort this password request, which will usually abort the TLS connection.
39493 * The implementation can either be a synchronous (eg: modal dialog) or an
39494 * asynchronous one (eg: modeless dialog). This function will take care of
39495 * calling which ever one correctly.
39497 * If the interaction is cancelled by the cancellation object, or by the
39498 * user then %G_TLS_INTERACTION_FAILED will be returned with an error that
39499 * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may
39500 * not support immediate cancellation.
39502 * Returns: The status of the ask password interaction.
39508 * g_tls_password_get_description:
39509 * @password: a #GTlsPassword object
39511 * Get a description string about what the password will be used for.
39513 * Returns: The description of the password.
39519 * g_tls_password_get_flags:
39520 * @password: a #GTlsPassword object
39522 * Get flags about the password.
39524 * Returns: The flags about the password.
39530 * g_tls_password_get_value:
39531 * @password: a #GTlsPassword object
39532 * @length: (allow-none): location to place the length of the password.
39534 * Get the password value. If @length is not %NULL then it will be
39535 * filled in with the length of the password value. (Note that the
39536 * password value is not nul-terminated, so you can only pass %NULL
39537 * for @length in contexts where you know the password will have a
39538 * certain fixed length.)
39540 * Returns: The password value (owned by the password object).
39546 * g_tls_password_get_warning:
39547 * @password: a #GTlsPassword object
39549 * Get a user readable translated warning. Usually this warning is a
39550 * representation of the password flags returned from
39551 * g_tls_password_get_flags().
39553 * Returns: The warning.
39559 * g_tls_password_new:
39560 * @flags: the password flags
39561 * @description: description of what the password is for
39563 * Create a new #GTlsPassword object.
39565 * Returns: (transfer full): The newly allocated password object
39570 * g_tls_password_set_description:
39571 * @password: a #GTlsPassword object
39572 * @description: The description of the password
39574 * Set a description string about what the password will be used for.
39581 * g_tls_password_set_flags:
39582 * @password: a #GTlsPassword object
39583 * @flags: The flags about the password
39585 * Set flags about the password.
39592 * g_tls_password_set_value:
39593 * @password: a #GTlsPassword object
39594 * @value: the new password value
39595 * @length: the length of the password, or -1
39597 * Set the value for this password. The @value will be copied by the password
39600 * Specify the @length, for a non-nul-terminated password. Pass -1 as
39601 * @length if using a nul-terminated password, and @length will be
39602 * calculated automatically. (Note that the terminating nul is not
39603 * considered part of the password in this case.)
39610 * g_tls_password_set_value_full:
39611 * @password: a #GTlsPassword object
39612 * @value: the value for the password
39613 * @length: the length of the password, or -1
39614 * @destroy: (allow-none): a function to use to free the password.
39616 * Provide the value for this password.
39618 * The @value will be owned by the password object, and later freed using
39619 * the @destroy function callback.
39621 * Specify the @length, for a non-nul-terminated password. Pass -1 as
39622 * @length if using a nul-terminated password, and @length will be
39623 * calculated automatically. (Note that the terminating nul is not
39624 * considered part of the password in this case.)
39626 * Virtual: set_value
39632 * g_tls_password_set_warning:
39633 * @password: a #GTlsPassword object
39634 * @warning: The user readable warning
39636 * Set a user readable translated warning. Usually this warning is a
39637 * representation of the password flags returned from
39638 * g_tls_password_get_flags().
39645 * g_tls_server_connection_new:
39646 * @base_io_stream: the #GIOStream to wrap
39647 * @certificate: (allow-none): the default server certificate, or %NULL
39648 * @error: #GError for error reporting, or %NULL to ignore.
39650 * Creates a new #GTlsServerConnection wrapping @base_io_stream (which
39651 * must have pollable input and output streams).
39653 * #GTlsServerConnection, or %NULL on error
39655 * Returns: (transfer full) (type GTlsServerConnection): the new
39662 * @struct_type: the type of the elements to allocate
39663 * @n_structs: the number of elements to allocate
39665 * Attempts to allocate @n_structs elements of type @struct_type, and returns
39666 * %NULL on failure. Contrast with g_new(), which aborts the program on failure.
39667 * The returned pointer is cast to a pointer to the given type.
39668 * The function returns %NULL when @n_structs is 0 of if an overflow occurs.
39671 * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
39677 * @struct_type: the type of the elements to allocate
39678 * @n_structs: the number of elements to allocate
39680 * Attempts to allocate @n_structs elements of type @struct_type, initialized
39681 * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
39682 * the program on failure.
39683 * The returned pointer is cast to a pointer to the given type.
39684 * The function returns %NULL when @n_structs is 0 of if an overflow occurs.
39687 * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type
39693 * @struct_type: the type of the elements to allocate
39694 * @mem: the currently allocated memory
39695 * @n_structs: the number of elements to allocate
39697 * Attempts to reallocate the memory pointed to by @mem, so that it now has
39698 * space for @n_structs elements of type @struct_type, and returns %NULL on
39699 * failure. Contrast with g_renew(), which aborts the program on failure.
39700 * It returns the new address of the memory, which may have been moved.
39701 * The function returns %NULL if an overflow occurs.
39704 * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type
39709 * g_unix_connection_receive_credentials:
39710 * @connection: A #GUnixConnection.
39711 * @cancellable: (allow-none): A #GCancellable or %NULL.
39712 * @error: Return location for error or %NULL.
39714 * Receives credentials from the sending end of the connection. The
39715 * sending end has to call g_unix_connection_send_credentials() (or
39716 * similar) for this to work.
39718 * As well as reading the credentials this also reads (and discards) a
39719 * single byte from the stream, as this is required for credentials
39720 * passing to work on some implementations.
39722 * Other ways to exchange credentials with a foreign peer includes the
39723 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
39725 * g_object_unref()), %NULL if @error is set.
39727 * Returns: (transfer full): Received credentials on success (free with
39733 * g_unix_connection_receive_credentials_async:
39734 * @connection: A #GUnixConnection.
39735 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
39736 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
39737 * @user_data: (closure): the data to pass to callback function
39739 * Asynchronously receive credentials.
39741 * For more details, see g_unix_connection_receive_credentials() which is
39742 * the synchronous version of this call.
39744 * When the operation is finished, @callback will be called. You can then call
39745 * g_unix_connection_receive_credentials_finish() to get the result of the operation.
39752 * g_unix_connection_receive_credentials_finish:
39753 * @connection: A #GUnixConnection.
39754 * @result: a #GAsyncResult.
39755 * @error: a #GError, or %NULL
39757 * Finishes an asynchronous receive credentials operation started with
39758 * g_unix_connection_receive_credentials_async().
39760 * Free the returned object with g_object_unref().
39762 * Returns: (transfer full): a #GCredentials, or %NULL on error.
39768 * g_unix_connection_receive_fd:
39769 * @connection: a #GUnixConnection
39770 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
39771 * @error: (allow-none): #GError for error reporting, or %NULL to ignore
39773 * Receives a file descriptor from the sending end of the connection.
39774 * The sending end has to call g_unix_connection_send_fd() for this
39777 * As well as reading the fd this also reads a single byte from the
39778 * stream, as this is required for fd passing to work on some
39781 * Returns: a file descriptor on success, -1 on error.
39787 * g_unix_connection_send_credentials:
39788 * @connection: A #GUnixConnection.
39789 * @cancellable: (allow-none): A #GCancellable or %NULL.
39790 * @error: Return location for error or %NULL.
39792 * Passes the credentials of the current user the receiving side
39793 * of the connection. The receiving end has to call
39794 * g_unix_connection_receive_credentials() (or similar) to accept the
39797 * As well as sending the credentials this also writes a single NUL
39798 * byte to the stream, as this is required for credentials passing to
39799 * work on some implementations.
39801 * Other ways to exchange credentials with a foreign peer includes the
39802 * #GUnixCredentialsMessage type and g_socket_get_credentials() function.
39804 * Returns: %TRUE on success, %FALSE if @error is set.
39810 * g_unix_connection_send_credentials_async:
39811 * @connection: A #GUnixConnection.
39812 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
39813 * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
39814 * @user_data: (closure): the data to pass to callback function
39816 * Asynchronously send credentials.
39818 * For more details, see g_unix_connection_send_credentials() which is
39819 * the synchronous version of this call.
39821 * When the operation is finished, @callback will be called. You can then call
39822 * g_unix_connection_send_credentials_finish() to get the result of the operation.
39829 * g_unix_connection_send_credentials_finish:
39830 * @connection: A #GUnixConnection.
39831 * @result: a #GAsyncResult.
39832 * @error: a #GError, or %NULL
39834 * Finishes an asynchronous send credentials operation started with
39835 * g_unix_connection_send_credentials_async().
39837 * Returns: %TRUE if the operation was successful, otherwise %FALSE.
39843 * g_unix_connection_send_fd:
39844 * @connection: a #GUnixConnection
39845 * @fd: a file descriptor
39846 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
39847 * @error: (allow-none): #GError for error reporting, or %NULL to ignore.
39849 * Passes a file descriptor to the receiving side of the
39850 * connection. The receiving end has to call g_unix_connection_receive_fd()
39851 * to accept the file descriptor.
39853 * As well as sending the fd this also writes a single byte to the
39854 * stream, as this is required for fd passing to work on some
39857 * Returns: a %TRUE on success, %NULL on error.
39863 * g_unix_credentials_message_get_credentials:
39864 * @message: A #GUnixCredentialsMessage.
39866 * Gets the credentials stored in @message.
39868 * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message.
39874 * g_unix_credentials_message_is_supported:
39876 * Checks if passing #GCredentials on a #GSocket is supported on this platform.
39878 * Returns: %TRUE if supported, %FALSE otherwise
39884 * g_unix_credentials_message_new:
39886 * Creates a new #GUnixCredentialsMessage with credentials matching the current processes.
39888 * Returns: a new #GUnixCredentialsMessage
39894 * g_unix_credentials_message_new_with_credentials:
39895 * @credentials: A #GCredentials object.
39897 * Creates a new #GUnixCredentialsMessage holding @credentials.
39899 * Returns: a new #GUnixCredentialsMessage
39905 * g_unix_fd_list_append:
39906 * @list: a #GUnixFDList
39907 * @fd: a valid open file descriptor
39908 * @error: a #GError pointer
39910 * Adds a file descriptor to @list.
39912 * The file descriptor is duplicated using dup(). You keep your copy
39913 * of the descriptor and the copy contained in @list will be closed
39914 * when @list is finalized.
39916 * A possible cause of failure is exceeding the per-process or
39917 * system-wide file descriptor limit.
39919 * The index of the file descriptor in the list is returned. If you use
39920 * this index with g_unix_fd_list_get() then you will receive back a
39921 * duplicated copy of the same file descriptor.
39923 * (and @error is set)
39925 * Returns: the index of the appended fd in case of success, else -1
39931 * g_unix_fd_list_get:
39932 * @list: a #GUnixFDList
39933 * @index_: the index into the list
39934 * @error: a #GError pointer
39936 * Gets a file descriptor out of @list.
39938 * @index_ specifies the index of the file descriptor to get. It is a
39939 * programmer error for @index_ to be out of range; see
39940 * g_unix_fd_list_get_length().
39942 * The file descriptor is duplicated using dup() and set as
39943 * close-on-exec before being returned. You must call close() on it
39944 * when you are done.
39946 * A possible cause of failure is exceeding the per-process or
39947 * system-wide file descriptor limit.
39949 * Returns: the file descriptor, or -1 in case of error
39955 * g_unix_fd_list_get_length:
39956 * @list: a #GUnixFDList
39958 * Gets the length of @list (ie: the number of file descriptors
39959 * contained within).
39961 * Returns: the length of @list
39967 * g_unix_fd_list_new:
39969 * Creates a new #GUnixFDList containing no file descriptors.
39971 * Returns: a new #GUnixFDList
39977 * g_unix_fd_list_new_from_array:
39978 * @fds: (array length=n_fds): the initial list of file descriptors
39979 * @n_fds: the length of #fds, or -1
39981 * Creates a new #GUnixFDList containing the file descriptors given in
39982 * @fds. The file descriptors become the property of the new list and
39983 * may no longer be used by the caller. The array itself is owned by
39986 * Each file descriptor in the array should be set to close-on-exec.
39988 * If @n_fds is -1 then @fds must be terminated with -1.
39990 * Returns: a new #GUnixFDList
39996 * g_unix_fd_list_peek_fds:
39997 * @list: a #GUnixFDList
39998 * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL
40000 * Returns the array of file descriptors that is contained in this
40003 * After this call, the descriptors remain the property of @list. The
40004 * caller must not close them and must not free the array. The array is
40005 * valid only until @list is changed in any way.
40007 * If @length is non-%NULL then it is set to the number of file
40008 * descriptors in the returned array. The returned array is also
40009 * terminated with -1.
40011 * This function never returns %NULL. In case there are no file
40012 * descriptors contained in @list, an empty array is returned.
40016 * Returns: (array length=length) (transfer none): an array of file
40022 * g_unix_fd_list_steal_fds:
40023 * @list: a #GUnixFDList
40024 * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL
40026 * Returns the array of file descriptors that is contained in this
40029 * After this call, the descriptors are no longer contained in
40030 * @list. Further calls will return an empty list (unless more
40031 * descriptors have been added).
40033 * The return result of this function must be freed with g_free().
40034 * The caller is also responsible for closing all of the file
40035 * descriptors. The file descriptors in the array are set to
40038 * If @length is non-%NULL then it is set to the number of file
40039 * descriptors in the returned array. The returned array is also
40040 * terminated with -1.
40042 * This function never returns %NULL. In case there are no file
40043 * descriptors contained in @list, an empty array is returned.
40047 * Returns: (array length=length) (transfer full): an array of file
40053 * g_unix_fd_message_append_fd:
40054 * @message: a #GUnixFDMessage
40055 * @fd: a valid open file descriptor
40056 * @error: a #GError pointer
40058 * Adds a file descriptor to @message.
40060 * The file descriptor is duplicated using dup(). You keep your copy
40061 * of the descriptor and the copy contained in @message will be closed
40062 * when @message is finalized.
40064 * A possible cause of failure is exceeding the per-process or
40065 * system-wide file descriptor limit.
40067 * Returns: %TRUE in case of success, else %FALSE (and @error is set)
40073 * g_unix_fd_message_get_fd_list:
40074 * @message: a #GUnixFDMessage
40076 * Gets the #GUnixFDList contained in @message. This function does not
40077 * return a reference to the caller, but the returned list is valid for
40078 * the lifetime of @message.
40080 * Returns: (transfer none): the #GUnixFDList from @message
40086 * g_unix_fd_message_new:
40088 * Creates a new #GUnixFDMessage containing an empty file descriptor
40091 * Returns: a new #GUnixFDMessage
40097 * g_unix_fd_message_new_with_fd_list:
40098 * @fd_list: a #GUnixFDList
40100 * Creates a new #GUnixFDMessage containing @list.
40102 * Returns: a new #GUnixFDMessage
40108 * g_unix_fd_message_steal_fds:
40109 * @message: a #GUnixFDMessage
40110 * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL
40112 * Returns the array of file descriptors that is contained in this
40115 * After this call, the descriptors are no longer contained in
40116 * @message. Further calls will return an empty list (unless more
40117 * descriptors have been added).
40119 * The return result of this function must be freed with g_free().
40120 * The caller is also responsible for closing all of the file
40123 * If @length is non-%NULL then it is set to the number of file
40124 * descriptors in the returned array. The returned array is also
40125 * terminated with -1.
40127 * This function never returns %NULL. In case there are no file
40128 * descriptors contained in @message, an empty array is returned.
40132 * Returns: (array length=length) (transfer full): an array of file
40138 * g_unix_input_stream_get_close_fd:
40139 * @stream: a #GUnixInputStream
40141 * Returns whether the file descriptor of @stream will be
40142 * closed when the stream is closed.
40144 * Returns: %TRUE if the file descriptor is closed when done
40150 * g_unix_input_stream_get_fd:
40151 * @stream: a #GUnixInputStream
40153 * Return the UNIX file descriptor that the stream reads from.
40155 * Returns: The file descriptor of @stream
40161 * g_unix_input_stream_new:
40162 * @fd: a UNIX file descriptor
40163 * @close_fd: %TRUE to close the file descriptor when done
40165 * Creates a new #GUnixInputStream for the given @fd.
40167 * If @close_fd is %TRUE, the file descriptor will be closed
40168 * when the stream is closed.
40170 * Returns: a new #GUnixInputStream
40175 * g_unix_input_stream_set_close_fd:
40176 * @stream: a #GUnixInputStream
40177 * @close_fd: %TRUE to close the file descriptor when done
40179 * Sets whether the file descriptor of @stream shall be closed
40180 * when the stream is closed.
40187 * g_unix_is_mount_path_system_internal:
40188 * @mount_path: a mount path, e.g. <filename>/media/disk</filename> or <filename>/usr</filename>
40190 * Determines if @mount_path is considered an implementation of the
40191 * OS. This is primarily used for hiding mountable and mounted volumes
40192 * that only are used in the OS and has little to no relevance to the
40197 * Returns: %TRUE if @mount_path is considered an implementation detail
40202 * g_unix_mount_at: (skip)
40203 * @mount_path: path for a possible unix mount.
40204 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
40206 * Gets a #GUnixMountEntry for a given mount path. If @time_read
40207 * is set, it will be filled with a unix timestamp for checking
40208 * if the mounts have changed since with g_unix_mounts_changed_since().
40210 * Returns: (transfer full): a #GUnixMountEntry.
40215 * g_unix_mount_compare:
40216 * @mount1: first #GUnixMountEntry to compare.
40217 * @mount2: second #GUnixMountEntry to compare.
40219 * Compares two unix mounts.
40221 * or less than @mount2, respectively.
40223 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
40228 * g_unix_mount_free:
40229 * @mount_entry: a #GUnixMountEntry.
40231 * Frees a unix mount.
40236 * g_unix_mount_get_device_path:
40237 * @mount_entry: a #GUnixMount.
40239 * Gets the device path for a unix mount.
40241 * Returns: a string containing the device path.
40246 * g_unix_mount_get_fs_type:
40247 * @mount_entry: a #GUnixMount.
40249 * Gets the filesystem type for the unix mount.
40251 * Returns: a string containing the file system type.
40256 * g_unix_mount_get_mount_path:
40257 * @mount_entry: input #GUnixMountEntry to get the mount path for.
40259 * Gets the mount path for a unix mount.
40261 * Returns: the mount path for @mount_entry.
40266 * g_unix_mount_guess_can_eject:
40267 * @mount_entry: a #GUnixMountEntry
40269 * Guesses whether a Unix mount can be ejected.
40271 * Returns: %TRUE if @mount_entry is deemed to be ejectable.
40276 * g_unix_mount_guess_icon:
40277 * @mount_entry: a #GUnixMountEntry
40279 * Guesses the icon of a Unix mount.
40281 * Returns: (transfer full): a #GIcon
40286 * g_unix_mount_guess_name:
40287 * @mount_entry: a #GUnixMountEntry
40289 * Guesses the name of a Unix mount.
40290 * The result is a translated string.
40292 * be freed with g_free()
40294 * Returns: A newly allocated string that must
40299 * g_unix_mount_guess_should_display:
40300 * @mount_entry: a #GUnixMountEntry
40302 * Guesses whether a Unix mount should be displayed in the UI.
40304 * Returns: %TRUE if @mount_entry is deemed to be displayable.
40309 * g_unix_mount_is_readonly:
40310 * @mount_entry: a #GUnixMount.
40312 * Checks if a unix mount is mounted read only.
40314 * Returns: %TRUE if @mount_entry is read only.
40319 * g_unix_mount_is_system_internal:
40320 * @mount_entry: a #GUnixMount.
40322 * Checks if a unix mount is a system path.
40324 * Returns: %TRUE if the unix mount is for a system path.
40329 * g_unix_mount_monitor_new:
40331 * Gets a new #GUnixMountMonitor. The default rate limit for which the
40332 * monitor will report consecutive changes for the mount and mount
40333 * point entry files is the default for a #GFileMonitor. Use
40334 * g_unix_mount_monitor_set_rate_limit() to change this.
40336 * Returns: a #GUnixMountMonitor.
40341 * g_unix_mount_monitor_set_rate_limit:
40342 * @mount_monitor: a #GUnixMountMonitor
40343 * @limit_msec: a integer with the limit in milliseconds to poll for changes.
40345 * Sets the rate limit to which the @mount_monitor will report
40346 * consecutive change events to the mount and mount point entry files.
40353 * g_unix_mount_point_compare:
40354 * @mount1: a #GUnixMount.
40355 * @mount2: a #GUnixMount.
40357 * Compares two unix mount points.
40359 * or less than @mount2, respectively.
40361 * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
40366 * g_unix_mount_point_free:
40367 * @mount_point: unix mount point to free.
40369 * Frees a unix mount point.
40374 * g_unix_mount_point_get_device_path:
40375 * @mount_point: a #GUnixMountPoint.
40377 * Gets the device path for a unix mount point.
40379 * Returns: a string containing the device path.
40384 * g_unix_mount_point_get_fs_type:
40385 * @mount_point: a #GUnixMountPoint.
40387 * Gets the file system type for the mount point.
40389 * Returns: a string containing the file system type.
40394 * g_unix_mount_point_get_mount_path:
40395 * @mount_point: a #GUnixMountPoint.
40397 * Gets the mount path for a unix mount point.
40399 * Returns: a string containing the mount path.
40404 * g_unix_mount_point_get_options:
40405 * @mount_point: a #GUnixMountPoint.
40407 * Gets the options for the mount point.
40409 * Returns: a string containing the options.
40415 * g_unix_mount_point_guess_can_eject:
40416 * @mount_point: a #GUnixMountPoint
40418 * Guesses whether a Unix mount point can be ejected.
40420 * Returns: %TRUE if @mount_point is deemed to be ejectable.
40425 * g_unix_mount_point_guess_icon:
40426 * @mount_point: a #GUnixMountPoint
40428 * Guesses the icon of a Unix mount point.
40430 * Returns: (transfer full): a #GIcon
40435 * g_unix_mount_point_guess_name:
40436 * @mount_point: a #GUnixMountPoint
40438 * Guesses the name of a Unix mount point.
40439 * The result is a translated string.
40441 * be freed with g_free()
40443 * Returns: A newly allocated string that must
40448 * g_unix_mount_point_is_loopback:
40449 * @mount_point: a #GUnixMountPoint.
40451 * Checks if a unix mount point is a loopback device.
40453 * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise.
40458 * g_unix_mount_point_is_readonly:
40459 * @mount_point: a #GUnixMountPoint.
40461 * Checks if a unix mount point is read only.
40463 * Returns: %TRUE if a mount point is read only.
40468 * g_unix_mount_point_is_user_mountable:
40469 * @mount_point: a #GUnixMountPoint.
40471 * Checks if a unix mount point is mountable by the user.
40473 * Returns: %TRUE if the mount point is user mountable.
40478 * g_unix_mount_points_changed_since:
40479 * @time: guint64 to contain a timestamp.
40481 * Checks if the unix mount points have changed since a given unix time.
40483 * Returns: %TRUE if the mount points have changed since @time.
40488 * g_unix_mount_points_get: (skip)
40489 * @time_read: (out) (allow-none): guint64 to contain a timestamp.
40491 * Gets a #GList of #GUnixMountPoint containing the unix mount points.
40492 * If @time_read is set, it will be filled with the mount timestamp,
40493 * allowing for checking if the mounts have changed with
40494 * g_unix_mount_points_changed_since().
40496 * a #GList of the UNIX mountpoints.
40498 * Returns: (element-type GUnixMountPoint) (transfer full):
40503 * g_unix_mounts_changed_since:
40504 * @time: guint64 to contain a timestamp.
40506 * Checks if the unix mounts have changed since a given unix time.
40508 * Returns: %TRUE if the mounts have changed since @time.
40513 * g_unix_mounts_get: (skip)
40514 * @time_read: (out) (allow-none): guint64 to contain a timestamp, or %NULL
40516 * Gets a #GList of #GUnixMountEntry containing the unix mounts.
40517 * If @time_read is set, it will be filled with the mount
40518 * timestamp, allowing for checking if the mounts have changed
40519 * with g_unix_mounts_changed_since().
40521 * a #GList of the UNIX mounts.
40523 * Returns: (element-type GUnixMountEntry) (transfer full):
40528 * g_unix_output_stream_get_close_fd:
40529 * @stream: a #GUnixOutputStream
40531 * Returns whether the file descriptor of @stream will be
40532 * closed when the stream is closed.
40534 * Returns: %TRUE if the file descriptor is closed when done
40540 * g_unix_output_stream_get_fd:
40541 * @stream: a #GUnixOutputStream
40543 * Return the UNIX file descriptor that the stream writes to.
40545 * Returns: The file descriptor of @stream
40551 * g_unix_output_stream_new:
40552 * @fd: a UNIX file descriptor
40553 * @close_fd: %TRUE to close the file descriptor when done
40555 * Creates a new #GUnixOutputStream for the given @fd.
40557 * If @close_fd, is %TRUE, the file descriptor will be closed when
40558 * the output stream is destroyed.
40560 * Returns: a new #GOutputStream
40565 * g_unix_output_stream_set_close_fd:
40566 * @stream: a #GUnixOutputStream
40567 * @close_fd: %TRUE to close the file descriptor when done
40569 * Sets whether the file descriptor of @stream shall be closed
40570 * when the stream is closed.
40577 * g_unix_socket_address_abstract_names_supported:
40579 * Checks if abstract unix domain socket names are supported.
40581 * Returns: %TRUE if supported, %FALSE otherwise
40587 * g_unix_socket_address_get_address_type:
40588 * @address: a #GInetSocketAddress
40590 * Gets @address's type.
40592 * Returns: a #GUnixSocketAddressType
40598 * g_unix_socket_address_get_is_abstract:
40599 * @address: a #GInetSocketAddress
40601 * Tests if @address is abstract.
40603 * Returns: %TRUE if the address is abstract, %FALSE otherwise
40605 * Deprecated: Use g_unix_socket_address_get_address_type()
40610 * g_unix_socket_address_get_path:
40611 * @address: a #GInetSocketAddress
40613 * Gets @address's path, or for abstract sockets the "name".
40615 * Guaranteed to be zero-terminated, but an abstract socket
40616 * may contain embedded zeros, and thus you should use
40617 * g_unix_socket_address_get_path_len() to get the true length
40620 * Returns: the path for @address
40626 * g_unix_socket_address_get_path_len:
40627 * @address: a #GInetSocketAddress
40629 * Gets the length of @address's path.
40631 * For details, see g_unix_socket_address_get_path().
40633 * Returns: the length of the path
40639 * g_unix_socket_address_new:
40640 * @path: the socket path
40642 * Creates a new #GUnixSocketAddress for @path.
40644 * To create abstract socket addresses, on systems that support that,
40645 * use g_unix_socket_address_new_abstract().
40647 * Returns: a new #GUnixSocketAddress
40653 * g_unix_socket_address_new_abstract:
40654 * @path: (array length=path_len) (element-type gchar): the abstract name
40655 * @path_len: the length of @path, or -1
40657 * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED
40658 * #GUnixSocketAddress for @path.
40660 * Returns: a new #GUnixSocketAddress
40661 * Deprecated: Use g_unix_socket_address_new_with_type().
40666 * g_unix_socket_address_new_with_type:
40667 * @path: (array length=path_len) (element-type gchar): the name
40668 * @path_len: the length of @path, or -1
40669 * @type: a #GUnixSocketAddressType
40671 * Creates a new #GUnixSocketAddress of type @type with name @path.
40673 * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to
40674 * calling g_unix_socket_address_new().
40676 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len
40677 * bytes of @path will be copied to the socket's path, and only those
40678 * bytes will be considered part of the name. (If @path_len is -1,
40679 * then @path is assumed to be NUL-terminated.) For example, if @path
40680 * was "test", then calling g_socket_address_get_native_size() on the
40681 * returned socket would return 7 (2 bytes of overhead, 1 byte for the
40682 * abstract-socket indicator byte, and 4 bytes for the name "test").
40684 * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then
40685 * @path_len bytes of @path will be copied to the socket's path, the
40686 * rest of the path will be padded with 0 bytes, and the entire
40687 * zero-padded buffer will be considered the name. (As above, if
40688 * @path_len is -1, then @path is assumed to be NUL-terminated.) In
40689 * this case, g_socket_address_get_native_size() will always return
40690 * the full size of a <literal>struct sockaddr_un</literal>, although
40691 * g_unix_socket_address_get_path_len() will still return just the
40694 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over
40695 * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course,
40696 * when connecting to a server created by another process, you must
40697 * use the appropriate type corresponding to how that process created
40698 * its listening socket.
40700 * Returns: a new #GUnixSocketAddress
40706 * g_utf8_next_char:
40707 * @p: Pointer to the start of a valid UTF-8 character
40709 * Skips to the next character in a UTF-8 string. The string must be
40710 * valid; this macro is as fast as possible, and has no error-checking.
40711 * You would use this macro to iterate over a string character by
40712 * character. The macro returns the start of the next UTF-8 character.
40713 * Before using this macro, use g_utf8_validate() to validate strings
40714 * that may contain invalid UTF-8.
40719 * g_vfs_get_default:
40721 * Gets the default #GVfs for the system.
40723 * Returns: (transfer none): a #GVfs.
40728 * g_vfs_get_file_for_path:
40730 * @path: a string containing a VFS path.
40732 * Gets a #GFile for @path.
40734 * Free the returned object with g_object_unref().
40736 * Returns: (transfer full): a #GFile.
40741 * g_vfs_get_file_for_uri:
40743 * @uri: a string containing a URI
40745 * Gets a #GFile for @uri.
40747 * This operation never fails, but the returned object
40748 * might not support any I/O operation if the URI
40749 * is malformed or if the URI scheme is not supported.
40751 * Free the returned object with g_object_unref().
40753 * Returns: (transfer full): a #GFile.
40760 * Gets the local #GVfs for the system.
40762 * Returns: (transfer none): a #GVfs.
40767 * g_vfs_get_supported_uri_schemes:
40770 * Gets a list of URI schemes supported by @vfs.
40772 * The returned array belongs to GIO and must
40773 * not be freed or modified.
40775 * Returns: (transfer none): a %NULL-terminated array of strings.
40783 * Checks if the VFS is active.
40785 * Returns: %TRUE if construction of the @vfs was successful and it is now active.
40790 * g_vfs_parse_name:
40792 * @parse_name: a string to be parsed by the VFS module.
40794 * This operation never fails, but the returned object might
40795 * not support any I/O operations if the @parse_name cannot
40796 * be parsed by the #GVfs module.
40798 * Free the returned object with g_object_unref().
40800 * Returns: (transfer full): a #GFile for the given @parse_name.
40805 * g_volume_can_eject:
40806 * @volume: a #GVolume.
40808 * Checks if a volume can be ejected.
40810 * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise.
40815 * g_volume_can_mount:
40816 * @volume: a #GVolume.
40818 * Checks if a volume can be mounted.
40820 * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise.
40826 * @volume: a #GVolume.
40827 * @flags: flags affecting the unmount if required for eject
40828 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
40829 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
40830 * @user_data: user data that gets passed to @callback
40832 * Ejects a volume. This is an asynchronous operation, and is
40833 * finished by calling g_volume_eject_finish() with the @volume
40834 * and #GAsyncResult returned in the @callback.
40836 * Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
40841 * g_volume_eject_finish:
40842 * @volume: pointer to a #GVolume.
40843 * @result: a #GAsyncResult.
40844 * @error: a #GError location to store an error, or %NULL to ignore
40846 * Finishes ejecting a volume. If any errors occurred during the operation,
40847 * @error will be set to contain the errors and %FALSE will be returned.
40849 * Returns: %TRUE, %FALSE if operation failed.
40850 * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
40855 * g_volume_eject_with_operation:
40856 * @volume: a #GVolume.
40857 * @flags: flags affecting the unmount if required for eject
40858 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
40859 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
40860 * @callback: a #GAsyncReadyCallback, or %NULL.
40861 * @user_data: user data passed to @callback.
40863 * Ejects a volume. This is an asynchronous operation, and is
40864 * finished by calling g_volume_eject_with_operation_finish() with the @volume
40865 * and #GAsyncResult data returned in the @callback.
40872 * g_volume_eject_with_operation_finish:
40873 * @volume: a #GVolume.
40874 * @result: a #GAsyncResult.
40875 * @error: a #GError location to store the error occurring, or %NULL to ignore.
40877 * Finishes ejecting a volume. If any errors occurred during the operation,
40878 * @error will be set to contain the errors and %FALSE will be returned.
40880 * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise.
40886 * g_volume_enumerate_identifiers:
40887 * @volume: a #GVolume
40889 * Gets the kinds of <link linkend="volume-identifier">identifiers</link>
40890 * that @volume has. Use g_volume_get_identifier() to obtain
40891 * the identifiers themselves.
40893 * of strings containing kinds of identifiers. Use g_strfreev() to free.
40895 * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
40900 * g_volume_get_activation_root:
40901 * @volume: a #GVolume
40903 * Gets the activation root for a #GVolume if it is known ahead of
40904 * mount time. Returns %NULL otherwise. If not %NULL and if @volume
40905 * is mounted, then the result of g_mount_get_root() on the
40906 * #GMount object obtained from g_volume_get_mount() will always
40907 * either be equal or a prefix of what this function returns. In
40908 * other words, in code
40912 * GFile *mount_root
40913 * GFile *volume_activation_root;
40915 * mount = g_volume_get_mount (volume); /* mounted, so never NULL */
40916 * mount_root = g_mount_get_root (mount);
40917 * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */
40918 * </programlisting>
40920 * then the expression
40923 * (g_file_has_prefix (volume_activation_root, mount_root) ||
40924 * </programlisting>
40926 * will always be %TRUE.
40928 * Activation roots are typically used in #GVolumeMonitor
40929 * implementations to find the underlying mount to shadow, see
40930 * g_mount_is_shadowed() for more details.
40932 * g_object_unref() to free.
40934 * Returns: (transfer full): the activation root of @volume or %NULL. Use
40940 * g_volume_get_drive:
40941 * @volume: a #GVolume.
40943 * Gets the drive for the @volume.
40945 * The returned object should be unreffed with g_object_unref()
40946 * when no longer needed.
40948 * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive.
40953 * g_volume_get_icon:
40954 * @volume: a #GVolume.
40956 * Gets the icon for @volume.
40958 * The returned object should be unreffed with g_object_unref()
40959 * when no longer needed.
40961 * Returns: (transfer full): a #GIcon.
40966 * g_volume_get_identifier:
40967 * @volume: a #GVolume
40968 * @kind: the kind of identifier to return
40970 * Gets the identifier of the given kind for @volume.
40971 * See the <link linkend="volume-identifier">introduction</link>
40972 * for more information about volume identifiers.
40974 * requested identfier, or %NULL if the #GVolume
40975 * doesn't have this kind of identifier
40977 * Returns: a newly allocated string containing the
40982 * g_volume_get_mount:
40983 * @volume: a #GVolume.
40985 * Gets the mount for the @volume.
40987 * The returned object should be unreffed with g_object_unref()
40988 * when no longer needed.
40990 * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted.
40995 * g_volume_get_name:
40996 * @volume: a #GVolume.
40998 * Gets the name of @volume.
41000 * be freed with g_free() when no longer needed.
41002 * Returns: the name for the given @volume. The returned string should
41007 * g_volume_get_sort_key:
41008 * @volume: A #GVolume.
41010 * Gets the sort key for @volume, if any.
41012 * Returns: Sorting key for @volume or %NULL if no such key is available.
41018 * g_volume_get_uuid:
41019 * @volume: a #GVolume.
41021 * Gets the UUID for the @volume. The reference is typically based on
41022 * the file system UUID for the volume in question and should be
41023 * considered an opaque string. Returns %NULL if there is no UUID
41026 * The returned string should be freed with g_free()
41027 * when no longer needed.
41029 * Returns: the UUID for @volume or %NULL if no UUID can be computed.
41034 * g_volume_monitor_adopt_orphan_mount:
41035 * @mount: a #GMount object to find a parent for
41037 * This function should be called by any #GVolumeMonitor
41038 * implementation when a new #GMount object is created that is not
41039 * associated with a #GVolume object. It must be called just before
41040 * emitting the @mount_added signal.
41042 * If the return value is not %NULL, the caller must associate the
41043 * returned #GVolume object with the #GMount. This involves returning
41044 * it in its g_mount_get_volume() implementation. The caller must
41045 * also listen for the "removed" signal on the returned object
41046 * and give up its reference when handling that signal
41048 * Similary, if implementing g_volume_monitor_adopt_orphan_mount(),
41049 * the implementor must take a reference to @mount and return it in
41050 * its g_volume_get_mount() implemented. Also, the implementor must
41051 * listen for the "unmounted" signal on @mount and give up its
41052 * reference upon handling that signal.
41054 * There are two main use cases for this function.
41056 * One is when implementing a user space file system driver that reads
41057 * blocks of a block device that is already represented by the native
41058 * volume monitor (for example a CD Audio file system driver). Such
41059 * a driver will generate its own #GMount object that needs to be
41060 * associated with the #GVolume object that represents the volume.
41062 * The other is for implementing a #GVolumeMonitor whose sole purpose
41063 * is to return #GVolume objects representing entries in the users
41064 * "favorite servers" list or similar.
41066 * if no wants to adopt the #GMount.
41068 * implementations should instead create shadow mounts with the URI of
41069 * the mount they intend to adopt. See the proxy volume monitor in
41070 * gvfs for an example of this. Also see g_mount_is_shadowed(),
41071 * g_mount_shadow() and g_mount_unshadow() functions.
41073 * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL
41074 * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor
41079 * g_volume_monitor_get:
41081 * Gets the volume monitor used by gio.
41083 * g_object_unref() when done with it.
41085 * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call
41090 * g_volume_monitor_get_connected_drives:
41091 * @volume_monitor: a #GVolumeMonitor.
41093 * Gets a list of drives connected to the system.
41095 * The returned list should be freed with g_list_free(), after
41096 * its elements have been unreffed with g_object_unref().
41098 * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects.
41103 * g_volume_monitor_get_mount_for_uuid:
41104 * @volume_monitor: a #GVolumeMonitor.
41105 * @uuid: the UUID to look for
41107 * Finds a #GMount object by its UUID (see g_mount_get_uuid())
41109 * Free the returned object with g_object_unref().
41111 * Returns: (transfer full): a #GMount or %NULL if no such mount is available.
41116 * g_volume_monitor_get_mounts:
41117 * @volume_monitor: a #GVolumeMonitor.
41119 * Gets a list of the mounts on the system.
41121 * The returned list should be freed with g_list_free(), after
41122 * its elements have been unreffed with g_object_unref().
41124 * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects.
41129 * g_volume_monitor_get_volume_for_uuid:
41130 * @volume_monitor: a #GVolumeMonitor.
41131 * @uuid: the UUID to look for
41133 * Finds a #GVolume object by its UUID (see g_volume_get_uuid())
41135 * Free the returned object with g_object_unref().
41137 * Returns: (transfer full): a #GVolume or %NULL if no such volume is available.
41142 * g_volume_monitor_get_volumes:
41143 * @volume_monitor: a #GVolumeMonitor.
41145 * Gets a list of the volumes on the system.
41147 * The returned list should be freed with g_list_free(), after
41148 * its elements have been unreffed with g_object_unref().
41150 * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects.
41156 * @volume: a #GVolume.
41157 * @flags: flags affecting the operation
41158 * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
41159 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
41160 * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
41161 * @user_data: user data that gets passed to @callback
41163 * Mounts a volume. This is an asynchronous operation, and is
41164 * finished by calling g_volume_mount_finish() with the @volume
41165 * and #GAsyncResult returned in the @callback.
41167 * Virtual: mount_fn
41172 * g_volume_mount_finish:
41173 * @volume: a #GVolume
41174 * @result: a #GAsyncResult
41175 * @error: a #GError location to store an error, or %NULL to ignore
41177 * Finishes mounting a volume. If any errors occurred during the operation,
41178 * @error will be set to contain the errors and %FALSE will be returned.
41180 * If the mount operation succeeded, g_volume_get_mount() on @volume
41181 * is guaranteed to return the mount right after calling this
41182 * function; there's no need to listen for the 'mount-added' signal on
41185 * Returns: %TRUE, %FALSE if operation failed.
41190 * g_volume_should_automount:
41191 * @volume: a #GVolume
41193 * Returns whether the volume should be automatically mounted.
41195 * Returns: %TRUE if the volume should be automatically mounted.
41201 * @expr: the expression to check
41203 * Logs a warning if the expression is not true.
41210 * g_warn_if_reached:
41212 * Logs a critical warning.
41219 * g_win32_input_stream_get_close_handle:
41220 * @stream: a #GWin32InputStream
41222 * Returns whether the handle of @stream will be
41223 * closed when the stream is closed.
41225 * Returns: %TRUE if the handle is closed when done
41231 * g_win32_input_stream_get_handle:
41232 * @stream: a #GWin32InputStream
41234 * Return the Windows file handle that the stream reads from.
41236 * Returns: The file handle of @stream
41242 * g_win32_input_stream_new:
41243 * @handle: a Win32 file handle
41244 * @close_handle: %TRUE to close the handle when done
41246 * Creates a new #GWin32InputStream for the given @handle.
41248 * If @close_handle is %TRUE, the handle will be closed
41249 * when the stream is closed.
41251 * Note that "handle" here means a Win32 HANDLE, not a "file descriptor"
41252 * as used in the Windows C libraries.
41254 * Returns: a new #GWin32InputStream
41259 * g_win32_input_stream_set_close_handle:
41260 * @stream: a #GWin32InputStream
41261 * @close_handle: %TRUE to close the handle when done
41263 * Sets whether the handle of @stream shall be closed
41264 * when the stream is closed.
41271 * g_win32_output_stream_get_close_handle:
41272 * @stream: a #GWin32OutputStream
41274 * Returns whether the handle of @stream will be closed when the
41275 * stream is closed.
41277 * Returns: %TRUE if the handle is closed when done
41283 * g_win32_output_stream_get_handle:
41284 * @stream: a #GWin32OutputStream
41286 * Return the Windows handle that the stream writes to.
41288 * Returns: The handle descriptor of @stream
41294 * g_win32_output_stream_new:
41295 * @handle: a Win32 file handle
41296 * @close_handle: %TRUE to close the handle when done
41298 * Creates a new #GWin32OutputStream for the given @handle.
41300 * If @close_handle, is %TRUE, the handle will be closed when the
41301 * output stream is destroyed.
41303 * Returns: a new #GOutputStream
41309 * g_win32_output_stream_set_close_handle:
41310 * @stream: a #GWin32OutputStream
41311 * @close_handle: %TRUE to close the handle when done
41313 * Sets whether the handle of @stream shall be closed when the stream
41321 * g_zlib_compressor_get_file_info:
41322 * @compressor: a #GZlibCompressor
41324 * Returns the #GZlibCompressor:file-info property.
41326 * Returns: (transfer none): a #GFileInfo, or %NULL
41332 * g_zlib_compressor_new:
41333 * @format: The format to use for the compressed data
41334 * @level: compression level (0-9), -1 for default
41336 * Creates a new #GZlibCompressor.
41338 * Returns: a new #GZlibCompressor
41344 * g_zlib_compressor_set_file_info:
41345 * @compressor: a #GZlibCompressor
41346 * @file_info: (allow-none): a #GFileInfo
41348 * Sets @file_info in @compressor. If non-%NULL, and @compressor's
41349 * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
41350 * it will be used to set the file name and modification time in
41351 * the GZIP header of the compressed data.
41353 * Note: it is an error to call this function while a compression is in
41354 * progress; it may only be called immediately after creation of @compressor,
41355 * or after resetting it with g_converter_reset().
41362 * g_zlib_decompressor_get_file_info:
41363 * @decompressor: a #GZlibDecompressor
41365 * Retrieves the #GFileInfo constructed from the GZIP header data
41366 * of compressed data processed by @compressor, or %NULL if @decompressor's
41367 * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP,
41368 * or the header data was not fully processed yet, or it not present in the
41369 * data stream at all.
41371 * Returns: (transfer none): a #GFileInfo, or %NULL
41377 * g_zlib_decompressor_new:
41378 * @format: The format to use for the compressed data
41380 * Creates a new #GZlibDecompressor.
41382 * Returns: a new #GZlibDecompressor
41390 * A C representable type name for #G_TYPE_STRING.
41395 * get_all_desktop_entries_for_mime_type:
41396 * @mime_type: a mime type.
41397 * @except: NULL or a strv list
41399 * Returns all the desktop ids for @mime_type. The desktop files
41400 * are listed in an order so that default applications are listed before
41401 * non-default ones, and handlers for inherited mimetypes are listed
41402 * after the base ones.
41404 * Optionally doesn't list the desktop ids given in the @except
41406 * to handle @mime_type.
41408 * Returns: a #GList containing the desktop ids which claim
41415 * A type which can hold any UTF-32 or UCS-4 character code,
41416 * also known as a Unicode code point.
41418 * If you want to produce the UTF-8 representation of a #gunichar,
41419 * use g_ucs4_to_utf8(). See also g_utf8_to_ucs4() for the reverse
41422 * To print/scan values of this type as integer, use
41423 * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
41425 * The notation to express a Unicode code point in running text is
41426 * as a hexadecimal number with four to six digits and uppercase
41427 * letters, prefixed by the string "U+". Leading zeros are omitted,
41428 * unless the code point would have fewer than four hexadecimal digits.
41429 * For example, "U+0041 LATIN CAPITAL LETTER A". To print a code point
41430 * in the U+-notation, use the format string "U+\%04"G_GINT32_FORMAT"X".
41431 * To scan, use the format string "U+\%06"G_GINT32_FORMAT"X".
41435 * sscanf ("U+0041", "U+%06"G_GINT32_FORMAT"X", &c)
41436 * g_print ("Read U+%04"G_GINT32_FORMAT"X", c);
41444 * A type which can hold any UTF-16 code
41445 * point<footnote id="utf16_surrogate_pairs">UTF-16 also has so called
41446 * <firstterm>surrogate pairs</firstterm> to encode characters beyond
41447 * the BMP as pairs of 16bit numbers. Surrogate pairs cannot be stored
41448 * in a single gunichar2 field, but all GLib functions accepting gunichar2
41449 * arrays will correctly interpret surrogate pairs.</footnote>.
41451 * To print/scan values of this type to/from text you need to convert
41452 * to/from UTF-8, using g_utf16_to_utf8()/g_utf8_to_utf16().
41454 * To print/scan values of this type as integer, use
41455 * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
41460 * mime_info_cache_reload:
41461 * @dir: directory path which needs reloading.
41463 * Reload the mime information for the @dir.
41468 /************************************************************/
41469 /* THIS FILE IS GENERATED DO NOT EDIT */
41470 /************************************************************/