IMAPIStatus::FlushQueues

The IMAPIStatus::FlushQueues method forces all messages waiting to be sent or received to be immediately uploaded or downloaded.

Quick Info

See IMAPIStatus : IMAPIProp.

HRESULT FlushQueues(
  ULONG ulUIParam,           
  ULONG cbTargetTransport,   
  LPENTRYID lpTargetTransport,   
  ULONG ulFlags              
);

Parameters

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

cbTargetTransport

[in] Count of bytes in the entry identifier pointed to by the lpTargetTransport parameter. The cbTargetTransport parameter is set only on calls to the MAPI spooler's status object. For calls to a transport provider, the cbTargetTransport parameter is set to zero.

lpTargetTransport

[in] Pointer to the entry identifier of the transport provider that is to flush its message queues. The lpTargetTransport parameter is set only on calls to the MAPI spooler's status object. For calls to a transport provider, the lpTargetTransport parameter is set to NULL.

ulFlags

[in] Bitmask of flags that controls the flush operation. The following flags can be set:

FLUSH_ASYNC_OK: The flush operation can occur asynchronously. This flag only applies to the MAPI spooler's status object.
FLUSH_DOWNLOAD: The inbound message queues should be flushed.
FLUSH_FORCE: The flush operation should occur regardless, in spite of the possibility of performance degradation. This flag must be set when targeting an asynchronous transport provider.
FLUSH_NO_UI: The status object should not display a progress indicator. This flag is used only by the MAPI spooler; providers ignore this flag.
FLUSH_UPLOAD: The outbound message queues should be flushed.

Return Values

S_OK: The flush operation was successful.
MAPI_E_BUSY: Another operation is in progress; it should be allowed to complete, or it should be stopped, before this operation can be initiated.
MAPI_E_NO_SUPPORT: The status object does not support this operation, as indicated by the absence of the STATUS_FLUSH_QUEUES flag in the status object's PR_RESOURCE_METHODS property.

Remarks

The IMAPIStatus::FlushQueues method requests that the MAPI spooler or a transport provider immediately send all messages in the outbound queue or receive all messages from the inbound queue. FlushQueues is only implemented by the MAPI spooler status object and by status objects supplied by transport providers.

The processing involved with FlushQueues can take a long time. By default, the MAPI spooler's implementation displays a progress indicator to keep the user informed. If the FLUSH_NO_UI flag is set in the ulFlags parameter, no progress indicator is displayed. Transport providers never display a progress indicator as part of their flush operation; they always ignore the FLUSH_NO_UI flag.

MAPI_E_BUSY should be returned for asynchronous requests so that clients can continue work.

By default, FlushQueues is a synchronous operation; control does not return to the caller until the flush has completed. Only the flush operation performed by the MAPI spooler can be asynchronous; clients request this behavior by setting the FLUSH_ASYNC_OK flag.

Notes to Implementers

A remote transport provider's implementation of FlushQueues sets bits in the PR_STATUS_CODE property in the logon object's status row to control how queues are flushed. If a remote viewer passes in the FLUSH_UPLOAD flag, the FlushQueues method should set the STATUS_INBOUND_ENABLED and STATUS_INBOUND_ACTIVE bits. If a remote viewer passes in the FLUSH_DOWNLOAD flag, the FlushQueues method should set the STATUS_OUTBOUND_ENABLED and STATUS_OUTBOUND_ACTIVE bits. FlushQueues should then return S_OK. The MAPI spooler will then initiate the appropriate actions to upload and download messages.

Notes to Callers

When calling the MAPI spooler status object, this is a directive to transfer all messages either to or from the appropriate transport provider. When calling an individual transport provider's status object, only the messages for that provider are affected.