home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / imessage.h < prev    next >
C/C++ Source or Header  |  1998-04-25  |  8KB  |  195 lines
  1. /*
  2.  *  I M E S S A G E . H
  3.  *
  4.  *  External definitions for MAPI's IMessage-on-IStorage facility
  5.  *
  6.  *  Copyright 1986-1996 Microsoft Corporation. All Rights Reserved.
  7.  */
  8.  
  9. #ifndef _IMESSAGE_H_
  10. #define _IMESSAGE_H_
  11.  
  12. #ifdef __cplusplus
  13. extern "C"
  14. {
  15. #endif
  16.  
  17. typedef struct _MSGSESS     FAR * LPMSGSESS;
  18.  
  19. /*  Typedef of optional callback routine to be called on last release of
  20.  *  top-level messages opened with OpenIMsgOnIStg
  21.  */
  22. typedef void (STDAPICALLTYPE MSGCALLRELEASE)(
  23.     ULONG       ulCallerData, 
  24.     LPMESSAGE   lpMessage );
  25.  
  26. /* DLL Entry Points (found in mapiu.dll) */
  27.  
  28. /* OpenIMsgSession
  29.  * CloseIMsgSession
  30.  *
  31.  * These entry points allow the caller to "wrap" the creation of messages
  32.  * inside a session, so that when the session is closed, all messages
  33.  * created within that session are closed as well. Use of IMSG sessions
  34.  * is optional. If OpenIMsgOnIStg is called with a NULL for the lpmsgsess
  35.  * parameter, the message is created independent of any session, and has
  36.  * no way to be shutdown. If the caller forgets to release the message, or
  37.  * to release open tables within the message, the memory will be leaked until
  38.  * the external application terminates.
  39.  */
  40.  
  41. STDAPI_(SCODE) OpenIMsgSession(
  42.     LPMALLOC        lpMalloc,           /* -> Co malloc object          */
  43.     ULONG           ulFlags,            /* reserved. Must be zero.      */
  44.     LPMSGSESS FAR   *lppMsgSess );      /* <- message session object    */
  45.  
  46. STDAPI_(void) CloseIMsgSession(
  47.     LPMSGSESS       lpMsgSess );        /* -> message session object    */
  48.  
  49. /*  OpenIMsgOnIStg - Main entry point
  50.  *
  51.  *  NOTE 1:  The IStg must be opened with STGM_TRANSACTED if STGM_READWRITE
  52.  *  is specified.  Since messages don't support a write only mode, IMessage
  53.  *  doesn't allow a storage object opened in write only mode. If the storage
  54.  *  is opened STGM_READ, then STGM_TRANSACTED is NOT required.
  55.  *
  56.  *  NOTE 2:  The lpMapiSup parameter is optional.  If supplied then IMessage 
  57.  *  will support the MAPI_DIALOG and ATTACH_DIALOG flags (by calling 
  58.  *  support method: DoMCDialog) on CopyTo and DeleteAttach methods.  
  59.  *  If lpMapiSup is not supplied (i.e. passed 0) then dialog flags will be
  60.  *  ignored.  If supplied then ModifyRecipients will attempt to convert 
  61.  *  short term entryids to long term entryids (by calling support method 
  62.  *  OpenAddressBook and calls on the returned object).  If not supplied 
  63.  *  then short term entryid's will be stored without conversion.
  64.  *
  65.  *  NOTE 3:  The lpfMsgCallRelease parameter is optional.  If supplied then
  66.  *  IMessage will call the routine when the last release on (the toplevel only)
  67.  *  message is called.  It is intended to allow the callee to free the IStorage
  68.  *  that contains the message.  IMessage will not use the IStorage object after
  69.  *  making this call.
  70.  *
  71.  *  NOTE 4:  Behavior of multiple opens of sub-objects (Attachments, Streams, 
  72.  *  Storages, Messages, etc.) within a message is deliberately undefined in 
  73.  *  MAPI.  This implementation allows them, but will do it by AddRef'ing the 
  74.  *  existing open and returning it to the caller of OpenAttachment or 
  75.  *  OpenProperty.  This means that whatever access mode the first open on a 
  76.  *  specific Attachment or Property had is what all others will get regardless 
  77.  *  of what the subsequent opens asked for.  
  78.  *
  79.  *  NOTE 5:  There is currently one flag defined for use with the ulFlags
  80.  *  parameter. The IMSG_NO_ISTG_COMMIT flag controls whether the commit
  81.  *  method of IStorage is called when the client calls SaveChanges on the
  82.  *  IMessage object. Some clients of IMessage may wish to commit the IStorage
  83.  *  themselves after writing additional data to the storage (beyond what
  84.  *  IMessage itself writes). To aid in this, the IMessage implementation
  85.  *  guarantees to name all sub-storages starting with "__". Therefore,
  86.  *  if the client keeps its names out of that namespace, there will be no
  87.  *  accidental collisions.
  88.  *
  89.  *  WARNING:    
  90.  *
  91.  *  This implementation of IMessage will support OpenProperty w/MAPI_CREATE
  92.  *  where the source interface is IID_IStorage if the property id is 
  93.  *  'PR_ATTACH_DATA'.  Once this has been done, the caller has an IStorage 
  94.  *  interface on this property.  This is ok and should allow for
  95.  *  easier implementation of OLE 2.0 Server functionality.  However, if you 
  96.  *  pass in the new IStorage ptr (to the attachment data) through the 
  97.  *  OpenIMsgOnIStg entry point and then proceed to release things in the 
  98.  *  wrong order we will make no attempt to behave in a predictable fashion.
  99.  *  Keep in mind that the correct method for placing a message into an 
  100.  *  attachment is to call OpenProperty where the source interface is
  101.  *  IID_IMessage.  The IStorage interface is supported to allow an easy way
  102.  *  to stick a WWord doc. into an attachment w/o converting to/from IStream.
  103.  *
  104.  */
  105. STDAPI_(SCODE) OpenIMsgOnIStg( 
  106.     LPMSGSESS       lpMsgSess,          /* -> message session obj (optional) */
  107.     LPALLOCATEBUFFER lpAllocateBuffer,  /* -> AllocateBuffer memory routine  */
  108.     LPALLOCATEMORE  lpAllocateMore,     /* -> AllocateMore memory routine    */
  109.     LPFREEBUFFER    lpFreeBuffer,       /* -> FreeBuffer memory routine      */
  110.     LPMALLOC        lpMalloc,           /* -> Co malloc object               */
  111.     LPVOID          lpMapiSup,          /* -> MAPI Support Obj (optional)    */
  112.     LPSTORAGE       lpStg,              /* -> open IStorage containing msg   */
  113.     MSGCALLRELEASE FAR *lpfMsgCallRelease,  /* -> release callback rtn (opt) */
  114.     ULONG           ulCallerData,       /* caller data returned in callback  */
  115.     ULONG           ulFlags,            /* -> flags (controls istg commit)   */
  116.     LPMESSAGE       FAR *lppMsg );      /* <- open message object            */
  117.  
  118. #define IMSG_NO_ISTG_COMMIT     ((ULONG) 0x00000001)
  119.  
  120.  
  121. /* NOTE: Property Attributes are specific to this IMessage on IStorage      */
  122. /* implementation and are not a part of standard MAPI 1.0 property methods  */
  123.  
  124. /* Property Attributes */
  125.  
  126. #define PROPATTR_MANDATORY      ((ULONG) 0x00000001)
  127. #define PROPATTR_READABLE       ((ULONG) 0x00000002)
  128. #define PROPATTR_WRITEABLE      ((ULONG) 0x00000004)
  129.  
  130. #define PROPATTR_NOT_PRESENT    ((ULONG) 0x00000008)
  131.  
  132. /* Attribute Array */
  133.  
  134. typedef struct _SPropAttrArray
  135. {
  136.     ULONG   cValues;                            
  137.     ULONG   aPropAttr[MAPI_DIM];
  138. } SPropAttrArray, FAR * LPSPropAttrArray;
  139.  
  140. #define CbNewSPropAttrArray(_cattr) \
  141.     (offsetof(SPropAttrArray,aPropAttr) + (_cattr)*sizeof(ULONG))
  142. #define CbSPropAttrArray(_lparray) \
  143.     (offsetof(SPropAttrArray,aPropAttr) + \
  144.     (UINT)((_lparray)->cValues)*sizeof(ULONG))
  145.  
  146. #define SizedSPropAttrArray(_cattr, _name) \
  147. struct _SPropAttrArray_ ## _name \
  148. { \
  149.     ULONG   cValues; \
  150.     ULONG   aPropAttr[_cattr]; \
  151. } _name
  152.  
  153.  
  154.  
  155. /*  GetAttribIMsgOnIStg - To get attributes on properties
  156.  *
  157.  *  This call is provided because there is no method of IMAPIPropSet to allow
  158.  *  getting attributes.
  159.  */
  160. STDAPI GetAttribIMsgOnIStg(
  161.     LPVOID                  lpObject,
  162.     LPSPropTagArray         lpPropTagArray,
  163.     LPSPropAttrArray FAR    *lppPropAttrArray );
  164.  
  165. /*  SetAttribIMsgOnIStg - To set attributes on properties
  166.  *
  167.  *  This call is provided because there is no method of IMAPIPropSet to allow
  168.  *  setting of attributes.
  169.  */
  170. STDAPI SetAttribIMsgOnIStg(
  171.     LPVOID                  lpObject,
  172.     LPSPropTagArray         lpPropTags,
  173.     LPSPropAttrArray        lpPropAttrs,
  174.     LPSPropProblemArray FAR *lppPropProblems );
  175.  
  176. /*  MapStorageSCode - To map an IStorage hResult to a MAPI sCode value
  177.  *
  178.  *  This call is provided for the internal use of PDK components that base
  179.  *  their message implementations on IMessage.  Since these components must 
  180.  *  open the storage themselves, there is a common need to map OLE 2.0 
  181.  *  Storage error returns to MAPI sCodes.
  182.  *
  183.  *  WARNING:    There is no guarantee that this entry point will exist in 
  184.  *  shipped versions of mapiu.dll.
  185.  */
  186. STDAPI_(SCODE) MapStorageSCode( SCODE StgSCode );
  187.  
  188.  
  189. #ifdef __cplusplus
  190. }
  191. #endif
  192.  
  193. #endif  /* _IMESSAGE_H_ */
  194.  
  195.