Document DN and error handling functions.

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

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

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.

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

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.
  *

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;

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 );