IMSProvider::Logon

The IMSProvider::Logon method logs MAPI on to one instance of a message store provider.

Quick Info

See IMSProvider : IUnknown0CR_PO.

HRESULT Logon(

Parameters

lpMAPISup

[in] Pointer to the current 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 store provider 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 lpEntryID 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_NO_MAIL

The message store should not be used for sending or receiving mail. The flag signals MAPI not to notify the MAPI spooler that this message store is being opened. If this flag is set, and the message store is tightly coupled with a transport provider, then the provider does not need to call the IMAPISupport::SpoolerNotifyRYSE6K method.

MDB_TEMPORARY

Logs on the store so that information can be retrieved programmatically from the profile section, without use of dialog boxes. This flag instructs MAPI that the store is not to be added to the message store table and that the store cannot be made permanent. If this flag is set, message store providers do not need to call the IMAPISupport::ModifyProfile1832SLO method.

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.

lpcbSpoolSecurity

[out] Pointer to the variable where the store provider returns the size, in bytes, of the validation data in the lppbSpoolSecurity parameter.

lppbSpoolSecurity

[out] Pointer to the pointer to the returned validation data. This validation data is provided so the IMSProvider::SpoolerLogon18QHGV method can log the MAPI spooler on to the same store as the message store provider.

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_FAILONEPROVIDER

This provider cannot log on, but this error should not disable the service.

MAPI_E_LOGON_FAILED

A logon session could not be established.

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_E_USER_CANCEL

The user canceled the operation, typically by clicking the Cancel button in a dialog box.

MAPI_E_UNKNOWN_CPID

The server is not configured to support the client's code page.

MAPI_E_UNKNOWN_LCID

The server is not configured to support the client's locale information.

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

MAPI calls the IMSProvider::Logon method to do the majority of processing necessary to obtain access to a message store. Message store providers validate any user credentials necessary to access a particular store and return a message store object in the lppMDB parameter that the MAPI spooler and client applications can log onto.

In addition to the message store object returned for client and MAPI spooler use, the provider also returns a message store logon object for MAPI s use in controlling the opened store. The message store logon object and the message store object should be tightly linked inside the message store provider so each can affect the other. Usage of the store object and the logon object should be identical; 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 exposing two interfaces. The two objects should also be created together and freed together.

The MAPI support object, created by MAPI and passed to the provider in the lpMAPISup parameter, provides access to functions in MAPI required by the provider. These include functions that save and retrieve profile information, access address books, and so on. The lpMAPISup pointer can be different for each store that is opened. While processing calls for a message store after logon, the store provider should use the lpMAPISup variable specific to that store. For any Logon call that opens a message store and succeeds in creating a message store logon object, the provider must save a pointer to the MAPI support object in the store logon object and must call the IUnknown::AddRef method to add a reference for the support object.

The ulUIParam parameter should be used if the provider presents dialog boxes during the Logon call. However, dialog boxes should not be presented if ulFlags contains the MDB_NO_DIALOG flag. If a user interface is called but ulFlags does not allow it, or if for some other reason a user interface cannot be displayed, the provider should return MAPI_E_LOGON_FAILED. If Logon displays a dialog box and the user cancels logon, typically by clicking the dialog box s Cancel button, the provider should return MAPI_E_USER_CANCEL.

The lpEntryID parameter can either be NULL or point to an unwrapped store entry identifier previously created by this message store. If lpEntryID points to an unwrapped entry identifier, that entry identifier can come from one of several places:

    It can be an entry identifier that the store provider previously wrapped and wrote to the profile section as a PR_ENTRYID2JH9H8T property.

    It can be an entry identifier that the provider previously wrapped and returned to a calling client as a PR_STORE_ENTRYIDSH8V.D property.

    It can be an entry identifier that the provider previously wrapped and returned to a calling client as the PR_ENTRYID property of a message store object.

In any of these cases, it is possible that the entry identifier was created on a different computer than the one currently being used.

When lpEntryID is not NULL, it should contain all of the information needed to identify and locate the message store. This information can include network volume names, phone numbers, user account names, and so on. If the connection to the store cannot be made using the data in the entry identifier, then the store provider should display a dialog box that enables the user to select the store to be opened. A dialog box might be required, for example, if a server has been renamed, an account name has changed, or portions of the network are not running.

When lpEntryID is NULL, the message store to use has not yet been selected. The provider can still access a store without displaying a dialog box if it supports further methods to specify the store. For example, the provider can check its initialization file, or it can look for additional properties that were placed in its or its message service s profile section at configuration.

If a provider finds that all the required information is not in the profile, it should return MAPI_E_UNCONFIGURED so that MAPI calls the provider s message service entry point function to enable the user to select a store, or even to create one, and to enter an account name and password as needed. MAPI automatically creates a new profile section for a new store; this new profile section can be temporary or permanent, depending on how it has been added. If the store provider calls the IMAPISupport::ModifyProfile1832SLO method, the new profile section becomes permanent and the store is added to the list of message stores returned by the IMAPISession::GetMsgStoresTableCF6D2F method.

The lpInterface parameter specifies the IID of the interface required for the newly opened store object. Passing NULL in lpInterface specifies that the MAPI message store interface, IMsgStore9A02HD, is required. Passing the message store object, IID_IMsgStore, also specifies that IMsgStore is required. If IID_IUnknown is passed in lpInterface, the provider should open the store using whatever interface derived from IUnknown that is best for the provider; again, this is typically IMsgStore. When IID_IUnknown is passed, after the store open operation succeeds the calling implementation uses the IUnknown::QueryInterface method to select an interface.

The IMSProvider::Logon call should return sufficient information, such as a path to the store and credentials for accessing the store, to allow the MAPI spooler to log onto the same store the store provider does without presenting a dialog box. The parameters lpcbSpoolSecurity and lppbSpoolSecurity are used to return this information. The provider allocates the memory for this data by passing a pointer to a buffer in the MSProviderInit2AMNAUH function s lpfAllocateBuffer parameter; the provider places the size of this buffer in lpcbSpoolSecurity.

MAPI frees this buffer when appropriate. If the MAPI spooler s logon to the store can be accomplished from the information in the profile section alone, the provider can return NULL in lppbSpoolSecurity and zero for the information s size in lpcbSpoolSecurity. The MAPI spooler logon occurs as part of a different process than the store logon; because the buffer holding the passed information gets copied between processes, it might not be in memory at the same location for the MAPI spooler process as for the store provider process. Therefore, a provider shouldn t put addresses into this buffer. For more information on MAPI spooler logon, see IMSProvider::SpoolerLogon18QHGV.

Most store providers use the IMAPISession::OpenProfileSectionDJX54W method of the support object passed in the lpMAPISup parameter for saving and retrieving user credentials and options. OpenProfileSection enables a store provider to save additional arbitrary information in a profile section and associate it with logon for a particular resource. For example, a store provider can save the user account name and password associated with a resource and any paths or other necessary information needed to access that resource for its logon.

Properties with property identifiers 0x6600 through 0x67FF are secure properties available to the provider for its own use to store private data in profile sections. For more information on the uses of properties in profile section objects, see IProfSect : IMAPIProp4OE62IC.

In addition to any private data in properties with identifiers 0x6600 through 0x67FF, the store provider should provide information for the PR_DISPLAY_NAME1KS30YA property in its profile section. It should place in PR_DISPLAY_NAME the display name of the provider itself   an identifying string displayed to users so they can distinguish this message store from others they might have access to   for example, Microsoft Personal Information Store. PR_DISPLAY_NAME commonly contains a server name, user account name, or path.

Some profile section properties are visible in the message store table; others are visible during setup, installation, and configuration of the MAPI subsystem. The provider typically provides information for these visible properties both for a new profile section, which does not yet include saved credentials or private information, and when it finds that property information has changed. For more information on profile sections, see IMAPISupport::OpenProfileSectionJSWD36.

After successfully logging on a user, and before returning to MAPI, the store provider should create the array of properties for the status row for the resource and call IMAPISupport::ModifyStatusRowF5S5Z4.

Logon calls that open message stores already open for the current MAPI session skip much of the processing described previously. These calls do not create status rows, do not return message store logon objects, do not call AddRef for the MAPI support object, and do not return data for MAPI spooler logon. These calls do return S_OK and do return a message store object with the interface requested.

To detect such calls, the provider should maintain a list in the message store provider object of stores already open for this provider object. When processing a Logon call, the provider should scan this list of open stores and determine if the store to be logged onto is already open. If it is, user credentials do not need to be checked and dialog box display should be avoided if possible. If dialog boxes must be displayed, the provider should check information returned to see whether a store has been opened a second time. In addition, the provider should check for duplicate openings using lpEntryID at the beginning of Logon call processing.

Standard processing for a Logon call that accesses an open store is as follows:

  1.  The store provider calls AddRef for the existing store object if the new interface being requested is the same as the interface for the existing store. Otherwise, it calls QueryInterface to get the new interface. If the new interface isn t one the store supports, the provider should return the error value MAPI_E_INTERFACE_NOT_SUPPORTED.

  2.  The provider returns a pointer to the required interface of the existing store object in lppMDB.

  3.  The provider returns NULL in lppMSLogon.

  4.  The provider should not open the profile for the support object passed in the call. Neither should it register a provider unique identifier, register a status row, nor return MAPI spooler logon data.

  5.  The provider should not call AddRef for the support object, because it does not require a pointer to the object.

Whenever possible, providers should return appropriate error and warning strings for Logon calls because doing so greatly eases the burden of users in figuring out why something did not work. To do so, a provider sets the members in the MAPIERROR4GS6AI structure. MAPI looks for, uses, and releases the MAPIERROR structure if it is returned by a provider.

Memory for this MAPIERROR should be allocated using the buffer passed in lpfAllocateBuffer on the MSProviderInit call. Any error strings contained in the returned structure should be in Unicode format if MAPI_UNICODE is set in the Logon ulFlags; otherwise, they should be in the ANSI character set.

For most error values returned from Logon, MAPI disables the message services to which the failing provider belongs. MAPI will not call any providers belonging to those services for the rest of the life of the MAPI session. In contrast, when Logon returns the MAPI_E_FAILONEPROVIDER error value from its logon, MAPI does not disable the message service to which the provider belongs. Logon should return MAPI_E_FAILONEPROVIDER if it encounters an error that does not warrant disabling the entire service for the life of the session. For example, a provider might return this error when it does not allow the display of a user interface and a required password is unavailable.

If a provider returns MAPI_E_UNCONFIGURED from its logon, MAPI will call the provider s message service entry function and then retry the logon. MAPI passes MSG_SERVICE_CONFIGURE as the context, to give the service a chance to configure itself. If the client has chosen to allow a user interface on the logon, the service can present its configuration property sheet so the user can enter configuration information.

See Also