IMAPIStatus::ValidateState

The IMAPIStatus::ValidateState method confirms the external status information available for the MAPI resource or the service provider.

Quick Info

See IMAPIStatus : IMAPIPropL2ZHF1.

HRESULT ValidateState(

Parameters

ulUIParam

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

ulFlags

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

ABORT_XP_HEADER_OPERATION

The user has canceled the operation, typically by clicking the Cancel button in the corresponding dialog box. The status object has two options:

   Continue working on the operation

   Abort the operation and return MAPI_E_USER_CANCELED

CONFIG_CHANGED

One or more of the status object s configuration properties has changed. Clients can set this flag to allow the MAPI spooler to dynamically correct critical transport provider failures.

FORCE_XP_CONNECT

The status object should perform a connection. When this flag is used with the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE flag, the connection occurs without caching.

FORCE_XP_DISCONNECT

The status object should perform a disconnect operation. When this flag is used with the REFRESH_XP_HEADER_CACHE or PROCESS_XP_HEADER_CACHE flag, the disconnection occurs without caching.

PROCESS_XP_HEADER_CACHE

Entries in the header cache table should be processed, all messages marked with the MSGSTATUS_REMOTE_DOWNLOAD flag should be downloaded, and all messages marked with the MSGSTATUS_REMOTE_DELETE flag should be deleted. Messages that have both MSGSTATUS_REMOTE_DOWNLOAD and MSGSTATUS_REMOTE_DELETE set should be moved.

REFRESH_XP_HEADER_CACHE

For a remote transport provider, a new list of message headers should be downloaded and all flags marking message status should be cleared.

SUPPRESS_UI

Prevents the status object from displaying a user interface as part of the operation.

Return Values

S_OK

The validation was successful.

MAPI_E_BUSY

Another operation is in progress; it should be allowed to complete, or it should be stopped, before this operation should be initiated.

MAPI_E_NO_SUPPORT

The status object does not support the validation method, as indicated by the absence of the STATUS_VALIDATE_STATE flag in the PR_RESOURCE_METHODS1BJ9KZ4 property.

MAPI_E_USER_CANCEL

The user canceled the validation operation, typically by clicking the Cancel button in a dialog box. This value is only returned by remote transport providers.

Remarks

The IMAPIStatus::ValidateState method checks the state of a resource associated with a status object. ValidateState is the only method in the IMAPIStatus interface that is required for all status objects.

The exact behavior of this method depends on the implementation. The following table describes the implementation of each of the different types of status objects:

Notes to Callers

Because this method can result in other calls being made that take some time, ValidateState can return MAPI_E_BUSY to inform you that this method is dependent upon another operation s completion and that operation is still in progress. You should wait until the pending operation has completed before attempting another task.

You have the most control over your calls to transport provider status objects. You can pass one or more flags to ValidateState that affect the transport provider s operations. For example, if you set the flag ABORT_XP_HEADER_OPERATION, this indicates that the user has canceled the validation. Transport providers can choose to abort   returning MAPI_E_USER_CANCELED   or continue.

The CONFIG_CHANGED flag can be set on a call to either the status object of a service provider or the MAPI spooler to indicate that a configuration option has been altered. You can use CONFIG_CHANGED to dynamically reconfigure a transport provider. When called on a service provider s status object, the provider responds with a call to IMAPISupport::SpoolerNotifyRYSE6K to alert the MAPI spooler of the change. When called on the MAPI spooler s status object, the spooler calls IXPLogon::AddressTypes1JYXH3N for each of the active transport providers and IMAPISession::MessageOptionsEGEI.U. AddressTypes informs the MAPI spooler of a transport s supported address types; MessageOptions invokes the display of a property sheet showing a transport s message option properties. Some service providers also display a progress indicator if the validation is expected to take a long time. Displaying a progress indicator is helpful, but not required.

When the SUPPRESS_UI flag is set, none of the configuration property sheets can be displayed nor can any progress dialog boxes.