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