IBroadcastEvent

IBroadcastEvent インターフェイスを使用すると、直接的なコネクションポイントを設定することなく、あるオブジェクトが別のオブジェクトからイベントを受信できるようになります。通常、アプリケーションがこのインターフェイスを使用する必要はありません。

ブロードキャストイベントは、DirectShow フィルター、Video Control の機能、および Video Control デバイスオブジェクト間の通信を可能にします。ブロードキャストイベントを送信するには、オブジェクトが Broadcast Event Service オブジェクトに対して IBroadcastEvent::Fire を呼び出します。他のオブジェクトは、Broadcast Event Service オブジェクトとのコネクションポイントを設定することで、イベントをリッスンできます。リスナーは IBroadcastEvent を実装し、Broadcast Event Service オブジェクトは、新しいブロードキャストイベントが発生するたびにリスナーの Fire メソッドを呼び出します。

ブロードキャストイベントは、いくつかの理由で役立ちます。

• DirectShow のイベントメカニズムである IMediaEventSink は、複数のリスナーをサポートしません。DirectShow のイベントはキューに入れられ、イベントを取得するとキューから削除されます。
• COM のコネクションポイントでは、シンクオブジェクトがソースオブジェクトを見つける必要があります。ブロードキャストイベントでは、Broadcast Event Service がソースオブジェクトとシンクオブジェクトの間の中継役を果たします。
• コネクションポイントでは、ソースはシンクが接続を確立したときと同じスレッド上でイベントを発生させるか、そうでなければイベントインターフェイスのポインターをマーシャリングする必要があります。フィルターグラフはマルチスレッドであるため、Broadcast Event Service オブジェクトが必要なマーシャリングを実装します。バックグラウンドスレッドを使用して、登録されているすべてのリスナーにイベントを配信します。

IBroadcastEvent インターフェイスはサービスであり、Filter Graph Manager の IServiceProvider インターフェイスを通じて取得できます。取得するには、IServiceProvider::QueryService を呼び出し、次の値を指定します。

• サービス識別子: SID_SBroadcastEventService
• インターフェイス識別子: IID_IBroadcastEvent

QueryService から失敗コードが返された場合は、まだどのオブジェクトも Broadcast Event Service オブジェクトを Filter Graph Manager に登録していないことを示します。その場合は、次の手順を実行します。

1. CoCreateInstance を使用して、新しい Broadcast Event Service オブジェクトを作成します。
2. Filter Graph Manager に対して IRegisterServiceProvider を照会します。
3. サービス識別子を指定して IRegisterServiceProvider::RegisterService を呼び出します。

IBroadcastEvent インターフェイスへのポインターを取得すると、イベントの送信またはイベントの受信(シンク)のいずれにも使用できます。イベントを送信するには、Fire メソッドを呼び出します。イベントを受信するには、シンクオブジェクトに IBroadcastEvent を実装し、Broadcast Event Service に対して IConnectionPoint を照会し、IConnectionPoint::Advise を呼び出して接続を確立します。定義済みのブロードキャストイベントの一覧については、IBroadcastEvent::Fire を参照してください。

このインターフェイスのインターフェイス識別子 (IID) を宣言するには、__uuidof 演算子を使用します: __uuidof(IBroadcastEvent)。

例

次の例では、ブロードキャストイベントの送信元(ソース)または受信先(シンク)となることができるクラスを実装しています。

class TunerEvent : public IBroadcastEvent
{

private:
    long m_nRefCount; // 参照カウントを保持します。
public:
    // IUnknown メソッド
    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 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;
    }

    // 唯一の IBroadcastEvent メソッド。
    STDMETHOD(Fire)(GUID eventID)
    {
        // 唯一の定義済みイベント。
        if (eventID == EVENTID_TuningChanged)
        {
            // チューナーが放送局またはチャンネルを変更しました。
        }
        
        return S_OK;
    }

    TunerEvent() : m_dwBroadcastEventCookie(0), m_nRefCount(1) {};

private:
    HRESULT HookupGraphEventService(IFilterGraph *pGraph);
    HRESULT RegisterForTunerEvents();
    HRESULT UnRegisterForTunerEvents();
    HRESULT Fire_Event(GUID eventID);

    CComPtr<IBroadcastEvent>   m_spBroadcastEvent; 
    DWORD m_dwBroadcastEventCookie;
};

