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.

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

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

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

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.

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

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.


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 512 of file dbus-bus.c.

References dbus_connection_send_with_reply_and_block(), dbus_message_append_args(), dbus_message_get_args(), dbus_message_new(), dbus_message_unref(), dbus_set_error_from_message(), dbus_uint32_t, and NULL.

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 651 of file dbus-bus.c.

References dbus_connection_send_with_reply_and_block(), dbus_message_append_args(), dbus_message_get_args(), dbus_message_new(), dbus_message_unref(), dbus_set_error_from_message(), FALSE, NULL, and TRUE.

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 282 of file dbus-bus.c.

References _dbus_assert, _DBUS_LOCK, _DBUS_UNLOCK, dbus_bus_register(), dbus_connection_disconnect(), dbus_connection_open(), dbus_connection_ref(), dbus_connection_unref(), dbus_set_error(), BusData::is_well_known, NULL, and TRUE.

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 483 of file dbus-bus.c.

References BusData::base_service, and NULL.

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 377 of file dbus-bus.c.

References _dbus_warn(), BusData::base_service, dbus_bool_t, dbus_connection_send_with_reply_and_block(), dbus_message_get_args(), dbus_message_new(), dbus_message_unref(), dbus_set_error_from_message(), FALSE, NULL, and TRUE.

Referenced by dbus_bus_get().

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 587 of file dbus-bus.c.

References dbus_connection_send_with_reply_and_block(), dbus_message_append_args(), dbus_message_get_args(), dbus_message_new(), dbus_message_unref(), FALSE, and NULL.

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 456 of file dbus-bus.c.

References _dbus_assert, _dbus_strdup(), BusData::base_service, FALSE, and NULL.


Generated on Wed Oct 22 14:05:06 2003 for D-BUS by doxygen1.3-rc3