D-Bus helper library

D-Bus helper library — Library for simple D-Bus integration with GLib

Synopsis

void                (*GDBusDestroyFunction)             (void *user_data);
enum                GDBusMethodFlags;
DBusMessage *       (*GDBusMethodFunction)              (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         void *user_data);
                    GDBusMethodTable;
enum                GDBusPropertyFlags;
dbus_bool_t         (*GDBusPropertyGetFunction)         (DBusConnection *connection,
                                                         DBusMessageIter *iter,
                                                         void *user_data);
dbus_bool_t         (*GDBusPropertySetFunction)         (DBusConnection *connection,
                                                         DBusMessageIter *iter,
                                                         void *user_data);
                    GDBusPropertyTable;
enum                GDBusSignalFlags;
gboolean            (*GDBusSignalFunction)              (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         void *user_data);
                    GDBusSignalTable;
void                (*GDBusWatchFunction)               (void *user_data);
guint               g_dbus_add_disconnect_watch         (DBusConnection *connection,
                                                         const char *name,
                                                         GDBusWatchFunction function,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);
guint               g_dbus_add_service_watch            (DBusConnection *connection,
                                                         const char *name,
                                                         GDBusWatchFunction connect,
                                                         GDBusWatchFunction disconnect,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);
guint               g_dbus_add_signal_watch             (DBusConnection *connection,
                                                         const char *rule,
                                                         GDBusSignalFunction function,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);
void                g_dbus_cleanup_connection           (DBusConnection *connection);
DBusMessage *       g_dbus_create_error                 (DBusMessage *message,
                                                         const char *name,
                                                         const char *format,
                                                         ...);
DBusMessage *       g_dbus_create_error_valist          (DBusMessage *message,
                                                         const char *name,
                                                         const char *format,
                                                         va_list args);
DBusMessage *       g_dbus_create_reply                 (DBusMessage *message,
                                                         int type,
                                                         ...);
DBusMessage *       g_dbus_create_reply_valist          (DBusMessage *message,
                                                         int type,
                                                         va_list args);
gboolean            g_dbus_emit_signal                  (DBusConnection *connection,
                                                         const char *path,
                                                         const char *interface,
                                                         const char *name,
                                                         int type,
                                                         ...);
gboolean            g_dbus_emit_signal_valist           (DBusConnection *connection,
                                                         const char *path,
                                                         const char *interface,
                                                         const char *name,
                                                         int type,
                                                         va_list args);
gboolean            g_dbus_register_interface           (DBusConnection *connection,
                                                         const char *path,
                                                         const char *name,
                                                         GDBusMethodTable *methods,
                                                         GDBusSignalTable *signals,
                                                         GDBusPropertyTable *properties,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);
void                g_dbus_remove_all_watches           (DBusConnection *connection);
gboolean            g_dbus_remove_watch                 (DBusConnection *connection,
                                                         guint tag);
gboolean            g_dbus_request_name                 (DBusConnection *connection,
                                                         const char *name,
                                                         DBusError *error);
gboolean            g_dbus_send_error                   (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         const char *name,
                                                         const char *format,
                                                         ...);
gboolean            g_dbus_send_message                 (DBusConnection *connection,
                                                         DBusMessage *message);
gboolean            g_dbus_send_reply                   (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         int type,
                                                         ...);
gboolean            g_dbus_send_reply_valist            (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         int type,
                                                         va_list args);
gboolean            g_dbus_set_disconnect_function      (DBusConnection *connection,
                                                         GDBusWatchFunction function,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);
DBusConnection *    g_dbus_setup_address                (const char *address,
                                                         DBusError *error);
DBusConnection *    g_dbus_setup_bus                    (DBusBusType type,
                                                         const char *name,
                                                         DBusError *error);
void                g_dbus_setup_connection             (DBusConnection *connection,
                                                         GMainContext *context);
gboolean            g_dbus_unregister_interface         (DBusConnection *connection,
                                                         const char *path,
                                                         const char *name);

