Move "struct cli_request" from client.h to async_smb.h

Also add some comments
(This used to be commit 2ecc311f785317caf5b60051147dcd085c80d64f)

diff --git a/source3/include/async_smb.h b/source3/include/async_smb.h
index 93d2273239c1261979272082364d7ace1318e782..031ab233dd49276f5dbbd3df0fdd049934363a63 100644 (file)
--- a/source3/include/async_smb.h
+++ b/source3/include/async_smb.h
@@ -17,8 +17,69 @@
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+#ifndef __ASYNC_SMB_H__
+#define __ASYNC_SMB_H__
+
 #include "includes.h"
 
+struct cli_request {
+       /**
+        * "prev" and "next" form the doubly linked list in
+        * cli_state->outstanding_requests
+        */
+       struct cli_request *prev, *next;
+
+       /**
+        * "our" struct async_req;
+        */
+       struct async_req *async;
+
+       /**
+        * The client connection for this request
+        */
+       struct cli_state *cli;
+
+       /**
+        * The enc_state to decrypt the reply
+        */
+       struct smb_trans_enc_state *enc_state;
+
+       /**
+        * The mid we used for this request. Mainly used to demultiplex on
+        * receiving replies.
+        */
+       uint16_t mid;
+
+       /**
+        * The bytes we have to ship to the server
+        */
+       char *outbuf;
+
+       /**
+        * How much from "outbuf" did we already send
+        */
+       size_t sent;
+
+       /**
+        * The reply comes in here. Its intended size is implicit by
+        * smb_len(), its current size can be read via talloc_get_size()
+        */
+       char *inbuf;
+
+       /**
+        * Specific requests might add stuff here. Maybe convert this to a
+        * private_pointer at some point.
+        */
+       union {
+               struct {
+                       off_t ofs;
+                       size_t size;
+                       ssize_t received;
+                       uint8_t *rcvbuf;
+               } read;
+       } data;
+};
+
 /*
  * Ship a new smb request to the server
  */
@@ -52,3 +113,5 @@ NTSTATUS cli_pull_error(char *buf);
  */
 
 void cli_set_error(struct cli_state *cli, NTSTATUS status);
+
+#endif

diff --git a/source3/include/client.h b/source3/include/client.h
index be12288f284409cf81b8e3e76dd56b5825ddb6e1..6a6e1a2faa000331d66154ebb91fcc2d8adc18ae 100644 (file)
--- a/source3/include/client.h
+++ b/source3/include/client.h
@@ -216,33 +216,12 @@ struct cli_state {
        struct fd_event *fd_event;
        char *evt_inbuf;
 
+       /**
+        * A linked list of requests that are waiting for a reply
+        */
        struct cli_request *outstanding_requests;
 };
 
-struct cli_request {
-       struct cli_request *prev, *next;
-       struct async_req *async;
-
-       struct cli_state *cli;
-
-       struct smb_trans_enc_state *enc_state;
-
-       uint16_t mid;
-
-       char *outbuf;
-       size_t sent;
-       char *inbuf;
-
-       union {
-               struct {
-                       off_t ofs;
-                       size_t size;
-                       ssize_t received;
-                       uint8_t *rcvbuf;
-               } read;
-       } data;
-};
-
 typedef struct file_info {
        struct cli_state *cli;
        SMB_BIG_UINT size;

diff --git a/source3/libsmb/async_smb.c b/source3/libsmb/async_smb.c
index 32f0e8abd6124f96bfda972fc1ee3668b8d1b004..e36e514a1665ec54104fe0055136e848fefb1e3e 100644 (file)
--- a/source3/libsmb/async_smb.c
+++ b/source3/libsmb/async_smb.c
@@ -22,8 +22,10 @@
 static void cli_state_handler(struct event_context *event_ctx,
                              struct fd_event *event, uint16 flags, void *p);
 
-/*
+/**
  * Fetch an error out of a NBT packet
+ * @param[in] buf      The SMB packet
+ * @retval             The error, converted to NTSTATUS
  */
 
 NTSTATUS cli_pull_error(char *buf)
@@ -43,8 +45,10 @@ NTSTATUS cli_pull_error(char *buf)
        return NT_STATUS_DOS(CVAL(buf, smb_rcls), SVAL(buf,smb_err));
 }
 
-/*
+/**
  * Compatibility helper for the sync APIs: Fake NTSTATUS in cli->inbuf
+ * @param[in] cli      The client connection that just received an error
+ * @param[in] status   The error to set on "cli"
  */
 
 void cli_set_error(struct cli_state *cli, NTSTATUS status)
@@ -64,8 +68,10 @@ void cli_set_error(struct cli_state *cli, NTSTATUS status)
        return;
 }
 
-/*
+/**
  * Allocate a new mid
+ * @param[in] cli      The client connection
+ * @retval             The new, unused mid
  */
 
 static uint16_t cli_new_mid(struct cli_state *cli)
@@ -91,6 +97,13 @@ static uint16_t cli_new_mid(struct cli_state *cli)
        }
 }
 
+/**
+ * Print an async req that happens to be a cli_request
+ * @param[in] mem_ctx  The TALLOC_CTX to put the result on
+ * @param[in] req      The request to print
+ * @retval             The string representation of "req"
+ */
+
 static char *cli_request_print(TALLOC_CTX *mem_ctx, struct async_req *req)
 {
        char *result = async_req_print(mem_ctx, req);
@@ -104,6 +117,12 @@ static char *cli_request_print(TALLOC_CTX *mem_ctx, struct async_req *req)
                result, "mid=%d\n", cli_req->mid);
 }
 
+/**
+ * Destroy a cli_request
+ * @param[in] req      The cli_request to kill
+ * @retval Can't fail
+ */
+
 static int cli_request_destructor(struct cli_request *req)
 {
        if (req->enc_state != NULL) {
@@ -284,8 +303,10 @@ NTSTATUS cli_pull_reply(struct async_req *req,
        return NT_STATUS_OK;
 }
 
-/*
+/**
  * Convenience function to get the SMB part out of an async_req
+ * @param[in] req      The request to look at
+ * @retval The private_data as struct cli_request
  */
 
 struct cli_request *cli_request_get(struct async_req *req)
@@ -296,8 +317,9 @@ struct cli_request *cli_request_get(struct async_req *req)
        return talloc_get_type_abort(req->private_data, struct cli_request);
 }
 
-/*
+/**
  * A PDU has arrived on cli->evt_inbuf
+ * @param[in] cli      The cli_state that received something
  */
 
 static void handle_incoming_pdu(struct cli_state *cli)
@@ -434,8 +456,12 @@ static void handle_incoming_pdu(struct cli_state *cli)
        return;
 }
 
-/*
+/**
  * fd event callback. This is the basic connection to the socket
+ * @param[in] event_ctx        The event context that called us
+ * @param[in] event    The event that fired
+ * @param[in] flags    EVENT_FD_READ | EVENT_FD_WRITE
+ * @param[in] p                private_data, in this case the cli_state
  */
 
 static void cli_state_handler(struct event_context *event_ctx,