Fungsi SetupDiRegisterDeviceInfo (setupapi.h)

Artikel
03/15/2023

Fungsi SetupDiRegisterDeviceInfo adalah handler default untuk permintaan DIF_REGISTERDEVICE .

Sintaks

WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
  [in]            HDEVINFO           DeviceInfoSet,
  [in, out]       PSP_DEVINFO_DATA   DeviceInfoData,
  [in]            DWORD              Flags,
  [in, optional]  PSP_DETSIG_CMPPROC CompareProc,
  [in, optional]  PVOID              CompareContext,
  [out, optional] PSP_DEVINFO_DATA   DupDeviceInfoData
);

Parameter

[in] DeviceInfoSet

Handel ke kumpulan informasi perangkat yang berisi elemen informasi perangkat yang mewakili perangkat untuk mendaftar. Kumpulan informasi perangkat tidak boleh berisi elemen jarak jauh apa pun.

[in, out] DeviceInfoData

Penunjuk ke struktur SP_DEVINFO_DATA yang menentukan elemen informasi perangkat di DeviceInfoSet. Ini adalah parameter IN-OUT karena DeviceInfoData.DevInst mungkin diperbarui dengan nilai handel baru saat dikembalikan.

[in] Flags

Nilai bendera yang mengontrol bagaimana perangkat terdaftar, yang bisa menjadi nol atau nilai berikut:

SPRDI_FIND_DUPS

Cari instans perangkat yang sudah ada sebelumnya yang sesuai dengan perangkat yang diwakili oleh DeviceInfoData. Jika bendera ini tidak ditentukan, instans perangkat didaftarkan terlepas dari apakah instans perangkat sudah ada untuknya.

Jika penelepon memasok CompareProc, pemanggil juga harus mengatur bendera ini.

[in, optional] CompareProc

Penunjuk ke fungsi panggilan balik perbandingan untuk digunakan dalam deteksi duplikat. Parameter ini bersifat opsional dan dapat berupa NULL. Jika parameter ini ditentukan, fungsi panggilan balik dipanggil untuk setiap instans perangkat yang berada di kelas yang sama dengan instans perangkat yang sedang didaftarkan. Prototipe fungsi panggilan balik adalah sebagai berikut:

typedef  DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
    IN HDEVINFO  DeviceInfoSet,
    IN PSP_DEVINFO_DATA  NewDeviceData,
    IN PSP_DEVINFO_DATA  ExistingDeviceData,
    IN PVOID  CompareContextOPTIONAL
    );

Fungsi perbandingan harus mengembalikan ERROR_DUPLICATE_FOUND jika menemukan bahwa kedua perangkat tersebut adalah duplikat. Jika tidak, itu harus mengembalikan NO_ERROR. Jika beberapa kesalahan lain ditemukan, fungsi panggilan balik harus mengembalikan kode ERROR_* yang sesuai untuk menunjukkan kegagalan.

Jika CompareProc tidak ditentukan dan deteksi duplikasi diminta, perilaku perbandingan default akan digunakan. Defaultnya adalah membandingkan tanda tangan deteksi perangkat baru dengan tanda tangan deteksi semua perangkat lain di kelas . Tanda tangan deteksi terkandung dalam pendeskripsi sumber daya khusus kelas dari konfigurasi log boot perangkat.

[in, optional] CompareContext

Penunjuk ke buffer konteks yang disediakan penelepon yang diteruskan ke fungsi panggilan balik. Parameter ini diabaikan jika CompareProc tidak ditentukan.

[out, optional] DupDeviceInfoData

Penunjuk ke struktur SP_DEVINFO_DATA untuk menerima informasi tentang instans perangkat duplikat, jika ada, ditemukan sebagai akibat dari mencoba mendaftarkan perangkat ini. Parameter ini bersifat opsional dan dapat berupa NULL. Jika parameter ini ditentukan, pemanggil harus mengatur DupDeviceInfoData.cbSize ke sizeof(SP_DEVINFO_DATA). Ini akan diisi jika fungsi mengembalikan FALSE, dan GetLastError mengembalikan ERROR_DUPLICATE_FOUND. Elemen informasi perangkat ini ditambahkan sebagai anggota DeviceInfoSet yang ditentukan, jika belum menjadi anggota. Jika DupDeviceInfoData tidak ditentukan, duplikat tidak ditambahkan ke kumpulan informasi perangkat.

Jika Anda memanggil fungsi ini saat menangani permintaan DIF_REGISTERDEVICE , parameter DupDeviceInfoData harus NULL.

Nilai kembali

Fungsi mengembalikan TRUE jika berhasil. Jika tidak, ia mengembalikan FALSE dan kesalahan yang dicatat dapat diambil dengan panggilan ke GetLastError.

Keterangan

