Méthode IWDFIoRequest2 ::RetrieveOutputBuffer (wudfddi.h)

Article
08/08/2023

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La méthode RequestRetrieveOutputBuffer récupère la mémoire tampon de sortie d’une requête d’E/S.

Syntaxe

HRESULT RetrieveOutputBuffer(
  [in]            SIZE_T MinimumRequiredCb,
  [out]           PVOID  *Buffer,
  [out, optional] SIZE_T *BufferCb
);

Paramètres

[in] MinimumRequiredCb

Taille de mémoire tampon minimale, en octets, dont le pilote a besoin pour traiter la demande d’E/S. Cette valeur peut être égale à zéro s’il n’y a pas de taille de mémoire tampon minimale.

[out] Buffer

Pointeur vers un emplacement qui reçoit l’adresse de la mémoire tampon.

[out, optional] BufferCb

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

RequestRetrieveOutputBuffer retourne S_OK si l’opération réussit. Sinon, cette méthode peut retourner la valeur suivante :

Code de retour	Description
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	La demande d’E/S n’a pas fourni de mémoire tampon de sortie, ou la taille de la mémoire tampon de sortie est inférieure à la taille minimale spécifiée par MinimumRequiredCb .
E_OUTOFMEMORY	La mémoire disponible est insuffisante pour récupérer la mémoire tampon. Le pilote doit terminer la requête avec une erreur status valeur.

Cette méthode peut retourner l’une des autres valeurs que Winerror.h contient.

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 RequestRetrieveOutputBuffer 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 RequestRetrieveOutputBuffer récupère la mémoire tampon de sortie pour les demandes d’E/S qui utilisent la méthode d’E/S en mémoire tampon ou d’E/S directes pour accéder aux mémoires tampons de données.

Si RequestRetrieveOutputBuffer retourne S_OK, 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.

Au lieu d’appeler RequestRetrieveOutputBuffer, le pilote peut appeler IWDFIoRequest2 ::RetrieveOutputMemory, ce qui crée un objet de mémoire framework qui représente la mémoire tampon.

Pour plus d’informations sur l’accès aux mémoires tampons de données d’une demande d’E/S, consultez Accès aux mémoires tampons de données dans les pilotes UMDF-Based.

Exemples

L’exemple de code suivant montre un segment de la fonction de rappel IQueueCallbackDeviceIoControl ::OnDeviceIoControl d’un pilote de port série. Le segment de code obtient la mémoire tampon de sortie de la demande d’E/S, puis transfère les informations de débit en bauds de l’appareil vers la mémoire tampon.

VOID
STDMETHODCALLTYPE
  CMyQueue::OnDeviceIoControl(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in ULONG ControlCode,
    __in SIZE_T InputBufferSizeInBytes,
    __in SIZE_T OutputBufferSizeInBytes
    )
{
    HRESULT hr;
    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    switch (ControlCode)
    {
        case IOCTL_SERIAL_GET_BAUD_RATE:
        {
            SERIAL_BAUD_RATE *pBaudRateBuffer;
            hr = pWdfRequest2->RetrieveOutputBuffer(sizeof(SERIAL_BAUD_RATE),
                                                    (PVOID*) &pBaudRateBuffer,
                                                    NULL);
            if (SUCCEEDED(hr))
                  {
                      RtlZeroMemory(pBaudRateBuffer, sizeof(SERIAL_BAUD_RATE));
                      pBaudRateBuffer->BaudRate = m_Device->GetBaudRate();
                      reqCompletionInfo = sizeof(SERIAL_BAUD_RATE);
                  }
            
        }
        break;
        ...
    }
    ...
}

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1,9
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll