HPProviderInit 

The HPProviderInit function initializes a messaging hook provider for operation.

Quick Info

HRESULT HPProviderInit(

Parameters

lpSession

[in] Pointer to a copy of the object representing the MAPI spooler session. Because the session object is a copy, any component installed as part of the messaging hook provider must be considered  trusted code.  The messaging hook provider should call the IUnknown::AddRef method for the session object.

hInstance

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

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.

lpSectionUID

[in] Pointer to the MAPIUIDT02NXD of the messaging hook provider s profile section. HPProviderInit can open this identifier using a session-level call to the IMAPISupport::OpenProfileSectionJSWD36 method. However, because MAPI and the MAPI spooler control some properties in the session, the provider should use the range of provider-specific property identifiers for storage and retrieval of profile section properties.

ulFlags

[in] Bitmask of flags used to control whether the messaging hook provider is called for incoming or outgoing messages. The following flags can be set:

HOOK_INBOUND

The messaging hook provider processes messages inbound to the MAPI spooler.

HOOK_OUTBOUND

The messaging hook provider processes messages outbound from the MAPI spooler.

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.

lppSpoolerHook

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

Return Values

S_OK

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

Remarks

MAPI calls the entry point function HPProviderInit to initialize a messaging hook provider following a client logon.

Notes to Implementers

A messaging hook provider must implement HPProviderInit as an entry point function in the provider s DLL. The implementation must be based on the HPPROVIDERINIT function prototype, also specified in MAPIHOOK.H. MAPI defines HPPROVIDERINIT to use the standard MAPI initialization call type, STDMAPIINITCALLTYPE, which causes HPProviderInit 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. HPProviderInit must return a different provider object in lppSpoolerHook for each initialization.

The messaging hook 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.

If the provider needs to use mutex objects or critical sections, it should set them up during initialization using HPProviderInit. A mutex object should be owned by the message-hook provider object created by this function.

For more information on using the OLE method IUnknown::AddRef, see Implementing the IUnknown Interface47QR_OL.

For more information on writing HPProviderInit, see Implementing HPProviderInit for Hook ProvidersA6GI9M. For more information on entry point functions, see About Provider Entry Point FunctionsT3ZERT.

See Also

ABProviderInitDN1VRN, IMAPISession : IUnknown2MVW67N, MSProviderInit2AMNAUH, XPProviderInit.S2ZUT