r18983: Add some comments for the LDAP based GPO routines.

Guenther
(This used to be commit 2c21ee684c4197899f2314e99b891ce771b1fd65)

3 files changed, 60 insertions, 49 deletions

diff --git a/source3/include/gpo.h b/source3/include/gpo.h
index cdec1628d0..24aaaea75d 100644
--- a/source3/include/gpo.h
+++ b/source3/include/gpo.h
@@ -20,11 +20,11 @@
 
 
 enum GPO_LINK_TYPE {
-	GP_LINK_UNKOWN,
-	GP_LINK_MACHINE,
-	GP_LINK_SITE,
-	GP_LINK_DOMAIN,
-	GP_LINK_OU
+	GP_LINK_UNKOWN	= 0,
+	GP_LINK_MACHINE	= 1,
+	GP_LINK_SITE	= 2,
+	GP_LINK_DOMAIN	= 3,
+	GP_LINK_OU	= 4
 };
 
 /* GPO_OPTIONS */
@@ -41,8 +41,6 @@ enum GPO_LINK_TYPE {
 struct GROUP_POLICY_OBJECT {
 	uint32 options;	/* GPFLAGS_* */ 
 	uint32 version;
-	uint16 version_user;
-	uint16 version_machine;
 	const char *ds_path;
 	const char *file_sys_path;
 	const char *display_name;
@@ -65,8 +63,8 @@ struct GROUP_POLICY_OBJECT {
 
 /* 'gPOptions', maybe a bitmask as well */
 enum GPO_INHERIT {
-	GPOPTIONS_INHERIT,
-	GPOPTIONS_BLOCK_INHERITANCE
+	GPOPTIONS_INHERIT		= 0,
+	GPOPTIONS_BLOCK_INHERITANCE	= 1
 };
 
 /* 'flags' in a 'groupPolicyContainer' object */
diff --git a/source3/libgpo/gpo_ldap.c b/source3/libgpo/gpo_ldap.c
index 4a121e9f6a..84c8e1ee9a 100644
--- a/source3/libgpo/gpo_ldap.c
+++ b/source3/libgpo/gpo_ldap.c
@@ -22,6 +22,10 @@
 
 #ifdef HAVE_LDAP
 
+/****************************************************************
+ parse the raw extension string into a GP_EXT structure
+****************************************************************/
+
 ADS_STATUS ads_parse_gp_ext(TALLOC_CTX *mem_ctx,
 			    const char *extension_raw,
 			    struct GP_EXT *gp_ext)
@@ -131,6 +135,10 @@ parse_error:
 	return ADS_ERROR(LDAP_NO_MEMORY);
 }
 
+/****************************************************************
+ parse the raw link string into a GP_LINK structure
+****************************************************************/
+
 ADS_STATUS ads_parse_gplink(TALLOC_CTX *mem_ctx, 
 			    const char *gp_link_raw,
 			    uint32 options,
@@ -206,6 +214,10 @@ parse_error:
 	return ADS_ERROR(LDAP_NO_MEMORY);
 }
 
+/****************************************************************
+ helper call to get a GP_LINK structure from a linkdn
+****************************************************************/
+
 ADS_STATUS ads_get_gpo_link(ADS_STRUCT *ads,
 			    TALLOC_CTX *mem_ctx,
 			    const char *link_dn,
@@ -238,6 +250,7 @@ ADS_STATUS ads_get_gpo_link(ADS_STRUCT *ads,
 		return ADS_ERROR(LDAP_NO_SUCH_ATTRIBUTE);	
 	}
 
+	/* perfectly leggal to have no options */
 	if (!ads_pull_uint32(ads, res, "gPOptions", &gp_options)) {
 		DEBUG(10,("ads_get_gpo_link: no 'gPOptions' attribute found\n"));
 		gp_options = 0;
@@ -248,6 +261,10 @@ ADS_STATUS ads_get_gpo_link(ADS_STRUCT *ads,
 	return ads_parse_gplink(mem_ctx, gp_link, gp_options, gp_link_struct); 
 }
 
+/****************************************************************
+ helper call to add a gp link
+****************************************************************/
+
 ADS_STATUS ads_add_gpo_link(ADS_STRUCT *ads, 
 			    TALLOC_CTX *mem_ctx, 
 			    const char *link_dn, 
@@ -260,7 +277,6 @@ ADS_STATUS ads_add_gpo_link(ADS_STRUCT *ads,
 	const char *gp_link, *gp_link_new;
 	ADS_MODLIST mods;
 
-
 	/* although ADS allows to set anything here, we better check here if
 	 * the gpo_dn is sane */
 
@@ -288,14 +304,10 @@ ADS_STATUS ads_add_gpo_link(ADS_STRUCT *ads,
 	}
 
 	ads_msgfree(ads, res);
-	if (gp_link_new == NULL) {
-		return ADS_ERROR(LDAP_NO_MEMORY);
-	}
+	ADS_ERROR_HAVE_NO_MEMORY(gp_link_new);
 
 	mods = ads_init_mods(mem_ctx);
-	if (mods == NULL) {
-		return ADS_ERROR(LDAP_NO_MEMORY);
-	}
+	ADS_ERROR_HAVE_NO_MEMORY(mods);
 
 	status = ads_mod_str(mem_ctx, &mods, "gPLink", gp_link_new);
 	if (!ADS_ERR_OK(status)) {
@@ -305,6 +317,10 @@ ADS_STATUS ads_add_gpo_link(ADS_STRUCT *ads,
 	return ads_gen_mod(ads, link_dn, mods); 
 }
 
+/****************************************************************
+ helper call to delete add a gp link
+****************************************************************/
+
 /* untested & broken */
 ADS_STATUS ads_delete_gpo_link(ADS_STRUCT *ads, 
 			       TALLOC_CTX *mem_ctx, 
@@ -349,14 +365,10 @@ ADS_STATUS ads_delete_gpo_link(ADS_STRUCT *ads,
 	/* gp_link_new = talloc_asprintf(mem_ctx, "%s[%s;%d]", gp_link, gpo_dn, gpo_opt); */
 
 	ads_msgfree(ads, res);
-	if (gp_link_new == NULL) {
-		return ADS_ERROR(LDAP_NO_MEMORY);
-	}
+	ADS_ERROR_HAVE_NO_MEMORY(gp_link_new);
 
 	mods = ads_init_mods(mem_ctx);
-	if (mods == NULL) {
-		return ADS_ERROR(LDAP_NO_MEMORY);
-	}
+	ADS_ERROR_HAVE_NO_MEMORY(mods);
 
 	status = ads_mod_str(mem_ctx, &mods, "gPLink", gp_link_new);
 	if (!ADS_ERR_OK(status)) {
@@ -366,6 +378,10 @@ ADS_STATUS ads_delete_gpo_link(ADS_STRUCT *ads,
 	return ads_gen_mod(ads, link_dn, mods); 
 }
 
+/****************************************************************
+ parse a GROUP_POLICY_OBJECT structure from an LDAPMessage result
+****************************************************************/
+
  ADS_STATUS ads_parse_gpo(ADS_STRUCT *ads,
 			  TALLOC_CTX *mem_ctx,
 			  LDAPMessage *res,
@@ -374,46 +390,33 @@ ADS_STATUS ads_delete_gpo_link(ADS_STRUCT *ads,
 {
 	ZERO_STRUCTP(gpo);
 
-	if (res == NULL) {
-		return ADS_ERROR(LDAP_NO_MEMORY);
-	}
+	ADS_ERROR_HAVE_NO_MEMORY(res);
 
 	if (gpo_dn) {
 		gpo->ds_path = talloc_strdup(mem_ctx, gpo_dn);
 	} else {
 		gpo->ds_path = ads_get_dn(ads, res);
 	}
-	if (gpo->ds_path == NULL) {
-		return ADS_ERROR(LDAP_NO_MEMORY);
-	}
+
+	ADS_ERROR_HAVE_NO_MEMORY(gpo->ds_path);
 
 	if (!ads_pull_uint32(ads, res, "versionNumber", &gpo->version)) {
 		return ADS_ERROR(LDAP_NO_MEMORY);
 	}
 
-	/* split here for convenience */
-	gpo->version_user = GPO_VERSION_USER(gpo->version);
-	gpo->version_machine = GPO_VERSION_MACHINE(gpo->version);
-
 	/* sure ??? */
 	if (!ads_pull_uint32(ads, res, "flags", &gpo->options)) {
 		return ADS_ERROR(LDAP_NO_MEMORY);
 	}
 
 	gpo->file_sys_path = ads_pull_string(ads, mem_ctx, res, "gPCFileSysPath");
-	if (gpo->file_sys_path == NULL) {
-		return ADS_ERROR(LDAP_NO_MEMORY);
-	}
+	ADS_ERROR_HAVE_NO_MEMORY(gpo->file_sys_path);
 
 	gpo->display_name = ads_pull_string(ads, mem_ctx, res, "displayName");
-	if (gpo->display_name == NULL) {
-		return ADS_ERROR(LDAP_NO_MEMORY);
-	}
+	ADS_ERROR_HAVE_NO_MEMORY(gpo->display_name);
 
 	gpo->name = ads_pull_string(ads, mem_ctx, res, "name");
-	if (gpo->name == NULL) {
-		return ADS_ERROR(LDAP_NO_MEMORY);
-	}
+	ADS_ERROR_HAVE_NO_MEMORY(gpo->name);
 
 	/* ???, this is optional to have and what does it depend on, the 'flags' ?) */
 	gpo->machine_extensions = ads_pull_string(ads, mem_ctx, res, "gPCMachineExtensionNames");
@@ -422,6 +425,10 @@ ADS_STATUS ads_delete_gpo_link(ADS_STRUCT *ads,
 	return ADS_ERROR(LDAP_SUCCESS);
 }
 
+/****************************************************************
+ get a GROUP_POLICY_OBJECT structure based on different input paramters
+****************************************************************/
+
 ADS_STATUS ads_get_gpo(ADS_STRUCT *ads,
 		       TALLOC_CTX *mem_ctx,
 		       const char *gpo_dn,
@@ -458,9 +465,7 @@ ADS_STATUS ads_get_gpo(ADS_STRUCT *ads,
 					 "(&(objectclass=groupPolicyContainer)(%s=%s))", 
 					 display_name ? "displayName" : "name",
 					 display_name ? display_name : guid_name);
-		if (filter == NULL) {
-			return ADS_ERROR(LDAP_NO_MEMORY);
-		}
+		ADS_ERROR_HAVE_NO_MEMORY(filter);
 
 		status = ads_do_search_all(ads, ads->config.bind_path,
 					   LDAP_SCOPE_SUBTREE, filter, 
@@ -491,6 +496,10 @@ ADS_STATUS ads_get_gpo(ADS_STRUCT *ads,
 	return status;
 }
 
+/****************************************************************
+ add a gplink to the GROUP_POLICY_OBJECT linked list
+****************************************************************/
+
 ADS_STATUS add_gplink_to_gpo_list(ADS_STRUCT *ads,
 				  TALLOC_CTX *mem_ctx, 
 				  struct GROUP_POLICY_OBJECT **gpo_list,
@@ -522,9 +531,7 @@ ADS_STATUS add_gplink_to_gpo_list(ADS_STRUCT *ads,
 		}
 
 		new_gpo = TALLOC_P(mem_ctx, struct GROUP_POLICY_OBJECT);
-		if (new_gpo == NULL) {
-			return ADS_ERROR(LDAP_NO_MEMORY);
-		}
+		ADS_ERROR_HAVE_NO_MEMORY(new_gpo);
 
 		ZERO_STRUCTP(new_gpo);
 
@@ -545,6 +552,10 @@ ADS_STATUS add_gplink_to_gpo_list(ADS_STRUCT *ads,
 	return ADS_ERROR(LDAP_SUCCESS);
 }
 
+/****************************************************************
+ get the full list of GROUP_POLICY_OBJECTs for a given dn
+****************************************************************/
+
 ADS_STATUS ads_get_gpo_list(ADS_STRUCT *ads, 
 			    TALLOC_CTX *mem_ctx, 
 			    const char *dn,
diff --git a/source3/libgpo/gpo_util.c b/source3/libgpo/gpo_util.c
index a30df6e9eb..37d3bb2ba8 100644
--- a/source3/libgpo/gpo_util.c
+++ b/source3/libgpo/gpo_util.c
@@ -202,8 +202,10 @@ void dump_gpo(TALLOC_CTX *mem_ctx, struct GROUP_POLICY_OBJECT *gpo)
 	DEBUGADD(lvl,("name:\t\t\t%s\n", gpo->name));
 	DEBUGADD(lvl,("displayname:\t\t%s\n", gpo->display_name));
 	DEBUGADD(lvl,("version:\t\t%d (0x%08x)\n", gpo->version, gpo->version));
-	DEBUGADD(lvl,("version_user:\t\t%d (0x%04x)\n", gpo->version_user, gpo->version_user));
-	DEBUGADD(lvl,("version_machine:\t%d (0x%04x)\n", gpo->version_machine, gpo->version_machine));
+	DEBUGADD(lvl,("version_user:\t\t%d (0x%04x)\n", GPO_VERSION_USER(gpo->version), 
+							GPO_VERSION_USER(gpo->version)));
+	DEBUGADD(lvl,("version_machine:\t%d (0x%04x)\n", GPO_VERSION_MACHINE(gpo->version), 
+							 GPO_VERSION_MACHINE(gpo->version)));
 	DEBUGADD(lvl,("filesyspath:\t\t%s\n", gpo->file_sys_path));
 	DEBUGADD(lvl,("dspath:\t\t%s\n", gpo->ds_path));