MAPIInitialize 

The MAPIInitialize function increments the MAPI subsystem reference count and initializes global data for the MAPI DLL.

Quick Info

HRESULT MAPIInitialize(

Parameters

lpMapiInit

[in] Pointer to a MAPIINIT_01WTSGWP structure. The lpMapiInit parameter can be set to NULL.

Return Values

S_OK

The MAPI subsystem was initialized successfully.

Remarks

The MAPIInitialize function increments the MAPI reference count for the MAPI subsystem, and the MAPIUninitializeZ2OJUQ function decrements the internal reference count. Thus, the number of calls to one function must equal the number of calls to the other. MAPIInitialize returns S_OK if MAPI has not been previously initialized.

A client or service provider must call MAPIInitialize before making any other MAPI call. Failure to do so causes client or service provider calls to return the MAPI_E_NOT_INITIALIZED value.

When calling MAPIInitialize from a multithreaded application, set the lpMapiInit parameter to a MAPIINIT_01WTSGWP structure that is declared as follows:

MAPIINIT_0 MAPIINIT= {  0, MAPI_MULTITHREAD_NOTIFICATIONS}

and call:

MAPIInitialize (&MAPIINIT);

When this structure is declared, MAPI creates a separate thread to handle the notification window, which continues until the initialize reference count falls to zero. A Windows NT service must set the ulflags member of the MAPIINIT_0 structure pointed to by lpMapiInit to MAPI_NT_SERVICE.

MAPIInitialize does not return any extended error information. Unlike most other MAPI calls, the meanings of its return values are strictly defined to correspond to the particular step of the initialization that failed:

Step 1 Checks parameters and flags

MAPI_E_INVALID_PARAMETER or MAPI_E_UNKNOWN_FLAGS. Caller passed invalid parameter or flag.

Step 2  Initializes registry keys required by MAPI and confirms the type of operating system. This step only happens if the client process is runnning as a service under Windows NT and sets the MAPI_NT SERVICE flag in the MAPIINIT_0. 

MAPI_E_TOO_COMPLEX. (Windows NT only) The calling process is an NT service and registry keys required by MAPI could not be initalized.

Additional information may be available in the application event log.

Step 3a  Checks for compatibility between the current versions of OLE and MAPI. 

MAPI_E_VERSION. The version of OLE installed on the workstation is not compatible with this version of MAPI.

Step 3b Initializes OLE.   

During this step only, this function can return an error code not listed here. Any error not listed here should be assumed to come from the OLE function CoInitialize.

Step 4  Initializes per-process global variables.

MAPI_E_SESSION_LIMIT  MAPI sets up context specific to the current process. Failures may occur on Win16 if the number of processes exceeds a certain number, or on any system if available memory is exhausted.

Step 5  Initializes shared global variables of all processes.

MAPI_E_NOT_ENOUGH_RESOURCES. Not enough system resources were available to complete the operation

Step 6  Initializes the notification engine, creates its window and its thread if requested by the MAPI_MULTITHREAD_NOTIFICATIONS flag.

MAPI_E_INVALID_OBJECT  May fail if system resources are exhausted.

Step 7  Loads and initializes the profile provider. Verifies that MAPIInitialize can access the registry key where profile data are stored.

MAPI_E_NOT_INITIALIZED  The profile provider has encountered an error. In a service running under Windows NT version 3.51, the profile provider must first initialize the registry subtree called HKEY_CURRENT_USER, this occurs in Step 2. This process is subject to additional failures, including lack of access rights to the registry.