Hans Leidekker : wldap32: Document ldap_{get, set}_option and the parsing functions.

[Alexandre Julliard]

Module: wine
Branch: master
Commit: 9744cdbc2279b3079cca5c01981a025f375620e5
URL:    http://source.winehq.org/git/?p=wine.git;a=commit;h=9744cdbc2279b3079cca5c01...

Author: Hans Leidekker <hans(a)it.vu.nl>
Date:   Wed Aug 16 12:53:09 2006 +0200

wldap32: Document ldap_{get,set}_option and the parsing functions.

---

 dlls/wldap32/option.c |   41 ++++++++++++++++
 dlls/wldap32/parse.c  |  125 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 166 insertions(+), 0 deletions(-)

diff --git a/dlls/wldap32/option.c b/dlls/wldap32/option.c
index 1b2ca78..d5206f5 100644
--- a/dlls/wldap32/option.c
+++ b/dlls/wldap32/option.c
@@ -40,6 +40,11 @@ #include "wldap32.h"
 
 WINE_DEFAULT_DEBUG_CHANNEL(wldap32);
 
+/***********************************************************************
+ *      ldap_get_optionA     (WLDAP32.@)
+ *
+ * See ldap_get_optionW.
+ */
 ULONG CDECL ldap_get_optionA( WLDAP32_LDAP *ld, int option, void *value )
 {
     ULONG ret = LDAP_NOT_SUPPORTED;
@@ -164,6 +169,20 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_get_optionW     (WLDAP32.@)
+ *
+ * Retrieve option values for a given LDAP context.
+ *
+ * PARAMS
+ *  ld      [I] Pointer to an LDAP context.
+ *  option  [I] Option to get values for.
+ *  value   [O] Pointer to option values.
+ *
+ * RETURNS
+ *  Success: LDAP_SUCCESS
+ *  Failure: An LDAP error code.
+ */
 ULONG CDECL ldap_get_optionW( WLDAP32_LDAP *ld, int option, void *value )
 {
     ULONG ret = LDAP_NOT_SUPPORTED;
@@ -288,6 +307,11 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_set_optionA     (WLDAP32.@)
+ *
+ * See ldap_set_optionW.
+ */
 ULONG CDECL ldap_set_optionA( WLDAP32_LDAP *ld, int option, void *value )
 {
     ULONG ret = LDAP_NOT_SUPPORTED;
@@ -363,6 +387,23 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_set_optionW     (WLDAP32.@)
+ *
+ * Set option values for a given LDAP context.
+ *
+ * PARAMS
+ *  ld      [I] Pointer to an LDAP context.
+ *  option  [I] Option to set values for.
+ *  value   [I] Pointer to option values.
+ *
+ * RETURNS
+ *  Success: LDAP_SUCCESS
+ *  Failure: An LDAP error code.
+ *
+ * NOTES
+ *  Set value to LDAP_OPT_ON or LDAP_OPT_OFF for on/off options.
+ */ 
 ULONG CDECL ldap_set_optionW( WLDAP32_LDAP *ld, int option, void *value )
 {
     ULONG ret = LDAP_NOT_SUPPORTED;
diff --git a/dlls/wldap32/parse.c b/dlls/wldap32/parse.c
index c56632d..c8742a0 100644
--- a/dlls/wldap32/parse.c
+++ b/dlls/wldap32/parse.c
@@ -40,6 +40,11 @@ #include "wldap32.h"
 
 WINE_DEFAULT_DEBUG_CHANNEL(wldap32);
 
+/***********************************************************************
+ *      ldap_parse_extended_resultA     (WLDAP32.@)
+ *
+ * See ldap_parse_extended_resultW.
+ */
 ULONG CDECL ldap_parse_extended_resultA( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *result,
     PCHAR *oid, struct WLDAP32_berval **data, BOOLEAN free )
 {
@@ -64,6 +69,26 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_parse_extended_resultW     (WLDAP32.@)
+ *
+ * Parse the result of an extended operation. 
+ *
+ * PARAMS
+ *  ld      [I] Pointer to an LDAP context.
+ *  result  [I] Result message from an extended operation.
+ *  oid     [O] OID of the extended operation.
+ *  data    [O] Result data.
+ *  free    [I] Free the result message?
+ *
+ * RETURNS
+ *  Success: LDAP_SUCCESS
+ *  Failure: An LDAP error code.
+ *
+ * NOTES
+ *  Free the OID and result data with ldap_memfree. Pass a nonzero
+ *  value for 'free' or call ldap_msgfree to free the result message.
+ */
 ULONG CDECL ldap_parse_extended_resultW( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *result,
     PWCHAR *oid, struct WLDAP32_berval **data, BOOLEAN free )
 {
@@ -88,6 +113,11 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_parse_referenceA     (WLDAP32.@)
+ *
+ * See ldap_parse_referenceW.
+ */
 ULONG CDECL ldap_parse_referenceA( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *message,
     PCHAR **referrals )
 {
@@ -108,6 +138,23 @@ #endif 
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_parse_referenceW     (WLDAP32.@)
+ *
+ * Return any referrals from a result message.
+ *
+ * PARAMS
+ *  ld         [I] Pointer to an LDAP context.
+ *  result     [I] Result message.
+ *  referrals  [O] Array of referral URLs.
+ *
+ * RETURNS
+ *  Success: LDAP_SUCCESS
+ *  Failure: An LDAP error code.
+ *
+ * NOTES
+ *  Free the referrals with ldap_value_free.
+ */
 ULONG CDECL ldap_parse_referenceW( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *message,
     PWCHAR **referrals )
 {
@@ -128,6 +175,11 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_parse_resultA     (WLDAP32.@)
+ *
+ * See ldap_parse_resultW.
+ */
 ULONG CDECL ldap_parse_resultA( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *result,
     ULONG *retcode, PCHAR *matched, PCHAR *error, PCHAR **referrals,
     PLDAPControlA **serverctrls, BOOLEAN free )
@@ -160,6 +212,31 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_parse_resultW     (WLDAP32.@)
+ *
+ * Parse a result message. 
+ *
+ * PARAMS
+ *  ld           [I] Pointer to an LDAP context.
+ *  result       [I] Result message.
+ *  retcode      [O] Return code for the server operation.
+ *  matched      [O] DNs matched in the operation.
+ *  error        [O] Error message for the operation.
+ *  referrals    [O] Referrals found in the result message.
+ *  serverctrls  [O] Controls used in the operation.
+ *  free         [I] Free the result message?
+ *
+ * RETURNS
+ *  Success: LDAP_SUCCESS
+ *  Failure: An LDAP error code.
+ *
+ * NOTES
+ *  Free the DNs and error message with ldap_memfree. Free
+ *  the referrals with ldap_value_free and the controls with
+ *  ldap_controls_free. Pass a nonzero value for 'free' or call
+ *  ldap_msgfree to free the result message.
+ */
 ULONG CDECL ldap_parse_resultW( WLDAP32_LDAP *ld, WLDAP32_LDAPMessage *result,
     ULONG *retcode, PWCHAR *matched, PWCHAR *error, PWCHAR **referrals,
     PLDAPControlW **serverctrls, BOOLEAN free )
@@ -192,6 +269,11 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_parse_sort_controlA     (WLDAP32.@)
+ *
+ * See ldap_parse_sort_controlW.
+ */
 ULONG CDECL ldap_parse_sort_controlA( WLDAP32_LDAP *ld, PLDAPControlA *control,
     ULONG *result, PCHAR *attr )
 {
@@ -218,6 +300,24 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_parse_sort_controlW     (WLDAP32.@)
+ *
+ * Parse a sort control.
+ *
+ * PARAMS
+ *  ld       [I] Pointer to an LDAP context.
+ *  control  [I] Control obtained from a result message.
+ *  result   [O] Result code.
+ *  attr     [O] Failing attribute.
+ *
+ * RETURNS
+ *  Success: LDAP_SUCCESS
+ *  Failure: An LDAP error code.
+ *
+ * NOTES
+ *  If the function fails, free the failing attribute with ldap_memfree.
+ */
 ULONG CDECL ldap_parse_sort_controlW( WLDAP32_LDAP *ld, PLDAPControlW *control,
     ULONG *result, PWCHAR *attr )
 {
@@ -244,6 +344,11 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_parse_vlv_controlA     (WLDAP32.@)
+ *
+ * See ldap_parse_vlv_controlW.
+ */
 INT CDECL ldap_parse_vlv_controlA( WLDAP32_LDAP *ld, PLDAPControlA *control,
     PULONG targetpos, PULONG listcount,
     struct WLDAP32_berval **context, PINT errcode )
@@ -271,6 +376,26 @@ #endif
     return ret;
 }
 
+/***********************************************************************
+ *      ldap_parse_vlv_controlW     (WLDAP32.@)
+ *
+ * Parse a virtual list view control.
+ *
+ * PARAMS
+ *  ld         [I] Pointer to an LDAP context.
+ *  control    [I] Controls obtained from a result message.
+ *  targetpos  [O] Positition of the target in the result list. 
+ *  listcount  [O] Estimate of the number of results in the list.
+ *  context    [O] Server side context.
+ *  errcode    [O] Error code from the listview operation.
+ *
+ * RETURNS
+ *  Success: LDAP_SUCCESS
+ *  Failure: An LDAP error code.
+ *
+ * NOTES
+ *  Free the server context with ber_bvfree.
+ */
 INT CDECL ldap_parse_vlv_controlW( WLDAP32_LDAP *ld, PLDAPControlW *control,
     PULONG targetpos, PULONG listcount,
     struct WLDAP32_berval **context, PINT errcode )