KsStreamIo, fonction (ks.h)

Article
02/07/2025

La fonction KsStreamIo effectue un flux de lecture ou d’écriture sur l’objet de fichier spécifié. La fonction tente d’utiliser FastIoDispatch si possible, ou génère une demande de lecture ou d’écriture sur l’objet de l’appareil.

Syntaxe

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

Paramètres

[in] FileObject

Spécifie l’objet de fichier sur lequel effectuer les E/S.

[in, optional] Event

Contient éventuellement l’événement à utiliser dans les E/S. Si aucun n’est passé, l’appel est supposé être sur un objet de fichier synchrone ou l’appelant attend l’événement de l’objet de fichier, ou bien il peut être terminé de manière asynchrone. Si elle est utilisée et que l’indicateur KSSTREAM_SYNCHRONOUS n’est pas défini, il doit s’agir d’un événement alloué par le gestionnaire d’objets. Si l’appelant effectue des E/S asynchrones, il doit attendre l’événement de l’objet de fichier ou passer un événement dans ce paramètre et l’attendre. Si ce n’est pas le cas, il n’existe aucun moyen pour l’appelant de savoir quand IoStatusBlock a été mis à jour par l’appel.

[in, optional] PortContext

Contient éventuellement des informations de contexte pour un port d’achèvement.

[in, optional] CompletionRoutine

Si vous le souhaitez, il pointe vers une routine d’achèvement pour cet IRP.

[in, optional] CompletionContext

Si completionRoutine est spécifié, cela fournit un pointeur de contexte dans le rappel de routine d’achèvement.

[in, optional] CompletionInvocationFlags

Spécifie les indicateurs d’appel spécifiant quand la routine d’achèvement est appelée. Consultez le tableau suivant pour connaître les valeurs utilisées.

[out] IoStatusBlock

Emplacement pour retourner les informations d’état. Il s’agit toujours d’une adresse valide, quel que soit le mode demandeur. La valeur doit rester valide tant que l’appel n’a pas mis à jour l’état. L’appelant doit effectuer des E/S synchrones ou attendre l’événement de l’objet de fichier ou un événement transmis dans le paramètre d’événement avant d’autoriser cette adresse à devenir non valide.

[in, out] StreamHeaders

Spécifie la liste des en-têtes de flux. Cette adresse, ainsi que les adresses des mémoires tampons de données, sont supposées avoir été examinées pour obtenir un accès approprié. Les clients en mode noyau qui envoient des en-têtes de streaming doivent allouer les en-têtes de la mémoire NonPagedPool.

[in] Length

Spécifie la taille du StreamHeaders passé.

[in] Flags

Spécifie différents indicateurs pour les E/S. Consultez le tableau suivant pour connaître les valeurs utilisées.

[in] RequestorMode

Indique le mode processeur à placer dans l’IRP si l’un d’eux doit être généré. Cette variable détermine également si un appel d’E/S rapide peut être effectué. Si le mode demandeur n’est pas le mode noyau, mais que le mode précédent est, les E/S rapides ne peuvent pas être utilisées.

Valeur de retour

La fonction KsStreamIo retourne STATUS_SUCCESS si elle réussit, STATUS_PENDING si l’action est en attente ou si elle échoue, elle renvoie une erreur d’E/S.

Remarques

Les valeurs énumérées suivantes sont utilisées pour la variable CompletionInvocationFlags et sont de type KSCOMPLETION_INVOCATION :

CompletionInvocationFlags	Description
KsInvokeOnSuccess	Appelle la routine d’achèvement en cas de réussite.
KsInvokeOnError	Appelle la routine d’achèvement en cas d’erreur.
KsInvokeOnCancel	Appelle la routine d’achèvement lors de l’annulation.

Les valeurs définies suivantes sont utilisées pour la variable Flags :

indicateurs	Description
KSSTREAM_READ	Spécifie qu’un IRP IOCTL_KS_STREAMREAD doit être généré. Il s’agit de la valeur par défaut.
KSSTREAM_WRITE	Spécifie qu’un IRP IOCTL_KS_STREAMWRITE doit être généré.
KSSTREAM_PAGED_DATA	Spécifie que les données sont paginables. Il s’agit de la valeur par défaut et peut être utilisée à tout moment.
KSSTREAM_NONPAGED_DATA	Spécifie que les données ne sont pas mises en page et peuvent être utilisées comme amélioration des performances.
KSSTREAM_SYNCHRONOUS	Spécifie que l’IRP est synchrone. Cela signifie que si le paramètre Event est passé, il n’est pas traité comme un événement de gestionnaire d’objets et n’est pas référencé ou déréférencé.

KSSTREAM_READ équivaut à KSPROBE_STREAMREAD.

De même, KSSTREAM_WRITE équivaut à KSPROBE_STREAMWRITE.

Exigences

Exigence	Valeur
plateforme cible	Universel
d’en-tête	ks.h (include Ks.h)
bibliothèque	Ks.lib

Partager via