função ldap_search_ext_sW (winldap.h)

A função ldap_search_ext_s pesquisa síncronamente o diretório LDAP e retorna um conjunto solicitado de atributos para cada entrada correspondente.

Sintaxe

WINLDAPAPI ULONG LDAPAPI ldap_search_ext_sW(
  [in]  LDAP          *ld,
  [in]  const PWSTR   base,
  [in]  ULONG         scope,
  [in]  const PWSTR   filter,
  [in]  PZPWSTR       attrs,
  [in]  ULONG         attrsonly,
  [in]  PLDAPControlW *ServerControls,
  [in]  PLDAPControlW *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 que indicam quais atributos devem ser 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 os 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 não indica nenhum 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 for mais exigido pelo aplicativo.

Valor de retorno

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 poderá falhar e ainda poderá alocar pMsg. Por exemplo, o código de erro LDAP_PARTIAL_RESULTS e LDAP_REFERRAL alocará pMsg. Para obter mais informações, consulte o exemplo de código a seguir. Para obter mais informações, consulte Valores retornados.

Observações

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 no caso de ldap_search_ext_s falhar.

// 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);

}

Nota

O cabeçalho winldap.h define ldap_search_ext_s como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista
servidor com suporte mínimo	Windows Server 2008
da Plataforma de Destino	Windows
cabeçalho	winldap.h
biblioteca	Wldap32.lib
de DLL	Wldap32.dll

Consulte também

controles estendidos

Funções

LDAP

opções de sessão

Comentários

Esta página foi útil?

Last updated on 2024-11-20