Gio.bus_own_name
Description: Reference for Gio.bus_own_name

### Function

# Giobus_own_name

since: 2.26

#### Declaration [src]

    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
    )

#### Description [src]

Requests ownership of `name` on the bus specified by `bus_type`.

It asynchronously calls `name_acquired_handler` and `name_lost_handler` when the name is acquired and lost, respectively.

Callbacks will be invoked in the thread-default main context (see `g_main_context_push_thread_default()`) 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, 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, for example, `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 want to own names and export objects. Simply register objects to be exported in `bus_acquired_handler` and unregister the objects (if any) in `name_lost_handler`.

Available since: 2.26

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

#### Parameters

`bus_type`

  Type: `GBusType`

  The type of bus to own a name on.

`name`

  Type: `const gchar*`

  The well-known name to own.

  The data is owned by the caller of the function.
  The value is a NUL terminated UTF-8 string.

`flags`

  Type: `GBusNameOwnerFlags`

  A set of flags with ownership options.

`bus_acquired_handler`

  Type: `GBusAcquiredCallback`

  Handler to invoke when connected to the bus of type `bus_type`, or `NULL` to ignore.

  The argument can be `NULL`.

`name_acquired_handler`

  Type: `GBusNameAcquiredCallback`

  Handler to invoke when `name` is acquired, or `NULL` to ignore.

  The argument can be `NULL`.

`name_lost_handler`

  Type: `GBusNameLostCallback`

  Handler to invoke when `name` is lost, or `NULL` to ignore.

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

  The argument can be `NULL`.

#### Return value

Type: `guint`

An identifier (never 0) that can be used with `g_bus_unown_name()` to stop owning the name.