r15439: Reorder the code a bit to be like in other calls. More comments

and comment-fixes.

rafal
(This used to be commit d35f1e07bed594dfae5421209c4318fe5e66a5aa)

diff --git a/source4/libnet/libnet_rpc.c b/source4/libnet/libnet_rpc.c
index e2b5b06035f6ddd8713b2bfd994f51cd365cfb4c..06e46f483580e4b4a5c5a6084ee2f9f3d7e1261e 100644 (file)
--- a/source4/libnet/libnet_rpc.c
+++ b/source4/libnet/libnet_rpc.c
@@ -305,98 +305,6 @@ static NTSTATUS libnet_RpcConnectDC_recv(struct composite_context *c,
 
 
 
-/**
- * Initiates connection to rpc pipe on remote server or pdc
- * 
- * @param ctx initialised libnet context
- * @param mem_ctx memory context of this call
- * @param r data structure containing necessary parameters and return values
- * @return composite context of this call
- **/
-
-struct composite_context* libnet_RpcConnect_send(struct libnet_context *ctx,
-                                                TALLOC_CTX *mem_ctx,
-                                                struct libnet_RpcConnect *r)
-{
-       struct composite_context *c;
-
-       switch (r->level) {
-       case LIBNET_RPC_CONNECT_SERVER:
-               c = libnet_RpcConnectSrv_send(ctx, mem_ctx, r);
-               break;
-
-       case LIBNET_RPC_CONNECT_BINDING:
-               c = libnet_RpcConnectSrv_send(ctx, mem_ctx, r);
-               break;
-                       
-       case LIBNET_RPC_CONNECT_PDC:
-       case LIBNET_RPC_CONNECT_DC:
-               c = libnet_RpcConnectDC_send(ctx, mem_ctx, r);
-               break;
-
-       case LIBNET_RPC_CONNECT_DC_INFO:
-               c = libnet_RpcConnectDCInfo_send(ctx, mem_ctx, r);
-               break;
-
-       default:
-               c = talloc_zero(mem_ctx, struct composite_context);
-               composite_error(c, NT_STATUS_INVALID_LEVEL);
-       }
-
-       return c;
-}
-
-
-/**
- * Receives result of connection to rpc pipe on remote server or pdc
- *
- * @param c composite context
- * @param ctx initialised libnet context
- * @param mem_ctx memory context of this call
- * @param r data structure containing necessary parameters and return values
- * @return nt status of rpc connection
- **/
-
-NTSTATUS libnet_RpcConnect_recv(struct composite_context *c, struct libnet_context *ctx,
-                               TALLOC_CTX *mem_ctx, struct libnet_RpcConnect *r)
-{
-       switch (r->level) {
-       case LIBNET_RPC_CONNECT_SERVER:
-       case LIBNET_RPC_CONNECT_BINDING:
-               return libnet_RpcConnectSrv_recv(c, ctx, mem_ctx, r);
-
-       case LIBNET_RPC_CONNECT_PDC:
-       case LIBNET_RPC_CONNECT_DC:
-               return libnet_RpcConnectDC_recv(c, ctx, mem_ctx, r);
-
-       case LIBNET_RPC_CONNECT_DC_INFO:
-               return libnet_RpcConnectDCInfo_recv(c, ctx, mem_ctx, r);
-
-       default:
-               return NT_STATUS_INVALID_LEVEL;
-       }
-}
-
-
-/**
- * Connect to a rpc pipe on a remote server - sync version
- *
- * @param ctx initialised libnet context
- * @param mem_ctx memory context of this call
- * @param r data structure containing necessary parameters and return values
- * @return nt status of rpc connection
- **/
-
-NTSTATUS libnet_RpcConnect(struct libnet_context *ctx, TALLOC_CTX *mem_ctx,
-                          struct libnet_RpcConnect *r)
-{
-       struct composite_context *c;
-       
-       c = libnet_RpcConnect_send(ctx, mem_ctx, r);
-       return libnet_RpcConnect_recv(c, ctx, mem_ctx, r);
-}
-
-
 struct rpc_connect_dci_state {
        struct libnet_context *ctx;
        struct libnet_RpcConnect r;
@@ -421,6 +329,62 @@ static void continue_epm_map_binding(struct composite_context *ctx);
 static void continue_secondary_conn(struct composite_context *ctx);
 
 
+/**
+ * Initiates connection to rpc pipe on remote server or pdc. Received result
+ * contains info on the domain name, domain sid and realm.
+ * 
+ * @param ctx initialised libnet context
+ * @param mem_ctx memory context of this call
+ * @param r data structure containing necessary parameters and return values. Must be a talloc context
+ * @return composite context of this call
+ **/
+
+static struct composite_context* libnet_RpcConnectDCInfo_send(struct libnet_context *ctx,
+                                                             TALLOC_CTX *mem_ctx,
+                                                             struct libnet_RpcConnect *r)
+{
+       struct composite_context *c, *conn_req;
+       struct rpc_connect_dci_state *s;
+
+       c = talloc_zero(mem_ctx, struct composite_context);
+       if (c == NULL) return NULL;
+
+       s = talloc_zero(c, struct rpc_connect_dci_state);
+       if (composite_nomem(s, c)) return c;
+
+       c->state = COMPOSITE_STATE_IN_PROGRESS;
+       c->private_data = s;
+       c->event_ctx = ctx->event_ctx;
+
+       s->r   = *r;
+       s->ctx = ctx;
+
+       /* proceed to pure rpc connection if the binding string is provided,
+          otherwise try to connect domain controller */
+       if (r->in.binding == NULL) {
+               s->rpc_conn.in.name    = r->in.name;
+               s->rpc_conn.level      = LIBNET_RPC_CONNECT_DC;
+       } else {
+               s->rpc_conn.in.binding = r->in.binding;
+               s->rpc_conn.level      = LIBNET_RPC_CONNECT_BINDING;
+       }
+
+       s->rpc_conn.in.dcerpc_iface    = &dcerpc_table_lsarpc;
+       
+       /* request connection to the lsa pipe on the pdc */
+       conn_req = libnet_RpcConnect_send(ctx, c, &s->rpc_conn);
+       if (composite_nomem(c, conn_req)) return c;
+
+       composite_continue(c, conn_req, continue_dci_rpc_connect, c);
+
+       return c;
+}
+
+
+/*
+  Step 2 of RpcConnectDCInfo: receive opened rpc pipe and open
+  lsa policy handle
+*/
 static void continue_dci_rpc_connect(struct composite_context *ctx)
 {
        struct composite_context *c;
@@ -459,6 +423,10 @@ static void continue_dci_rpc_connect(struct composite_context *ctx)
 }
 
 
+/*
+  Step 3 of RpcConnectDCInfo: Get policy handle and query lsa info
+  for kerberos realm (dns name) and guid. The query may fail.
+*/
 static void continue_lsa_policy(struct rpc_request *req)
 {
        struct composite_context *c;
@@ -484,6 +452,10 @@ static void continue_lsa_policy(struct rpc_request *req)
 }
 
 
+/*
+  Step 4 of RpcConnectDCInfo: Get realm and guid if provided (rpc call
+  may result in failure) and query lsa info for domain name and sid.
+*/
 static void continue_lsa_query_info2(struct rpc_request *req)
 {      
        struct composite_context *c;
@@ -527,6 +499,10 @@ static void continue_lsa_query_info2(struct rpc_request *req)
 }
 
 
+/*
+  Step 5 of RpcConnectDCInfo: Get domain name and sid and request endpoint
+  map binding
+*/
 static void continue_lsa_query_info(struct rpc_request *req)
 {
        struct composite_context *c, *epm_map_req;
@@ -562,6 +538,10 @@ static void continue_lsa_query_info(struct rpc_request *req)
 }
 
 
+/*
+  Step 6 of RpcConnectDCInfo: Receive endpoint mapping and create secondary
+  lsa pipe connection derived from already used pipe
+*/
 static void continue_epm_map_binding(struct composite_context *ctx)
 {
        struct composite_context *c, *sec_conn_req;
@@ -586,6 +566,10 @@ static void continue_epm_map_binding(struct composite_context *ctx)
 }
 
 
+/*
+  Step 7 of RpcConnectDCInfo: Get actual lsa pipe to be returned
+  and complete this composite call
+*/
 static void continue_secondary_conn(struct composite_context *ctx)
 {
        struct composite_context *c;
@@ -609,50 +593,19 @@ static void continue_secondary_conn(struct composite_context *ctx)
 }
 
 
-struct composite_context* libnet_RpcConnectDCInfo_send(struct libnet_context *ctx,
-                                                      TALLOC_CTX *mem_ctx,
-                                                      struct libnet_RpcConnect *r)
-{
-       struct composite_context *c, *conn_req;
-       struct rpc_connect_dci_state *s;
-
-       c = talloc_zero(mem_ctx, struct composite_context);
-       if (c == NULL) return NULL;
-
-       s = talloc_zero(c, struct rpc_connect_dci_state);
-       if (composite_nomem(s, c)) return c;
-
-       c->state = COMPOSITE_STATE_IN_PROGRESS;
-       c->private_data = s;
-       c->event_ctx = ctx->event_ctx;
-
-       s->r   = *r;
-       s->ctx = ctx;
-
-       s->rpc_conn.level = r->level;
-
-       if (r->in.binding == NULL) {
-               s->rpc_conn.in.name    = r->in.name;
-               s->rpc_conn.level      = LIBNET_RPC_CONNECT_DC;
-       } else {
-               s->rpc_conn.in.binding = r->in.binding;
-               s->rpc_conn.level      = LIBNET_RPC_CONNECT_BINDING;
-       }
-
-       s->rpc_conn.in.dcerpc_iface    = &dcerpc_table_lsarpc;
-       
-       /* request connection to the lsa pipe on the pdc */
-       conn_req = libnet_RpcConnect_send(ctx, c, &s->rpc_conn);
-       if (composite_nomem(c, conn_req)) return c;
-
-       composite_continue(c, conn_req, continue_dci_rpc_connect, c);
-
-       return c;
-}
-
+/**
+ * Receives result of connection to rpc pipe and gets basic
+ * domain info (name, sid, realm, guid)
+ *
+ * @param c composite context
+ * @param ctx initialised libnet context
+ * @param mem_ctx memory context of this call
+ * @param r data structure containing return values
+ * @return nt status of rpc connection
+ **/
 
-NTSTATUS libnet_RpcConnectDCInfo_recv(struct composite_context *c, struct libnet_context *ctx,
-                                     TALLOC_CTX *mem_ctx, struct libnet_RpcConnect *r)
+static NTSTATUS libnet_RpcConnectDCInfo_recv(struct composite_context *c, struct libnet_context *ctx,
+                                            TALLOC_CTX *mem_ctx, struct libnet_RpcConnect *r)
 {
        NTSTATUS status;
        struct rpc_connect_dci_state *s;
@@ -673,18 +626,93 @@ NTSTATUS libnet_RpcConnectDCInfo_recv(struct composite_context *c, struct libnet
 
 
 /**
- * Connects to rpc pipe on remote server or pdc, and returns info on the domain name, domain sid and realm
+ * Initiates connection to rpc pipe on remote server or pdc, optionally
+ * providing domain info
  * 
  * @param ctx initialised libnet context
- * @param r data structure containing necessary parameters and return values.  Must be a talloc context
- * @return nt status of the call
+ * @param mem_ctx memory context of this call
+ * @param r data structure containing necessary parameters and return values
+ * @return composite context of this call
  **/
 
-NTSTATUS libnet_RpcConnectDCInfo(struct libnet_context *ctx, TALLOC_CTX *mem_ctx,
-                                struct libnet_RpcConnect *r)
+struct composite_context* libnet_RpcConnect_send(struct libnet_context *ctx,
+                                                TALLOC_CTX *mem_ctx,
+                                                struct libnet_RpcConnect *r)
 {
        struct composite_context *c;
 
-       c = libnet_RpcConnectDCInfo_send(ctx, mem_ctx, r);
-       return libnet_RpcConnectDCInfo_recv(c, ctx, mem_ctx, r);
+       switch (r->level) {
+       case LIBNET_RPC_CONNECT_SERVER:
+               c = libnet_RpcConnectSrv_send(ctx, mem_ctx, r);
+               break;
+
+       case LIBNET_RPC_CONNECT_BINDING:
+               c = libnet_RpcConnectSrv_send(ctx, mem_ctx, r);
+               break;
+                       
+       case LIBNET_RPC_CONNECT_PDC:
+       case LIBNET_RPC_CONNECT_DC:
+               c = libnet_RpcConnectDC_send(ctx, mem_ctx, r);
+               break;
+
+       case LIBNET_RPC_CONNECT_DC_INFO:
+               c = libnet_RpcConnectDCInfo_send(ctx, mem_ctx, r);
+               break;
+
+       default:
+               c = talloc_zero(mem_ctx, struct composite_context);
+               composite_error(c, NT_STATUS_INVALID_LEVEL);
+       }
+
+       return c;
+}
+
+
+/**
+ * Receives result of connection to rpc pipe on remote server or pdc
+ *
+ * @param c composite context
+ * @param ctx initialised libnet context
+ * @param mem_ctx memory context of this call
+ * @param r data structure containing necessary parameters and return values
+ * @return nt status of rpc connection
+ **/
+
+NTSTATUS libnet_RpcConnect_recv(struct composite_context *c, struct libnet_context *ctx,
+                               TALLOC_CTX *mem_ctx, struct libnet_RpcConnect *r)
+{
+       switch (r->level) {
+       case LIBNET_RPC_CONNECT_SERVER:
+       case LIBNET_RPC_CONNECT_BINDING:
+               return libnet_RpcConnectSrv_recv(c, ctx, mem_ctx, r);
+
+       case LIBNET_RPC_CONNECT_PDC:
+       case LIBNET_RPC_CONNECT_DC:
+               return libnet_RpcConnectDC_recv(c, ctx, mem_ctx, r);
+
+       case LIBNET_RPC_CONNECT_DC_INFO:
+               return libnet_RpcConnectDCInfo_recv(c, ctx, mem_ctx, r);
+
+       default:
+               return NT_STATUS_INVALID_LEVEL;
+       }
+}
+
+
+/**
+ * Connect to a rpc pipe on a remote server - sync version
+ *
+ * @param ctx initialised libnet context
+ * @param mem_ctx memory context of this call
+ * @param r data structure containing necessary parameters and return values
+ * @return nt status of rpc connection
+ **/
+
+NTSTATUS libnet_RpcConnect(struct libnet_context *ctx, TALLOC_CTX *mem_ctx,
+                          struct libnet_RpcConnect *r)
+{
+       struct composite_context *c;
+       
+       c = libnet_RpcConnect_send(ctx, mem_ctx, r);
+       return libnet_RpcConnect_recv(c, ctx, mem_ctx, r);
 }