Main Page | Modules | Namespace List | Class Hierarchy | Data Structures | Directories | File List | Namespace Members | Data Fields | Related Pages

Message bus APIs
[D-BUS low-level 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_unique_name (DBusConnection *connection, const char *unique_name)
 Sets the unique name of the connection.
const char * dbus_bus_get_unique_name (DBusConnection *connection)
 Gets the unique name of the connection.
unsigned long dbus_bus_get_unix_user (DBusConnection *connection, const char *name, DBusError *error)
 Asks the bus to return the uid of the named connection.
int dbus_bus_request_name (DBusConnection *connection, const char *name, unsigned int flags, DBusError *error)
 Asks the bus to assign the given name to this connection.
dbus_bool_t dbus_bus_name_has_owner (DBusConnection *connection, const char *name, DBusError *error)
 Checks whether a certain name has an owner.
dbus_bool_t dbus_bus_start_service_by_name (DBusConnection *connection, const char *name, dbus_uint32_t flags, dbus_uint32_t *result, DBusError *error)
 Starts a service that will request ownership of the given name.
void dbus_bus_add_match (DBusConnection *connection, const char *rule, DBusError *error)
 Adds a match rule to match messages going through the message bus.
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).

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

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

References dbus_message_append_args(), dbus_message_new_method_call(), dbus_message_unref(), and NULL.

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. Caller owns a reference to the bus.

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 with new ref

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

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

Referenced by dbus_g_bus_get().

const char* dbus_bus_get_unique_name DBusConnection connection  ) 
 

Gets the unique name of the connection.

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

Parameters:
connection the connection
Returns:
the unique name

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

References NULL, and BusData::unique_name.

unsigned long dbus_bus_get_unix_user DBusConnection connection,
const char *  name,
DBusError error
 

Asks the bus to return the uid of the named connection.

Parameters:
connection the connection
name a name owned by the connection
error location to store the error
Returns:
a result code, -1 if error is set

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

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

dbus_bool_t dbus_bus_name_has_owner DBusConnection connection,
const char *  name,
DBusError error
 

Checks whether a certain name has an owner.

Parameters:
connection the connection
name the name
error location to store any errors
Returns:
TRUE if the name exists, FALSE if not or on error

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

References dbus_connection_send_with_reply_and_block(), dbus_message_append_args(), dbus_message_get_args(), dbus_message_new_method_call(), dbus_message_unref(), FALSE, 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 unique name will be set, and can be obtained using dbus_bus_get_unique_name().

Parameters:
connection the connection
error place to store errors
Returns:
TRUE on success

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

References _dbus_strdup(), _dbus_warn(), dbus_connection_send_with_reply_and_block(), dbus_message_get_args(), dbus_message_new_method_call(), dbus_message_unref(), dbus_set_error_from_message(), FALSE, NULL, TRUE, and BusData::unique_name.

Referenced by dbus_bus_get().

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

References dbus_message_append_args(), dbus_message_new_method_call(), dbus_message_unref(), and NULL.

int dbus_bus_request_name DBusConnection connection,
const char *  name,
unsigned int  flags,
DBusError error
 

Asks the bus to assign the given name to this connection.

Todo:
these docs are not complete, need to document the return value and flags
Todo:
if we get an error reply, it has to be converted into DBusError and returned
Parameters:
connection the connection
name the name to request
flags flags
error location to store the error
Returns:
a result code, -1 if error is set

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

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

dbus_bool_t dbus_bus_set_unique_name DBusConnection connection,
const char *  unique_name
 

Sets the unique 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
unique_name the unique name
Returns:
FALSE if not enough memory

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

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

dbus_bool_t dbus_bus_start_service_by_name DBusConnection connection,
const char *  name,
dbus_uint32_t  flags,
dbus_uint32_t result,
DBusError error
 

Starts a service that will request ownership of the given name.

The returned result will be one of be one of DBUS_START_REPLY_SUCCESS or DBUS_START_REPLY_ALREADY_RUNNING if successful. Pass NULL if you don't care about the result.

Parameters:
connection the connection
name the name we want the new service to request
flags the flags
result a place to store the result or NULL
error location to store any errors
Returns:
TRUE if the activation succeeded, FALSE if not
Todo:
document what the flags do

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

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


Generated on Tue Sep 13 01:28:08 2005 for D-BUS by  doxygen 1.4.4