man: document sd_bus_message_get_cookie()

[elogind.git] / src / libsystemd-bus / kdbus.h

diff --git a/src/libsystemd-bus/kdbus.h b/src/libsystemd-bus/kdbus.h
index 61dc33d8d5b7b8cfab4dc24df6f838b7a8924326..71cfe06eac1b37eace0f0b65ae8b8f05cf751087 100644 (file)
--- a/src/libsystemd-bus/kdbus.h
+++ b/src/libsystemd-bus/kdbus.h
@@ -313,9 +313,11 @@ struct kdbus_item {
 
 /**
  * enum kdbus_msg_flags - type of message
- * @KDBUS_MSG_FLAGS_EXPECT_REPLY:      Expect a reply message, used for method
- *                                     calls. The cookie identifies the
- *                                     message and the respective reply
+ * @KDBUS_MSG_FLAGS_EXPECT_REPLY:      Expect a reply message, used for
+ *                                     method calls. The userspace-supplied
+ *                                     cookie identifies the message and the
+ *                                     respective reply carries the cookie
+ *                                     in cookie_reply
  * @KDBUS_MSG_FLAGS_NO_AUTO_START:     Do not start a service, if the addressed
  *                                     name is not currently active
  */
@@ -327,7 +329,7 @@ enum kdbus_msg_flags {
 /**
  * enum kdbus_payload_type - type of payload carried by message
  * @KDBUS_PAYLOAD_KERNEL:      Kernel-generated simple message
- * @KDBUS_PAYLOAD_DBUS:                D-Bus marshalling
+ * @KDBUS_PAYLOAD_DBUS:                D-Bus marshalling
  */
 enum kdbus_payload_type {
        KDBUS_PAYLOAD_KERNEL,
@@ -341,21 +343,15 @@ enum kdbus_payload_type {
  * @dst_id:            64-bit ID of the destination connection
  * @src_id:            64-bit ID of the source connection
  * @payload_type:      Payload type (KDBUS_PAYLOAD_*)
- * @cookie:            Userspace-supplied cookie
- * @cookie_reply:      For kernel-generated messages, this is the cookie
- *                     the message is a reply to
- * @timeout_ns:                For non-kernel-generated messages, this denotes the
- *                     message timeout in nanoseconds. A message has to be
- *                     received with KDBUS_CMD_MSG_RECV by the destination
- *                     connection within this time frame. For messages that
- *                     have KDBUS_MSG_FLAGS_EXPECT_REPLY set in @flags,
- *                     this value also denotes the timeout for the reply to
- *                     this message. If there is no reply, or the message is
- *                     not received in time by the other side, a
- *                     kernel-generated message with an attached
- *                     KDBUS_ITEM_REPLY_TIMEOUT item is sent to @src_id.
- *                     A 0-value is only valid if KDBUS_MSG_FLAGS_EXPECT_REPLY
- *                     is unset in @flags.
+ * @cookie:            Userspace-supplied cookie, for the connection
+ *                     to identify its messages
+ * @cookie_reply:      A reply to the requesting message with the same
+ *                     cookie. The requesting connection can match its
+ *                     request and the reply with this value
+ * @timeout_ns:                The time to wait for a message reply from the peer.
+ *                     If there is no reply, a kernel-generated message
+ *                     with an attached KDBUS_ITEM_REPLY_TIMEOUT item
+ *                     is sent to @src_id.
  * @items:             A list of kdbus_items containing the message payload
  */
 struct kdbus_msg {
@@ -528,8 +524,9 @@ enum kdbus_name_flags {
  * struct kdbus_cmd_name - struct to describe a well-known name
  * @size:              The total size of the struct
  * @flags:             Flags for a name entry (KDBUS_NAME_*)
- * @id:                        Privileged users may use this field to (de)register
- *                     names on behalf of other peers.
+ * @owner_id:          The current owner of the name. For requests,
+ *                     privileged users may set this field to
+ *                     (de)register names on behalf of other connections.
  * @conn_flags:                The flags of the owning connection (KDBUS_HELLO_*)
  * @name:              The well-known name
  *
@@ -538,7 +535,7 @@ enum kdbus_name_flags {
 struct kdbus_cmd_name {
        __u64 size;
        __u64 flags;
-       __u64 id;
+       __u64 owner_id;
        __u64 conn_flags;
        char name[0];
 } __attribute__((aligned(8)));
@@ -629,10 +626,10 @@ struct kdbus_conn_info {
 /**
  * struct kdbus_cmd_match - struct to add or remove matches
  * @size:              The total size of the struct
- * @id:                        Privileged users may (de)register matches on behalf
- *                     of other peers. In other cases, set to 0.
+ * @owner_id:          Privileged users may (de)register matches on behalf
+ *                     of other peers
  * @cookie:            Userspace supplied cookie. When removing, the cookie
- *                     identifies the match to remove.
+ *                     identifies the match to remove
  * @items:             A list of items for additional information
  *
  * This structure is used with the KDBUS_CMD_ADD_MATCH and
@@ -640,7 +637,7 @@ struct kdbus_conn_info {
  */
 struct kdbus_cmd_match {
        __u64 size;
-       __u64 id;
+       __u64 owner_id;
        __u64 cookie;
        struct kdbus_item items[0];
 } __attribute__((aligned(8)));
@@ -765,6 +762,8 @@ enum kdbus_ioctl_type {
  * @EBADFD:            A bus connection is in a corrupted state.
  * @EBADMSG:           Passed data contains a combination of conflicting or
  *                     inconsistent types.
+ * @EBUSY:             The user tried to say BYEBYE to a connection, but the
+ *                     connection had a non-empty message list.
  * @ECONNRESET:                A connection is shut down, no further operations are
  *                     possible.
  * @ECOMM:             A peer does not accept the file descriptors addressed
@@ -791,6 +790,8 @@ enum kdbus_ioctl_type {
  *                     size.
  * @ENOBUFS:           There is no space left for the submitted data to fit
  *                     into the receiver's pool.
+ * @ENOENT:            The name to query information about is currently not on
+ *                     the bus.
  * @ENOMEM:            Out of memory.
  * @ENOSYS:            The requested functionality is not available.
  * @ENOTCONN:          The addressed peer is not an active connection.