ber_scanf

Decodes a BerElement, similar to the sscanf function.

Library:*ldapsdk.*

NDS Version:7.xx or higher

Platform:NLM, Windows (NT, 95, 98, 2000, XP, Vista 32-bit and 64-bit ), Linux (32-bit and 64-bit), Solaris, AIX, and HP-UX

Syntax

  #include <ldap.h> or <lber.h>
  
  ber_tag_t ber_scanf (
     BerElement  *ber,
     const char  *fmt,
     ...);

Parameters

ber: (IN) Points to a BerElement returned by the ber_init function.
fmt: (IN) Points to the format modifiers to use when interpreting the BerElement bytes.
...: (OUT) Returns pointers to data values returned by the function.

Return Values

Returns a non-LBER_ERROR value on success; otherwise, returns LBER_ERROR on failure.

Remarks

The ber_scanf function keeps some of the state information with the ber parameter so that the ber_scanf function can be called iteratively to sequentially read from the BerElement.

The results of successfully calling the ber_scanf function are stored in additional parameters.

The fmt parameter can have the following values.

a	Octet string	A char* pointer must be supplied. Memory is allocated and filled with the contents of the octet string (zero-terminated). The pointer to the string is stored in the parameter. The returned value should be freed by calling the ldap_memfree function. The element tag must indicate the primitive form (constructed strings are not supported) but is otherwise ignored and discarded during the decoding. This character cannot be used with octet string that contain NULL bytes.
b	Boolean	A pointer to ber_int_t must be supplied. The stored value will be zero for FALSE or nonzero for TRUE. The element tag must indicate the primitive form but is otherwise ignored during the decoding.
B	Bitstring	A char** parameter must be supplied that will point to the allocated bits. This is followed by a ber_len_t* parameter that will point to the length (in bits) of the returned bitstring. The ldap_memfree function should be called to free the bitstring. The element tag must indicate the primitive form (constructed bitstrings are not supported) but is otherwise ignored during the decoding.
e	Enumerated	A pointer to ber_int_t must be supplied. The stored value will be in host byte order. The element tag must indicate the primitive form but is otherwise ignored during the decoding. The ber_scanf function returns an error if the enumerated value cannot be stored in a ber_int_t.
i	Integer	A pointer to ber_int_t must be supplied. The stored value will be in host byte order. The element tag must indicate the primitive form but is otherwise ignored during the decoding. The ber_scanf function returns an error if the integer cannot be stored in a ber_int_t.
L	Length	A pointer to a ber_len_t must be supplied. The length of the next element in bytes is returned.
n	NULL	No parameter is needed. The element is verified to have a zero-length value and is skipped. The tag is ignored.
o	Octet string	A berval * parameter must be supplied, pointing to an existing empty berval structure. The buffer inside the berval is allocated as required and should be freed with the ldap_memfree function when done.
O	Octet string	A berval ** parameter must be supplied, which will point to an allocated berval structure that contains the octet string and its length upon return. The ber_bvfree function should be called to free the allocated memory. The element tag must indicate the primitive form (constructed strings are not supported) but is otherwise ignored during the decoding.
s	Octet string	A char * buffer must be supplied, point to an existing buffer. It must be followed by a ber_len_t * parameter. The object of this pointer contains the size of the buffer on input and is replaced with the size of the data written to the buffer on output.
t	Tag	A pointer to ber_tag_t must be supplied. The stored value will be the tag of the next element in the BerElement ber parameter and represented so it can be written using the 't' modifier of the ber_printf function. The decoding position within the ber parameter is not changed and can be used in the future.
v	Several octet strings	A char*** parameter must be supplied, which points to an allocated, NULL-terminated array of char* pointers that contain the octet strings upon return. NULL is stored if the sequence is empty. The ldap_memfree function should be called to free each element of the array and the array itself. The sequence tag and the octet string tags are ignored.
V	Several octet strings	A berval*** structure pointer must be supplied, which points to an allocated, NULL-terminated array of berval* structure pointers that contain the octet strings and their lengths upon return. NULL is stored if the sequence is empty. The ber_bvecfree function can be called to free the allocated memory. The sequence tag and the octet string tags are ignored.
x	Skip element	The next element is skipped. No parameter is needed.
{	Begin sequence	No parameter is needed. The initial sequence tag and length are skipped.
}	End sequence	No parameter is needed.
[	Begin set	No parameter is needed. The initial set tag and length are skipped.
]	End set	No parameter is needed.