HrThisThreadAdviseSink

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Creates an advise sink that wraps an existing advise sink for thread safety.

HrThisThreadAdviseSink(
  LPMAPIADVISESINK lpAdviseSink,
  LPMAPIADVISESINK FAR * lppAdviseSink
);

Parameters

• lpAdviseSink
  [in] Pointer to the advise sink to be wrapped.

• lppAdviseSink
  [out] Pointer to a pointer to a new advise sink that wraps the advise sink pointed to by the lpAdviseSink parameter.

Return Value

None.

Remarks

The purpose of the wrapper is to make sure that notification is called on the same thread that called the HrThisThreadAdviseSink function. This function is used to protect notification callbacks that must run on a particular thread.

Client applications should use HrThisThreadAdviseSink to restrict when notifications are generated, that is, when calls are made to the IMAPIAdviseSink::OnNotify method of the advise sink object passed by the client in a previous Advise call. If notifications are allowed to be generated arbitrarily, a notification implementation might force a client into multithreaded operation when that would not be appropriate. For example, a client might use a library, such as one of the Microsoft Foundation Class Libraries, that does not support multithreaded calls. Notification on a different thread would make such a client difficult to test and prone to error.

   HrThisThreadAdviseSink makes sure that OnNotify calls occur only at these appropriate times:

• During processing of a call to any MAPI method.

• During processing of Windows messages.

When HrThisThreadAdviseSink is implemented, any calls to the new advise sink's OnNotify method on any thread cause the original notification method to be executed on the thread on which HrThisThreadAdviseSink was called.

For more information about notification and advise sinks, see Event Notification in MAPI and Implementing an Advise Sink Object.