IMAPIProp::GetIDsFromNames
S’applique à : Outlook 2013 | Outlook 2016
Fournit les identificateurs de propriété qui correspondent à un ou plusieurs noms de propriété.
HRESULT GetIDsFromNames(
ULONG cPropNames,
LPMAPINAMEID FAR * lppPropNames,
ULONG ulFlags,
LPSPropTagArray FAR * lppPropTags
);
Paramètres
cPropNames
[in] Nombre de noms de propriétés pointés par le paramètre lppPropNames . Si lppPropNames a la valeur NULL, le paramètre cPropNames doit être 0.
lppPropNames
[in] Pointeur vers un tableau de noms de propriétés, ou NULL. Le passage d’identificateurs de propriété de demande NULL pour tous les noms de propriétés dans tous les jeux de propriétés sur lesquels l’objet contient des informations. Le paramètre lppPropNames ne doit pas être NULL si l’indicateur MAPI_CREATE est défini dans le paramètre ulFlags .
ulFlags
[in] Masque de bits d’indicateurs qui indique comment les identificateurs de propriété doivent être retournés. L’indicateur suivant peut être défini :
MAPI_CREATE
Affecte un identificateur de propriété, s’il n’en a pas encore été affecté, à un ou plusieurs des noms inclus dans le tableau de noms de propriété pointé par lppPropNames. Cet indicateur inscrit en interne l’identificateur dans la table de mappage nom-à-identificateur.
lppPropTags
[out] Pointeur vers un tableau de balises de propriété qui contient des identificateurs de propriété existants ou nouvellement attribués. Les types de propriétés pour les balises de propriété dans ce tableau sont définis sur PT_UNSPECIFIED.
Valeur renvoyée
S_OK
Les identificateurs des noms de propriétés spécifié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_E_NOT_ENOUGH_MEMORY
La mémoire disponible était insuffisante pour récupérer les identificateurs.
MAPI_E_TOO_BIG
L’opération ne peut pas être effectuée, car elle nécessite trop de balises de propriété pour être retournées.
MAPI_W_ERRORS_RETURNED
L’appel a réussi dans l’ensemble, mais un ou plusieurs identificateurs de propriété n’ont pas pu être retournés. Le type de propriété correspondant pour chaque propriété non disponible est défini sur PT_ERROR et son identificateur sur zéro. Lorsque cet avertissement est retourné, gérez l’appel comme réussi. Pour tester cet avertissement, utilisez la macro HR_FAILED . Consultez Utilisation de macros pour la gestion des erreurs.
Remarques
La méthode IMAPIProp ::GetIDsFromNames récupère un tableau de balises de propriété qui contiennent les identificateurs de propriété pour une ou plusieurs propriétés nommées. IMAPIProp ::GetIDsFromNames peut être appelé pour effectuer les opérations suivantes :
Créez des identificateurs pour les nouveaux noms.
Récupérez les identificateurs pour des noms spécifiques.
Récupérez les identificateurs de toutes les propriétés nommées incluses dans le mappage de l’objet.
Les propriétés nommées sont généralement utilisées par les fournisseurs de magasins de messages pour les dossiers et les messages. D’autres objets, tels que les utilisateurs de messagerie et les sections de profil, peuvent ne pas prendre en charge l’association de noms à des identificateurs de propriété et retourner des MAPI_E_NO_SUPPORT à partir de GetIDsFromNames.
En cas d’erreur qui renvoie un identificateur pour un nom particulier, GetIDsFromNames renvoie MAPI_W_ERRORS_RETURNED et définit le type de propriété dans l’entrée du tableau de balises de propriétés qui correspond au nom à PT_ERROR et l’identificateur à zéro.
Le mappage de nom à identificateur est représenté par la propriété PR_MAPPING_SIGNATURE (PidTagMappingSignature) d’un objet. PR_MAPPING_SIGNATURE contient une structure MAPIUID qui indique le fournisseur de services responsable de l’objet. Si la propriété PR_MAPPING_SIGNATURE est identique pour deux objets, supposons que ces objets utilisent le même mappage de nom à identificateur.
Remarques pour les responsables de l’implémentation
Les identificateurs que vous transmettez dans le tableau de balises de propriétés vers lequel pointe le paramètre lppPropNames doivent se trouver dans la 0x8000 à 0xFFFE plage. Les entrées de ce tableau doivent être dans le même ordre que les noms passés dans le tableau de noms de propriétés pointés par lppPropNames.
Si vous prenez en charge les propriétés nommées sur un conteneur, utilisez le même mappage nom-à-identificateur pour tous les objets de votre conteneur (autrement dit, n’utilisez pas de mappage différent pour chaque dossier de votre magasin de messages ou chaque message de votre dossier).
Remarques pour les appelants
Étant donné que les types de propriétés pour les identificateurs retournés dans le tableau de balises de propriété pointé par lppPropTags sont définis sur PT_UNSPECIFIED, vous devez appeler la méthode IMAPIProp ::SetProps pour récupérer les types précis.
Si vous déplacez ou copiez des objets avec des propriétés nommées et que les objets source et de destination ont des signatures de mappage différentes, comme indiqué par les valeurs de leurs propriétés PR_MAPPING_SIGNATURE , vous devez conserver les noms pendant ces opérations. Pour conserver les noms des propriétés, ajustez les identificateurs de propriété correspondants pour qu’ils correspondent au mappage nom-à-identificateur de l’objet de destination.
Certains objets ont une limite quant au nombre d’identificateurs de propriété qu’ils peuvent nommer. Si un appel à GetIDsFromNames entraîne le dépassement de cette limite, la méthode retourne MAPI_E_TOO_BIG. Dans ce cas, interrogez par identificateur.
Pour plus d’informations, 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 ::FindAllNamedPropsUsed |
MFCMAPI utilise la méthode IMAPIProp ::GetIDsFromNames pour obtenir des balises de propriété pour toutes les propriétés nommées qui ont été mappées. |