IMAPITable::SetColumns

Article
04/04/2023

S’applique à : Outlook 2013 | Outlook 2016

Définit les propriétés particulières et l’ordre des propriétés à afficher sous forme de colonnes dans la table.

HRESULT SetColumns(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags
);

Paramètres

lpPropTagArray

[in] Pointeur vers un tableau de balises de propriété identifiant les propriétés à inclure en tant que colonnes dans la table. La partie type de propriété de chaque balise peut être définie sur un type valide ou sur PR_NULL pour réserver de l’espace pour les ajouts suivants. Le paramètre lpPropTagArray ne peut pas être défini sur NULL ; chaque table doit avoir au moins une colonne.

ulFlags

[in] Masque de bits des indicateurs qui contrôle le retour d’un appel asynchrone à SetColumns, par exemple lorsque SetColumns est utilisé dans la notification. Les indicateurs suivants peuvent être définis :

TBL_ASYNC

Demande que l’opération de définition de colonne soit effectuée de manière asynchrone, ce qui entraîne le retour potentiel de SetColumns avant que l’opération ne soit entièrement terminée.

TBL_BATCH

Permet à la table de reporter l’opération de paramètre de colonne jusqu’à ce que les données soient réellement requises.

Valeur renvoyée

S_OK

L’opération de définition de colonne a réussi.

MAPI_E_BUSY

Une autre opération est en cours qui empêche l’opération de définition de colonne de démarrer. Soit l’opération en cours doit être autorisée à se terminer, soit elle doit être arrêtée.

Remarques

Le jeu de colonnes d’une table est le groupe de propriétés qui composent les colonnes des lignes de la table. Il existe un jeu de colonnes par défaut pour chaque type de table. L’ensemble de colonnes par défaut est constitué des propriétés que l’implémenteur de table inclut automatiquement. Les utilisateurs de table peuvent modifier ce jeu par défaut en appelant la méthode IMAPITable ::SetColumns . Ils peuvent demander que d’autres colonnes soient ajoutées au jeu par défaut si l’implémenteur de table les prend en charge pour que les colonnes soient supprimées ou que l’ordre des colonnes soit modifié. SetColumns spécifie les colonnes retournées avec chaque ligne et l’ordre de ces colonnes dans la ligne.

La réussite de l’opération SetColumns n’est apparente qu’après un appel ultérieur pour récupérer les données de la table. C’est alors que toutes les erreurs sont signalées.

Remarques pour les responsables de l’implémentation

Certains fournisseurs autorisent un appel SetColumns à classer uniquement les colonnes de table qui font partie des colonnes disponibles pour une vue de table. D’autres fournisseurs autorisent un appel SetColumns pour classer toutes les colonnes de table, y compris celles qui contiennent des propriétés qui ne se trouve pas dans le jeu de colonnes d’origine.

Lorsque TBL_BATCH est défini pour les opérations asynchrones, les fournisseurs doivent retourner un type de propriété PT_ERROR et une valeur de propriété NULL pour les colonnes qui ne sont pas prises en charge.

Vous n’avez pas besoin de répondre à l’indicateur TBL_ASYNC demandant que l’opération soit asynchrone. Si vous ne prenez pas en charge la définition asynchrone d’un jeu de colonnes, effectuez l’opération de manière synchrone. Si vous pouvez prendre en charge l’indicateur TBL_ASYNC et qu’une autre opération asynchrone est toujours en cours, retournez MAPI_E_BUSY. Sinon, retournez S_OK que vous preniez ou non en charge toutes les propriétés incluses dans le tableau de balises de propriétés. Les erreurs résultant de propriétés non prises en charge doivent être retournées à partir de méthodes IMAPITable qui récupèrent des données, telles que QueryRows.

Ne générez pas de notifications pour les lignes de table masquées par les appels à Restreindre.

