Message Receiving
The transport provider can tell the Spooler (see TransportLogin() above) whether it wants to be polled for incoming mail or whether it wants to perform a callback to the Spooler when incoming mail is available. After learning that incoming mail is available, the Spooler will (at a convenient time) start asking the transport provider for the data associated with the message.
Poll()
ulResult = Poll([in] ulLoginHandle, [out] lpulIncoming)
ULONG ulLoginHandle 32-bit opaque Login handle assigned on TransportLogin()
ULONG * lpulIncoming flag (non-zero) returned to indicate one or more incoming messages are available
This call, made periodically by the Spooler to the transport, allows the transport to indicate when it has one or more incoming messages available. This call will only be made when the transport selected, by its response to TransportLogin(), that it wanted to be polled for new mail.
StartMessage()
ulResult = StartMessage([in] ulLoginHandle, [in] ulFlags, [out] lpulMsgRef)
ULONG ulLoginHandle 32-bit opaque Login handle assigned on TransportLogin()
ULONG ulFlags Flags. For future use. May be ignored.
ULONG * lpulMsgRef Address of where to return 32-bit opaque reference value assigned by the transport for this message. The spooler will pass this handle in on subsequent calls dealing with this message.
This call initiates the transfer of an incoming message from the transport provider to the Spooler. The transport provider assigns an opaque handle to the message which the Spooler will pass back in on subsequent calls.
Some transport providers will be implemented to transfer the entire contents of a message from a server to the local file system during this call, and then to convert the format of the message from that native to the underlying messaging system. This call may take a long time, but of course transport providers will use the SpoolerYield() callback to the Spooler frequently during these operations to release time for other tasks on the system.
ReadData()
When reading data from the message or an attachment, the transport provider controls the order of the properties, the order of the attachments, and the order of the recipients. With this call, the Spooler asks the transport provider for something, but it doesn't know what it will get. The structure passed back is a union which might return any of a number of types of data, depending on the return code.
ulResult = ReadData([in] ulRef, [in] ulFlags, [out] lpulType, [out] lpReturnData)
ULONG ulRef 32-bit opaque handle assigned on to the message or to the attachment.
ULONG ulFlags Flags. For future use. May be ignored.
ULONG * lpulType Return type for the other data. Defined below
SReturnData * lpReturnData Address of a SReturnData structure which is to be filled in by the transport provider. Defined below.
#define ReturnStop 0
#define ReturnProperties 1
#define ReturnRecipients 2
#define ReturnStream 3
#define ReturnAttachment 4
typedef structure {
[switch_is(ultype)] union
{
[case(ReturnStop) ] ULONG; // nothing more. Stop reading.
[case(ReturnProperties) ] SPropSet *; // one or more properties returned.
[case(ReturnRecipients) ] ADRLIST *; // one or more recipients returned.
[case(ReturnStream) ] StreamInfo *; // Stream opened. Info returned (see below)
[case(ReturnAttachment) ] ULONG; // Attachment opened. 32-bit opaque handle
[default ] ULONG;
} Value;
} SReturnData;
typedef structure {
PropID * szPropName; // Property name
ULONG ulPropertyType; // Property type
ULONG ulPropertySize; // Property size (characters or bytes, as approp)
ULONG ulStreamRef; // 32-bit opaque stream reference handle
} StreamInfo;
The property type (ulPropertyType) can be PT_STRING8, PT_WCSTRING, or PT_BINARY.
When allocating memory for a returned structure, such as SPropSet, ADRLIST, or StreamInfo, the transport provider should use SpoolerAllocate() to obtain the memory.
ReturnStop
This return code indicates that there is no more data to the message or the attachment. If currently reading an attachment the Spooler will return to reading data from the message. If currently reading the message, the Spooler will complete the processing of the message and call StopMessage().
ReturnProperties
This code indicates that one or more properties were returned on the call. These are properties of a message or properties of an attachment, depending on what is being read.
When allocating memory for the complex SPropSet structure the transport provider should use SpoolerAllocate() to allocate one buffer for the entire structure. The Spooler will release the memory by calling SpoolerFree() with the address of the base structure.
ReturnRecipients
This code indicates that one or more recipients were returned on the. These may only be returned when reading data from the message, not from attachments.
The structure used for passing recipient data is the same as for WriteRecips() in the message submission APIs.
The transport provider should use SpoolerAllocate() to allocate a buffer to hold the entire data returned. The Spooler will release the data by calling SpoolerFree() with the address of the base structure.
ReturnStream
This code indicates that a large property has been opened for stream reading. A 32-bit opaque handle is returned to identify the open stream. This code can be used when reading either the message or the attachment. Upon receiving this code the Spooler will repeatedly call ReadStream() until the entire large property has been transferred.
The structure returned on this call identifies the property name, the property type, and the total size of the property (if known). Property sizes are in bytes for Binary properties, and in characters for string properties.
ReturnAttachment
This code indicates that the transport provider would now like to transfer the data of an attachment. A 32-bit opaque handle to the attachment has been assigned by the transport provider and is returned on the call. The spooler will repeatedly call ReadData() on the attachment handle until all data for the attachment is transferred. (Of course, some large properties may be included with the appropriate reads for those done as well.)
ReadStream()
This call transfers a portion of a large property from the transport provider to the Spooler.
ulResult = ReadStream([in] ulStreamRef, [in] ulFlags, [out] lpOffset, [out] lpSize, [out] lppData)
ULONG ulStreamRef 32-bit opaque reference value assigned by transport to identify the stream.
ULONG ulFlags Flags. For future use. May be ignored.
ULONG * lpOffset address of variable in which the total number of bytes of data transferred previously is returned.
ULONG * lpSize address of variable in which the size (in bytes) of the data transferred on this call is returned.
LPBYTE * lppData address of variable in which a pointer to the data transferred on this call is returned.
The Spooler will repeatedly make this call until the transport provider returns a zero in the *lpsize value. The transport provider should transfer all the data of the large property in order from beginning to end. The transport provider should allocate the memory for the data buffer with SpoolerAllocate(). The Spooler will release that memory with SpoolerFree().
After reading all the data of a large property, the Spooler will return to reading data from the current message or attachment being transferred.
StopMessage()
This call terminates the reading of a message. It is the formal handoff that indicates that the Spooler has accepted responsibility for the message.
ulResult = StopMessage([in] ulMsgRef, [in] ulFlags)
ULONG ulMsgRef 32-bit opaque reference value assigned by transport to identify the message.
ULONG ulFlags Flags. For future use. May be ignored.
This call releases the 32-bit opaque reference value assigned to the message.
Revision History
2/26/92 First public release of the draft without non-disclosure agreement. Revision 1.05.
4/12/92 Pointer types (always 32 bits in MAPI) now use "LP" instead of "P" for compatability with other header files.
4/15/92 Updated to latest structure names used in the Property interface.
Copyright © 1991, 1992 Microsoft Corporation. All Rights Reserved.
DRAFT SUBJECT TO CHANGE
| 