Callbacks

AsyncReadyCallback (source_object, res, data)

BusAcquiredCallback (connection, name, *user_data)

BusNameAcquiredCallback (connection, name, *user_data)

BusNameAppearedCallback (connection, name, name_owner, *user_data)

BusNameLostCallback (connection, name, *user_data)

BusNameVanishedCallback (connection, name, *user_data)

CancellableSourceFunc (cancellable, data)

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

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

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

DBusMessageFilterFunction (connection, message, incoming, *user_data)

DBusProxyTypeFunc (manager, object_path, interface_name, data)

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

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

DBusSubtreeEnumerateFunc (connection, sender, object_path, *user_data)

DBusSubtreeIntrospectFunc (connection, sender, object_path, node, *user_data)

DatagramBasedSourceFunc (datagram_based, condition, data)

DesktopAppLaunchCallback (appinfo, pid, *user_data)

FileMeasureProgressCallback (reporting, current_size, num_dirs, num_files, data)

FileProgressCallback (current_num_bytes, total_num_bytes, data)

FileReadMoreCallback (file_contents, file_size, callback_data)

IOSchedulerJobFunc (job, cancellable, data)

PollableSourceFunc (pollable_stream, data)

ReallocFunc (data, size)

SettingsBindGetMapping (value, variant, *user_data)

SettingsBindSetMapping (value, expected_type, *user_data)

SettingsGetMapping (value, *user_data)

SimpleAsyncThreadFunc (res, object, cancellable)

SocketSourceFunc (socket, condition, data)

TaskThreadFunc (task, source_object, task_data, cancellable)

VfsFileLookupFunc (vfs, identifier, *user_data)

Details

Gio.AsyncReadyCallback(source_object, res, data)
Parameters:

Type definition for a function that will be called back when an asynchronous operation within GIO has been completed. Gio.AsyncReadyCallback callbacks 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 of Gio.AsyncReadyCallback must likewise call it asynchronously in a later iteration of the main context.

The asynchronous operation is guaranteed to have held a reference to source_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:

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:

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 be None.

New in version 2.26.

Gio.CancellableSourceFunc(cancellable, data)
Parameters:
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.Source returned by Gio.Cancellable.source_new().

New in version 2.28.

Gio.DBusInterfaceGetPropertyFunc(connection, sender, object_path, interface_name, property_name, error, *user_data)
Parameters:
Returns:

A GLib.Variant with the value for property_name or None if error 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:

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 the D-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:
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:
Returns:

A Gio.DBusMessage that will be freed with GObject.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 a Gio.DBusCapabilityFlags value obtained from connection.

New in version 2.26.

Gio.DBusProxyTypeFunc(manager, object_path, interface_name, data)
Parameters:
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:
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:
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 the Gio.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:
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.DBusInterfaceInfo structures 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 None case.

New in version 2.26.

Gio.DatagramBasedSourceFunc(datagram_based, condition, data)
Parameters:
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.Source returned by Gio.DatagramBased.create_source().

New in version 2.48.

Gio.DesktopAppLaunchCallback(appinfo, pid, *user_data)
Parameters:

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 of Gio.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 to False (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 (see Gio.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:
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 cancellable to 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:
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.Source returned by Gio.PollableInputStream.create_source() and Gio.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 to size 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 at result and true returned. If mapping fails (for example, if value is not in the right format) then false should be returned.

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

Gio.SimpleAsyncThreadFunc(res, object, cancellable)
Parameters:

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

Gio.SocketSourceFunc(socket, condition, data)
Parameters:
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.Source returned by g_socket_create_source().

New in version 2.22.

Gio.TaskThreadFunc(task, source_object, task_data, cancellable)
Parameters:

The prototype for a task function to be run in a thread via Gio.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 though Gio.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. See Gio.Task.set_return_on_cancel() for more details.

Other than in that case, task will be completed when the Gio.TaskThreadFunc returns, not when it calls a g_task_return_ function.

New in version 2.36.

Gio.VfsFileLookupFunc(vfs, identifier, *user_data)
Parameters:
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.File implementation.

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.