IWMDMDevice3

IWMDMDevice3 インターフェイスは、デバイスのプロパティを照会するメソッドやデバイス I/O 制御コードを送信するメソッド、さらにストレージの検索やデバイスのフォーマット機能の取得を行う改良されたメソッドを提供することで、IWMDMDevice2 インターフェイスを拡張します。

GetProperty メソッドは、特定のデバイスメタデータプロパティを取得します。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準的な COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

サポートされているデバイスプロパティの一覧を取得するには、クライアントはこの関数を呼び出し、g_wszWMDMSupportedDeviceProperties を指定します。標準的なデバイスプロパティ名の一覧については、Metadata Constants を参照してください。

クライアントは、pValue パラメーターに空の PROPVARIANT へのポインターを渡す必要があります。戻り時には、pValue にプロパティの値が格納されます。

このメソッドは、ストレージに対する GetMetadata メソッドおよび GetSpecifiedMetadata メソッドに似ていますが、一度に 1 つのプロパティしか取得できません。

例

次の C++ コードは g_wszWMDMFormatsSupported プロパティを照会し、デバイスがサポートするフォーマットの SAFEARRAY リストを取得します。

// Query a device for supported configurations for each media or format type. 
HRESULT GetCaps(IWMDMDevice3* pDevice)
{
    HRESULT hr = S_OK;

    // Request the "formats supported" property to get a list of supported formats.
    PROPVARIANT pvFormatsSupported;
    PropVariantInit(&pvFormatsSupported);
    hr = pDevice->GetProperty(g_wszWMDMFormatsSupported, &pvFormatsSupported);
    HANDLE_HR(hr, "Got a property list in GetCaps", "Couldn't get a property list in GetCaps.");

    // Loop through the retrieved format list.
    // For each format, get a list of format configurations.
    SAFEARRAY* formatList = pvFormatsSupported.parray;
    WMDM_FORMATCODE formatCode = WMDM_FORMATCODE_NOTUSED;
    for(LONG iCap = 0; iCap < formatList->rgsabound[0].cElements; iCap++)
    { 
        // Get a format from the SAFEARRAY of retrieved formats.
        SafeArrayGetElement(formatList, &iCap, &formatCode);

        // Call a custom function to see the specifics of device support for 
       // each format.
        if (formatCode != WMDM_FORMATCODE_NOTUSED)
            myGetFormatCaps(formatCode, pDevice);
    }

e_Exit:
    // Clear out the memory we used.
    PropVariantClear(&pvFormatsSupported);
    return hr;
}

SetProperty メソッドは、書き込み可能な特定のデバイスプロパティを設定します。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準的な COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

このメソッドは、指定されたデバイスプロパティを設定します。サポートされているデバイスプロパティの一覧を取得するには、クライアントは IWMDMDevice3::GetProperty メソッドで g_wszWMDMSupportedDeviceProperties プロパティを照会します。

デバイスプロパティ名の一覧については、Metadata Constants を参照してください。

このメソッドは、ストレージに対する SetMetadata メソッドに似ていますが、一度に 1 つのプロパティしか設定できません。

デバイスのすべてのプロパティを設定できるわけではありません。

GetFormatCapability メソッドは、指定されたフォーマットのファイルに対するデバイスのサポート内容を取得します。この機能情報は、サポートされるプロパティと、それぞれに許可される値として表現されます。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準的な COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

クライアントは、IWMDMDevice3::GetProperty メソッドで g_wszWMDMFormatsSupported デバイスプロパティを照会することにより、サポートされているフォーマットの一覧を取得できます。

特定のフォーマットについて、クライアントはこの関数を呼び出すことで、サポートされるプロパティを取得し、サポートされるプロパティの構成 (たとえばビットレートとサンプルレートの組み合わせ) に関する情報を得ることができます。この情報はフォーマット機能 (format capability) として表現されます。

例

次の関数は、デバイスへのポインターとフォーマットコードを受け取り、そのフォーマットに対するデバイスのフォーマット機能を取得します。この関数は、取得した値を解放するためにカスタム関数を使用しています。このカスタム関数は Getting Format Capabilities on Devices That Support IWMDMDevice3 に示されています。

