Owning Bus Names

Owning Bus Names — Simple API for owning bus names

Functions

Types and Values

Object Hierarchy

    GFlags
    ╰── GBusNameOwnerFlags

Includes

#include <gio/gio.h>

Description

Convenience API for owning bus names.

A simple example for owning a name can be found in gdbus-example-own-name.c

Functions

GBusAcquiredCallback ()

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

Invoked when a connection to a message bus has been obtained.

Parameters

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.

Parameters

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.

Parameters

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


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 context 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. Simply register objects to be exported in bus_acquired_handler and unregister the objects (if any) in name_lost_handler .

Parameters

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.

[nullable]

name_acquired_handler

handler to invoke when name is acquired or NULL.

[nullable]

name_lost_handler

handler to invoke when name is lost or NULL.

[nullable]

user_data

user data to pass to handlers

 

user_data_free_func

function for freeing user_data or NULL.

[nullable]

Returns

an identifier (never 0) that can 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.

Parameters

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.

[nullable]

name_lost_handler

handler to invoke when name is lost or NULL.

[nullable]

user_data

user data to pass to handlers

 

user_data_free_func

function for freeing user_data or NULL.

[nullable]

Returns

an identifier (never 0) that can 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.

Note that there may still be D-Bus traffic to process (relating to owning and unowning the name) in the current thread-default GMainContext after this function has returned. You should continue to iterate the GMainContext until the GDestroyNotify function passed to g_bus_own_name() is called, in order to avoid memory leaks through callbacks queued on the GMainContext after it’s stopped being iterated.

Parameters

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.

[rename-to g_bus_own_name]

Parameters

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.

[nullable]

name_acquired_closure

GClosure to invoke when name is acquired or NULL.

[nullable]

name_lost_closure

GClosure to invoke when name is lost or NULL.

[nullable]

Returns

an identifier (never 0) that can be used with g_bus_unown_name() to stop owning the 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.

[rename-to g_bus_own_name_on_connection]

Parameters

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.

[nullable]

name_lost_closure

GClosure to invoke when name is lost or NULL.

[nullable]

Returns

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

Since: 2.26

Types and Values

enum GBusNameOwnerFlags

Flags used in g_bus_own_name().

Members

G_BUS_NAME_OWNER_FLAGS_NONE

No flags set.

 

G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT

Allow another message bus connection to claim 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.

 

G_BUS_NAME_OWNER_FLAGS_DO_NOT_QUEUE

If another message bus connection owns the name, immediately return an error from g_bus_own_name() rather than entering the waiting queue for that name. (Since 2.54)

 

Since: 2.26