複数のオブジェクトのプロパティの設定

[アーティクル]
01/28/2024

一部のデバイスドライバーでは、1 つの関数呼び出しで複数のオブジェクトのプロパティの設定をサポートしています。これは一括書き込みと呼ばれます。アプリケーションは、次の表で説明するインターフェイスを使用して一括書き込みを実行できます。

インターフェイス	説明
IPortableDeviceContent インターフェイス	コンテンツ固有のメソッドへのアクセスを提供します。
IPortableDeviceProperties インターフェイス	プロパティ固有のメソッドへのアクセスを提供します。
IPortableDevicePropertiesBulk インターフェイス	一括書き込み操作をサポートします。
IPortableDevicePropVariantCollection インターフェイス	一括操作のオブジェクト識別子を格納するために使用されます。
IPortableDeviceValuesCollection インターフェイス	書き込まれるプロパティを識別するために使用されます。

サンプルアプリケーションの ContentProperties.cpp モジュールの関数は WriteContentPropertiesBulk 、一括書き込み操作を示しています。

このサンプルで最初に実行するタスクは、指定されたドライバーが一括操作をサポートしているかどうかを判断することです。これを行うには、 IPortableDeviceProperties オブジェクトで QueryInterface を呼び出し、 IPortableDevicePropertiesBulk の存在を確認します。

HRESULT                                       hr                = S_OK;
GUID                                          guidContext       = GUID_NULL;
CSetBulkValuesCallback*                       pCallback         = NULL;
CComPtr<IPortableDeviceProperties>            pProperties;
CComPtr<IPortableDevicePropertiesBulk>        pPropertiesBulk;
CComPtr<IPortableDeviceValues>                pObjectProperties;
CComPtr<IPortableDeviceContent>               pContent;
CComPtr<IPortableDeviceValuesCollection>      pPropertiesToWrite;
CComPtr<IPortableDevicePropVariantCollection> pObjectIDs;
DWORD                                         cObjectIDs        = 0;
if (SUCCEEDED(hr))
{
    hr = pDevice->Content(&pContent);
    if (FAILED(hr))
    {
        printf("! Failed to get IPortableDeviceContent from IPortableDevice, hr = 0x%lx\n",hr);
    }
}



if (SUCCEEDED(hr))
{
    hr = pContent->Properties(&pProperties);
    if (FAILED(hr))
    {
        printf("! Failed to get IPortableDeviceProperties from IPortableDevice, hr = 0x%lx\n",hr);
    }
}



if (SUCCEEDED(hr))
{
    hr = pProperties->QueryInterface(IID_PPV_ARGS(&pPropertiesBulk));
    if (FAILED(hr))
    {
        printf("This driver does not support BULK property operations.\n");
    }
}

次のタスクでは、 IPortableDeviceValuesCollection オブジェクトを 作成します。これは、サンプルが書き込むプロパティ値を含むオブジェクトです。

HRESULT                                       hr                = S_OK;
GUID                                          guidContext       = GUID_NULL;
CSetBulkValuesCallback*                       pCallback         = NULL;
CComPtr<IPortableDeviceProperties>            pProperties;
CComPtr<IPortableDevicePropertiesBulk>        pPropertiesBulk;
CComPtr<IPortableDeviceValues>                pObjectProperties;
CComPtr<IPortableDeviceContent>               pContent;
CComPtr<IPortableDeviceValuesCollection>      pPropertiesToWrite;
CComPtr<IPortableDevicePropVariantCollection> pObjectIDs;
DWORD                                         cObjectIDs        = 0;
if (SUCCEEDED(hr))
{
    hr = CoCreateInstance(CLSID_PortableDeviceValuesCollection,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_IPortableDeviceValuesCollection,
                          (VOID**) &pPropertiesToWrite);
    if (FAILED(hr))
    {
        printf("! Failed to CoCreate IPortableDeviceValuesCollection for bulk property values, hr = 0x%lx\n", hr);
    }
}

この後、サンプルは IPortableDevicePropertiesBulkCallback インターフェイスのインスタンスを作成します。アプリケーションでは、このインターフェイスのメソッドを使用して、非同期の一括書き込み操作の進行状況を追跡します。

