WdfIoTargetFormatRequestForInternalIoctlOthers, fonction (wdfiotarget.h)

Article
08/08/2023

[S’applique uniquement à KMDF]

La méthode WdfIoTargetFormatRequestForInternalIoctlOthers génère une demande de contrôle d’appareil interne non standard pour une cible d’E/S, mais n’envoie pas la requête.

Syntaxe

NTSTATUS WdfIoTargetFormatRequestForInternalIoctlOthers(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in]           ULONG             IoctlCode,
  [in, optional] WDFMEMORY         OtherArg1,
  [in, optional] PWDFMEMORY_OFFSET OtherArg1Offset,
  [in, optional] WDFMEMORY         OtherArg2,
  [in, optional] PWDFMEMORY_OFFSET OtherArg2Offset,
  [in, optional] WDFMEMORY         OtherArg4,
  [in, optional] PWDFMEMORY_OFFSET OtherArg4Offset
);

Paramètres

[in] IoTarget

Handle vers un objet cible d’E/S local ou distant qui a été obtenu à partir d’un appel précédent à WdfDeviceGetIoTarget ou WdfIoTargetCreate, ou à partir d’une méthode qu’une cible d’E/S spécialisée fournit.

[in] Request

Handle d’un objet de requête d’infrastructure. Pour plus d'informations, consultez la section Notes qui suit.

[in] IoctlCode

Code de contrôle d’E/S (IOCTL) pris en charge par la cible d’E/S.

[in, optional] OtherArg1

Handle d’un objet de mémoire framework. Cet objet représente une mémoire tampon que le pilote utilise pour les informations de contexte spécifiques à la requête et définies par le pilote. Pour plus d'informations, consultez la section Notes qui suit. Ce paramètre est facultatif et peut être NULL.

[in, optional] OtherArg1Offset

Pointeur vers une structure de WDFMEMORY_OFFSET allouée à l’appelant qui fournit des valeurs facultatives de décalage d’octet et de longueur. Les pilotes peuvent utiliser ces valeurs pour spécifier l’adresse de début et la longueur d’un segment de la zone de contexte spécifiée par OtherArg1. Ce paramètre est facultatif et peut être NULL.

[in, optional] OtherArg2

[in, optional] OtherArg2Offset

Pointeur vers une structure de WDFMEMORY_OFFSET allouée à l’appelant qui fournit des valeurs facultatives de décalage d’octet et de longueur. Les pilotes peuvent utiliser ces valeurs pour spécifier l’adresse de début et la longueur d’un segment de la zone de contexte spécifiée par OtherArg2. Ce paramètre est facultatif et peut être NULL.

[in, optional] OtherArg4

[in, optional] OtherArg4Offset

Pointeur vers une structure de WDFMEMORY_OFFSET allouée à l’appelant qui fournit des valeurs facultatives de décalage d’octet et de longueur. Les pilotes peuvent utiliser ces valeurs pour spécifier l’adresse de début et la longueur d’un segment de la zone de contexte spécifiée par OtherArg4. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

WdfIoTargetFormatRequestForInternalIoctlOthers retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INVALID_DEVICE_REQUEST	La longueur de transfert était supérieure à la longueur de la mémoire tampon, ou la demande d’E/S était déjà mise en file d’attente vers une cible d’E/S.
STATUS_INSUFFICIENT_RESOURCES	L’infrastructure n’a pas pu allouer de ressources système (généralement de la mémoire).
STATUS_REQUEST_NOT_ACCEPTED	Le paquet de demande d’E/S (IRP) que représente le paramètre Request ne fournit pas suffisamment de structures IO_STACK_LOCATION pour permettre au pilote de transférer la requête.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Utilisez la méthode WdfIoTargetFormatRequestForInternalIoctlOthers , suivie de la méthode WdfRequestSend , pour envoyer des demandes de contrôle d’appareil interne non standard de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfIoTargetSendInternalIoctlOthersSynchronously pour envoyer des demandes de contrôle d’appareil interne non standard de manière synchrone.

Vous pouvez transférer une demande de contrôle d’appareil interne non standard que votre pilote a reçue dans une file d’E/S, ou vous pouvez créer et envoyer une nouvelle demande. Dans les deux cas, l’infrastructure nécessite un objet de requête et un espace de mémoire tampon.

Pour transférer une demande de contrôle d’appareil interne non standard que votre pilote a reçue dans une file d’E/S :

Spécifiez le handle de la requête reçue pour le paramètre Request de la méthode WdfIoTargetFormatRequestForInternalIoctlOthers.
Utilisez les informations de contexte de la demande reçue pour les paramètresOtherArg1, OtherArg2 de la méthode WdfIogetFormatRequestForInternalIoctlOthers.
Pour obtenir ces valeurs de paramètre, le pilote doit appeler WdfRequestGetParameters et utiliser le membre DeviceIoControl de la structure WDF_REQUEST_PARAMETERS qui est retournée.

