Function
Giobus_watch_name
Declaration
guint
g_bus_watch_name (
GBusType bus_type,
const gchar* name,
GBusNameWatcherFlags flags,
GBusNameAppearedCallback name_appeared_handler,
GBusNameVanishedCallback name_vanished_handler,
gpointer user_data,
GDestroyNotify user_data_free_func
)
Description
Starts watching name
on the bus specified by bus_type
and calls
name_appeared_handler
and name_vanished_handler
when the name is
known to have an owner respectively known to lose its
owner. Callbacks will be invoked in the
[thread-default main context][g-main-context-push-thread-default]
of the thread you are calling this function from.
You are guaranteed that one of the handlers will be invoked after
calling this function. When you are done watching the name, just
call g_bus_unwatch_name()
with the watcher id this function returns.
If the name vanishes or appears (for example the application owning
the name could restart), the handlers are also invoked. If the
GDBusConnection
that is used for watching the name disconnects, then
name_vanished_handler
is invoked since it is no longer
possible to access the name.
Another guarantee is that invocations of name_appeared_handler
and name_vanished_handler
are guaranteed to alternate; that
is, if name_appeared_handler
is invoked then you are
guaranteed that the next time one of the handlers is invoked, it
will be name_vanished_handler
. The reverse is also true.
This behavior makes it very simple to write applications that want
to take action when a certain [name exists][gdbus-watching-names].
Basically, the application should create object proxies in
name_appeared_handler
and destroy them again (if any) in
name_vanished_handler
.
Available since: | 2.26 |
This function is not directly available to language bindings | |
The implementation of this function is provided by g_bus_watch_name_with_closures() in language bindings |
Parameters
bus_type |
GBusType |
The type of bus to watch a name on. |
|
name |
const gchar* |
The name (well-known or unique) to watch. |
|
The data is owned by the caller of the function. | |
The value is a NUL terminated UTF-8 string. | |
flags |
GBusNameWatcherFlags |
Flags from the |
|
name_appeared_handler |
GBusNameAppearedCallback |
Handler to invoke when |
|
The argument can be NULL . | |
name_vanished_handler |
GBusNameVanishedCallback |
Handler to invoke when |
|
The argument can be NULL . | |
user_data |
gpointer |
User data to pass to handlers. |
|
The argument can be NULL . | |
The data is owned by the caller of the function. | |
user_data_free_func |
GDestroyNotify |
Function for freeing |
|
The argument can be NULL . |