ADS_SEARCHPREF_ENUM enumeración (iads.h)
La enumeración ADS_SEARCHPREF_ENUM especifica las preferencias de un objeto IDirectorySearch . Esta enumeración se usa en el miembro dwSearchPref de la estructura ADS_SEARCHPREF_INFO en el método IDirectorySearch::SetSearchPreference .
Syntax
typedef enum __MIDL___MIDL_itf_ads_0000_0000_0025 {
ADS_SEARCHPREF_ASYNCHRONOUS = 0,
ADS_SEARCHPREF_DEREF_ALIASES,
ADS_SEARCHPREF_SIZE_LIMIT,
ADS_SEARCHPREF_TIME_LIMIT,
ADS_SEARCHPREF_ATTRIBTYPES_ONLY,
ADS_SEARCHPREF_SEARCH_SCOPE,
ADS_SEARCHPREF_TIMEOUT,
ADS_SEARCHPREF_PAGESIZE,
ADS_SEARCHPREF_PAGED_TIME_LIMIT,
ADS_SEARCHPREF_CHASE_REFERRALS,
ADS_SEARCHPREF_SORT_ON,
ADS_SEARCHPREF_CACHE_RESULTS,
ADS_SEARCHPREF_DIRSYNC,
ADS_SEARCHPREF_TOMBSTONE,
ADS_SEARCHPREF_VLV,
ADS_SEARCHPREF_ATTRIBUTE_QUERY,
ADS_SEARCHPREF_SECURITY_MASK,
ADS_SEARCHPREF_DIRSYNC_FLAG,
ADS_SEARCHPREF_EXTENDED_DN
} ADS_SEARCHPREF_ENUM;
Constantes
ADS_SEARCHPREF_ASYNCHRONOUSValor: 0 Especifica que las búsquedas se deben realizar de forma asincrónica. De forma predeterminada, las búsquedas son sincrónicas. En una búsqueda sincrónica, los métodos IDirectorySearch::GetFirstRow e IDirectorySearch::GetNextRow no devuelven hasta que el servidor devuelva todo el resultado o para una búsqueda paginada, toda la página. Una búsqueda asincrónica se bloquea hasta que transcurre una fila de los resultados de búsqueda o hasta que transcurre el intervalo de tiempo de espera especificado por el ADS_SEARCHPREF_TIMEOUT preferencias de búsqueda. |
|||||||||||||||||
ADS_SEARCHPREF_DEREF_ALIASESEspecifica que se van a resolver los alias de los objetos encontrados. Use la enumeración ADS_DEREFENUM para especificar cómo se realiza. |
|||||||||||||||||
ADS_SEARCHPREF_SIZE_LIMITEspecifica el límite de tamaño que el servidor debe observar durante una búsqueda. El servidor deja de buscar cuando se alcanza el límite de tamaño y devuelve los resultados acumulados hasta ese punto. Si este valor es cero, el servicio de directorio determina el límite de tamaño. El valor predeterminado para este valor es cero. Si este valor es mayor que el límite de tamaño determinado por el servicio de directorio, el límite del servicio de directorio tiene prioridad. Para Active Directory, el límite de tamaño especifica el número máximo de objetos que devolverá la búsqueda. También para Active Directory, el número máximo de objetos devueltos por una búsqueda es de 1000 objetos. |
|||||||||||||||||
ADS_SEARCHPREF_TIME_LIMITEspecifica el número de segundos que el servidor espera a que se complete una búsqueda. Cuando se alcanza el límite de tiempo, el servidor deja de buscar y devuelve los resultados acumulados hasta ese momento. Si este valor es cero, el período de tiempo de espera es infinito. El valor predeterminado para este valor es de 120 segundos. |
|||||||||||||||||
ADS_SEARCHPREF_ATTRIBTYPES_ONLYIndica que la búsqueda debe obtener solo el nombre de los atributos a los que se asignan los valores. |
|||||||||||||||||
ADS_SEARCHPREF_SEARCH_SCOPEEspecifica el ámbito de búsqueda que debe observar el servidor. Para obtener más información sobre la configuración adecuada, vea la enumeración ADS_SCOPEENUM . |
|||||||||||||||||
ADS_SEARCHPREF_TIMEOUTEspecifica el límite de tiempo, en segundos, que un cliente esperará a que el servidor devuelva el resultado. Esta opción se establece en una estructura ADS_SEARCHPREF_INFO . |
|||||||||||||||||
ADS_SEARCHPREF_PAGESIZEEspecifica el tamaño de página en una búsqueda paginada. Para cada solicitud del cliente, el servidor devuelve, como máximo, el número de objetos establecido por el tamaño de página. Cuando se establece el tamaño de página, no es necesario establecer el límite de tamaño. Si se establece un límite de tamaño, el valor del tamaño de página debe ser menor que el valor del límite de tamaño. Si el valor del tamaño de página supera el límite de tamaño, el ERROR_DS_SIZELIMIT_EXCEEDED error se devuelve con el número de filas especificadas por límite de tamaño. |
|||||||||||||||||
ADS_SEARCHPREF_PAGED_TIME_LIMITEspecifica el número de segundos que el servidor debe esperar a una página de resultados de búsqueda, en lugar del límite de tiempo de toda la búsqueda. Cuando se alcanza el límite de tiempo, el servidor deja de buscar y devuelve los resultados obtenidos hasta ese momento, junto con una cookie que contiene los datos sobre dónde reanudar la búsqueda. Si este valor es cero, el período de tiempo de espera de la página es infinito. El valor predeterminado para este límite es de 120 segundos. |
|||||||||||||||||
ADS_SEARCHPREF_CHASE_REFERRALSEspecifica que se pueden perseguir las referencias. Si la búsqueda raíz no se especifica en el contexto de nomenclatura del servidor o cuando los resultados de la búsqueda cruzan un contexto de nomenclatura, por ejemplo, cuando tiene dominios secundarios y busca en el dominio primario, el servidor envía un mensaje de referencia al cliente que el cliente puede elegir omitir o perseguir. Para obtener más información sobre el seguimiento de referencias, consulte ADS_CHASE_REFERRALS_ENUM. |
|||||||||||||||||
ADS_SEARCHPREF_SORT_ONEspecifica que el servidor ordena el conjunto de resultados. Use la estructura ADS_SORTKEY para especificar las claves de ordenación. Esta preferencia de búsqueda solo funciona para los servidores de directorio que admiten el control LDAP para la ordenación del lado servidor. Active Directory admite el control de ordenación, pero puede afectar al rendimiento del servidor, especialmente si el conjunto de resultados es grande. Active Directory solo admite una clave de ordenación única. |
|||||||||||||||||
ADS_SEARCHPREF_CACHE_RESULTSEspecifica si el resultado se debe almacenar en caché en el lado cliente. De forma predeterminada, ADSI almacena en caché el conjunto de resultados. Deshabilitar esta opción puede ser deseable para grandes conjuntos de resultados. |
|||||||||||||||||
ADS_SEARCHPREF_DIRSYNCEspecifica una búsqueda de sincronización de directorios (DirSync), que devuelve todos los cambios desde un estado especificado. En la estructura ADSVALUE , establezca el miembro dwType en ADS_PROV_SPECIFIC. El miembro ProviderSpecific es una estructura ADS_PROV_SPECIFIC cuyo miembro lpValue especifica una cookie que indica el estado del que se recuperan los cambios. La primera vez que use el control DirSync, establezca los miembros dwLength y lpValue de la estructura ADS_PROV_SPECIFIC en cero y NULL respectivamente. Después de leer el conjunto de resultados devuelto por la búsqueda hasta que IDirectorySearch::GetNextRow devuelva S_ADS_NOMORE_ROWS, llame a IDirectorySearch::GetColumn para recuperar el atributo ADS_DIRSYNC_COOKIE que contiene una cookie que se usará en la siguiente búsqueda DirSync. Para obtener más información, vea Sondeo de cambios mediante el control DirSync y LDAP_SERVER_DIRSYNC_OID. Esta marca no se puede combinar con ADS_SEARCHPREF_PAGESIZE. El autor de la llamada debe tener el privilegio SE_SYNC_AGENT_NAME . |
|||||||||||||||||
ADS_SEARCHPREF_TOMBSTONEEspecifica si la búsqueda también debe devolver objetos eliminados que coincidan con el filtro de búsqueda. Cuando se eliminan los objetos, Active Directory los mueve a un contenedor "Objetos eliminados". De forma predeterminada, los objetos eliminados no se incluyen en los resultados de la búsqueda. En la estructura ADSVALUE , establezca el miembro dwTypeen ADSTYPE_BOOLEAN. Para incluir objetos eliminados, establezca el miembro booleano de la estructura ADSVALUE en TRUE. No todos los atributos se conservan cuando se elimina el objeto. Puede recuperar los atributos objectGUID y RDN . El atributo distinguishedName es el DN del objeto en el contenedor "Objetos eliminados", no el DN anterior. El atributo isDeleted es TRUE para un objeto eliminado. Para obtener más información, vea Recuperar objetos eliminados. |
|||||||||||||||||
ADS_SEARCHPREF_VLVEspecifica que la búsqueda debe usar el control de vista de lista virtual LDAP (VLV). ADS_SEARCHPREF_VLV se puede usar para acceder a las búsquedas VLV de tipo cadena y de tipo offset, estableciendo los campos adecuados. Estas dos opciones no se pueden usar simultáneamente porque no es posible establecer el control VLV para solicitar un conjunto de resultados que se encuentra en un desplazamiento específico y sigue un valor determinado en la secuencia de ordenación. Para realizar una búsqueda de cadenas, establezca el campo lpszTarget en ADS_VLV en la cadena que se va a buscar. Para realizar una búsqueda de tipo de desplazamiento, establezca el campo dwOffset en ADS_VLV. Si usa una búsqueda de desplazamiento, debe establecer lpszTarget en NULL. ADS_SEARCHPREF_SORT_ON debe establecerse en TRUE al usar ADS_SEARCHPREF_VLV. El criterio de ordenación de los resultados de búsqueda determina el orden utilizado para la búsqueda de VLV. Si realiza una búsqueda de tipo offset, el desplazamiento se usa como índice en la lista ordenada. Si realiza una búsqueda de tipo cadena, el servidor intenta devolver la primera entrada que es mayor o igual a la cadena, en función del criterio de ordenación. El almacenamiento en caché de los resultados de la búsqueda se deshabilita cuando se especifica ADS_SEARCHPREF_VLV . Si asigna ADS_SEARCHPREF_CACHE_RESULTStrue, el valor al usar ADS_SEARCHPREF_VLV, SetSearchPreference producirá un error y devolverá el error E_ADS_BAD_PARAMETER. |
|||||||||||||||||
ADS_SEARCHPREF_ATTRIBUTE_QUERYEspecifica que se debe realizar una búsqueda de consultas con ámbito de atributo. La búsqueda se realiza en esos objetos denominados en un atributo especificado del objeto base. El miembro vValue de la estructura ADS_SEARCHPREF_INFO contiene un valor de ADSTYPE_CASE_IGNORE_STRING que contiene el lDAPDisplayName del atributo que se va a buscar. Este atributo debe ser un atributo ADS_DN_STRING . Solo se puede especificar un atributo. El ámbito de búsqueda se establece automáticamente en ADS_SCOPE_BASE al usar esta preferencia y, de lo contrario, se producirá un error al intentar establecer el ámbito con el error E_ADS_BAD_PARAMETER. A excepción de la preferencia de ADS_SEARCHPREF_VLV , no se permiten todas las demás preferencias que usan controles LDAP, como ADS_SEARCHPREF_DIRSYNC, ADS_SEARCHPREF_TOMBSTONE, etc. cuando se especifica esta preferencia. |
|||||||||||||||||
ADS_SEARCHPREF_SECURITY_MASKEspecifica que la búsqueda debe devolver datos de acceso de seguridad para los atributos especificados. El miembro vValue de la estructura ADS_SEARCHPREF_INFO contiene un valor de ADS_INTEGER que es una combinación de uno o varios de los valores siguientes.
Si lee un descriptor de seguridad sin especificar explícitamente una máscara de seguridad mediante ADS_SEARCHPREF_SECURITY_MASK, el valor predeterminado es equivalente a ADS_SECURITY_INFO_OWNER |
ADS_SECURITY_INFO_GROUP | ADS_SECURITY_INFO_DACL. | |||||||||||||||
ADS_SEARCHPREF_DIRSYNC_FLAGContiene marcas opcionales para su uso con la preferencia de búsqueda ADS_SEARCHPREF_DIRSYNC . El miembro vValue de la estructura ADS_SEARCHPREF_INFO contiene un valor de ADSTYPE_INTEGER que es cero o una combinación de uno o varios de los valores siguientes. Para obtener más información sobre el control DirSync, vea Sondear cambios mediante el control DirSync y LDAP_SERVER_DIRSYNC_OID.
|
|||||||||||||||||
ADS_SEARCHPREF_EXTENDED_DNLa búsqueda debe devolver nombres distintivos en formato extendido de Active Directory. El miembro vValue de la estructura de ADS_SEARCHPREF_INFO contiene un valor de ADSTYPE_INTEGER que contiene cero si las partes GUID y SID de la cadena DN deben estar en formato hexadecimal o una si las partes GUID y SID de la cadena DN deben estar en formato estándar. Para obtener más información sobre los nombres distintivos extendidos, vea LDAP_SERVER_EXTENDED_DN_OID. |
Comentarios
Para configurar una preferencia de búsqueda, asigne los valores adecuados a los campos de una estructura de ADS_SEARCHPREF_INFO que se pasa al servidor. El miembro vValue de la estructura ADS_SEARCHPREF_INFO es una estructura ADSVALUE . En la lista siguiente se enumeran los valores de ADS_SEARCHPREF_ENUM , los valores correspondientes para el miembro dwType de la estructura ADSVALUE y el miembro ADSVALUE que se usa para el tipo especificado.
| ADS_SEARCHPREF_ENUM valor | miembro dwType de ADSVALUE | Miembro ADSVALUE |
|---|---|---|
| ADS_SEARCHPREF_ASYNCHRONOUS | ADSTYPE_BOOLEAN | Boolean |
| ADS_SEARCHPREF_DEREF_ALIASES | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_SIZE_LIMIT | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_TIME_LIMIT | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_ATTRIBTYPES_ONLY | ADSTYPE_BOOLEAN | Boolean |
| ADS_SEARCHPREF_SEARCH_SCOPE | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_TIMEOUT | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_PAGESIZE | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_PAGED_TIME_LIMIT | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_CHASE_REFERRALS | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_SORT_ON | ADSTYPE_PROV_SPECIFIC | ProviderSpecific |
| ADS_SEARCHPREF_CACHE_RESULTS | ADSTYPE_BOOLEAN | Boolean |
| ADS_SEARCHPREF_DIRSYNC | ADSTYPE_PROV_SPECIFIC | ProviderSpecific |
| ADS_SEARCHPREF_TOMBSTONE | ADSTYPE_BOOLEAN | Boolean |
| ADS_SEARCHPREF_VLV | ADSTYPE_PROV_SPECIFIC | ProviderSpecific |
| ADS_SEARCHPREF_ATTRIBUTE_QUERY | ADSTYPE_CASE_IGNORE_STRING | CaseIgnoreString |
| ADS_SEARCHPREF_SECURITY_MASK | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_DIRSYNC_FLAG | ADSTYPE_INTEGER | Entero |
| ADS_SEARCHPREF_EXTENDED_DN | ADSTYPE_INTEGER | Entero |
Para configurar varias preferencias, use una matriz de estructuras de ADS_SEARCHPREF_INFO . Los valores de miembro de esta enumeración se asignan al miembro dwSearchPref de la estructura ADS_SEARCHPREF_INFO .
El proveedor del sistema LDAP admite todas las opciones.
Dado que VBScript no puede leer datos de una biblioteca de tipos, las aplicaciones VBScript no reconocen las constantes simbólicas como se ha definido anteriormente. En su lugar, debe usar las constantes numéricas para establecer las marcas adecuadas en las aplicaciones vbScript. Para usar las constantes simbólicas, como práctica de programación recomendada, declare explícitamente estas constantes, como se hace aquí, en las aplicaciones VBScript.
Ejemplos
En el ejemplo de código siguiente se muestra cómo configurar las preferencias de búsqueda mediante la enumeración ADS_SEARCHPREF_INFO .
HRESULT SetSearchPreferences2(
DWORD dwScope,// -1 indicates default: subtree.
DWORD dwOverallTimeOut,// <=0 indicates default: no time out set.
DWORD dwOverallSizeLimit,// <=0 indicates default: no size limit set.
DWORD dwOverallTimeLimit,// <=0 indicates default: no time limit set.
BOOL bCacheResult,// TRUE indicates default.
BOOL bIsAsynchronous,// FALSE indicates default.
DWORD dwPageSize,// <=0 indicates default.
DWORD dwPageTimeLimit,// <=0 indicates default.
DWORD dwChaseReferral,// <=0 indicates default.
LPOLESTR szSortKey,// NULL indicates do not sort.
BOOL bIsDescending,
BOOL bReturnAttributeNamesOnly,// FALSE indicates default.
ADS_SEARCHPREF_INFO **ppSearchPref, // Return an array of search preferences.
DWORD *pdwSearchPrefCount
)
{
HRESULT hr = S_OK;
DWORD dwCountPref = 0L;
// Determine size of preferences array.
DWORD dwTotal = 11L;
if(dwScope==-1)
dwTotal--;
if(dwOverallTimeOut<=0)
dwTotal--;
if(dwOverallSizeLimit<=0)
dwTotal--;
if(dwOverallTimeLimit<=0)
dwTotal--;
if(bCacheResult)
dwTotal--;
if(!bIsAsynchronous)
dwTotal--;
if(dwPageSize<=0)
dwTotal--;
if(dwPageTimeLimit<=0)
dwTotal--;
if(dwChaseReferral<=0)
dwTotal--;
if(!bReturnAttributeNamesOnly)
dwTotal--;
if (!szSortKey)
dwTotal--;
ADS_SEARCHPREF_INFO *prefInfo = new ADS_SEARCHPREF_INFO[ dwTotal ];
ADS_SORTKEY SortKey;
if(!prefInfo)
{
return E_OUTOFMEMORY;
}
//////////////////
// Search Scope
//////////////////
if(dwScope>=0)
{
prefInfo[dwCountPref].dwSearchPref =
ADS_SEARCHPREF_SEARCH_SCOPE;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_INTEGER;
prefInfo[dwCountPref].vValue.Integer = dwScope;
dwCountPref++;
}
//////////////////
// Time Out
//////////////////
if(dwOverallTimeOut>0)
{
prefInfo[dwCountPref].dwSearchPref = ADS_SEARCHPREF_TIMEOUT;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_INTEGER;
prefInfo[dwCountPref].vValue.Integer = dwOverallTimeOut;
dwCountPref++;
}
///////////////
// Size Limit
///////////////
if(dwOverallSizeLimit>0)
{
prefInfo[dwCountPref].dwSearchPref = ADS_SEARCHPREF_SIZE_LIMIT;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_INTEGER;
prefInfo[dwCountPref].vValue.Integer = dwOverallSizeLimit;
dwCountPref++;
}
///////////////
// Time Limit
///////////////
if(dwOverallTimeLimit>0)
{
prefInfo[dwCountPref].dwSearchPref = ADS_SEARCHPREF_TIME_LIMIT;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_INTEGER;
prefInfo[dwCountPref].vValue.Integer = dwOverallTimeLimit;
dwCountPref++;
}
/////////////////
// Cache Result
/////////////////
if (!bCacheResult)
{
prefInfo[dwCountPref].dwSearchPref =
ADS_SEARCHPREF_CACHE_RESULTS;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_BOOLEAN;
prefInfo[dwCountPref].vValue.Boolean = bCacheResult;
dwCountPref++;
}
//////////////
// Page Size
//////////////
if(dwPageSize>0)
{
prefInfo[dwCountPref].dwSearchPref = ADS_SEARCHPREF_PAGESIZE;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_INTEGER;;
prefInfo[dwCountPref].vValue.Integer = dwPageSize;
dwCountPref++;
}
//////////////////
// Page Time Limit
//////////////////
if(dwPageTimeLimit>0)
{
prefInfo[dwCountPref].dwSearchPref =
ADS_SEARCHPREF_PAGED_TIME_LIMIT;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_INTEGER;;
prefInfo[dwCountPref].vValue.Integer = dwPageTimeLimit;
dwCountPref++;
}
///////////////////
// Chase Referrals
///////////////////
if(dwChaseReferral>0)
{
prefInfo[dwCountPref].dwSearchPref =
ADS_SEARCHPREF_CHASE_REFERRALS;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_INTEGER;
prefInfo[dwCountPref].vValue.Integer = dwChaseReferral;
dwCountPref++;
}
/////////////
// Sort
/////////////
if (szSortKey)
{
prefInfo[dwCountPref].dwSearchPref = ADS_SEARCHPREF_SORT_ON;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_PROV_SPECIFIC;
SortKey.pszAttrType = (LPWSTR)LocalAlloc(
LPTR,
wcslen(szSortKey)*sizeof(WCHAR) +sizeof(WCHAR)
);
wcscpy_s(SortKey.pszAttrType,szSortKey);
SortKey.pszReserved = NULL;
SortKey.fReverseorder = 0;
prefInfo[dwCountPref].vValue.ProviderSpecific.dwLength =
sizeof(ADS_SORTKEY);
prefInfo[dwCountPref].vValue.ProviderSpecific.lpValue =
(LPBYTE) &SortKey;
dwCountPref++;
}
/////////////////
// Asynchronous
/////////////////
if(bIsAsynchronous)
{
prefInfo[dwCountPref].dwSearchPref =
ADS_SEARCHPREF_ASYNCHRONOUS;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_BOOLEAN;
prefInfo[dwCountPref].vValue.Integer = bIsAsynchronous;
dwCountPref++;
}
////////////////////////
// Attribute Type Only
////////////////////////
if(bReturnAttributeNamesOnly)
{
prefInfo[dwCountPref].dwSearchPref =
ADS_SEARCHPREF_ATTRIBTYPES_ONLY;
prefInfo[dwCountPref].vValue.dwType = ADSTYPE_BOOLEAN;
prefInfo[dwCountPref].vValue.Integer =
bReturnAttributeNamesOnly;
dwCountPref++;
}
if (SUCCEEDED(hr))
{
*pdwSearchPrefCount = dwCountPref;
*ppSearchPref = prefInfo;
}
else
{
*pdwSearchPrefCount = 0L;
*ppSearchPref = NULL;
}
return hr;
}
Requisitos
| Cliente mínimo compatible | Windows Vista |
| Servidor mínimo compatible | Windows Server 2008 |
| Encabezado | iads.h |
Consulte también
IDirectorySearch::SetSearchPreference