função ldap_search_s (winldap.h)
A função ldap_search_s pesquisa de forma síncrona o diretório LDAP e retorna um conjunto solicitado de atributos para cada entrada correspondente.
Sintaxe
WINLDAPAPI ULONG LDAPAPI ldap_search_s(
[in] LDAP *ld,
[in] PSTR base,
[in] ULONG scope,
[in] PSTR filter,
[in] PZPSTR attrs,
[in] ULONG attrsonly,
[out] PLDAPMessage *res
);
Parâmetros
[in] ld
Identificador de sessão.
[in] base
Ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome diferenciado da entrada na qual iniciar a pesquisa.
[in] scope
Especifica um dos valores a seguir para indicar o escopo da pesquisa.
LDAP_SCOPE_BASE
Pesquise somente a entrada base.
LDAP_SCOPE_ONELEVEL
Pesquise todas as entradas no primeiro nível abaixo da entrada base, excluindo a entrada base.
LDAP_SCOPE_SUBTREE
Pesquise a entrada base e todas as entradas na árvore abaixo da base.
[in] filter
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o filtro de pesquisa. Para obter mais informações, consulte Sintaxe de filtro de pesquisa.
[in] attrs
Uma matriz terminada em nulo de cadeias de caracteres terminadas em nulo que indica os atributos a serem retornados para cada entrada correspondente. Passe NULL para recuperar todos os atributos disponíveis.
[in] attrsonly
Valor booliano que deve ser zero se os tipos de atributo e os valores forem retornados, diferente de zero se apenas tipos forem necessários.
[out] res
Contém os resultados da pesquisa após a conclusão da chamada. Também pode conter resultados parciais ou dados estendidos quando a chamada de função falhar com um código de erro. Resultados gratuitos retornados com uma chamada para ldap_msgfree quando eles não são mais exigidos pelo aplicativo.
Retornar valor
Se a função for bem-sucedida, o valor retornado será LDAP_SUCCESS.
Se a função falhar, ela retornará um código de erro, no entanto , ldap_search_s poderá falhar e ainda poderá alocar pMsg. Por exemplo, LDAP_PARTIAL_RESULTS e LDAP_REFERRAL código de erro alocam pMsg. Para obter mais informações, consulte o exemplo de código a seguir. Para obter mais informações, consulte Valores retornados.
Comentários
A função ldap_search_s inicia uma pesquisa síncrona.
Use a função ldap_set_option com o identificador de sessão ld para definir as opções de LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT e LDAP_OPT_DEREF que determinam como a pesquisa é executada. Para obter mais informações, consulte Opções de sessão.
Após a conclusão da operação de pesquisa, ldap_search_s retorna ao chamador. Use ldap_search para que a operação seja executada de forma assíncrona.
Multithreading: as chamadas para ldap_search_s são thread-safe.
O exemplo de código a seguir mostra como liberar pMsg caso ldap_search_s falhe.
// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;
// Perform the search request.
dwErr = ldap_search_s (i_pldap,
i_lpszBase,
i_ulScope,
i_lpszSearchFilter,
lpszAttributes,
0,
&pMsg
);
// Cleanup calling parameters.
if (lpszAttributes != NULL)
delete [] lpszAttributes;
// Convert error code and cleanup pMsg, if necessary.
if (dwErr != LDAP_SUCCESS)
{
DebugOutLDAPError(i_pldap, dwErr, _T("ldap_search_s"));
hr = HRESULT_FROM_WIN32(dwErr);
// Be aware that pMsg can contain valid data, even if the
// call to ldap_search_s returned an error code.
// This can be caused by the server returning codes,
// such as LDAP_RESULTS_TOO_LARGE or other codes,
// that indicate that the search returned partial
// results. The user code can handle these cases
// if required, this example just frees pMsg on any
// error code.
if (pMsg != NULL)
ldap_msgfree(pMsg);
}
else
{
// Process the search results.
...
// Free the results when no longer required.
if (pMsg != NULL) ldap_msgfree(pMsg);
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista |
| Servidor mínimo com suporte | Windows Server 2008 |
| Plataforma de Destino | Windows |
| Cabeçalho | winldap.h |
| Biblioteca | Wldap32.lib |
| DLL | Wldap32.dll |