WdfRequestRetrieveOutputBuffer, fonction (wdfrequest.h)
[S’applique à KMDF et UMDF]
La méthode WdfRequestRetrieveOutputBuffer récupère la mémoire tampon de sortie d’une requête d’E/S.
Syntaxe
NTSTATUS WdfRequestRetrieveOutputBuffer(
[in] WDFREQUEST Request,
[in] size_t MinimumRequiredSize,
[out] PVOID *Buffer,
[out, optional] size_t *Length
);
Paramètres
[in] Request
Handle pour un objet de requête d’infrastructure.
[in] MinimumRequiredSize
Taille de mémoire tampon minimale, en octets, dont le pilote a besoin pour traiter la demande d’E/S.
[out] Buffer
Pointeur vers un emplacement qui reçoit l’adresse de la mémoire tampon.
[out, optional] Length
Pointeur vers un emplacement qui reçoit la taille de la mémoire tampon, en octets. Ce paramètre est facultatif et peut être NULL.
Valeur retournée
WdfRequestRetrieveOutputBuffer 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. |
|
La longueur de la mémoire tampon de sortie est égale à zéro, ou le paramètre MinimumRequiredSize spécifie une taille de mémoire tampon supérieure à la taille réelle de la mémoire tampon. |
|
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 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 WdfRequestRetrieveOutputBuffer 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 WdfRequestRetrieveOutputBuffer 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, WdfRequestRetrieveOutputBuffer prend également en charge les demandes d’E/S qui n’utilisent ni mise en mémoire tampon ni E/S directes.
Si WdfRequestRetrieveOutputBuffer retourne STATUS_SUCCESS, le pilote reçoit l’adresse et, éventuellement, la taille de la mémoire tampon de sortie.
Le pilote peut accéder à la mémoire tampon récupérée jusqu’à ce qu’il termine la demande d’E/S que représente le paramètre Request .
Au lieu d’appeler WdfRequestRetrieveOutputBuffer, le pilote peut appeler WdfRequestRetrieveOutputMemory, ce qui crée un objet de mémoire framework qui représente la mémoire tampon.
Pour plus d’informations sur WdfRequestRetrieveOutputBuffer, consultez Accès aux mémoires tampons de données dans les pilotes Framework-Based.
Exemples
L’exemple de code suivant fait partie d’une fonction de rappel EvtIoDeviceControl . Cet exemple obtient le descripteur de configuration d’un périphérique USB et place le descripteur dans la mémoire tampon de sortie de la requête d’E/S.
VOID
MyEvtIoDeviceControl(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t OutputBufferLength,
IN size_t InputBufferLength,
IN ULONG IoControlCode
)
{
WDFDEVICE device;
PDEVICE_CONTEXT pDevContext;
size_t bytesReturned = 0;
NTSTATUS status;
device = WdfIoQueueGetDevice(Queue);
//
// GetDeviceContext is a driver-defined function
// to retrieve device object context space.
//
pDevContext = GetDeviceContext(device);
switch(IoControlCode) {
case IOCTL_OSRUSBFX2_GET_CONFIG_DESCRIPTOR: {
PUSB_CONFIGURATION_DESCRIPTOR configurationDescriptor = NULL;
USHORT requiredSize;
//
// First, get the size of the USB configuration descriptor.
//
status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
pDevContext->UsbDevice,
NULL,
&requiredSize
);
if (status == STATUS_BUFFER_TOO_SMALL) {
break;
}
//
// Get the buffer. Make sure the buffer is big
// enough to hold the configuration descriptor.
//
status = WdfRequestRetrieveOutputBuffer(
Request,
(size_t)requiredSize,
&configurationDescriptor,
NULL
);
if(!NT_SUCCESS(status)){
break;
}
//
// Now get the config descriptor.
//
status = WdfUsbTargetDeviceRetrieveConfigDescriptor(
pDevContext->UsbDevice,
configurationDescriptor,
&requiredSize
);
if (!NT_SUCCESS(status)) {
break;
}
bytesReturned = requiredSize;
}
break;
...
(Other case statements removed.)
...
default:
status = STATUS_INVALID_DEVICE_REQUEST;
break;
}
//
// Complete the request.
//
WdfRequestCompleteWithInformation(
Request,
status,
bytesReturned
);
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 | BufAfterReqCompletedIntIoctl(kmdf), BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctl(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedRead(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWrite(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), OutputBufferAPI(kmdf) |