énumération ADS_SEARCHPREF_ENUM (iads.h)
L’énumération ADS_SEARCHPREF_ENUM spécifie les préférences d’un objet IDirectorySearch. Cette énumération est utilisée dans le membre dwSearchPref de la structure ADS_SEARCHPREF_INFO dans la méthode IDirectorySearch::SetSearchPreference .
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;
Constantes
ADS_SEARCHPREF_ASYNCHRONOUSValeur : 0 Spécifie que les recherches doivent être effectuées de manière asynchrone. Par défaut, les recherches sont synchrones. Dans une recherche synchrone, les méthodes IDirectorySearch::GetFirstRow et IDirectorySearch::GetNextRow ne retournent pas tant que le serveur n’a pas retourné le résultat entier ou, pour une recherche paginée, la page entière. Une recherche asynchrone se bloque jusqu’à ce qu’une ligne des résultats de la recherche soit disponible, ou jusqu’à ce que l’intervalle de délai d’expiration spécifié par la préférence de recherche ADS_SEARCHPREF_TIMEOUT s’écoule. |
|||||||||||||||||
ADS_SEARCHPREF_DEREF_ALIASESSpécifie que les alias des objets trouvés doivent être résolus. Utilisez l’énumération ADS_DEREFENUM pour spécifier la façon dont cette opération est effectuée. |
|||||||||||||||||
ADS_SEARCHPREF_SIZE_LIMITSpécifie la limite de taille que le serveur doit observer pendant une recherche. Le serveur arrête la recherche lorsque la limite de taille est atteinte et retourne les résultats accumulés à ce point. Si cette valeur est égale à zéro, la limite de taille est déterminée par le service d’annuaire. La valeur par défaut de cette valeur est zéro. Si cette valeur est supérieure à la limite de taille déterminée par le service d’annuaire, la limite du service d’annuaire est prioritaire. Pour Active Directory, la limite de taille spécifie le nombre maximal d’objets à retourner par la recherche. De même, pour Active Directory, le nombre maximal d’objets retournés par une recherche est de 1 000 objets. |
|||||||||||||||||
ADS_SEARCHPREF_TIME_LIMITSpécifie le nombre de secondes pendant lesquelles le serveur attend la fin d’une recherche. Lorsque la limite de temps est atteinte, le serveur cesse de rechercher et retourne les résultats accumulés jusqu’à ce point. Si cette valeur est égale à zéro, le délai d’expiration est infini. La valeur par défaut pour cette valeur est 120 secondes. |
|||||||||||||||||
ADS_SEARCHPREF_ATTRIBTYPES_ONLYIndique que la recherche doit obtenir uniquement le nom des attributs auxquels les valeurs sont affectées. |
|||||||||||||||||
ADS_SEARCHPREF_SEARCH_SCOPESpécifie l’étendue de recherche qui doit être observée par le serveur. Pour plus d’informations sur les paramètres appropriés, consultez l’énumération ADS_SCOPEENUM . |
|||||||||||||||||
ADS_SEARCHPREF_TIMEOUTSpécifie la limite de temps, en secondes, pendant laquelle un client attend que le serveur retourne le résultat. Cette option est définie dans une structure ADS_SEARCHPREF_INFO . |
|||||||||||||||||
ADS_SEARCHPREF_PAGESIZESpécifie la taille de page dans une recherche paginée. Pour chaque requête du client, le serveur retourne, au maximum, le nombre d’objets tel que défini par la taille de page. Lorsque la taille de page est définie, il n’est pas nécessaire de définir la limite de taille. Si une limite de taille est définie, la valeur de la taille de page doit être inférieure à la valeur de la limite de taille. Si la valeur de la taille de la page dépasse la limite de taille, l’erreur ERROR_DS_SIZELIMIT_EXCEEDED est retournée avec le nombre de lignes spécifié par la limite de taille. |
|||||||||||||||||
ADS_SEARCHPREF_PAGED_TIME_LIMITSpécifie le nombre de secondes pendant lesquelles le serveur doit attendre une page de résultats de recherche, par opposition à la limite de temps pour l’ensemble de la recherche. Lorsque la limite de temps est atteinte, le serveur arrête la recherche et retourne les résultats obtenus jusqu’à ce point, ainsi qu’un cookie qui contient les données sur l’endroit où reprendre la recherche. Si cette valeur est égale à zéro, le délai d’expiration de la page est infini. La valeur par défaut de cette limite est de 120 secondes. |
|||||||||||||||||
ADS_SEARCHPREF_CHASE_REFERRALSSpécifie que les références peuvent être poursuivies. Si la recherche racine n’est pas spécifiée dans le contexte d’affectation de noms du serveur ou lorsque les résultats de la recherche croisent un contexte de nommage, par exemple, lorsque vous avez des domaines enfants et que vous effectuez une recherche dans le domaine parent, le serveur envoie un message de référence au client que le client peut choisir d’ignorer ou de poursuivre. Pour plus d’informations sur la poursuite des références, consultez ADS_CHASE_REFERRALS_ENUM. |
|||||||||||||||||
ADS_SEARCHPREF_SORT_ONSpécifie que le serveur trie le jeu de résultats. Utilisez la structure ADS_SORTKEY pour spécifier les clés de tri. Cette préférence de recherche fonctionne uniquement pour les serveurs d’annuaire qui prennent en charge le contrôle LDAP pour le tri côté serveur. Active Directory prend en charge le contrôle de tri, mais il peut avoir un impact sur les performances du serveur, en particulier si le jeu de résultats est volumineux. Active Directory ne prend en charge qu’une seule clé de tri. |
|||||||||||||||||
ADS_SEARCHPREF_CACHE_RESULTSSpécifie si le résultat doit être mis en cache côté client. Par défaut, ADSI met en cache le jeu de résultats. La désactivation de cette option peut être souhaitable pour les jeux de résultats volumineux. |
|||||||||||||||||
ADS_SEARCHPREF_DIRSYNCSpécifie une recherche de synchronisation d’annuaires (DirSync) qui retourne toutes les modifications depuis un état spécifié. Dans la structure ADSVALUE , définissez le membre dwTypesur ADS_PROV_SPECIFIC. Le membre ProviderSpecific est une structure ADS_PROV_SPECIFIC dont le membre lpValue spécifie un cookie qui indique l’état à partir duquel les modifications sont récupérées. La première fois que vous utilisez le contrôle DirSync, définissez les membres dwLength et lpValue de la structure ADS_PROV_SPECIFIC respectivement sur zéro et NULL . Après avoir lu le jeu de résultats retourné par la recherche jusqu’à ce que IDirectorySearch::GetNextRow retourne S_ADS_NOMORE_ROWS, appelez IDirectorySearch::GetColumn pour récupérer l’attribut ADS_DIRSYNC_COOKIE qui contient un cookie à utiliser dans la prochaine recherche DirSync. Pour plus d’informations, consultez Interrogation des modifications à l’aide du contrôle DirSync et LDAP_SERVER_DIRSYNC_OID. Cet indicateur ne peut pas être combiné avec ADS_SEARCHPREF_PAGESIZE. L’appelant doit disposer du privilège SE_SYNC_AGENT_NAME . |
|||||||||||||||||
ADS_SEARCHPREF_TOMBSTONESpécifie si la recherche doit également retourner des objets supprimés qui correspondent au filtre de recherche. Lorsque des objets sont supprimés, Active Directory les déplace vers un conteneur « Objets supprimés ». Par défaut, les objets supprimés ne sont pas inclus dans les résultats de la recherche. Dans la structure ADSVALUE , définissez le membre dwTypesur ADSTYPE_BOOLEAN. Pour inclure des objets supprimés, définissez le membre booléen de la structure ADSVALUE sur TRUE. Tous les attributs ne sont pas conservés lorsque l’objet est supprimé. Vous pouvez récupérer les attributs objectGUID et RDN . L’attribut distinguishedName est le DN de l’objet dans le conteneur « Objets supprimés », et non le nom de domaine précédent. L’attribut isDeleted a la valeur TRUE pour un objet supprimé. Pour plus d’informations, consultez Récupération d’objets supprimés. |
|||||||||||||||||
ADS_SEARCHPREF_VLVSpécifie que la recherche doit utiliser le contrôle VLV (Ldap Virtual List View). ADS_SEARCHPREF_VLV pouvez être utilisé pour accéder aux recherches VLV de type chaîne et de type offset, en définissant les champs appropriés. Ces deux options ne peuvent pas être utilisées simultanément, car il n’est pas possible de définir le contrôle VLV pour demander un jeu de résultats situé à la fois à un décalage spécifique et qui suit une valeur particulière dans la séquence de tri. Pour effectuer une recherche de chaîne, définissez le champ lpszTarget dans ADS_VLV sur la chaîne à rechercher. Pour effectuer une recherche de type offset, définissez le champ dwOffset dans ADS_VLV. Si vous utilisez une recherche par décalage, vous devez définir lpszTarget surNULL. ADS_SEARCHPREF_SORT_ON doit avoir la valeur TRUE lors de l’utilisation de ADS_SEARCHPREF_VLV. L’ordre de tri des résultats de la recherche détermine l’ordre utilisé pour la recherche VLV. Si vous effectuez une recherche de type offset, le décalage est utilisé comme index dans la liste triée. Si vous effectuez une recherche de type chaîne, le serveur tente de retourner la première entrée qui est supérieure ou égale à la chaîne, en fonction de l’ordre de tri. La mise en cache des résultats de la recherche est désactivée lorsque ADS_SEARCHPREF_VLV est spécifié. Si vous affectez ADS_SEARCHPREF_CACHE_RESULTS valeur TRUE lors de l’utilisation de ADS_SEARCHPREF_VLV, SetSearchPreference échoue et retourne l’erreur E_ADS_BAD_PARAMETER. |
|||||||||||||||||
ADS_SEARCHPREF_ATTRIBUTE_QUERYSpécifie qu’une recherche de requête étendue aux attributs doit être effectuée. La recherche est effectuée sur ces objets nommés dans un attribut spécifié de l’objet de base. Le membre vValue de la structure ADS_SEARCHPREF_INFO contient une valeur ADSTYPE_CASE_IGNORE_STRING qui contient l’attribut lDAPDisplayName de l’attribut à rechercher. Cet attribut doit être un attribut ADS_DN_STRING . Un seul attribut peut être spécifié. L’étendue de la recherche est automatiquement définie sur ADS_SCOPE_BASE lors de l’utilisation de cette préférence. Sinon, toute tentative de définition de l’étendue échoue avec l’erreur E_ADS_BAD_PARAMETER. À l’exception de la préférence ADS_SEARCHPREF_VLV , toutes les autres préférences qui utilisent des contrôles LDAP, tels que ADS_SEARCHPREF_DIRSYNC, ADS_SEARCHPREF_TOMBSTONE, etc., ne sont pas autorisées lorsque cette préférence est spécifiée. |
|||||||||||||||||
ADS_SEARCHPREF_SECURITY_MASKSpécifie que la recherche doit retourner des données d’accès de sécurité pour les attributs spécifiés. Le membre vValue de la structure ADS_SEARCHPREF_INFO contient une valeur ADS_INTEGER qui est une combinaison d’une ou plusieurs des valeurs suivantes.
Si vous lisez un descripteur de sécurité sans spécifier explicitement de masque de sécurité à l’aide de ADS_SEARCHPREF_SECURITY_MASK, il est l’équivalent par défaut de ADS_SECURITY_INFO_OWNER |
ADS_SECURITY_INFO_GROUP | ADS_SECURITY_INFO_DACL. | |||||||||||||||
ADS_SEARCHPREF_DIRSYNC_FLAGContient des indicateurs facultatifs à utiliser avec la préférence de recherche ADS_SEARCHPREF_DIRSYNC . Le membre vValue de la structure ADS_SEARCHPREF_INFO contient une valeur ADSTYPE_INTEGER égale à zéro ou une combinaison d’une ou plusieurs des valeurs suivantes. Pour plus d’informations sur le contrôle DirSync, consultez Interrogation des modifications à l’aide du contrôle DirSync et LDAP_SERVER_DIRSYNC_OID.
|
|||||||||||||||||
ADS_SEARCHPREF_EXTENDED_DNLa recherche doit retourner des noms uniques au format étendu Active Directory. Le membre vValue de la structure ADS_SEARCHPREF_INFO contient une valeur ADSTYPE_INTEGER qui contient zéro si les parties GUID et SID de la chaîne DN doivent être au format hexadécimal ou une autre si les parties GUID et SID de la chaîne DN doivent être au format standard. Pour plus d’informations sur les noms uniques étendus, consultez LDAP_SERVER_EXTENDED_DN_OID. |
Notes
Pour configurer une préférence de recherche, affectez les valeurs appropriées aux champs d’une structure de ADS_SEARCHPREF_INFO passée au serveur. Le membre vValue de la structure ADS_SEARCHPREF_INFO est une structure ADSVALUE . La liste suivante répertorie les valeurs ADS_SEARCHPREF_ENUM , les valeurs correspondantes pour le membre dwType de la structure ADSVALUE et le membre ADSVALUE utilisé pour le type spécifié.
| ADS_SEARCHPREF_ENUM valeur | membre dwTyped’ADSVALUE | Membre ADSVALUE |
|---|---|---|
| ADS_SEARCHPREF_ASYNCHRONOUS | ADSTYPE_BOOLEAN | Booléen |
| ADS_SEARCHPREF_DEREF_ALIASES | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_SIZE_LIMIT | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_TIME_LIMIT | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_ATTRIBTYPES_ONLY | ADSTYPE_BOOLEAN | Booléen |
| ADS_SEARCHPREF_SEARCH_SCOPE | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_TIMEOUT | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_PAGESIZE | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_PAGED_TIME_LIMIT | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_CHASE_REFERRALS | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_SORT_ON | ADSTYPE_PROV_SPECIFIC | ProviderSpecific |
| ADS_SEARCHPREF_CACHE_RESULTS | ADSTYPE_BOOLEAN | Booléen |
| ADS_SEARCHPREF_DIRSYNC | ADSTYPE_PROV_SPECIFIC | ProviderSpecific |
| ADS_SEARCHPREF_TOMBSTONE | ADSTYPE_BOOLEAN | Booléen |
| ADS_SEARCHPREF_VLV | ADSTYPE_PROV_SPECIFIC | ProviderSpecific |
| ADS_SEARCHPREF_ATTRIBUTE_QUERY | ADSTYPE_CASE_IGNORE_STRING | CaseIgnoreString |
| ADS_SEARCHPREF_SECURITY_MASK | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_DIRSYNC_FLAG | ADSTYPE_INTEGER | Integer |
| ADS_SEARCHPREF_EXTENDED_DN | ADSTYPE_INTEGER | Integer |
Pour configurer plusieurs préférences, utilisez un tableau de structures ADS_SEARCHPREF_INFO . Les valeurs membres de cette énumération sont affectées au membre dwSearchPref de la structure ADS_SEARCHPREF_INFO .
Toutes les options sont prises en charge par le fournisseur de système LDAP.
Étant donné que VBScript ne peut pas lire les données d’une bibliothèque de types, les applications VBScript ne reconnaissent pas les constantes symboliques définies ci-dessus. Vous devez utiliser les constantes numériques à la place pour définir les indicateurs appropriés dans vos applications VBScript. Pour utiliser les constantes symboliques, comme bonne pratique de programmation, déclarez explicitement ces constantes, comme cela est fait ici, dans vos applications VBScript.
Exemples
L’exemple de code suivant montre comment configurer les préférences de recherche à l’aide de l’énumération 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;
}
Configuration requise
| Client minimal pris en charge | Windows Vista |
| Serveur minimal pris en charge | Windows Server 2008 |
| En-tête | iads.h |
Voir aussi
IDirectorySearch::SetSearchPreference
Interrogation des modifications à l’aide du contrôle DirSync