IMAPITable::QueryRows
S’applique à : Outlook 2013 | Outlook 2016
Retourne une ou plusieurs lignes d’un tableau, en commençant à la position actuelle du curseur.
HRESULT QueryRows(
LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
);
Paramètres
lRowCount
[in] Nombre maximal de lignes à retourner.
ulFlags
[in] Masque de bits des indicateurs qui contrôlent la façon dont les lignes sont retournées. L’indicateur suivant peut être défini :
TBL_NOADVANCE
Empêche l’avancement du curseur suite à la récupération de ligne. Si l’indicateur TBL_NOADVANCE est défini, le curseur pointe vers la première ligne retournée. Si l’indicateur TBL_NOADVANCE n’est pas défini, le curseur pointe vers la ligne qui suit la dernière ligne retournée.
lppRows
[out] Pointeur vers un pointeur vers une structure SRowSet contenant les lignes du tableau.
Valeur renvoyée
S_OK
Les lignes ont été retournées avec succès.
MAPI_E_BUSY
Une autre opération est en cours qui empêche l’opération de récupération de ligne de démarrer. Soit l’opération en cours doit être autorisée à se terminer, soit elle doit être arrêtée.
MAPI_E_INVALID_PARAMETER
Le paramètre IRowCount est défini sur zéro.
Remarques
La méthode IMAPITable ::QueryRows obtient une ou plusieurs lignes de données d’une table. La valeur du paramètre IRowCount affecte le point de départ de la récupération. Si IRowCount est positif, les lignes sont lues dans un sens vers l’avant, en commençant à la position actuelle. Si IRowCount est négatif, QueryRows réinitialise le point de départ en déplaçant vers l’arrière le nombre de lignes indiqué. Une fois le curseur réinitialisé, les lignes sont lues dans l’ordre de progression.
Le membre cRows dans la structure SRowSet pointée vers le paramètre lppRows indique le nombre de lignes retournées. Si zéro ligne est retournée :
Le curseur était déjà positionné au début de la table et la valeur de IRowCount est négative. -Ou-
Le curseur était déjà positionné à la fin de la table et la valeur de IRowCount est positive.
Le nombre de colonnes et leur classement sont les mêmes pour chaque ligne. S’il n’existe pas de propriété pour une ligne ou s’il y a une erreur lors de la lecture d’une propriété, la structure SPropValue de la propriété dans la ligne contient les valeurs suivantes :
PT_ERROR pour le type de propriété dans le membre ulPropTag .
MAPI_E_NOT_FOUND pour le membre Value .
La mémoire utilisée pour les structures SPropValue dans le jeu de lignes vers lequel pointe le paramètre lppRows doit être allouée et libérée séparément pour chaque ligne. Utilisez MAPIFreeBuffer pour libérer les structures de valeurs de propriété et libérer le jeu de lignes. Toutefois, lorsqu’un appel à QueryRows retourne zéro, indiquant le début ou la fin de la table, seule la structure SRowSet elle-même doit être libérée. Pour plus d’informations sur l’allocation et la libération de mémoire dans une structure SRowSet , consultez Gestion de la mémoire pour les structures ADRLIST et SRowSet.
Les lignes retournées et l’ordre dans lequel elles sont retournées varient selon que des appels ont été effectués ou non à IMAPITable ::Restrict et IMAPITable ::SortTable. Restreindre les filtres de lignes de la vue, ce qui entraîne le renvoi de QueryRows uniquement les lignes qui correspondent aux critères spécifiés dans la restriction. SortTable établit un ordre de tri standard ou classé, affectant la séquence de lignes retournées par QueryRows. Les lignes retournées sont dans l’ordre spécifié dans la structure SSortOrderSet passée à SortTable.
Les colonnes retournées pour chaque ligne et l’ordre dans lequel elles sont retournées varient selon qu’un appel réussi a été effectué ou non à IMAPITable ::SetColumns. SetColumns établit un ensemble de colonnes, en spécifiant les propriétés à inclure dans les colonnes de la table et l’ordre dans lequel elles doivent être incluses. Si un appel SetColumns a été effectué, les colonnes particulières de chaque ligne et l’ordre de ces colonnes correspondent au jeu de colonnes spécifié dans l’appel. Si aucun appel SetColumns n’a été effectué, la table retourne son jeu de colonnes par défaut.
Si aucun de ces appels n’a été effectué, QueryRows retourne toutes les lignes de la table. Chaque ligne contient l’ensemble de colonnes par défaut dans l’ordre par défaut.
Lorsque le jeu de colonnes établi dans un appel à IMAPITable ::SetColumns inclut des colonnes définies sur PR_NULL, le tableau SPropValue dans le jeu de lignes retourné dans lppRows contient des emplacements vides .
Remarques pour les responsables de l’implémentation
Vous pouvez autoriser un appelant à demander l’inclusion d’une colonne non prise en charge dans l’ensemble de colonnes. Dans ce cas, placez PT_ERROR dans la partie type de propriété de la balise de propriété et MAPI_E_NOT_FOUND dans la valeur de propriété de la colonne non prise en charge.
Traitez le nombre de lignes comme une requête plutôt qu’une exigence. Vous pouvez retourner n’importe où de zéro ligne, s’il n’y a aucune ligne dans le sens de la requête, au nombre demandé.
Retourne uniquement les lignes que l’utilisateur verra quand des lignes sont demandées à partir d’une vue de table catégorisée, ce qui permet à l’appelant d’effectuer des hypothèses valides sur l’étendue des données et d’éviter un travail supplémentaire.
Remarques pour les appelants
En règle générale, vous obtiendrez autant de lignes que vous avez spécifié dans le paramètre lRowCount . Toutefois, lorsque les limites de mémoire ou d’implémentation sont un problème ou lorsque l’opération atteint prématurément le début ou la fin de la table, QueryRows retourne moins de lignes que demandé.
Si QueryRows retourne MAPI_E_BUSY, appelez la méthode IMAPITable ::WaitForCompletion et réessayez l’appel à QueryRows une fois l’opération asynchrone terminée.
Lorsque vous appelez QueryRows, n’oubliez pas que le minutage des notifications asynchrones peut potentiellement empêcher le jeu de lignes que vous obtenez à partir de QueryRows de représenter avec précision les données sous-jacentes. Par exemple, un appel à QueryRows vers la table de contenu d’un dossier après la suppression d’un message, mais avant la réception de la notification correspondante, entraîne le renvoi de la ligne supprimée dans le jeu de lignes. Attendez toujours qu’une notification arrive avant de mettre à jour la vue des données de l’utilisateur.
Pour plus d’informations sur la récupération de lignes à partir de tables, consultez Récupération de données à partir de lignes de table.
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 ::QueryRows pour récupérer les lignes de la table à charger dans la vue. |