Module: wine
Branch: refs/heads/master
Commit: cc7118594d691e4eb71bd5fa0c9b05cfad265270
URL: http://source.winehq.org/git/?p=wine.git;a=commit;h=cc7118594d691e4eb71bd5f…
Author: Hans Leidekker <hans(a)it.vu.nl>
Date: Mon Jul 10 22:18:40 2006 +0200
wldap32: Document the ber functions.
---
dlls/wldap32/ber.c | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 165 insertions(+), 0 deletions(-)
diff --git a/dlls/wldap32/ber.c b/dlls/wldap32/ber.c
index 31c4b6f..c037a16 100644
--- a/dlls/wldap32/ber.c
+++ b/dlls/wldap32/ber.c
@@ -34,6 +34,18 @@ #endif
/***********************************************************************
* ber_alloc_t (WLDAP32.@)
+ *
+ * Allocate a berelement structure.
+ *
+ * PARAMS
+ * options [I] Must be LBER_USE_DER.
+ *
+ * RETURNS
+ * Success: Pointer to an allocated berelement structure.
+ * Failure: NULL
+ *
+ * NOTES
+ * Free the berelement structure with ber_free.
*/
BerElement * CDECL WLDAP32_ber_alloc_t( INT options )
{
@@ -47,6 +59,18 @@ #endif
/***********************************************************************
* ber_bvdup (WLDAP32.@)
+ *
+ * Copy a berval structure.
+ *
+ * PARAMS
+ * berval [I] Pointer to the berval structure to be copied.
+ *
+ * RETURNS
+ * Success: Pointer to a copy of the berval structure.
+ * Failure: NULL
+ *
+ * NOTES
+ * Free the copy with ber_bvfree.
*/
BERVAL * CDECL WLDAP32_ber_bvdup( BERVAL *berval )
{
@@ -60,6 +84,18 @@ #endif
/***********************************************************************
* ber_bvecfree (WLDAP32.@)
+ *
+ * Free an array of berval structures.
+ *
+ * PARAMS
+ * berval [I] Pointer to an array of berval structures.
+ *
+ * RETURNS
+ * Nothing.
+ *
+ * NOTES
+ * Use this function only to free an array of berval structures
+ * returned by a call to ber_scanf with a 'V' in the format string.
*/
void CDECL WLDAP32_ber_bvecfree( PBERVAL *berval )
{
@@ -71,6 +107,18 @@ #endif
/***********************************************************************
* ber_bvfree (WLDAP32.@)
+ *
+ * Free a berval structure.
+ *
+ * PARAMS
+ * berval [I] Pointer to a berval structure.
+ *
+ * RETURNS
+ * Nothing.
+ *
+ * NOTES
+ * Use this function only to free berval structures allocated by
+ * an LDAP API.
*/
void CDECL WLDAP32_ber_bvfree( BERVAL *berval )
{
@@ -82,6 +130,20 @@ #endif
/***********************************************************************
* ber_first_element (WLDAP32.@)
+ *
+ * Return the tag of the first element in a set or sequence.
+ *
+ * PARAMS
+ * berelement [I] Pointer to a berelement structure.
+ * len [O] Receives the length of the first element.
+ * opaque [O] Receives a pointer to a cookie.
+ *
+ * RETURNS
+ * Success: Tag of the first element.
+ * Failure: LBER_DEFAULT (no more data).
+ *
+ * NOTES
+ * len and cookie should be passed to ber_next_element.
*/
ULONG CDECL WLDAP32_ber_first_element( BerElement *berelement, ULONG *len, CHAR **opaque )
{
@@ -95,6 +157,19 @@ #endif
/***********************************************************************
* ber_flatten (WLDAP32.@)
+ *
+ * Flatten a berelement structure into a berval structure.
+ *
+ * PARAMS
+ * berlement [I] Pointer to a berelement structure.
+ * berval [O] Pointer to a berval structure.
+ *
+ * RETURNS
+ * Success: 0
+ * Failure: LBER_ERROR
+ *
+ * NOTES
+ * Free the berval structure with ber_bvfree.
*/
INT CDECL WLDAP32_ber_flatten( BerElement *berelement, PBERVAL *berval )
{
@@ -108,6 +183,19 @@ #endif
/***********************************************************************
* ber_free (WLDAP32.@)
+ *
+ * Free a berelement structure.
+ *
+ * PARAMS
+ * berlement [I] Pointer to the berelement structure to be freed.
+ * buf [I] Flag.
+ *
+ * RETURNS
+ * Nothing.
+ *
+ * NOTES
+ * Set buf to 0 if the berelement was allocated with ldap_first_attribute
+ * or ldap_next_attribute, otherwise set it to 1.
*/
void CDECL WLDAP32_ber_free( BerElement *berelement, INT buf )
{
@@ -119,6 +207,18 @@ #endif
/***********************************************************************
* ber_init (WLDAP32.@)
+ *
+ * Initialise a berelement structure from a berval structure.
+ *
+ * PARAMS
+ * berval [I] Pointer to a berval structure.
+ *
+ * RETURNS
+ * Success: Pointer to a berelement structure.
+ * Failure: NULL
+ *
+ * NOTES
+ * Call ber_free to free the returned berelement structure.
*/
BerElement * CDECL WLDAP32_ber_init( BERVAL *berval )
{
@@ -132,6 +232,21 @@ #endif
/***********************************************************************
* ber_next_element (WLDAP32.@)
+ *
+ * Return the tag of the next element in a set or sequence.
+ *
+ * PARAMS
+ * berelement [I] Pointer to a berelement structure.
+ * len [I/O] Receives the length of the next element.
+ * opaque [I/O] Pointer to a cookie.
+ *
+ * RETURNS
+ * Success: Tag of the next element.
+ * Failure: LBER_DEFAULT (no more data).
+ *
+ * NOTES
+ * len and cookie are intitialised by ber_first_element and should
+ * be passed on in subsequent calls to ber_next_element.
*/
ULONG CDECL WLDAP32_ber_next_element( BerElement *berelement, ULONG *len, CHAR *opaque )
{
@@ -145,6 +260,16 @@ #endif
/***********************************************************************
* ber_peek_tag (WLDAP32.@)
+ *
+ * Return the tag of the next element.
+ *
+ * PARAMS
+ * berelement [I] Pointer to a berelement structure.
+ * len [O] Receives the length of the next element.
+ *
+ * RETURNS
+ * Success: Tag of the next element.
+ * Failure: LBER_DEFAULT (no more data).
*/
ULONG CDECL WLDAP32_ber_peek_tag( BerElement *berelement, ULONG *len )
{
@@ -158,6 +283,16 @@ #endif
/***********************************************************************
* ber_skip_tag (WLDAP32.@)
+ *
+ * Skip the current tag and return the tag of the next element.
+ *
+ * PARAMS
+ * berelement [I] Pointer to a berelement structure.
+ * len [O] Receives the length of the skipped element.
+ *
+ * RETURNS
+ * Success: Tag of the next element.
+ * Failure: LBER_DEFAULT (no more data).
*/
ULONG CDECL WLDAP32_ber_skip_tag( BerElement *berelement, ULONG *len )
{
@@ -171,6 +306,21 @@ #endif
/***********************************************************************
* ber_printf (WLDAP32.@)
+ *
+ * Encode a berelement structure.
+ *
+ * PARAMS
+ * berelement [I/O] Pointer to a berelement structure.
+ * fmt [I] Format string.
+ * ... [I] Values to encode.
+ *
+ * RETURNS
+ * Success: Non-negative number.
+ * Failure: LBER_ERROR
+ *
+ * NOTES
+ * berelement must have been allocated with ber_alloc_t. This function
+ * can be called multiple times to append data.
*/
INT CDECL WLDAP32_ber_printf( BerElement *berelement, PCHAR fmt, ... )
{
@@ -250,6 +400,21 @@ #endif
/***********************************************************************
* ber_scanf (WLDAP32.@)
+ *
+ * Decode a berelement structure.
+ *
+ * PARAMS
+ * berelement [I/O] Pointer to a berelement structure.
+ * fmt [I] Format string.
+ * ... [I] Pointers to values to be decoded.
+ *
+ * RETURNS
+ * Success: Non-negative number.
+ * Failure: LBER_ERROR
+ *
+ * NOTES
+ * berelement must have been allocated with ber_init. This function
+ * can be called multiple times to decode data.
*/
INT CDECL WLDAP32_ber_scanf( BerElement *berelement, PCHAR fmt, ... )
{