diff options
| -rw-r--r-- | reserve.h | 21 | ||||
| -rw-r--r-- | reserve.txt | 34 |
2 files changed, 30 insertions, 25 deletions
@@ -31,10 +31,11 @@ typedef struct rd_device rd_device; /* Prototype for a function that is called whenever someone else wants - * your app to release the device you having locked. A return value <= - * 0 denies the request, a positive return value agrees to it. Before - * returning your application should close the device in question - * completely to make sure the new application may acceess it. */ + * your application to release the device it has locked. A return + * value <= 0 denies the request, a positive return value agrees to + * it. Before returning your application should close the device in + * question completely to make sure the new application may access + * it. */ typedef int (*rd_request_cb_t)( rd_device *d, int forced); /* Non-zero if an application forcibly took the lock away without asking. If this is the case then the return value of this call is ignored. */ @@ -48,20 +49,20 @@ int rd_acquire( const char *device_name, /* The device to lock, e.g. "Audio0" */ const char *application_name, /* A human readable name of the application, e.g. "PulseAudio Sound Server" */ int32_t priority, /* The priority for this application. If unsure use 0 */ - rd_request_cb_t request_cb, /* Will be called whenever someone asks that this device shall be released. May be NULL if priority is INT32_MAX */ + rd_request_cb_t request_cb, /* Will be called whenever someone requests that this device shall be released. May be NULL if priority is INT32_MAX */ DBusError *error); /* If we fail due to a D-Bus related issue the error will be filled in here. May be NULL. */ -/* Unlock (if needed) and destroy a rd_device object again */ +/* Unlock (if needed) and destroy an rd_device object again */ void rd_release(rd_device *d); -/* Set the application device name for a rd_device object Returns 0 on - * success, a negative errno style return value on error. */ +/* Set the application device name for an rd_device object. Returns 0 + * on success, a negative errno style return value on error. */ int rd_set_application_device_name(rd_device *d, const char *name); -/* Attach a userdata pointer to a rd_device */ +/* Attach a userdata pointer to an rd_device */ void rd_set_userdata(rd_device *d, void *userdata); -/* Query the userdata pointer from a rd_device. Returns NULL if no +/* Query the userdata pointer from an rd_device. Returns NULL if no * userdata was set. */ void* rd_get_userdata(rd_device *d); diff --git a/reserve.txt b/reserve.txt index bab36f6..fdff6e5 100644 --- a/reserve.txt +++ b/reserve.txt @@ -139,15 +139,18 @@ LOGIC (as in only reserving playback, not capturing) shall not be implemented. - 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, + As an exception to the rules above if an application has a + priority of INT32_MAX DBUS_NAME_FLAG_ALLOW_REPLACEMENT should + not be set when requesting the name. Also, in this case + implementing the RequestRelease() method is + optional. + + Implementations that call RequestName() MUST be able to handle + the org.freedesktop.DBus.Error.UnknownMethod, org.freedesktop.DBus.Error.NoReply and - org.freedesktop.DBus.Error.TimedOut when calling this - function. Both cases should NOT be treated as errors but as - negative replies. + org.freedesktop.DBus.Error.TimedOut error conditions. All + three cases should NOT be treated as errors but as negative + replies. PRIORITIES @@ -167,7 +170,7 @@ PROPERTIES Optionally the owner of the device access may export a few properties with a bit of descriptive information about - itself. This is supposed to be useful to how a nice message + itself. This is supposed to be useful to show a nice message to the user: "Application %s is blocking device %s. Please close this application or make sure it closes the access to that device." with ApplicationName and ApplicationDeviceName @@ -190,15 +193,16 @@ RATIONALE priority logic requires an explicit method likes this. If an application dies its service name will automatically be - released as well. + released by the D-Bus bus daemon. IMPLEMENTATION A trivial implementation of this interface uses INT32_MAX as - 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. + priority value and does not implement RequestRelease or any + other function or property of the interface defined above. 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. Lennart Poettering |