Description

Details

GDBusDestroyFunction ()

void                (*GDBusDestroyFunction)             (void *user_data);

Destroy function

user_data :

user data to pass to the function

enum GDBusMethodFlags

typedef enum {
	G_DBUS_METHOD_FLAG_DEPRECATED = (1 << 0),
	G_DBUS_METHOD_FLAG_NOREPLY    = (1 << 1),
	G_DBUS_METHOD_FLAG_ASYNC      = (1 << 2),
} GDBusMethodFlags;

Method flags

G_DBUS_METHOD_FLAG_DEPRECATED

annotate deprecated methods

G_DBUS_METHOD_FLAG_NOREPLY

annotate methods with no reply

G_DBUS_METHOD_FLAG_ASYNC

annotate asynchronous methods

GDBusMethodFunction ()

DBusMessage *       (*GDBusMethodFunction)              (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         void *user_data);

Method function

connection :

a DBusConnection

message :

a DBusMessage

user_data :

user data to pass to the function

Returns :

DBusMessage reply

GDBusMethodTable

typedef struct {
	const char *name;
	const char *signature;
	const char *reply;
	GDBusMethodFunction function;
	GDBusMethodFlags flags;
} GDBusMethodTable;

Method table

const char *name;

method name

const char *signature;

method signature

const char *reply;

reply signature

GDBusMethodFunction function;

method function

GDBusMethodFlags flags;

method flags

enum GDBusPropertyFlags

typedef enum {
	G_DBUS_PROPERTY_FLAG_DEPRECATED = (1 << 0),
} GDBusPropertyFlags;

Property flags

G_DBUS_PROPERTY_FLAG_DEPRECATED

annotate deprecated properties

GDBusPropertyGetFunction ()

dbus_bool_t         (*GDBusPropertyGetFunction)         (DBusConnection *connection,
                                                         DBusMessageIter *iter,
                                                         void *user_data);

Property get function

connection :

a DBusConnection

iter :

a DBusMessageIter

user_data :

user data to pass to the function

Returns :

TRUE on success

GDBusPropertySetFunction ()

dbus_bool_t         (*GDBusPropertySetFunction)         (DBusConnection *connection,
                                                         DBusMessageIter *iter,
                                                         void *user_data);

Property set function

connection :

a DBusConnection

iter :

a DBusMessageIter

user_data :

user data to pass to the function

Returns :

TRUE on success

GDBusPropertyTable

typedef struct {
	const char *name;
	const char *type;
	GDBusPropertyGetFunction get;
	GDBusPropertyGetFunction set;
	GDBusPropertyFlags flags;
} GDBusPropertyTable;

Property table

const char *name;

property name

const char *type;

property value type

GDBusPropertyGetFunction get;

property get function

GDBusPropertyGetFunction set;

property set function

GDBusPropertyFlags flags;

property flags

enum GDBusSignalFlags

typedef enum {
	G_DBUS_SIGNAL_FLAG_DEPRECATED = (1 << 0),
} GDBusSignalFlags;

Signal flags

G_DBUS_SIGNAL_FLAG_DEPRECATED

annotate deprecated signals

GDBusSignalFunction ()

gboolean            (*GDBusSignalFunction)              (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         void *user_data);

Signal function

connection :

a DBusConnection

message :

a DBusMessage

user_data :

user data to pass to the function

Returns :

FALSE to remove this watch

GDBusSignalTable

typedef struct {
	const char *name;
	const char *signature;
	GDBusSignalFlags flags;
} GDBusSignalTable;

Signal table

const char *name;

signal name

const char *signature;

signal signature

GDBusSignalFlags flags;

signal flags

GDBusWatchFunction ()

void                (*GDBusWatchFunction)               (void *user_data);

Watch function

user_data :

user data to pass to the function

g_dbus_add_disconnect_watch ()

guint               g_dbus_add_disconnect_watch         (DBusConnection *connection,
                                                         const char *name,
                                                         GDBusWatchFunction function,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);

