Fungsi SwDeviceCreate (swdevice.h)

Artikel
03/04/2024

Memulai enumerasi perangkat lunak.

Sintaks

HRESULT SwDeviceCreate(
  [in]           PCWSTR                      pszEnumeratorName,
  [in]           PCWSTR                      pszParentDeviceInstance,
  [in]           const SW_DEVICE_CREATE_INFO *pCreateInfo,
  [in]           ULONG                       cPropertyCount,
  [in, optional] const DEVPROPERTY           *pProperties,
  [in]           SW_DEVICE_CREATE_CALLBACK   pCallback,
  [in, optional] PVOID                       pContext,
  [out]          PHSWDEVICE                  phSwDevice
);

Parameter

[in] pszEnumeratorName

String yang menamai enumerator perangkat lunak. Pilih nama yang mewakili komponen yang menghitung perangkat.

[in] pszParentDeviceInstance

String yang menentukan ID instans perangkat dari perangkat yang merupakan induk perangkat lunak.

Ini bisa HTREE\ROOT\0, tetapi kami sarankan untuk menjaga anak-anak dari perangkat root minimal. Kami juga menyarankan agar induk pilihan perangkat lunak menjadi perangkat nyata yang diperluas oleh perangkat lunak. Dalam situasi di mana perangkat lunak tidak memiliki induk alami seperti itu, buat perangkat sebagai anak dari root yang dapat mengumpulkan semua perangkat perangkat lunak yang akan dijumlahkan oleh komponen; kemudian, hitung perangkat perangkat lunak aktual sebagai turunan dari simpul pengelompokan perangkat ini. Ini membuat anak-anak perangkat root ke nomor yang dapat dikelola.

[in] pCreateInfo

Penunjuk ke struktur SW_DEVICE_CREATE_INFO yang menjelaskan info yang digunakan PnP untuk membuat perangkat.

[in] cPropertyCount

Jumlah struktur DEVPROPERTY dalam array pProperties .

[in, optional] pProperties

Array opsional struktur DEVPROPERTY . Properti ini diatur pada perangkat setelah dibuat tetapi sebelum pemberitahuan bahwa perangkat telah dibuat dikirim. Untuk informasi selengkapnya, lihat Komentar. Penunjuk ini bisa NULL.

[in] pCallback

Fungsi panggilan balik SW_DEVICE_CREATE_CALLBACK yang dipanggil sistem operasi setelah PnP menghitung perangkat.

[in, optional] pContext

Konteks klien opsional yang diteruskan sistem operasi ke fungsi panggilan balik. Penunjuk ini bisa NULL.

[out] phSwDevice

Penunjuk ke variabel yang menerima handel HSWDEVICE yang mewakili perangkat. Panggil SwDeviceClose untuk menutup handel ini setelah aplikasi klien ingin PnP menghapus perangkat.


DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;

Nilai kembali

S_OK dikembalikan jika enumerasi perangkat berhasil dimulai. Ini tidak berarti bahwa perangkat telah berhasil dijumlahkan. Periksa parameter CreateResult dari fungsi panggilan balik SW_DEVICE_CREATE_CALLBACK untuk menentukan apakah perangkat berhasil dijumlahkan.

Keterangan

SwDeviceCreate mengembalikan handel yang mewakili perangkat. Setelah handel ini ditutup, PnP akan menghapus perangkat.

Proses panggilan harus memiliki akses Administrator untuk memulai enumerasi perangkat lunak.

PnP membentuk ID instans perangkat dari perangkat lunak sebagai "SWD< pszEnumeratorName>< pszInstanceId>," tetapi string ini mungkin berubah atau PnP mungkin menghiasi nama. Selalu dapatkan ID instans perangkat dari fungsi panggilan balik.

Ada perbedaan halus antara properti yang ditetapkan sebagai bagian dari panggilan dan properti SwDeviceCreate yang kemudian diatur dengan memanggil SwDevicePropertySet. Properti yang ditetapkan sebagai bagian dari SwDeviceCreate disimpan dalam memori; jika perangkat dihapus instalannya atau driver null menghapus penyimpanan properti, properti ini ditulis lagi oleh fitur API Perangkat Lunak saat PnP menghitung ulang perangkat. Ini semua transparan untuk klien. Properti yang diatur menggunakan SwDevicePropertySet setelah enumerasi tidak bertahan dalam memori. Tetapi, jika Anda mengatur properti dengan menggunakan SwDeviceCreate, Anda dapat memperbarui nilai dengan SwDevicePropertySet, dan pembaruan ini diterapkan ke nilai dalam memori serta penyimpanan yang bertahan.

Kami menyarankan agar semua properti ditentukan sebagai bagian dari panggilan ke SwDeviceCreate jika memungkinkan dan bahwa properti ini ditentukan untuk setiap panggilan ke SwDeviceCreate.

Catatan Sistem operasi mungkin memanggil SW_DEVICE_CREATE_CALLBACK sebelum panggilan ke SwDeviceCreate kembali. Untuk alasan ini, handel perangkat lunak untuk perangkat disediakan sebagai parameter untuk fungsi panggilan balik.

Anda dapat membuat perangkat lunak sebagai anak dari induk yang tidak ada pada saat itu. PnP akan menghitung perangkat lunak setelah induk hadir.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8
Server minimum yang didukung	Windows Server 2012
Target Platform	Universal
Header	swdevice.h
Pustaka	Swdevice.lib; OneCoreUAP.lib di Windows 10
DLL	Cfgmgr32.dll

Lihat juga

SW_DEVICE_CREATE_CALLBACK

Bagikan melalui