Partager via


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 vers un objet de requête de framework.

[in] MinimumRequiredSize

Taille minimale de la mémoire tampon, en octets, que le pilote doit traiter la requête 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 de retour

WdfRequestRetrieveOutputBuffer 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_BUFFER_TOO_SMALL
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.
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_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 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 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, WdfRequestRetrieveOutputBuffer prend également en charge les requêtes d’E/S qui utilisent ni les E/S directes ni les 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’elle termine la requête d’E/S que le paramètre de demande de représente.

Au lieu d’appeler WdfRequestRetrieveOutputBuffer, le pilote peut appeler WdfRequestRetrieveOutputMemory, ce qui crée un objet 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 Framework-Based Drivers.

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;
}

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 BufAfterReqCompletedIntIoctl(kmdf), BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctl(km), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedRead(kmdf), BufAfterReqCompletedReadA (kmdf), BufAfterReqCompletedWrite(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), Non valide, KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), OutputBufferAPI(kmdf)

Voir aussi

WdfRequestRetrieveInputBuffer

WdfRequestRetrieveOutputMemory