IMSProvider::SpoolerLogon

The IMSProvider::SpoolerLogon method logs the MAPI spooler onto a message store.

Quick Info

See IMSProvider : IUnknown0CR_PO.

HRESULT SpoolerLogon(

Parameters

lpMAPISup

[in] Pointer to the MAPI support object for the message store.

ulUIParam

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

lpszProfileName

[in] Pointer to a string containing the name of the profile being used for the MAPI spooler logon. This string can be displayed in dialog boxes, written out to a log file, or simply ignored. It must be in Unicode format if the MAPI_UNICODE flag is set in the ulFlags parameter.

cbEntryID

[in] Size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier for the message store. Passing NULL in the lpEntryID parameter indicates that a message store has not yet been selected and that dialog boxes enabling the user to select a message store can be presented.

ulFlags

[in] Bitmask of flags that controls how the logon is performed. The following flags can be set:

MAPI_DEFERRED_ERRORS

The call is allowed to succeed even if the underlying object is not accessible to the calling implementation. If the object is not accessible, some subsequent call to the object might return an error.

MAPI_UNICODE

The passed-in strings are in Unicode format. If MAPI_UNICODE is not set, the strings are in ANSI format.

MDB_NO_DIALOG

Prevents display of logon dialog boxes. If this flag is set, the error value MAPI_E_LOGON_FAILED is returned if logon is unsuccessful. If this flag is not set, the message store provider can prompt the user to correct a name or password, to insert a disk, or to perform other actions necessary to establish connection to the store.

MDB_WRITE

Requests read/write access.

lpInterface

[in] Pointer to the interface identifier (IID) for the message store to log on to. Passing NULL indicates the MAPI interface for the message store is returned   that is, the IMsgStore9A02HD interface. The lpInterface parameter can also be set to an identifier for an appropriate interface for the message store, for example IID_IUnknown or IID_IMAPIProp.

cbSpoolSecurity

[in] Pointer to the size, in bytes, of validation data in the lppbSpoolSecurity parameter.

lpbSpoolSecurity

[in] Pointer to a pointer to validation data. The SpoolerLogon method uses this data to log the MAPI spooler on to the same store as the message store provider previously logged on to using the IMSProvider::LogonU3W4H6 method.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR4GS6AI structure, if any, containing version, component, and context information for an error. The lppMAPIError parameter can be set to NULL if there is no MAPIERROR structure to return.

lppMSLogon

[out] Pointer to the pointer to the message store logon object for MAPI to log on to.

lppMDB

[out] Pointer to the pointer to the message store object for the MAPI spooler and client applications to log on to.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_UNCONFIGURED

The profile does not contain enough information for the logon to complete. When this value is returned, MAPI calls the message store provider s message service entry point function.

MAPI_W_ERRORS_RETURNED

The call succeeded, but the message store provider has error information available. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling3AFTHZP. To get the error information from the provider, call the IMAPISession::GetLastError39J16BE method.

Remarks

The MAPI spooler calls the IMSProvider::SpoolerLogon method to log on to a message store. The MAPI spooler should use the message store object returned by the message store provider in the lppMDB parameter during and after logon.

For consistency with the IMSProvider::LogonU3W4H6 method, the provider also returns a message store logon object in the lppMSLogon parameter. Usage of the store object and the logon object are identical for usual store logon, because there is a one-to-one correspondence between the logon object and the store object; you can think of the logon and store objects as one object exposing two interfaces. The two objects are created together and freed together.

The store provider should internally mark the returned message store object to indicate that the store is being used by the MAPI spooler. Some of the methods for this store object behave differently than for the message store object provided to client applications. Keeping this internal mark is the most common way of triggering the behavior specific to the MAPI spooler.

See Also