HRESULT                                       hr                = S_OK;
GUID                                          guidContext       = GUID_NULL;
CSetBulkValuesCallback*                       pCallback         = NULL;
CComPtr<IPortableDeviceProperties>            pProperties;
CComPtr<IPortableDevicePropertiesBulk>        pPropertiesBulk;
CComPtr<IPortableDeviceValues>                pObjectProperties;
CComPtr<IPortableDeviceContent>               pContent;
CComPtr<IPortableDeviceValuesCollection>      pPropertiesToWrite;
CComPtr<IPortableDevicePropVariantCollection> pObjectIDs;
DWORD                                         cObjectIDs        = 0;
if (SUCCEEDED(hr))
{
    pCallback = new CSetBulkValuesCallback();
    if (pCallback == NULL)
    {
        hr = E_OUTOFMEMORY;
        printf("! Failed to allocate CSetBulkValuesCallback, hr = 0x%lx\n", hr);
    }
}

サンプルアプリケーションが呼び出す次の関数はヘルパー CreateIPortableDevicePropVariantCollectionWithAllObjectIDs 関数です。この関数は、特定のデバイス上のすべてのオブジェクトを再帰的に列挙し、検出された各オブジェクトの識別子を含む IPortableDevicePropVariantCollection インターフェイス を返します。この関数は、ContentEnumeration.cpp モジュールで定義されています。

// 7) Call our helper function CreateIPortableDevicePropVariantCollectionWithAllObjectIDs
// to enumerate and create an IPortableDevicePropVariantCollection with the object
// identifiers needed to perform the bulk operation on.
if (SUCCEEDED(hr))
{
    hr = CreateIPortableDevicePropVariantCollectionWithAllObjectIDs(pDevice,
                                                                    pContent,
                                                                    &pObjectIDs);
}

IPortableDevicePropVariantCollection オブジェクトは、同じ VARTYPE のインデックス付き PROPVARIANT 値のコレクションを保持します。この場合、これらの値には、デバイスで見つかった各オブジェクトの特定のオブジェクト識別子が含まれます。

オブジェクト識別子とそれぞれの名前プロパティは、 IPortableDeviceValuesCollection オブジェクトに格納されます。名前のプロパティは、最初のオブジェクトに "NewName0" という名前プロパティが割り当てられ、2 番目のオブジェクトに "NewName1" という名前プロパティが割り当てられるように編成されます。

サンプルからの次の抜粋は、 IPortableDeviceValuesCollection オブジェクトがオブジェクト識別子と新しい名前文字列を使用して初期化された方法を示しています。

HRESULT                                       hr                = S_OK;
GUID                                          guidContext       = GUID_NULL;
CSetBulkValuesCallback*                       pCallback         = NULL;
CComPtr<IPortableDeviceProperties>            pProperties;
CComPtr<IPortableDevicePropertiesBulk>        pPropertiesBulk;
CComPtr<IPortableDeviceValues>                pObjectProperties;
CComPtr<IPortableDeviceContent>               pContent;
CComPtr<IPortableDeviceValuesCollection>      pPropertiesToWrite;
CComPtr<IPortableDevicePropVariantCollection> pObjectIDs;
DWORD                                         cObjectIDs        = 0;
if (SUCCEEDED(hr))
{
    hr = pObjectIDs->GetCount(&cObjectIDs);
    if (FAILED(hr))
    {
        printf("! Failed to get number of objectIDs from IPortableDevicePropVariantCollection, hr = 0x%lx\n", hr);
    }
}


