Function
Giobus_own_name
since: 2.26
Declaration [src]
guint
g_bus_own_name (
GBusType bus_type,
const gchar* name,
GBusNameOwnerFlags flags,
GBusAcquiredCallback bus_acquired_handler,
GBusNameAcquiredCallback name_acquired_handler,
GBusNameLostCallback name_lost_handler,
gpointer user_data,
GDestroyNotify user_data_free_func
)
Description [src]
Requests ownership of name on the bus specified by bus_type.
It asynchronously calls name_acquired_handler and name_lost_handler when
the name is acquired and lost, respectively.
Callbacks will be invoked in the thread-default
main context (see g_main_context_push_thread_default())
of the thread you are calling this function from.
You are guaranteed that one of the name_acquired_handler and name_lost_handler
callbacks will be invoked after calling this function — there are three
possible cases:
name_lost_handlerwith aNULLconnection (if a connection to the bus can’t be made).bus_acquired_handlerthenname_lost_handler(if the name can’t be obtained).bus_acquired_handlerthenname_acquired_handler(if the name was obtained).
When you are done owning the name, call g_bus_unown_name() with the
owner ID this function returns.
If the name is acquired or lost (for example another application
could acquire the name if you allow replacement or the application
currently owning the name exits), the handlers are also invoked.
If the GDBusConnection that is used for attempting to own the name
closes, then name_lost_handler is invoked since it is no longer
possible for other processes to access the process.
You cannot use g_bus_own_name() several times for the same name (unless
interleaved with calls to g_bus_unown_name()) — only the first call
will work.
Another guarantee is that invocations of name_acquired_handler
and name_lost_handler are guaranteed to alternate; that
is, if name_acquired_handler is invoked then you are
guaranteed that the next time one of the handlers is invoked, it
will be name_lost_handler. The reverse is also true.
If you plan on exporting objects (using, for example,
g_dbus_connection_register_object()), note that it is generally too late
to export the objects in name_acquired_handler. Instead, you can do this in bus_acquired_handler since you are guaranteed that this will run before name is requested from the bus.
This behavior makes it very simple to write applications that want
to own names and export objects.
Simply register objects to be exported in bus_acquired_handler and
unregister the objects (if any) in name_lost_handler.
Available since: 2.26
The implementation of this function is provided by g_bus_own_name_with_closures() in language bindings.
Parameters
bus_type-
Type:
GBusTypeThe type of bus to own a name on.
name-
Type:
const gchar*The well-known name to own.
The data is owned by the caller of the function. The value is a NUL terminated UTF-8 string. flags-
Type:
GBusNameOwnerFlagsA set of flags with ownership options.
bus_acquired_handler-
Type:
GBusAcquiredCallbackHandler to invoke when connected to the bus of type
bus_type, orNULLto ignore.The argument can be NULL. name_acquired_handler-
Type:
GBusNameAcquiredCallbackHandler to invoke when
nameis acquired, orNULLto ignore.The argument can be NULL. name_lost_handler-
Type:
GBusNameLostCallbackHandler to invoke when
nameis lost, orNULLto ignore.The argument can be NULL. user_data-
Type:
gpointerUser data to pass to handlers.
The argument can be NULL.The data is owned by the caller of the function. user_data_free_func-
Type:
GDestroyNotifyFunction for freeing
user_data.The argument can be NULL.
Return value
Type: guint
An identifier (never 0) that can be used with
g_bus_unown_name() to stop owning the name.