IMAPIProp::GetProps

Article
04/04/2023

S’applique à : Outlook 2013 | Outlook 2016

Récupère la valeur de propriété d’une ou de plusieurs propriétés d’un objet .

HRESULT GetProps(
  LPSPropTagArray lpPropTagArray,
  ULONG ulFlags,
  ULONG FAR * lpcValues,
  LPSPropValue FAR * lppPropArray
);

Paramètres

lpPropTagArray

[in] Pointeur vers un tableau de balises de propriété qui identifient les propriétés dont les valeurs doivent être récupérées. Le paramètre lpPropTagArray doit être NULL, ce qui indique que les valeurs de toutes les propriétés de l’objet doivent être retournées, ou pointer vers une structure SPropTagArray qui contient une ou plusieurs balises de propriété.

ulFlags

[in] Masque de bits d’indicateurs qui indique le format des propriétés de type PT_UNSPECIFIED. L’indicateur suivant peut être défini :

MAPI_UNICODE

Les valeurs de chaîne de ces propriétés doivent être retournées au format Unicode. Si l’indicateur MAPI_UNICODE n’est pas défini, les valeurs de chaîne doivent être retournées au format ANSI.

lpcValues

[out] Pointeur vers un nombre de valeurs de propriété vers lesquelles pointe le paramètre lppPropArray . Si lppPropArray a la valeur NULL, le contenu du paramètre lpcValues est égal à zéro.

lppPropArray

[out] Pointeur vers un pointeur vers les valeurs de propriété récupérées.

Valeur renvoyée

S_OK

Les valeurs de propriété ont été récupérées avec succès.

MAPI_W_ERRORS_RETURNED

L’appel a réussi dans l’ensemble, mais une ou plusieurs propriétés n’ont pas pu être consultées. Le membre aulPropTag de la valeur de propriété pour chaque propriété indisponible a un type de propriété de PT_ERROR et un identificateur égal à zéro. 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

Zéro a été passé dans le membre cValues de la structure SPropTagArray pointée par lpPropTagArray.

Remarques

La méthode IMAPIProp ::GetProps obtient les valeurs de propriété d’une ou plusieurs propriétés d’un objet.

Les valeurs de propriété sont retournées dans le même ordre qu’elles ont été demandées (autrement dit, l’ordre des propriétés dans le tableau de balises de propriété pointé par lpPropTagArray correspond à l’ordre dans le tableau des structures de valeurs de propriété pointées par lppPropArray).

Les types de propriétés spécifiés dans les membres aulPropTag du tableau de balises de propriété indiquent le type de valeur qui doit être retourné dans le membre Value de chaque structure de valeur de propriété. Toutefois, si l’appelant ne connaît pas le type d’une propriété, le type dans le membre aulPropTag peut être défini à la place sur PT_UNSPECIFIED. Lors de la récupération de la valeur, GetProps définit le type correct dans le membre aulPropTag de la structure de la valeur de propriété pour la propriété.

Si des types de propriété sont spécifiés dans le SPropTagArray dans lpPropTagArray, les valeurs de propriété dans la valeur SPropValue retournée dans lppPropArray ont des types qui correspondent exactement aux types demandés, sauf si une valeur d’erreur est retournée à la place.

Les propriétés de chaîne peuvent avoir l’un des deux types de propriétés : PT_UNICODE pour représenter le format Unicode et PT_STRING8 pour représenter le format ANSI. Si l’indicateur MAPI_UNICODE est défini dans le paramètre ulFlags , chaque fois que GetProps ne peut pas déterminer le format approprié pour une propriété de chaîne, il retourne sa valeur au format Unicode. GetProps ne peut pas déterminer un type de propriété de chaîne exact dans les situations suivantes :

Le paramètre lpPropTagArray est défini sur NULL pour demander toutes les propriétés.
Le membre aulPropTag inclut la valeur PT_UNSPECIFIED comme type de propriété dans le tableau de balises de propriété.

Si le paramètre lpPropTagArray est défini sur NULL pour récupérer toutes les propriétés de l’objet et qu’il n’existe aucune propriété, GetProps effectue les opérations suivantes :

Retourne S_OK.
Définit la valeur count dans le membre cValues de la structure de valeur de propriété sur 0.
Définit le contenu de lpcValues sur 0.
Définit lppPropArray sur NULL.

GetProps ne doit pas retourner de propriétés à valeurs multiples avec cValues défini sur 0.

Remarques pour les responsables de l’implémentation

Appelez la fonction MAPIAllocateBuffer pour allouer de la mémoire initialement pour la structure SPropValue pointée par lpPropTagArray ; appelez MAPIAllocateMore pour allouer toute mémoire supplémentaire nécessaire aux membres de la structure.

Retourne MAPI_W_ERRORS_RETURNED si vous ne pouvez pas récupérer la valeur d’une ou plusieurs des propriétés demandées. Dans la structure des valeurs de propriété, définissez le type dans le membre aulPropTag sur PT_ERROR et le membre Value sur un code status qui décrit l’erreur. Par exemple, si vous devez convertir une chaîne en Unicode et que vous ne prenez pas en charge Unicode, définissez le membre Value sur MAPI_E_BAD_CHARWIDTH. Si la propriété est trop grande, définissez-la sur MAPI_E_NOT_ENOUGH_MEMORY. Si l’objet ne prend pas en charge la propriété, définissez-le sur MAPI_E_NOT_FOUND.

