Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function is used to decode a basic encoding rules (BER) element in much the same way that sscanfworks. One important difference, though, is that some state information is kept with the pBerElementargument so that multiple calls can be made to ber_scanfto sequentially read from the BER element. The pBerElementargument should be a pointer to a BerElementstructure returned by a call to the ber_initfunction.

Syntax

INT ber_scanf(
  BerElement* 
pBerElement,
  UNICODE PTCHAR 
fmt,

...
);

Parameters

pBerElement

[in, out] Pointer to the BerElementbeing decoded.

fmt

[in] Encoding format string (see the Remarkssection below).

...

[in] Pointers to variables used to hold the values decoded as specified by the fmtargument.

Return Value

This function returns LBER_ERROR on error.

Remarks

The function interprets the bytes according to the format string fmt, and stores the results in its additional arguments. The format string contains conversion specifications which are used to direct the interpretation of the BER element. The format string can contain the following characters.

Value Description

a

Octet string. A char** argument must be supplied. Memory is allocated, filled with the contents of the octet string, and zero-terminated, and the pointer to the string is stored in the argument. The returned value should be freed using ldap_memfree. The tag of the element must indicate the primitive form (constructed strings are not supported), but it is otherwise ignored and discarded during the decoding. This format cannot be used with octet strings, which could contain null bytes.

O

Octet string. A berval** argument must be supplied, which upon return points to an allocated berval containing the octet string and its length. ber_bvfree should be called to free the allocated memory. The tag of the element must indicate the primitive form (constructed strings are not supported), but it is otherwise ignored during the decoding.

b

Boolean. A pointer to a ber_int_t must be supplied. The ber_int_t value stored will be 0 for FALSE or nonzero for TRUE. The tag of the element must indicate the primitive form, but it is otherwise ignored during the decoding.

e

Enumerated. A pointer to a ber_int_t must be supplied. The tag of the element must indicate the primitive form, but it is otherwise ignored during the decoding. The ber_scanffunction will return an error if the value of the enumerated value cannot be stored in a ber_int_t.

I

Integer. A pointer to a ber_int_t must be supplied. The tag of the element must indicate the primitive form but is otherwise ignored during the decoding. The ber_scanffunction will return an error if the integer cannot be stored in a ber_int_t.

B

Bitstring. A char** argument must be supplied, which will point to the allocated bits, followed by a ber_len_t * argument, which will point to the length (in bits) of the bitstring returned. The ldap_memfreefunction should be called to free the bitstring. The tag of the element must indicate the primitive form (constructed bitstrings are not supported), but it is otherwise ignored during the decoding.

n

Null. No argument is needed. The element is verified to have a zero-length value and is skipped. The tag is ignored.

t

Tag. A pointer to a ber_tag_t must be supplied. The ber_tag_t value stored will be the tag of the next element in the pBerElement, represented so it can be written using the t format of ber_printf. The decoding position within the pBerElementargument is unchanged by this.

v

Several octet strings. A char*** argument must be supplied, which upon return points to an allocated NULL-terminated array of char * arguments containing the octet strings. NULL is stored if the sequence is empty. The ldap_memfreefunction should be called to free each element of the array and the array itself. The tag of the sequence and of the octet strings are ignored.

V

Several octet strings(which could contain null bytes). A berval*** must be supplied, which upon return points to an allocated NULL-terminated array of berval* structures containing the octet strings and their lengths. NULL is stored if the sequence is empty. The ber_bvecfreefunction can be called to free the allocated memory. The tag of the sequence and of the octet strings are ignored.

x

Skip element. The next element is skipped. No argument is needed.

{

Begin sequence. No argument is needed. The initial sequence tag and length are skipped.

}

End sequence. No argument is needed.

[

Begin set. No argument is needed. The initial set tag and length are skipped.

]

End set. No argument is needed.

Requirements

Header winber.h
Library wldap32.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also