Funzione KsStreamIo (ks.h)

Articolo
02/07/2025

La funzione KsStreamIo esegue una lettura o una scrittura del flusso sull'oggetto file specificato. La funzione tenta di usare FastIoDispatch, se possibile, oppure genera una richiesta di lettura o scrittura sull'oggetto dispositivo.

Sintassi

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
);

Parametri

[in] FileObject

Specifica l'oggetto file su cui eseguire l'I/O.

[in, optional] Event

Facoltativamente contiene l'evento da usare nell'I/O. Se non viene passato nessuno, si presuppone che la chiamata si tratti di un oggetto file sincrono o che il chiamante sia in attesa dell'evento dell'oggetto file oppure che possa essere completato in modo asincrono. Se utilizzato e il flag KSSTREAM_SYNCHRONOUS non è impostato, deve essere un evento allocato dal gestore oggetti. Se il chiamante esegue operazioni di I/O asincrone, deve attendere l'evento dell'oggetto file o passare un evento in questo parametro e attenderlo. Se questa operazione non viene eseguita, non c'è modo per il chiamante di sapere quando L'IoStatusBlock è stato aggiornato dalla chiamata.

[in, optional] PortContext

Facoltativamente, contiene informazioni di contesto per una porta di completamento.

[in, optional] CompletionRoutine

Facoltativamente, punta a una routine di completamento per questo IRP.

[in, optional] CompletionContext

Se si specifica completionRoutine, viene fornito un puntatore di contesto nel callback della routine di completamento.

[in, optional] CompletionInvocationFlags

Specifica i flag di chiamata che specificano quando viene richiamata la routine di completamento. Vedere la tabella seguente per i valori usati.

[out] IoStatusBlock

Posizione in cui restituire le informazioni sullo stato. Si presuppone sempre che sia un indirizzo valido, indipendentemente dalla modalità richiedente. Il valore deve rimanere valido fino a quando la chiamata non ha aggiornato lo stato. Il chiamante deve eseguire operazioni di I/O sincrone oppure deve attendere l'evento dell'oggetto file o un evento passato nel parametro Event prima di consentire a questo indirizzo di diventare non valido.

[in, out] StreamHeaders

Specifica l'elenco di intestazioni di flusso. Questo indirizzo, nonché gli indirizzi dei buffer di dati, si presuppone che siano stati sottoposti a probe per l'accesso appropriato. I client in modalità kernel che inviano intestazioni di streaming devono allocare le intestazioni dalla memoria NonPagedPool.

[in] Length

Specifica le dimensioni del StreamHeaders passato.

[in] Flags

Specifica vari flag per l'I/O. Vedere la tabella seguente per i valori usati.

[in] RequestorMode

Indica la modalità processore da inserire nell'IRP se è necessario generarne una. Questa variabile determina anche se è possibile eseguire una chiamata di I/O veloce. Se la modalità richiedente non è in modalità kernel, ma la modalità precedente è , non è possibile usare l'I/O veloce.

Valore restituito

La funzione KsStreamIo restituisce STATUS_SUCCESS se ha esito positivo, STATUS_PENDING se l'azione è in sospeso o se ha esito negativo restituisce un errore di I/O.

Osservazioni

I valori enumerati seguenti vengono usati per la variabile CompletionInvocationFlags e sono di tipo KSCOMPLETION_INVOCATION:

CompletionInvocationFlags	Descrizione
KsInvokeOnSuccess	Richiama la routine di completamento in caso di esito positivo.
KsInvokeOnError	Richiama la routine di completamento in caso di errore.
KsInvokeOnCancel	Richiama la routine di completamento all'annullamento.

Per la variabile flag vengono usati i valori definiti seguenti:

flag	Descrizione
KSSTREAM_READ	Specifica che deve essere compilato un IOCTL_KS_STREAMREAD IRP. Si tratta dell'impostazione predefinita.
KSSTREAM_WRITE	Specifica che deve essere compilato un IOCTL_KS_STREAMWRITE IRP.
KSSTREAM_PAGED_DATA	Specifica che i dati sono visualizzabili in pagine. Si tratta dell'impostazione predefinita e può essere usata in qualsiasi momento.
KSSTREAM_NONPAGED_DATA	Specifica che i dati non vengono visualizzati e possono essere usati come miglioramento delle prestazioni.
KSSTREAM_SYNCHRONOUS	Specifica che l'IRP è sincrono. Ciò significa che se il parametro Event viene passato, non viene considerato come un evento di gestione oggetti e non viene fatto riferimento o dereferenziato.

KSSTREAM_READ equivale a KSPROBE_STREAMREAD.

Analogamente, KSSTREAM_WRITE equivale a KSPROBE_STREAMWRITE.

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
intestazione	ks.h (include Ks.h)
libreria	Ks.lib

Condividi tramite