From 548d08884b95b46dae4e4de8bc5be515a5aee689 Mon Sep 17 00:00:00 2001 From: Hans Leidekker Date: Fri, 2 Dec 2005 11:26:19 +0100 Subject: [PATCH] Document DN and error handling functions. Try to stick to Wine's documentation format. --- dlls/wldap32/add.c | 8 ++-- dlls/wldap32/bind.c | 18 ++++----- dlls/wldap32/compare.c | 8 ++-- dlls/wldap32/control.c | 14 +++---- dlls/wldap32/delete.c | 8 ++-- dlls/wldap32/dn.c | 84 ++++++++++++++++++++++++++++++++++++++++++ dlls/wldap32/error.c | 76 +++++++++++++++++++++++++++++++++++++- 7 files changed, 186 insertions(+), 30 deletions(-) diff --git a/dlls/wldap32/add.c b/dlls/wldap32/add.c index 040f5bb5b89..87cae0ff690 100644 --- a/dlls/wldap32/add.c +++ b/dlls/wldap32/add.c @@ -83,7 +83,7 @@ exit: * * Add an entry to a directory tree (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of the entry to add. * attrs [I] Pointer to an array of LDAPModW structures, each @@ -191,7 +191,7 @@ exit: * * Add an entry to a directory tree (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of the entry to add. * attrs [I] Pointer to an array of LDAPModW structures, each @@ -311,7 +311,7 @@ exit: * * Add an entry to a directory tree (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of the entry to add. * attrs [I] Pointer to an array of LDAPModW structures, each @@ -416,7 +416,7 @@ exit: * * Add an entry to a directory tree (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of the entry to add. * attrs [I] Pointer to an array of LDAPModW structures, each diff --git a/dlls/wldap32/bind.c b/dlls/wldap32/bind.c index 9d68fa1d2a0..a11729ebcec 100644 --- a/dlls/wldap32/bind.c +++ b/dlls/wldap32/bind.c @@ -82,7 +82,7 @@ exit: * * Authenticate with an LDAP server (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to bind as. * cred [I] Credentials (e.g. password string). @@ -93,7 +93,7 @@ exit: * Failure: An LDAP error code. * * NOTES - * Only LDAP_AUTH_SIMPLE is supported. + * Only LDAP_AUTH_SIMPLE is supported (just like native). */ ULONG ldap_bindW( WLDAP32_LDAP *ld, PWCHAR dn, PWCHAR cred, ULONG method ) { @@ -178,7 +178,7 @@ exit: * * Authenticate with an LDAP server (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to bind as. * cred [I] Credentials (e.g. password string). @@ -278,7 +278,7 @@ exit: * * Authenticate with an LDAP server using SASL (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to bind as. * mechanism [I] Authentication method. @@ -394,7 +394,7 @@ exit: * * Authenticate with an LDAP server using SASL (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to bind as. * mechanism [I] Authentication method. @@ -497,7 +497,7 @@ exit: * * Authenticate with an LDAP server (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to bind as. * passwd [I] Password string. @@ -591,7 +591,7 @@ exit: * * Authenticate with an LDAP server (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to bind as. * passwd [I] Password string. @@ -643,7 +643,7 @@ exit: * * Close LDAP connection and free resources (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * * RETURNS @@ -671,7 +671,7 @@ ULONG WLDAP32_ldap_unbind( WLDAP32_LDAP *ld ) * * Close LDAP connection and free resources (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * * RETURNS diff --git a/dlls/wldap32/compare.c b/dlls/wldap32/compare.c index 7a1464145dc..e381a2a8c66 100644 --- a/dlls/wldap32/compare.c +++ b/dlls/wldap32/compare.c @@ -87,7 +87,7 @@ exit: * * Check if an attribute has a certain value (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to compare value for. * attr [I] Attribute to compare value for. @@ -206,7 +206,7 @@ exit: * * Check if an attribute has a certain value (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to compare value for. * attr [I] Attribute to compare value for. @@ -345,7 +345,7 @@ exit: * * Check if an attribute has a certain value (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to compare value for. * attr [I] Attribute to compare value for. @@ -468,7 +468,7 @@ exit: * * Check if an attribute has a certain value (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of entry to compare value for. * attr [I] Attribute to compare value for. diff --git a/dlls/wldap32/control.c b/dlls/wldap32/control.c index e946e95ed5d..35f2298a08c 100644 --- a/dlls/wldap32/control.c +++ b/dlls/wldap32/control.c @@ -63,7 +63,7 @@ ULONG ldap_control_freeA( LDAPControlA *control ) * * Free an LDAPControl structure. * - * Parameters + * PARAMS * control [I] LDAPControl structure to free. * * RETURNS @@ -103,7 +103,7 @@ ULONG ldap_controls_freeA( LDAPControlA **controls ) * * Free an array of LDAPControl structures. * - * Parameters + * PARAMS * controls [I] Array of LDAPControl structures to free. * * RETURNS @@ -139,7 +139,7 @@ ULONG ldap_create_page_controlA( WLDAP32_LDAP *ld, ULONG pagesize, * * Create a control for paged search results. * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * pagesize [I] Number of entries to return per page. * cookie [I] Used by the server to track its location in the @@ -202,7 +202,7 @@ ULONG ldap_create_sort_controlA( WLDAP32_LDAP *ld, PLDAPSortKeyA *sortkey, * * Create a control for server sorted search results. * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * sortkey [I] Array of LDAPSortKey structures, each specifying an * attribute to use as a sort key, a matching rule and @@ -277,7 +277,7 @@ INT ldap_create_vlv_controlA( WLDAP32_LDAP *ld, WLDAP32_LDAPVLVInfo *info, * * Create a virtual list view control. * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * info [I] LDAPVLVInfo structure specifying a list view window. * critical [I] Tells the server this control is critical to the @@ -330,7 +330,7 @@ ULONG ldap_encode_sort_controlA( WLDAP32_LDAP *ld, PLDAPSortKeyA *sortkeys, * * Create a control for server sorted search results. * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * sortkey [I] Array of LDAPSortKey structures, each specifying an * attribute to use as a sort key, a matching rule and @@ -368,7 +368,7 @@ ULONG ldap_free_controlsA( LDAPControlA **controls ) * * Free an array of LDAPControl structures. * - * Parameters + * PARAMS * controls [I] Array of LDAPControl structures to free. * * RETURNS diff --git a/dlls/wldap32/delete.c b/dlls/wldap32/delete.c index f9d95f4e909..e6d5740fb81 100644 --- a/dlls/wldap32/delete.c +++ b/dlls/wldap32/delete.c @@ -72,7 +72,7 @@ ULONG ldap_deleteA( WLDAP32_LDAP *ld, PCHAR dn ) * * Delete an entry from a directory tree (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of the entry to delete. * @@ -163,7 +163,7 @@ exit: * * Delete an entry from a directory tree (asynchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of the entry to delete. * serverctrls [I] Array of LDAP server controls. @@ -267,7 +267,7 @@ exit: * * Delete an entry from a directory tree (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of the entry to delete. * serverctrls [I] Array of LDAP server controls. @@ -350,7 +350,7 @@ ULONG ldap_delete_sA( WLDAP32_LDAP *ld, PCHAR dn ) * * Delete an entry from a directory tree (synchronous operation). * - * Parameters + * PARAMS * ld [I] Pointer to an LDAP context. * dn [I] DN of the entry to delete. * diff --git a/dlls/wldap32/dn.c b/dlls/wldap32/dn.c index 5be63e7d264..c935c0a2613 100644 --- a/dlls/wldap32/dn.c +++ b/dlls/wldap32/dn.c @@ -40,6 +40,11 @@ WINE_DEFAULT_DEBUG_CHANNEL(wldap32); +/*********************************************************************** + * ldap_dn2ufnA (WLDAP32.@) + * + * See ldap_dn2ufnW. + */ PCHAR ldap_dn2ufnA( PCHAR dn ) { PCHAR ret = NULL; @@ -61,6 +66,21 @@ PCHAR ldap_dn2ufnA( PCHAR dn ) return ret; } +/*********************************************************************** + * ldap_dn2ufnW (WLDAP32.@) + * + * Convert a DN to a user-friendly name. + * + * PARAMS + * dn [I] DN to convert. + * + * RETURNS + * Success: Pointer to a string containing the user-friendly name. + * Failure: NULL + * + * NOTES + * Free the string with ldap_memfree. + */ PWCHAR ldap_dn2ufnW( PWCHAR dn ) { PWCHAR ret = NULL; @@ -82,6 +102,11 @@ PWCHAR ldap_dn2ufnW( PWCHAR dn ) return ret; } +/*********************************************************************** + * ldap_explode_dnA (WLDAP32.@) + * + * See ldap_explode_dnW. + */ PCHAR *ldap_explode_dnA( PCHAR dn, ULONG notypes ) { PCHAR *ret = NULL; @@ -103,6 +128,23 @@ PCHAR *ldap_explode_dnA( PCHAR dn, ULONG notypes ) return ret; } +/*********************************************************************** + * ldap_explode_dnW (WLDAP32.@) + * + * Break up a DN into its components. + * + * PARAMS + * dn [I] DN to break up. + * notypes [I] Remove attribute type information from the components. + * + * RETURNS + * Success: Pointer to a NULL-terminated array that contains the DN + * components. + * Failure: NULL + * + * NOTES + * Free the string array with ldap_value_free. + */ PWCHAR *ldap_explode_dnW( PWCHAR dn, ULONG notypes ) { PWCHAR *ret = NULL; @@ -124,6 +166,11 @@ PWCHAR *ldap_explode_dnW( PWCHAR dn, ULONG notypes ) return ret; } +/*********************************************************************** + * ldap_get_dnA (WLDAP32.@) + * + * See ldap_get_dnW. + */ PCHAR ldap_get_dnA( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *entry ) { PCHAR ret = NULL; @@ -143,6 +190,22 @@ PCHAR ldap_get_dnA( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *entry ) return ret; } +/*********************************************************************** + * ldap_get_dnW (WLDAP32.@) + * + * Retrieve the DN from a given LDAP message. + * + * PARAMS + * ld [I] Pointer to an LDAP context. + * entry [I] LDAPMessage structure to retrieve the DN from. + * + * RETURNS + * Success: Pointer to a string that contains the DN. + * Failure: NULL + * + * NOTES + * Free the string with ldap_memfree. + */ PWCHAR ldap_get_dnW( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *entry ) { PWCHAR ret = NULL; @@ -162,6 +225,11 @@ PWCHAR ldap_get_dnW( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *entry ) return ret; } +/*********************************************************************** + * ldap_ufn2dnA (WLDAP32.@) + * + * See ldap_ufn2dnW. + */ ULONG ldap_ufn2dnA( PCHAR ufn, PCHAR *dn ) { ULONG ret = LDAP_SUCCESS; @@ -193,6 +261,22 @@ ULONG ldap_ufn2dnA( PCHAR ufn, PCHAR *dn ) return ret; } +/*********************************************************************** + * ldap_ufn2dnW (WLDAP32.@) + * + * Convert a user-friendly name to a DN. + * + * PARAMS + * ufn [I] User-friendly name to convert. + * dn [O] Receives a pointer to a string containing the DN. + * + * RETURNS + * Success: LDAP_SUCCESS + * Failure: An LDAP error code. + * + * NOTES + * Free the string with ldap_memfree. + */ ULONG ldap_ufn2dnW( PWCHAR ufn, PWCHAR *dn ) { ULONG ret = LDAP_SUCCESS; diff --git a/dlls/wldap32/error.c b/dlls/wldap32/error.c index 240c6eade25..265a99b6d6b 100644 --- a/dlls/wldap32/error.c +++ b/dlls/wldap32/error.c @@ -44,6 +44,11 @@ extern HINSTANCE hwldap32; WINE_DEFAULT_DEBUG_CHANNEL(wldap32); +/*********************************************************************** + * ldap_err2stringA (WLDAP32.@) + * + * See ldap_err2stringW. + */ PCHAR ldap_err2stringA( ULONG err ) { static char buf[256] = ""; @@ -58,6 +63,22 @@ PCHAR ldap_err2stringA( ULONG err ) return buf; } +/*********************************************************************** + * ldap_err2stringW (WLDAP32.@) + * + * Convert an error code into a string describing the error. + * + * PARAMS + * err [I] Error code to convert. + * + * RETURNS + * Success: Pointer to a string containing the error description. + * Failure: NULL + * + * NOTES + * The returned string is statically allocated, you must not + * free this string. + */ PWCHAR ldap_err2stringW( ULONG err ) { static WCHAR buf[256] = { 0 }; @@ -72,14 +93,43 @@ PWCHAR ldap_err2stringW( ULONG err ) return buf; } -/* - * NOTES: does nothing +/*********************************************************************** + * ldap_perror (WLDAP32.@) + * + * Print a given error string. + * + * PARAMS + * ld [I] Pointer to an LDAP context. + * msg [I] Error string. + * + * RETURNS + * Nothing. + * + * NOTES + * Like native, this function does nothing. */ void WLDAP32_ldap_perror( WLDAP32_LDAP *ld, const PCHAR msg ) { TRACE( "(%p, %s)\n", ld, debugstr_a(msg) ); } +/*********************************************************************** + * ldap_result2error (WLDAP32.@) + * + * Parse an LDAP message and return the error obtained from it. + * + * PARAMS + * ld [I] Pointer to an LDAP context. + * res [I] Pointer to an LDAPMessage structure. + * free [I] Ask for the LDAPMessage structure to be freed. + * + * RETURNS + * Success: LDAP_SUCCESS + * Failure: An LDAP error code. + * + * NOTES + * If not asked for, use ldap_msgfree to free the LDAPMessage. + */ ULONG WLDAP32_ldap_result2error( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *res, ULONG free ) { ULONG ret = LDAP_NOT_SUPPORTED; @@ -101,6 +151,17 @@ ULONG WLDAP32_ldap_result2error( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *res, ULO return ret; } +/*********************************************************************** + * LdapGetLastError (WLDAP32.@) + * + * Return the last error set by an LDAP function call. + * + * PARAMS + * None. + * + * RETURNS + * An LDAP error code. + */ ULONG LdapGetLastError( void ) { TRACE( "\n" ); @@ -208,6 +269,17 @@ static const ULONG WLDAP32_errormap[] = { /* LDAP_REFERRAL_LIMIT_EXCEEDED */ ERROR_DS_GENERIC_ERROR }; +/*********************************************************************** + * LdapMapErrorToWin32 (WLDAP32.@) + * + * Map an LDAP error code to a Win32 error code. + * + * PARAMS + * err [I] An LDAP error code. + * + * RETURNS + * A Win32 error code. + */ ULONG LdapMapErrorToWin32( ULONG err ) { TRACE( "(0x%08lx)\n", err );