// Filter Graph Manager にブロードキャストイベントサービスを照会します。
// 見つからない場合は、作成して登録します。
HRESULT TunerEvent::HookupGraphEventService(IFilterGraph *pGraph)
{
    HRESULT hr = S_OK;
    if (!m_spBroadcastEvent)
    {
        CComQIPtr<IServiceProvider> spServiceProvider(pGraph);
        if (!spServiceProvider)
        {
            return E_NOINTERFACE;
        }
        hr = spServiceProvider->QueryService(SID_SBroadcastEventService, 
            IID_IBroadcastEvent, 
            reinterpret_cast<void**>(&m_spBroadcastEvent));
        if (FAILED(hr))
        {
            // Broadcast Event Service オブジェクトを作成します。
            hr = m_spBroadcastEvent.CoCreateInstance(
                CLSID_BroadcastEventService,
                NULL, CLSCTX_INPROC_SERVER);
            if (FAILED(hr))
            {
                return hr; 
            }
            
            CComQIPtr<IRegisterServiceProvider> spRegService(pGraph);
            if (!spRegService)
            {
                return E_NOINTERFACE;
            }
            
            // Broadcast Event Service オブジェクトをサービスとして登録します。
            hr = spRegService->RegisterService(
                SID_SBroadcastEventService,
                m_spBroadcastEvent);
        }
    }
    return hr;
}

// イベントを受信するためのコネクションポイントを確立します。
HRESULT TunerEvent::RegisterForTunerEvents()
{
    if (!m_spBroadcastEvent)
    {
        return E_FAIL;  // HookupGraphEventService の呼び出しを忘れています。
    }
    if(m_dwBroadcastEventCookie)
    {
        return S_FALSE;  // 既に接続があります。何もすることはありません。
    }
    CComQIPtr<IConnectionPoint> spConnectionPoint(m_spBroadcastEvent);
    if(!spConnectionPoint)
    {
        return E_NOINTERFACE;
    }
    return spConnectionPoint->Advise(static_cast<IBroadcastEvent*>(this),
        &m_dwBroadcastEventCookie);
}

// イベントの登録を解除します。
HRESULT TunerEvent::UnRegisterForTunerEvents()
{
    HRESULT hr = S_OK;
    if(!m_dwBroadcastEventCookie)
    {
        return S_OK; // イベントに登録されていません。何もすることはありません。
    }
    CComQIPtr<IConnectionPoint> spConnectionPoint(m_spBroadcastEvent);
    if(!spConnectionPoint)
    {
        return E_NOINTERFACE;
    }
    
    // コネクションポイントを解放します。
    hr = spConnectionPoint->Unadvise(m_dwBroadcastEventCookie);
    if (FAILED(hr))
    {
        // エラー: コネクションポイントの登録解除ができませんでした。
        return hr;
    }
    m_dwBroadcastEventCookie = 0;
    m_spBroadcastEvent.Release();
    return S_OK;
}

// イベントを送信します(ソースオブジェクト用)。
HRESULT TunerEvent::Fire_Event(GUID eventID)
{
    if (!m_spBroadcastEvent)
    {
        return E_FAIL; // HookupGraphEventService の呼び出しを忘れています。
    }
    return m_spBroadcastEvent->Fire(eventID);
}

Fire メソッドは、ブロードキャストイベントを発生させます。

メソッドが成功した場合は S_OK を返します。失敗した場合はエラーコードを返します。

テレビのチューニングについては、次のイベントが定義されています。

チューナーイベント	説明
EVENTID_TuningChanged	チューナーが放送局またはチャンネルを変更したときに発生します。Bdamedia.h で定義されています。

TV レーティングコンポーネントによって発生するイベントの一覧については、TV Ratings Broadcast Events を参照してください。

#define global IID_IBroadcastEvent "{3B21263F-26E8-489D-AAC4-924F7EFD9511}"
#usecom global IBroadcastEvent IID_IBroadcastEvent "{}"
#comfunc global IBroadcastEvent_Fire  3 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。