ISpoolerHook::OutboundMsgHook

The ISpoolerHook::OutboundMsgHook method is called by the MAPI spooler to process outgoing messages. This processing can include archiving the message in a Sent Items folder, modifying the message, and so on.

Quick Info

See ISpoolerHook : IUnknown.

HRESULT OutboundMsgHook(
  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.

Remarks

The ISpoolerHook::OutboundMsgHook method is called after the message has been submitted to any transport providers. To process an outgoing message before the message is sent, use a preprocessor. See About Preprocessors for details.

Notes to Implementers

Messaging hook providers implement the ISpoolerHook::OutboundMsgHook method to process outbound messages. Because outbound message hooks are called after a message has been sent, they are typically used to save sent messages to one or more Sent Items folders. 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 move 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 saves 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 MAPIFreeBuffer function to free the previous one. The entry identifier the provider stores in lppEntryID should be allocated using the MAPIAllocateBuffer function.

If a messaging hook provider's implementation must move a message to another folder itself instead of allowing the MAPI spooler to move the message, it should close the message, place zero in the lpcbEntryID parameter, and free the lppEntryID entry identifier if it 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 sets the HOOK_CANCEL and HOOK_DELETE flags in lpulFlags. The MAPI spooler then deletes the message from its 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 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.