199 lines
7.4 KiB
C
199 lines
7.4 KiB
C
|
/*
|
||
|
|
* I M E S S A G E . H
|
||
|
|
*
|
||
|
|
* External definitions for MAPI's IMessage-on-IStorage facility
|
||
|
|
*
|
||
|
|
* Copyright 1986-1999 Microsoft Corporation. All Rights Reserved.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef _IMESSAGE_H_
|
||
|
|
#define _IMESSAGE_H_
|
||
|
|
|
||
|
|
#if _MSC_VER > 1000
|
||
|
|
#pragma once
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#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_ */
|
||
|
|
|