L’implémentation de la méthode GetProps par un fournisseur de transport distant doit retourner les valeurs de propriété du dossier pour les propriétés demandées par l’appelant. Votre implémentation doit effectuer les opérations suivantes :

Allouez un tableau de valeurs de propriété à retourner à l’appelant et stockez son adresse dans le paramètre de pointeur de valeur de propriété transmis à cet effet.
Copiez les balises de propriété des propriétés du dossier dans les balises de propriété du tableau de valeurs de propriété en fonction du tableau de balises de propriété passées à GetProps.
Vérifiez que le type de propriété est défini pour toutes les balises de propriété passées à GetProps. L’appelant peut passer un type de propriété de PT_UNSPECIFIED, auquel cas GetProps doit définir le type de propriété correct pour cette balise de propriété.
Définissez la valeur de chaque propriété dans le tableau de valeurs de propriété en fonction de sa balise. Par exemple, si la balise de propriété demandée par l’appelant est PR_OBJECT_TYPE (PidTagObjectType), GetProps peut définir la valeur sur MAPI_FOLDER.
Si l’appelant transmet des balises de propriété que votre implémentation ne gère pas, vous pouvez définir la balise de propriété sur PT_ERROR pour ces propriétés et définir la valeur de la propriété sur MAPI_E_NOT_FOUND.
Retourne S_OK si aucune erreur ne s’est produite ou MAPI_W_ERRORS_RETURNED s’il y a eu des erreurs.

L’implémentation de la méthode GetProps par un fournisseur de transport distant doit prendre en charge au minimum les propriétés suivantes :

PR_ACCESS (PidTagAccess)
PR_ACCESS_LEVEL (PidTagAccessLevel)
PR_ASSOC_CONTENT_COUNT (PidTagAssociatedContentCount)
PR_CONTENT_COUNT (PidTagContentCount)
PR_CREATION_TIME (PidTagCreationTime)
PR_DISPLAY_NAME (PidTagDisplayName)
PR_DISPLAY_TYPE (PidTagDisplayType)
PR_FOLDER_TYPE (PidTagFolderType)
PR_OBJECT_TYPE
PR_SUBFOLDERS (PidTagSubfolders)

Remarques pour les appelants

Pour les propriétés de type PT_OBJECT, appelez la méthode IMAPIProp ::OpenProperty au lieu de GetProps.

Pour les propriétés sécurisées, ne vous attendez pas à les récupérer en appelant GetProps avec le paramètre lppPropTagArray défini sur NULL. Vous devez définir explicitement l’identificateur d’une propriété sécurisée dans le membre aulPropTag de son tableau de balises de propriété lorsque vous appelez GetProps. Quand et comment une propriété sécurisée est disponible sont à la charge du fournisseur de services.

Libérez la structure SPropValue retournée en appelant la fonction MAPIFreeBuffer uniquement si GetProps retourne S_OK ou MAPI_W_ERRORS_RETURNED.

Si GetProps renvoie MAPI_W_ERRORS_RETURNED parce qu’il n’a pas pu accéder à une ou plusieurs propriétés, case activée les balises de propriété des propriétés retournées. Les propriétés ayant échoué auront les valeurs suivantes définies dans leur structure de valeur de propriété :

Type de propriété dans le membre aulPropTag défini sur PT_ERROR.
Valeur de propriété dans le membre Value définie sur un code status pour l’erreur, par exemple MAPI_E_NOT_FOUND.

Les propriétés qui échouent parce qu’elles sont trop volumineuses pour être renvoyées dans la structure de valeur de propriété ont leur membre Value défini sur MAPI_E_NOT_ENOUGH_MEMORY. En règle générale, cela se produit avec des propriétés chaîne ou binaires de type PT_STRING8, PT_UNICODE ou PT_BINARY lorsque la valeur de la propriété est supérieure ou égale à 4 Ko. Appelez IMAPIProp ::OpenProperty pour récupérer des propriétés volumineuses.

Toutes les implémentations de GetProps ne prennent pas en charge les formats Unicode et ANSI pour les chaînes de caractères. Lorsqu’une propriété particulière nécessite une conversion au format de chaîne et que GetProps ne peut pas la prendre en charge, le membre Value de la propriété est défini sur MAPI_E_BAD_CHARWIDTH.

Pour case activée si un PST est un PST SharePoint, montez le PST à l’aide de IMAPISession ::OpenMsgStore, puis appelez GetProps sur l’objet de la banque de messages demandant cette propriété. S’il existe, vous pouvez supposer que la pst a été configurée pour SharePoint ; si ce n’est pas le cas, le PST n’a pas été configuré en tant que PST SharePoint.

Pour plus d’informations sur l’utilisation de GetProps pour accéder aux propriétés, consultez Récupération des propriétés MAPI.

Référence MFCMAPI

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

Fichier	Fonction	Commentaire
MAPIFunctions.cpp	GetPropsNULL	MFCMAPI utilise la méthode IMAPIProp ::GetProps pour obtenir toutes les propriétés d’un objet en transmettant null ou le tableau retourné par la méthode IMAPIProp ::GetPropList dans le paramètre lpPropTagArray .