Main Page   Modules   Data Structures   File List   Data Fields   Related Pages  

Message bus APIs
[D-BUS message system public API]

Functions for communicating with the message bus. More...

Functions

DBusConnectiondbus_bus_get (DBusBusType type, DBusError *error)
 Connects to a bus daemon and registers the client with it. More...

dbus_bool_t dbus_bus_register (DBusConnection *connection, DBusError *error)
 Registers a connection with the bus. More...

dbus_bool_t dbus_bus_set_base_service (DBusConnection *connection, const char *base_service)
 Sets the base service name of the connection. More...

const char * dbus_bus_get_base_service (DBusConnection *connection)
 Gets the base service name of the connection. More...

int dbus_bus_acquire_service (DBusConnection *connection, const char *service_name, unsigned int flags, DBusError *error)
 Asks the bus to try to acquire a certain service. More...

dbus_bool_t dbus_bus_service_exists (DBusConnection *connection, const char *service_name, DBusError *error)
 Checks whether a certain service exists. More...

dbus_bool_t dbus_bus_activate_service (DBusConnection *connection, const char *service_name, dbus_uint32_t flags, dbus_uint32_t *result, DBusError *error)
 Activates a given service. More...

void dbus_bus_add_match (DBusConnection *connection, const char *rule, DBusError *error)
 Adds a match rule to match messages going through the message bus. More...

void dbus_bus_remove_match (DBusConnection *connection, const char *rule, DBusError *error)
 Removes a previously-added match rule "by value" (the most recently-added identical rule gets removed). More...


Detailed Description

Functions for communicating with the message bus.

Todo:
right now the default address of the system bus is hardcoded, so if you change it in the global config file suddenly you have to set DBUS_SYSTEM_BUS_ADDRESS env variable. Might be nice if the client lib somehow read the config file, or if the bus on startup somehow wrote out its address to a well-known spot, but might also not be worth it.

Function Documentation

int dbus_bus_acquire_service DBusConnection   connection,
const char *    service_name,
unsigned int    flags,
DBusError   error
 

Asks the bus to try to acquire a certain service.

Todo:
these docs are not complete, need to document the return value and flags

if we get an error reply, it has to be converted into DBusError and returned

Parameters:
connection  the connection
service_name  the service name
flags  flags
error  location to store the error
Returns:
a result code, -1 if error is set

Definition at line 564 of file dbus-bus.c.

dbus_bool_t dbus_bus_activate_service DBusConnection   connection,
const char *    service_name,
dbus_uint32_t    flags,
dbus_uint32_t   result,
DBusError   error
 

Activates a given service.

Parameters:
connection  the connection
service_name  the service name
flags  the flags
result  a place to store the result of the activation, which will be one of DBUS_ACTIVATION_REPLY_ACTIVATED or DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE if successful. Pass NULL if you don't care about the result.
error  location to store any errors
Returns:
TRUE if the activation succeeded, FALSE if not
Todo:
document what the flags do

Definition at line 706 of file dbus-bus.c.

void dbus_bus_add_match DBusConnection   connection,
const char *    rule,
DBusError   error
 

Adds a match rule to match messages going through the message bus.

The "rule" argument is the string form of a match rule.

If you pass NULL for the error, this function will not block; the match thus won't be added until you flush the connection, and if there's an error adding the match (only possible error is lack of resources in the bus), you won't find out about it.

If you pass non-NULL for the error this function will block until it gets a reply.

Normal API conventions would have the function return a boolean value indicating whether the error was set, but that would require blocking always to determine the return value.

Parameters:
connection  connection to the message bus
rule  textual form of match rule
error  location to store any errors

Definition at line 817 of file dbus-bus.c.

DBusConnection* dbus_bus_get DBusBusType    type,
DBusError   error
 

Connects to a bus daemon and registers the client with it.

If a connection to the bus already exists, then that connection is returned.

Todo:
alex thinks we should nullify the connection when we get a disconnect-message.
Parameters:
type  bus type
error  address where an error can be returned.
Returns:
a DBusConnection

Definition at line 325 of file dbus-bus.c.

References BusData::is_well_known.

const char* dbus_bus_get_base_service DBusConnection   connection
 

Gets the base service name of the connection.

Only possible after the connection has been registered with the message bus.

Parameters:
connection  the connection
Returns:
the base service name

Definition at line 535 of file dbus-bus.c.

References BusData::base_service.

dbus_bool_t dbus_bus_register DBusConnection   connection,
DBusError   error
 

Registers a connection with the bus.

This must be the first thing an application does when connecting to the message bus. If registration succeeds, the base service name will be set, and can be obtained using dbus_bus_get_base_service().

Todo:
if we get an error reply, it has to be converted into DBusError and returned
Parameters:
connection  the connection
error  place to store errors
Returns:
TRUE on success

Definition at line 428 of file dbus-bus.c.

References BusData::base_service.

void dbus_bus_remove_match DBusConnection   connection,
const char *    rule,
DBusError   error
 

Removes a previously-added match rule "by value" (the most recently-added identical rule gets removed).

The "rule" argument is the string form of a match rule.

If you pass NULL for the error, this function will not block; otherwise it will. See detailed explanation in docs for dbus_bus_add_match().

Parameters:
connection  connection to the message bus
rule  textual form of match rule
error  location to store any errors

Definition at line 855 of file dbus-bus.c.

dbus_bool_t dbus_bus_service_exists DBusConnection   connection,
const char *    service_name,
DBusError   error
 

Checks whether a certain service exists.

Todo:
the SERVICE_EXISTS message should use BOOLEAN not UINT32
Parameters:
connection  the connection
service_name  the service name
error  location to store any errors
Returns:
TRUE if the service exists, FALSE if not or on error

Definition at line 640 of file dbus-bus.c.

dbus_bool_t dbus_bus_set_base_service DBusConnection   connection,
const char *    base_service
 

Sets the base service name of the connection.

Can only be used if you registered with the bus manually (i.e. if you did not call dbus_bus_register()). Can only be called once per connection.

Parameters:
connection  the connection
base_service  the base service name
Returns:
FALSE if not enough memory

Definition at line 508 of file dbus-bus.c.

References BusData::base_service.


Generated on Wed Jun 9 05:01:27 2004 for D-BUS by doxygen1.2.15