Platform SDK: Active Directory, ADSI, and Directory Services

ADS_SEARCHPREF_ENUM

The ADS_SEARCHPREF_ENUM enumeration specifies preferences for the directory search using IDirectorySearch methods.

typedef enum {
  ADS_SEARCHPREF_ASYNCHRONOUS     = 0,
  ADS_SEARCHPREF_DEREF_ALIASES    = 1,
  ADS_SEARCHPREF_SIZE_LIMIT       = 2,
  ADS_SEARCHPREF_TIME_LIMIT       = 3,
  ADS_SEARCHPREF_ATTRIBTYPES_ONLY = 4,
  ADS_SEARCHPREF_SEARCH_SCOPE     = 5,
  ADS_SEARCHPREF_TIMEOUT          = 6,
  ADS_SEARCHPREF_PAGESIZE         = 7,
  ADS_SEARCHPREF_PAGED_TIME_LIMIT = 8,
  ADS_SEARCHPREF_CHASE_REFERRALS  = 9,
  ADS_SEARCHPREF_SORT_ON          = 10,
  ADS_SEARCHPREF_CACHE_RESULTS    = 11,
  ADS_SEARCHPREF_DIRSYNC          = 12,
  ADS_SEARCHPREF_TOMBSTONE        = 13
  } ADS_SEARCHPREF_ENUM;

Elements

ADS_SEARCHPREF_ASYNCHRONOUS

Specifies that searches should be carried out in an asynchronous way.

ADS_SEARCHPREF_DEREF_ALIASES

Specifies that aliases of found objects are to be resolved. Use the ADS_DEREFENUM enumeration to specify how this should be done.

ADS_SEARCHPREF_SIZE_LIMIT

Specifies the size limit that the server should observe in a search. For Active Directory, the size limit specifies the maximum number of returned objects. The server stops searching once the size limit is reached and returns the results accumulated up to that point.

ADS_SEARCHPREF_TIME_LIMIT

Specifies the time limit (in seconds) for the search that the server should observe in a search. When the time limit is reached, the server stops searching and returns whatever results it has accumulated up to that point.

ADS_SEARCHPREF_ATTRIBTYPES_ONLY

Indicates that the search should obtain only the name of attributes to which values have been assigned.

ADS_SEARCHPREF_SEARCH_SCOPE

Specifies the search scope that should be observed by the server. For the appropriate settings, see the ADS_SCOPEENUM enumeration.

ADS_SEARCHPREF_TIMEOUT

Specifies the time limit (in seconds) that a client is willing to wait for the server to return the result. This option is set in an ADS_SEARCHPREF_INFO structure.

ADS_SEARCHPREF_PAGESIZE

Specifies the page size in a paged search. For each request by the client, the server returns at most the number of objects as set by the page size.

ADS_SEARCHPREF_PAGED_TIME_LIMIT

Specifies the time limit (in seconds) that the server should observe to search a page of results (as opposed to the time limit for the entire search). When the limit is reached, the server stops searching and returns the result obtained up to that point, along with a cookie containing the information about where to resume searching.

ADS_SEARCHPREF_CHASE_REFERRALS

Specifies that referrals may be chased. If the root search is not specified in the naming context of the server or when the search results cross a naming context (for example, when you have child domains and search in the parent domain), the server sends a referral message to the client which the client can choose to ignore or chase. For more information on referrals chasing, see ADS_CHASE_REFERRALS_ENUM.

ADS_SEARCHPREF_SORT_ON

Specifies that the server sorts the result set. Use the ADS_SORTKEY structure to specify the sort keys.

ADS_SEARCHPREF_CACHE_RESULTS

Specifies if the result should be cached on the client side. By default, ADSI caches the result set. Turning off this option may be more desirable for large result sets.

ADS_SEARCHPREF_DIRSYNC

Specifies a directory synchronization (DirSync) search, which returns all changes since a specified state. In the ADSVALUE structure, set the dwType member to ADSTYPE_PROV_SPECIFIC. The ProviderSpecific member is an ADS_PROV_SPECIFIC structure whose lpValue member specifies a "cookie" that indicates the state from which changes are retrieved. The first time you use the DirSync control, set the dwLength and lpValue members of the ADS_PROV_SPECIFIC structure to zero and NULL respectively. After reading through the results set returned by the search until IDirectorySearch::GetNextRow returns S_ADS_NOMORE_ROWS, call IDirectorySearch::GetColumn to retrieve the ADS_DIRSYNC_COOKIE attribute which contains a cookie to use in the next DirSync search. See Polling for Changes Using the DirSync Control.

This flag cannot be combined with ADS_SEARCHPREF_PAGESIZE.

The caller must have the SE_SYNC_AGENT_NAME privilege.

ADS_SEARCHPREF_TOMBSTONE

Specifies whether the search should also return deleted objects that match the search filter. When objects are deleted, Active Directory moves them to a "Deleted Objects" container. By default, deleted objects are not included in the search results. In the ADSVALUE structure, set the dwType member to ADSTYPE_BOOLEAN. To include deleted objects, set ADSVALUE.Boolean to TRUE.

Not all attributes are preserved when the object is deleted. You can retrieve the objectGUID and RDN attributes. The distinguishedName attribute is the DN of the object in the "Deleted Objects" container, not the previous DN. The isDeleted attribute is TRUE for a deleted object. See also Retrieving Deleted Objects.

Remarks

To set up a search preference, you assign appropriate values to the fields of an ADS_SEARCHPREF_INFO structure that will be passed to the server. To set up multiple preferences, you need to use an array of ADS_SEARCHPREF_INFO structures. The member values of this enumeration are assigned to the dwSearchPref field of the structure.

Note Because VBScript cannot read information from a type library, VBScript applications do not understand the symbolic constants as defined above. You should use the numerical constants instead to set the appropriate flags in your VBScript applications. If you want to use the symbolic constants as a good programming practice, you should make explicit declarations of such constants, as done here, in your VBScript applications.

Example Code [C++]

The following code snippet illustrates how to set up search preferences using the ADS_SEARCHPREF_ENUM enumeration.

HRESULT SetSearchPreferences2(
               DWORD dwScope,//-1 means use default: subtree
               DWORD dwOverallTimeOut,//<=0 means use default: no time out set.
               DWORD dwOverallSizeLimit,//<=0 means use default: no size limit set.
               DWORD dwOverallTimeLimit,//<=0 means use default: no time limit set.
               BOOL bCacheResult,//True means use default.
               BOOL bIsAsynchronous,//False means use default
               DWORD dwPageSize,//<=0 means use default
               DWORD dwPageTimeLimit,//<=0 means use default
               DWORD dwChaseReferral,//<=0 means use default
               LPOLESTR szSortKey,//NULL means don't sort.
               BOOL bIsDescending,
               BOOL bReturnAttributeNamesOnly,//False means use 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;
 
    //////////////////
    // 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(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;
}

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Iads.h.

ADS_SEARCHPREF_ENUM

Elements

Remarks

Example Code [C++]

Requirements

See Also