IMAPITable::SortTable
S’applique à : Outlook 2013 | Outlook 2016
La méthode IMAPITable ::SortTable trie les lignes de la table, en fonction des critères de tri.
HRESULT SortTable(
LPSSortOrderSet lpSortCriteria,
ULONG ulFlags
);
Paramètres
lpSortCriteria
[in] Pointeur vers une structure SSortOrderSet qui contient les critères de tri à appliquer. Le passage d’une structure SSortOrderSet qui contient zéro colonne indique que la table n’a pas besoin d’être triée dans un ordre particulier.
ulFlags
[in] Masque de bits des indicateurs qui contrôle le minutage de l’opération IMAPITable ::SortTable . 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 la fin du tri jusqu’à ce que les données de la table soient requises.
Valeur renvoyée
S_OK
L’opération de tri a réussi.
MAPI_E_BUSY
Une autre opération est en cours qui empêche le démarrage de l’opération de tri. Soit l’opération en cours doit être autorisée à se terminer, soit elle doit être arrêtée.
MAPI_E_NO_SUPPORT
La table ne prend pas en charge le type de tri demandé.
MAPI_E_TOO_COMPLEX
La table ne peut pas effectuer l’opération, car les critères de tri spécifiques pointés par le paramètre lpSortCriteria sont trop complexes. SortTable peut retourner MAPI_E_TOO_COMPLEX dans les conditions suivantes.
Une opération de tri est demandée pour une colonne de propriété que l’implémentation ne peut pas trier.
L’implémentation ne prend pas en charge l’ordre de tri demandé dans le membre ulOrder de la structure SSortOrderSet .
Le nombre de colonnes à trier, tel que spécifié dans le membre cSorts dans SSortOrderSet, est supérieur à ce que l’implémentation peut gérer.
Une opération de tri est demandée, comme indiqué par une balise de propriété dans SSortOrderSet, en fonction d’une propriété qui n’est pas dans le jeu disponible ou actif, et l’implémentation ne prend pas en charge le tri sur les propriétés qui ne sont pas dans le jeu disponible.
Une propriété est spécifiée plusieurs fois dans un ensemble d’ordre de tri, comme indiqué par plusieurs instances de la même balise de propriété, et l’implémentation ne peut pas effectuer une telle opération de tri.
Une opération de tri basée sur des colonnes de propriétés à valeurs multiples est demandée à l’aide de MVI_FLAG et l’implémentation ne prend pas en charge le tri sur les propriétés à valeurs multiples.
Une balise de propriété pour une propriété dans SSortOrderSet spécifie une propriété ou un type que l’implémentation ne prend pas en charge.
Une opération de tri autre que celle qui passe par la table à partir de la propriété PR_RENDERING_POSITION (PidTagRenderingPosition) est spécifiée uniquement pour une table de pièces jointes qui prend en charge ce type de tri.
Remarques
La méthode IMAPITable ::SortTable classe les lignes dans une vue de table. Alors que certaines tables prennent en charge à la fois le tri standard et catégorisé sur différentes colonnes de clé de tri, d’autres tables sont plus limitées dans leur prise en charge. Les fournisseurs de carnets d’adresses ne prennent généralement pas en charge le tri de table. Les fournisseurs de magasins de messages prennent généralement en charge le tri dans la mesure où ils conservent l’ordre de tri des dossiers qui se produit lorsqu’une table complète (table sans restrictions) est triée.
Certaines tables permettent d’effectuer le tri sur n’importe quelle colonne de table. Ce n’est pas le cas des autres tables ; Les colonnes non incluses dans la vue table ne sont pas affectées par un appel SortTable . Certaines tables exigent que les clés de tri soient générées uniquement avec des colonnes dans l’ensemble de colonnes actuel de la table.
Une table peut retourner MAPI_E_NO_SUPPORT ou MAPI_E_TOO_COMPLEX à partir de SortTable lorsqu’elle ne peut pas effectuer une opération de tri. En outre, il n’est pas garanti que les fournisseurs de magasin respectent l’ordre de tri défini pour les tables de hiérarchie.
Lorsqu’il n’y a aucune colonne dans la structure SSortOrderSet vers laquelle pointe le paramètre lpSortCriteria , la table retourne le jeu de colonnes actuel. L’ordre de tri actuel peut être récupéré en appelant la méthode IMAPITable ::QuerySortOrder de la table.
Tous les signets d’une table sont invalidés et doivent être supprimés lorsqu’un appel à SortTable est effectué, et le signet BOOKMARK_CURRENT qui indique la position actuelle du curseur doit être défini sur le début du tableau.
Si vous triez sur une colonne qui contient une propriété à plusieurs valeurs sans l’indicateur MVI_FLAG défini, les valeurs de la colonne sont traitées comme un tuple complètement 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é, et retourne l’égalité 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.
Remarques pour les appelants
SortTable fonctionne de manière synchrone, sauf si vous définissez l’un des indicateurs. Si vous définissez l’indicateur TBL_BATCH, SortTable reporte l’opération de tri, sauf si vous demandez les données. Si l’indicateur de TBL_ASYNC est défini, SortTable fonctionne de façon asynchrone et peut éventuellement retourner avant la fin de l’opération.
Appelez la méthode IMAPITable ::Abort pour arrêter une opération asynchrone en cours si votre tri doit être effectué immédiatement. Si SortTable ne peut pas continuer parce qu’une ou plusieurs opérations asynchrones sur la table sont en cours, elle retourne MAPI_E_BUSY.
Pour de meilleures performances, appelez SetColumns pour personnaliser l’ensemble de colonnes de la table et Restrict pour limiter le nombre de lignes dans la table avant d’appeler SortTable pour effectuer le tri.
Chaque fois que SortTable échoue, l’ordre de tri qui était en vigueur avant l’échec est toujours en vigueur.