Owning Bus Names

## Owning Bus Names Owning Bus Names — Simple API for owning bus names |

## Synopsis

    #include <gio/gio.h>

    void                (*GBusAcquiredCallback)             (GDBusConnection *connection,
                                                             const gchar *name,
                                                             gpointer user_data);
    void                (*GBusNameAcquiredCallback)         (GDBusConnection *connection,
                                                             const gchar *name,
                                                             gpointer user_data);
    void                (*GBusNameLostCallback)             (GDBusConnection *connection,
                                                             const gchar *name,
                                                             gpointer user_data);
    enum                GBusNameOwnerFlags;
    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);
    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);
    void                g_bus_unown_name                    (guint owner_id);
    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);
    guint               g_bus_own_name_on_connection_with_closures
                                                            (GDBusConnection *connection,
                                                             const gchar *name,
                                                             GBusNameOwnerFlags flags,
                                                             GClosure *name_acquired_closure,
                                                             GClosure *name_lost_closure);

## Description

Convenience API for owning bus names.

Example 8. Simple application owning 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
    #include <gio/gio.h>

    static void
    on_bus_acquired (GDBusConnection *connection,
                     const gchar     *name,
                     gpointer         user_data)
    {
      /* This is where we'd export some objects on the bus */
    }

    static void
    on_name_acquired (GDBusConnection *connection,
                      const gchar     *name,
                      gpointer         user_data)
    {
      g_print ("Acquired the name %s on the session bus\n", name);
    }

    static void
    on_name_lost (GDBusConnection *connection,
                  const gchar     *name,
                  gpointer         user_data)
    {
      g_print ("Lost the name %s on the session bus\n", name);
    }

    int
    main (int argc, char *argv[])
    {
      guint owner_id;
      GMainLoop *loop;
      GBusNameOwnerFlags flags;
      gboolean opt_replace;
      gboolean opt_allow_replacement;
      gchar *opt_name;
      GOptionContext *opt_context;
      GError *error;
      GOptionEntry opt_entries[] =
        {
          { "replace", 'r', 0, G_OPTION_ARG_NONE, &opt_replace, "Replace existing name if possible", NULL },
          { "allow-replacement", 'a', 0, G_OPTION_ARG_NONE, &opt_allow_replacement, "Allow replacement", NULL },
          { "name", 'n', 0, G_OPTION_ARG_STRING, &opt_name, "Name to acquire", NULL },
          { NULL}
        };

      g_type_init ();

      error = NULL;
      opt_name = NULL;
      opt_replace = FALSE;
      opt_allow_replacement = FALSE;
      opt_context = g_option_context_new ("g_bus_own_name() example");
      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);
          return 1;
        }
      if (opt_name == NULL)
        {
          g_printerr ("Incorrect usage, try --help.\n");
          return 1;
        }

      flags = G_BUS_NAME_OWNER_FLAGS_NONE;
      if (opt_replace)
        flags |= G_BUS_NAME_OWNER_FLAGS_REPLACE;
      if (opt_allow_replacement)
        flags |= G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT;

      owner_id = g_bus_own_name (G_BUS_TYPE_SESSION,
                                 opt_name,
                                 flags,
                                 on_bus_acquired,
                                 on_name_acquired,
                                 on_name_lost,
                                 NULL,
                                 NULL);

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

      g_bus_unown_name (owner_id);

      return 0;
    }

## Details

### GBusAcquiredCallback ()

    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 `g_bus_own_name()`.

Since 2.26

### GBusNameAcquiredCallback ()

    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 `g_bus_own_name()` or `g_bus_own_name_on_connection()`.

Since 2.26

### GBusNameLostCallback ()

    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 `NULL` if the connection was disconnected.
`name` : | The name being owned.
`user_data` : | User data passed to `g_bus_own_name()` or `g_bus_own_name_on_connection()`.

Since 2.26

### enum GBusNameOwnerFlags

    typedef enum {
      G_BUS_NAME_OWNER_FLAGS_NONE = 0,                    /*< nick=none >*/
      G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT = (1<<0),  /*< nick=allow-replacement >*/
      G_BUS_NAME_OWNER_FLAGS_REPLACE = (1<<1)            /*< nick=replace >*/
    } GBusNameOwnerFlags;

Flags used in `g_bus_own_name()`.

`G_BUS_NAME_OWNER_FLAGS_NONE` | No flags set.
`G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT` | Allow another message bus connection to claim the the name.
`G_BUS_NAME_OWNER_FLAGS_REPLACE` | If another message bus connection owns the name and have specified G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection.

Since 2.26

### g_bus_own_name ()

    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 loop 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, see Example 8, “Simple application owning a name”. 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 `bus_type` or `NULL`.
`name_acquired_handler` : | Handler to invoke when `name` is acquired or `NULL`.
`name_lost_handler` : | Handler to invoke when `name` is lost 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_unown_name()` to stop owning the name.

Since 2.26

### g_bus_own_name_on_connection ()

    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` : | A GDBusConnection.
`name` : | The well-known name to own.
`flags` : | A set of flags from the GBusNameOwnerFlags enumeration.
`name_acquired_handler` : | Handler to invoke when `name` is acquired or `NULL`.
`name_lost_handler` : | Handler to invoke when `name` is lost 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_unown_name()` to stop owning the name.

Since 2.26

### g_bus_unown_name ()

    void                g_bus_unown_name                    (guint owner_id);

Stops owning a name.

`owner_id` : | An identifier obtained from `g_bus_own_name()`

Since 2.26

### g_bus_own_name_with_closures ()

    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.

`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 `bus_type` or `NULL`. [allow-none]
`name_acquired_closure` : | GClosure to invoke when `name` is acquired or `NULL`. [allow-none]
`name_lost_closure` : | GClosure to invoke when `name` is lost or `NULL`. [allow-none]
Returns : | An identifier (never 0) that an be used with `g_bus_unown_name()` to stop owning the name. Rename to: g_bus_own_name

Since 2.26

### g_bus_own_name_on_connection_with_closures ()

    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.

`connection` : | A GDBusConnection.
`name` : | The well-known name to own.
`flags` : | A set of flags from the GBusNameOwnerFlags enumeration.
`name_acquired_closure` : | GClosure to invoke when `name` is acquired or `NULL`. [allow-none]
`name_lost_closure` : | GClosure to invoke when `name` is lost or `NULL`. [allow-none]
Returns : | An identifier (never 0) that an be used with `g_bus_unown_name()` to stop owning the name. Rename to: g_bus_own_name_on_connection

Since 2.26