if (SUCCEEDED(hr))
{
    for(DWORD dwIndex = 0; (dwIndex < cObjectIDs) && (hr == S_OK); dwIndex++)
    {
        CComPtr<IPortableDeviceValues>  pValues;
        PROPVARIANT                     pv = {0};

        PropVariantInit(&pv);
        hr = CoCreateInstance(CLSID_PortableDeviceValues,
                              NULL,
                              CLSCTX_INPROC_SERVER,
                              IID_IPortableDeviceValues,
                              (VOID**) &pValues);
        if (FAILED(hr))
        {
            printf("! Failed to CoCreate CLSID_PortableDeviceValues, hr = 0x%lx\n", hr);
        }

        // Get the Object ID whose properties we will set
        if (hr == S_OK)
        {
            hr = pObjectIDs->GetAt(dwIndex, &pv);
            if (FAILED(hr))
            {
                printf("! Failed to get next Object ID from list, hr = 0x%lx\n", hr);
            }
        }

        // Save them into the IPortableDeviceValues so the driver knows which object this proeprty set belongs to
        if (hr == S_OK)
        {
            hr = pValues->SetStringValue(WPD_OBJECT_ID, pv.pwszVal);
            if (FAILED(hr))
            {
                printf("! Failed to set WPD_OBJECT_ID, hr = 0x%lx\n", hr);
            }
        }

        // Set the new values.  In this sample, we attempt to set the name property.
        if (hr == S_OK)
        {
            CAtlStringW strValue;
            strValue.Format(L"NewName%d", dwIndex);

            hr = pValues->SetStringValue(WPD_OBJECT_NAME, strValue.GetString());
            if (FAILED(hr))
            {
                printf("! Failed to set WPD_OBJECT_NAME, hr = 0x%lx\n", hr);
            }
        }

        // Add this property set to the collection
        if (hr == S_OK)
        {
            hr = pPropertiesToWrite->Add(pValues);
            if (FAILED(hr))
            {
                printf("! Failed to add values to collection, hr = 0x%lx\n", hr);
            }
        }
        PropVariantClear(&pv);
    }
}

サンプルでは、オブジェクト識別子と名前のペアを含む IPortableDeviceValuesCollection オブジェクトを作成したら、非同期操作を開始できます。

非同期書き込み操作は、サンプルが IPortableDevicePropertiesBulk::QueueSetValuesByObjectList メソッドを呼び出すと開始されます。このメソッドは、一括操作が開始されようとしていることをドライバーに通知します。この後、サンプルは IPortableDeviceBulk::Start メソッドを呼び出して、新しい名前の値の実際の書き込みを開始します。

   HRESULT                                       hr                = S_OK;
   GUID                                          guidContext       = GUID_NULL;
   CSetBulkValuesCallback*                       pCallback         = NULL;
   CComPtr<IPortableDeviceProperties>            pProperties;
   CComPtr<IPortableDevicePropertiesBulk>        pPropertiesBulk;
   CComPtr<IPortableDeviceValues>                pObjectProperties;
   CComPtr<IPortableDeviceContent>               pContent;
   CComPtr<IPortableDeviceValuesCollection>      pPropertiesToWrite;
   CComPtr<IPortableDevicePropVariantCollection> pObjectIDs;
   DWORD                                         cObjectIDs        = 0;
   if (SUCCEEDED(hr))
   {
       hr = pPropertiesBulk->QueueSetValuesByObjectList(pPropertiesToWrite,
                                                        pCallback,
                                                        &guidContext);


       if(SUCCEEDED(hr))
       {
           // Cleanup any previously created global event handles.
           if (g_hBulkPropertyOperationEvent != NULL)
           {
               CloseHandle(g_hBulkPropertyOperationEvent);
               g_hBulkPropertyOperationEvent = NULL;
           }

           // In order to create a simpler to follow example we create and wait infinitly
           // for the bulk property operation to complete and ignore any errors.
           // Production code should be written in a more robust manner.
           // Create the global event handle to wait on for the bulk operation
           // to complete.
           g_hBulkPropertyOperationEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
           if (g_hBulkPropertyOperationEvent != NULL)
           {
               // Call Start() to actually being the Asynchronous bulk operation.
               hr = pPropertiesBulk->Start(guidContext);
               if(FAILED(hr))
               {
                   printf("! Failed to start property operation, hr = 0x%lx\n", hr);
               }
           }
           else
           {
               printf("! Failed to create the global event handle to wait on for the bulk operation. Aborting operation.\n");
           }
       }
       else
       {
           printf("! QueueSetValuesByObjectList Failed, hr = 0x%lx\n", hr);
       }
   }

このサンプルは、操作が完了するまで無限に長い時間待機します。これが運用アプリケーションの場合は、コードを変更する必要があります。

IPortableDevice インターフェイス
IPortableDeviceContent インターフェイス
IPortableDeviceProperties インターフェイス
IPortableDevicePropertiesBulk インターフェイス
IPortableDevicePropVariantCollection インターフェイス
プログラミングガイド

次の方法で共有

複数のオブジェクトのプロパティの設定

フィードバック

その他のリソース

次の方法で共有

複数のオブジェクトのプロパティの設定

関連トピック

フィードバック

その他のリソース