перечисление ADS_SEARCHPREF_ENUM (iads.h)
Перечисление ADS_SEARCHPREF_ENUM задает параметры для объекта IDirectorySearch . Это перечисление используется в элементе dwSearchPrefструктуры ADS_SEARCHPREF_INFO в методе IDirectorySearch::SetSearchPreference .
Синтаксис
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;
Константы
ADS_SEARCHPREF_ASYNCHRONOUSЗначение: 0 Указывает, что поиск должен выполняться асинхронно. По умолчанию поиск выполняется синхронно. При синхронном поиске методы IDirectorySearch::GetFirstRow и IDirectorySearch::GetNextRow не возвращаются до тех пор, пока сервер не вернет весь результат или для поиска по страницам всю страницу. Асинхронный поиск блокируется до тех пор, пока не будет доступна одна строка результатов поиска или пока не истестеет интервал времени ожидания, заданный параметром ADS_SEARCHPREF_TIMEOUT поиска. |
|||||||||||||||||
ADS_SEARCHPREF_DEREF_ALIASESУказывает, что псевдонимы найденных объектов должны быть разрешены. Используйте перечисление ADS_DEREFENUM , чтобы указать, как это выполняется. |
|||||||||||||||||
ADS_SEARCHPREF_SIZE_LIMITУказывает ограничение размера, которое сервер должен соблюдать во время поиска. Сервер прекращает поиск по достижении предельного размера и возвращает результаты, накопленные к этой точке. Если это значение равно нулю, ограничение размера определяется службой каталогов. Значение по умолчанию для этого значения равно нулю. Если это значение превышает ограничение размера, определенное службой каталогов, приоритет имеет ограничение службы каталогов. Для Active Directory ограничение размера определяет максимальное количество объектов, возвращаемых при поиске. Кроме того, для Active Directory максимальное число объектов, возвращаемых при поиске, составляет 1000 объектов. |
|||||||||||||||||
ADS_SEARCHPREF_TIME_LIMITУказывает время в секундах, в течение которых сервер ожидает завершения поиска. По достижении предельного времени сервер прекращает поиск и возвращает результаты, накопленные к этой точке. Если это значение равно нулю, период ожидания будет бесконечным. Значение по умолчанию для этого значения — 120 секунд. |
|||||||||||||||||
ADS_SEARCHPREF_ATTRIBTYPES_ONLYУказывает, что поиск должен получить только имя атрибутов, которым назначены значения. |
|||||||||||||||||
ADS_SEARCHPREF_SEARCH_SCOPEУказывает область поиска, который должен наблюдаться сервером. Дополнительные сведения о соответствующих параметрах см. в перечислении ADS_SCOPEENUM . |
|||||||||||||||||
ADS_SEARCHPREF_TIMEOUTУказывает ограничение времени (в секундах), которое клиент будет ожидать, пока сервер вернет результат. Этот параметр задается в структуре ADS_SEARCHPREF_INFO . |
|||||||||||||||||
ADS_SEARCHPREF_PAGESIZEУказывает размер страницы в поиске по страницам. Для каждого запроса клиента сервер возвращает не более количества объектов, заданных размером страницы. Если задан размер страницы, устанавливать ограничение на размер не требуется. Если задано ограничение на размер, то значение размера страницы должно быть меньше значения ограничения размера. Если значение размера страницы превышает предельный размер, возвращается ERROR_DS_SIZELIMIT_EXCEEDED ошибка с количеством строк, заданных ограничением размера. |
|||||||||||||||||
ADS_SEARCHPREF_PAGED_TIME_LIMITУказывает время в секундах, в течение которых сервер должен ожидать страницу результатов поиска, а не ограничение по времени для всего поиска. По достижении предельного времени сервер прекращает поиск и возвращает результаты, полученные до этого момента, а также файл cookie, содержащий данные о том, где возобновить поиск. Если это значение равно нулю, период времени ожидания страницы будет бесконечным. Значение по умолчанию для этого ограничения — 120 секунд. |
|||||||||||||||||
ADS_SEARCHPREF_CHASE_REFERRALSУказывает, что рефералы могут преследоваться. Если корневой поиск не указан в контексте именования сервера или когда результаты поиска пересекают контекст именования, например, если у вас есть дочерние домены и поиск в родительском домене, сервер отправляет клиенту реферальные сообщения, которые клиент может игнорировать или преследовать. Дополнительные сведения о поиске рефералов см. в разделе ADS_CHASE_REFERRALS_ENUM. |
|||||||||||||||||
ADS_SEARCHPREF_SORT_ONУказывает, что сервер сортирует результирующий набор. Используйте структуру ADS_SORTKEY для указания ключей сортировки. Этот параметр поиска работает только для серверов каталогов, поддерживающих элемент управления LDAP для сортировки на стороне сервера. Active Directory поддерживает элемент управления сортировкой, но это может повлиять на производительность сервера, особенно если набор результатов большой. Active Directory поддерживает только один ключ сортировки. |
|||||||||||||||||
ADS_SEARCHPREF_CACHE_RESULTSУказывает, следует ли кэшировать результат на стороне клиента. По умолчанию ADSI кэширует результирующий набор. Отключение этого параметра может быть желательно для больших результирующих наборов. |
|||||||||||||||||
ADS_SEARCHPREF_DIRSYNCУказывает поиск синхронизации каталогов (DirSync), который возвращает все изменения с указанного состояния. В структуре ADSVALUE задайте для элемента dwTypeзначение ADS_PROV_SPECIFIC. Член ProviderSpecific — это структура ADS_PROV_SPECIFIC , член которой lpValue указывает файл cookie, указывающий состояние, из которого извлекаются изменения. При первом использовании элемента управления DirSync задайте для элементов dwLength и lpValue структуры ADS_PROV_SPECIFIC значения 0 и NULL соответственно. После считывания набора результатов, возвращаемого поиском, пока IDirectorySearch::GetNextRow не вернет S_ADS_NOMORE_ROWS, вызовите IDirectorySearch::GetColumn , чтобы получить атрибут ADS_DIRSYNC_COOKIE , содержащий файл cookie для использования в следующем поиске DirSync. Дополнительные сведения см. в разделе Опрос изменений с помощью элемента управления DirSync и LDAP_SERVER_DIRSYNC_OID. Этот флаг нельзя сочетать с ADS_SEARCHPREF_PAGESIZE. Вызывающий объект должен иметь привилегию SE_SYNC_AGENT_NAME . |
|||||||||||||||||
ADS_SEARCHPREF_TOMBSTONEУказывает, должен ли поиск также возвращать удаленные объекты, соответствующие фильтру поиска. При удалении объектов Active Directory перемещает их в контейнер "Удаленные объекты". По умолчанию удаленные объекты не включаются в результаты поиска. В структуре ADSVALUE задайте для элемента dwTypeзначение ADSTYPE_BOOLEAN. Чтобы включить удаленные объекты, задайте для логического элемента структуры ADSVALUEзначение TRUE. При удалении объекта сохраняются не все атрибуты. Можно получить атрибуты objectGUID и RDN . Атрибут distinguishedName — это DN объекта в контейнере "Удаленные объекты", а не предыдущее имя DN. Атрибут isDeleted имеет значение TRUE для удаленного объекта. Дополнительные сведения см. в разделе Извлечение удаленных объектов. |
|||||||||||||||||
ADS_SEARCHPREF_VLVУказывает, что поиск должен использовать элемент управления представление виртуального списка LDAP (VLV). ADS_SEARCHPREF_VLV можно использовать для доступа к поиску VLV строкового и смещения, задав соответствующие поля. Эти два параметра нельзя использовать одновременно, так как невозможно задать элемент управления VLV для запроса результирующий набор, расположенный с определенным смещением и следующий за определенным значением в последовательности сортировки. Чтобы выполнить поиск по строке, задайте для поля lpszTarget в ADS_VLV строку для поиска. Чтобы выполнить поиск по типу смещения, задайте поле dwOffset в ADS_VLV. При использовании поиска смещения необходимо задать для lpszTargetзначение NULL. при использовании ADS_SEARCHPREF_VLV ADS_SEARCHPREF_SORT_ON должно быть задано значение TRUE. Порядок сортировки результатов поиска определяет порядок, используемый для поиска VLV. При выполнении поиска по типу смещения смещение используется в качестве индекса в отсортированный список. При выполнении поиска строкового типа сервер пытается вернуть первую запись, которая больше или равна строке, в зависимости от порядка сортировки. Кэширование результатов поиска отключается при указании ADS_SEARCHPREF_VLV . Если при использовании ADS_SEARCHPREF_VLVназначить ADS_SEARCHPREF_CACHE_RESULTS значение TRUE, setSearchPreference завершится ошибкой и вернет E_ADS_BAD_PARAMETER ошибки. |
|||||||||||||||||
ADS_SEARCHPREF_ATTRIBUTE_QUERYУказывает, что должен выполняться поиск запроса с областью атрибута. Поиск выполняется для этих объектов с именами в указанном атрибуте базового объекта. Элемент vValue структуры ADS_SEARCHPREF_INFO содержит значение ADSTYPE_CASE_IGNORE_STRING , содержащее lDAPDisplayName атрибута для поиска. Этот атрибут должен быть ADS_DN_STRING атрибутом. Можно указать только один атрибут. При использовании этого параметра область поиска автоматически устанавливается значение ADS_SCOPE_BASE, а попытка задать область в противном случае приведет к сбою с E_ADS_BAD_PARAMETER ошибки. За исключением предпочтения ADS_SEARCHPREF_VLV , все остальные настройки, использующие элементы управления LDAP, такие как ADS_SEARCHPREF_DIRSYNC, ADS_SEARCHPREF_TOMBSTONE и т. д., не допускаются при указании этого параметра. |
|||||||||||||||||
ADS_SEARCHPREF_SECURITY_MASKУказывает, что поиск должен возвращать данные доступа к безопасности для указанных атрибутов. Элемент vValue структуры ADS_SEARCHPREF_INFO содержит ADS_INTEGER значение, которое представляет собой сочетание одного или нескольких из следующих значений.
Если вы считываете дескриптор безопасности без явного указания маски безопасности с помощью ADS_SEARCHPREF_SECURITY_MASK, по умолчанию используется эквивалент ADS_SECURITY_INFO_OWNER |
ADS_SECURITY_INFO_GROUP | ADS_SECURITY_INFO_DACL. | |||||||||||||||
ADS_SEARCHPREF_DIRSYNC_FLAGСодержит необязательные флаги для использования с параметром поиска ADS_SEARCHPREF_DIRSYNC . Элемент vValue структуры ADS_SEARCHPREF_INFO содержит ADSTYPE_INTEGER значение, равное нулю, или сочетание одного или нескольких из следующих значений. Дополнительные сведения об элементе управления DirSync см. в разделе Опрос изменений с помощью элемента управления DirSync и LDAP_SERVER_DIRSYNC_OID.
|
|||||||||||||||||
ADS_SEARCHPREF_EXTENDED_DNПоиск должен возвращать различающиеся имена в расширенном формате Active Directory. Элемент vValue структуры ADS_SEARCHPREF_INFO содержит значение ADSTYPE_INTEGER , содержащее ноль, если части GUID и SID строки DN должны быть в шестнадцатеричном формате или один, если части GUID и SID строки DN должны быть в стандартном формате. Дополнительные сведения о расширенных различающихся именах см. в разделе LDAP_SERVER_EXTENDED_DN_OID. |
Комментарии
Чтобы настроить предпочтения поиска, назначьте соответствующие значения полям структуры ADS_SEARCHPREF_INFO , передаваемой на сервер. Элемент vValueструктуры ADS_SEARCHPREF_INFO является структурой ADSVALUE . В следующем списке перечислены ADS_SEARCHPREF_ENUM значения, соответствующие значения для элемента dwType структуры ADSVALUE и члена ADSVALUE , используемого для указанного типа.
| значение ADS_SEARCHPREF_ENUM | Элемент dwTypeобъекта ADSVALUE | Элемент ADSVALUE |
|---|---|---|
| ADS_SEARCHPREF_ASYNCHRONOUS | ADSTYPE_BOOLEAN | Boolean |
| ADS_SEARCHPREF_DEREF_ALIASES | ADSTYPE_INTEGER | Целое число |
| ADS_SEARCHPREF_SIZE_LIMIT | ADSTYPE_INTEGER | Целое число |
| ADS_SEARCHPREF_TIME_LIMIT | ADSTYPE_INTEGER | Целое число |
| ADS_SEARCHPREF_ATTRIBTYPES_ONLY | ADSTYPE_BOOLEAN | Boolean |
| ADS_SEARCHPREF_SEARCH_SCOPE | ADSTYPE_INTEGER | Целое число |
| ADS_SEARCHPREF_TIMEOUT | ADSTYPE_INTEGER | Целое число |
| ADS_SEARCHPREF_PAGESIZE | ADSTYPE_INTEGER | Целое число |
| ADS_SEARCHPREF_PAGED_TIME_LIMIT | ADSTYPE_INTEGER | Целое число |
| ADS_SEARCHPREF_CHASE_REFERRALS | ADSTYPE_INTEGER | Целое число |
| 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 | Целое число |
| ADS_SEARCHPREF_DIRSYNC_FLAG | ADSTYPE_INTEGER | Целое число |
| ADS_SEARCHPREF_EXTENDED_DN | ADSTYPE_INTEGER | Целое число |
Чтобы настроить несколько параметров, используйте массив ADS_SEARCHPREF_INFO структур. Значения элементов этого перечисления назначаются элементу dwSearchPrefструктуры ADS_SEARCHPREF_INFO .
Все параметры поддерживаются поставщиком системы LDAP.
Так как VBScript не может считывать данные из библиотеки типов, приложения VBScript не распознают символьные константы, как определено выше. Вместо этого следует использовать числовые константы для установки соответствующих флагов в приложениях VBScript. Чтобы использовать символьные константы, в качестве рекомендуемой практики программирования явно объявите такие константы, как показано здесь, в приложениях VBScript.
Примеры
В следующем примере кода показано, как настроить параметры поиска с помощью перечисления 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;
}
Требования
| Минимальная версия клиента | Windows Vista |
| Минимальная версия сервера | Windows Server 2008 |
| Верхняя часть | iads.h |
См. также раздел
IDirectorySearch::SetSearchPreference
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по