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