DevCreateObjectQueryFromId 関数 (devquery.h)

指定したクエリ パラメーターとオブジェクト ID に基づいてプロパティを取得するデバイス クエリを作成します。

構文

HRESULT DevCreateObjectQueryFromId(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           PCWSTR                          pszObjectId,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in, optional] const DEVPROPCOMPKEY            *pRequestedProperties,
  [in]           ULONG                           cFilterExpressionCount,
  [in, optional] const DEVPROP_FILTER_EXPRESSION *pFilter,
  [in]           PDEV_QUERY_RESULT_CALLBACK      pCallback,
  [in, optional] PVOID                           pContext,
  [out]          PHDEVQUERY                      phDevQuery
);

パラメーター

[in] ObjectType

このクエリが操作する必要があるオブジェクトの種類を決定する DEV_OBJECT_TYPE 列挙体の値。

[in] pszObjectId

クエリが操作する必要があるオブジェクトの文字列識別子。

[in] QueryFlags

ビットごとの OR 演算を使用して結合される DEV_QUERY_FLAGS 値の組み合わせ。

[in] cRequestedProperties

pRequestedPropertiesで提供される DEVPROPCOMPKEY 構造体の数。 DevQueryFlagAllProperties 指定する場合は、0 に設定する必要があります。

[in, optional] pRequestedProperties

必要に応じて、pCallback 呼び出されたときにクエリの結果セット内のオブジェクトに対して取得するプロパティを指定する DEVPROPCOMPKEY 構造体の配列を提供 、結果セットへのオブジェクトの追加をクエリに通知します。
QueryFlagsで DevQueryFlagUpdateResults が指定された場合、クエリの結果セット内のオブジェクトに対してこれらのプロパティの値が変更された場合、クエリに通知されます。

DEVPROPCOMPKEY 構造体の LocaleName フィールドは無視され、NULL に設定する必要があります。

cRequestedProperties が 0 の場合、これは NULL である必要があります。

[in] cFilterExpressionCount

pFilterで提供される DEVPROP_FILTER_EXPRESSION 構造体の数。

[in, optional] pFilter

必要に応じて、クエリの結果セットに含めるオブジェクトのフィルター条件を指定する DEVPROP_FILTER_EXPRESSION 構造体の配列を提供します。 cFilterExpressionCount が 0 の場合、これは NULL である必要があります。

[in] pCallback

このクエリの結果を送信する必要がある PDEV_QUERY_RESULT_CALLBACK コールバック関数。

[in, optional] pContext

呼び出し元が指定したコンテキスト。 この値は、変更されていないコールバック関数に渡されます。

[out] phDevQuery

クエリを表すハンドルを受け取るポインター。 devQueryFlagsUpdateResults 指定した場合、クエリはハンドルが閉じられるまで更新を受け取ります。 DevCloseObjectQuery 呼び出して、このハンドルを閉じてクエリを停止します。

戻り値

クエリが正常に作成された場合、S_OKが返されます。それ以外の場合は、適切なエラー値。

備考

クライアントが ID を指定して特定のオブジェクトに関するデータを取得する場合は、フィルターで DevCreateObjectQuery を するのではなく、この関数を使用します。 この関数の方が効率的です。

詳細については、この関数にも適用 DevCreateObjectQueryの解説セクションを参照してください。

例

次の例では、PDEV_QUERY_RESULT_CALLBACK メソッドを実装して、クエリの状態が変更されたとき、項目がクエリ結果に追加、更新、または削除されたときに、ステータス メッセージを出力します。 次に、DevCreateObjectQueryFromId を InterfacePath変数で指定されたオブジェクト ID で呼び出す単純なクエリ シナリオ 実装します。

void WINAPI
Example1Callback(
    HDEVQUERY hDevQuery,
    PVOID pContext,
    const DEV_QUERY_RESULT_ACTION_DATA *pActionData
    )
{
    UNREFERENCED_PARAMETER(hDevQuery);
    UNREFERENCED_PARAMETER(pContext);

    switch (pActionData->Action)
    {
    case DevQueryResultStateChange:
        if (pActionData->Data.State == DevQueryStateEnumCompleted)
        {
            wprintf(L"Enumeration of current system state complete.\n");
        }
        else if (pActionData->Data.State == DevQueryStateAborted)
        {
            wprintf(L"Query has aborted. No further results will be received.\n");
            // Communicate back to the creator of the query that it has aborted
            // so it can handle that appropriately, such as by recreating the
            // query
        }
        break;

    case DevQueryResultAdd:
        wprintf(L"Object '%ws' has been added to the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultUpdate:
        wprintf(L"Object '%ws' was updated.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultRemove:
        wprintf(L"Object '%ws' has been removed from the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;
    }
}

void
Example1(PCWSTR InterfacePath)
{
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_DeviceInterface_FriendlyName, DEVPROP_STORE_SYSTEM, NULL }
    };

    HDEVQUERY hDevQuery = NULL;
    HRESULT hr = DevCreateObjectQueryFromId(DevObjectTypeDeviceInterface,
                                            InterfacePath,
                                            DevQueryFlagUpdateResults,
                                            RTL_NUMBER_OF(RequestedProperties),
                                            RequestedProperties,
                                            0,
                                            NULL,
                                            Example1Callback,
                                            NULL,
                                            &hDevQuery);

    if (FAILED(hr))
    {
        wprintf(L"Failed to create query. hr = 0x%08x\n", hr);
        goto exit;
    }

    // do other work while the query monitors system state in the background

  exit:

    if (hDevQuery != NULL)
    {
        DevCloseObjectQuery(hDevQuery);
    }

    return;
}

必要条件

関連項目

DevCreateObjectQuery の