IPortableDevice::SendCommand メソッド (portabledeviceapi.h)

  • [アーティクル]

SendCommand メソッドは、デバイスにコマンドを送信し、同期的に結果を取得します。

構文

HRESULT SendCommand(
  [in]  const DWORD           dwFlags,
  [in]  IPortableDeviceValues *pParameters,
  [out] IPortableDeviceValues **ppResults
);

パラメーター

[in] dwFlags

現在は使用されていません。0 を指定します。

[in] pParameters

デバイスで呼び出すコマンドとパラメーターを指定する IPortableDeviceValues インターフェイスへのポインター。 このインターフェイスには、コマンドを示すために次の 2 つの値を含める必要があります。 追加のパラメーターは、コマンドによって異なります。 各コマンドに必要なパラメーターの一覧については、「 コマンド」を参照してください。

コマンドまたはプロパティ 説明
WPD_PROPERTY_COMMON_COMMAND_CATEGORY 送信するコマンドのカテゴリ GUID 。 たとえば、デバイスをリセットするには、 WPD_COMMAND_COMMON_RESET_DEVICE.fmtid を送信します。
WPD_PROPERTY_COMMON_COMMAND_ID 送信するコマンドの PID。 たとえば、デバイスをリセットするには、 WPD_COMMAND_COMMON_RESET_DEVICE.pid を送信します。

[out] ppResults

成功または失敗を含むコマンド結果の結果と、デバイスによって返されるコマンド値を示す IPortableDeviceValues インターフェイスへのポインターを受け取る変数のアドレス。 呼び出し元は、このインターフェイスの使用が完了したら、このインターフェイスを解放する必要があります。 取得された値はコマンドによって異なります。各コマンド呼び出しによって返される値については、「 コマンド 」の適切なコマンド ドキュメントを参照してください。

戻り値

戻り値は、コマンドを送信し、ドライバーから結果を返す成功または失敗を示します。ドライバーがコマンドをサポートしているかどうか、またはコマンドの処理中に何らかのエラーが発生したかどうかは示されません。 (詳細については、「解説」を参照してください)。これらのエラーは、ppResults パラメーターの HRESULT 値で返されます。 このメソッドによって返される HRESULT 値には、次の表に示す値が含まれますが、これらに限定されません。

リターン コード 説明
S_OK
 コマンドはドライバーによって正常に受信されました。 これは、コマンド自体が成功したことを示すものではありません。コマンドの成功または失敗を判断するには、ppResults をチェックする必要があります。
E_POINTER
 引数の少なくとも 1 つが NULL ポインターでした。

注釈

この関数は、ドライバーにコマンドを直接送信するために使用されます。 コマンドは、必要なパラメーターの一覧と共に、予想されるアクションを示すためにドライバーに送信される PROPERTYKEY です。 各コマンドには、必須パラメーターと省略可能なパラメーターと結果の一覧が含まれています。ドライバーが要求されたアクションを実行するには、 コマンドを使用してパッケージ化する必要があります。 必要なパラメーターと戻り値を持つ Windows ポータブル デバイスによって定義されたコマンドの一覧は、コマンドで指定 します。

ほとんどの Windows ポータブル デバイス メソッドは、実際には、1 つ以上の Windows ポータブル デバイス コマンドを送信し、パラメーターをラップすることで機能します。 一部のコマンドには、対応する Windows ポータブル デバイス メソッドがありません。 これらのコマンドを呼び出す唯一の方法は、 SendCommand を使用することです。 次のコマンドには、対応するメソッドはありません。

また、 SendCommand を呼び出して、カスタム ドライバー コマンド ドライバーを送信する必要があります。

一部のカスタム コマンドでは、特定の入出力制御コード (IOCTL) アクセス レベルが必要になる場合があります。 アプリケーションは、SendCommand メソッドに渡すコマンド パラメーターに対して IPortableDeviceValues::SetUnsignedIntegerValue メソッドを呼び出すことによって、このアクセス レベルを設定します。 たとえば、カスタム コマンドで読み取り専用アクセスが必要な場合は、 SetUnsignedIntegerValue を呼び出し、WPD_API_OPTION_IOCTL_ACCESSを最初の引数として渡し、FILE_READ_ACCESSを 2 番目の引数として渡します。 これらのコマンド パラメーターを更新することで、アプリケーションは Windows ポータブル デバイス API が読み取り専用 IOCTL でコマンドを発行することを保証します。

コマンドの処理中にドライバーによって発生したエラーは、SendCommand 戻り値ではなく ppResults パラメーターによって取得されます。 このメソッドの戻り値は、ドライバーへのコマンドの送信中に発生したエラー (または成功) コードです。

ドライバーが指定したコマンドをサポートしていない場合、このメソッドは成功しますが、返される ppResults パラメーター内の保証される要素はWPD_PROPERTY_COMMON_HRESULTのみです。これには、E_NOTIMPLが含まれます。 ドライバーがコマンドをサポートしているかどうかを確認するには、コマンドを呼び出す前 に IPortableDeviceCapabilities::GetSupportedCommands を呼び出します。

コマンドでオプションがサポートされている場合 (再帰的に削除する、非回復的に削除するなど)、 IPortableDeviceCapabilities::GetCommandOptions を呼び出して、サポートされているオプションのクエリを実行できます。

SendCommand の呼び出しでタイムアウトを設定するオプションはありませんが、開発者は、別のスレッドから IPortableDevice::Cancel を呼び出すことでコマンドを取り消すことができます。

例


// 

void ResetDevice(IPortableDevice* pDevice)
{
    HRESULT  hr = S_OK;
    CComPtr<IPortableDeviceValues>  pDevValues;

    hr = CoCreateInstance(CLSID_PortableDeviceValues,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IPortableDeviceValues,
        (VOID**) &pDevValues);
    if (SUCCEEDED(hr))
    {
        if (pDevValues != NULL)
        {
            hr = pDevValues->SetGuidValue(WPD_PROPERTY_COMMON_COMMAND_CATEGORY, 
                WPD_COMMAND_COMMON_RESET_DEVICE.fmtid);
            if (FAILED(hr))
            {
                printf("! IPortableDeviceValues::SetGuidValue failed, hr= 0x%lx\n", hr);
            }
            hr = pDevValues->SetUnsignedIntegerValue(WPD_PROPERTY_COMMON_COMMAND_ID,
                WPD_COMMAND_COMMON_RESET_DEVICE.pid);
            if (FAILED(hr))
            {
                printf("! IPortableDeviceValues::SetGuidValue failed, hr= 0x%lx\n", hr);
            }
        }
    }
    hr = pDevice->SendCommand(0, pDevValues, &pDevValues);
    if (FAILED(hr))
    {
        printf("! Failed to reset the device, hr = 0x%lx\n",hr);
    }
    else
        printf("Device successfully reset\n");
    return;
}

//

要件

要件 値
対象プラットフォーム Windows
ヘッダー portabledeviceapi.h
Library PortableDeviceGUIDs.lib

こちらもご覧ください

IPortableDevice インターフェイス