nl: improve API doc of transmit functions

Signed-off-by: Thomas Graf <tgraf@redhat.com>

4 files changed, 164 insertions, 53 deletions

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index c43d764..7a0640c 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -198,7 +198,9 @@ ALIASES                = arg=\param \
                          "ref_core{2}=\ref_asciidoc{core,\1,\2 (Netlink Core Library Development Guide)}" \
                          "ref_route{2}=\ref_asciidoc{route,\1,\2 (Netlink Routing Development Guide)}" \
                          "core_doc{2}=\ref_core{\1,\2}" \
-                         "route_doc{2}=\ref_route{\1,\2}"
+                         "route_doc{2}=\ref_route{\1,\2}" \
+			 "callback=\par Callback Invocation:\n" \
+			 "lowlevel=\copydoc low_level_api"
 
 # This tag can be used to specify a number of word-keyword mappings (TCL only).
 # A mapping has the form "name=value". For example adding
diff --git a/doc/DoxygenLayout.xml b/doc/DoxygenLayout.xml
index 8d3e3ff..680d3da 100644
--- a/doc/DoxygenLayout.xml
+++ b/doc/DoxygenLayout.xml
@@ -18,7 +18,6 @@
       <tab type="files" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="dirs" visible="no" title="" intro=""/>
     <tab type="examples" visible="yes" title="" intro=""/>  
   </navindex>
 
diff --git a/doc/src/hidden.c b/doc/src/hidden.c
index be4a042..a63621d 100644
--- a/doc/src/hidden.c
+++ b/doc/src/hidden.c
@@ -32,4 +32,11 @@
       accessor function is provided solely for the purpose of creating
       objects for comparison and filtering.
 
+\page low_level_api Low Level API
+
+\note This is a low level API function. A high level function implementing
+      the same functionality with a simplified usage pattern exists. This
+      function is available as an alternative if the default library
+      behaviour is not desirable.
+
 */
