* Block of message-bus-related data we attach to each
* #DBusConnection used with these convenience functions.
*
- *
- * @todo get rid of most of these; they should be done
- * with DBusGProxy and the Qt equivalent, i.e. the same
- * way any other interface would be used.
*/
typedef struct
{
return bd;
}
-/** @} */ /* end of implementation details docs */
-
-/**
- * @addtogroup DBusBus
- * @{
- */
-
-/**
- * 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.
- *
- * @param type bus type
- * @param error address where an error can be returned.
- * @returns a DBusConnection with new ref
- */
-DBusConnection *
-dbus_bus_get (DBusBusType type,
- DBusError *error)
+static DBusConnection *
+internal_bus_get (DBusBusType type,
+ DBusError *error, dbus_bool_t private)
{
const char *address;
DBusConnection *connection;
bus_connection_addresses[activation_bus_type] != NULL)
type = activation_bus_type;
- if (bus_connections[type] != NULL)
+ if (!private && bus_connections[type] != NULL)
{
connection = bus_connections[type];
dbus_connection_ref (connection);
return NULL;
}
- connection = dbus_connection_open (address, error);
+ if (private)
+ connection = dbus_connection_open_private(address, error);
+ else
+ connection = dbus_connection_open (address, error);
if (!connection)
{
return NULL;
}
- bus_connections[type] = connection;
+ if (!private)
+ bus_connections[type] = connection;
+
bd = ensure_bus_data (connection);
_dbus_assert (bd != NULL);
}
+/** @} */ /* end of implementation details docs */
+
+/**
+ * @addtogroup DBusBus
+ * @{
+ */
+
+/**
+ * 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.
+ *
+ * @param type bus type
+ * @param error address where an error can be returned.
+ * @returns a DBusConnection with new ref
+ */
+DBusConnection *
+dbus_bus_get (DBusBusType type,
+ DBusError *error) {
+ return internal_bus_get(type, error, FALSE);
+}
+
+/**
+ * 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.
+ *
+ * @param type bus type
+ * @param error address where an error can be returned.
+ * @returns a DBusConnection with new ref
+ */
+DBusConnection *
+dbus_bus_get_private (DBusBusType type,
+ DBusError *error) {
+ return internal_bus_get(type, error, TRUE);
+}
+
/**
* Registers a connection with the bus. This must be the first
* thing an application does when connecting to the message bus.
* 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.
+ *
* @param connection the connection
- * @returns the unique name
+ * @returns the unique name or NULL on error
*/
const char*
dbus_bus_get_unique_name (DBusConnection *connection)
/**
- * Asks the bus to assign the given name to this connection.
+ * 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_PROHIBIT_REPLACEMENT flag indicates that
+ * if the name is successfully requested, other applications
+ * will not be able to take over the name. i.e. the name's
+ * owner (the application calling this function) must let go of
+ * the name, it will not lose it involuntarily.
*
- * @todo these docs are not complete, need to document the
- * return value and flags
+ * 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 used #DBUS_NAME_FLAG_PROHIBIT_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; and it will 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.
*
- * @todo if we get an error reply, it has to be converted into
- * DBusError and returned
+ * #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 did not
+ * specify #DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT.
+ *
+ * #DBUS_REQUEST_NAME_REPLY_IN_QUEUE happens only if the current owner
+ * specified #DBUS_NAME_FLAG_PROHIBIT_REPLACEMENT and the caller specified
+ * #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 DBUS_NAME_FLAG_REPLACE_EXISTING was not specified.
*
+ * #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_PROHIBIT_REPLACEMENT if it wants
+ * the first editor started to be the user's editor vs. the last 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_PROHIBIT_REPLACEMENT was given.
+ *
+ * @todo this all seems sort of broken. Shouldn't the flags be a property
+ * of the name, not the app requesting the name? What are the use-cases
+ * other than the "text editor" thing and how are we supporting them?
+ *
* @param connection the connection
* @param name the name to request
* @param flags flags
return result;
}
+int
+dbus_bus_release_name (DBusConnection *connection,
+ const char *name,
+ DBusError *error)
+{
+ DBusMessage *message, *reply;
+ dbus_uint32_t result;
+
+ _dbus_return_val_if_fail (connection != NULL, 0);
+ _dbus_return_val_if_fail (name != NULL, 0);
+ _dbus_return_val_if_fail (_dbus_check_is_valid_bus_name (name), 0);
+ _dbus_return_val_if_error_is_set (error, 0);
+
+ message = dbus_message_new_method_call (DBUS_SERVICE_DBUS,
+ DBUS_PATH_DBUS,
+ DBUS_INTERFACE_DBUS,
+ "ReleaseName");
+
+ if (message == NULL)
+ {
+ _DBUS_SET_OOM (error);
+ return -1;
+ }
+
+ if (!dbus_message_append_args (message,
+ DBUS_TYPE_STRING, &name,
+ DBUS_TYPE_INVALID))
+ {
+ dbus_message_unref (message);
+ _DBUS_SET_OOM (error);
+ return -1;
+ }
+
+ reply = dbus_connection_send_with_reply_and_block (connection, message, -1,
+ error);
+
+ dbus_message_unref (message);
+
+ if (reply == NULL)
+ {
+ _DBUS_ASSERT_ERROR_IS_SET (error);
+ return -1;
+ }
+
+ if (dbus_set_error_from_message (error, reply))
+ {
+ _DBUS_ASSERT_ERROR_IS_SET (error);
+ dbus_message_unref (reply);
+ return -1;
+ }
+
+ if (!dbus_message_get_args (reply, error,
+ DBUS_TYPE_UINT32, &result,
+ DBUS_TYPE_INVALID))
+ {
+ _DBUS_ASSERT_ERROR_IS_SET (error);
+ dbus_message_unref (reply);
+ return -1;
+ }
+
+ dbus_message_unref (reply);
+
+ return result;
+}
+
/**
* Checks whether a certain name has an owner.
*
* 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.
*
* @param connection the connection
* @param name the name we want the new service to request
- * @param flags the flags
+ * @param flags the flags (should always be 0 for now)
* @param result a place to store the result or #NULL
* @param error location to store any errors
* @returns #TRUE if the activation succeeded, #FALSE if not
- *
- * @todo document what the flags do
*/
dbus_bool_t
dbus_bus_start_service_by_name (DBusConnection *connection,
projects / platform / upstream / dbus.git / blobdiff