r24732: Add comments and fix memory leak.

rafal
(This used to be commit 07b52b360676692abf00b64e6eada0f7850357bd)

1 files changed, 61 insertions, 8 deletions

diff --git a/source4/libnet/libnet_group.c b/source4/libnet/libnet_group.c
index 1a54ec35bc..50615f3946 100644
--- a/source4/libnet/libnet_group.c
+++ b/source4/libnet/libnet_group.c
@@ -41,7 +41,15 @@ static void continue_domain_open_info(struct composite_context *ctx);
 static void continue_name_found(struct composite_context *ctx);
 static void continue_group_info(struct composite_context *ctx);
 
-
+/**
+ * Sends request to get group information
+ *
+ * @param ctx initialised libnet context
+ * @param mem_ctx memory context of this call
+ * @param io pointer to structure containing arguments the call
+ * @param monitor function pointer for receiving monitor messages
+ * @return composite context of this request
+ */
 struct composite_context* libnet_GroupInfo_send(struct libnet_context *ctx,
 						TALLOC_CTX *mem_ctx,
 						struct libnet_GroupInfo *io,
@@ -61,9 +69,9 @@ struct composite_context* libnet_GroupInfo_send(struct libnet_context *ctx,
 
 	c->private_data = s;
 
+	/* store arguments in the state structure */
 	s->monitor_fn = monitor;
-	s->ctx = ctx;
-	
+	s->ctx = ctx;	
 	s->domain_name = talloc_strdup(c, io->in.domain_name);
 	s->group_name  = talloc_strdup(c, io->in.group_name);
 
@@ -71,18 +79,24 @@ struct composite_context* libnet_GroupInfo_send(struct libnet_context *ctx,
 	prereq_met = samr_domain_opened(ctx, s->domain_name, &c, &s->domopen,
 					continue_domain_open_info, monitor);
 	if (!prereq_met) return c;
-
+	
+	/* prepare arguments for LookupName call */
 	s->lookup.in.name        = s->group_name;
 	s->lookup.in.domain_name = s->domain_name;
 
+	/* send the request */
 	lookup_req = libnet_LookupName_send(s->ctx, c, &s->lookup, s->monitor_fn);
 	if (composite_nomem(lookup_req, c)) return c;
 
+	/* set the next stage */
 	composite_continue(c, lookup_req, continue_name_found, c);
 	return c;
 }
 
 
+/*
+ * Stage 0.5 (optional): receive opened domain and send lookup name request
+ */
 static void continue_domain_open_info(struct composite_context *ctx)
 {
 	struct composite_context *c;
@@ -92,19 +106,26 @@ static void continue_domain_open_info(struct composite_context *ctx)
 	c = talloc_get_type(ctx->async.private_data, struct composite_context);
 	s = talloc_get_type(c->private_data, struct group_info_state);
 	
+	/* receive domain handle */
 	c->status = libnet_DomainOpen_recv(ctx, s->ctx, c, &s->domopen);
 	if (!composite_is_ok(c)) return;
 
+	/* prepare arguments for LookupName call */
 	s->lookup.in.name        = s->group_name;
 	s->lookup.in.domain_name = s->domain_name;
-	
+
+	/* send the request */
 	lookup_req = libnet_LookupName_send(s->ctx, c, &s->lookup, s->monitor_fn);
 	if (composite_nomem(lookup_req, c)) return;
 	
+	/* set the next stage */
 	composite_continue(c, lookup_req, continue_name_found, c);
 }
 
 
+/*
+ * Stage 1: Receive SID found and send request for group info
+ */
 static void continue_name_found(struct composite_context *ctx)
 {
 	struct composite_context *c;
@@ -113,27 +134,36 @@ static void continue_name_found(struct composite_context *ctx)
 
 	c = talloc_get_type(ctx->async.private_data, struct composite_context);
 	s = talloc_get_type(c->private_data, struct group_info_state);
-	
+
+	/* receive SID assiociated with name found */
 	c->status = libnet_LookupName_recv(ctx, c, &s->lookup);
 	if (!composite_is_ok(c)) return;
-
+	
+	/* Is is a group SID actually ? */
 	if (s->lookup.out.sid_type != SID_NAME_DOM_GRP &&
 	    s->lookup.out.sid_type != SID_NAME_ALIAS) {
 		composite_error(c, NT_STATUS_NO_SUCH_GROUP);
 	}
 
+	/* prepare arguments for groupinfo call */
 	s->info.in.domain_handle = s->ctx->samr.handle;
 	s->info.in.groupname     = s->group_name;
 	s->info.in.sid           = s->lookup.out.sidstr;
+	/* we're looking for all information available */
 	s->info.in.level         = GROUPINFOALL;
-	
+
+	/* send the request */
 	info_req = libnet_rpc_groupinfo_send(s->ctx->samr.pipe, &s->info, s->monitor_fn);
 	if (composite_nomem(info_req, c)) return;
 
+	/* set the next stage */
 	composite_continue(c, info_req, continue_group_info, c);
 }
 
 
+/*
+ * Stage 2: Receive group information
+ */
 static void continue_group_info(struct composite_context *ctx)
 {
 	struct composite_context *c;
@@ -142,13 +172,23 @@ static void continue_group_info(struct composite_context *ctx)
 	c = talloc_get_type(ctx->async.private_data, struct composite_context);
 	s = talloc_get_type(c->private_data, struct group_info_state);
 
+	/* receive group information */
 	c->status = libnet_rpc_groupinfo_recv(ctx, c, &s->info);
 	if (!composite_is_ok(c)) return;
 
+	/* we're done */
 	composite_done(c);
 }
 
 
+/*
+ * Receive group information
+ *
+ * @param c composite context returned by libnet_GroupInfo_send
+ * @param mem_ctx memory context of this call
+ * @param io pointer to a structure receiving results of the call
+ * @result nt status
+ */
 NTSTATUS libnet_GroupInfo_recv(struct composite_context* c, TALLOC_CTX *mem_ctx,
 			       struct libnet_GroupInfo *io)
 {
@@ -157,6 +197,7 @@ NTSTATUS libnet_GroupInfo_recv(struct composite_context* c, TALLOC_CTX *mem_ctx,
 	
 	status = composite_wait(c);
 	if (NT_STATUS_IS_OK(status)) {
+		/* put the results into io structure if everything went fine */
 		s = talloc_get_type(c->private_data, struct group_info_state);
 		
 		io->out.group_sid = talloc_steal(mem_ctx, s->lookup.out.sid);
@@ -164,12 +205,24 @@ NTSTATUS libnet_GroupInfo_recv(struct composite_context* c, TALLOC_CTX *mem_ctx,
 		io->out.description = talloc_steal(mem_ctx, s->info.out.info.all.description.string);
 
 		io->out.error_string = talloc_strdup(mem_ctx, "Success");
+
+	} else {
+		io->out.error_string = talloc_asprintf(mem_ctx, "Error: %s", nt_errstr(status));
 	}
 
+	talloc_free(c);
+
 	return status;
 }
 
 
+/**
+ * Obtains specified group information
+ * 
+ * @param ctx initialised libnet context
+ * @param mem_ctx memory context of the call
+ * @param io pointer to a structure containing arguments and results of the call
+ */
 NTSTATUS libnet_GroupInfo(struct libnet_context *ctx, TALLOC_CTX *mem_ctx,
 			  struct libnet_GroupInfo *io)
 {