Function

Giobus_watch_name

since: 2.26

Declaration [src]

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 [src]

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

The implementation of this function is provided by g_bus_watch_name_with_closures() in language bindings.

Parameters

bus_type

Type: GBusType

The type of bus to watch a name on.

name

Type: 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

Type: GBusNameWatcherFlags

Flags from the GBusNameWatcherFlags enumeration.

name_appeared_handler

Type: GBusNameAppearedCallback

Handler to invoke when name is known to exist or NULL.

The argument can be NULL.

name_vanished_handler

Type: GBusNameVanishedCallback

Handler to invoke when name is known to not exist or NULL.

The argument can be NULL.

user_data

Type: 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

Type: GDestroyNotify

Function for freeing user_data or NULL.

The argument can be NULL.

Return value

Type: guint

An identifier (never 0) that can be used with g_bus_unwatch_name() to stop watching the name.