IBroadcastEvent Interface

Microsoft DirectShow 9.0

IBroadcastEvent Interface

This topic applies to Windows XP or later.

The IBroadcastEvent interface enables an object to receive events from another object without setting up a direct connection point. Applications typically do not need to use this interface.

In addition to the methods inherited from IUnknown, the IBroadcastEvent interface exposes the following method.

Method	Description
Fire	Fires an event.

Remarks

Broadcast events enable communication among DirectShow filters, Video Control features, and Video Control device objects. To send a broadcast event, an object calls IBroadcastEvent::Fire on the Broadcast Event Service object. Other objects can listen for events by setting up a connection point with the Broadcast Event Service object. The listener implements IBroadcastEvent and the Broadcast Event Service object calls the listener's Fire method whenever there is a new broadcast event.

Broadcast events are useful for several reasons:

• The DirectShow event mechanism, IMediaEventSink, does not support multiple listeners. DirectShow events go onto a queue, and retrieving an event removes it from the queue.
• COM connection points require the sink object to locate the source object. With broadcast events, the Broadcast Event Service acts as a relay between the source object and the sink object.
• In a connection point, the source must fire events on the same thread that the sink used to establish the connection, or else marshal the event interface pointer. Filter graphs are multithreaded, so the Broadcast Event Service object implements the necessary marshaling. It uses a background thread to distribute events to all the registered listeners.

The IBroadcastEvent interface is a service, which can be obtained through the Filter Graph Manager's IServiceProvider interface. To do so, call IServiceProvider::QueryService and specify the following values:

• Service identifier: SID_SBroadcastEventService
• Interface identifier: IID_IBroadcastEvent

A failure code from QueryService indicates that no object has yet registered the Broadcast Event Service object with the Filter Graph Manager. In that case, do the following:

1. Create a new Broadcast Event Service object, using CoCreateInstance.
2. Query the Filter Graph Manager for IRegisterServiceProvider.
3. Call IRegisterServiceProvider::RegisterService with the service identifier.

Once you have a pointer to the IBroadcastEvent interface, you can use it either to send events or to sink events. To send events, call the Fire method. To sink events, implement IBroadcastEvent on the sink object, query the Broadcast Event Service for IConnectionPoint, and call IConnectionPoint::Advise to establish the connection. For a list of defined broadcast events, see IBroadcastEvent::Fire.

Example Code

The following example implements a class that can source or sink broadcast events:

  private:
    long m_nRefCount; // Holds the reference count.

    // IUnknown methods
    STDMETHODIMP_(ULONG) AddRef()
    {
        return InterlockedIncrement(&m_nRefCount);
    }
    STDMETHODIMP_(ULONG) Release()
    {
        _ASSERT(m_nRefCount >= 0);
        ULONG uCount = InterlockedDecrement(&m_nRefCount);
        if (uCount == 0)
        {
            delete this;
        }
        // Return the temporary variable, not the member
        // variable, for thread safety.
        return uCount;
    }
    STDMETHODIMP QueryInterface(REFIID riid, void **ppvObject)
    {
        if (NULL == ppvObject)
            return E_POINTER;
        if (riid == __uuidof(IUnknown))
            *ppvObject = static_cast<IUnknown*>(this);
        else if (riid == __uuidof(IBroadcastEvent))
            *ppvObject = static_cast<IBroadcastEvent*>(this);
        else 
            return E_NOINTERFACE;
        AddRef();
        return S_OK;
    }

See Also

• Video Control Interfaces