IMAPITable::Restrict
S’applique à : Outlook 2013 | Outlook 2016
Applique un filtre à une table, en réduisant l’ensemble de lignes uniquement aux lignes correspondant aux critères spécifiés.
HRESULT Restrict(
LPSRestriction lpRestriction,
ULONG ulFlags
);
Paramètres
lpRestriction
[in] Pointeur vers une structure SRestriction définissant les conditions du filtre. La transmission de la valeur NULL dans le paramètre lpRestriction supprime le filtre actuel.
ulFlags
[in] Masque de bits des indicateurs qui contrôle le minutage de l’opération de restriction. Les indicateurs suivants peuvent être définis :
TBL_ASYNC
Démarre l’opération de façon asynchrone et retourne avant la fin de l’opération.
TBL_BATCH
Reporte l’évaluation du filtre jusqu’à ce que les données de la table soient requises.
Valeur renvoyée
S_OK
Le filtre a été correctement appliqué.
MAPI_E_BUSY
Une autre opération est en cours qui empêche l’opération de restriction de démarrer. Soit l’opération en cours doit être autorisée à se terminer, soit elle doit être arrêtée.
MAPI_E_TOO_COMPLEX
La table ne peut pas effectuer l’opération, car le filtre particulier vers lequel pointe le paramètre lpRestriction est trop compliqué.
Remarques
La méthode IMAPITable ::Restrict établit une restriction, ou un filtre, sur une table. S’il existe une restriction précédente, elle est ignorée et la nouvelle est appliquée. L’application d’une restriction n’a aucune incidence sur les données sous-jacentes d’une table ; Il modifie simplement la vue en limitant les lignes qui peuvent être récupérées aux lignes contenant des données qui satisfont à la restriction.
Il existe plusieurs types de restrictions, chacun décrit avec une structure différente. La structure SRestriction contient deux membres : une valeur qui indique le type de restriction et la structure spécifique applicable à ce type.
Les notifications pour les lignes de table masquées par les appels à Restrict ne sont jamais générées.
Une restriction de propriété sur une propriété à valeurs multiples fonctionne comme une restriction sur une propriété à valeur unique. Une propriété à valeurs multiples à utiliser dans une restriction de propriété doit avoir l’indicateur MVI_FLAG défini. S’il n’a pas cet indicateur défini, il est traité comme un tuple totalement ordonné. Une comparaison de deux colonnes à valeurs multiples compare les éléments de colonne dans l’ordre, en signalant la relation des colonnes à la première inégalité. L’égalité est retournée uniquement si les colonnes comparées contiennent les mêmes valeurs dans le même ordre. Si une colonne a moins de valeurs que l’autre, la relation signalée est celle d’une valeur null à l’autre valeur.
Pour plus d’informations sur les restrictions, consultez À propos des restrictions.
Remarque
Si vous créez des requêtes dynamiques pour rechercher des données sur le serveur, utilisez la méthode FindRow au lieu d’utiliser la méthode Restrict et la méthode QueryRows ensemble. La méthode Restrict crée une vue mise en cache qui est utilisée pour évaluer tous les messages ajoutés ou modifiés dans le dossier de base. Si une application cliente utilise la méthode Restrict pour chaque requête dynamique, une vue mise en cache est créée pour chaque requête.
Remarques pour les appelants
Pour ignorer la restriction actuelle sans en créer une nouvelle, passez NULL dans lpRestriction.
Si un autre appel de table asynchrone est en cours, ce qui entraîne le retour MAPI_E_BUSY, vous pouvez appeler IMAPITable ::Abort pour arrêter l’appel.
Restrict fonctionne de manière synchrone, sauf si vous définissez l’un des indicateurs. Si vous définissez l’indicateur TBL_BATCH, Restrict reporte l’évaluation de la restriction, sauf si vous demandez les données. Si l’indicateur TBL_ASYNC est défini, Restrictfonctionne de façon asynchrone, et peut être retourné avant la fin de l’opération.
Tous les signets d’une table sont ignorés lorsqu’un appel à Restrict est effectué et BOOKMARK_CURRENT, la position actuelle du curseur, est définie sur le début du tableau.
Si vous tentez d’imposer une restriction de propriété à une propriété qui ne figure pas dans le jeu de colonnes de la table, les résultats ne sont pas définis. Chaque fois que vous ne savez pas si une propriété est prise en charge dans une table, combinez la restriction de propriété avec une restriction exists. La restriction exists vérifie l’existence de la propriété avant de tenter d’imposer la restriction de propriété.
Ne vous attendez pas à recevoir une notification de table sur une ligne qui a été filtrée à partir d’une table en raison d’une restriction.
Référence MFCMAPI
Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.
| Fichier | Fonction | Commentaire |
|---|---|---|
| ContentsTableListCtrl.cpp |
CContentsTableListCtrl ::ApplyRestriction |
MFCMAPI utilise la méthode IMAPITable ::Restrict pour définir une restriction sur une table. |