SetupDiRegisterDeviceInfo terutama dirancang untuk mendaftarkan perangkat non-PnP dengan manajer Plug and Play (PnP) di komputer lokal. Meskipun SetupDiRegisterDeviceInfo tidak akan gagal jika kumpulan informasi perangkat adalah untuk komputer jarak jauh, hasilnya adalah penggunaan terbatas karena kumpulan informasi perangkat kemudian tidak dapat digunakan dengan permintaan penginstalan DIF_Xxx atau fungsi SetupDiXxx yang tidak mendukung operasi pada komputer jarak jauh. Misalnya, memanggil SetupDiCreateDevRegKey untuk menjalankan bagian INF untuk perangkat yang baru terdaftar di komputer jarak jauh akan gagal.

Catatan Hanya penginstal kelas yang harus memanggil SetupDiRegisterDeviceInfo dan hanya dalam situasi di mana penginstal kelas harus melakukan operasi pendaftaran perangkat setelah SetupDiRegisterDeviceInfo menyelesaikan operasi pendaftaran perangkat default. Dalam situasi seperti itu, penginstal kelas harus langsung memanggil SetupDiRegisterDeviceInfo saat alat penginstal memproses permintaan DIF_REGISTERDEVICE. Untuk informasi selengkapnya tentang memanggil handler default, lihat Memanggil Penangan Kode DIF Default.

Setelah mendaftarkan elemen informasi perangkat, pemanggil harus memperbarui salinan tersimpan dari handel DevInst yang terkait dengan perangkat ini. Ini diperlukan karena nilai handel mungkin telah berubah selama pendaftaran. Pemanggil tidak perlu mengambil struktur SP_DEVINFO_DATA lagi karena bidang DevInst struktur diperbarui untuk mencerminkan nilai handel saat ini.

Jangan langsung memanggil fungsi ini untuk instans perangkat PnP. Instans perangkat PnP secara otomatis didaftarkan oleh sistem operasi. Namun, Anda harus mendaftarkan instans perangkat non-PnP dengan salah satu cara berikut:

Jika aplikasi penginstalan Anda menggunakan permintaan DIF_DETECT untuk berhasil mendeteksi perangkat, aplikasi tersebut juga harus menggunakan permintaan DIF_REGISTERDEVICE untuk mendaftarkan instans perangkat. Permintaan harus ditangani dengan cara default. (Secara default, SetupDiCallClassInstaller pertama-tama memanggil penginstal kelas dan rekan penginstal kelas untuk melakukan deteksi duplikat dan mendaftarkan instans perangkat. Jika penginstal ini tidak mendaftarkan instans perangkat, SetupDiCallClassInstaller memanggil SetupDiRegisterDeviceInfo untuk melakukan deteksi duplikat dan mendaftarkan instans perangkat.)
Jika aplikasi penginstalan Anda membuat instans perangkat (misalnya, dengan memanggil SetupDiCreateDeviceInfo) tetapi tidak melakukan deteksi duplikat, aplikasi penginstalan Anda harus menggunakan permintaan DIF_REGISTERDEVICE untuk mendaftarkan instans perangkat. Permintaan harus ditangani secara default seperti yang dijelaskan sebelumnya.
Jika aplikasi penginstalan Anda membuat perangkat baru dan melakukan deteksi duplikat, aplikasi penginstalan Anda harus menggunakan permintaan DIF_REGISTERDEVICE tetapi harus mencegah SetupDiCallClassInstaller memanggil SetupDiRegisterDeviceInfo. Untuk mencegah SetupDiCallClassInstaller memanggil SetupDiRegisterDeviceInfo, atur bendera DI_NODI_DEFAULTACTION di anggota Bendera struktur SP_DEVINSTALL_PARAMS untuk instans perangkat.
Jika SetupDiCallClassInstaller mengembalikan TRUE untuk permintaan DIF_REGISTERDEVICE, penginstal kelas atau rekan penginstal kelas mendaftarkan instans perangkat. Dalam hal ini, aplikasi penginstalan dapat terus menginstal perangkat.

Jika SetupDiCallClassInstaller mengembalikan FALSE untuk permintaan DIF_REGISTERDEVICE, penginstal kelas atau penginstal bersama kelas tidak mendaftarkan instans perangkat. Dalam hal ini, aplikasi penginstalan harus melakukan salah satu hal berikut, tergantung pada kesalahan terakhir yang dikembalikan GetLastError untuk permintaan:
- Jika kesalahan terakhir adalah ERROR_DI_DO_DEFAULT, aplikasi penginstalan dapat langsung memanggil SetupDiRegisterDeviceInfo dan menyediakan CompareProc untuk melakukan deteksi duplikat. Jika panggilan ini berhasil dan tidak ada duplikat yang ditemukan, penginstalan perangkat dapat dilanjutkan. Jika duplikat ditemukan, SetupDiRegisterDeviceInfo mengembalikan FALSE, dan aplikasi penginstalan harus mengakhiri penginstalan perangkat.
- Jika kesalahan terakhir tidak ERROR_DI_DO_DEFAULT, aplikasi penginstalan harus mengakhiri penginstalan perangkat.
Pemanggil SetupDiRegisterDeviceInfo harus menjadi anggota grup Administrator.

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
DLL	Setupapi.dll

Lihat juga

DIF_REGISTERDEVICE

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS

Bagikan melalui