Add new watch to listen for disconnect of a client for the given connection.

After the callback has been called, this watch will be automatically removed.

connection :

the connection

name :

unique or well known name

function :

function called on name disconnect

user_data :

user data to pass to the function

destroy :

function called to destroy user_data

Returns :

identifier of the watch

g_dbus_add_service_watch ()

guint               g_dbus_add_service_watch            (DBusConnection *connection,
                                                         const char *name,
                                                         GDBusWatchFunction connect,
                                                         GDBusWatchFunction disconnect,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);

Add new watch to listen for connects and/or disconnects of a client for the given connection.

connection :

the connection

name :

unique or well known name

connect :

function called on name connect

disconnect :

function called on name disconnect

user_data :

user data to pass to the function

destroy :

function called to destroy user_data

Returns :

identifier of the watch

g_dbus_add_signal_watch ()

guint               g_dbus_add_signal_watch             (DBusConnection *connection,
                                                         const char *rule,
                                                         GDBusSignalFunction function,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);

Add new watch to listen for specific signals of a client for the given connection.

If the callback returns FALSE this watch will be automatically removed.

connection :

the connection

rule :

matching rule for this signal

function :

function called when signal arrives

user_data :

user data to pass to the function

destroy :

function called to destroy user_data

Returns :

identifier of the watch

g_dbus_cleanup_connection ()

void                g_dbus_cleanup_connection           (DBusConnection *connection);

Cleanup the setup of DBusConnection and free the allocated memory.

connection :

a DBusConnection

g_dbus_create_error ()

DBusMessage *       g_dbus_create_error                 (DBusMessage *message,
                                                         const char *name,
                                                         const char *format,
                                                         ...);

Create error reply for the given message.

message :

the originating message

name :

the error name

format :

the error description

Returns :

reply message on success

g_dbus_create_error_valist ()

DBusMessage *       g_dbus_create_error_valist          (DBusMessage *message,
                                                         const char *name,
                                                         const char *format,
                                                         va_list args);

Create error reply for the given message.

message :

the originating message

name :

the error name

format :

the error description

args :

argument list

Returns :

reply message on success

g_dbus_create_reply ()

DBusMessage *       g_dbus_create_reply                 (DBusMessage *message,
                                                         int type,
                                                         ...);

Create reply for the given message.

message :

the originating message

type :

first argument type

Returns :

reply message on success

g_dbus_create_reply_valist ()

DBusMessage *       g_dbus_create_reply_valist          (DBusMessage *message,
                                                         int type,
                                                         va_list args);

Create reply for the given message.

message :

the originating message

type :

first argument type

args :

argument list

Returns :

reply message on success

g_dbus_emit_signal ()

gboolean            g_dbus_emit_signal                  (DBusConnection *connection,
                                                         const char *path,
                                                         const char *interface,
                                                         const char *name,
                                                         int type,
                                                         ...);

Emit a signal for the given path and interface with the given signal name.

The signal signature will be check against the registered signal table.

connection :

the connection

path :

object path

interface :

interface name

name :

signal name

type :

first argument type

Returns :

TRUE on success

g_dbus_emit_signal_valist ()

gboolean            g_dbus_emit_signal_valist           (DBusConnection *connection,
                                                         const char *path,
                                                         const char *interface,
                                                         const char *name,
                                                         int type,
                                                         va_list args);

Emit a signal for the given path and interface with the given signal name.

The signal signature will be check against the registered signal table.

connection :

the connection

path :

object path

interface :

interface name

name :

signal name

type :

first argument type

args :

argument list

Returns :

TRUE on success

g_dbus_register_interface ()

gboolean            g_dbus_register_interface           (DBusConnection *connection,
                                                         const char *path,
                                                         const char *name,
                                                         GDBusMethodTable *methods,
                                                         GDBusSignalTable *signals,
                                                         GDBusPropertyTable *properties,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);

Registers an interface for the given path in the object hierarchy with the given methods, signals and/or properties.

connection :

the connection

