перечисление ADS_SEARCHPREF_ENUM (iads.h)

Статья
08/24/2023

Перечисление 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_SECURITY_INFO_OWNER	Считывает данные владельца.
ADS_SECURITY_INFO_GROUP	Считывает данные группы.
ADS_SECURITY_INFO_DACL	Считывает список управления доступом на уровне пользователей (DACL).
ADS_SECURITY_INFO_SACL	Считывает системный список управления доступом (SACL).

Если вы считываете дескриптор безопасности без явного указания маски безопасности с помощью 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.

Идентификатор	Значение	Описание
LDAP_DIRSYNC_OBJECT_SECURITY	1	Если этот флаг отсутствует, вызывающий объект должен иметь право на репликацию изменений. Если этот флаг присутствует, вызывающий объект не требует прав, но ему разрешено видеть только объекты и атрибуты, доступные вызывающему объекту.
LDAP_DIRSYNC_ANCESTORS_FIRST_ORDER	2048 (0x00000800)	Возвращает родительские объекты перед дочерними объектами, если родительские объекты в противном случае появятся позже в потоке репликации.
LDAP_DIRSYNC_PUBLIC_DATA_ONLY	8192 (0x00002000)	Закрытые данные в результатах поиска не возвращаются.
LDAP_DIRSYNC_INCREMENTAL_VALUES	2147483648 (0x80000000)	Если этот флаг отсутствует, то при изменении значения возвращаются все значения, вплоть до заданного сервером лимита, в атрибуте с множеством значений. Если флаг представлен, возвращаются только измененные значения.

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