Some doxygen comments for idmap

(This used to be commit adecc6d91338e7e34afd0672aada5d0e47247a33)

2 files changed, 157 insertions, 15 deletions

diff --git a/source3/winbindd/idmap.c b/source3/winbindd/idmap.c
index bace38876b..c23919fb18 100644
--- a/source3/winbindd/idmap.c
+++ b/source3/winbindd/idmap.c
@@ -28,37 +28,59 @@
 
 static_decl_idmap;
 
+/**
+ * Pointer to the backend methods. Modules register themselves here via
+ * smb_register_idmap.
+ */
+
 struct idmap_backend {
 	const char *name;
 	struct idmap_methods *methods;
 	struct idmap_backend *prev, *next;
 };
+static struct idmap_backend *backends = NULL;
 
+/**
+ * Pointer to the alloc backend methods. Modules register themselves here via
+ * smb_register_idmap_alloc.
+ */
 struct idmap_alloc_backend {
 	const char *name;
 	struct idmap_alloc_methods *methods;
 	struct idmap_alloc_backend *prev, *next;
 };
+static struct idmap_alloc_backend *alloc_backends = NULL;
 
+/**
+ * The idmap alloc context that is configured via "idmap alloc
+ * backend". Defaults to "idmap backend" in case the module (tdb, ldap) also
+ * provides alloc methods.
+ */
 struct idmap_alloc_context {
 	struct idmap_alloc_methods *methods;
 };
+static struct idmap_alloc_context *idmap_alloc_ctx = NULL;
 
-/*
- * Lists for the module initializations
+/**
+ * Default idmap domain configured via "idmap backend".
  */
-static struct idmap_backend *backends = NULL;
-static struct idmap_alloc_backend *alloc_backends = NULL;
-
-
 static struct idmap_domain *default_idmap_domain;
+
+/**
+ * Passdb idmap domain, not configurable. winbind must always give passdb a
+ * chance to map ids.
+ */
 static struct idmap_domain *passdb_idmap_domain;
 
+/**
+ * List of specially configured idmap domains. This list is filled on demand
+ * in the winbind idmap child when the parent winbind figures out via the
+ * special range parameter or via the domain SID that a special "idmap config
+ * domain" configuration is present.
+ */
 static struct idmap_domain **idmap_domains = NULL;
 static int num_domains = 0;
 
