IOverlay::Advise method (strmif.h)
[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]
The Advise method sets up an advise link for the overlay events specified by the dwInterests parameter.
Syntax
HRESULT Advise(
[in] IOverlayNotify *pOverlayNotify,
[in] DWORD dwInterests
);
Parameters
[in] pOverlayNotify
Pointer to the notification interface.
[in] dwInterests
Callbacks of interest, which can be any subset of the following events.
| Event | Description |
|---|---|
| ADVISE_NONE | No changes. |
| ADVISE_CLIPPING | Change in clipping region (synchronized with the window). |
| ADVISE_PALETTE | Change in palette. |
| ADVISE_COLORKEY | Change of chroma key value. |
| ADVISE_POSITION | Change in position of video window (not synchronized with the window). |
| ADVISE_DISPLAY_CHANGE | Called on WM_DISPLAYCHANGE. The WM_DISPLAYCHANGE message is sent to all windows when the display resolution has changed. |
| ADVISE_ALL2 | All of the above. |
Return value
Returns S_OK if successful. If the method fails, it returns an HRESULT error code.
Remarks
This method sets up an advise link for the IOverlayNotify interface to receive notifications. If one of these events occurs, the appropriate entry point in the pOverlayNotify parameter passed in is called (IOverlayNotify::OnClipChange, IOverlayNotify::OnColorKeyChange, IOverlayNotify::OnPaletteChange, or IOverlayNotify::OnPositionChange).
Only one advise link can be set on any given IOverlay interface. Trying to set another notification interface on second and subsequent calls returns VFW_E_ADVISE_ALREADY_SET. You can cancel an advise link by using IOverlay::Unadvise.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | strmif.h (include Dshow.h) |
| Library | Strmiids.lib |