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 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
WdfRequestRetrieveOutputMemory retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :
| Code de retour | Description |
|---|---|
|
Un paramètre d’entrée n’est pas valide. |
|
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. |
|
La demande a déjà été effectuée. |
|
La longueur de la mémoire tampon de sortie est égale à zéro. |
|
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 de sortie d’une requête reçoit des informations, telles que des données d’un disque, que le pilote fournit à l’initiateur 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 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 requête est IRP_MJ_INTERNAL_DEVICE_CONTROL, ou si la requête provient d’un autre pilote en mode noyau, WdfRequestRetrieveOutputMemory prend également en charge les demandes d’E/S qui n’utilisent ni mise en mémoire tampon ni E/S directes.
Si WdfRequestRetrieveOutputMemory retourne STATUS_SUCCESS, le pilote reçoit un handle pour un objet de mémoire d’infrastructure 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 demande d’E/S que représente le paramètre Request .
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 les pilotes Framework-Based.
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;
}
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), 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) |