ADS_SEARCHPREF_ENUM 枚举 (iads.h)
ADS_SEARCHPREF_ENUM 枚举指定 IDirectorySearch 对象的首选项。 此枚举用于 IDirectorySearch：：SetSearchPreference 方法中 ADS_SEARCHPREF_INFO 结构的 dwSearchPref 成员。
语法
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 控件时，请将ADS_PROV_SPECIFIC结构的 dwLength 和 lpValue 成员分别设置为零和 NULL。 读取搜索返回的结果集，直到 IDirectorySearch：：GetNextRow 返回 S_ADS_NOMORE_ROWS，然后调用 IDirectorySearch：：GetColumn 以检索包含要用于下一个 DirSync 搜索的 cookie 的 ADS_DIRSYNC_COOKIE 属性。 有关详细信息，请参阅 使用 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 控件来请求位于特定偏移量且遵循排序序列中特定值的结果集。 若要执行字符串搜索，请将 ADS_VLV 中的 lpszTarget 字段设置为要搜索的字符串。 若要执行偏移类型搜索，请在 ADS_VLV 中设置 dwOffset 字段。 如果使用偏移量搜索，则必须将 lpszTarget 设置为 NULL。 使用 ADS_SEARCHPREF_VLV 时，必须将ADS_SEARCHPREF_SORT_ON设置为 TRUE。 搜索结果的排序顺序决定了用于 VLV 搜索的顺序。 如果执行偏移类型搜索，则偏移量将用作排序列表中的索引。 如果执行字符串类型搜索，服务器会尝试根据排序顺序返回大于或等于字符串的第一个条目。 指定 ADS_SEARCHPREF_VLV 时，将禁用搜索结果的缓存。 如果使用 ADS_SEARCHPREF_VLV 分配ADS_SEARCHPREF_CACHE_RESULTSTRUE，则 SetSearchPreference 将失败并返回错误E_ADS_BAD_PARAMETER。 |
|||||||||||||||||
ADS_SEARCHPREF_ATTRIBUTE_QUERY指定应执行属性范围的查询搜索。 对基对象的指定属性中命名的对象执行搜索。 ADS_SEARCHPREF_INFO 结构的 vValue 成员包含一个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指定搜索应返回指定属性的安全访问数据。 ADS_SEARCHPREF_INFO 结构的 vValue 成员包含一个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 搜索首选项一起使用的可选标志。 ADS_SEARCHPREF_INFO 结构的 vValue 成员包含一个ADSTYPE_INTEGER值，该值为零或以下一个或多个值的组合。 有关 DirSync 控件的详细信息，请参阅 使用 DirSync 控件轮询更改 和 LDAP_SERVER_DIRSYNC_OID。
|
|||||||||||||||||
ADS_SEARCHPREF_EXTENDED_DN搜索应返回 Active Directory 扩展格式的可分辨名称。 如果 DN 字符串的 GUID 和 SID 部分应采用十六进制格式，则 ADS_SEARCHPREF_INFO 结构的 vValue 成员包含一个包含零的 ADSTYPE_INTEGER 值;如果 DN 字符串的 GUID 和 SID 部分应采用标准格式，则为 0。 有关扩展的可分辨名称的详细信息，请参阅 LDAP_SERVER_EXTENDED_DN_OID。 |
注解
若要设置搜索首选项，请将适当的值分配给传递给服务器的 ADS_SEARCHPREF_INFO 结构的字段。 ADS_SEARCHPREF_INFO 结构的 vValue 成员是 ADSVALUE 结构。 以下列表列出了ADS_SEARCHPREF_ENUM值、ADSVALUE 结构的 dwType 成员的相应值，以及用于指定类型的 ADSVALUE 成员。
| ADS_SEARCHPREF_ENUM 值 | ADSVALUE 的 dwType 成员 | ADSVALUE 成员 |
|---|---|---|
| ADS_SEARCHPREF_ASYNCHRONOUS | ADSTYPE_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 | 布尔值 |
| 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 | 布尔值 |
| ADS_SEARCHPREF_DIRSYNC | ADSTYPE_PROV_SPECIFIC | ProviderSpecific |
| ADS_SEARCHPREF_TOMBSTONE | ADSTYPE_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 结构数组。 此枚举的成员值分配给 ADS_SEARCHPREF_INFO 结构的 dwSearchPref 成员。
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 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