IMSProvider::SpoolerLogon

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

Quick Info

HRESULT SpoolerLogon(
  LPMAPISUP lpMAPISup,          
  ULONG ulUIParam,              
  LPTSTR lpszProfileName,       
  ULONG cbEntryID,              
  LPENTRYID lpEntryID,          
  ULONG ulFlags,                
  LPCIID lpInterface,           
  ULONG cbSpoolSecurity,        
  LPBYTE lpbSpoolSecurity,      
  LPMAPIERROR FAR * lppMAPIError,   
  LPMSLOGON FAR * lppMSLogon,   
  LPMDB FAR * lppMDB            
);

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 IMsgStore 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::Logon method.

lppMAPIError

[out] Pointer to a pointer to the returned MAPIERROR 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 Handling. To get the error information from the provider, call the IMAPISession::GetLastError 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::Logon 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.