ISpoolerHook::InboundMsgHook

The ISpoolerHook::InboundMsgHook method informs the MAPI spooler it should allow the messaging hook provider to reroute a message from the Inbox to another folder.

Quick Info

See ISpoolerHook : IUnknownC3KEC4.

HRESULT InboundMsgHook(

Parameters

lpMessage

[in] Pointer to the message to reroute.

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 folder where the message will be moved.

Return Values

S_OK

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

Remarks

Messaging hook providers implement the ISpoolerHook::InboundMsgHook method to reroute a message from the default Inbox to another folder. Before moving a message to another folder or message store, 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.

Before rerouting 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. 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 MAPIFreeBuffer16U06F function to free the previous one. The copy of the entry identifier the provider stores in lppEntryID should be allocated using the MAPIAllocateBuffer1MW3BAZ function.

If a messaging hook provider s implementation must move a message to another folder itself, 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 deletes a message, it should close the message, place zero in lpcbEntryID, and place NULL in lppEntryID after freeing the existing entry identifier if need be. It then deletes the message and returns HOOK_CANCEL in lpulFlags. Alternatively, it can combine the HOOK_CANCEL and HOOK_DELETE flags in lpulFlags using the logical OR operator.

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 provider called the IUnknown::AddRef method for a session at initialization, 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.