|author||Lennart Poettering <firstname.lastname@example.org>||2009-02-24 01:00:28 +0100|
|committer||Lennart Poettering <email@example.com>||2009-02-24 01:00:28 +0100|
Simplifications for applications with a priority of INT32_MAX
For clients with a priority of INT32_MAX implementing RequestRelease() is optional, and the service name maybe acquired without DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
Diffstat (limited to 'reserve.txt')
1 files changed, 30 insertions, 14 deletions
diff --git a/reserve.txt b/reserve.txt
index 2673334..9aab9f1 100644
@@ -37,7 +37,8 @@ INTERFACE DEFINITION
- BOOL RequestRelease(INT32 priority) (mandatory)
+ BOOL RequestRelease(INT32 priority)
+ (mandatory unless own priority is INT32_MAX)
Ask the current owner of the device to release
the device for take-over. The application
@@ -59,17 +60,20 @@ INTERFACE DEFINITION
i.e. no user interaction shall be involved.
- INT32 Priority (optional)
+ INT32 Priority
The priority of the current owner of the
- STRING ApplicationName (optional)
+ STRING ApplicationName
The name of the application currently holding
- STRING ApplicationDeviceName (optional)
+ STRING ApplicationDeviceName
The name of the device how it is presented in
the application's context. This is supposed to
@@ -106,8 +110,8 @@ LOGIC
The initial request shall be made with
- DBUS_NAME_FLAG_ALLOW_REPLACEMENT. DBUS_NAME_FLAG_REPLACE_EXISTING
- shall not be set.
+ DBUS_NAME_FLAG_ALLOW_REPLACEMENT (exception see
+ below). DBUS_NAME_FLAG_REPLACE_EXISTING shall not be set.
If the name request fails, the application may issue the
RequestRelease() method on the service. It shall pass a
@@ -116,9 +120,9 @@ LOGIC
and return TRUE (in this order!). The client shall then
request the name again, this time with
- DBUS_NAME_FLAG_ALLOW_REPLACEMENT set. If the priority is lower
- then the owner should return FALSE and the client shall not try
- further access to the device.
+ DBUS_NAME_FLAG_ALLOW_REPLACEMENT (exception see below) set. If
+ the priority is lower then the owner should return FALSE and
+ the client shall not try further access to the device.
An application shall watch for
org.freedesktop.DBus.LostName signals and give up
@@ -135,6 +139,14 @@ LOGIC
(as in only reserving playback, not capturing) shall not be
+ If an application has priority of INT32_MAX
+ DBUS_NAME_FLAG_ALLOW_REPLACEMENT should not be set when
+ requesting the name. Also, in this case implementing
+ RequestRelease() is optional. Implementations MUST be able to
+ deal with org.freedesktop.DBus.Error.UnknownMethod and
+ timeouts when calling this function. Both cases should NOT be
+ treated as errors but as negative replies.
Priorities may use the full INT32 range. Normal applications
@@ -159,6 +171,10 @@ PROPERTIES
that device." with ApplicationName and ApplicationDeviceName
+ This data can be augmented by the data that is available from
+ org.freedesktop.DBus.GetConnectionUnixUser and
There are two reasons to have RequestRelease instead of simply
@@ -177,10 +193,10 @@ RATIONALE
A trivial implementation of this interface uses INT32_MAX as
- priority value and always returns FALSE in RequestRelease. An
- application written like this would always get access to the
- device (unless the device is already owned by an application
- that uses a similar trivial implementation) and would never
- need to give it up again.
+ priority value and does not actually implement
+ RequestRelease. An application written like this would always
+ get access to the device (unless the device is already owned
+ by an application that uses a similar trivial implementation)
+ and would never need to give it up again.