ldap_search_s

The ldap_search_s function searches the LDAP directory and returns a requested set of attributes for each entry matched.

ULONG ldap_search_s(
  LDAP* ld,
  PCHAR base,
  ULONG scope,
  PCHAR filter,
  PCHAR attrs[],
  ULONG attrsonly,
  LDAPMessage** res
);

Parameters

ld

[in] The session handle.

base

[in] The distinguished name of the entry at which to start the search.

scope

[in] The scope of the search. See Remarks for a description.

filter

[in] The search filter.

attrs

[in] A null-terminated array of strings indicating the attributes to return for each matching entry. Pass NULL to retrieve all available attributes.

attrsonly

[in] A boolean value that should be zero if both attribute types and values are to be returned, nonzero if only types are wanted.

res

[out] Contains the results of the search upon completion of the call.

Return Values

If the function succeeds, the return value is LDAP_SUCCESS.

If the function fails it returns an error code, however ldap_search_s can fail and can still allocate pMsg. See the example below for handling this behavior. Also, see Return Values for more information.

Remarks

The ldap_search_s function initiates a synchronous search operation. The scope of the search is determined by the value of the scope parameter, as shown in the following table.

Three options in the Session Options also determine how the search is performed: LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, and LDAP_OPT_DEREF.

Upon completion of the search operation, ldap_search_s returns to the caller. Use ldap_search if you prefer to have the operation carried out asynchronously.

Multithreading: Calls to ldap_search_s are thread-safe.

The following code example shows how to allocate pMsg in the event ldap_search_s fails.

dwErr = ldap_search_s (i_pldap,
        i_lpszBase,
        i_ulScope,
        i_lpszSearchFilter,
        lpszAttributes,
        0,
        pMsg
        );

//ldap_search_s may return a failure and still allocate pMsg.

delete [] lpszAttributes;

If (LDAP_SUCCESS !=dwErr)
{
    DebugOutLDAPError(i_pldap, dwErr, _T("ldap_search_s"));
    hr = HRESULT_FROM_WIN32(dwErr);
}

else
//Skip to the end of else.
{
    ldap_msgfree(pMsg);

//Still in else, not freed in failure.
}

if (FAILED(HR))
{
    for (i = 0; i<i_ulAttrCount; i++)
    FreeAttrValList(o_ppValues[i]);
}

return hr;
//Leak pMsg here.
}

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP4 or later.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in Winldap.h.
  Library: Use Wldap32.lib.
  Unicode: Declared as Unicode and ANSI prototypes.

See Also

Functions, ldap_search, Return Values, Session Options