ADS_SEARCHPREF_ENUM列舉 (iads.h)
ADS_SEARCHPREF_ENUM列舉會指定IDirectorySearch物件的喜好設定。 這個列舉用於IDirectorySearch：：SetSearchPreference方法中ADS_SEARCHPREF_INFO結構的dwSearchPref成員。
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;
常數
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屬性是 「Deleted Objects」 容器中物件的 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_CACHE_RESULTSTRUE，則使用 ADS_SEARCHPREF_VLV時， 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 部分應為標準格式，則為零。 如需擴充辨別名稱的詳細資訊，請參閱 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。
提交並檢視相關的意見反應