IFunctionDiscoveryNotification

このインターフェイスは、非同期クエリをサポートするためにクライアントプログラムによって実装され、クエリパラメーターに一致する関数インスタンスが追加または削除されたときにクライアントプログラムに通知するために Function Discovery によって呼び出されます。

Function Discovery から通知を受け取るには、クライアントプログラムがこのインターフェイスを実装する必要があります。クライアントプログラムの実装のアドレスをいずれかのクエリメソッドに渡すことで、クエリパラメーターに一致する関数インスタンスの通知が有効になります。

Function Discovery は、実際の通知を行うためにクライアントプログラムの IFunctionDiscoveryNotification::OnUpdate メソッドを呼び出します。この通知は、関数インスタンスが追加または削除されたときに生成されます。

例

個々のメソッドのページに掲載されている例は、次のクラス宣言に基づいています。

class CMyNotificationListener : public CFunctionDiscoveryNotificationWrapper
{
public:
    CMyNotificationListener() {
        m_hAddEvent      = CreateEvent( NULL, FALSE, FALSE, NULL );
        m_hRemoveEvent   = CreateEvent( NULL, FALSE, FALSE, NULL );
        m_hChangeEvent   = CreateEvent( NULL, FALSE, FALSE, NULL );
    }

    ~CMyNotificationListener() {
        CloseHandle( m_hAddEvent );
        CloseHandle( m_hRemoveEvent );
        CloseHandle( m_hChangeEvent );
    }
        

private:
    HANDLE m_hAddEvent, m_hRemoveEvent, m_hChangeEvent;
};

関数インスタンスが追加、削除、または変更されたことを示します。

クライアントプログラムによる OnUpdate メソッドの実装は、呼び出し元に次のいずれかの HRESULT 値を返す必要があります。

このメソッドからクエリオブジェクトに対して Release を呼び出さないでください。呼び出すとデッドロックが発生する可能性があります。コールバックの処理中に別のスレッドからクエリオブジェクトに対して Release が呼び出された場合、そのオブジェクトはコールバックが完了するまで解放されません。

プロバイダーによって Function Discovery に渡されるすべての通知はキューに格納され、クライアントへ 1 つずつ返されます。コールバックは同期されるため、クライアントが一度に受け取る通知は 1 つだけです。

他の IFunctionDiscoveryNotification メソッドの呼び出しが別のスレッドで行われる可能性があるため、呼び出し中にスレッドの状態に加えた変更は、メソッドを終了する前に元に戻す必要があります。

例

次のコードは OnUpdate ハンドラーの実装を示しています。CMyNotificationListener クラスは IFunctionDiscoveryNotification のトピックで定義されています。

#include <windows.h>

HRESULT STDMETHODCALLTYPE CMyNotificationListener::OnUpdate(
                                          IN QueryUpdateAction Action,
                                          IN FDQUERYCONTEXT fdqcQueryContext,
                                          IN IFunctionInstance *pInstance)
{
    HRESULT hr = S_OK;

    switch (Action) {
    case QUA_ADD:
        SetEvent( m_hAddEvent );
        break;
    case QUA_REMOVE:
        SetEvent( m_hRemoveEvent );
        break;
    case QUA_CHANGE:
        SetEvent( m_hChangeEvent );
        break;
    }
    return S_OK;
}

非同期クエリの処理中に発生したエラーを受け取ります。

クライアントプログラムによる OnError メソッドの実装は、呼び出し元に次のいずれかの HRESULT 値を返す必要があります。

通常、クライアントは、非同期エラーはすべて致命的でありクエリが結果を返さなくなると想定しますが、カスタムプロバイダーのドキュメントでは特定のエラーコードについて別の動作が示されている場合があります。

このメソッドからクエリオブジェクトに対して Release を呼び出さないでください。呼び出すとデッドロックが発生する可能性があります。コールバックの処理中に別のスレッドからクエリオブジェクトに対して Release が呼び出された場合、そのオブジェクトはコールバックが完了するまで解放されません。

プロバイダーによって Function Discovery に渡されるすべての通知はキューに格納され、クライアントへ 1 つずつ返されます。コールバックは同期されるため、クライアントが一度に受け取る通知は 1 つだけです。

他の IFunctionDiscoveryNotification メソッドの呼び出しが別のスレッドで行われる可能性があるため、呼び出し中にスレッドの状態に加えた変更は、メソッドを終了する前に元に戻す必要があります。

通知中に発生した追加、削除、または更新の各イベントを受け取ります。

クライアントプログラムによる OnEvent メソッドの実装は、呼び出し元に次のいずれかの HRESULT 値を返す必要があります。

Function Discovery プロバイダー(SSDP および WSD)は、検索パスが完了したことを通知するためにこのメソッドを使用します。

このメソッドからクエリオブジェクトに対して Release を呼び出さないでください。呼び出すとデッドロックが発生する可能性があります。コールバックの処理中に別のスレッドからクエリオブジェクトに対して Release が呼び出された場合、そのオブジェクトはコールバックが完了するまで解放されません。

プロバイダーによって Function Discovery に渡されるすべての通知はキューに格納され、クライアントへ 1 つずつ返されます。コールバックは同期されるため、クライアントが一度に受け取る通知は 1 つだけです。

他の IFunctionDiscoveryNotification メソッドの呼び出しが別のスレッドで行われる可能性があるため、呼び出し中にスレッドの状態に加えた変更は、メソッドを終了する前に元に戻す必要があります。

例

次の例は OnEvent ハンドラーの実装を示しています。CMyNotificationListener クラスは IFunctionDiscoveryNotification のトピックで定義されています。

#include <windows.h>

HRESULT CMyNotificationListener::OnEvent(
                                         IN DWORD dwEventID,
                                         IN FDQUERYCONTEXT fdqcQueryContext,
                                         IN const WCHAR * pszProvider
                                         )
{
    HRESULT hr = S_OK;
    HANDLE hSearchComplete = INVALID_HANDLE_VALUE;
    hSearchComplete = OpenEventW( EVENT_ALL_ACCESS, 
                                  FALSE, 
                                  L"SearchComplete" );
    
    if( NULL == hSearchComplete )
    {
        return hr;
    }

    if( FD_EVENTID_SEARCHCOMPLETE == dwEventID )
    {
        SetEvent( hSearchComplete );
    }

    CloseHandle( hSearchComplete );
    
    return hr;
}