IPortableDevice::Metode SendCommand (portabledeviceapi.h)

Metode SendCommand mengirim perintah ke perangkat dan mengambil hasilnya secara sinkron.

Sintaks

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

Parameter

[in] dwFlags

Saat ini tidak digunakan; tentukan nol.

[in] pParameters

Penunjuk ke antarmuka IPortableDeviceValues yang menentukan perintah dan parameter untuk dipanggil pada perangkat. Antarmuka ini harus menyertakan dua nilai berikut untuk menunjukkan perintah . Parameter tambahan bervariasi tergantung pada perintah . Untuk daftar parameter yang diperlukan untuk setiap perintah, lihat Perintah.

Perintah atau properti	Deskripsi
WPD_PROPERTY_COMMON_COMMAND_CATEGORY	GUID kategori perintah yang akan dikirim. Misalnya, untuk mengatur ulang perangkat, Anda akan mengirim WPD_COMMAND_COMMON_RESET_DEVICE.fmtid.
WPD_PROPERTY_COMMON_COMMAND_ID	PID perintah yang akan dikirim. Misalnya, untuk mengatur ulang perangkat, Anda akan mengirim WPD_COMMAND_COMMON_RESET_DEVICE.pid.

[out] ppResults

Alamat variabel yang menerima penunjuk ke antarmuka IPortableDeviceValues yang menunjukkan hasil perintah, termasuk keberhasilan atau kegagalan, dan nilai perintah apa pun yang dikembalikan oleh perangkat. Pemanggil harus merilis antarmuka ini ketika selesai. Nilai yang diambil bervariasi menurut perintah; lihat dokumentasi perintah yang sesuai di Perintah untuk mempelajari nilai apa yang dikembalikan oleh setiap panggilan perintah.

Nilai kembali

Nilai yang dikembalikan menunjukkan keberhasilan atau kegagalan untuk mengirim perintah dan mengembalikan hasil dari driver; itu tidak menunjukkan apakah driver mendukung perintah atau jika mengalami beberapa kesalahan dalam memproses perintah. (Untuk informasi selengkapnya, lihat Keterangan.) Kesalahan ini dikembalikan dalam nilai HRESULT dari parameter ppResults . Kemungkinan nilai HRESULT yang dikembalikan oleh metode ini termasuk, tetapi tidak terbatas pada, yang ada dalam tabel berikut.

Menampilkan kode	Deskripsi
S_OK	Perintah berhasil diterima oleh driver. Ini tidak menunjukkan bahwa perintah itu sendiri berhasil—Anda harus memeriksa ppResults untuk menentukan keberhasilan atau kegagalan perintah.
E_POINTER	Setidaknya salah satu argumen adalah penunjuk NULL.

Keterangan

Fungsi ini digunakan untuk mengirim perintah langsung ke driver. Perintah adalah PROPERTYKEY yang dikirim ke driver untuk menunjukkan tindakan yang diharapkan, bersama dengan daftar parameter yang diperlukan. Setiap perintah memiliki daftar parameter dan hasil yang diperlukan dan opsional yang harus dipaketkan dengan perintah agar driver dapat melakukan tindakan yang diminta. Daftar perintah yang ditentukan oleh Perangkat Portabel Windows, dengan parameter dan nilai pengembalian yang diperlukan, diberikan dalam Perintah.

Sebagian besar metode Perangkat Portabel Windows benar-benar berfungsi dengan mengirim satu atau beberapa perintah Perangkat Portabel Windows untuk Anda dan membungkus parameter untuk Anda. Beberapa perintah tidak memiliki metode Perangkat Portabel Windows yang sesuai. Satu-satunya cara untuk memanggil perintah ini adalah dengan menggunakan SendCommand. Perintah berikut tidak memiliki metode yang sesuai:

• 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

Anda juga harus memanggil SendCommand untuk mengirim driver perintah driver kustom apa pun.

Beberapa perintah kustom mungkin memerlukan tingkat akses Input/Output Control Code (IOCTL) tertentu. Aplikasi Anda menetapkan tingkat akses ini dengan memanggil metode IPortableDeviceValues::SetUnsignedIntegerValue pada parameter perintah yang diteruskannya ke metode SendCommand . Misalnya, jika perintah kustom memerlukan akses baca-saja, Anda akan memanggil SetUnsignedIntegerValue dan meneruskan WPD_API_OPTION_IOCTL_ACCESS sebagai argumen pertama dan FILE_READ_ACCESS sebagai argumen kedua. Dengan memperbarui parameter perintah ini, aplikasi Anda memastikan bahwa WINDOWS Portable Devices API mengeluarkan perintah dengan IOCTL baca-saja.

Kesalahan yang ditemui oleh driver saat memproses perintah diambil oleh parameter ppResults , bukan oleh nilai pengembalian SendCommand . Nilai yang dikembalikan dari metode ini adalah kode kesalahan (atau keberhasilan) yang ditemui saat mengirim perintah ke driver.

Jika driver tidak mendukung perintah yang ditentukan, metode ini akan berhasil, tetapi satu-satunya elemen yang dijamin dalam parameter ppResults yang dikembalikan akan WPD_PROPERTY_COMMON_HRESULT, yang akan berisi E_NOTIMPL. Anda dapat memverifikasi apakah driver mendukung perintah dengan memanggil IPortableDeviceCapabilities::GetSupportedCommands sebelum memanggil perintah.

Jika perintah mendukung opsi (seperti menghapus secara rekursif atau menghapus secara nonrekursif), Anda dapat meminta opsi yang didukung dengan memanggil IPortableDeviceCapabilities::GetCommandOptions.

Tidak ada opsi untuk mengatur batas waktu dalam panggilan ke SendCommand tetapi pengembang dapat mencoba membatalkan perintah dengan memanggil IPortableDevice::Cancel dari utas terpisah.

Contoh

// 

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;
}

//

Persyaratan

Persyaratan	Nilai
Target Platform	Windows
Header	portabledeviceapi.h
Pustaka	PortableDeviceGUIDs.lib

Lihat juga

Antarmuka IPortableDevice