DevCreateObjectQueryFromId 函式 （devquery.h）

建立裝置查詢，以根據指定的查詢參數和對象標識符擷取屬性。

語法

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

選擇性地提供 DEVPROPCOMPKEY 的陣列， 結構，指定當呼叫 pCallback pCallback 時，應針對查詢中物件擷取的屬性，以通知查詢將物件新增至其結果集。
如果在 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;否則為適當的錯誤值。

言論

當用戶端想要擷取特定物件身分識別的相關數據時，請使用此函式，而不是使用篩選條件 DevCreateObjectQuery。 此函式更有效率。

如需詳細資訊，請參閱 DevCreateObjectQuery的一節，這也適用於此函式。

例子

在下列範例中，會實作 PDEV_QUERY_RESULT_CALLBACK 方法，以在查詢狀態變更、專案已加入、更新或從查詢結果中移除時列印出狀態消息。 接下來，會實作簡單的查詢案例，其中 DevCreateObjectQueryFromId 會使用 interfacePath變數 所指定的物件識別符來呼叫 。

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;
}

要求

要求	價值
最低支援的用戶端	Windows 10 版本 1809
標頭	devquery.h
連結庫	Onecore.lib
DLL	Cfgmgr32.dll

另請參閱

DevCreateObjectQuery