Compartilhar via

MAPIInitialize

  • Artigo

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Increments the MAPI subsystem reference count and initializes global data for the MAPI DLL.

Header file:

Mapix.h

Implemented by:

MAPI

Called by:

Client applications

 
HRESULT MAPIInitialize(
  LPVOID lpMapiInit
);

Parameters

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

Return Value

  • S_OK
    The MAPI subsystem was initialized successfully.

Remarks

The MAPIInitialize function increments the MAPI reference count for the MAPI subsystem, and the MAPIUninitialize 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_0 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 service must set the ulflags member of the MAPIINIT_0 structure pointed to by lpMapiInit to MAPI_NT_SERVICE.

NoteNote

You cannot call MAPIInitialize or MAPIUninitialize from within a Win32 DllMain function or any other function that creates or terminates threads. For more information, see Using Thread-Safe Objects.

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:

  1. Checks parameters and flags.

    MAPI_E_INVALID_PARAMETER or MAPI_E_UNKNOWN_FLAGS. Caller passed invalid parameter or flag.

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

    MAPI_E_TOO_COMPLEX. The calling process is a Windows service and registry keys required by MAPI could not be initialized.

    Additional information may be available in the application event log.

  3. Check for the compatibility of MAPI with OLE, then initialize OLE.

    1. 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.

    2. 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.

  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.

  5. Initializes shared global variables of all processes.

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

  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.

  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.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File

Function

Comment

ContentsTableListCtrl.cpp

MFCMAPI uses the MAPIInitialize method to initialize MAPI on a background thread to do some table processing.

See Also

Concepts

MFCMAPI as a Code Sample