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 値には、次の表に示す値が含まれますが、これらに限定されません。
| リターン コード | 説明 |
|---|---|
|
コマンドはドライバーによって正常に受信されました。 これは、コマンド自体が成功したことを示すものではありません。コマンドの成功または失敗を判断するには、ppResults をチェックする必要があります。 |
|
引数の少なくとも 1 つが NULL ポインターでした。 |
注釈
この関数は、ドライバーにコマンドを直接送信するために使用されます。 コマンドは、必要なパラメーターの一覧と共に、予想されるアクションを示すためにドライバーに送信される 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;
}
//
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | Windows |
| ヘッダー | portabledeviceapi.h |
| Library | PortableDeviceGUIDs.lib |