r24732: Add comments and fix memory leak.

rafal
(This used to be commit 07b52b360676692abf00b64e6eada0f7850357bd)

diff --git a/source4/libnet/libnet_group.c b/source4/libnet/libnet_group.c
index 1a54ec35bc89b54a20be6f45f7055c98b4309cb4..50615f3946e12831d71ec25989c50c92feaa05ac 100644 (file)
--- 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)
 {