From d97eac36d889a43bc71dcc9d43f8b6e536dddaae Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 20 Dec 2017 16:31:58 +0100 Subject: man: document all the new APIs we added --- man/sd_bus_request_name.xml | 140 ++++++++++++++++++++++++++------------------ 1 file changed, 83 insertions(+), 57 deletions(-) (limited to 'man/sd_bus_request_name.xml') diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml index f44cfdb1ac..9e668f0b02 100644 --- a/man/sd_bus_request_name.xml +++ b/man/sd_bus_request_name.xml @@ -46,7 +46,9 @@ sd_bus_request_name + sd_bus_request_name_async sd_bus_release_name + sd_bus_release_name_async Request or release a well-known service name on a bus @@ -61,71 +63,103 @@ uint64_t flags + + int sd_bus_request_name_async + sd_bus *bus + sd_bus_slot **slot + const char *name + uint64_t flags + sd_bus_message_handler_t callback + void *userdata + + int sd_bus_release_name sd_bus *bus const char *name + + + int sd_bus_release_name_async + sd_bus *bus + sd_bus_slot **slot + const char *name + sd_bus_message_handler_t callback + void *userdata + Description - sd_bus_request_name() requests a - well-known service name on a bus. It takes a bus connection, a - valid bus name and a flags parameter. The flags parameter is a - combination of the following flags: + sd_bus_request_name() requests a well-known service name on a bus. It takes a bus + connection, a valid bus name and a flags parameter. The flags parameter is a combination of the following + flags: SD_BUS_NAME_ALLOW_REPLACEMENT - After acquiring the name successfully, permit - other peers to take over the name when they try to acquire it - with the SD_BUS_NAME_REPLACE_EXISTING flag - set. If SD_BUS_NAME_ALLOW_REPLACEMENT is - not set on the original request, such a request by other peers - will be denied. + After acquiring the name successfully, permit other peers to take over the name when they try + to acquire it with the SD_BUS_NAME_REPLACE_EXISTING flag set. If + SD_BUS_NAME_ALLOW_REPLACEMENT is not set on the original request, such a request by other + peers will be denied. SD_BUS_NAME_REPLACE_EXISTING - Take over the name if it is already acquired - by another peer, and that other peer has permitted takeover by - setting SD_BUS_NAME_ALLOW_REPLACEMENT while - acquiring it. + Take over the name if it is already acquired by another peer, and that other peer has permitted + takeover by setting SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring it. SD_BUS_NAME_QUEUE - Queue the acquisition of the name when the - name is already taken. + Queue the acquisition of the name when the name is already taken. - sd_bus_release_name() releases an - acquired well-known name. It takes a bus connection and a valid - bus name as parameters. + sd_bus_request_name() operates in a synchronous fashion: a message requesting the name + is sent to the bus broker, and the call waits until the broker responds. + + sd_bus_request_name_async() is an asynchronous version of of + sd_bus_release_name(). Instead of waiting for the request to complete, the request message is + enqueued. The specified callback will be called when the broker's response is received. If + the parameter is specified as NULL a default implementation is used instead which will + terminate the connection when the name cannot be acquired. The function returns a slot object in its + slot parameter — if it is passed as non-NULL — which may be used as a + reference to the name request operation. Use + sd_bus_slot_unref3 to destroy + this reference. Note that destroying the reference will not unregister the name, but simply ensure the specified + callback is no longer called. + + sd_bus_release_name() releases an acquired well-known name. It takes a bus connection + and a valid bus name as parameters. This function operates synchronously, sending a release request message to the + bus broker and waiting for it to reply. + + sd_bus_release_name_async() is an asynchronous version of + sd_bus_release_name(). The specified callback function is called when + the name has been released successfully. If specified as NULL a generic implementation is used + that ignores the result of the operation. As above, the slot (if + non-NULL) is set to an object that may be used to reference the operation. + + These functions are supported only on bus connections, i.e. connections to a bus broker and not on direct + connections. Return Value - On success, these calls return 0 or a positive integer. On - failure, these calls return a negative errno-style error - code. - - If SD_BUS_NAME_QUEUE is specified, - sd_bus_request_name() will return 0 when the - name is already taken by another peer and the client has been - added to the queue for the name. In that case, the caller can - subscribe to NameOwnerChanged signals to be - notified when the name is successfully acquired. - sd_bus_request_name() returns > 0 when the - name has immediately been acquired successfully. + On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style + error code. + + If SD_BUS_NAME_QUEUE is specified, sd_bus_request_name() will return + 0 when the name is already taken by another peer and the client has been added to the queue for the name. In that + case, the caller can subscribe to NameOwnerChanged signals to be notified when the name is + successfully acquired. sd_bus_request_name() returns > 0 when the name has immediately + been acquired successfully. @@ -137,56 +171,50 @@ -EALREADY - The caller already is the owner of the - specified name. + The caller already is the owner of the specified name. -EEXIST - The name has already been acquired by a - different peer, and SD_BUS_NAME_REPLACE_EXISTING was not - specified or the other peer did not specify - SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the + The name has already been acquired by a different peer, and SD_BUS_NAME_REPLACE_EXISTING was + not specified or the other peer did not specify SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the name. -ESRCH - It was attempted to release a name that is - currently not registered on the bus. + It was attempted to release a name that is currently not registered on the + bus. -EADDRINUSE - It was attempted to release a name that is - owned by a different peer on the bus. + It was attempted to release a name that is owned by a different peer on the + bus. -EINVAL - A specified parameter is invalid. This is also - generated when the requested name is a special service name - reserved by the D-Bus specification, or when the operation is - requested on a connection that does not refer to a - bus. + A specified parameter is invalid. This is also generated when the requested name is a special + service name reserved by the D-Bus specification, or when the operation is requested on a connection that does + not refer to a bus. -ENOTCONN - The bus connection has been - disconnected. + The bus connection has been disconnected. -ECHILD - The bus connection has been created in a - different process than the current one. + The bus connection has been created in a different process than the current + one. @@ -194,12 +222,9 @@ Notes - The sd_bus_acquire_name() and - sd_bus_release_name() interfaces are - available as a shared library, which can be compiled and linked to - with the - libsystemd pkg-config1 - file. + The sd_bus_acquire_name() and the other interfaces described here are available as a + shared library, which can be compiled and linked to with the libsystemd pkg-config1 file. @@ -208,7 +233,8 @@ systemd1, sd-bus3, - sd_bus_new3 + sd_bus_new3, + sd_bus_slot_unref3 -- cgit v1.2.1