Fungsi SetupDiOpenDeviceInterfaceA (setupapi.h)
Fungsi SetupDiOpenDeviceInterface mengambil informasi tentang antarmuka perangkat dan menambahkan antarmuka ke informasi perangkat yang ditentukan yang ditetapkan untuk sistem lokal atau sistem jarak jauh.
Sintaks
WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
[in] HDEVINFO DeviceInfoSet,
[in] PCSTR DevicePath,
[in] DWORD OpenFlags,
[out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);
Parameter
[in] DeviceInfoSet
Penunjuk ke kumpulan informasi perangkat yang berisi, atau akan berisi, elemen informasi perangkat yang mewakili perangkat yang mendukung antarmuka untuk dibuka.
[in] DevicePath
Penunjuk ke string yang dihentikan NULL yang memasok nama antarmuka perangkat yang akan dibuka. Nama ini adalah jalur perangkat Win32 yang biasanya diterima dalam struktur pemberitahuan PnP atau diperoleh oleh panggilan sebelumnya ke SetupDiEnumDeviceInterfaces dan fungsi terkait.
[in] OpenFlags
Bendera yang menentukan bagaimana elemen antarmuka perangkat akan dibuka. Satu-satunya bendera yang valid adalah sebagai berikut:
DIODI_NO_ADD
Menentukan bahwa elemen informasi perangkat untuk perangkat dasar tidak akan dibuat jika elemen tersebut belum ada dalam kumpulan informasi perangkat yang ditentukan. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[out, optional] DeviceInterfaceData
Penunjuk ke struktur SP_DEVICE_INTERFACE_DATA yang diinisialisasi penelepon yang menerima data antarmuka yang diminta. Penunjuk ini bersifat opsional dan dapat berupa NULL. Jika buffer disediakan, pemanggil harus mengatur anggota cbSize struktur ke sizeof(SP_DEVICE_INTERFACE_DATA) sebelum memanggil SetupDiOpenDeviceInterface. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
Nilai kembali
SetupDiOpenDeviceInterface mengembalikan TRUE jika fungsi selesai tanpa kesalahan. Jika fungsi selesai dengan kesalahan, fungsi mengembalikan FALSE dan kode kesalahan untuk kegagalan dapat diambil dengan memanggil GetLastError.
Keterangan
Jika elemen antarmuka perangkat untuk antarmuka sudah ada di DeviceInfoSet, SetupDiOpenDeviceInterface memperbarui bendera. Oleh karena itu, fungsi ini dapat digunakan untuk memperbarui bendera untuk antarmuka perangkat. Misalnya, antarmuka mungkin tidak aktif ketika pertama kali dibuka, tetapi kemudian menjadi aktif. Jika elemen informasi perangkat untuk perangkat yang mendasar belum ada di DeviceInfoSet, fungsi ini membuatnya dan menambahkannya ke DeviceInfoSet.
Jika fungsi berhasil membuka antarmuka perangkat baru tetapi pemanggil tidak menyediakan struktur yang valid dalam parameter DeviceInterfaceData , fungsi akan mengembalikan FALSE dan panggilan berikutnya ke GetLastError akan mengembalikan ERROR_INVALID_USER_BUFFER. Namun, dalam situasi ini, SetupDiOpenDeviceInterface memang menambahkan antarmuka yang diminta ke set informasi perangkat.
Jika antarmuka perangkat baru berhasil dibuka, tetapi buffer DeviceInterfaceData yang disediakan penelepon tidak valid, fungsi ini mengembalikan FALSE dan GetLastError mengembalikan ERROR_INVALID_USER_BUFFER. Kesalahan buffer pemanggil tidak mencegah antarmuka dibuka.
Jika bendera DIODI_NO_ADD ditentukan untuk parameter OpenFlags , dan elemen informasi perangkat untuk perangkat yang mendasar belum ada dalam kumpulan informasi perangkat yang ditentukan, fungsi ini mengembalikan FALSE dan GetLastError mengembalikan ERROR_NO_SUCH_DEVICE_INTERFACE.
Ketika aplikasi telah selesai menggunakan informasi yang diambil SetupDiOpenDeviceInterface, aplikasi harus memanggil SetupDiDeleteDeviceInterfaceData.
MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK atribut dapat diteruskan sebagai nilai argumen DevicePath dari fungsi SetupDiOpenDeviceInterface .
Catatan
Header setupapi.h mendefinisikan SetupDiOpenDeviceInterface sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
Persyaratan | Nilai |
---|---|
Klien minimum yang didukung | Tersedia di Microsoft Windows 2000 dan versi Windows yang lebih baru. |
Target Platform | Desktop |
Header | setupapi.h (termasuk Setupapi.h) |
Pustaka | Setupapi.lib |