ISpoolerHook::InboundMsgHook

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.

Quick Info

See ISpoolerHook : IUnknown.

HRESULT InboundMsgHook(
  LPMESSAGE lpMessage,   
  LPMAPIFOLDER lpFolder,   
  LPMDB lpMDB,           
  ULONG FAR * lpulFlags,   
  ULONG FAR * lpcbEntryID,   
  LPBYTE FAR * lppEntryID  
);
 

Parameters

lpMessage

[in] Pointer to the message to process.

lpFolder

[in] Pointer to the parent folder of the message in its message store.

lpMDB

[in] Pointer to the message store containing the folder and message.

lpulFlags

[out] Bitmask of flags that controls how the MAPI spooler responds to the hook for the message indicated in the lpMessage parameter. The following flags can be set:

HOOK_CANCEL

Any subsequent hook functions should not be called for this message. If a hook closes, moves, or deletes the message, the messaging hook provider should set this flag.

HOOK_DELETE

The message should be deleted without being moved.

lpcbEntryID

[in, out] Pointer to the size, in bytes, of the entry identifier pointed to by the lppEntryID parameter.

lppEntryID

[in, out] Pointer to the pointer to the entry identifier of the destination folder, if the hook processor moves the message. This can be NULL if the hook does not move the message.

Return Values

S_OK

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

Notes to Implementers

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.