lib/ldb: Clarify the intent of ldb_data_unpack_withlist

This patch renames the function to indicate that you are unpacking with respect to some
attribute list, as well as adding some comments.

Signed-off-by: Garming Sam <garming@catalyst.net.nz>
Reviewed-by: Andrew Bartlett <abartlet@samba.org>
BUG: https://bugzilla.samba.org/show_bug.cgi?id=11602

2 files changed, 27 insertions, 19 deletions

diff --git a/lib/ldb/common/ldb_pack.c b/lib/ldb/common/ldb_pack.c
index 5524542dcd9..50bf9b80eea 100644
--- a/lib/ldb/common/ldb_pack.c
+++ b/lib/ldb/common/ldb_pack.c
@@ -169,17 +169,21 @@ static bool ldb_consume_element_data(uint8_t **pp, unsigned int *premaining)
 	*pp = p;
 	return true;
 }
-/*
-  unpack a ldb message from a linear buffer in ldb_val
 
-  Free with ldb_unpack_data_free()
-*/
-int ldb_unpack_data_withlist(struct ldb_context *ldb,
-			     const struct ldb_val *data,
-			     struct ldb_message *message,
-			     const char * const *list,
-			     unsigned int list_size,
-			     unsigned int *nb_elements_in_db)
+/*
+ * Unpack a ldb message from a linear buffer in ldb_val
+ *
+ * Providing a list of attributes to this function allows selective unpacking.
+ * Giving a NULL list (or a list_size of 0) unpacks all the attributes.
+ *
+ * Free with ldb_unpack_data_free()
+ */
+int ldb_unpack_data_only_attr_list(struct ldb_context *ldb,
+				   const struct ldb_val *data,
+				   struct ldb_message *message,
+				   const char * const *list,
+				   unsigned int list_size,
+				   unsigned int *nb_elements_in_db)
 {
 	uint8_t *p;
 	unsigned int remaining;
@@ -272,10 +276,14 @@ int ldb_unpack_data_withlist(struct ldb_context *ldb,
 			goto failed;
 		}
 		attr = (char *)p;
+
 		/*
+		 * The general idea is to reduce allocations by skipping over
+		 * attributes that we do not actually care about.
+		 *
 		 * This is a bit expensive but normally the list is pretty small
 		 * also the cost of freeing unused attributes is quite important
-		 * and can dwarf the cost of looping
+		 * and can dwarf the cost of looping.
 		 */
 		if (list_size != 0) {
 			bool keep = false;
@@ -356,7 +364,7 @@ int ldb_unpack_data_withlist(struct ldb_context *ldb,
 
 	if (remaining != 0) {
 		ldb_debug(ldb, LDB_DEBUG_ERROR,
-			  "Error: %d bytes unread in ldb_unpack_data_withlist",
+			  "Error: %d bytes unread in ldb_unpack_data_only_attr_list",
 			  remaining);
 	}
 
@@ -371,5 +379,5 @@ int ldb_unpack_data(struct ldb_context *ldb,
 		    const struct ldb_val *data,
 		    struct ldb_message *message)
 {
-	return ldb_unpack_data_withlist(ldb, data, message, NULL, 0, NULL);
+	return ldb_unpack_data_only_attr_list(ldb, data, message, NULL, 0, NULL);
 }
diff --git a/lib/ldb/include/ldb_module.h b/lib/ldb/include/ldb_module.h
index 7176721655f..c6a24d35e53 100644
--- a/lib/ldb/include/ldb_module.h
+++ b/lib/ldb/include/ldb_module.h
@@ -390,12 +390,12 @@ int ldb_register_extended_match_rule(struct ldb_context *ldb,
 int ldb_pack_data(struct ldb_context *ldb,
 		  const struct ldb_message *message,
 		  struct ldb_val *data);
-int ldb_unpack_data_withlist(struct ldb_context *ldb,
-			     const struct ldb_val *data,
-			     struct ldb_message *message,
-			     const char* const * list,
-			     unsigned int list_size,
-			     unsigned int *nb_attributes_indb);
+int ldb_unpack_data_only_attr_list(struct ldb_context *ldb,
+				   const struct ldb_val *data,
+				   struct ldb_message *message,
+				   const char* const * list,
+				   unsigned int list_size,
+				   unsigned int *nb_attributes_indb);
 int ldb_unpack_data(struct ldb_context *ldb,
 		    const struct ldb_val *data,
 		    struct ldb_message *message);