función ldap_search_st (winldap.h)
La función ldap_search_st busca sincrónicamente el directorio LDAP y devuelve un conjunto solicitado de atributos para cada entrada coincidente. Un parámetro adicional especifica un tiempo de espera local para la búsqueda. La función es idéntica a ldap_search_s, excepto el parámetro de tiempo de espera local adicional.
Sintaxis
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 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 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] timeout
Valor de tiempo de espera de búsqueda local, en segundos.
[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. Los resultados devueltos deben liberarse 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_st puede producir un error y seguir asignando pMsg. Por ejemplo, tanto LDAP_PARTIAL_RESULTS comoLDAP_REFERRAL código de error asignan 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_st inicia una operación de búsqueda sincrónica.
Use la función ldap_set_option con el identificador de sesión ld para establecer las opciones de LDAP_OPT_SIZELIMIT y LDAP_OPT_DEREF que determinan cómo se realiza la búsqueda. Para obtener más información, vea Opciones de sesión. El parámetro de tiempo de espera de ldap_search_st invalida el LDAP_OPT_TIMELIMIT.
Tras la finalización de la operación de búsqueda, ldap_search_st vuelve al autor de la llamada. Use ldap_search o ldap_search_ext para que la operación se realice de forma asincrónica.
Multithreading: las llamadas a ldap_search_st son seguras para subprocesos.
En el ejemplo de código siguiente se muestra cómo liberar pMsg si se produce un error en ldap_search_st .
// 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 | 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 |