WdfRequestRetrieveOutputMemory, fonction (wdfrequest.h)

[S’applique à KMDF et UMDF]

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

Syntaxe

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

Paramètres

[in] Request

Handle vers un objet de requête de framework.

[out] Memory

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

Valeur de retour

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

Retourner le code	Description
STATUS_INVALID_PARAMETER	Un paramètre d’entrée n’est pas valide.
STATUS_INVALID_DEVICE_REQUEST	Le type de requête n’est pas valide ou la requête utilise ni mise en mémoire tampon nid’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 de sortie est égale à zéro.
STATUS_INSUFFICIENT_RESOURCES	La mémoire est insuffisante.

 

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

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

La mémoire tampon de sortie d’une requête reçoit des informations, telles que les données d’un disque, que le pilote fournit à l’origine de la requête. Votre pilote peut appeler WdfRequestRetrieveOutputMemory pour obtenir la mémoire tampon de sortie pour une demande de lecture ou une demande de contrôle d’E/S d’appareil, mais pas pour une demande d’écriture (car les demandes d’écriture ne fournissent pas de données de sortie).

La méthode WdfRequestRetrieveOutputMemory récupère la mémoire tampon de sortie pour les requêtes d’E/S qui utilisent la méthode d’E/S mise en mémoire tampon 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 requête est IRP_MJ_INTERNAL_DEVICE_CONTROLou si la requête provient d’un autre pilote en mode noyau, WdfRequestRetrieveOutputMemory prend également en charge les requêtes d’E/S qui utilisent ni mises en mémoire tampon nidirectes d’E/S.

Si WdfRequestRetrieveOutputMemory retourne STATUS_SUCCESS, le pilote reçoit un handle vers un objet mémoire de framework qui représente la mémoire tampon de sortie. 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 requête d’E/S que le paramètre Request représente.

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

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

Exemples

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

VOID 
MyEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    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->BulkReadPipe;

    //
    // Get output memory.
    //
    status = WdfRequestRetrieveOutputMemory(
                                            Request,
                                            &reqMemory
                                            );
    if(!NT_SUCCESS(status)){
        goto Exit;
    }
    //
    // Format the request.
    //
    status = WdfUsbTargetPipeFormatRequestForRead(
                                           pipe,
                                           Request,
                                           reqMemory,
                                           NULL
                                           ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestReadCompletionRoutine,
                                   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;
}

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’en-tête	wdfrequest.h (include Wdf.h)
bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
règles de conformité DDI	DriverCreate(kmdf), invalidReqAccess(kmdf), invalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedReadA(kmdf), MemAfterReqCompletedWrite(kmdf), OutputBufferAPI(kmdf)

Voir aussi

WdfMemoryGetBuffer

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputBuffer