Fungsi KsStreamIo (ks.h)

Artikel
08/07/2023

Fungsi KsStreamIo melakukan streaming baca atau tulis terhadap objek file yang ditentukan. Fungsi ini mencoba menggunakan FastIoDispatch jika memungkinkan, atau menghasilkan permintaan baca atau tulis terhadap objek perangkat.

Sintaks

KSDDKAPI NTSTATUS KsStreamIo(
  [in]           PFILE_OBJECT            FileObject,
  [in, optional] PKEVENT                 Event,
  [in, optional] PVOID                   PortContext,
  [in, optional] PIO_COMPLETION_ROUTINE  CompletionRoutine,
  [in, optional] PVOID                   CompletionContext,
  [in, optional] KSCOMPLETION_INVOCATION CompletionInvocationFlags,
  [out]          PIO_STATUS_BLOCK        IoStatusBlock,
  [in, out]      PVOID                   StreamHeaders,
  [in]           ULONG                   Length,
  [in]           ULONG                   Flags,
  [in]           KPROCESSOR_MODE         RequestorMode
);

Parameter

[in] FileObject

Menentukan objek file untuk melakukan I/O terhadap.

[in, optional] Event

Secara opsional berisi peristiwa yang akan digunakan dalam I/O. Jika tidak ada yang diteruskan, panggilan diasumsikan berada pada objek file sinkron atau pemanggil sedang menunggu peristiwa objek file, atau panggilan dapat diselesaikan secara asinkron. Jika digunakan, dan bendera KSSTREAM_SYNCHRONOUS tidak diatur, ini harus menjadi peristiwa yang dialokasikan oleh manajer objek. Jika pemanggil melakukan I/O asinkron, penelepon harus menunggu peristiwa objek file atau meneruskan peristiwa dalam parameter ini dan menunggunya. Jika ini tidak dilakukan, maka tidak ada cara bagi pemanggil untuk mengetahui kapan IoStatusBlock telah diperbarui oleh panggilan.

[in, optional] PortContext

Secara opsional berisi informasi konteks untuk port penyelesaian.

[in, optional] CompletionRoutine

Secara opsional menunjuk ke rutinitas penyelesaian untuk IRP ini.

[in, optional] CompletionContext

Jika CompletionRoutine ditentukan, ini menyediakan penunjuk konteks dalam panggilan balik rutin penyelesaian.

[in, optional] CompletionInvocationFlags

Menentukan bendera pemanggilan yang menentukan kapan rutinitas penyelesaian dipanggil. Lihat tabel berikut untuk nilai yang digunakan.

[out] IoStatusBlock

Lokasi untuk mengembalikan informasi status. Ini selalu diasumsikan sebagai alamat yang valid, terlepas dari mode pemohon. Nilai harus tetap valid sampai panggilan telah memperbarui status. Pemanggil harus melakukan I/O sinkron atau harus menunggu peristiwa objek file atau peristiwa yang diteruskan dalam parameter Peristiwa sebelum mengizinkan alamat ini menjadi tidak valid.

[in, out] StreamHeaders

Menentukan daftar header stream. Alamat ini, serta alamat buffer data, diasumsikan telah diperiksa untuk akses yang sesuai. Klien mode kernel yang mengirimkan header streaming harus mengalokasikan header dari memori NonPagedPool.

[in] Length

Menentukan ukuran StreamHeaders yang diteruskan.

[in] Flags

Menentukan berbagai bendera untuk I/O. Lihat tabel berikut untuk nilai yang digunakan.

[in] RequestorMode

Menunjukkan mode prosesor untuk ditempatkan di IRP jika perlu dibuat. Variabel ini juga menentukan apakah panggilan I/O cepat dapat dilakukan. Jika mode pemohon bukan mode kernel, tetapi mode sebelumnya adalah, maka I/O cepat tidak dapat digunakan.

Nilai kembali

Fungsi KsStreamIo mengembalikan STATUS_SUCCESS jika berhasil, STATUS_PENDING jika tindakan tertunda, atau jika tidak berhasil, tindakan tersebut mengembalikan kesalahan I/O.

Keterangan

Nilai enumerasi berikut digunakan untuk variabel CompletionInvocationFlags dan berjenis KSCOMPLETION_INVOCATION:

CompletionInvocationFlags	Deskripsi
KsInvokeOnSuccess	Memanggil rutinitas penyelesaian pada keberhasilan.
KsInvokeOnError	Memanggil rutinitas penyelesaian pada kesalahan.
KsInvokeOnCancel	Memanggil rutinitas penyelesaian pada pembatalan.

Nilai yang ditentukan berikut digunakan untuk variabel Bendera :

Bendera	Deskripsi
KSSTREAM_READ	Menentukan bahwa IOCTL_KS_STREAMREAD IRP akan dibangun. Ini adalah default.
KSSTREAM_WRITE	Menentukan bahwa IRP IOCTL_KS_STREAMWRITE akan dibangun.
KSSTREAM_PAGED_DATA	Menentukan bahwa data dapat di-pageable. Ini adalah default dan dapat digunakan setiap saat.
KSSTREAM_NONPAGED_DATA	Menentukan bahwa data tidak disebarkan dan dapat digunakan sebagai peningkatan performa.
KSSTREAM_SYNCHRONOUS	Menentukan bahwa IRP sinkron. Ini berarti bahwa jika parameter Peristiwa diteruskan, parameter tersebut tidak diperlakukan sebagai peristiwa manajer objek dan tidak direferensikan atau didereferensikan.

KSSTREAM_READ setara dengan KSPROBE_STREAMREAD.

Demikian pula, KSSTREAM_WRITE setara dengan KSPROBE_STREAMWRITE.

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	ks.h (termasuk Ks.h)
Pustaka	Ks.lib

Share via