função ldap_search_st (winldap.h)
A função ldap_search_st pesquisa de forma síncrona o diretório LDAP e retorna um conjunto solicitado de atributos para cada entrada correspondente. Um parâmetro adicional especifica um tempo limite local para a pesquisa. A função é idêntica a ldap_search_s, exceto pelo parâmetro de tempo limite local adicional.
Sintaxe
WINLDAPAPI ULONG LDAPAPI ldap_search_st(
[in] LDAP *ld,
[in] PSTR base,
[in] ULONG scope,
[in] PSTR filter,
[in] PZPSTR attrs,
[in] ULONG attrsonly,
[in] l_timeval *timeout,
[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
Pesquisar 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 indicam quais atributos retornar 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 devem ser retornados, diferente de zero se apenas tipos forem necessários.
[in] timeout
O valor de tempo limite da pesquisa local, em segundos.
[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 falha com um código de erro. Todos os resultados retornados devem ser liberados com uma chamada para ldap_msgfree quando não forem 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_st 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_st inicia uma operação de 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 e LDAP_OPT_DEREF que determinam como a pesquisa é executada. Para obter mais informações, consulte Opções de sessão. O parâmetro timeout no ldap_search_st substitui o LDAP_OPT_TIMELIMIT.
Após a conclusão da operação de pesquisa, ldap_search_st retorna ao chamador. Use ldap_search ou ldap_search_ext para que a operação seja executada de forma assíncrona.
Multithreading: as chamadas para ldap_search_st são thread-safe.
O exemplo de código a seguir mostra como liberar pMsg se ldap_search_st falhar.
// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;
// Perform the search request.
dwErr = ldap_search_st (i_pldap,
i_lpszBase,
i_ulScope,
i_lpszSearchFilter,
lpszAttributes,
0,
lpsTimeout,
&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_st"));
hr = HRESULT_FROM_WIN32(dwErr);
// Be aware that pMsg can contain valid data, even if the
// call to ldap_search_st 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 complete.
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 |