IPortableDevice::Metode buka (portabledeviceapi.h)

Artikel
03/04/2024

Metode Buka membuka koneksi antara aplikasi dan perangkat.

Sintaks

HRESULT Open(
  [in] LPCWSTR               pszPnPDeviceID,
  [in] IPortableDeviceValues *pClientInfo
);

Parameter

[in] pszPnPDeviceID

Penunjuk ke string yang dihentikan null yang berisi string ID Plug and Play untuk perangkat. Anda bisa mendapatkan string ini dengan memanggil IPortableDeviceManager::GetDevices.

[in] pClientInfo

Penunjuk ke antarmuka IPortableDeviceValues yang menyimpan informasi yang mengidentifikasi aplikasi ke perangkat. Antarmuka ini menyimpan pasangan PROPERTYKEY/nilai yang mencoba mengidentifikasi aplikasi secara unik. Meskipun kehadiran antarmuka CoCreated diperlukan, aplikasi tidak diperlukan untuk mengirim pasangan kunci/nilai apa pun. Namun, mengirim data dapat meningkatkan performa. Pasangan kunci/nilai umum mencakup nama aplikasi, versi utama dan minor, dan nomor build.

Lihat properti yang dimulai dengan "WPD_CLIENT_" di bagian Properti .

Nilai kembali

Metode mengembalikan HRESULT. Nilai yang mungkin termasuk, tetapi tidak terbatas pada, yang ada dalam tabel berikut.

Menampilkan kode	Deskripsi
S_OK	Metode berhasil.
E_WPD_DEVICE_ALREADY_OPENED	Koneksi perangkat telah dibuka.
E_POINTER	Setidaknya salah satu argumen adalah penunjuk NULL.

Keterangan

Perangkat harus dibuka sebelum Anda dapat memanggil metode apa pun di dalamnya. (Perhatikan bahwa metode IPortableDeviceManager tidak mengharuskan Anda membuka perangkat sebelum memanggil metode apa pun.) Namun, biasanya Anda tidak perlu memanggil Tutup.

Administrator dapat membatasi akses perangkat portabel ke komputer yang berjalan pada jaringan. Misalnya, administrator dapat membatasi semua pengguna Tamu untuk akses baca-saja, sementara pengguna terautentikasi diberikan akses baca/tulis.

Karena masalah keamanan ini, jika aplikasi Anda tidak akan melakukan operasi tulis, aplikasi harus memanggil metode Buka dan meminta akses baca-saja dengan menentukan GENERIC_READ untuk properti WPD_CLIENT_DESIRED_ACCESS yang disediakannya dalam parameter pClientInfo .

Jika aplikasi Anda memerlukan operasi tulis, aplikasi harus memanggil metode Buka seperti yang ditunjukkan dalam contoh kode berikut. Pertama kali, ini harus meminta akses baca/tulis dengan meneruskan properti WPD_CLIENT_DESIRED_ACCESS default di parameter pClientInfo . Jika panggilan pertama ini gagal dan mengembalikan E_ACCESSDENIED, aplikasi Anda harus memanggil metode Buka untuk kedua kalinya dan meminta akses baca-saja dengan menentukan GENERIC_READ untuk properti WPD_CLIENT_DESIRED_ACCESS yang disediakannya dalam parameter pClientInfo .

Aplikasi yang tinggal di Single Threaded Apartments harus menggunakan CLSID_PortableDeviceFTM, karena ini menghilangkan overhead marshaling pointer antarmuka. CLSID_PortableDevice masih didukung untuk aplikasi warisan.

Contoh


#define CLIENT_NAME         L"My WPD Application"
#define CLIENT_MAJOR_VER    1
#define CLIENT_MINOR_VER    0
#define CLIENT_REVISION     0

HRESULT OpenDevice(LPCWSTR wszPnPDeviceID, IPortableDevice** ppDevice)
{
    HRESULT                hr                 = S_OK;
    IPortableDeviceValues* pClientInformation = NULL;
    IPortableDevice*       pDevice            = NULL;

    if ((wszPnPDeviceID == NULL) || (ppDevice == NULL))
    {
        hr = E_INVALIDARG;
        return hr;
    }

    // CoCreate an IPortableDeviceValues interface to hold the client information.
    hr = CoCreateInstance(CLSID_PortableDeviceValues,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_IPortableDeviceValues,
                          (VOID**) &pClientInformation);
    if (SUCCEEDED(hr))
    {
        HRESULT ClientInfoHR = S_OK;

        // Attempt to set all properties for client information. If we fail to set
        // any of the properties below it is OK. Failing to set a property in the
        // client information isn't a fatal error.
        ClientInfoHR = pClientInformation->SetStringValue(WPD_CLIENT_NAME, CLIENT_NAME);
        if (FAILED(ClientInfoHR))
        {
           // Failed to set WPD_CLIENT_NAME
        }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_MAJOR_VERSION, CLIENT_MAJOR_VER);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_MAJOR_VERSION
        }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_MINOR_VERSION, CLIENT_MINOR_VER);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_MINOR_VERSION
        }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_REVISION, CLIENT_REVISION);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_REVISION
        }
    }
    else
    {
        // Failed to CoCreateInstance CLSID_PortableDeviceValues for client information
    }

        ClientInfoHR = pClientInformation->SetUnsignedIntegerValue(WPD_CLIENT_SECURITY_QUALITY_OF_SERVICE, SECURITY_IMPERSONATION);
        if (FAILED(ClientInfoHR))
        {
            // Failed to set WPD_CLIENT_SECURITY_QUALITY_OF_SERVICE
        }

    if (SUCCEEDED(hr))
    {
        // CoCreate an IPortableDevice interface
        hr = CoCreateInstance(CLSID_PortableDeviceFTM,
                              NULL,
                              CLSCTX_INPROC_SERVER,
                              IID_IPortableDevice,
                              (VOID**) &pDevice);

        if (SUCCEEDED(hr))
        {
            // Attempt to open the device using the PnPDeviceID string given
            // to this function and the newly created client information.
            // Note that we're attempting to open the device the first 
            // time using the default (read/write) access. If this fails
            // with E_ACCESSDENIED, we'll attempt to open a second time
            // with read-only access.
            hr = pDevice->Open(wszPnPDeviceID, pClientInformation);
            if (hr == E_ACCESSDENIED)
            {
                 // Attempt to open for read-only access
                 pClientInformation->SetUnsignedIntegerValue(
                       WPD_CLIENT_DESIRED_ACCESS,
                       GENERIC_READ);
                 hr = pDevice->Open(wszPnPDeviceID, pClientInformation);
            }
            if (SUCCEEDED(hr))
            {
                // The device successfully opened, obtain an instance of the Device into
                // ppDevice so the caller can be returned an opened IPortableDevice.
                hr = pDevice->QueryInterface(IID_IPortableDevice, (VOID**)ppDevice);
                if (FAILED(hr))
                {
                    // Failed to QueryInterface the opened IPortableDevice
                }
            }
        }
        else
        {
            // Failed to CoCreateInstance CLSID_PortableDevice
        }
    }

    // Release the IPortableDevice when finished
    if (pDevice != NULL)
    {
        pDevice->Release();
        pDevice = NULL;
    }

    // Release the IPortableDeviceValues that contains the client information when finished
    if (pClientInformation != NULL)
    {
        pClientInformation->Release();
        pClientInformation = NULL;
    }

    return hr;
}

Persyaratan

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

Lihat juga

Membuat Koneksi

Antarmuka IPortableDevice

IPortableDevice::Close

Share via