diff --git a/lib/nl.c b/lib/nl.c
index f069b69..5f4ab94 100644
--- a/lib/nl.c
+++ b/lib/nl.c
@@ -158,12 +158,12 @@ void nl_close(struct nl_sock *sk)
  */
 
 /**
- * Transmit raw data over netlink socket.
+ * Transmit raw data over Netlink socket.
  * @arg sk		Netlink socket (required)
  * @arg buf		Buffer carrying data to send (required)
  * @arg size		Size of buffer (required)
  *
- * Transmits "raw" data over the specified netlink socket. Unlike the other
+ * Transmits "raw" data over the specified Netlink socket. Unlike the other
  * transmit functions it does not modify the data in any way. It directly
  * passes the buffer \c buf of \c size to sendto().
  *
@@ -199,17 +199,49 @@ int nl_sendto(struct nl_sock *sk, void *buf, size_t size)
 }
 
 /**
- * Send netlink message with control over sendmsg() message header.
- * @arg sk		Netlink socket.
- * @arg msg		Netlink message to be sent.
- * @arg hdr		Sendmsg() message header.
- * @return Number of characters sent on sucess or a negative error code.
+ * Transmit Netlink message using sendmsg()
+ * @arg sk		Netlink socket (required)
+ * @arg msg		Netlink message to be sent (required)
+ * @arg hdr		sendmsg() message header (required)
+ *
+ * Transmits the message specified in \c hdr over the Netlink socket using the
+ * sendmsg() system call.
+ *
+ * @attention
+ * The `msg` argument will *not* be used to derive the message payload that
+ * is being sent out. The `msg` argument is *only* passed on to the
+ * `NL_CB_MSG_OUT` callback. The caller is responsible to initialize the
+ * `hdr` struct properly and have it point to the message payload and
+ * socket address.
+ *
+ * @note
+ * This function uses `nlmsg_set_src()` to modify the `msg` argument prior to
+ * invoking the `NL_CB_MSG_OUT` callback to provide the local port number.
+ *
+ * @callback This function triggers the `NL_CB_MSG_OUT` callback.
+ *
+ * @attention
+ * Think twice before using this function. It provides a low level access to
+ * the Netlink socket. Among other limitations, it does not add credentials
+ * even if enabled or respect the destination address specified in the `msg`
+ * object.
+ *
+ * @see nl_socket_set_local_port()
+ * @see nl_send_auto()
+ * @see nl_send_iovec()
+ *
+ * @return Number of bytes sent on success or a negative error code.
+ *
+ * @lowlevel
  */
 int nl_sendmsg(struct nl_sock *sk, struct nl_msg *msg, struct msghdr *hdr)
 {
 	struct nl_cb *cb;
 	int ret;
 
+	if (sk->s_fd < 0)
+		return -NLE_BAD_SOCK;
+
 	nlmsg_set_src(msg, &sk->s_local);
 
 	cb = sk->s_cb;
@@ -227,13 +259,23 @@ int nl_sendmsg(struct nl_sock *sk, struct nl_msg *msg, struct msghdr *hdr)
 
 
 /**
- * Send netlink message.
- * @arg sk		Netlink socket.
- * @arg msg		Netlink message to be sent.
- * @arg iov		iovec to be sent.
- * @arg iovlen		number of struct iovec to be sent.
- * @see nl_sendmsg()
- * @return Number of characters sent on success or a negative error code.
+ * Transmit Netlink message (taking IO vector)
+ * @arg sk		Netlink socket (required)
+ * @arg msg		Netlink message to be sent (required)
+ * @arg iov		IO vector to be sent (required)
+ * @arg iovlen		Number of struct iovec to be sent (required)
+ *
+ * This function is identical to nl_send() except that instead of taking a
+ * `struct nl_msg` object it takes an IO vector. Please see the description
+ * of `nl_send()`.
+ *
+ * @callback This function triggers the `NL_CB_MSG_OUT` callback.
+ *
+ * @see nl_send()
+ *
+ * @return Number of bytes sent on success or a negative error code.
+ *
+ * @lowlevel
  */
 int nl_send_iovec(struct nl_sock *sk, struct nl_msg *msg, struct iovec *iov, unsigned iovlen)
 {
@@ -272,14 +314,37 @@ int nl_send_iovec(struct nl_sock *sk, struct nl_msg *msg, struct iovec *iov, uns
 	return nl_sendmsg(sk, msg, &hdr);
 }
 
-
-
 /**
-* Send netlink message.
-* @arg sk		Netlink socket.
-* @arg msg		Netlink message to be sent.
-* @see nl_sendmsg()
-* @return Number of characters sent on success or a negative error code.
+ * Transmit Netlink message
+ * @arg sk		Netlink socket (required)
+ * @arg msg		Netlink message (required)
+ *
+ * Transmits the Netlink message `msg` over the Netlink socket using the
+ * `sendmsg()` system call. This function is based on `nl_send_iovec()` but
+ * takes care of initializing a `struct iovec` based on the `msg` object.
+ *
+ * The message is addressed to the peer as specified in the socket by either
+ * the nl_socket_set_peer_port() or nl_socket_set_peer_groups() function.
+ * The peer address can be overwritten by specifying an address in the `msg`
+ * object using nlmsg_set_dst().
+ *
+ * If present in the `msg`, credentials set by the nlmsg_set_creds() function
+ * are added to the control buffer of the message.
+ *
+ * @callback This function triggers the `NL_CB_MSG_OUT` callback.
+ *
+ * @attention
+ * Unlike `nl_send_auto()`, this function does *not* finalize the message in
+ * terms of automatically adding needed flags or filling out port numbers.
+ *
+ * @see nl_send_auto()
+ * @see nl_send_iovec()
+ * @see nl_socket_set_peer_port()
+ * @see nl_socket_set_peer_groups()
+ * @see nlmsg_set_dst()
+ * @see nlmsg_set_creds()
+ *
+ * @return Number of bytes sent on success or a negative error code.
 */
 int nl_send(struct nl_sock *sk, struct nl_msg *msg)
 {
@@ -291,6 +356,24 @@ int nl_send(struct nl_sock *sk, struct nl_msg *msg)
 	return nl_send_iovec(sk, msg, &iov, 1);
 }
 
+/**
+ * Finalize Netlink message
+ * @arg sk		Netlink socket (required)
+ * @arg msg		Netlink message (required)
+ *
+ * This function finalizes a Netlink message by completing the message with
+ * desirable flags and values depending on the socket configuration.
+ *
+ *  - If not yet filled out, the source address of the message (`nlmsg_pid`)
+ *    will be set to the local port number of the socket.
+ *  - If not yet specified, the next available sequence number is assigned
+ *    to the message (`nlmsg_seq`).
+ *  - If not yet specified, the protocol field of the message will be set to
+ *    the protocol field of the socket.
+ *  - The `NLM_F_REQUEST` Netlink message flag will be set.
+ *  - The `NLM_F_ACK` flag will be set if Auto-ACK mode is enabled on the
+ *    socket.
+ */
 void nl_complete_msg(struct nl_sock *sk, struct nl_msg *msg)
 {
 	struct nlmsghdr *nlh;
@@ -311,25 +394,20 @@ void nl_complete_msg(struct nl_sock *sk, struct nl_msg *msg)
 		nlh->nlmsg_flags |= NLM_F_ACK;
 }
 
-void nl_auto_complete(struct nl_sock *sk, struct nl_msg *msg)
-{
-	nl_complete_msg(sk, msg);
-}
-
 /**
- * Automatically complete and send a netlink message
- * @arg sk		Netlink socket.
- * @arg msg		Netlink message to be sent.
+ * Finalize and transmit Netlink message
+ * @arg sk		Netlink socket (required)
+ * @arg msg		Netlink message (required)
  *
- * This function takes a netlink message and passes it on to
- * nl_auto_complete() for completion.
+ * Finalizes the message by passing it to `nl_complete_msg()` and transmits it
+ * by passing it to `nl_send()`.
  *
- * Checks the netlink message \c nlh for completness and extends it
- * as required before sending it out. Checked fields include pid,
- * sequence nr, and flags.
+ * @callback This function triggers the `NL_CB_MSG_OUT` callback.
  *
+ * @see nl_complete_msg()
  * @see nl_send()
- * @return Number of characters sent or a negative error code.
+ *
+ * @return Number of bytes sent or a negative error code.
  */
 int nl_send_auto(struct nl_sock *sk, struct nl_msg *msg)
 {
@@ -343,27 +421,28 @@ int nl_send_auto(struct nl_sock *sk, struct nl_msg *msg)
 		return nl_send(sk, msg);
 }
 
-int nl_send_auto_complete(struct nl_sock *sk, struct nl_msg *msg)
-{
-	return nl_send_auto(sk, msg);
-}
-
 /**
- * Send netlink message and wait for response (sync request-response)
- * @arg sk		Netlink socket
- * @arg msg		Netlink message to be sent
+ * Finalize and transmit Netlink message and wait for ACK or error message
+ * @arg sk		Netlink socket (required)
+ * @arg msg		Netlink message (required)
+ *
+ * Passes the `msg` to `nl_send_auto()` to finalize and transmit it. Frees the
+ * message and waits (sleeps) for the ACK or error message to be received.
  *
- * This function takes a netlink message and sends it using nl_send_auto().
- * It will then wait for the response (ACK or error message) to be
- * received. Threfore this function will block until the operation has
- * been completed.
+ * @attention
+ * Disabling Auto-ACK (nl_socket_disable_auto_ack()) will cause this function
+ * to return immediately after transmitting the message. However, the peer may
+ * still be returning an error message in response to the request. It is the
+ * responsibility of the caller to handle such messages.
  *
- * @note Disabling auto-ack (nl_socket_disable_auto_ack()) will cause
- *       this function to return immediately after sending. In this case,
- *       it is the responsibility of the caller to handle any eventual
- *       error messages returned.
+ * @callback This function triggers the `NL_CB_MSG_OUT` callback.
+ *
+ * @attention
+ * This function frees the `msg` object after transmitting it by calling
+ * `nlmsg_free()`.
  *
  * @see nl_send_auto().
+ * @see nl_wait_for_ack()
  *
  * @return 0 on success or a negative error code.
  */
@@ -996,6 +1075,30 @@ errout:
 
 /** @} */
 
+/**
+ * @name Deprecated
+ * @{
+ */
+
+/**
+ * @deprecated Please use nl_complete_msg()
+ */
+void nl_auto_complete(struct nl_sock *sk, struct nl_msg *msg)
+{
+	nl_complete_msg(sk, msg);
+}
+
+/**
+ * @deprecated Please use nl_send_auto()
+ */
+int nl_send_auto_complete(struct nl_sock *sk, struct nl_msg *msg)
+{
+	return nl_send_auto(sk, msg);
+}
+
+
+/** @} */
+
 /** @} */
 
 /** @} */