Bagikan melalui

Fungsi SetupDiOpenDeviceInterfaceA (setupapi.h)

  • Artikel

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

Lihat juga

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces