ABProviderInit
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Initializes an address book provider for operation.
Header file: |
Mapispi.h |
Implemented by: |
Address book providers |
Called by: |
MAPI |
HRESULT ABProviderInit(
HINSTANCE hInstance,
LPMALLOC lpMalloc,
LPALLOCATEBUFFER lpAllocateBuffer,
LPALLOCATEMORE lpAllocateMore,
LPFREEBUFFER lpFreeBuffer,
ULONG ulFlags,
ULONG ulMAPIVer,
ULONG FAR * lpulProviderVer,
LPABPROVIDER FAR * lppABProvider
);
Parameters
hInstance
[in] The instance of the address book 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 address book provider may need to use this allocation method when working with certain interfaces such as IStream.lpAllocateBuffer
[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.lpAllocateMore
[in] Pointer to the MAPIAllocateMore function, to be used where required by MAPI to allocate additional memory.lpFreeBuffer
[in] Pointer to the MAPIFreeBuffer 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 service, a special type of process without access to any user interface.
- MAPI_NT_SERVICE
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 address book provider uses.lppABProvider
[out] Pointer to a pointer to the initialized address book provider object.
Return Value
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 ABProviderInit to initialize an address book provider following a client logon.
Notes to Implementers
An address book provider must implement ABProviderInit as an entry point function in the provider's DLL. The implementation must be based on the ABPROVIDERINIT function prototype, also specified in MAPISPI.H. MAPI defines ABPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes ABProviderInit to follow the CDECL calling convention.
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. Because the provider object contains context, ABProviderInit must return a different provider object in lppABProvider for each initialization, even for multiple initializations in the same process.
The address book 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::GetProps and IMAPITable::QueryRows. 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 ABProviderInit, see Implementing an Address Book Provider Entry Point Function. For more information on entry point functions, see Implementing a Service Provider Entry Point Function.