Lors de l’envoi de notifications de table, l’ordre des propriétés dans le membre de ligne de la structure TABLE_NOTIFICATION et l’ordre spécifié par l’appel SetColumns le plus récent doivent être identiques à l’heure à laquelle la demande de notification a été envoyée.

Un autre indicateur, TBL_BATCH, permet aux appelants de spécifier que l’implémenteur de table peut différer l’évaluation des résultats de l’opération jusqu’à une date ultérieure. Dans la mesure du possible, les appelants doivent définir cet indicateur, car l’opération par lot améliore les performances.

Il est souvent pratique pour les appelants de réserver des colonnes dans l’ensemble de lignes récupérées pour que des valeurs soient ajoutées ultérieurement. Pour ce faire, les appelants placent PR_NULL (PidTagNull) aux positions souhaitées dans le tableau de balises de propriétés transmis à SetColumns ; la table revient ensuite PR_NULL à ces positions dans toutes les lignes récupérées avec QueryRows.

Remarques pour les appelants

Lors de la génération du tableau de balises de propriété pour le paramètre lpPropTagArray , triez les balises dans l’ordre dans lequel vous souhaitez que les colonnes apparaissent dans la vue de table.

Vous pouvez spécifier des propriétés à valeurs multiples à inclure dans le jeu de colonnes en appliquant l’indicateur de instance à valeurs multiples, ou MVI_FLAG constante, à la balise de propriété. Définissez cet indicateur en transmettant la balise de propriété pour la version à valeur unique de la propriété en tant que paramètre à la macro MVI_PROP comme suit :

MVI_PROP(ulPropTag)

La macro MVI_PROP définit MVI_FLAG pour la propriété, en transformant la balise en balise à valeurs multiples. Si vous essayez par erreur d’appeler MVI_PROP sur une propriété à valeur unique, MAPI ignore l’appel et laisse la balise de propriété inchangée.

Vous pouvez inclure des balises de propriété définies sur PR_NULL dans le tableau de balises de propriété pour réserver de l’espace dans le jeu de colonnes. La réservation d’espace vous permet d’ajouter à un jeu de colonnes sans avoir à allouer un nouveau tableau de balises de propriété.

Lorsque votre appel à SetColumns entraîne une modification de l’ordre des colonnes d’une table et qu’une ou plusieurs de ces colonnes représentent une propriété à valeurs multiples, il est possible que le nombre de lignes de la table augmente. Si cela se produit, tous les signets de la table sont ignorés. Pour plus d’informations sur la façon dont les colonnes à valeurs multiples affectent les tables, consultez Utilisation de colonnes à valeurs multiples.

La définition de colonnes est par défaut une opération synchrone. Toutefois, vous pouvez autoriser la table à reporter l’opération jusqu’à ce que les données soient nécessaires en définissant l’indicateur TBL_BATCH. La définition de cet indicateur peut améliorer les performances. Un autre indicateur, TBL_ASYNC, rend l’opération asynchrone, ce qui permet à SetColumns de revenir avant la fin de l’opération. Pour déterminer quand l’achèvement se produit, appelez IMAPITable ::GetStatus.

Si un appel à SetColumns retourne MAPI_E_BUSY, indiquant qu’une autre opération empêche votre opération de démarrer, vous pouvez appeler IMAPITable ::Abort pour arrêter l’opération en cours.

Vous pouvez également appeler HrAddColumnsEx pour modifier un jeu de colonnes. La différence entre HrAddColumnsEx et IMAPITable ::SetColumns est que HrAddColumnsEx est moins flexible ; elle peut uniquement ajouter des colonnes. Les colonnes supplémentaires sont placées au début de l’ensemble de colonnes ; toutes les colonnes existantes apparaissent après ces colonnes.

Référence MFCMAPI

Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.

Fichier	Fonction	Commentaire
ContentsTableListCtrl.cpp	CContentsTableListCtrl ::D oSetColumns	MFCMAPI utilise la méthode IMAPITable ::SetColumns pour définir les colonnes souhaitées pour la table.