Functions | |
DBusConnection * | dbus_bus_get (DBusBusType type, DBusError *error) |
Connects to a bus daemon and registers the client with it. | |
DBusConnection * | dbus_bus_get_private (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 by invoking the RequestName method on the bus. | |
int | dbus_bus_release_name (DBusConnection *connection, const char *name, DBusError *error) |
Asks the bus to unassign the given name to this connection by invoking the ReleaseName method on the bus. | |
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). |
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.
The AddMatch method is fully documented in the D-Bus specification. For quick reference, the format of the match rules is discussed here, but the specification is the canonical version of this information.
Rules are specified as a string of comma separated key/value pairs. An example is "type='signal',sender='org.freedesktop.DBus', interface='org.freedesktop.DBus',member='Foo', path='/bar/foo',destination=':452345.34'"
Possible keys you can match on are type, sender, interface, member, path, destination and the special arg keys. Excluding a key from the rule indicates a wildcard match. For instance excluding the the member from a match rule but adding a sender would let all messages from that sender through.
Matches are inclusive not exclusive so as long as one rule matches the message will get through. It is important to note this because every time a message is received the application will be paged into memory to process it. This can cause performance problems such as draining batteries on embedded platforms.
The special arg keys are used for further restricting the match based on the parameters sent by the signal or method. For instance arg1='foo' will check the first argument, arg2='bar' the second and so on. For performance reasons there is a set limit on the highest number parameter that can be checked which is set in dbus-protocol.h
connection | connection to the message bus | |
rule | textual form of match rule | |
error | location to store any errors |
Definition at line 1097 of file dbus-bus.c.
References DBUS_INTERFACE_DBUS, dbus_message_append_args(), dbus_message_new_method_call(), dbus_message_unref(), DBUS_PATH_DBUS, DBUS_SERVICE_DBUS, DBUS_TYPE_INVALID, DBUS_TYPE_STRING, 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.
type | bus type | |
error | address where an error can be returned. |
Definition at line 448 of file dbus-bus.c.
References FALSE.
DBusConnection* dbus_bus_get_private | ( | DBusBusType | type, | |
DBusError * | error | |||
) |
Connects to a bus daemon and registers the client with it.
Unlike dbus_bus_get(), always creates a new connection. This connection will not be saved or recycled by libdbus. Caller owns a reference to the bus.
type | bus type | |
error | address where an error can be returned. |
Definition at line 464 of file dbus-bus.c.
References TRUE.
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.
The name remains valid for the duration of the connection and should not be freed by the caller.
connection | the connection |
Definition at line 592 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.
connection | the connection | |
name | a name owned by the connection | |
error | location to store the error |
Definition at line 615 of file dbus-bus.c.
References dbus_connection_send_with_reply_and_block(), DBUS_INTERFACE_DBUS, dbus_message_append_args(), dbus_message_get_args(), dbus_message_new_method_call(), dbus_message_unref(), DBUS_PATH_DBUS, DBUS_SERVICE_DBUS, dbus_set_error_from_message(), DBUS_TYPE_INVALID, DBUS_TYPE_STRING, DBUS_TYPE_UINT32, 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.
connection | the connection | |
name | the name | |
error | location to store any errors |
Definition at line 891 of file dbus-bus.c.
References dbus_connection_send_with_reply_and_block(), DBUS_INTERFACE_DBUS, dbus_message_append_args(), dbus_message_get_args(), dbus_message_new_method_call(), dbus_message_unref(), DBUS_PATH_DBUS, DBUS_SERVICE_DBUS, DBUS_TYPE_BOOLEAN, DBUS_TYPE_INVALID, DBUS_TYPE_STRING, 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().
connection | the connection | |
error | place to store errors |
Definition at line 480 of file dbus-bus.c.
References _dbus_strdup(), _dbus_warn(), dbus_connection_send_with_reply_and_block(), DBUS_INTERFACE_DBUS, dbus_message_get_args(), dbus_message_new_method_call(), dbus_message_unref(), DBUS_PATH_DBUS, DBUS_SERVICE_DBUS, dbus_set_error_from_message(), DBUS_TYPE_INVALID, DBUS_TYPE_STRING, FALSE, NULL, TRUE, and BusData::unique_name.
int dbus_bus_release_name | ( | DBusConnection * | connection, | |
const char * | name, | |||
DBusError * | error | |||
) |
Asks the bus to unassign the given name to this connection by invoking the ReleaseName method on the bus.
This method is fully documented in the D-Bus specification.
connection | the connection | |
name | the name to remove | |
error | location to store the error |
Definition at line 818 of file dbus-bus.c.
References dbus_connection_send_with_reply_and_block(), DBUS_INTERFACE_DBUS, dbus_message_append_args(), dbus_message_get_args(), dbus_message_new_method_call(), dbus_message_unref(), DBUS_PATH_DBUS, DBUS_SERVICE_DBUS, dbus_set_error_from_message(), DBUS_TYPE_INVALID, DBUS_TYPE_STRING, DBUS_TYPE_UINT32, and NULL.
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().
connection | connection to the message bus | |
rule | textual form of match rule | |
error | location to store any errors |
Definition at line 1143 of file dbus-bus.c.
References DBUS_INTERFACE_DBUS, dbus_message_append_args(), dbus_message_new_method_call(), dbus_message_unref(), DBUS_PATH_DBUS, DBUS_SERVICE_DBUS, DBUS_TYPE_INVALID, DBUS_TYPE_STRING, 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 by invoking the RequestName method on the bus.
This method is fully documented in the D-Bus specification. For quick reference, the flags and result codes are discussed here, but the specification is the canonical version of this information.
The DBUS_NAME_FLAG_ALLOW_REPLACEMENT flag indicates that the caller will allow other services to take over the name from the current owner.
The DBUS_NAME_FLAG_REPLACE_EXISTING flag indicates that the caller would like to take over the name from the current owner. If the current name owner did not use DBUS_NAME_FLAG_ALLOW_REPLACEMENT then this flag indicates that the caller would like to be placed in the queue to own the name when the current owner lets go.
If no flags are given, an application will receive the requested name only if the name is currently unowned; it will NOT give up the name if another application asks to take it over using DBUS_NAME_FLAG_REPLACE_EXISTING.
This function returns a result code. The possible result codes are as follows.
DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER means that the name had no existing owner, and the caller is now the primary owner; or that the name had an owner, and the caller specified DBUS_NAME_FLAG_REPLACE_EXISTING, and the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
DBUS_REQUEST_NAME_REPLY_IN_QUEUE happens only if the caller does NOT specify DBUS_NAME_FLAG_DO_NOT_QUEUE and either the current owner did NOT specify DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the caller did NOT specify DBUS_NAME_FLAG_REPLACE_EXISTING. In this case the caller ends up in a queue to own the name after the current owner gives it up.
DBUS_REQUEST_NAME_REPLY_EXISTS happens if the name has an owner already and the caller specifies DBUS_NAME_FLAG_DO_NOT_QUEUE and either the current owner has NOT specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the caller did NOT specify DBUS_NAME_FLAG_REPLACE_EXISTING.
DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER happens if an application requests a name it already owns.
When a service represents an application, say "text editor," then it should specify DBUS_NAME_FLAG_ALLOW_REPLACEMENT if it wants the last editor started to be the user's editor vs. the first one started. Then any editor that can be the user's editor should specify DBUS_NAME_FLAG_REPLACE_EXISTING to either take over (last-started-wins) or be queued up (first-started-wins) according to whether DBUS_NAME_FLAG_ALLOW_REPLACEMENT was given.
connection | the connection | |
name | the name to request | |
flags | flags | |
error | location to store the error |
Definition at line 740 of file dbus-bus.c.
References dbus_connection_send_with_reply_and_block(), DBUS_INTERFACE_DBUS, dbus_message_append_args(), dbus_message_get_args(), dbus_message_new_method_call(), dbus_message_unref(), DBUS_PATH_DBUS, DBUS_SERVICE_DBUS, dbus_set_error_from_message(), DBUS_TYPE_INVALID, DBUS_TYPE_STRING, DBUS_TYPE_UINT32, 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.
connection | the connection | |
unique_name | the unique name |
Definition at line 563 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.
The flags parameter is for future expansion, currently you should specify 0.
connection | the connection | |
name | the name we want the new service to request | |
flags | the flags (should always be 0 for now) | |
result | a place to store the result or NULL | |
error | location to store any errors |
Definition at line 961 of file dbus-bus.c.
References dbus_connection_send_with_reply_and_block(), DBUS_INTERFACE_DBUS, dbus_message_append_args(), dbus_message_get_args(), dbus_message_new_method_call(), dbus_message_unref(), DBUS_PATH_DBUS, DBUS_SERVICE_DBUS, dbus_set_error_from_message(), DBUS_TYPE_INVALID, DBUS_TYPE_STRING, DBUS_TYPE_UINT32, FALSE, NULL, and TRUE.