Callbacks -

Gio 2.0 ([original](https://lazka.github.io/pgi-docs/Gio-2.0/callbacks.html)) ([raw](?raw))

Details¶

Gio.AsyncReadyCallback(source_object, res, data)¶

Parameters:

• source_object (GObject.Object or None) – the object the asynchronous operation was started with.
• res (Gio.AsyncResult) – a Gio.AsyncResult.
• data (object or None) – user data passed to the callback.

Type definition for a function that will be called back when an asynchronous operation within GIO has been completed. Gio.AsyncReadyCallbackcallbacks from Gio.Task are guaranteed to be invoked in a later iteration of the thread-default main context (see [method`GLib`.MainContext.push_thread_default]) where the Gio.Task was created. All other users ofGio.AsyncReadyCallback must likewise call it asynchronously in a later iteration of the main context.

The asynchronous operation is guaranteed to have held a reference tosource_object from the time when the *_async() function was called, until after this callback returns.

Gio.BusAcquiredCallback(connection, name, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – the connection to a message bus
• name (str) – the name that is requested to be owned
• user_data (object or None) – user data passed to [func`Gio`.bus_own_name]

Invoked when a connection to a message bus has been obtained.

New in version 2.26.

Gio.BusNameAcquiredCallback(connection, name, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – the connection on which to acquired the name
• name (str) – the name being owned
• user_data (object or None) – user data passed to [func`Gio`.bus_own_name] or [func`Gio`.bus_own_name_on_connection]

Invoked when the name is acquired.

New in version 2.26.

Gio.BusNameAppearedCallback(connection, name, name_owner, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – The Gio.DBusConnection the name is being watched on.
• name (str) – The name being watched.
• name_owner (str) – Unique name of the owner of the name being watched.
• user_data (object or None) – User data passed to Gio.bus_watch_name().

Invoked when the name being watched is known to have to have an owner.

New in version 2.26.

Gio.BusNameLostCallback(connection, name, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – the connect on which to acquire the name or NULL if the connection was disconnected
• name (str) – the name being owned
• user_data (object or None) – user data passed to [func`Gio`.bus_own_name] or [func`Gio`.bus_own_name_on_connection]

Invoked when the name is lost or connection has been closed.

New in version 2.26.

Gio.BusNameVanishedCallback(connection, name, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – The Gio.DBusConnection the name is being watched on, orNone.
• name (str) – The name being watched.
• user_data (object or None) – User data passed to Gio.bus_watch_name().

Invoked when the name being watched is known not to have to have an owner.

This is also invoked when the Gio.DBusConnection on which the watch was established has been closed. In that case, connection will beNone.

New in version 2.26.

Gio.CancellableSourceFunc(cancellable, data)¶

Parameters:

• cancellable (Gio.Cancellable or None) – the Gio.Cancellable
• data (object or None) – data passed in by the user.

Returns:

it should return False if the source should be removed.

Return type:

bool

This is the function type of the callback used for the GLib.Sourcereturned by Gio.Cancellable.source_new().

New in version 2.28.

Gio.DBusInterfaceGetPropertyFunc(connection, sender, object_path, interface_name, property_name, error, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – A Gio.DBusConnection.
• sender (str or None) – The unique bus name of the remote caller or None if not specified by the caller, e.g. on peer-to-peer connections.
• object_path (str) – The object path that the method was invoked on.
• interface_name (str) – The D-Bus interface name for the property.
• property_name (str) – The name of the property to get the value of.
• error (GLib.Error) – Return location for error.
• user_data (object or None) – The user_data object passed to Gio.DBusConnection.register_object().

Returns:

A GLib.Variant with the value for property_name or None iferror is set. If the returned GLib.Variant is floating, it is consumed - otherwise its reference count is decreased by one.

Return type:

GLib.Variant

The type of the get_property function in Gio.DBusInterfaceVTable.

New in version 2.26.

Gio.DBusInterfaceMethodCallFunc(connection, sender, object_path, interface_name, method_name, parameters, invocation, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – A Gio.DBusConnection.
• sender (str or None) – The unique bus name of the remote caller, or NULL if not specified by the caller, e.g. on peer-to-peer connections.
• object_path (str) – The object path that the method was invoked on.
• interface_name (str or None) – The D-Bus interface name the method was invoked on, or NULL if not specified by the sender.
• method_name (str) – The name of the method that was invoked.
• parameters (GLib.Variant) – A GLib.Variant tuple with parameters.
• invocation (Gio.DBusMethodInvocation) – A Gio.DBusMethodInvocation object that must be used to return a value or error.
• user_data (object or None) – The user_data object passed to Gio.DBusConnection.register_object().

The type of the method_call function in Gio.DBusInterfaceVTable.

interface_name may be NULL if not specified by the sender, although it’s encouraged for the sender to set it. If unset, and the object has only one method (across all interfaces) matching method_name, that method is invoked. Otherwise, behaviour is implementation defined. See theD-Bus specification. It is recommended to return [error`Gio`.DBusError.UNKNOWN_METHOD].

New in version 2.26.

Gio.DBusInterfaceSetPropertyFunc(connection, sender, object_path, interface_name, property_name, value, error, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – A Gio.DBusConnection.
• sender (str or None) – The unique bus name of the remote caller or None if not specified by the caller, e.g. on peer-to-peer connections.
• object_path (str) – The object path that the method was invoked on.
• interface_name (str) – The D-Bus interface name for the property.
• property_name (str) – The name of the property to get the value of.
• value (GLib.Variant) – The value to set the property to.
• error (GLib.Error) – Return location for error.
• user_data (object or None) – The user_data object passed to Gio.DBusConnection.register_object().

Returns:

True if the property was set to value, False if error is set.

Return type:

bool

The type of the set_property function in Gio.DBusInterfaceVTable.

New in version 2.26.

Gio.DBusMessageFilterFunction(connection, message, incoming, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – A Gio.DBusConnection.
• message (Gio.DBusMessage) – A locked Gio.DBusMessage that the filter function takes ownership of.
• incoming (bool) – True if it is a message received from the other peer, False if it is a message to be sent to the other peer.
• user_data (object or None) – User data passed when adding the filter.

Returns:

A Gio.DBusMessage that will be freed withGObject.Object.unref() or None to drop the message. Passive filter functions can simply return the passed message object.

Return type:

Gio.DBusMessage or None

Signature for function used in Gio.DBusConnection.add_filter().

A filter function is passed a Gio.DBusMessage and expected to return a Gio.DBusMessage too. Passive filter functions that don’t modify the message can simply return the message object:

static GDBusMessage * passive_filter (GDBusConnection *connection GDBusMessage *message, gboolean incoming, gpointer user_data) { // inspect @message return message; }

Filter functions that wants to drop a message can simply return None:

static GDBusMessage * drop_filter (GDBusConnection *connection GDBusMessage *message, gboolean incoming, gpointer user_data) { if (should_drop_message) { g_object_unref (message); message = NULL; } return message; }

Finally, a filter function may modify a message by copying it:

static GDBusMessage * modifying_filter (GDBusConnection *connection GDBusMessage *message, gboolean incoming, gpointer user_data) { GDBusMessage *copy; GError *error;

error = NULL; copy = g_dbus_message_copy (message, &error); // handle @error being set g_object_unref (message);

// modify @copy

return copy; }

If the returned Gio.DBusMessage is different from message and cannot be sent on connection (it could use features, such as file descriptors, not compatible with connection), then a warning is logged to standard error. Applications can check this ahead of time using Gio.DBusMessage.to_blob() passing aGio.DBusCapabilityFlags value obtained from connection.

New in version 2.26.

Gio.DBusProxyTypeFunc(manager, object_path, interface_name, data)¶

Parameters:

• manager (Gio.DBusObjectManagerClient) – A Gio.DBusObjectManagerClient.
• object_path (str) – The object path of the remote object.
• interface_name (str or None) – The interface name of the remote object or None if a Gio.DBusObjectProxy GObject.GType is requested.
• data (object or None) – data passed in by the user.

Returns:

A GObject.GType to use for the remote object. The returned type must be a Gio.DBusProxy or Gio.DBusObjectProxy -derived type.

Return type:

GObject.GType

Function signature for a function used to determine the GObject.GType to use for an interface proxy (if interface_name is not None) or object proxy (if interface_name is None).

This function is called in the thread-default main context (see [method`GLib`.MainContext.push_thread_default]) that manager was constructed in.

New in version 2.30.

Gio.DBusSignalCallback(connection, sender_name, object_path, interface_name, signal_name, parameters, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – A Gio.DBusConnection.
• sender_name (str or None) – The unique bus name of the sender of the signal, or None on a peer-to-peer D-Bus connection.
• object_path (str) – The object path that the signal was emitted on.
• interface_name (str) – The name of the interface.
• signal_name (str) – The name of the signal.
• parameters (GLib.Variant) – A GLib.Variant tuple with parameters for the signal.
• user_data (object or None) – User data passed when subscribing to the signal.

Signature for callback function used in Gio.DBusConnection.signal_subscribe().

New in version 2.26.

Gio.DBusSubtreeDispatchFunc(connection, sender, object_path, interface_name, node, out_user_data, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – A Gio.DBusConnection.
• sender (str) – The unique bus name of the remote caller.
• object_path (str) – The object path that was registered with Gio.DBusConnection.register_subtree().
• interface_name (str) – The D-Bus interface name that the method call or property access is for.
• node (str) – A node that is a child of object_path (relative to object_path) or None for the root of the subtree.
• out_user_data (object) – Return location for user data to pass to functions in the returned Gio.DBusInterfaceVTable.
• user_data (object or None) – The user_data object passed to Gio.DBusConnection.register_subtree().

Returns:

A Gio.DBusInterfaceVTable or None if you don’t want to handle the methods.

Return type:

Gio.DBusInterfaceVTable or None

The type of the dispatch function in Gio.DBusSubtreeVTable.

Subtrees are flat. node, if non-None, is always exactly one segment of the object path (ie: it never contains a slash).

New in version 2.26.

Gio.DBusSubtreeEnumerateFunc(connection, sender, object_path, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – A Gio.DBusConnection.
• sender (str) – The unique bus name of the remote caller.
• object_path (str) – The object path that was registered with Gio.DBusConnection.register_subtree().
• user_data (object or None) – The user_data object passed to Gio.DBusConnection.register_subtree().

Returns:

A newly allocated array of strings for node names that are children of object_path.

Return type:

[str]

The type of the enumerate function in Gio.DBusSubtreeVTable.

This function is called when generating introspection data and also when preparing to dispatch incoming messages in the event that theGio.DBusSubtreeFlags.DISPATCH_TO_UNENUMERATED_NODES flag is not specified (ie: to verify that the object path is valid).

Hierarchies are not supported; the items that you return should not contain the / character.

The return value will be freed with GLib.strfreev().

New in version 2.26.

Gio.DBusSubtreeIntrospectFunc(connection, sender, object_path, node, *user_data)¶

Parameters:

• connection (Gio.DBusConnection) – A Gio.DBusConnection.
• sender (str) – The unique bus name of the remote caller.
• object_path (str) – The object path that was registered with Gio.DBusConnection.register_subtree().
• node (str) – A node that is a child of object_path (relative to object_path) or None for the root of the subtree.
• user_data (object or None) – The user_data object passed to Gio.DBusConnection.register_subtree().

Returns:

A None-terminated array of pointers to Gio.DBusInterfaceInfo, or None.

Return type:

[Gio.DBusInterfaceInfo] or None

The type of the introspect function in Gio.DBusSubtreeVTable.

Subtrees are flat. node, if non-None, is always exactly one segment of the object path (ie: it never contains a slash).

This function should return None to indicate that there is no object at this node.

If this function returns non-None, the return value is expected to be a None-terminated array of pointers to Gio.DBusInterfaceInfostructures describing the interfaces implemented by node. This array will have Gio.DBusInterfaceInfo.unref() called on each item before being freed with GLib.free().

The difference between returning None and an array containing zero items is that the standard DBus interfaces will returned to the remote introspector in the empty array case, but not in the Nonecase.

New in version 2.26.

Gio.DatagramBasedSourceFunc(datagram_based, condition, data)¶

Parameters:

• datagram_based (Gio.DatagramBased) – the Gio.DatagramBased
• condition (GLib.IOCondition) – the current condition at the source fired
• data (object or None) – data passed in by the user

Returns:

GLib.SOURCE_REMOVE if the source should be removed,GLib.SOURCE_CONTINUE otherwise

Return type:

bool

This is the function type of the callback used for the GLib.Sourcereturned by Gio.DatagramBased.create_source().

New in version 2.48.

Gio.DesktopAppLaunchCallback(appinfo, pid, *user_data)¶

Parameters:

• appinfo (Gio.DesktopAppInfo) – a Gio.DesktopAppInfo
• pid (int) – Process identifier
• user_data (object or None) – User data

During invocation, Gio.DesktopAppInfo.launch_uris_as_manager() may create one or more child processes. This callback is invoked once for each, providing the process ID.

Gio.FileMeasureProgressCallback(reporting, current_size, num_dirs, num_files, data)¶

Parameters:

• reporting (bool) – True if more reports will come
• current_size (int) – the current cumulative size measurement
• num_dirs (int) – the number of directories visited so far
• num_files (int) – the number of non-directory files encountered
• data (object or None) – the data passed to the original request for this callback

This callback type is used by Gio.File.measure_disk_usage() to make periodic progress reports when measuring the amount of disk spaced used by a directory.

These calls are made on a best-effort basis and not all types ofGio.File will support them. At the minimum, however, one call will always be made immediately.

In the case that there is no support, reporting will be set toFalse (and the other values undefined) and no further calls will be made. Otherwise, the reporting will be True and the other values all-zeros during the first (immediate) call. In this way, you can know which type of progress UI to show without a delay.

For Gio.File.measure_disk_usage() the callback is made directly. For g_file_measure_disk_usage_async() the callback is made via the default main context of the calling thread (ie: the same way that the final async result would be reported).

current_size is in the same units as requested by the operation (seeGio.FileMeasureFlags.APPARENT_SIZE).

The frequency of the updates is implementation defined, but is ideally about once every 200ms.

The last progress callback may or may not be equal to the final result. Always check the async result to get the final value.

New in version 2.38.

Gio.FileProgressCallback(current_num_bytes, total_num_bytes, data)¶

Parameters:

• current_num_bytes (int) – the current number of bytes in the operation.
• total_num_bytes (int) – the total number of bytes in the operation.
• data (object or None) – user data passed to the callback.

When doing file operations that may take a while, such as moving a file or copying a file, a progress callback is used to pass how far along that operation is to the application.

Gio.FileReadMoreCallback(file_contents, file_size, callback_data)¶

Parameters:

• file_contents (str) – the data as currently read.
• file_size (int) – the size of the data currently read.
• callback_data (object or None) – data passed to the callback.

Returns:

True if more data should be read back. False otherwise.

Return type:

bool

When loading the partial contents of a file with g_file_load_partial_contents_async(), it may become necessary to determine if any more data from the file should be loaded. A Gio.FileReadMoreCallback function facilitates this by returning True if more data should be read, or False otherwise.

Gio.IOSchedulerJobFunc(job, cancellable, data)¶

Parameters:

• job (Gio.IOSchedulerJob) – a Gio.IOSchedulerJob.
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
• data (object or None) – data passed to the callback function

Returns:

True if this function should be called again to complete the job, False if the job is complete (or cancelled)

Return type:

bool

I/O Job function.

Long-running jobs should periodically check the cancellableto see if they have been cancelled.

Deprecated since version 2.36: Use [struct`GLib`.ThreadPool] or [method`Gio`.Task.run_in_thread]

Gio.PollableSourceFunc(pollable_stream, data)¶

Parameters:

• pollable_stream (GObject.Object) – the Gio.PollableInputStream or Gio.PollableOutputStream
• data (object or None) – data passed in by the user.

Returns:

it should return False if the source should be removed.

Return type:

bool

This is the function type of the callback used for the GLib.Sourcereturned by Gio.PollableInputStream.create_source() andGio.PollableOutputStream.create_source().

New in version 2.28.

Gio.ReallocFunc(data, size)¶

Parameters:

• data (object or None) – memory block to reallocate
• size (int) – size to reallocate data to

Returns:

a pointer to the reallocated memory

Return type:

object or None

Changes the size of the memory block pointed to by data tosize bytes.

The function should have the same semantics as realloc().

Gio.SettingsBindGetMapping(value, variant, *user_data)¶

Parameters:

• value (GObject.Value) – return location for the property value
• variant (GLib.Variant) – variant to map to the property value
• user_data (object or None) – user data that was specified when the binding was created

Returns:

true if the conversion succeeded, false in case of an error

Return type:

bool

The type for the function that is used to convert from [class`Gio`.Settings] to an object property.

The value is already initialized to hold values of the appropriate type.

Gio.SettingsBindSetMapping(value, expected_type, *user_data)¶

Parameters:

• value (GObject.Value) – the property value to map
• expected_type (GLib.VariantType) – expected type of the result
• user_data (object or None) – user data that was specified when the binding was created

Returns:

a new [struct`GLib`.Variant] holding the data from value, or NULL in case of an error

Return type:

GLib.Variant or None

The type for the function that is used to convert an object property value to a [struct`GLib`.Variant] for storing it in [class`Gio`.Settings].

Gio.SettingsGetMapping(value, *user_data)¶

Parameters:

• value (GLib.Variant or None) – variant to map to the application value
• user_data (object or None) – the user data that was passed to [method`Gio`.Settings.get_mapped]

Returns:

true if the conversion succeeded, false in case of an error

result:

the result of the mapping

Return type:

(bool, result: object)

The type of the function that is used to convert from a value stored in a [class`Gio`.Settings] to a value that is useful to the application.

If the value is successfully mapped, the result should be stored atresult and true returned. If mapping fails (for example, if valueis not in the right format) then false should be returned.

If value is NULL then it means that the mapping function is being given a ‘last chance’ to successfully return a valid value. True must be returned in this case.

Gio.SimpleAsyncThreadFunc(res, object, cancellable)¶

Parameters:

• res (Gio.SimpleAsyncResult) – a Gio.SimpleAsyncResult.
• object (GObject.Object) – a GObject.Object.
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Simple thread function that runs an asynchronous operation and checks for cancellation.

Gio.SocketSourceFunc(socket, condition, data)¶

Parameters:

• socket (Gio.Socket) – the Gio.Socket
• condition (GLib.IOCondition) – the current condition at the source fired.
• data (object or None) – data passed in by the user.

Returns:

it should return False if the source should be removed.

Return type:

bool

This is the function type of the callback used for the GLib.Sourcereturned by g_socket_create_source().

New in version 2.22.

Gio.TaskThreadFunc(task, source_object, task_data, cancellable)¶

Parameters:

• task (Gio.Task) – the Gio.Task
• source_object (GObject.Object) – task's source object
• task_data (object or None) – task's task data
• cancellable (Gio.Cancellable or None) – task's Gio.Cancellable, or None

The prototype for a task function to be run in a thread viaGio.Task.run_in_thread() or Gio.Task.run_in_thread_sync().

If the return-on-cancel flag is set on task, and cancellable gets cancelled, then the Gio.Task will be completed immediately (as thoughGio.Task.return_error_if_cancelled() had been called), without waiting for the task function to complete. However, the task function will continue running in its thread in the background. The function therefore needs to be careful about how it uses externally-visible state in this case. SeeGio.Task.set_return_on_cancel() for more details.

Other than in that case, task will be completed when theGio.TaskThreadFunc returns, not when it calls ag_task_return_ function.

New in version 2.36.

Gio.VfsFileLookupFunc(vfs, identifier, *user_data)¶

Parameters:

• vfs (Gio.Vfs) – a Gio.Vfs
• identifier (str) – the identifier to look up a Gio.File for. This can either be a URI or a parse name as returned by Gio.File.get_parse_name()
• user_data (object or None) – user data passed to the function, or None

Returns:

a Gio.File for identifier.

Return type:

Gio.File or None

This function type is used by Gio.Vfs.register_uri_scheme() to make it possible for a client to associate a URI scheme to a different Gio.Fileimplementation.

The client should return a reference to the new file that has been created for uri, or None to continue with the default implementation.

New in version 2.50.