función ldap_search_ext_s (winldap.h)

Artículo
03/08/2023

La función ldap_search_ext_s busca sincrónicamente el directorio LDAP y devuelve un conjunto solicitado de atributos para cada entrada coincidente.

Sintaxis

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 sesión.

[in] base

Puntero a una cadena terminada en null que contiene el nombre distintivo de la entrada en la que se va a iniciar la búsqueda.

[in] scope

Especifica uno de los valores siguientes para indicar el ámbito de búsqueda.

LDAP_SCOPE_BASE

Busque solo la entrada base.

LDAP_SCOPE_ONELEVEL

Busque todas las entradas del primer nivel por debajo de la entrada base, excepto la entrada base.

LDAP_SCOPE_SUBTREE

Busque la entrada base y todas las entradas del árbol debajo de la base.

[in] filter

Puntero a una cadena terminada en null que especifica el filtro de búsqueda. Para obtener más información, vea Sintaxis de filtro de búsqueda.

[in] attrs

Matriz terminada en null de punteros a cadenas terminadas en null que indican qué atributos se van a devolver para cada entrada coincidente. Pase NULL para recuperar todos los atributos disponibles.

[in] attrsonly

Valor booleano que debe ser cero si se van a devolver los tipos de atributo y los valores, distinto de cero si solo se requieren tipos.

[in] ServerControls

Lista de controles de servidor LDAP.

[in] ClientControls

Una lista de controles de cliente.

[in] timeout

Especifica el valor de tiempo de espera de búsqueda local, en segundos, y el límite de tiempo de operación que se envía al servidor dentro de la solicitud de búsqueda.

[in] SizeLimit

Límite en el número de entradas que se van a devolver de la búsqueda. Un valor de cero indica que no hay límite.

[out] res

Contiene los resultados de la búsqueda tras la finalización de la llamada. También puede contener resultados parciales o datos extendidos cuando se produce un error en la llamada de función con un código de error. Resultados devueltos gratis con una llamada a ldap_msgfree cuando la aplicación ya no lo requiera.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es LDAP_SUCCESS.

Si se produce un error en la función, devuelve un código de error, pero ldap_search_ext_s puede producir un error y seguir asignando pMsg. Por ejemplo, tanto LDAP_PARTIAL_RESULTS comoLDAP_REFERRAL código de error asignarán pMsg. Para obtener más información, vea el ejemplo de código siguiente. Para obtener más información, vea Valores devueltos.

Comentarios

La función ldap_search_ext_s inicia una operación de búsqueda sincrónica. Los parámetros y efectos de ldap_search_ext_s incluyen los de ldap_search_s. La rutina extendida incluye parámetros adicionales para admitir controles de cliente y servidor, y para especificar límites de tamaño y tiempo para cada operación de búsqueda.

Use la función ldap_set_option con el identificador de sesión ld para establecer la opción LDAP_OPT_DEREF que determine cómo se realiza la búsqueda. Para obtener más información, vea Opciones de sesión. Otras dos opciones de búsqueda, LDAP_OPT_SIZELIMIT y LDAP_OPT_TIMELIMIT, se omiten en favor de los parámetros de opción SizeLimit y TimeLimit de esta función.

Tras la finalización de la operación de búsqueda, ldap_search_ext_s vuelve al autor de la llamada. Use ldap_search_ext para que la operación se realice de forma asincrónica.

Multithreading: las llamadas a ldap_search_ext_s son seguras para subprocesos.

En el ejemplo de código siguiente se muestra cómo liberar pMsg en caso de que se produzca un error en ldap_search_ext_s .

// 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	Value
Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	winldap.h
Library	Wldap32.lib
Archivo DLL	Wldap32.dll