DevGetObjects 関数 (devquery.h)

指定された要求されたプロパティとフィルター条件に基づいて、一連の DEV_OBJECT 構造体を同期的に取得します。

構文

HRESULT DevGetObjects(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in, optional] const DEVPROPCOMPKEY            *pRequestedProperties,
  [in]           ULONG                           cFilterExpressionCount,
  [in, optional] const DEVPROP_FILTER_EXPRESSION *pFilter,
  [out]          PULONG                          pcObjectCount,
  [out]          const DEV_OBJECT                **ppObjects
);

パラメーター

[in] ObjectType

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

[in] QueryFlags

ビットごとの OR 演算を使用して結合される DEV_QUERY_FLAGS 値の組み合わせ。 DevQueryFlagUpdateResults または DevQueryFlagAsyncClose をこの関数に渡しても無効です。

[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 である必要があります。

[out] pcObjectCount

ppObjects で返される DEV_OBJECT 構造体の数。

[out] ppObjects

DEV_OBJECT 結果の新しく割り当てられた配列を受け取るポインター。 呼び出し元は、DevFreeObjectsを使用してポインターを解放する必要があります。 オブジェクトが列挙されていない場合は、NULL が返されます。

戻り値

S_OKは、関数が検索条件を正常に評価し、一致するオブジェクトを返した場合に返されます。それ以外の場合は、適切なエラー値。

備考

この関数は、プロパティの取得中にオブジェクトを同期的に列挙する効率的な方法です。 返されるオブジェクトの配列は、DevFreeObjectsを使用して解放する必要があります。 フィルター条件を満たすオブジェクトに対して要求されたプロパティが存在しない場合、そのプロパティの DEV_OBJECT の DEVPROPERTY エントリには、DEVPROP_TYPE_EMPTYの種類があります。

この関数を使用する前に、配列に返されるデータの量と呼び出しがブロックできる期間を考慮してください。 DevCreateObjectQuery 関数を使用することをお勧めします。これにより、データを段階的かつ非同期的に使用できます。

例

次の例では、DevGetObjects を使用して、一連の DEVPROP_FILTER_EXPRESSION 構造体に一致する DEV_OBJECT のセットを取得する方法を示します。

void
Example1()
{
    HRESULT hr = S_OK;
    ULONG ObjectCount = 0;
    const DEV_OBJECT* ObjectList = NULL;
    DEVPROP_BOOLEAN DevPropTrue = DEVPROP_TRUE;
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_Device_InstanceId, DEVPROP_STORE_SYSTEM, NULL }
    };
    DEVPROP_FILTER_EXPRESSION ObjectFilter[] =
    {
        {
            DEVPROP_OPERATOR_AND_OPEN, {0}
        },
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_BOOLEAN,
                sizeof(DevPropTrue),
                (void*)&DevPropTrue
            }
        },
        {
            DEVPROP_OPERATOR_OR_OPEN, {0}
        },
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_DeviceInterface_ClassGuid, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_GUID,
                sizeof(GUID),
                (void*)&GUID_DEVINTERFACE_MOUSE
            }
        },
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_DeviceInterface_ClassGuid, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_GUID,
                sizeof(GUID),
                (void*)&GUID_DEVINTERFACE_KEYBOARD
            }
        },
        {
            DEVPROP_OPERATOR_OR_CLOSE, {0}
        },
        {
            DEVPROP_OPERATOR_AND_CLOSE, {0}
        }
    };

    hr = DevGetObjects(DevObjectTypeDeviceInterface,
                       DevQueryFlagNone,
                       RTL_NUMBER_OF(RequestedProperties),
                       RequestedProperties,
                       RTL_NUMBER_OF(ObjectFilter),
                       ObjectFilter,
                       &ObjectCount,
                       &ObjectList);

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

    for (ULONG i = 0; i < ObjectCount; i++)
    {
        wprintf(L"Retrieved object '%ws'\n",
                ObjectList[i].pszObjectId);
    }

  exit:

    if (ObjectList != NULL)
    {
        DevFreeObjects(ObjectCount, ObjectList);
    }

    return;
}

必要条件

関連項目

DevCreateObjectQuery の