IMAPIContainer::SetSearchCriteria
S’applique à : Outlook 2013 | Outlook 2016
Établit des critères de recherche pour le conteneur.
HRESULT SetSearchCriteria(
LPSRestriction lpRestriction,
LPENTRYLIST lpContainerList,
ULONG ulSearchFlags
);
Paramètres
lpRestriction
[in] Pointeur vers une structure SRestriction qui définit les critères de recherche. Si NULL est passé dans le paramètre lpRestriction , les critères de recherche qui ont été utilisés le plus récemment pour ce conteneur sont réutilisés. Null ne doit pas être passé dans lpRestriction pour la première recherche dans un conteneur.
lpContainerList
[in] Pointeur vers un tableau d’identificateurs d’entrée qui représentent les conteneurs à inclure dans la recherche. Si un client transmet NULL dans le paramètre lpContainerList , les identificateurs d’entrée utilisés récemment pour rechercher ce conteneur sont utilisés pour la nouvelle recherche. Un client ne doit pas passer NULL dans lpContainerList pour la première recherche dans un conteneur.
ulSearchFlags
[in] Masque de bits d’indicateurs qui contrôlent la façon dont la recherche est effectuée. Les indicateurs suivants peuvent être définis :
BACKGROUND_SEARCH
La recherche doit s’exécuter avec une priorité normale par rapport aux autres recherches. Cet indicateur ne peut pas être défini en même temps que l’indicateur FOREGROUND_SEARCH.
FOREGROUND_SEARCH
La recherche doit s’exécuter avec une priorité élevée par rapport aux autres recherches. Cet indicateur ne peut pas être défini en même temps que l’indicateur BACKGROUND_SEARCH.
NON_CONTENT_INDEXED_SEARCH
La recherche ne doit pas utiliser l’indexation de contenu pour rechercher les entrées correspondantes. Cet indicateur est valide uniquement pour les magasins Exchange.
RECURSIVE_SEARCH
La recherche doit inclure les conteneurs spécifiés dans le paramètre lpContainerList et tous leurs conteneurs enfants. Cet indicateur ne peut pas être défini en même temps que l’indicateur SHALLOW_SEARCH.
RESTART_SEARCH
La recherche doit être lancée s’il s’agit du premier appel à SetSearchCriteria, ou redémarrée si la recherche est inactive. Cet indicateur ne peut pas être défini en même temps que l’indicateur STOP_SEARCH.
SHALLOW_SEARCH
La recherche doit rechercher uniquement dans les conteneurs spécifiés dans le paramètre lpContainerList pour les entrées correspondantes. Cet indicateur ne peut pas être défini en même temps que l’indicateur RECURSIVE_SEARCH.
STOP_SEARCH
La recherche doit être arrêtée. Cet indicateur ne peut pas être défini en même temps que l’indicateur RESTART_SEARCH.
Valeur renvoyée
S_OK
Les critères de recherche ont été correctement définis.
MAPI_E_TOO_COMPLEX
Le fournisseur de services ne prend pas en charge les critères de recherche spécifiés.
Remarques
La méthode IMAPIContainer ::SetSearchCriteria établit des critères de recherche pour un conteneur qui prend en charge les recherches, généralement un dossier de résultats de recherche. Un dossier search-results contient des liens vers les messages qui répondent aux critères de recherche ; les messages réels sont toujours stockés à leur emplacement d’origine. Les seules données uniques contenues dans un dossier de résultats de recherche sont sa table de contenu. La table des matières d’un dossier search-results contient le contenu fusionné de la banque de messages après l’application de la restriction de recherche.
Une opération de recherche fonctionne uniquement sur cette table de contenu fusionnée ; il ne recherche pas dans d’autres dossiers de résultats de recherche. Les résultats de la recherche retournent uniquement les messages qui correspondent aux critères de recherche ; la hiérarchie de dossiers n’est pas retournée.
Le contrôle est retourné au client une fois la recherche terminée.
Remarques pour les responsables de l’implémentation
Les conteneurs de carnets d’adresses établissent des critères de recherche en appliquant des restrictions à leurs tables de contenu. Pour plus d’informations sur les critères de recherche et les conteneurs de carnet d’adresses, consultez Implémentation de la recherche avancée.
Vous devez prendre en charge les opérations d’ouverture, de copie, de déplacement et de suppression sur les messages dans les dossiers de résultats de recherche, et non sur le dossier search-results lui-même. N’autorisez pas la création ou la copie de messages dans un dossier de résultats de recherche.
Remarques pour les appelants
Pour rechercher les destinataires des messages, définissez lpRestriction pour qu’il pointe vers une restriction de sous-objet avec le membre ulSubObject dans la structure SSubRestriction défini sur PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients). Pour rechercher des pièces jointes, définissez le membre ulSubObjectsur PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments). Définissez le membre lpRes pour qu’il pointe vers une restriction de propriété qui décrit les critères de recherche des destinataires ou des pièces jointes.
Par exemple, pour rechercher les fichiers joints qui ont l’extension .mss, définissez ulSubObject sur PR_MESSAGE_ATTACHMENTS et lpRes sur une restriction de propriété qui correspond à PR_ATTACH_EXTENSION (PidTagAttachExtension) avec .mss.
La définition de l’indicateur FOREGROUND_SEARCH dans le paramètre ulSearchFlags peut entraîner une diminution des performances du système.
Vous pouvez utiliser SetSearchCriteria pour modifier les critères de recherche d’une recherche déjà en cours. Vous pouvez spécifier de nouvelles restrictions, de nouvelles listes de dossiers à rechercher et une nouvelle priorité de recherche, comme la mise à niveau d’une recherche vers une priorité plus élevée. Les modifications apportées à la priorité de recherche n’entraînent pas le redémarrage d’une recherche existante, mais d’autres modifications apportées aux critères de recherche le peuvent.
Lorsque vous utilisez un dossier de résultats de recherche, vous pouvez supprimer le dossier ou le laisser ouvert pour une utilisation ultérieure. Si vous supprimez le dossier search-results, seuls les liens de message sont supprimés. Les messages réels restent dans leurs dossiers parents.
Pour plus d’informations sur les dossiers de résultats de recherche, consultez Dossiers de recherche MAPI.
Référence MFCMAPI
Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.
| Fichier | Fonction | Commentaire |
|---|---|---|
| HierarchyTableDlg.cpp |
CHierarchyTableDlg ::OnEditSearchCriteria |
MFCMAPI utilise la méthode IMAPIContainer ::SetSearchCriteria pour écrire des critères de recherche pour un dossier après qu’un utilisateur l’a modifié. |