XPProviderInit 

The XPProviderInit function initializes a transport provider for operation.

Quick Info

HRESULT XPProviderInit(

Parameters

hInstance

[in] The instance of the transport provider s dynamic-link library (DLL) that MAPI used when it linked.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The transport provider may need to use this allocation method when working with certain interfaces such as IStream.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer1MW3BAZ function, to be used where required by MAPI to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMoreB1SGX_ function, to be used where required by MAPI to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer16U06F function, to be used where required by MAPI to free memory.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_NT_SERVICE

The provider is being loaded in the context of a Windows NT service, a special type of process without access to any user interface.

ulMAPIVer

[in] Version number of the service provider interface (SPI) that MAPI.DLL uses. For the current version number, see the MAPISPI.H header file.

lpulProviderVer

[out] Pointer to the version number of the SPI that this transport provider uses.

lppXPProvider

[out] Pointer to a pointer to the initialized transport provider object.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_VERSION

The SPI version being used by MAPI is not compatible with the SPI being used by this provider.

Remarks

MAPI calls the entry point function XPProviderInit to initialize a transport provider following a client logon.

Notes to Implementers

A transport provider must implement XPProviderInit as an entry point function in the provider s DLL. The implementation must be based on the XPPROVIDERINIT function prototype, also specified in MAPISPI.H. MAPI defines XPPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes XPProviderInit to follow the CDECL calling convention. The advantage of CDECL is that calls can be attempted even if the number of calling parameters does not match the number of defined parameters.

A provider can be initialized multiple times, as a result of appearing in several profiles in simultaneous use or of appearing more than once in the same profile. XPProviderInit must return a different provider object in lppXPProvider for each initialization.

The transport provider should use the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation. In particular, the provider must use these functions to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetPropsK06IXU and IMAPITable::QueryRowsKPHHB. If the provider also expects to use the OLE memory allocator, it should call the IUnknown::AddRef method of the allocator object pointed to by the lpMalloc parameter.

For more information on writing XPProviderInit, see Initializing the Transport Provider2GSG3ZT. For more information on entry point functions, see About Provider Entry Point FunctionsT3ZERT.

See Also