IMSProvider::SpoolerLogon
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Logs the MAPI spooler on to a message store.
HRESULT SpoolerLogon(
LPMAPISUP lpMAPISup,
ULONG_PTR ulUIParam,
LPSTR 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] A pointer to the MAPI support object for the message store.ulUIParam
[in] A handle to the parent window of any dialog boxes or windows this method displays.lpszProfileName
[in] A pointer to a string that contains 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] The size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.lpEntryID
[in] A 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 that enable the user to select a message store can be presented.ulFlags
[in] A 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 available to the calling implementation. If the object is not available, a subsequent call to the object might raise 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 the display of logon dialog boxes. If this flag is set, the error value MAPI_E_LOGON_FAILED is returned if the 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 permission.
lpInterface
[in] A pointer to the interface identifier (IID) for the message store to log on to. Passing NULL indicates the MAPI interface for the message store (IMsgStore) is returned. 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] A pointer to the size, in bytes, of validation data in the lppbSpoolSecurity parameter.lpbSpoolSecurity
[in] A 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 by using the IMSProvider::Logon method.lppMAPIError
[out] A pointer to a pointer to the returned MAPIERROR structure, if any, that contains 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] A pointer to the pointer to the message store logon object for MAPI to log on to.lppMDB
[out] A pointer to the pointer to the message store object for the MAPI spooler and client applications to log on to.
Return Value
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. For more information, 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. The use of the store object and the logon object are identical for usual store logon; there should be a one-to-one correspondence between the logon object and the store object such that the objects act as if they are one object that exposes 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.