From: Andreas Schneider Date: Tue, 9 Dec 2008 12:18:06 +0000 (+0100) Subject: Move the doxygen comments of wbclient to the header file. X-Git-Tag: samba-4.0.0alpha6~479^2~38 X-Git-Url: http://git.samba.org/samba.git/?p=ira%2Fwip.git;a=commitdiff_plain;h=94c44fcb6b9c67d3fac39b290c05c718b2980443 Move the doxygen comments of wbclient to the header file. So that a developer who wants to use the wbclient api can read the documentation in the header file. Signed-off-by: Andreas Schneider Signed-off-by: Michael Adam --- diff --git a/source3/nsswitch/libwbclient/wbc_guid.c b/source3/nsswitch/libwbclient/wbc_guid.c index 0cb33e9868a..c343e24351f 100644 --- a/source3/nsswitch/libwbclient/wbc_guid.c +++ b/source3/nsswitch/libwbclient/wbc_guid.c @@ -24,14 +24,7 @@ #include "libwbclient.h" -/** @brief Convert a binary GUID to a character string - * - * @param guid Binary Guid - * @param **guid_string Resulting character string - * - * @return #wbcErr - **/ - +/* Convert a binary GUID to a character string */ wbcErr wbcGuidToString(const struct wbcGuid *guid, char **guid_string) { @@ -59,14 +52,7 @@ done: return wbc_status; } -/** @brief Convert a character string to a binary GUID - * - * @param *str Character string - * @param guid Resulting binary GUID - * - * @return #wbcErr - **/ - +/* @brief Convert a character string to a binary GUID */ wbcErr wbcStringToGuid(const char *str, struct wbcGuid *guid) { diff --git a/source3/nsswitch/libwbclient/wbc_idmap.c b/source3/nsswitch/libwbclient/wbc_idmap.c index 81b369c87cc..5b2ab875f62 100644 --- a/source3/nsswitch/libwbclient/wbc_idmap.c +++ b/source3/nsswitch/libwbclient/wbc_idmap.c @@ -24,15 +24,7 @@ #include "libwbclient.h" -/** @brief Convert a Windows SID to a Unix uid, allocating an uid if needed - * - * @param *sid Pointer to the domain SID to be resolved - * @param *puid Pointer to the resolved uid_t value - * - * @return #wbcErr - * - **/ - +/* Convert a Windows SID to a Unix uid, allocating an uid if needed */ wbcErr wbcSidToUid(const struct wbcDomainSid *sid, uid_t *puid) { struct winbindd_request request; @@ -71,30 +63,14 @@ wbcErr wbcSidToUid(const struct wbcDomainSid *sid, uid_t *puid) return wbc_status; } -/** @brief Convert a Windows SID to a Unix uid if there already is a mapping - * - * @param *sid Pointer to the domain SID to be resolved - * @param *puid Pointer to the resolved uid_t value - * - * @return #wbcErr - * - **/ - +/* Convert a Windows SID to a Unix uid if there already is a mapping */ wbcErr wbcQuerySidToUid(const struct wbcDomainSid *sid, uid_t *puid) { return WBC_ERR_NOT_IMPLEMENTED; } -/** @brief Convert a Unix uid to a Windows SID, allocating a SID if needed - * - * @param uid Unix uid to be resolved - * @param *sid Pointer to the resolved domain SID - * - * @return #wbcErr - * - **/ - +/* Convert a Unix uid to a Windows SID, allocating a SID if needed */ wbcErr wbcUidToSid(uid_t uid, struct wbcDomainSid *sid) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -127,15 +103,7 @@ done: return wbc_status; } -/** @brief Convert a Unix uid to a Windows SID if there already is a mapping - * - * @param uid Unix uid to be resolved - * @param *sid Pointer to the resolved domain SID - * - * @return #wbcErr - * - **/ - +/* Convert a Unix uid to a Windows SID if there already is a mapping */ wbcErr wbcQueryUidToSid(uid_t uid, struct wbcDomainSid *sid) { @@ -189,14 +157,7 @@ wbcErr wbcSidToGid(const struct wbcDomainSid *sid, gid_t *pgid) return wbc_status; } -/** @brief Convert a Windows SID to a Unix gid if there already is a mapping - * - * @param *sid Pointer to the domain SID to be resolved - * @param *pgid Pointer to the resolved gid_t value - * - * @return #wbcErr - * - **/ +/* Convert a Windows SID to a Unix gid if there already is a mapping */ wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid, gid_t *pgid) @@ -204,15 +165,7 @@ wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid, return WBC_ERR_NOT_IMPLEMENTED; } -/** @brief Convert a Unix gid to a Windows SID, allocating a SID if needed - * - * @param gid Unix gid to be resolved - * @param *sid Pointer to the resolved domain SID - * - * @return #wbcErr - * - **/ - +/* Convert a Unix gid to a Windows SID, allocating a SID if needed */ wbcErr wbcGidToSid(gid_t gid, struct wbcDomainSid *sid) { struct winbindd_request request; @@ -245,28 +198,14 @@ done: return wbc_status; } -/** @brief Convert a Unix gid to a Windows SID if there already is a mapping - * - * @param gid Unix gid to be resolved - * @param *sid Pointer to the resolved domain SID - * - * @return #wbcErr - * - **/ - +/* Convert a Unix gid to a Windows SID if there already is a mapping */ wbcErr wbcQueryGidToSid(gid_t gid, struct wbcDomainSid *sid) { return WBC_ERR_NOT_IMPLEMENTED; } -/** @brief Obtain a new uid from Winbind - * - * @param *puid *pointer to the allocated uid - * - * @return #wbcErr - **/ - +/* Obtain a new uid from Winbind */ wbcErr wbcAllocateUid(uid_t *puid) { struct winbindd_request request; @@ -296,13 +235,7 @@ wbcErr wbcAllocateUid(uid_t *puid) return wbc_status; } -/** @brief Obtain a new gid from Winbind - * - * @param *pgid Pointer to the allocated gid - * - * @return #wbcErr - **/ - +/* Obtain a new gid from Winbind */ wbcErr wbcAllocateGid(gid_t *pgid) { struct winbindd_request request; @@ -336,13 +269,7 @@ wbcErr wbcAllocateGid(gid_t *pgid) #define _ID_TYPE_UID 1 #define _ID_TYPE_GID 2 -/** @brief Set an user id mapping - * - * @param uid Uid of the desired mapping. - * @param *sid Pointer to the sid of the diresired mapping. - * - * @return #wbcErr - **/ +/* Set an user id mapping */ wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid) { struct winbindd_request request; @@ -379,13 +306,7 @@ wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid) return wbc_status; } -/** @brief Set a group id mapping - * - * @param gid Gid of the desired mapping. - * @param *sid Pointer to the sid of the diresired mapping. - * - * @return #wbcErr - **/ +/* Set a group id mapping */ wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid) { struct winbindd_request request; @@ -422,13 +343,7 @@ wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid) return wbc_status; } -/** @brief Remove a user id mapping - * - * @param uid Uid of the mapping to remove. - * @param *sid Pointer to the sid of the mapping to remove. - * - * @return #wbcErr - **/ +/* Remove a user id mapping */ wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid) { struct winbindd_request request; @@ -465,13 +380,7 @@ wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid) return wbc_status; } -/** @brief Remove a group id mapping - * - * @param gid Gid of the mapping to remove. - * @param *sid Pointer to the sid of the mapping to remove. - * - * @return #wbcErr - **/ +/* Remove a group id mapping */ wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid) { struct winbindd_request request; @@ -508,12 +417,7 @@ wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid) return wbc_status; } -/** @brief Set the highwater mark for allocated uids. - * - * @param uid_hwm The new uid highwater mark value - * - * @return #wbcErr - **/ +/* Set the highwater mark for allocated uids. */ wbcErr wbcSetUidHwm(uid_t uid_hwm) { struct winbindd_request request; @@ -538,12 +442,7 @@ wbcErr wbcSetUidHwm(uid_t uid_hwm) return wbc_status; } -/** @brief Set the highwater mark for allocated gids. - * - * @param gid_hwm The new gid highwater mark value - * - * @return #wbcErr - **/ +/* Set the highwater mark for allocated gids. */ wbcErr wbcSetGidHwm(gid_t gid_hwm) { struct winbindd_request request; diff --git a/source3/nsswitch/libwbclient/wbc_pam.c b/source3/nsswitch/libwbclient/wbc_pam.c index 401d2ad2c3f..92c66436317 100644 --- a/source3/nsswitch/libwbclient/wbc_pam.c +++ b/source3/nsswitch/libwbclient/wbc_pam.c @@ -24,14 +24,7 @@ #include "libwbclient.h" -/** @brief Authenticate a username/password pair - * - * @param username Name of user to authenticate - * @param password Clear text password os user - * - * @return #wbcErr - **/ - +/* Authenticate a username/password pair */ wbcErr wbcAuthenticateUser(const char *username, const char *password) { @@ -305,16 +298,7 @@ done: return wbc_status; } -/** @brief Authenticate with more detailed information - * - * @param params Input parameters, WBC_AUTH_USER_LEVEL_HASH - * is not supported yet - * @param info Output details on WBC_ERR_SUCCESS - * @param error Output details on WBC_ERR_AUTH_ERROR - * - * @return #wbcErr - **/ - +/* Authenticate with more detailed information */ wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params, struct wbcAuthUserInfo **info, struct wbcAuthErrorInfo **error) @@ -496,16 +480,7 @@ done: return wbc_status; } -/** @brief Trigger a verification of the trust credentials of a specific domain - * - * @param *domain The name of the domain, only NULL for the default domain is - * supported yet. Other values than NULL will result in - * WBC_ERR_NOT_IMPLEMENTED. - * @param error Output details on WBC_ERR_AUTH_ERROR - * - * @return #wbcErr - * - **/ +/* Trigger a verification of the trust credentials of a specific domain */ wbcErr wbcCheckTrustCredentials(const char *domain, struct wbcAuthErrorInfo **error) { @@ -547,15 +522,7 @@ wbcErr wbcCheckTrustCredentials(const char *domain, return wbc_status; } -/** @brief Trigger an extended logoff notification to Winbind for a specific user - * - * @param params A wbcLogoffUserParams structure - * @param error User output details on error - * - * @return #wbcErr - * - **/ - +/* Trigger an extended logoff notification to Winbind for a specific user */ wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params, struct wbcAuthErrorInfo **error) { @@ -642,18 +609,7 @@ wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params, return wbc_status; } -/** @brief Trigger a logoff notification to Winbind for a specific user - * - * @param username Name of user to remove from Winbind's list of - * logged on users. - * @param uid Uid assigned to the username - * @param ccfilename Absolute path to the Krb5 credentials cache to - * be removed - * - * @return #wbcErr - * - **/ - +/* Trigger a logoff notification to Winbind for a specific user */ wbcErr wbcLogoffUser(const char *username, uid_t uid, const char *ccfilename) @@ -693,16 +649,7 @@ wbcErr wbcLogoffUser(const char *username, return wbc_status; } -/** @brief Change a password for a user with more detailed information upon - * failure - * @param params Input parameters - * @param error User output details on WBC_ERR_PWD_CHANGE_FAILED - * @param reject_reason New password reject reason on WBC_ERR_PWD_CHANGE_FAILED - * @param policy Password policy output details on WBC_ERR_PWD_CHANGE_FAILED - * - * @return #wbcErr - **/ - +/* Change a password for a user with more detailed information upon failure */ wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params, struct wbcAuthErrorInfo **error, enum wbcPasswordChangeRejectReason *reject_reason, @@ -907,15 +854,7 @@ wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params, return wbc_status; } -/** @brief Change a password for a user - * - * @param username Name of user to authenticate - * @param old_password Old clear text password of user - * @param new_password New clear text password of user - * - * @return #wbcErr - **/ - +/* Change a password for a user */ wbcErr wbcChangeUserPassword(const char *username, const char *old_password, const char *new_password) @@ -940,17 +879,7 @@ done: return wbc_status; } -/** @brief Logon a User - * - * @param[in] params Pointer to a wbcLogonUserParams structure - * @param[out] info Pointer to a pointer to a wbcLogonUserInfo structure - * @param[out] error Pointer to a pointer to a wbcAuthErrorInfo structure - * @param[out] policy Pointer to a pointer to a wbcUserPasswordPolicyInfo structure - * - * @return #wbcErr - * - **/ - +/* Logon a User */ wbcErr wbcLogonUser(const struct wbcLogonUserParams *params, struct wbcLogonUserInfo **info, struct wbcAuthErrorInfo **error, @@ -1096,14 +1025,7 @@ done: return wbc_status; } -/** @brief Authenticate a user with cached credentials - * - * @param *params Pointer to a wbcCredentialCacheParams structure - * @param **info Pointer to a pointer to a wbcCredentialCacheInfo structure - * @param **error Pointer to a pointer to a wbcAuthErrorInfo structure - * - * @return #wbcErr - **/ +/* Authenticate a user with cached credentials */ wbcErr wbcCredentialCache(struct wbcCredentialCacheParams *params, struct wbcCredentialCacheInfo **info, struct wbcAuthErrorInfo **error) diff --git a/source3/nsswitch/libwbclient/wbc_pwd.c b/source3/nsswitch/libwbclient/wbc_pwd.c index d54a5af4fc5..cd945996c89 100644 --- a/source3/nsswitch/libwbclient/wbc_pwd.c +++ b/source3/nsswitch/libwbclient/wbc_pwd.c @@ -126,15 +126,7 @@ done: return grp; } -/** @brief Fill in a struct passwd* for a domain user based - * on username - * - * @param *name Username to lookup - * @param **pwd Pointer to resulting struct passwd* from the query. - * - * @return #wbcErr - **/ - +/* Fill in a struct passwd* for a domain user based on username */ wbcErr wbcGetpwnam(const char *name, struct passwd **pwd) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -167,15 +159,7 @@ wbcErr wbcGetpwnam(const char *name, struct passwd **pwd) return wbc_status; } -/** @brief Fill in a struct passwd* for a domain user based - * on uid - * - * @param uid Uid to lookup - * @param **pwd Pointer to resulting struct passwd* from the query. - * - * @return #wbcErr - **/ - +/* Fill in a struct passwd* for a domain user based on uid */ wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -206,15 +190,7 @@ wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd) return wbc_status; } -/** @brief Fill in a struct passwd* for a domain user based - * on username - * - * @param *name Username to lookup - * @param **grp Pointer to resulting struct group* from the query. - * - * @return #wbcErr - **/ - +/* Fill in a struct passwd* for a domain user based on username */ wbcErr wbcGetgrnam(const char *name, struct group **grp) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -251,15 +227,7 @@ wbcErr wbcGetgrnam(const char *name, struct group **grp) return wbc_status; } -/** @brief Fill in a struct passwd* for a domain user based - * on uid - * - * @param gid Uid to lookup - * @param **grp Pointer to resulting struct group* from the query. - * - * @return #wbcErr - **/ - +/* Fill in a struct passwd* for a domain user based on uid */ wbcErr wbcGetgrgid(gid_t gid, struct group **grp) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -309,11 +277,7 @@ static uint32_t pw_cache_idx; */ static struct winbindd_response pw_response; -/** @brief Reset the passwd iterator - * - * @return #wbcErr - **/ - +/* Reset the passwd iterator */ wbcErr wbcSetpwent(void) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -335,11 +299,7 @@ wbcErr wbcSetpwent(void) return wbc_status; } -/** @brief Close the passwd iterator - * - * @return #wbcErr - **/ - +/* Close the passwd iterator */ wbcErr wbcEndpwent(void) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -359,13 +319,7 @@ wbcErr wbcEndpwent(void) return wbc_status; } -/** @brief Return the next struct passwd* entry from the pwent iterator - * - * @param **pwd Pointer to resulting struct passwd* from the query. - * - * @return #wbcErr - **/ - +/* Return the next struct passwd* entry from the pwent iterator */ wbcErr wbcGetpwent(struct passwd **pwd) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -425,11 +379,7 @@ static uint32_t gr_cache_idx; */ static struct winbindd_response gr_response; -/** @brief Reset the group iterator - * - * @return #wbcErr - **/ - +/* Reset the group iterator */ wbcErr wbcSetgrent(void) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -451,11 +401,7 @@ wbcErr wbcSetgrent(void) return wbc_status; } -/** @brief Close the group iterator - * - * @return #wbcErr - **/ - +/* Close the group iterator */ wbcErr wbcEndgrent(void) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -475,13 +421,7 @@ wbcErr wbcEndgrent(void) return wbc_status; } -/** @brief Return the next struct group* entry from the pwent iterator - * - * @param **grp Pointer to resulting struct group* from the query. - * - * @return #wbcErr - **/ - +/* Return the next struct group* entry from the pwent iterator */ wbcErr wbcGetgrent(struct group **grp) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -531,15 +471,7 @@ done: return wbc_status; } -/** @brief Return the next struct group* entry from the pwent iterator - * - * This is similar to #wbcGetgrent, just that the member list is empty - * - * @param **grp Pointer to resulting struct group* from the query. - * - * @return #wbcErr - **/ - +/* Return the next struct group* entry from the pwent iterator */ wbcErr wbcGetgrlist(struct group **grp) { wbcErr wbc_status = WBC_ERR_UNKNOWN_FAILURE; @@ -584,14 +516,7 @@ done: return wbc_status; } -/** @brief Return the unix group array belonging to the given user - * - * @param *account The given user name - * @param *num_groups Number of elements returned in the groups array - * @param **_groups Pointer to resulting gid_t array. - * - * @return #wbcErr - **/ +/* Return the unix group array belonging to the given user */ wbcErr wbcGetGroups(const char *account, uint32_t *num_groups, gid_t **_groups) diff --git a/source3/nsswitch/libwbclient/wbc_sid.c b/source3/nsswitch/libwbclient/wbc_sid.c index 92de22e9019..e2157b96097 100644 --- a/source3/nsswitch/libwbclient/wbc_sid.c +++ b/source3/nsswitch/libwbclient/wbc_sid.c @@ -25,14 +25,7 @@ #include "libwbclient.h" -/** @brief Convert a binary SID to a character string - * - * @param sid Binary Security Identifier - * @param **sid_string Resulting character string - * - * @return #wbcErr - **/ - +/* Convert a binary SID to a character string */ wbcErr wbcSidToString(const struct wbcDomainSid *sid, char **sid_string) { @@ -73,14 +66,7 @@ done: return wbc_status; } -/** @brief Convert a character string to a binary SID - * - * @param *str Character string in the form of S-... - * @param sid Resulting binary SID - * - * @return #wbcErr - **/ - +/* Convert a character string to a binary SID */ wbcErr wbcStringToSid(const char *str, struct wbcDomainSid *sid) { @@ -163,17 +149,7 @@ done: } -/** @brief Convert a domain and name to SID - * - * @param domain Domain name (possibly "") - * @param name User or group name - * @param *sid Pointer to the resolved domain SID - * @param *name_type Pointer to the SID type - * - * @return #wbcErr - * - **/ - +/* Convert a domain and name to SID */ wbcErr wbcLookupName(const char *domain, const char *name, struct wbcDomainSid *sid, @@ -216,17 +192,7 @@ wbcErr wbcLookupName(const char *domain, return wbc_status; } -/** @brief Convert a SID to a domain and name - * - * @param *sid Pointer to the domain SID to be resolved - * @param pdomain Resolved Domain name (possibly "") - * @param pname Resolved User or group name - * @param *pname_type Pointer to the resolved SID type - * - * @return #wbcErr - * - **/ - +/* Convert a SID to a domain and name */ wbcErr wbcLookupSid(const struct wbcDomainSid *sid, char **pdomain, char **pname, @@ -310,9 +276,7 @@ wbcErr wbcLookupSid(const struct wbcDomainSid *sid, return wbc_status; } -/** @brief Translate a collection of RIDs within a domain to names - * - **/ +/* Translate a collection of RIDs within a domain to names */ wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid, int num_rids, @@ -448,10 +412,7 @@ wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid, return wbc_status; } -/** @brief Get the groups a user belongs to - * - **/ - +/* Get the groups a user belongs to */ wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid, bool domain_groups_only, uint32_t *num_sids, @@ -530,10 +491,7 @@ wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid, return wbc_status; } -/** @brief Lists Users - * - **/ - +/* Lists Users */ wbcErr wbcListUsers(const char *domain_name, uint32_t *_num_users, const char ***_users) @@ -601,10 +559,7 @@ wbcErr wbcListUsers(const char *domain_name, return wbc_status; } -/** @brief Lists Groups - * - **/ - +/* Lists Groups */ wbcErr wbcListGroups(const char *domain_name, uint32_t *_num_groups, const char ***_groups) diff --git a/source3/nsswitch/libwbclient/wbc_util.c b/source3/nsswitch/libwbclient/wbc_util.c index b4868748aec..7cfb64b87e9 100644 --- a/source3/nsswitch/libwbclient/wbc_util.c +++ b/source3/nsswitch/libwbclient/wbc_util.c @@ -119,16 +119,7 @@ done: } -/** @brief Lookup the current status of a trusted domain - * - * @param domain Domain to query - * @param *dinfo Pointer to returned domain_info struct - * - * @return #wbcErr - * - **/ - - +/* Lookup the current status of a trusted domain */ wbcErr wbcDomainInfo(const char *domain, struct wbcDomainInfo **dinfo) { struct winbindd_request request; @@ -189,14 +180,7 @@ wbcErr wbcDomainInfo(const char *domain, struct wbcDomainInfo **dinfo) } -/** @brief Resolve a NetbiosName via WINS - * - * @param name Name to resolve - * @param *ip Pointer to the ip address string - * - * @return #wbcErr - * - **/ +/* Resolve a NetbiosName via WINS */ wbcErr wbcResolveWinsByName(const char *name, char **ip) { struct winbindd_request request; @@ -229,14 +213,7 @@ wbcErr wbcResolveWinsByName(const char *name, char **ip) return wbc_status; } -/** @brief Resolve an IP address via WINS into a NetbiosName - * - * @param ip The ip address string - * @param *name Pointer to the name - * - * @return #wbcErr - * - **/ +/* Resolve an IP address via WINS into a NetbiosName */ wbcErr wbcResolveWinsByIP(const char *ip, char **name) { struct winbindd_request request; @@ -401,14 +378,7 @@ static wbcErr process_domain_info_string(TALLOC_CTX *ctx, return wbc_status; } -/** @brief Enumerate the domain trusts known by Winbind - * - * @param **domains Pointer to the allocated domain list array - * @param *num_domains Pointer to number of domains returned - * - * @return #wbcErr - * - **/ +/* Enumerate the domain trusts known by Winbind */ wbcErr wbcListTrusts(struct wbcDomainInfo **domains, size_t *num_domains) { struct winbindd_response response; @@ -493,18 +463,7 @@ wbcErr wbcListTrusts(struct wbcDomainInfo **domains, size_t *num_domains) return wbc_status; } -/** @brief Enumerate the domain trusts known by Winbind - * - * @param domain Name of the domain to query for a DC - * @param flags Bit flags used to control the domain location query - * @param *dc_info Pointer to the returned domain controller information - * - * @return #wbcErr - * - **/ - - - +/* Enumerate the domain trusts known by Winbind */ wbcErr wbcLookupDomainController(const char *domain, uint32_t flags, struct wbcDomainControllerInfo **dc_info) @@ -617,18 +576,7 @@ done: return wbc_status; } -/** @brief Get extended domain controller information - * - * @param domain Name of the domain to query for a DC - * @param guid Guid of the domain to query for a DC - * @param site Site of the domain to query for a DC - * @param flags Bit flags used to control the domain location query - * @param *dc_info Pointer to the returned extended domain controller information - * - * @return #wbcErr - * - **/ - +/* Get extended domain controller information */ wbcErr wbcLookupDomainControllerEx(const char *domain, struct wbcGuid *guid, const char *site, @@ -690,19 +638,7 @@ done: return wbc_status; } -/** @brief Initialize a named blob and add to list of blobs - * - * @param[in,out] num_blobs Pointer to the number of blobs - * @param[in,out] blobs Pointer to an array of blobs - * @param[in] name Name of the new named blob - * @param[in] flags Flags of the new named blob - * @param[in] data Blob data of new blob - * @param[in] length Blob data length of new blob - * - * @return #wbcErr - * - **/ - +/* Initialize a named blob and add to list of blobs */ wbcErr wbcAddNamedBlob(size_t *num_blobs, struct wbcNamedBlob **blobs, const char *name, diff --git a/source3/nsswitch/libwbclient/wbclient.c b/source3/nsswitch/libwbclient/wbclient.c index c0b7e0675aa..3a9afad15d4 100644 --- a/source3/nsswitch/libwbclient/wbclient.c +++ b/source3/nsswitch/libwbclient/wbclient.c @@ -123,13 +123,7 @@ const char *wbcErrorString(wbcErr error) return "unknown wbcErr value"; } -/** @brief Free library allocated memory - * - * @param *p Pointer to free - * - * @return void - **/ - +/* Free library allocated memory */ void wbcFreeMemory(void *p) { if (p) diff --git a/source3/nsswitch/libwbclient/wbclient.h b/source3/nsswitch/libwbclient/wbclient.h index cb31360407a..fcad3ff69bd 100644 --- a/source3/nsswitch/libwbclient/wbclient.h +++ b/source3/nsswitch/libwbclient/wbclient.h @@ -486,10 +486,17 @@ struct wbcDomainControllerInfoEx { const char *client_site_name; }; -/* +/********************************************************** * Memory Management - */ + **********************************************************/ +/** + * @brief Free library allocated memory + * + * @param *p Pointer to free + * + * @return void + **/ void wbcFreeMemory(void*); @@ -497,9 +504,25 @@ void wbcFreeMemory(void*); * Utility functions for dealing with SIDs */ +/** + * @brief Convert a binary SID to a character string + * + * @param sid Binary Security Identifier + * @param **sid_string Resulting character string + * + * @return #wbcErr + **/ wbcErr wbcSidToString(const struct wbcDomainSid *sid, char **sid_string); +/** + * @brief Convert a character string to a binary SID + * + * @param *str Character string in the form of S-... + * @param sid Resulting binary SID + * + * @return #wbcErr + **/ wbcErr wbcStringToSid(const char *sid_string, struct wbcDomainSid *sid); @@ -507,32 +530,76 @@ wbcErr wbcStringToSid(const char *sid_string, * Utility functions for dealing with GUIDs */ +/** + * @brief Convert a binary GUID to a character string + * + * @param guid Binary Guid + * @param **guid_string Resulting character string + * + * @return #wbcErr + **/ wbcErr wbcGuidToString(const struct wbcGuid *guid, char **guid_string); +/** + * @brief Convert a character string to a binary GUID + * + * @param *str Character string + * @param guid Resulting binary GUID + * + * @return #wbcErr + **/ wbcErr wbcStringToGuid(const char *guid_string, struct wbcGuid *guid); +/** + * @brief Ping winbindd to see if the daemon is running + * + * @return #wbcErr + **/ wbcErr wbcPing(void); wbcErr wbcLibraryDetails(struct wbcLibraryDetails **details); wbcErr wbcInterfaceDetails(struct wbcInterfaceDetails **details); -/* +/********************************************************** * Name/SID conversion - */ + **********************************************************/ +/** + * @brief Convert a domain and name to SID + * + * @param domain Domain name (possibly "") + * @param name User or group name + * @param *sid Pointer to the resolved domain SID + * @param *name_type Pointer to the SID type + * + * @return #wbcErr + **/ wbcErr wbcLookupName(const char *dom_name, const char *name, struct wbcDomainSid *sid, enum wbcSidType *name_type); +/** + * @brief Convert a SID to a domain and name + * + * @param *sid Pointer to the domain SID to be resolved + * @param pdomain Resolved Domain name (possibly "") + * @param pname Resolved User or group name + * @param *pname_type Pointer to the resolved SID type + * + * @return #wbcErr + **/ wbcErr wbcLookupSid(const struct wbcDomainSid *sid, char **domain, char **name, enum wbcSidType *name_type); +/** + * @brief Translate a collection of RIDs within a domain to names + */ wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid, int num_rids, uint32_t *rids, @@ -540,15 +607,24 @@ wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid, const char ***names, enum wbcSidType **types); +/* + * @brief Get the groups a user belongs to + **/ wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid, bool domain_groups_only, uint32_t *num_sids, struct wbcDomainSid **sids); +/** + * @brief Lists Users + **/ wbcErr wbcListUsers(const char *domain_name, uint32_t *num_users, const char ***users); +/** + * @brief Lists Groups + **/ wbcErr wbcListGroups(const char *domain_name, uint32_t *num_groups, const char ***groups); @@ -558,88 +634,324 @@ wbcErr wbcGetDisplayName(const struct wbcDomainSid *sid, char **pfullname, enum wbcSidType *pname_type); -/* +/********************************************************** * SID/uid/gid Mappings - */ + **********************************************************/ +/** + * @brief Convert a Windows SID to a Unix uid, allocating an uid if needed + * + * @param *sid Pointer to the domain SID to be resolved + * @param *puid Pointer to the resolved uid_t value + * + * @return #wbcErr + * + **/ wbcErr wbcSidToUid(const struct wbcDomainSid *sid, uid_t *puid); +/** + * @brief Convert a Windows SID to a Unix uid if there already is a mapping + * + * @param *sid Pointer to the domain SID to be resolved + * @param *puid Pointer to the resolved uid_t value + * + * @return #wbcErr + * + **/ wbcErr wbcQuerySidToUid(const struct wbcDomainSid *sid, uid_t *puid); +/** + * @brief Convert a Unix uid to a Windows SID, allocating a SID if needed + * + * @param uid Unix uid to be resolved + * @param *sid Pointer to the resolved domain SID + * + * @return #wbcErr + * + **/ wbcErr wbcUidToSid(uid_t uid, struct wbcDomainSid *sid); +/** + * @brief Convert a Unix uid to a Windows SID if there already is a mapping + * + * @param uid Unix uid to be resolved + * @param *sid Pointer to the resolved domain SID + * + * @return #wbcErr + * + **/ wbcErr wbcQueryUidToSid(uid_t uid, struct wbcDomainSid *sid); +/** + * @brief Convert a Windows SID to a Unix gid, allocating a gid if needed + * + * @param *sid Pointer to the domain SID to be resolved + * @param *pgid Pointer to the resolved gid_t value + * + * @return #wbcErr + * + **/ wbcErr wbcSidToGid(const struct wbcDomainSid *sid, gid_t *pgid); +/** + * @brief Convert a Windows SID to a Unix gid if there already is a mapping + * + * @param *sid Pointer to the domain SID to be resolved + * @param *pgid Pointer to the resolved gid_t value + * + * @return #wbcErr + * + **/ wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid, gid_t *pgid); +/** + * @brief Convert a Unix gid to a Windows SID, allocating a SID if needed + * + * @param gid Unix gid to be resolved + * @param *sid Pointer to the resolved domain SID + * + * @return #wbcErr + * + **/ wbcErr wbcGidToSid(gid_t gid, struct wbcDomainSid *sid); +/** + * @brief Convert a Unix gid to a Windows SID if there already is a mapping + * + * @param gid Unix gid to be resolved + * @param *sid Pointer to the resolved domain SID + * + * @return #wbcErr + * + **/ wbcErr wbcQueryGidToSid(gid_t gid, struct wbcDomainSid *sid); +/** + * @brief Obtain a new uid from Winbind + * + * @param *puid *pointer to the allocated uid + * + * @return #wbcErr + **/ wbcErr wbcAllocateUid(uid_t *puid); +/** + * @brief Obtain a new gid from Winbind + * + * @param *pgid Pointer to the allocated gid + * + * @return #wbcErr + **/ wbcErr wbcAllocateGid(gid_t *pgid); +/** + * @brief Set an user id mapping + * + * @param uid Uid of the desired mapping. + * @param *sid Pointer to the sid of the diresired mapping. + * + * @return #wbcErr + **/ wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid); +/** + * @brief Set a group id mapping + * + * @param gid Gid of the desired mapping. + * @param *sid Pointer to the sid of the diresired mapping. + * + * @return #wbcErr + **/ wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid); +/** + * @brief Remove a user id mapping + * + * @param uid Uid of the mapping to remove. + * @param *sid Pointer to the sid of the mapping to remove. + * + * @return #wbcErr + **/ wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid); +/** + * @brief Remove a group id mapping + * + * @param gid Gid of the mapping to remove. + * @param *sid Pointer to the sid of the mapping to remove. + * + * @return #wbcErr + **/ wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid); +/** + * @brief Set the highwater mark for allocated uids. + * + * @param uid_hwm The new uid highwater mark value + * + * @return #wbcErr + **/ wbcErr wbcSetUidHwm(uid_t uid_hwm); +/** + * @brief Set the highwater mark for allocated gids. + * + * @param gid_hwm The new gid highwater mark value + * + * @return #wbcErr + **/ wbcErr wbcSetGidHwm(gid_t gid_hwm); -/* +/********************************************************** * NSS Lookup User/Group details - */ + **********************************************************/ +/** + * @brief Fill in a struct passwd* for a domain user based + * on username + * + * @param *name Username to lookup + * @param **pwd Pointer to resulting struct passwd* from the query. + * + * @return #wbcErr + **/ wbcErr wbcGetpwnam(const char *name, struct passwd **pwd); +/** + * @brief Fill in a struct passwd* for a domain user based + * on uid + * + * @param uid Uid to lookup + * @param **pwd Pointer to resulting struct passwd* from the query. + * + * @return #wbcErr + **/ wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd); +/** + * @brief Fill in a struct passwd* for a domain user based + * on username + * + * @param *name Username to lookup + * @param **grp Pointer to resulting struct group* from the query. + * + * @return #wbcErr + **/ wbcErr wbcGetgrnam(const char *name, struct group **grp); +/** + * @brief Fill in a struct passwd* for a domain user based + * on uid + * + * @param gid Uid to lookup + * @param **grp Pointer to resulting struct group* from the query. + * + * @return #wbcErr + **/ wbcErr wbcGetgrgid(gid_t gid, struct group **grp); +/** + * @brief Reset the passwd iterator + * + * @return #wbcErr + **/ wbcErr wbcSetpwent(void); +/** + * @brief Close the passwd iterator + * + * @return #wbcErr + **/ wbcErr wbcEndpwent(void); +/** + * @brief Return the next struct passwd* entry from the pwent iterator + * + * @param **pwd Pointer to resulting struct passwd* from the query. + * + * @return #wbcErr + **/ wbcErr wbcGetpwent(struct passwd **pwd); +/** + * @brief Reset the group iterator + * + * @return #wbcErr + **/ wbcErr wbcSetgrent(void); +/** + * @brief Close the group iterator + * + * @return #wbcErr + **/ wbcErr wbcEndgrent(void); +/** + * @brief Return the next struct group* entry from the pwent iterator + * + * @param **grp Pointer to resulting struct group* from the query. + * + * @return #wbcErr + **/ wbcErr wbcGetgrent(struct group **grp); +/** + * @brief Return the next struct group* entry from the pwent iterator + * + * This is similar to #wbcGetgrent, just that the member list is empty + * + * @param **grp Pointer to resulting struct group* from the query. + * + * @return #wbcErr + **/ wbcErr wbcGetgrlist(struct group **grp); +/** + * @brief Return the unix group array belonging to the given user + * + * @param *account The given user name + * @param *num_groups Number of elements returned in the groups array + * @param **_groups Pointer to resulting gid_t array. + * + * @return #wbcErr + **/ wbcErr wbcGetGroups(const char *account, uint32_t *num_groups, gid_t **_groups); -/* +/********************************************************** * Lookup Domain information - */ + **********************************************************/ +/** + * @brief Lookup the current status of a trusted domain + * + * @param domain Domain to query + * @param *dinfo Pointer to returned domain_info struct + * + * @return #wbcErr + **/ wbcErr wbcDomainInfo(const char *domain, struct wbcDomainInfo **info); +/** + * @brief Enumerate the domain trusts known by Winbind + * + * @param **domains Pointer to the allocated domain list array + * @param *num_domains Pointer to number of domains returned + * + * @return #wbcErr + **/ wbcErr wbcListTrusts(struct wbcDomainInfo **domains, size_t *num_domains); @@ -665,66 +977,206 @@ wbcErr wbcListTrusts(struct wbcDomainInfo **domains, #define WBC_LOOKUP_DC_RETURN_DNS_NAME 0x40000000 #define WBC_LOOKUP_DC_RETURN_FLAT_NAME 0x80000000 +/** + * @brief Enumerate the domain trusts known by Winbind + * + * @param domain Name of the domain to query for a DC + * @param flags Bit flags used to control the domain location query + * @param *dc_info Pointer to the returned domain controller information + * + * @return #wbcErr + **/ wbcErr wbcLookupDomainController(const char *domain, uint32_t flags, struct wbcDomainControllerInfo **dc_info); +/** + * @brief Get extended domain controller information + * + * @param domain Name of the domain to query for a DC + * @param guid Guid of the domain to query for a DC + * @param site Site of the domain to query for a DC + * @param flags Bit flags used to control the domain location query + * @param *dc_info Pointer to the returned extended domain controller information + * + * @return #wbcErr + **/ wbcErr wbcLookupDomainControllerEx(const char *domain, struct wbcGuid *guid, const char *site, uint32_t flags, struct wbcDomainControllerInfoEx **dc_info); -/* +/********************************************************** * Athenticate functions - */ + **********************************************************/ +/** + * @brief Authenticate a username/password pair + * + * @param username Name of user to authenticate + * @param password Clear text password os user + * + * @return #wbcErr + **/ wbcErr wbcAuthenticateUser(const char *username, const char *password); +/** + * @brief Authenticate with more detailed information + * + * @param params Input parameters, WBC_AUTH_USER_LEVEL_HASH + * is not supported yet + * @param info Output details on WBC_ERR_SUCCESS + * @param error Output details on WBC_ERR_AUTH_ERROR + * + * @return #wbcErr + **/ wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params, struct wbcAuthUserInfo **info, struct wbcAuthErrorInfo **error); +/** + * @brief Logon a User + * + * @param[in] params Pointer to a wbcLogonUserParams structure + * @param[out] info Pointer to a pointer to a wbcLogonUserInfo structure + * @param[out] error Pointer to a pointer to a wbcAuthErrorInfo structure + * @param[out] policy Pointer to a pointer to a wbcUserPasswordPolicyInfo structure + * + * @return #wbcErr + **/ wbcErr wbcLogonUser(const struct wbcLogonUserParams *params, struct wbcLogonUserInfo **info, struct wbcAuthErrorInfo **error, struct wbcUserPasswordPolicyInfo **policy); +/** + * @brief Trigger a logoff notification to Winbind for a specific user + * + * @param username Name of user to remove from Winbind's list of + * logged on users. + * @param uid Uid assigned to the username + * @param ccfilename Absolute path to the Krb5 credentials cache to + * be removed + * + * @return #wbcErr + **/ wbcErr wbcLogoffUser(const char *username, uid_t uid, const char *ccfilename); +/** + * @brief Trigger an extended logoff notification to Winbind for a specific user + * + * @param params A wbcLogoffUserParams structure + * @param error User output details on error + * + * @return #wbcErr + **/ wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params, struct wbcAuthErrorInfo **error); +/** + * @brief Change a password for a user + * + * @param username Name of user to authenticate + * @param old_password Old clear text password of user + * @param new_password New clear text password of user + * + * @return #wbcErr + **/ wbcErr wbcChangeUserPassword(const char *username, const char *old_password, const char *new_password); +/** + * @brief Change a password for a user with more detailed information upon + * failure + * + * @param params Input parameters + * @param error User output details on WBC_ERR_PWD_CHANGE_FAILED + * @param reject_reason New password reject reason on WBC_ERR_PWD_CHANGE_FAILED + * @param policy Password policy output details on WBC_ERR_PWD_CHANGE_FAILED + * + * @return #wbcErr + **/ wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params, struct wbcAuthErrorInfo **error, enum wbcPasswordChangeRejectReason *reject_reason, struct wbcUserPasswordPolicyInfo **policy); +/** + * @brief Authenticate a user with cached credentials + * + * @param *params Pointer to a wbcCredentialCacheParams structure + * @param **info Pointer to a pointer to a wbcCredentialCacheInfo structure + * @param **error Pointer to a pointer to a wbcAuthErrorInfo structure + * + * @return #wbcErr + **/ wbcErr wbcCredentialCache(struct wbcCredentialCacheParams *params, struct wbcCredentialCacheInfo **info, struct wbcAuthErrorInfo **error); -/* +/********************************************************** * Resolve functions - */ + **********************************************************/ + +/** + * @brief Resolve a NetbiosName via WINS + * + * @param name Name to resolve + * @param *ip Pointer to the ip address string + * + * @return #wbcErr + **/ wbcErr wbcResolveWinsByName(const char *name, char **ip); + +/** + * @brief Resolve an IP address via WINS into a NetbiosName + * + * @param ip The ip address string + * @param *name Pointer to the name + * + * @return #wbcErr + * + **/ wbcErr wbcResolveWinsByIP(const char *ip, char **name); -/* +/********************************************************** * Trusted domain functions - */ + **********************************************************/ + +/** + * @brief Trigger a verification of the trust credentials of a specific domain + * + * @param *domain The name of the domain, only NULL for the default domain is + * supported yet. Other values than NULL will result in + * WBC_ERR_NOT_IMPLEMENTED. + * @param error Output details on WBC_ERR_AUTH_ERROR + * + * @return #wbcErr + **/ wbcErr wbcCheckTrustCredentials(const char *domain, struct wbcAuthErrorInfo **error); -/* + +/********************************************************** * Helper functions - */ + **********************************************************/ + +/** + * @brief Initialize a named blob and add to list of blobs + * + * @param[in,out] num_blobs Pointer to the number of blobs + * @param[in,out] blobs Pointer to an array of blobs + * @param[in] name Name of the new named blob + * @param[in] flags Flags of the new named blob + * @param[in] data Blob data of new blob + * @param[in] length Blob data length of new blob + * + * @return #wbcErr + **/ wbcErr wbcAddNamedBlob(size_t *num_blobs, struct wbcNamedBlob **blobs, const char *name,