Watching Bus Names

## Watching Bus Names Watching Bus Names — Simple API for watching bus names |

## Synopsis

    #include <gio/gio.h>

    void                (*GBusNameAppearedCallback)         (GDBusConnection *connection,
                                                             const gchar *name,
                                                             const gchar *name_owner,
                                                             gpointer user_data);
    void                (*GBusNameVanishedCallback)         (GDBusConnection *connection,
                                                             const gchar *name,
                                                             gpointer user_data);
    enum                GBusNameWatcherFlags;
    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);
    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);
    void                g_bus_unwatch_name                  (guint watcher_id);
    guint               g_bus_watch_name_with_closures      (GBusType bus_type,
                                                             const gchar *name,
                                                             GBusNameWatcherFlags flags,
                                                             GClosure *name_appeared_closure,
                                                             GClosure *name_vanished_closure);
    guint               g_bus_watch_name_on_connection_with_closures
                                                            (GDBusConnection *connection,
                                                             const gchar *name,
                                                             GBusNameWatcherFlags flags,
                                                             GClosure *name_appeared_closure,
                                                             GClosure *name_vanished_closure);

## Description

Convenience API for watching bus names.

Example 9. Simple application watching a name

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    #include <gio/gio.h>

    static gchar *opt_name         = NULL;
    static gboolean opt_system_bus = FALSE;
    static gboolean opt_auto_start = FALSE;

    static GOptionEntry opt_entries[] =
    {
      { "name", 'n', 0, G_OPTION_ARG_STRING, &opt_name, "Name to watch", NULL },
      { "system-bus", 's', 0, G_OPTION_ARG_NONE, &opt_system_bus, "Use the system-bus instead of the session-bus", NULL },
      { "auto-start", 'a', 0, G_OPTION_ARG_NONE, &opt_auto_start, "Instruct the bus to launch an owner for the name", NULL},
      { NULL}
    };

    static void
    on_name_appeared (GDBusConnection *connection,
                      const gchar     *name,
                      const gchar     *name_owner,
                      gpointer         user_data)
    {
      g_print ("Name %s on %s is owned by %s\n",
               name,
               opt_system_bus ? "the system bus" : "the session bus",
               name_owner);
    }

    static void
    on_name_vanished (GDBusConnection *connection,
                      const gchar     *name,
                      gpointer         user_data)
    {
      g_print ("Name %s does not exist on %s\n",
               name,
               opt_system_bus ? "the system bus" : "the session bus");
    }

    int
    main (int argc, char *argv[])
    {
      guint watcher_id;
      GMainLoop *loop;
      GOptionContext *opt_context;
      GError *error;
      GBusNameWatcherFlags flags;

      g_type_init ();

      error = NULL;
      opt_context = g_option_context_new ("g_bus_watch_name() example");
      g_option_context_set_summary (opt_context,
                                    "Example: to watch the power manager on the session bus, use:\n"
                                    "\n"
                                    "  ./example-watch-name -n org.gnome.PowerManager");
      g_option_context_add_main_entries (opt_context, opt_entries, NULL);
      if (!g_option_context_parse (opt_context, &argc, &argv, &error))
        {
          g_printerr ("Error parsing options: %s", error->message);
          goto out;
        }
      if (opt_name == NULL)
        {
          g_printerr ("Incorrect usage, try --help.\n");
          goto out;
        }

      flags = G_BUS_NAME_WATCHER_FLAGS_NONE;
      if (opt_auto_start)
        flags |= G_BUS_NAME_WATCHER_FLAGS_AUTO_START;

      watcher_id = g_bus_watch_name (opt_system_bus ? G_BUS_TYPE_SYSTEM : G_BUS_TYPE_SESSION,
                                     opt_name,
                                     flags,
                                     on_name_appeared,
                                     on_name_vanished,
                                     NULL,
                                     NULL);

      loop = g_main_loop_new (NULL, FALSE);
      g_main_loop_run (loop);

      g_bus_unwatch_name (watcher_id);

     out:
      g_option_context_free (opt_context);
      g_free (opt_name);

      return 0;
    }

## Details

### 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.

`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.

`connection` : | The GDBusConnection the name is being watched on.
`name` : | The name being watched.
`user_data` : | User data passed to `g_bus_watch_name()`.

Since 2.26

### enum GBusNameWatcherFlags

    typedef enum
    {
      G_BUS_NAME_WATCHER_FLAGS_NONE = 0,
      G_BUS_NAME_WATCHER_FLAGS_AUTO_START = (1<<0)
    } GBusNameWatcherFlags;

Flags used in `g_bus_watch_name()`.

`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

### 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 loop 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 wants to take action when a certain name exists, see Example 9, “Simple application watching a name”. Basically, the application should create object proxies in `name_appeared_handler` and destroy them again (if any) in `name_vanished_handler`.

`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`.
`name_vanished_handler` : | Handler to invoke when `name` is known to not exist or `NULL`.
`user_data` : | User data to pass to handlers.
`user_data_free_func` : | Function for freeing `user_data` or `NULL`.
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.

`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`.
`name_vanished_handler` : | Handler to invoke when `name` is known to not exist or `NULL`.
`user_data` : | User data to pass to handlers.
`user_data_free_func` : | Function for freeing `user_data` or `NULL`.
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.

`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.

`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. Rename to: g_bus_watch_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.

`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. Rename to: g_bus_watch_name_on_connection

Since 2.26