ldap_parse_resultW function (winldap.h)

Article
02/09/2023

The ldap_parse_result function parses responses from the server and returns the appropriate fields.

Syntax

WINLDAPAPI ULONG LDAPAPI ldap_parse_resultW(
  [in]            LDAP          *Connection,
  [in]            LDAPMessage   *ResultMessage,
  [out, optional] ULONG         *ReturnCode,
  [out, optional] PWSTR         *MatchedDNs,
  [out, optional] PWSTR         *ErrorMessage,
  [out, optional] PZPWSTR       *Referrals,
  [out, optional] PLDAPControlW **ServerControls,
  [in]            BOOLEAN       Freeit
);

Parameters

[in] Connection

The session handle.

[in] ResultMessage

The result of an LDAP operation as returned by one of the synchronous operation calls or by ldap_result for an asynchronous operation.

[out, optional] ReturnCode

Indicates the outcome of the server operation that generated the original result message. Pass NULL to ignore this field.

[out, optional] MatchedDNs

A pointer to a wide, null-terminated string. In the case of a return of LDAP_NO_SUCH_OBJECT, this result parameter is filled in with a distinguished name indicating how much of the name in the request was recognized. Pass NULL to ignore this field.

[out, optional] ErrorMessage

A pointer to a wide, null-terminated string that contains the contents of the error message field from the ResultMessage parameter. Pass NULL to ignore this field.

[out, optional] Referrals

A pointer to a wide, null-terminated string that contains the contents of the referrals field from the ResultMessage parameter, indicating zero or more alternate LDAP servers where the request should be retried. Pass NULL to ignore this field.

[out, optional] ServerControls

This result parameter is filled in with an allocated array of controls copied from the ResultMessage parameter.

[in] Freeit

Determines whether the ResultMessage parameter is freed. You can pass any nonzero value to the Freeit parameter to free the ResultMessage pointer when it is no longer needed, or you can call ldap_msgfree to free the result later.

Return value

If the function succeeds, the return value is LDAP_SUCCESS.

If the function fails, it returns an error code. See Return Values for more information.

Remarks

The ldap_parse_result function traverses a chain of server responses looking for result messages to parse. Use this function if you want to access the referrals, matching distinguished names, or server controls returned. The function skips over messages of type LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE.

When they are no longer needed, free the ErrorMessage and MatchedDNs strings by calling ldap_memfree. Free the Referrals array by calling ldap_value_free. Free the ServerControls by calling ldap_controls_free.

Note

The winldap.h header defines ldap_parse_result as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	winldap.h
Library	Wldap32.lib
DLL	Wldap32.dll