/*
* I M E S S A G E . H
*
* External definitions for MAPI's IMessage-on-IStorage facility
*
* Copyright 1986-1996 Microsoft Corporation. All Rights Reserved.
*/
#ifndef _IMESSAGE_H_
#define _IMESSAGE_H_
#ifdef __cplusplus
extern "C"
{
#endif
typedef struct _MSGSESS FAR * LPMSGSESS;
/* Typedef of optional callback routine to be called on last release of
* top-level messages opened with OpenIMsgOnIStg
*/
typedef void (STDAPICALLTYPE MSGCALLRELEASE)(
ULONG ulCallerData,
LPMESSAGE lpMessage );
/* DLL Entry Points (found in mapiu.dll) */
/* OpenIMsgSession
* CloseIMsgSession
*
* These entry points allow the caller to "wrap" the creation of messages
* inside a session, so that when the session is closed, all messages
* created within that session are closed as well. Use of IMSG sessions
* is optional. If OpenIMsgOnIStg is called with a NULL for the lpmsgsess
* parameter, the message is created independent of any session, and has
* no way to be shutdown. If the caller forgets to release the message, or
* to release open tables within the message, the memory will be leaked until
* the external application terminates.
*/
STDAPI_(SCODE) OpenIMsgSession(
LPMALLOC lpMalloc, /* -> Co malloc object */
ULONG ulFlags, /* reserved. Must be zero. */
LPMSGSESS FAR *lppMsgSess ); /* <- message session object */
STDAPI_(void) CloseIMsgSession(
LPMSGSESS lpMsgSess ); /* -> message session object */
/* OpenIMsgOnIStg - Main entry point
*
* NOTE 1: The IStg must be opened with STGM_TRANSACTED if STGM_READWRITE
* is specified. Since messages don't support a write only mode, IMessage
* doesn't allow a storage object opened in write only mode. If the storage
* is opened STGM_READ, then STGM_TRANSACTED is NOT required.
*
* NOTE 2: The lpMapiSup parameter is optional. If supplied then IMessage
* will support the MAPI_DIALOG and ATTACH_DIALOG flags (by calling
* support method: DoMCDialog) on CopyTo and DeleteAttach methods.
* If lpMapiSup is not supplied (i.e. passed 0) then dialog flags will be
* ignored. If supplied then ModifyRecipients will attempt to convert
* short term entryids to long term entryids (by calling support method
* OpenAddressBook and calls on the returned object). If not supplied
* then short term entryid's will be stored without conversion.
*
* NOTE 3: The lpfMsgCallRelease parameter is optional. If supplied then
* IMessage will call the routine when the last release on (the toplevel only)
* message is called. It is intended to allow the callee to free the IStorage
* that contains the message. IMessage will not use the IStorage object after
* making this call.
*
* NOTE 4: Behavior of multiple opens of sub-objects (Attachments, Streams,
* Storages, Messages, etc.) within a message is deliberately undefined in
* MAPI. This implementation allows them, but will do it by AddRef'ing the
* existing open and returning it to the caller of OpenAttachment or
* OpenProperty. This means that whatever access mode the first open on a
* specific Attachment or Property had is what all others will get regardless
* of what the subsequent opens asked for.
*
* NOTE 5: There is currently one flag defined for use with the ulFlags
* parameter. The IMSG_NO_ISTG_COMMIT flag controls whether the commit
* method of IStorage is called when the client calls SaveChanges on the
* IMessage object. Some clients of IMessage may wish to commit the IStorage
* themselves after writing additional data to the storage (beyond what
* IMessage itself writes). To aid in this, the IMessage implementation
* guarantees to name all sub-storages starting with "__". Therefore,
* if the client keeps its names out of that namespace, there will be no
* accidental collisions.
*
* WARNING:
*
* This implementation of IMessage will support OpenProperty w/MAPI_CREATE
* where the source interface is IID_IStorage if the property id is
* 'PR_ATTACH_DATA'. Once this has been done, the caller has an IStorage
* interface on this property. This is ok and should allow for
* easier implementation of OLE 2.0 Server functionality. However, if you
* pass in the new IStorage ptr (to the attachment data) through the
* OpenIMsgOnIStg entry point and then proceed to release things in the
* wrong order we will make no attempt to behave in a predictable fashion.
* Keep in mind that the correct method for placing a message into an
* attachment is to call OpenProperty where the source interface is
* IID_IMessage. The IStorage interface is supported to allow an easy way
* to stick a WWord doc. into an attachment w/o converting to/from IStream.
*
*/
STDAPI_(SCODE) OpenIMsgOnIStg(
LPMSGSESS lpMsgSess, /* -> message session obj (optional) */
LPALLOCATEBUFFER lpAllocateBuffer, /* -> AllocateBuffer memory routine */
LPALLOCATEMORE lpAllocateMore, /* -> AllocateMore memory routine */
LPFREEBUFFER lpFreeBuffer, /* -> FreeBuffer memory routine */
LPMALLOC lpMalloc, /* -> Co malloc object */
LPVOID lpMapiSup, /* -> MAPI Support Obj (optional) */
LPSTORAGE lpStg, /* -> open IStorage containing msg */
MSGCALLRELEASE FAR *lpfMsgCallRelease, /* -> release callback rtn (opt) */
ULONG ulCallerData, /* caller data returned in callback */
ULONG ulFlags, /* -> flags (controls istg commit) */
LPMESSAGE FAR *lppMsg ); /* <- open message object */
#define IMSG_NO_ISTG_COMMIT ((ULONG) 0x00000001)
/* NOTE: Property Attributes are specific to this IMessage on IStorage */
/* implementation and are not a part of standard MAPI 1.0 property methods */
/* Property Attributes */
#define PROPATTR_MANDATORY ((ULONG) 0x00000001)
#define PROPATTR_READABLE ((ULONG) 0x00000002)
#define PROPATTR_WRITEABLE ((ULONG) 0x00000004)
#define PROPATTR_NOT_PRESENT ((ULONG) 0x00000008)
/* Attribute Array */
typedef struct _SPropAttrArray
{
ULONG cValues;
ULONG aPropAttr[MAPI_DIM];
} SPropAttrArray, FAR * LPSPropAttrArray;
#define CbNewSPropAttrArray(_cattr) \
(offsetof(SPropAttrArray,aPropAttr) + (_cattr)*sizeof(ULONG))
#define CbSPropAttrArray(_lparray) \
(offsetof(SPropAttrArray,aPropAttr) + \
(UINT)((_lparray)->cValues)*sizeof(ULONG))
#define SizedSPropAttrArray(_cattr, _name) \
struct _SPropAttrArray_ ## _name \
{ \
ULONG cValues; \
ULONG aPropAttr[_cattr]; \
} _name
/* GetAttribIMsgOnIStg - To get attributes on properties
*
* This call is provided because there is no method of IMAPIPropSet to allow
* getting attributes.
*/
STDAPI GetAttribIMsgOnIStg(
LPVOID lpObject,
LPSPropTagArray lpPropTagArray,
LPSPropAttrArray FAR *lppPropAttrArray );
/* SetAttribIMsgOnIStg - To set attributes on properties
*
* This call is provided because there is no method of IMAPIPropSet to allow
* setting of attributes.
*/
STDAPI SetAttribIMsgOnIStg(
LPVOID lpObject,
LPSPropTagArray lpPropTags,
LPSPropAttrArray lpPropAttrs,
LPSPropProblemArray FAR *lppPropProblems );
/* MapStorageSCode - To map an IStorage hResult to a MAPI sCode value
*
* This call is provided for the internal use of PDK components that base
* their message implementations on IMessage. Since these components must
* open the storage themselves, there is a common need to map OLE 2.0
* Storage error returns to MAPI sCodes.
*
* WARNING: There is no guarantee that this entry point will exist in
* shipped versions of mapiu.dll.
*/
STDAPI_(SCODE) MapStorageSCode( SCODE StgSCode );
#ifdef __cplusplus
}
#endif
#endif /* _IMESSAGE_H_ */