-static struct idmap_alloc_context *idmap_alloc_ctx = NULL;
-
 static struct idmap_methods *get_methods(struct idmap_backend *be,
 					 const char *name)
 {
@@ -126,7 +148,8 @@ NTSTATUS smb_register_idmap(int version, const char *name,
 
 	for (entry = backends; entry != NULL; entry = entry->next) {
 		if (strequal(entry->name, name)) {
-			DEBUG(0,("Idmap module %s already registered!\n", name));
+			DEBUG(0,("Idmap module %s already registered!\n",
+				 name));
 			return NT_STATUS_OBJECT_NAME_COLLISION;
 		}
 	}
@@ -151,7 +174,7 @@ NTSTATUS smb_register_idmap(int version, const char *name,
 }
 
 /**********************************************************************
- Allow a module to register itself as a method.
+ Allow a module to register itself as an alloc method.
 **********************************************************************/
 
 NTSTATUS smb_register_idmap_alloc(int version, const char *name,
@@ -249,6 +272,14 @@ static bool parse_idmap_module(TALLOC_CTX *mem_ctx, const char *param,
 	return true;
 }
 
+/**
+ * Initialize a domain structure
+ * @param[in] mem_ctx		memory context for the result
+ * @param[in] domainname	which domain is this for
+ * @param[in] modulename	which backend module
+ * @param[in] params		parameter to pass to the init function
+ * @result The initialized structure
+ */
 static struct idmap_domain *idmap_init_domain(TALLOC_CTX *mem_ctx,
 					      const char *domainname,
 					      const char *modulename,
@@ -303,6 +334,15 @@ fail:
 	return NULL;
 }
 
+/**
+ * Initialize the default domain structure
+ * @param[in] mem_ctx		memory context for the result
+ * @result The default domain structure
+ *
+ * This routine takes the module name from the "idmap backend" parameter,
+ * passing a possible parameter like ldap:ldap://ldap-url/ to the module.
+ */
+
 static struct idmap_domain *idmap_init_default_domain(TALLOC_CTX *mem_ctx)
 {
 	struct idmap_domain *result;
@@ -337,6 +377,16 @@ fail:
 	return NULL;
 }
 
+/**
+ * Initialize a named domain structure
+ * @param[in] mem_ctx		memory context for the result
+ * @param[in] domname		the domain name
+ * @result The default domain structure
+ *
+ * This routine looks at the "idmap config <domname>" parameters to figure out
+ * the configuration.
+ */
+
 static struct idmap_domain *idmap_init_named_domain(TALLOC_CTX *mem_ctx,
 						    const char *domname)
 {
@@ -371,6 +421,14 @@ fail:
 	return NULL;
 }
 
+/**
+ * Initialize the passdb domain structure
+ * @param[in] mem_ctx		memory context for the result
+ * @result The default domain structure
+ *
+ * No config, passdb has its own configuration.
+ */
+
 static struct idmap_domain *idmap_init_passdb_domain(TALLOC_CTX *mem_ctx)
 {
 	if (passdb_idmap_domain != NULL) {
@@ -386,6 +444,21 @@ static struct idmap_domain *idmap_init_passdb_domain(TALLOC_CTX *mem_ctx)
 	return passdb_idmap_domain;
 }
 
+/**
+ * Find a domain struct according to a domain name
+ * @param[in] domname		Domain name to get the config for
+ * @result The default domain structure that fits
+ *
+ * This is the central routine in the winbindd-idmap child to pick the correct
+ * domain for looking up IDs. If domname is NULL or empty, we use the default
+ * domain. If it contains something, we try to use idmap_init_named_domain()
+ * to fetch the correct backend.
+ *
+ * The choice about "domname" is being made by the winbind parent, look at the
+ * "have_idmap_config" of "struct winbindd_domain" which is set in
+ * add_trusted_domain.
+ */
+
 static struct idmap_domain *idmap_find_domain(const char *domname)
 {
 	struct idmap_domain *result;
@@ -449,6 +522,14 @@ void idmap_close(void)
 	num_domains = 0;
 }
 
+/**
+ * Initialize the idmap alloc backend
+ * @param[out] ctx		Where to put the alloc_ctx?
+ * @result Did it work fine?
+ *
+ * This routine first looks at "idmap alloc backend" and if that is not
+ * defined, it uses "idmap backend" for the module name.
+ */
 static NTSTATUS idmap_alloc_init(struct idmap_alloc_context **ctx)
 {
 	const char *backend;
diff --git a/source3/winbindd/idmap_cache.c b/source3/winbindd/idmap_cache.c
index b818d0dafb..496f70ab45 100644
--- a/source3/winbindd/idmap_cache.c
+++ b/source3/winbindd/idmap_cache.c
@@ -1,11 +1,8 @@
-/* 
+/*
    Unix SMB/CIFS implementation.
    ID Mapping Cache
 
-   based on gencache
-
-   Copyright (C) Simo Sorce		2006
-   Copyright (C) Rafal Szczesniak	2002
+   Copyright (C) Volker Lendecke	2008
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -23,6 +20,16 @@
 #include "includes.h"
 #include "winbindd.h"
 
+/**
+ * Find a sid2uid mapping
+ * @param[in] sid		the sid to map
+ * @param[out] puid		where to put the result
+ * @param[out] expired		is the cache entry expired?
+ * @retval Was anything in the cache at all?
+ *
+ * If *puid == -1 this was a negative mapping.
+ */
+
 bool idmap_cache_find_sid2uid(const struct dom_sid *sid, uid_t *puid,
 			      bool *expired)
 {
@@ -54,6 +61,16 @@ bool idmap_cache_find_sid2uid(const struct dom_sid *sid, uid_t *puid,
 	return ret;
 }
 
+/**
+ * Find a uid2sid mapping
+ * @param[in] uid		the uid to map
+ * @param[out] sid		where to put the result
+ * @param[out] expired		is the cache entry expired?
+ * @retval Was anything in the cache at all?
+ *
+ * If "is_null_sid(sid)", this was a negative mapping.
+ */
+
 bool idmap_cache_find_uid2sid(uid_t uid, struct dom_sid *sid, bool *expired)
 {
 	char *key;
@@ -81,6 +98,18 @@ bool idmap_cache_find_uid2sid(uid_t uid, struct dom_sid *sid, bool *expired)
 	return ret;
 }
 
+/**
+ * Store a mapping in the idmap cache
+ * @param[in] sid		the sid to map
+ * @param[in] uid		the uid to map
+ *
+ * If both parameters are valid values, then a positive mapping in both
+ * directions is stored. If "is_null_sid(sid)" is true, then this will be a
+ * negative mapping of uid, we want to cache that for this uid we could not
+ * find anything. Likewise if "uid==-1", then we want to cache that we did not
+ * find a mapping for the sid passed here.
+ */
+
 void idmap_cache_set_sid2uid(const struct dom_sid *sid, uid_t uid)
 {
 	time_t now = time(NULL);
@@ -111,6 +140,16 @@ void idmap_cache_set_sid2uid(const struct dom_sid *sid, uid_t uid)
 	}
 }
 
+/**
+ * Find a sid2gid mapping
+ * @param[in] sid		the sid to map
+ * @param[out] pgid		where to put the result
+ * @param[out] expired		is the cache entry expired?
+ * @retval Was anything in the cache at all?
+ *
+ * If *pgid == -1 this was a negative mapping.
+ */
+
 bool idmap_cache_find_sid2gid(const struct dom_sid *sid, gid_t *pgid,
 			      bool *expired)
 {
@@ -142,6 +181,16 @@ bool idmap_cache_find_sid2gid(const struct dom_sid *sid, gid_t *pgid,
 	return ret;
 }
 
+/**
+ * Find a gid2sid mapping
+ * @param[in] gid		the gid to map
+ * @param[out] sid		where to put the result
+ * @param[out] expired		is the cache entry expired?
+ * @retval Was anything in the cache at all?
+ *
+ * If "is_null_sid(sid)", this was a negative mapping.
+ */
+
 bool idmap_cache_find_gid2sid(gid_t gid, struct dom_sid *sid, bool *expired)
 {
 	char *key;
@@ -169,6 +218,18 @@ bool idmap_cache_find_gid2sid(gid_t gid, struct dom_sid *sid, bool *expired)
 	return ret;
 }
 
+/**
+ * Store a mapping in the idmap cache
+ * @param[in] sid		the sid to map
+ * @param[in] gid		the gid to map
+ *
+ * If both parameters are valid values, then a positive mapping in both
+ * directions is stored. If "is_null_sid(sid)" is true, then this will be a
+ * negative mapping of gid, we want to cache that for this gid we could not
+ * find anything. Likewise if "gid==-1", then we want to cache that we did not
+ * find a mapping for the sid passed here.
+ */
+
 void idmap_cache_set_sid2gid(const struct dom_sid *sid, gid_t gid)
 {
 	time_t now = time(NULL);