Function

Giobus_own_name

since: 2.26

Declaration 

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

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 context][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, 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][gdbus-owning-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 method 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 from the GBusNameOwnerFlags enumeration.

bus_acquired_handler

Type: GBusAcquiredCallback

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

The argument can be NULL.
name_acquired_handler

Type: GBusNameAcquiredCallback

Handler to invoke when name is acquired or NULL.

The argument can be NULL.
name_lost_handler

Type: GBusNameLostCallback

Handler to invoke when name is lost 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_unown_name() to stop owning the name.