função ldap_search_ext_s (winldap.h)
A função ldap_search_ext_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_ext_s(
[in] LDAP *ld,
[in] PSTR base,
[in] ULONG scope,
[in] PSTR filter,
[in] PZPSTR attrs,
[in] ULONG attrsonly,
[in] PLDAPControlA *ServerControls,
[in] PLDAPControlA *ClientControls,
[in] l_timeval *timeout,
[in] ULONG SizeLimit,
[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 ponteiros para cadeias de caracteres terminadas em nulo indicando 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 forem retornados, diferente de zero se apenas tipos forem necessários.
[in] ServerControls
Uma lista de controles de servidor LDAP.
[in] ClientControls
Uma lista de controles de cliente.
[in] timeout
Especifica o valor de tempo limite de pesquisa local, em segundos, e o limite de tempo de operação que é enviado ao servidor dentro da solicitação de pesquisa.
[in] SizeLimit
Um limite no número de entradas a serem retornadas da pesquisa. Um valor igual a zero indica que não há limite.
[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 retornados gratuitamente 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_ext_s pode falhar e ainda poderá alocar pMsg. Por exemplo, LDAP_PARTIAL_RESULTS e LDAP_REFERRAL código de erro alocarão 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_ext_s inicia uma operação de pesquisa síncrona. Os parâmetros e efeitos de ldap_search_ext_s incluem os de ldap_search_s. A rotina estendida inclui parâmetros adicionais para dar suporte a controles de cliente e servidor e especificar limites de tamanho e tempo para cada operação de pesquisa.
Use a função ldap_set_option com o identificador de sessão ld para definir a opção LDAP_OPT_DEREF que determina como a pesquisa é executada. Para obter mais informações, consulte Opções de sessão. Duas outras opções de pesquisa, LDAP_OPT_SIZELIMIT e LDAP_OPT_TIMELIMIT, são ignoradas em favor dos parâmetros de opção SizeLimit e TimeLimit nessa função.
Após a conclusão da operação de pesquisa, ldap_search_ext_s retorna ao chamador. Use ldap_search_ext para que a operação seja executada de forma assíncrona.
Multithreading: as chamadas para ldap_search_ext_s são thread-safe.
O exemplo de código a seguir mostra como liberar pMsg caso ldap_search_ext_s falhe.
// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;
// Perform the search request.
dwErr = ldap_search_ext_s (i_pldap,
i_lpszBase,
i_ulScope,
i_lpszSearchFilter,
lpszAttributes,
0,
pServerControls,
pClientControls,
lpsTimeout,
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_ext_s"));
hr = HRESULT_FROM_WIN32(dwErr);
// Be aware that pMsg can contain valid data, even if
// the call to ldap_search_ext_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 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 |