Pour plus d’informations sur le transfert d’une demande d’E/S, consultez Transfert de demandes d’E/S.

Les pilotes divisent souvent les demandes d’E/S reçues en demandes plus petites qu’ils envoient à une cible d’E/S, afin que votre pilote puisse en créer de nouvelles.

Pour créer une demande d’E/S :

Créez un objet de requête et fournissez son handle pour le paramètre Request de la méthode WdfIoTargetFormatRequestForInternalIoctlOthers.
Appelez WdfRequestCreate pour préallouer un ou plusieurs objets de requête. Vous pouvez réutiliser ces objets de requête en appelant WdfRequestReuse. La fonction de rappel EvtDriverDeviceAdd de votre pilote peut préallouer des objets de requête pour un appareil.
Fournissez des mémoires tampons de contexte, si la requête les requiert, et fournissez des handles de mémoire tampon pour les paramètres OtherArg1, OtherArg2 et OtherArg4 de la méthode WdfIonalIoctlOthers.
Votre pilote doit spécifier cet espace tampon en tant que handles WDFMEMORY pour la mémoire gérée par l’infrastructure. Pour obtenir des handles WDFMEMORY, le pilote appelle WdfMemoryCreate ou WdfMemoryCreatePreallocated.

Après qu’un pilote a appelé WdfIoTargetFormatRequestForInternalIoctlOthers pour mettre en forme une demande de contrôle d’appareil, le pilote doit appeler WdfRequestSend pour envoyer la requête (de manière synchrone ou asynchrone) à une cible d’E/S.

Les appels multiples à WdfIoTargetFormatRequestForInternalIoctlOthers qui utilisent la même requête ne provoquent pas d’allocations de ressources supplémentaires. Par conséquent, pour réduire le risque que WdfRequestCreate retourne STATUS_INSUFFICIENT_RESOURCES, la fonction de rappel EvtDriverDeviceAdd de votre pilote peut appeler WdfRequestCreate pour préallouer un ou plusieurs objets de requête pour un appareil. Le pilote peut ensuite réutiliser (appeler WdfRequestReuse), reformater (appeler WdfIoTargetFormatRequestForInternalIoctlOthers) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer un STATUS_INSUFFICIENT_RESOURCES valeur de retour à partir d’un appel ultérieur à WdfRequestCreate. (Si le pilote n’appelle pas la même méthode de mise en forme des requêtes à chaque fois, des ressources supplémentaires peuvent être allouées.) Tous les appels suivants à WdfIoTargetFormatRequestForInternalIoctlOthers pour l’objet de requête réutilisé retournent STATUS_SUCCESS, si les valeurs des paramètres ne changent pas.

Pour plus d’informations sur l’obtention d’informations status après la fin d’une demande d’E/S, consultez Obtention des informations d’achèvement.

Pour plus d’informations sur WdfIoTargetFormatRequestForInternalIoctlOthers, consultez Envoi de demandes d’E/S à des cibles d’E/S générales.

Pour plus d’informations sur les cibles d’E/S, consultez Utilisation des cibles d’E/S.

Exemples

L’exemple de code suivant crée un objet de mémoire framework, obtient la mémoire tampon que l’objet mémoire contient et initialise la mémoire tampon. Ensuite, l’exemple met en forme la demande, définit une fonction de rappel CompletionRoutine et envoie la demande à une cible d’E/S.

PIRB pIrb;
WDFMEMORY memory;
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(IRB),
                         &memory,
                         NULL
                         );
if (!NT_SUCCESS(status)) {
    goto Done;
}
pIrb = WdfMemoryGetBuffer(
                          memory,
                          NULL
                          );

pIrb->FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
pIrb->Flags = 0;
pIrb->u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
pIrb->u.AllocateAddressRange.fulFlags = fulFlags;
pIrb->u.AllocateAddressRange.nLength = nLength;
pIrb->u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
pIrb->u.AllocateAddressRange.fulAccessType = fulAccessType;
pIrb->u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
pIrb->u.AllocateAddressRange.Callback = NULL;
pIrb->u.AllocateAddressRange.Context = NULL;
pIrb->u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
pIrb->u.AllocateAddressRange.FifoSListHead = NULL;
pIrb->u.AllocateAddressRange.FifoSpinLock = NULL;
pIrb->u.AllocateAddressRange.AddressesReturned = 0;
pIrb->u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
pIrb->u.AllocateAddressRange.DeviceExtension = deviceExtension;

status = WdfIoTargetFormatRequestForInternalIoctlOthers(
                                                        IoTarget,
                                                        Request,
                                                        IOCTL_1394_CLASS,
                                                        memory,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL
                                                        );

if (!NT_SUCCESS(status)) {
    goto Done;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               MyRequestCompletion,
                               NULL
                               );

if (WdfRequestSend(
                   Request,
                   IoTarget,
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
}
else {
    status = STATUS_SUCCESS;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfiotarget.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)