Fungsi ScsiPortWmiSetInstanceName (scsiwmi.h)

Artikel
08/07/2023

ScsiPortWmiSetInstanceName rutin memperbarui struktur WNODE_ALL_DATA dalam konteks permintaan untuk menentukan posisi dan panjang nama instans.

Catatan Driver port SCSI dan model driver miniport SCSI dapat diubah atau tidak tersedia di masa mendatang. Sebagai gantinya, sebaiknya gunakan driver Storport dan model driver miniport Storport .

Sintaks

PWCHAR ScsiPortWmiSetInstanceName(
  [in]      PSCSIWMI_REQUEST_CONTEXT RequestContext,
  [in]      ULONG                    InstanceIndex,
  [in]      ULONG                    InstanceNameLength,
  [out]     PULONG                   BufferAvail,
  [in, out] PULONG                   SizeNeeded
);

Parameter

[in] RequestContext

Penunjuk ke struktur jenis SCSIWMI_REQUEST_CONTEXT yang berisi konteks permintaan untuk WMI SRB.

[in] InstanceIndex

Berisi indeks yang menunjukkan instans yang posisi dan panjang nama instansnya akan ditentukan.

[in] InstanceNameLength

Menentukan ukuran dalam byte nama instans.

[out] BufferAvail

Harus berisi, pada input, jumlah byte ruang buffer dalam struktur WNODE_ALL_DATA yang dapat digunakan untuk menjelaskan nama instans dan data. Saat kembali, anggota ini berisi jumlah byte ruang buffer yang tersisa.

Ada tiga rutinitas SCSI Port WMI yang mengembalikan nilai untuk ukuran buffer yang tersedia dalam parameter BufferAvail mereka:

ScsiPortWmiSetInstanceCount

ScsiPortWmiSetData

ScsiPortWmiSetInstanceName

Driver miniport harus memanggil ScsiPortWmiSetInstanceCount terlebih dahulu, tetapi setelah ScsiPortWmiSetInstanceCount dipanggil, tidak masalah dalam urutan apa minidriver memanggil ScsiPortWmiSetData dan ScsiPortWmiSetInstanceName. Saat memanggil ScsiPortWmiSetData atau ScsiPortWmiSetInstanceName, nilai yang diteruskan ke rutinitas dalam parameter BufferAvail-nya harus sama dengan nilai yang dikembalikan dalam parameter BufferAvail oleh yang terbaru disebut rutinitas SCSI Port WMI. Misalnya, minidriver memanggil ScsiPortWmiSetInstanceCount terlebih dahulu, dan rutinitas ini mengembalikan nilai 1.000 dalam parameter BufferAvail-nya . Selanjutnya, minidriver memanggil ScsiPortWmiSetData yang mengembalikan nilai 500 dalam parameter BufferAvail-nya . Terakhir, minidriver memanggil ScsiPortWmiSetInstanceName yang mengembalikan nilai 200 dalam parameter BufferAvail-nya . Nilai awal 1.000 harus diteruskan ke ScsiPortWmiSetData di BufferAvail, dan nilai 500 harus diteruskan ke ScsiPortWmiSetInstanceName.

Jika tidak ada cukup memori yang tersedia untuk menambahkan nama instans dengan panjang InstanceNameLength, nol akan dikembalikan di anggota BufferAvail .

[in, out] SizeNeeded

Menunjukkan, pada input, jumlah byte yang diperlukan untuk menjelaskan WNODE sebelum menambahkan data deskriptif untuk instans yang ditentukan oleh InstanceIndex. Saat kembali, anggota ini akan berisi ukuran seluruh WNODE, termasuk data untuk instans baru.

Nilai kembali

Rutinitas ScsiPortWmiSetInstanceCount mengembalikan penunjuk ke buffer tempat pemanggil dapat menyimpan nama instans yang ditentukan dalam InstanceIndex. Jika ScsiPortWmiSetInstanceCount tidak dapat mengalokasikan cukup memori untuk nama instans, atau jika WNODE yang terkandung dalam konteks permintaan tidak berjenis WNODE_ALL_DATA, ScsiPortWmiSetData mengembalikan NULL.

Keterangan

Minidriver harus memanggil ScsiPortWmiSetInstanceCount sebelum memanggil ScsiPortWmiSetInstanceName.

Parameter RequestContext menunjuk ke struktur konteks permintaan, SCSIWMI_REQUEST_CONTEXT, yang berisi informasi yang terkait dengan blok permintaan SCSI Windows Management Instrumentation (WMI). Struktur konteks permintaan, pada gilirannya, berisi salah satu Struktur WNODE_XXX WMI yang digunakan oleh sistem WMI untuk meneruskan data antara konsumen data mode pengguna dan penyedia data mode kernel seperti driver.

Rutinitas ScsiPortWmiSetInstanceName memerlukan struktur WNODE yang ditentukan dalam konteks permintaan berjenis WNODE_ALL_DATA. Ini karena ScsiPortWmiSetInstanceName dapat menyisihkan area nama instans untuk salah satu instans yang terkait dengan blok data WMI. Tidak seperti struktur WNODE_SINGLE_INSTANCE yang berisi informasi tentang satu instans, struktur WNODE_ALL_DATA berisi array pointer ke area buffer untuk instans yang berbeda, dan ScsiPortWmiSetInstanceCount menginisialisasi array ini, sehingga setiap buffer data instans dapat diakses satu per satu.

Memori yang dialokasikan untuk konteks permintaan harus tetap valid sampai setelah driver miniport memanggil ScsiPortWmiPostProcess, dan ScsiPortWmiPostProcess mengembalikan status SRB akhir dan ukuran buffer. Jika SRB dapat tertunda, memori untuk konteks permintaan harus dialokasikan dari ekstensi SRB. Jika SRB tidak dapat tertunda, memori dapat dialokasikan dari bingkai tumpukan yang tidak keluar dari cakupan.

Persyaratan

Persyaratan	Nilai
Target Platform	Desktop
Header	scsiwmi.h (termasuk Miniport.h, Scsi.h)

Lihat juga

SCSIWMI_REQUEST_CONTEXT

WNODE_ALL_DATA

WNODE_SINGLE_INSTANCE

Bagikan melalui