IMAPIProp::GetNamesFromIDs
S’applique à : Outlook 2013 | Outlook 2016
Fournit les noms de propriétés qui correspondent à un ou plusieurs identificateurs de propriété.
HRESULT GetNamesFromIDs(
LPSPropTagArray FAR * lppPropTags,
LPGUID lpPropSetGuid,
ULONG ulFlags,
ULONG FAR * lpcPropNames,
LPMAPINAMEID FAR * FAR * lpppPropNames
);
Paramètres
lppPropTags
[in, out] En entrée, pointeur vers une structure SPropTagArray qui contient un tableau de balises de propriété ; sinon, NULL, indiquant que tous les noms doivent être retournés. Le membre cValues pour le tableau de balises de propriété ne peut pas être 0. Si lppPropTags est un pointeur valide en entrée, GetNamesFromIDs renvoie les noms de chaque identificateur de propriété inclus dans le tableau.
lpPropSetGuid
[in] Pointeur vers un GUID, ou structure GUID , qui identifie un jeu de propriétés. Le paramètre lpPropSetGuid peut pointer vers un jeu de propriétés valide ou avoir la valeur NULL.
ulFlags
[in] Masque de bits d’indicateurs qui indique le type de noms à retourner. Les indicateurs suivants peuvent être utilisés (si les deux indicateurs sont définis, aucun nom n’est retourné) :
MAPI_NO_IDS
Demande que seuls les noms stockés sous forme de chaînes Unicode soient retournés.
MAPI_NO_STRINGS
Demande que seuls les noms stockés en tant qu’identificateurs numériques soient retournés.
lpcPropNames
[out] Pointeur vers un nombre de pointeurs de nom de propriété dans le tableau vers lequel pointe le paramètre lppPropNames .
lpppPropNames
[out] Pointeur vers un tableau de pointeurs vers des structures MAPINAMEID qui contient des noms de propriétés.
Valeur renvoyée
S_OK
Les noms des propriétés ont été retournés avec succès.
MAPI_E_NO_SUPPORT
L’objet ne prend pas en charge les propriétés nommées.
MAPI_W_ERRORS_RETURNED
L’appel a réussi dans l’ensemble, mais les noms d’une ou de plusieurs propriétés n’ont pas pu être retournés. Les balises de propriété pour les propriétés ayant échoué ont un type de propriété de PT_ERROR. Lorsque cet avertissement est retourné, l’appel doit être géré comme ayant réussi. Pour tester cet avertissement, utilisez la macro HR_FAILED . Pour plus d’informations, consultez Utilisation de macros pour la gestion des erreurs.
MAPI_E_INVALID_PARAMETER
Le membre cValues d’une ou plusieurs des entrées dans le tableau de balises de propriétés vers lequel pointe lppPropTags est défini sur 0.
Remarques
Bien que l’accès à la plupart des propriétés soit par identificateur de propriété, certaines propriétés sont accessibles par nom. La méthode IMAPIProp ::GetNamesFromIDs peut être appelée pour effectuer les opérations suivantes :
Récupérer les noms des identificateurs de propriétés spécifiques dans un jeu de propriétés spécifique.
Récupérez les noms des identificateurs de propriétés spécifiques dans n’importe quel jeu de propriétés.
Récupérez les noms de toutes les propriétés nommées incluses dans le mappage de l’objet.
Si lppPropTags pointe vers un tableau d’étiquettes de propriétés valide avec un ou plusieurs identificateurs de propriété et que lpPropSetGuid pointe vers un jeu de propriétés valide, GetNamesFromIDs ignore le jeu de propriétés et les types de propriétés et retourne tous les noms mappés aux identificateurs spécifiés.
Si lppPropTags pointe vers un tableau d’étiquettes de propriétés valide avec un ou plusieurs identificateurs de propriété et que lpPropSetGuid a la valeur NULL, GetNamesFromIDs renvoie tous les noms qui correspondent aux identificateurs spécifiés.
Si un identificateur spécifié n’a pas de nom, GetNamesFromIDs retourne NULL à la place de cet identificateur dans la structure retournée dans lpppPropNames et retourne également MAPI_W_ERRORS_RETURNED.
Si lpPropSetGuid et lppPropTags ont la valeur NULL, GetNamesFromIDs alloue un nouveau tableau de balises de propriétés et retourne tous les noms pour toutes les propriétés nommées de l’objet.
Quand aucun nom ne doit être retourné, peut-être parce qu’il n’y a pas de propriétés dans le jeu de propriétés demandé ou que toutes les propriétés sont d’un type exclu par les indicateurs, GetNamesFromIDs effectue les opérations suivantes :
Retourne S_OK.
Alloue une nouvelle structure SPropTagArray , en définissant le membre cValues sur 0.
Définit le contenu de lpcPropNames sur 0.
Définit le contenu de lpppPropNames sur NULL.
Remarques pour les responsables de l’implémentation
Si lpPropSetGuid pointe vers un jeu de propriétés valide et que lppPropTags a la valeur NULL, le résultat n’est pas défini. Vous pouvez utiliser l’une des stratégies suivantes :
Ignorez le jeu de propriétés et retournez les noms des identificateurs dans le tableau de balises de propriété.
Retourne les noms des identificateurs du tableau de balises de propriétés qui appartiennent au jeu de propriétés spécifié.
Échec de l’appel, en retournant MAPI_E_INVALID_PARAMETER.
Remarques pour les appelants
Pour récupérer toutes les propriétés nommées d’un objet, vous devez d’abord appeler la méthode IMAPIProp ::GetPropList de l’objet, puis passer les identificateurs retournés au-dessus de la plage 0x8000 à GetNamesFromIDs.
Si vous transmettez un jeu de propriétés valide mais pas un tableau d’étiquettes de propriété valide, préparez-vous à des résultats imprévisibles. Certaines implémentations de GetNamesFromIDs ignorent le jeu de propriétés et retournent les noms des identificateurs dans le tableau de balises de propriétés. Certaines implémentations retournent MAPI_E_INVALID_PARAMETER. D’autres implémentations retournent des noms pour les identificateurs de toutes les propriétés dans le jeu de propriétés. Si le jeu de propriétés est PS_PUBLIC_STRINGS, GetNamesFromIDs peut retourner tous les noms qui ont été créés. Il est sans importance de savoir si le fournisseur de services stocke une propriété sous les identificateurs associés aux chaînes publiques.
Lorsque vous avez terminé avec les noms de propriété, case activée le contenu du paramètre lpcPropNames pour déterminer si des noms ont été retournés. Si c’est le cas, appelez la fonction MAPIFreeBuffer pour libérer la mémoire pointée par lppPropTags et lpppPropNames lorsqu’un résultat réussi est retourné. Un appel à MAPIFreeBuffer est suffisant pour chaque paramètre ; vous n’avez pas besoin de parcourir le tableau de pointeurs et de libérer chaque structure MAPINAMEID individuellement.
Pour plus d’informations sur les propriétés nommées, consultez Propriétés nommées MAPI.
Référence MFCMAPI
Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.
| Fichier | Fonction | Commentaire |
|---|---|---|
| SingleMAPIPropListCtrl.cpp |
CSingleMAPIPropListCtrl ::FindAllNamedProps |
MFCMAPI utilise la méthode IMAPIProp ::GetNamesFromIDs pour rechercher les propriétés nommées précédemment mappées. |