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 that 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 |
A
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 the IMAPISupport::SpoolerNotify method 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 is 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