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

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

構文

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

パラメーター

[in] dwFlags

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

[in] pParameters

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

[out] ppResults

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

戻り値

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

注釈

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

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

• WPD_COMMAND_COMMON_RESET_DEVICE
• WPD_COMMAND_DEVICE_HINTS_GET_CONTENT_LOCATION
• WPD_COMMAND_SMS_SEND
• WPD_COMMAND_STILL_IMAGE_CAPTURE_INITIATE
• WPD_COMMAND_STORAGE_EJECT

一部のカスタム コマンドでは、特定の入出力制御コード (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;
}

//

要件

こちらもご覧ください

IPortableDevice インターフェイス