KsStreamIo, fonction (ks.h)

Article
02/29/2024

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 d’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 transmis, l’appel est supposé se trouver sur un objet de fichier synchrone ou l’appelant attend l’événement de l’objet fichier, sinon il peut être terminé de manière asynchrone. S’il est utilisé 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 fichier ou passer un événement dans ce paramètre et l’attendre. Si ce n’est pas le cas, il n’y a aucun moyen pour l’appelant de savoir quand l’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

Pointe éventuellement vers une routine d’achèvement pour cette IRP.

[in, optional] CompletionContext

Si CompletionRoutine est spécifié, cela fournit un pointeur de contexte dans le rappel de la 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 de status. Il s’agit toujours d’une adresse valide, quel que soit le mode du demandeur. La valeur doit rester valide jusqu’à ce que l’appel ait mis à jour le status. L’appelant doit effectuer des E/S synchrones ou attendre l’événement de l’objet fichier ou un événement transmis dans le paramètre Event 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é sondé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 à partir de la mémoire NonPagedPool.

[in] Length

Spécifie la taille des StreamHeaders passés.

[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 un 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 l’est, les E/S rapides ne peuvent pas être utilisées.

Valeur retournée

La fonction KsStreamIo retourne STATUS_SUCCESS en cas de réussite, STATUS_PENDING si l’action est en attente ou si elle a échoué, elle retourne 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 peuvent être paginables. Il s’agit de la valeur par défaut et peut être utilisé à tout moment.
KSSTREAM_NONPAGED_DATA	Spécifie que les données ne sont pas paginés 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.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	ks.h (inclure Ks.h)
Bibliothèque	Ks.lib

Partager via