IMAPISupport::SpoolerNotify

The IMAPISupport::SpoolerNotify method notifies the MAPI spooler of a change in status or a request for service.

Quick Info

See IMAPISupport : IUnknown.

HRESULT SpoolerNotify(
  ULONG ulFlags,  
  LPVOID lpvData  
);
 

Parameters

ulFlags

[in] Bitmask of flags that indicates the type of notification. All of the flags except for NOTIFY_NEWMAIL_RECEIVED can be set by transport providers; only NOTIFY_NEWMAIL_RECEIVED and NOTIFY_READTOSEND are valid for message store providers.

The following flags are valid for the ulFlags parameter::

NOTIFY_CONFIG_CHANGE

Registers a request to change the transport provider's configuration.

NOTIFY_CRITICAL_ERROR

An unrecoverable error has occurred to the transport provider. Because both NOTIFY_SENTDEFERRED and NOTIFY_CRITICAL_ERROR use the lpvData parameter for transport provider calls, these flags are mutually exclusive.

NOTIFY_CRITSEC

Requests a critical section for the transport provider. The lpvData parameter is undefined and should be NULL.

NOTIFY_NEWMAIL

The MAPI spooler should download any newly received messages at the next available time. The lpvData parameter is undefined and should be set to NULL.

NOTIFY_NEWMAIL_RECEIVED

A new message has been received in the message store. The lpvData parameter points to a NEWMAIL_NOTIFICATION structure describing the message. This flag is used for message store providers that are tightly coupled with transport providers and is ignored if the store provider logged on with the MAPI_NO_MAIL flag set.

NOTIFY_NONCRIT

Releases a critical section that was obtained with a previous call to SpoolerNotify with ulFlags set to NOTIFY_CRITSEC. The lpvData parameter is undefined and should be set to NULL.

NOTIFY_READYTOSEND

The transport or message store provider is ready to send messages. The lpvData parameter is undefined and should be set to NULL.

NOTIFY_SENTDEFERRED

A previously deferred message should now be sent and the transport provider should be notified when it is ready to be delivered with a call to IXPLogon::SubmitMessage. The entry identifier of the deferred message is contained in an SBinary structure pointed to by lpvData. Because both NOTIFY_SENTDEFERRED and NOTIFY_CRITICAL_ERROR use the lpvData parameter, these flags are mutually exclusive.

lpvData

[in] Pointer to associated data applicable to a notification. The lpvData parameter points to valid data only when the following flags are set; lpvData is NULL when ulFlags is set to the other notification types:

Setting for ulFlags	Value for lpvData
NOTIFY_CRITICAL_ERROR	Information about the error.
NOTIFY_NEWMAIL_RECEIVED	NEWMAIL_NOTIFICATION structure with information about the newly delivered message.
NOTIFY_SENTDEFERRED	SBinary structure with entry identifier of deferred message.

Return Values

S_OK

The notification was successful.

Remarks

The IMAPISupport::SpoolerNotify method is implemented for message store and transport provider support objects. These providers call SpoolerNotify to notify the MAPI spooler of a change in status or a request for service. SpoolerNotify is called primarily by transport providers and may be called at any time during the session.

Notes to Transport Providers

If you have changed your configuration, call SpoolerNotify and set ulFlags to NOTIFY_CONFIG_CHANGED. SpoolerNotify responds by calling your IXPLogon::AddressTypes method to query for a change in supported address types and the IMAPISession::MessageOptions method to ask MAPI to display your configuration properties to the user.

If you need a critical section to ensure uninterrupted processing, call SpoolerNotify with ulFlags set to NOTIFY_CRITSEC. Setting this flag informs the MAPI spooler that it should not call your IXPLogon::Idle and IXPLogon::Poll methods. While you have a critical section open, return MAPI_E_BUSY whenever your IMAPIStatus::ValidateState method is called. When you have finished with the critical section, make another call to SpoolerNotify with ulFlags set to NOTIFY_NONCRIT.

For example, if you are a remote transport provider in the process of uploading messages, you might need to allow a user to enter a telephone number for establishing the remote connection. Before looping through your dialog box procedure, declare a critical section. When the user closes the dialog box, terminating the dialog box procedure, release the critical section.

When you set ulFlags to NOTIFY_CRITICAL_ERROR, the MAPI spooler makes no further calls to your provider except to release it. If you call SpoolerNotify with this flag set from IXPLogon::StartMessage or IXPLogon::SubmitMessage, return with an appropriate error value from the StartMessage or SubmitMessage call immediately after the SpoolerNotify call.

If you have recovered from a condition that previously caused you to fail, call SpoolerNotify with ulFlags set to NOTIFY_READYTOSEND. This flag indicates that you are again ready to handle messages.

Notes to Message Store Providers

Call SpoolerNotify, passing the NOTIFY_READYTOSEND flag in ulFlags, before you make your first call to IMAPISupport::PrepareSubmit in IMessage::SubmitMessage. This call to SpoolerNotify only needs to be made once per session.

If you are tightly coupled with a transport provider and you call SpoolerNotify with ulFlags set to NOTIFY_NEWMAIL_RECEIVED, the MAPI spooler opens the new message and begins processing the new message hook function. When processing is complete, the MAPI spooler calls your IMsgStore::NotifyNewMail method to inform you of your own new message.

For more information about calling SpoolerNotify, see any of the following topics:

Implementing the FlushQueues Method

Interacting with the MAPI Spooler

Message Reception Model

See Also

IMsgStore::NotifyNewMail, IXPLogon::StartMessage, IXPLogon::SubmitMessage