1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
/*
* 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_ */
|
