Récupération des propriétés MAPI
S’applique à : Outlook 2013 | Outlook 2016
Lorsqu’un client ou un fournisseur de services récupère une propriété à partir d’un objet, l’objet met à disposition la valeur, le type et l’identificateur de la propriété.
Les clients et les fournisseurs de services peuvent récupérer les propriétés d’un objet en appelant l’un des éléments suivants :
La méthode GetProps est utilisée pour récupérer une ou plusieurs propriétés qui n’ont pas besoin d’une interface spécialisée ou alternative pour l’accès. Cela implique que les propriétés disponibles avec GetProps sont petites, telles que les entiers et les valeurs booléennes.
Pour récupérer plusieurs propriétés
Allouez une structure SPropTagArray suffisamment grande pour contenir le nombre de propriétés à récupérer.
Définissez le membre cValues de la structure SPropTagArray sur le nombre de propriétés à récupérer et définissez chaque membre aulPropTag sur l’identificateur et le type, si possible, de l’une des propriétés cibles. Si le type est inconnu, définissez-le sur PT_UNSPECIFIED. Si le type et l’identificateur sont inconnus, recherchez ces informations en appelant IMAPIProp ::GetPropList. GetPropList retourne un tableau de balises de propriété avec toutes les propriétés prises en charge de l’objet. Si seul un nom de propriété est disponible, appelez IMAPIProp ::GetIDsFromNames pour accéder à l’identificateur associé.
Appelez IMAPIProp ::GetProps pour ouvrir la ou les propriétés.
La méthode OpenProperty est utilisée pour ouvrir des propriétés plus volumineuses qui nécessitent une autre interface comme IStream ou IMAPITable pour l’accès. OpenProperty est généralement utilisé pour ouvrir des propriétés de chaîne de caractères volumineuses, binaires et d’objets et ne peut ouvrir qu’une seule propriété à la fois. Les appelants passent l’identificateur de l’interface supplémentaire requise comme l’un des paramètres d’entrée.
Parmi les utilisations courantes d’OpenProperty , citons l’ouverture de PR_BODY (PidTagBody), la propriété qui contient le corps d’un message textuel, PR_ATTACH_DATA_OBJ (PidTagAttachDataObject), la propriété qui contient un objet OLE ou une pièce jointe de message, et PR_CONTAINER_CONTENTS (PidTagContainerContents), la propriété qui contient un dossier ou une table de contenu de conteneur de carnet d’adresses.
Selon la propriété, une interface différente est demandée à partir d’OpenProperty. IStream, une interface qui permet aux données de propriété d’être lues et écrites sous la forme d’un flux d’octets, est généralement utilisée pour accéder à PR_BODY. IMessage ou IStream peut être utilisé pour accéder à PR_ATTACH_DATA_OBJ. Les pièces jointes incorporées qui sont des messages standard utilisent IMessage , tandis que les messages au format TNEF utilisent IStream. Étant donné que PR_CONTAINER_CONTENTS est un objet table, il est accessible avec IMAPITable.
Pour récupérer la propriété PR_ATTACH_DATA_BIN d’une pièce jointe
Appelez la fonction OpenStreamOnFile pour ouvrir un flux pour le fichier.
Appelez la méthode IMAPIProp ::OpenProperty du message pour récupérer la propriété PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) avec l’interface IStream . Définissez les indicateurs MAPI_MODIFY et MAPI_CREATE.
Allouez une structure STATSTG et passez-la dans un appel à la méthode IStream ::Stat du flux de fichier pour déterminer sa taille. Une autre façon de déterminer la taille du flux consiste à appeler IStream ::Seek avec l’indicateur STREAM_SEEK_END.
Appelez la méthode IStream ::CopyTo du flux pour copier les données du flux du fichier dans le flux de pièces jointes.
Une fois l’opération de copie terminée, libérez les deux flux en appelant leurs méthodes IUnknown ::Release .
Quand IStream est utilisé pour l’accès aux propriétés, certains fournisseurs de services renvoient automatiquement la taille de la propriété avec le flux. L’appel d’OpenProperty avec l’indicateur MAPI_DEFERRED_ERRORS peut retarder l’ouverture de la propriété et le retour de la taille du flux. Si IStream ::Stat est appelé pour récupérer cette taille après OpenProperty avec l’indicateur MAPI_DEFERRED_ERRORS défini, les performances seront affectées, car cette séquence d’appels force un appel de procédure distante supplémentaire. Pour éviter un impact sur les performances, les clients peuvent appeler n’importe quelle méthode MAPI entre les appels à OpenProperty et à Stat.
La fonction HrGetOneProp , comme OpenProperty, ouvre une propriété à la fois. HrGetOneProp doit être utilisé uniquement lorsque l’objet cible existe sur l’ordinateur local. Lorsque l’objet cible n’est pas disponible localement, l’utilisation répétée de HrGetOneProp peut entraîner plusieurs appels de procédure distante et une dégradation des performances.
Les appelants qui ont besoin de plusieurs propriétés peuvent appeler HrGetOneProp ou OpenProperty dans une boucle ou effectuer un appel à GetProps. L’appel de GetProps une fois est plus efficace.
Remarque
Les propriétés sécurisées ne sont pas automatiquement disponibles avec d’autres propriétés dans un appel GetProps, HrGetOneProp ou GetPropList . Les propriétés sécurisées doivent être explicitement demandées à l’aide de leurs identificateurs de propriété.