Platform SDK: MAPI |
The IMAPISupport::SpoolerNotify method notifies the MAPI spooler of a change in status or a request for service.
HRESULT SpoolerNotify( ULONG ulFlags, LPVOID lpvData );
The following flags are valid for the ulFlags parameter::
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. |
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.
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.
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
IMsgStore::NotifyNewMail, IXPLogon::StartMessage, IXPLogon::SubmitMessage