IMAPITable::FindRow
S’applique à : Outlook 2013 | Outlook 2016
Recherche la ligne suivante dans un tableau qui correspond à des critères de recherche spécifiques et déplace le curseur vers cette ligne.
HRESULT FindRow(
LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
);
Paramètres
lpRestriction
[in] Pointeur vers une structure SRestriction qui décrit les critères de recherche.
BkOrigin
[in] Signet identifiant la ligne dans laquelle FindRow doit commencer sa recherche. Un signet peut être créé à l’aide de la méthode IMAPITable ::CreateBookmark , ou l’une des valeurs prédéfinies suivantes peut être passée.
BOOKMARK_BEGINNING
Recherche à partir du début de la table.
BOOKMARK_CURRENT
Recherche à partir de la ligne de la table où se trouve le curseur.
BOOKMARK_END
Recherche à partir de la fin de la table.
ulFlags
[in] Masque de bits d’indicateurs qui contrôle la direction de la recherche. L’indicateur suivant peut être défini :
DIR_BACKWARD
Recherche vers l’arrière à partir de la ligne identifiée par le signet.
Valeur renvoyée
S_OK
L’opération de recherche a réussi.
MAPI_E_INVALID_BOOKMARK
Le signet dans le paramètre BkOrigin n’est pas valide, car il a été supprimé ou parce qu’il est au-delà de la dernière ligne demandée.
MAPI_E_NOT_FOUND
Aucune ligne correspondant à la restriction n’a été trouvée.
MAPI_W_POSITION_CHANGED
L’appel a réussi, mais le signet utilisé dans l’opération n’est plus défini sur la même ligne que lors de sa dernière utilisation ; si le signet n’a pas été utilisé, il n’est plus dans la même position que lors de sa création. Lorsque cet avertissement est retourné, l’appel doit être géré comme ayant réussi. Pour tester cet avertissement, utilisez la macro HR_FAILED . Consultez Utilisation de macros pour la gestion des erreurs.
Remarques
La méthode IMAPITable ::FindRow localise la première ligne de la table pour qu’elle corresponde à un ensemble de critères de recherche décrits dans la structure SRestriction vers laquelle pointe le paramètre lpRestriction .
En règle générale, FindRow effectue des recherches vers l’avant à partir du signet spécifié. L’appelant peut définir la recherche pour qu’elle recule à partir du signet en définissant l’indicateur DIR_BACKWARD dans le paramètre ulFlags . La recherche vers l’avant commence à partir du signet actuel ; La recherche vers l’arrière commence à partir de la ligne précédant le signet. La position de fin de la recherche est juste avant la première ligne trouvée qui a satisfait à la restriction.
Si la ligne pointée par le signet dans le paramètre BkOrigin n’existe plus dans la table et que la table ne peut pas établir une nouvelle position pour le signet, FindRow renvoie MAPI_E_INVALID_BOOKMARK. Si la ligne pointée par BkOrigin n’existe plus et que la table est en mesure d’établir une nouvelle position pour le signet, FindRow renvoie MAPI_W_POSITION_CHANGED.
Si le signet passé dans BkOrigin est BOOKMARK_BEGINNING ou BOOKMARK_END, FindRow renvoie MAPI_E_NOT_FOUND si aucune ligne correspondante n’est trouvée. Si le signet utilisé dans BkOrigin est BOOKMARK_CURRENT, FindRow peut retourner MAPI_W_POSITION_CHANGED mais pas MAPI_E_INVALID_BOOKMARK, car il y a toujours une position de curseur actuelle.
La colonne de propriété PR_INSTANCE_KEY (PidTagInstanceKey) est requise pour toutes les tables, et toutes les implémentations de FindRow sont nécessaires pour prendre en charge les appels à la recherche d’une ligne basée sur PR_INSTANCE_KEY.
Remarques pour les responsables de l’implémentation
Le type de recherche de préfixe effectué par FindRow n’est utile que lorsque la recherche suit la même direction que l’organisation de la table. Pour obtenir le comportement requis, la fonction de comparaison implicite par l’RELOP_GE passée dans la structure de restriction de propriété doit être la même fonction de comparaison sur laquelle l’ordre de tri de table est basé.
Remarques pour les appelants
Vous pouvez utiliser FindRow pour prendre en charge le défilement en fonction des chaînes tapées par l’utilisateur, en particulier dans les zones de liste des boîtes de dialogue d’adresse. Dans ce type de défilement, les utilisateurs entrent des préfixes progressivement plus longs d’une valeur de chaîne souhaitée, et vous pouvez émettre régulièrement un appel FindRow pour accéder à la première ligne qui correspond au préfixe. La direction dans laquelle le curseur saute dépend de la direction dans laquelle la recherche est définie pour s’exécuter.
Pour utiliser FindRow, un signet doit être défini. La recherche de chaîne peut provenir de n’importe quel signet, y compris des signets prédéfinis indiquant la position actuelle et le début et la fin du tableau. S’il existe un grand nombre de lignes dans la table, l’opération de recherche peut être lente.
Utilisez une restriction pour rechercher un préfixe de chaîne pour le défilement comme suit. Pour effectuer une recherche vers l’avant sur une colonne triée par ordre croissant et pour effectuer une recherche vers l’arrière sur une colonne triée dans l’ordre décroissant, transmettez une structure de restriction de propriété dans le paramètre lpRestriction avec la relation RELOP_GE et la balise de propriété et le préfixe appropriés, à l’aide du préfixeGE de la balise de format.
Pour plus d’informations sur l’utilisation de structures de restriction pour spécifier un filtre, consultez À propos des restrictions.
Référence MFCMAPI
Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.
| Fichier | Fonction | Commentaire |
|---|---|---|
| ContentsTableListCtrl.cpp |
DwThreadFuncLoadTable |
MFCMAPI utilise la méthode IMAPITable ::FindRow pour rechercher les lignes qui correspondent à une restriction. |