Top |
void | (*GBusAcquiredCallback) () |
void | (*GBusNameAcquiredCallback) () |
void | (*GBusNameLostCallback) () |
guint | g_bus_own_name () |
guint | g_bus_own_name_on_connection () |
void | g_bus_unown_name () |
guint | g_bus_own_name_with_closures () |
guint | g_bus_own_name_on_connection_with_closures () |
Convenience API for owning bus names.
A simple example for owning a name can be found in gdbus-example-own-name.c
void (*GBusAcquiredCallback) (GDBusConnection *connection
,const gchar *name
,gpointer user_data
);
Invoked when a connection to a message bus has been obtained.
connection |
The GDBusConnection to a message bus. |
|
name |
The name that is requested to be owned. |
|
user_data |
User data passed to |
Since: 2.26
void (*GBusNameAcquiredCallback) (GDBusConnection *connection
,const gchar *name
,gpointer user_data
);
Invoked when the name is acquired.
connection |
The GDBusConnection on which to acquired the name. |
|
name |
The name being owned. |
|
user_data |
User data passed to |
Since: 2.26
void (*GBusNameLostCallback) (GDBusConnection *connection
,const gchar *name
,gpointer user_data
);
Invoked when the name is lost or connection
has been closed.
connection |
The GDBusConnection on which to acquire the name or |
|
name |
The name being owned. |
|
user_data |
User data passed to |
Since: 2.26
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
);
Starts acquiring name
on the bus specified by bus_type
and calls
name_acquired_handler
and name_lost_handler
when the name is
acquired respectively lost. Callbacks will be invoked in the
thread-default main context
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_handler
with a NULL
connection (if a connection to the bus
can't be made).
bus_acquired_handler
then name_lost_handler
(if the name can't be
obtained)
bus_acquired_handler
then name_acquired_handler
(if the name was
obtained).
When you are done owning the name, just call g_bus_unown_name()
with the owner id this function returns.
If the name is acquired or lost (for example another application
could acquire the name if you allow replacement or the application
currently owning the name exits), the handlers are also invoked.
If the GDBusConnection that is used for attempting to own the name
closes, then name_lost_handler
is invoked since it is no longer
possible for other processes to access the process.
You cannot use g_bus_own_name()
several times for the same name (unless
interleaved with calls to g_bus_unown_name()
) - only the first call
will work.
Another guarantee is that invocations of name_acquired_handler
and name_lost_handler
are guaranteed to alternate; that
is, if name_acquired_handler
is invoked then you are
guaranteed that the next time one of the handlers is invoked, it
will be name_lost_handler
. The reverse is also true.
If you plan on exporting objects (using e.g.
g_dbus_connection_register_object()
), note that it is generally too late
to export the objects in name_acquired_handler
. Instead, you can do this
in bus_acquired_handler
since you are guaranteed that this will run
before name
is requested from the bus.
This behavior makes it very simple to write applications that wants
to own names and export objects.
Simply register objects to be exported in bus_acquired_handler
and
unregister the objects (if any) in name_lost_handler
.
bus_type |
the type of bus to own a name on |
|
name |
the well-known name to own |
|
flags |
a set of flags from the GBusNameOwnerFlags enumeration |
|
bus_acquired_handler |
handler to invoke when connected to the bus of type |
[nullable] |
name_acquired_handler |
handler to invoke when |
[nullable] |
name_lost_handler |
handler to invoke when |
[nullable] |
user_data |
user data to pass to handlers |
|
user_data_free_func |
function for freeing |
[nullable] |
Since: 2.26
guint g_bus_own_name_on_connection (GDBusConnection *connection
,const gchar *name
,GBusNameOwnerFlags flags
,GBusNameAcquiredCallback name_acquired_handler
,GBusNameLostCallback name_lost_handler
,gpointer user_data
,GDestroyNotify user_data_free_func
);
Like g_bus_own_name()
but takes a GDBusConnection instead of a
GBusType.
connection |
||
name |
the well-known name to own |
|
flags |
a set of flags from the GBusNameOwnerFlags enumeration |
|
name_acquired_handler |
handler to invoke when |
[nullable] |
name_lost_handler |
handler to invoke when |
[nullable] |
user_data |
user data to pass to handlers |
|
user_data_free_func |
function for freeing |
[nullable] |
Since: 2.26
void
g_bus_unown_name (guint owner_id
);
Stops owning a name.
Note that there may still be D-Bus traffic to process (relating to owning
and unowning the name) in the current thread-default GMainContext after
this function has returned. You should continue to iterate the GMainContext
until the GDestroyNotify function passed to g_bus_own_name()
is called, in
order to avoid memory leaks through callbacks queued on the GMainContext
after it’s stopped being iterated.
Since: 2.26
guint g_bus_own_name_with_closures (GBusType bus_type
,const gchar *name
,GBusNameOwnerFlags flags
,GClosure *bus_acquired_closure
,GClosure *name_acquired_closure
,GClosure *name_lost_closure
);
Version of g_bus_own_name()
using closures instead of callbacks for
easier binding in other languages.
[rename-to g_bus_own_name]
bus_type |
the type of bus to own a name on |
|
name |
the well-known name to own |
|
flags |
a set of flags from the GBusNameOwnerFlags enumeration |
|
bus_acquired_closure |
GClosure to invoke when connected to
the bus of type |
[nullable] |
name_acquired_closure |
GClosure to invoke when |
[nullable] |
name_lost_closure |
GClosure to invoke when |
[nullable] |
Since: 2.26
guint g_bus_own_name_on_connection_with_closures (GDBusConnection *connection
,const gchar *name
,GBusNameOwnerFlags flags
,GClosure *name_acquired_closure
,GClosure *name_lost_closure
);
Version of g_bus_own_name_on_connection()
using closures instead of
callbacks for easier binding in other languages.
[rename-to g_bus_own_name_on_connection]
connection |
||
name |
the well-known name to own |
|
flags |
a set of flags from the GBusNameOwnerFlags enumeration |
|
name_acquired_closure |
GClosure to invoke when |
[nullable] |
name_lost_closure |
GClosure to invoke when |
[nullable] |
Since: 2.26
Flags used in g_bus_own_name()
.
No flags set. |
||
Allow another message bus connection to claim the name. |
||
If another message bus connection owns the name and have
specified |
||
If another message bus connection owns the name, immediately
return an error from |
Since: 2.26