The ISpoolerHook::InboundMsgHook method is called by the MAPI spooler. The method can perform arbitrary processing on an inbound message and can change the message's delivery point from the Inbox to another folder.
HRESULT InboundMsgHook(
LPMESSAGE lpMessage,
LPMAPIFOLDER lpFolder,
LPMDB lpMDB,
ULONG FAR * lpulFlags,
ULONG FAR * lpcbEntryID,
LPBYTE FAR * lppEntryID
);
Messaging hook providers implement the ISpoolerHook::InboundMsgHook method to process inbound messages. This processing can include rerouting a message from the default Inbox to another folder, modifying the message, or automatically deleting it. Before processing a message, a messaging hook provider should call the IUnknown::QueryInterface method for the message object to make sure the provider can get an interface for the message that is compatible with the provider's implementation.
To modify a message, the hook processor must change the values of the message's properties. For example, if a hook processor is created to make message delivery information explicit in the body of the message, it must take information from the message's header properties and insert it somewhere in the message's PR_BODY or PR_RTF_COMPRESSED properties. The hook processor should call the IMAPIProp::SaveChanges method after modifying the message's properties.
To reroute a message, a messaging hook provider must replace the passed-in entry identifier in lppEntryID with the entry identifier of the new target folder. The MAPI spooler moves the message to the indicated folder for the provider, unless another hook function replaces the folder entry identifier again. If a hook requires that its operation be the final action on the message, it can set the HOOK_CANCEL flag in the lpulFlags parameter before returning.
If a provider replaces the lppEntryID entry identifier, it must call the MAPIFreeBuffer function to free the original one. The entry identifier the provider stores in lppEntryID should be allocated using the MAPIAllocateBuffer function.
If a messaging hook must move a message to another folder itself rather than letting the MAPI spooler move the message, it should close the message, place zero in the lpcbEntryID parameter, and free the lppEntryID entry identifier, if lppEntryID is not already NULL. The hook then sets lppEntryID to NULL and places a pointer to the message's new parent folder in lpFolder. Messaging hook providers that move the message must set HOOK_CANCEL in lpulFlags.
If a hook needs to delete a message, it only needs to set both the HOOK_CANCEL and HOOK_DELETE flags in lpulFlags. The MAPI spooler will take care of deleting the message from the message store.
The MAPI spooler calls hook providers in the order in which they are specified in the provider section of the profile, as it does transport providers. The MAPI spooler releases the messaging hook provider object at session shutdown. If a hook provider calls the IUnknown::AddRef method for a session at initialization, at shutdown it should call the IUnknown::Release method to release the session and any objects, such as message stores, it opened and maintained during the session.