path :

object path

name :

interface name

methods :

method table

signals :

signal table

properties :

property table

user_data :

user data to assign to interface

destroy :

function called to destroy user_data

Returns :

TRUE on success

g_dbus_remove_all_watches ()

void                g_dbus_remove_all_watches           (DBusConnection *connection);

Removes all registered watches.

connection :

the connection

g_dbus_remove_watch ()

gboolean            g_dbus_remove_watch                 (DBusConnection *connection,
                                                         guint tag);

Removes the watch for the given identifier.

connection :

the connection

tag :

watch identifier

Returns :

TRUE on success

g_dbus_request_name ()

gboolean            g_dbus_request_name                 (DBusConnection *connection,
                                                         const char *name,
                                                         DBusError *error);

Requests a well known name for connection.

connection :

a DBusConnection

name :

well known name

error :

a DBusError

Returns :

TRUE on success

g_dbus_send_error ()

gboolean            g_dbus_send_error                   (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         const char *name,
                                                         const char *format,
                                                         ...);

Send error reply for the given message and via the given D-Bus connection.

connection :

the connection

message :

the originating message

name :

the error name

format :

the error description

Returns :

TRUE on success

g_dbus_send_message ()

gboolean            g_dbus_send_message                 (DBusConnection *connection,
                                                         DBusMessage *message);

Send message via the given D-Bus connection.

The reference count for the message will be decremented by this function.

connection :

the connection

message :

the message to send

Returns :

TRUE on success

g_dbus_send_reply ()

gboolean            g_dbus_send_reply                   (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         int type,
                                                         ...);

Send reply for the given message and via the given D-Bus connection.

connection :

the connection

message :

the originating message

type :

first argument type

Returns :

TRUE on success

g_dbus_send_reply_valist ()

gboolean            g_dbus_send_reply_valist            (DBusConnection *connection,
                                                         DBusMessage *message,
                                                         int type,
                                                         va_list args);

Send reply for the given message and via the given D-Bus connection.

connection :

the connection

message :

the originating message

type :

first argument type

args :

argument list

Returns :

TRUE on success

g_dbus_set_disconnect_function ()

gboolean            g_dbus_set_disconnect_function      (DBusConnection *connection,
                                                         GDBusWatchFunction function,
                                                         void *user_data,
                                                         GDBusDestroyFunction destroy);

Set a callback function that will be called when the D-Bus message bus exits.

connection :

a DBusConnection

function :

a GDBusWatchFunction

user_data :

user data to pass to the function

destroy :

a GDBusDestroyFunction

Returns :

TRUE on success

g_dbus_setup_address ()

DBusConnection *    g_dbus_setup_address                (const char *address,
                                                         DBusError *error);

Connect to bus and setup connection

Returns a connection to the bus specified via the given address and sets the watch and timeout functions for it.

address :

bus address

error :

a DBusError

Returns :

newly setup DBusConnection

g_dbus_setup_bus ()

DBusConnection *    g_dbus_setup_bus                    (DBusBusType type,
                                                         const char *name,
                                                         DBusError *error);

Connect to bus and setup connection

Returns a connection to the given bus and requests a well known name for it. Sets the watch and timeout functions for it.

type :

a DBusBusType

name :

well known name

error :

a DBusError

Returns :

newly setup DBusConnection

g_dbus_setup_connection ()

void                g_dbus_setup_connection             (DBusConnection *connection,
                                                         GMainContext *context);

Setup connection with main context

Sets the watch and timeout functions of a DBusConnection to integrate the connection with the GLib main loop. Pass in NULL for the GMainContext unless you're doing something specialized.

connection :

a DBusConnection

context :

a GMainContext or NULL for default context

g_dbus_unregister_interface ()

gboolean            g_dbus_unregister_interface         (DBusConnection *connection,
                                                         const char *path,
                                                         const char *name);

Unregister the given interface for the given path in the object hierarchy.

connection :

the connection

path :

object path

name :

interface name

Returns :

TRUE on success