r12103: Comments and a bit of formatting.

rafal
(This used to be commit 4a12711c310f3dc228ea7be539703fc3fc77444a)

diff --git a/source4/librpc/rpc/dcerpc_connect.c b/source4/librpc/rpc/dcerpc_connect.c
index d98c296a3fba25afa3d571526edc9fe7c7c0042a..9af54740a2503cf23dfc7416f7cb95d042304c09 100644 (file)
--- a/source4/librpc/rpc/dcerpc_connect.c
+++ b/source4/librpc/rpc/dcerpc_connect.c
@@ -43,16 +43,18 @@ struct pipe_np_smb_state {
 };
 
 
+/*
+  Stage 3 of ncacn_np_smb: Named pipe opened (?)
+*/
 void continue_pipe_open_smb(struct composite_context *ctx)
 {
        struct composite_context *c = talloc_get_type(ctx->async.private_data,
                                                      struct composite_context);
        struct pipe_np_smb_state *s = talloc_get_type(c->private_data,
                                                      struct pipe_np_smb_state);
-
+       /* receive result of named pipe open request */
        c->status = dcerpc_pipe_open_smb_recv(ctx);
        if (!NT_STATUS_IS_OK(c->status)) {
-
                DEBUG(0,("Failed to open pipe %s - %s\n", s->io.pipe_name, nt_errstr(c->status)));
                composite_error(c, c->status);
                return;
@@ -61,7 +63,9 @@ void continue_pipe_open_smb(struct composite_context *ctx)
        composite_done(c);
 }
 
-
+/*
+  Stage 2 of ncacn_np_smb: Open a named pipe after successful smb connection
+*/
 void continue_smb_connect(struct composite_context *ctx)
 {
        struct composite_context *open_ctx;
@@ -70,17 +74,19 @@ void continue_smb_connect(struct composite_context *ctx)
        struct pipe_np_smb_state *s = talloc_get_type(c->private_data,
                                                      struct pipe_np_smb_state);
        
+       /* receive result of smb connect request */
        c->status = smb_composite_connect_recv(ctx, c);
        if (!NT_STATUS_IS_OK(c->status)) {
-
                DEBUG(0,("Failed to connect to %s - %s\n", s->io.binding->host, nt_errstr(c->status)));
                composite_error(c, c->status);
                return;
        }
 
+       /* prepare named pipe open parameters */
        s->tree         = s->conn.out.tree;
        s->io.pipe_name = s->io.binding->endpoint;
 
+       /* send named pipe open request */
        open_ctx = dcerpc_pipe_open_smb_send(s->io.pipe->conn, s->tree, s->io.pipe_name);
        if (open_ctx == NULL) {
                composite_error(c, NT_STATUS_NO_MEMORY);
@@ -91,8 +97,10 @@ void continue_smb_connect(struct composite_context *ctx)
 }
 
 
-/* open a rpc connection to a rpc pipe on SMB using the binding
-   structure to determine the endpoint and options */
+/*
+  Initiate async open of a rpc connection to a rpc pipe on SMB using
+  the binding structure to determine the endpoint and options
+*/
 struct composite_context *dcerpc_pipe_connect_ncacn_np_smb_send(TALLOC_CTX *tmp_ctx, 
                                                                struct dcerpc_pipe_connect *io)
 {
@@ -101,6 +109,7 @@ struct composite_context *dcerpc_pipe_connect_ncacn_np_smb_send(TALLOC_CTX *tmp_
        struct composite_context *conn_req;
        struct smb_composite_connect *conn;
 
+       /* composite context allocation and setup */
        c = talloc_zero(tmp_ctx, struct composite_context);
        if (c == NULL) return NULL;
 
@@ -117,6 +126,8 @@ struct composite_context *dcerpc_pipe_connect_ncacn_np_smb_send(TALLOC_CTX *tmp_
        s->io  = *io;
        conn   = &s->conn;
 
+       /* prepare smb connection parameters: we're connecting to IPC$ share on
+          remote rpc server */
        conn->in.dest_host              = s->io.binding->host;
        conn->in.port                   = 0;
        conn->in.called_name            = strupper_talloc(tmp_ctx, s->io.binding->host);
@@ -125,6 +136,10 @@ struct composite_context *dcerpc_pipe_connect_ncacn_np_smb_send(TALLOC_CTX *tmp_
        conn->in.fallback_to_anonymous  = False;
        conn->in.workgroup              = lp_workgroup();
 
+       /*
+        * provide proper credentials - user supplied or anonymous in case this is
+        * schannel connection
+        */
        if (s->io.binding->flags & DCERPC_SCHANNEL) {
                struct cli_credentials *anon_creds;
 
@@ -143,6 +158,7 @@ struct composite_context *dcerpc_pipe_connect_ncacn_np_smb_send(TALLOC_CTX *tmp_
                s->conn.in.credentials = s->io.creds;
        }
 
+       /* send smb connect request */
        conn_req = smb_composite_connect_send(conn, s->io.pipe->conn, s->io.pipe->conn->event_ctx);
        if (!conn_req) {
                composite_error(c, NT_STATUS_NO_MEMORY);
@@ -156,6 +172,9 @@ done:
 }
 
 
+/*
+  Receive result of a rpc connection to a rpc pipe on SMB
+*/
 NTSTATUS dcerpc_pipe_connect_ncacn_np_smb_recv(struct composite_context *c)
 {
        NTSTATUS status = composite_wait(c);
@@ -165,6 +184,9 @@ NTSTATUS dcerpc_pipe_connect_ncacn_np_smb_recv(struct composite_context *c)
 }
 
 
+/*
+  Sync version of a rpc connection to a rpc pipe on SMB
+*/
 NTSTATUS dcerpc_pipe_connect_ncacn_np_smb(TALLOC_CTX *tmp_ctx,
                                          struct dcerpc_pipe_connect *io)
 {