OpenIMsgOnIStg
S’applique à : Outlook 2013 | Outlook 2016
Génère un nouvel objet IMessage sur un objet OLE IStorage existant, à utiliser dans une session de message.
| Propriété | Valeur |
|---|---|
| Fichier d’en-tête : |
Imessage.h |
| Implémenté par : |
MAPI |
| Appelé par : |
Applications clientes et fournisseurs de services |
SCODE OpenIMsgOnIStg(
LPMSGSESS lpMsgSess,
LPALLOCATEBUFFER lpAllocateBuffer,
LPALLOCATEMORE lpAllocateMore,
LPFREEBUFFER lpFreeBuffer,
LPMALLOC lpmalloc,
LPVOID lpMapiSup,
LPSTORAGE lpStg,
MSGCALLRELEASE FAR * lpfMsgCallRelease,
ULONG ulCallerData,
ULONG ulFlags,
LPMESSAGE FAR * lppMsg
);
Paramètres
lpMsgSess
[in] Pointeur vers un objet de session de message dans lequel le nouvel objet IMessage-on-IStorage doit être créé.
lpAllocateBuffer
[in] Pointeur vers la fonction MAPIAllocateBuffer , à utiliser pour allouer de la mémoire.
lpAllocatePlus
[in] Pointeur vers la fonction MAPIAllocateMore , à utiliser pour allouer de la mémoire supplémentaire.
lpFreeBuffer
[in] Pointeur vers la fonction MAPIFreeBuffer , à utiliser pour libérer de la mémoire.
lpMalloc
[in] Pointeur vers un objet allocateur de mémoire exposant l’interface OLE IMalloc . L’interface IMessage doit utiliser cette méthode d’allocation lors de l’utilisation d’interfaces telles que IStorage et IStream.
lpMapiSup
[in] Pointeur facultatif vers un objet de prise en charge MAPI qu’un fournisseur de services peut utiliser pour appeler les méthodes de l’interface IMAPISupport : IUnknown .
lpStg
[in, out] Pointeur vers un objet OLE IStorage ouvert et disposant d’une autorisation en lecture seule ou en lecture/écriture. Étant donné qu’IMessage ne prend pas en charge l’accès en écriture seule, OpenIMsgOnIStg n’accepte pas d’objet de stockage ouvert en mode écriture seule.
lpfMsgCallRelease
[in] Pointeur facultatif vers une fonction de rappel basée sur le prototype MSGCALLRELEASE que MAPI doit appeler après la dernière version sur l’objet IMessage-on-IStorage.
ulCallerData
[in] Données de l’appelant enregistrées par MAPI avec l’objet IMessage-on-IStorage et transmises à la fonction de rappel basée sur MSGCALLRELEASE. Les données fournissent un contexte sur l’objet IMessage en cours de libération et l’objet IStorage sur lequel il a été généré.
ulFlags
[in] Masque de bits des indicateurs utilisés pour contrôler si la méthode OLE IStorage ::Commit est appelée lorsque l’application cliente ou le fournisseur de services appelle la méthode IMessage ::SaveChanges . Les indicateurs suivants peuvent être définis :
IMSG_NO_ISTG_COMMIT
La méthode OLE IStorage ::Commit ne doit pas être appelée lorsque le client ou le fournisseur appelle SaveChanges.
MAPI_UNICODE
Active la création de fichiers .msg Unicode. Le fichier IMessage obtenu affiche STORE_UNICODE_OK dans son PR_STORE_SUPPORT_MASK et prend en charge les propriétés Unicode.
Remarque
L’indicateur MAPI_UNICODE est pris en charge uniquement dans cette fonction sur Outlook 2003 ou version ultérieure.
lppMsg
[out] Pointeur vers un pointeur vers l’objet IMessage ouvert.
Valeur renvoyée
S_OK
L'appel a r�ussi et a renvoy� la valeur attendue ou les valeurs.
Remarques
Les attributs de propriété sont accessibles uniquement sur les objets de propriété, c’est-à-dire les objets implémentant l’interface IMAPIProp : IUnknown . Pour rendre les propriétés MAPI disponibles sur un objet de stockage structuré OLE, OpenIMsgOnIStg génère un objet IMessage : IMAPIProp sur l’objet OLE IStorage . Les attributs de propriété sur ces objets peuvent être définis ou modifiés avec SetAttribIMsgOnIStg et récupérés avec GetAttribIMsgOnIStg.
Remarques pour les appelants
Une session de message doit être ouverte avec OpenIMsgSession avant l’appel d’OpenIMsgOnIStg . La fourniture d’un paramètre lpMsgSess valide vérifie que le nouveau message est créé dans une session de message afin qu’il soit fermé lorsque la session est fermée. Si lpMsgSess a la valeur NULL, le message est créé indépendamment de toute session de message. Si l’application cliente ou le fournisseur de services qui a créé le message ne le libère pas, ainsi que toutes ses pièces jointes et tables ouvertes, la mémoire est divulguée et peut entraîner l’arrêt de l’application.
MAPI utilise les fonctions pointées par lpAllocateBuffer, lpAllocateMore et lpFreeBuffer pour la plupart des allocations et désallocations de mémoire, en particulier pour allouer de la mémoire à utiliser par les applications clientes lors de l’appel d’interfaces objet telles que IMAPIProp ::GetProps et IMAPITable ::QueryRows. Les pointeurs lpAllocateBuffer, lpAllocateMore et lpFreeBuffer sont facultatifs lorsque la fonction OpenIMsgOnIStg est appelée avec un paramètre lpMapiSup valide.
Étant donné qu’il traite d’un objet OLE sous-jacent, MAPI doit également utiliser l’allocation de mémoire OLE. Pour plus d’informations sur les objets de stockage structuré OLE et l’allocation de mémoire OLE, consultez la référence du programmeur OLE.
Si une valeur valide est fournie pour lpMapiSup, IMessage prend en charge les indicateurs MAPI_DIALOG et ATTACH_DIALOG en appelant la méthode IMAPISupport ::D oProgressDialog pour fournir une interface utilisateur de progression pour les méthodes IMAPIProp ::CopyTo et IMessage ::D eleteAttach . En outre, la méthode IMessage ::ModifyRecipients tente de convertir les identificateurs d’entrée à court terme en identificateurs d’entrée à long terme en appelant la méthode IMAPISupport ::OpenAddressBook et en effectuant des appels sur l’objet de carnet d’adresses obtenu. Si null est passé pour lpMapiSup, IMessage ignore MAPI_DIALOG et ATTACH_DIALOG et stocke les identificateurs d’entrée à court terme sans conversion.
L’objet IStorage vers lequel pointe le paramètre lpStg doit être ouvert en mode STGM_READ ou STGM_READWRITE. Si le mode STGM_READWRITE est utilisé, le mode STGM_TRANSACTED doit également être défini.
La fonction de rappel pointée par le paramètre lpfMsgCallRelease est facultative ; s’il est fourni, il doit être basé sur le prototype de fonction MSGCALLRELEASE . L’interface IMessage l’appelle lorsque le nombre de références de l’objet IMessage-on-IStorage est défini sur zéro par le dernier appel à sa méthode Release. La fonction de rappel est couramment utilisée pour libérer l’interface IStorage sous-jacente. IMessage ne tente pas d’accéder à l’objet IStorage vers lequel pointe le paramètre lpStg après avoir effectué le rappel.
Certains clients ou fournisseurs peuvent écrire des données supplémentaires dans l’objet IStorage au-delà de ce qu’IMessage lui-même écrit lorsque sa méthode SaveChanges est appelée. Le client ou le fournisseur peut utiliser l’indicateur IMSG_NO_ISTG_COMMIT pour empêcher IMessage d’appeler la méthode OLE IStorage ::Commit lors du traitement d’un appel SaveChanges . dans ce cas, le client ou le fournisseur doit lui-même valider l’objet IStorage lors de l’écriture des données supplémentaires. Pour faciliter cette opération, l’implémentation IMessage garantit le nom de tous les sous-stockages qu’elle crée dans l’objet IStorage en commençant par la chaîne « __ », c’est-à-dire avec deux traits de soulignement. Le client ou le fournisseur peut éviter les collisions de noms en conservant ses noms de sous-stockage en dehors de cet espace de noms.
MAPI ne définit pas le comportement de plusieurs opérations ouvertes effectuées sur un sous-objet d’un message, comme une pièce jointe, un flux ou un message incorporé. MAPI autorise actuellement l’ouverture d’un sous-objet déjà ouvert, mais MAPI effectue l’opération d’ouverture en incrémentant le nombre de références pour l’objet ouvert existant et en le renvoyant au client ou au fournisseur qui a appelé la méthode IMessage ::OpenAttach ou IMAPIProp ::OpenProperty . Cela signifie que l’accès demandé pour la première opération d’ouverture sur un sous-objet est l’accès fourni pour toutes les opérations ouvertes suivantes, quel que soit l’accès demandé par les opérations.
La procédure correcte pour placer un message dans une pièce jointe consiste à appeler la méthode IMAPIProp ::OpenProperty avec un identificateur d’interface de IID_IMessage. Actuellement, OpenProperty prend également en charge la création de pièces jointes de message disponibles directement sur l’interface OLE IStorage , c’est-à-dire à l’aide de l’identificateur d’interface IID_IStorage. L’accès IStorage est pris en charge pour permettre de placer facilement un document Microsoft Word dans une pièce jointe sans le convertir vers ou à partir de l’interface OLE IStream. Toutefois, IMessage peut ne pas se comporter de manière prévisible si OpenIMsgOnIStg est passé à un pointeur IStorage vers les données de pièce jointe, puis les objets sont libérés dans le mauvais ordre.
Référence MFCMAPI
Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.
| Fichier | Fonction | Commentaire |
|---|---|---|
| File.cpp |
LoadMSGToMessage |
MFCMAPI utilise la méthode OpenIMsgOnIStg pour ouvrir une interface IMessage sur le . Fichier MSG afin que le fichier puisse être manipulé avec MAPI. |