Watching Bus Names: GIO Reference Manual

Watching Bus Names

Watching Bus Names — Simple API for watching bus names

Functions

void	(*GBusNameAppearedCallback) ()
void	(*GBusNameVanishedCallback) ()
guint	g_bus_watch_name ()
guint	g_bus_watch_name_on_connection ()
void	g_bus_unwatch_name ()
guint	g_bus_watch_name_with_closures ()
guint	g_bus_watch_name_on_connection_with_closures ()

Types and Values

enum	GBusNameWatcherFlags

Includes

#include <gio/gio.h>

Description

Convenience API for watching bus names.

A simple example for watching a name can be found in gdbus-example-watch-name.c

Functions

GBusNameAppearedCallback ()

void
(*GBusNameAppearedCallback) (GDBusConnection *connection,
                             const gchar *name,
                             const gchar *name_owner,
                             gpointer user_data);

Invoked when the name being watched is known to have to have a owner.

Parameters

connection	The GDBusConnection the name is being watched on.
name	The name being watched.
name_owner	Unique name of the owner of the name being watched.
user_data	User data passed to `g_bus_watch_name()`.

Since 2.26

GBusNameVanishedCallback ()

void
(*GBusNameVanishedCallback) (GDBusConnection *connection,
                             const gchar *name,
                             gpointer user_data);

Invoked when the name being watched is known not to have to have a owner.

This is also invoked when the GDBusConection on which the watch was established has been closed. In that case, connection will be NULL.

Parameters

connection	The GDBusConnection the name is being watched on, or `NULL`.
name	The name being watched.
user_data	User data passed to `g_bus_watch_name()`.

Since 2.26

g_bus_watch_name ()

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);

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 a owner respectively known to lose its owner. 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 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. Basically, the application should create object proxies in name_appeared_handler and destroy them again (if any) in name_vanished_handler .

Parameters

bus_type	The type of bus to watch a name on.
name	The name (well-known or unique) to watch.
flags	Flags from the GBusNameWatcherFlags enumeration.
name_appeared_handler	Handler to invoke when `name` is known to exist or `NULL`.	[allow-none]
name_vanished_handler	Handler to invoke when `name` is known to not exist or `NULL`.	[allow-none]
user_data	User data to pass to handlers.
user_data_free_func	Function for freeing `user_data` or `NULL`.	[allow-none]

Returns

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

Since 2.26

g_bus_watch_name_on_connection ()

guint
g_bus_watch_name_on_connection (GDBusConnection *connection,
                                const gchar *name,
                                GBusNameWatcherFlags flags,
                                GBusNameAppearedCallback name_appeared_handler,
                                GBusNameVanishedCallback name_vanished_handler,
                                gpointer user_data,
                                GDestroyNotify user_data_free_func);

Like g_bus_watch_name() but takes a GDBusConnection instead of a GBusType.

Parameters

connection	A GDBusConnection.
name	The name (well-known or unique) to watch.
flags	Flags from the GBusNameWatcherFlags enumeration.
name_appeared_handler	Handler to invoke when `name` is known to exist or `NULL`.	[allow-none]
name_vanished_handler	Handler to invoke when `name` is known to not exist or `NULL`.	[allow-none]
user_data	User data to pass to handlers.
user_data_free_func	Function for freeing `user_data` or `NULL`.	[allow-none]

Returns

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

Since 2.26

g_bus_unwatch_name ()

void
g_bus_unwatch_name (guint watcher_id);

Stops watching a name.

Parameters

watcher_id

An identifier obtained from g_bus_watch_name()

Since 2.26

g_bus_watch_name_with_closures ()

guint
g_bus_watch_name_with_closures (GBusType bus_type,
                                const gchar *name,
                                GBusNameWatcherFlags flags,
                                GClosure *name_appeared_closure,
                                GClosure *name_vanished_closure);

Version of g_bus_watch_name() using closures instead of callbacks for easier binding in other languages.

Parameters

bus_type	The type of bus to watch a name on.
name	The name (well-known or unique) to watch.
flags	Flags from the GBusNameWatcherFlags enumeration.
name_appeared_closure	GClosure to invoke when `name` is known to exist or `NULL`.	[allow-none]
name_vanished_closure	GClosure to invoke when `name` is known to not exist or `NULL`.	[allow-none]

Returns

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

Since 2.26

g_bus_watch_name_on_connection_with_closures ()

guint
g_bus_watch_name_on_connection_with_closures
                               (GDBusConnection *connection,
                                const gchar *name,
                                GBusNameWatcherFlags flags,
                                GClosure *name_appeared_closure,
                                GClosure *name_vanished_closure);

Version of g_bus_watch_name_on_connection() using closures instead of callbacks for easier binding in other languages.

Parameters

connection	A GDBusConnection.
name	The name (well-known or unique) to watch.
flags	Flags from the GBusNameWatcherFlags enumeration.
name_appeared_closure	GClosure to invoke when `name` is known to exist or `NULL`.	[allow-none]
name_vanished_closure	GClosure to invoke when `name` is known to not exist or `NULL`.	[allow-none]

Returns

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

Since 2.26

Types and Values

enum GBusNameWatcherFlags

Flags used in g_bus_watch_name().

Members

G_BUS_NAME_WATCHER_FLAGS_NONE	No flags set.
G_BUS_NAME_WATCHER_FLAGS_AUTO_START	If no-one owns the name when beginning to watch the name, ask the bus to launch an owner for the name.

Since 2.26