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

and comment-fixes.

rafal
(This used to be commit d35f1e07bed594dfae5421209c4318fe5e66a5aa)

1 files changed, 170 insertions, 142 deletions

diff --git a/source4/libnet/libnet_rpc.c b/source4/libnet/libnet_rpc.c
index e2b5b06035..06e46f4835 100644
--- 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);
 }