WdfRequestRetrieveInputMemory, fonction (wdfrequest.h)

[S’applique à KMDF et UMDF]

La méthode WdfRequestRetrieveInputMemory récupère un handle dans un objet de mémoire d’infrastructure qui représente la mémoire tampon d’entrée d’une requête d’E/S.

Syntaxe

NTSTATUS WdfRequestRetrieveInputMemory(
  [in]  WDFREQUEST Request,
  [out] WDFMEMORY  *Memory
);

Paramètres

[in] Request

Handle pour un objet de requête d’infrastructure.

[out] Memory

Pointeur vers un emplacement qui reçoit un handle vers un objet de mémoire de framework.

Valeur retournée

WdfRequestRetrieveInputMemory 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 d’entrée n’est pas valide.
STATUS_INVALID_DEVICE_REQUEST	Le type de demande n’est pas valide ou la demande n’utilise ni e/S en mémoire tampon ni d’E/S directes. Pour plus d’informations sur les méthodes prises en charge pour accéder aux mémoires tampons de données, consultez la section Remarques suivante.
STATUS_INTERNAL_ERROR	La demande a déjà été effectuée.
STATUS_BUFFER_TOO_SMALL	La longueur de la mémoire tampon d’entrée est égale à zéro.
STATUS_INSUFFICIENT_RESOURCES	La mémoire est insuffisante.

 

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

La mémoire tampon d’entrée d’une requête contient des informations, telles que les données à écrire sur un disque, qui ont été fournies par l’initiateur de la requête. Votre pilote peut appeler WdfRequestRetrieveInputMemory pour obtenir la mémoire tampon d’entrée pour une demande d’écriture ou une demande de contrôle d’E/S d’appareil, mais pas pour une demande de lecture (car les demandes de lecture ne fournissent pas de données d’entrée).

La méthode WdfRequestRetrieveInputMemory récupère la mémoire tampon d’entrée pour les demandes d’E/S qui utilisent la méthode d’E/S mise en mémoire tampon ou la méthode d’E/S directe pour accéder aux mémoires tampons de données. Si le code de contrôle d’E/S de la demande est IRP_MJ_INTERNAL_DEVICE_CONTROL, ou si la requête provient d’un autre pilote en mode noyau, WdfRequestRetrieveInputMemory prend également en charge les demandes d’E/S qui n’utilisent ni mise en mémoire tampon ni E/S directes.

Si WdfRequestRetrieveInputMemory retourne STATUS_SUCCESS, le pilote reçoit un handle pour un objet de mémoire du framework qui représente la mémoire tampon d’entrée. Pour accéder à la mémoire tampon, le pilote doit appeler WdfMemoryGetBuffer.

Le pilote peut accéder à l’objet mémoire du framework récupéré jusqu’à ce qu’il termine la demande d’E/S que représente le paramètre Request .

Au lieu d’appeler WdfRequestRetrieveInputMemory, le pilote peut appeler WdfRequestRetrieveInputBuffer, qui récupère l’adresse et la longueur de la mémoire tampon.

Pour plus d’informations sur WdfRequestRetrieveInputMemory, consultez Accès aux mémoires tampons de données dans les pilotes Framework-Based.

Exemples

L’exemple de code suivant montre comment une fonction de rappel EvtIoWrite peut obtenir un handle pour l’objet mémoire du framework qui représente la mémoire tampon d’entrée d’une demande d’écriture. L’exemple met ensuite en forme et envoie la demande d’écriture à une cible d’E/S USB.

VOID 
MyEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    NTSTATUS  status;
    WDFUSBPIPE  pipe;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    //
    // The driver previously stored a pipe handle in 
    // the device object's context space.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkWritePipe;

    //
    // Get input memory.
    //
    status = WdfRequestRetrieveInputMemory(
                                           Request,
                                           &reqMemory
                                           );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }

    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForWrite(
                                          pipe,
                                          Request,
                                          reqMemory,
                                          NULL
                                          );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestWriteCompletionRoutine,
                                   pipe
                                   );

    //
    // Send the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    //
    // Complete the request now if an error occurred.
    //
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfrequest.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), InputBufferAPI(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedWrite(kmdf) , MemAfterReqCompletedWriteA(kmdf)

Voir aussi

WdfMemoryGetBuffer

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory