OpenIMsgOnIStg  

The OpenIMsgOnIStg function creates internal memory structures and an object handle for creation of a new message object.

Quick Info

SCODE OpenIMsgOnIStg(

Parameters

lpMsgSess

[in] Pointer to a message session object.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer1MW3BAZ function, to be used by the service provider to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMoreB1SGX_ function, to be used by the service provider to allocate additional memory where required.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer16U06F function, to be used by the service provider to free memory.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The message object may need to use this allocation method when working with certain interfaces such as IStream.

lpMapiSup

[in] Pointer to an optional MAPI support object used when a service provider calls OpenIMsgOnIStg.

lpStg

[in, out] Pointer to an IStorage object that is open and has read/write access. Because messages do not support write-only access, OpenIMsgOnIStg does not accept a storage object opened with write-only access.

lpfMsgCallRelease

[in] Pointer to a message-release callback function in the service provider DLL.

ulCallerData

[in] Caller data to be written by the callback function indicated by the lpfMsgCallRelease parameter.

ulFlags

[in] Bitmask of flags used to control whether the OLE IStorage::Commit method is called when the client application calls the IMessage::SaveChanges method. The following flag can be set:

IMSG_NO_ISTG_COMMIT

Controls whether the OLE method IStorage::Commit is called when the client calls SaveChanges21IFXQ.

lppMsg

[out] Pointer to a pointer to the opened message object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

Warning  The correct process for defining a message attachment is to call the IMAPIProp::OpenPropertyLFSSYS method with a source interface of IMessage : IMAPIProp3LEP_T6. IMAPIProp::OpenProperty is also supported for message attachments when the source interface is the OLE interface IStorage. IStorage is supported to allow an easy way to put a Microsoft Word for Windows document into an attachment without converting the attachment to or from the OLE IStream interface. However, use of IStorage presents a danger to the predictability of IMessage when the client application or service provider passes a new attachment data pointer to OpenIMsgOnIStg and then releases objects in the wrong order.

Including the lpMsgSess parameter ensures that the new message is created within a session so that it can be closed when the session is closed. If lpMsgSess is NULL, a message is created independently of any session. If the client or service provider that created the message does not release the message or does not release open tables within the message, memory is leaked until the external application terminates.

The lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer input parameters point to the MAPIAllocateBuffer1MW3BAZ, MAPIAllocateMoreB1SGX_, and MAPIFreeBuffer16U06F functions, respectively, for use by the service provider DLL. The provider DLL should not be linked with MAPIX.DLL. Instead, it should use these pointers for memory allocation or deallocation. In particular, the provider must use these pointers when allocating memory for use by clients in calling object interfaces. For example, two provider interface methods that typically allocate memory are IMAPIProp::GetPropsK06IXU and IMAPITable::QueryRowsKPHHB. The lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer pointers are optional when the OpenIMsgOnIStg function is called with a valid lpMapiSup parameter.

If a value is supplied for lpMapiSup, IMessage supports the MAPI_DIALOG and ATTACH_DIALOG flags by calling the IMAPISupport::DoProgressDialog31XNWXP method to supply a progress user interface for the IMAPIProp::CopyTo1_YJNNR and IMessage::DeleteAttach1OO.7K5 methods. The IMessage::ModifyRecipientsBTAS42 method attempts to convert short-term entry identifiers to long-term entry identifiers by calling the support method IMAPISession::OpenAddressBookC0WT.7 and making calls on the resulting address book object. If zero is passed for lpMapiSup, IMessage ignores MAPI_DIALOG and ATTACH_DIALOG and stores short-term entry identifiers without conversion.

MAPI does not define the behavior of multiple open operations performed on a message subobject, such as an attachment, a stream, a message store, or another message. MAPI currently allows a subobject that is already open to be opened once more, but MAPI performs the open operation by incrementing the reference count for the existing open object and returning it to the client or provider that called the IMessage::OpenAttach method14RPEGD or IMAPIProp::OpenPropertyLFSSYS method. Thus, the access requested for the first open operation on a subobject is the access provided for all subsequent open operations, regardless of the access requested by the operations.

Some clients of IMessage might call the OLE method IStorage::Commit after writing data beyond what IMessage itself writes to the storage object. To aid in this, the IMessage implementation guarantees to name all substorages. Therefore, if the client keeps its names out of that namespace, there will be no accidental collisions.

The callback function mentioned with the lpfMsgCallRelease parameter is optional; if provided, it should be based on the MSGCALLRELEASE71OOG6 function prototype. If lpfMsgCallRelease is supplied, the IMessage interface calls the callback function when the top-level message receives its last release call. IMSG.DLL will not use the IStorage object pointed to by the lpStg parameter after making this call.

See Also

OpenIMsgSession1XB._ED