// Each format configuration is described by a WMDM_FORMAT_CAPABILITY enum, and
// has a WMDM_FORMAT_CAPABILITY structure describing the device capabilities for that format.
//        Each WMDM_FORMAT_CAPABILITY structure has a WMDM_PROP_CONFIG structure listing configurations.
//            Each WMDM_PROP_CONFIG has a WMDM_PROP_DESC describing a specific format configuration.
//                Each WMDM_PROP_DESC holds specific values as a range, a set, or a flag meaning all values are accepted.
HRESULT myGetFormatCaps(WMDM_FORMATCODE formatCode, IWMDMDevice3* pDevice)
{
    HRESULT hr = S_OK;

    // Get a list of supported configurations for the format.
    WMDM_FORMAT_CAPABILITY formatCapList;
    hr = pDevice->GetFormatCapability(formatCode, &formatCapList);
    HANDLE_HR(hr, "Got a WMDM_FORMATCODE structure in GetCaps","Couldn't get a WMDM_FORMATCODE structure in GetCaps");

    // Print out the format name.
    // TODO: Display a banner for device formats.
    PrintWMDM_FORMATCODE(formatCode); // Custom function to print out the format code.
    

    // Loop through the configurations and examine each one.
    for(UINT iConfig = 0; iConfig < formatCapList.nPropConfig; iConfig++)
    {
        WMDM_PROP_CONFIG formatConfig = formatCapList.pConfigs[iConfig];

        // Preference level for this configuration (lower number means more preferred).
        // TODO: Display a banner for the preference-level output.

        // Loop through all properties for this configuration and get supported
        // values for the property. Values can be a single value, a range, 
        // or a list of enumerated values.
        for(UINT iDesc = 0; iDesc < formatConfig.nPropDesc; iDesc++)
        {
            WMDM_PROP_DESC propDesc = formatConfig.pPropDesc[iDesc];
            // TODO: Display the property name.

            // Three ways a value can be represented: any, a range, or a list.
            switch (propDesc.ValidValuesForm)
            {
                case WMDM_ENUM_PROP_VALID_VALUES_ANY:
                    // TODO: Display a message indicating that all values are valid.
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_RANGE:
                    {
                        // List these in the docs as the propvariants set.
                        WMDM_PROP_VALUES_RANGE rng = propDesc.ValidValues.ValidValuesRange;
                        // TODO: Display a banner for the values to follow
                        // TODO: Display the max value.
                        // TODO: Display the min value.
                        // TODO: Display the step value.
                    }
                    break;
                case WMDM_ENUM_PROP_VALID_VALUES_ENUM:
                    {
                        // TODO: Display a banner for the values to follow.
                        WMDM_PROP_VALUES_ENUM list = propDesc.ValidValues.EnumeratedValidValues;
                        PROPVARIANT pVal;
                        for(UINT iValue = 0; iValue < list.cEnumValues; iValue++)
                        {
                            pVal = list.pValues[iValue];
                            // TODO: Display the current value.
                            PropVariantClear(&pVal);
                            PropVariantInit(&pVal);
                        }
                    }

                    break;
                default:
                    HANDLE_HR(E_FAIL, "Undefined configuration type in GetCaps" << endl, "");
                    break;
            }
        }
    }
    // Now clear the memory used by WMDM_FORMAT_CAPABILITY.
    FreeFormatCapability(formatCapList);

e_Exit:
    return hr;
}

DeviceIoControl メソッドは、デバイス I/O 制御 (IOCTL) コードをデバイスに送信します。これはパススルー方式のメソッドで、Windows Media Device Manager はパラメーターを検証したうえで、呼び出しをサービスプロバイダーにそのまま転送します。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準的な COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

このメソッドは、アプリケーションとサービスプロバイダーの間のプライベートな通信手段を提供します。サービスプロバイダーはこの IOCTL を処理し、必要に応じて変更したうえで、カーネルモードドライバーに渡すことができます。

IWMDMDevice::SendOpaqueCommand と比べて、このメソッドは出力バッファーを呼び出し元が提供するため、Windows API の DeviceIoControl により近い形になっています。また IWMDMDevice::SendOpaqueCommand とは異なり、このメソッドは MAC チェックを伴わないため、より効率的です。

このメソッドは、たとえば MTP デバイスにカスタムの Media Transport Protocol (MTP) コマンドを送信するために使用できます。

FindStorage メソッドは、永続的な一意識別子によってストレージを検索します。他のメソッドとは異なり、このメソッドはルートストレージから再帰的に検索できます。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準的な COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

永続的な一意識別子は、特定のデバイスに保存されているコンテンツを一意に識別するために使用されます。これは、すべてのデバイスで同一となるコンテンツ固有のグローバル一意識別子を表すものではありません。したがって、同じコンテンツでも異なるストレージに保存されていれば、永続的な一意識別子は異なります。同様に、異なるコンテンツであっても、異なるデバイスに保存されていれば同じ永続的な一意識別子を持つことがあります。デバイス上のコンテンツをデータベースの行に例えると、このプロパティはデータベースの ID 列と同じ役割を果たします。

永続的な一意識別子はデバイスによって生成されるため、その形式はデバイスに依存します。アプリケーションは、ストレージの g_wszWMDMPersistentUniqueID プロパティを照会して永続的な一意識別子を取得してください。このプロパティを照会するには、GetSpecifiedMetadata メソッドまたは GetMetadata メソッドを使用できます。