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

Article
02/27/2024

[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 RetrieveOutputMemory récupère l’interface IWDFMemory d’un objet mémoire framework qui représente la mémoire tampon de sortie d’une requête d’E/S.

Syntaxe

HRESULT RetrieveOutputMemory(
  [out] IWDFMemory **Memory
);

Paramètres

[out] Memory

Adresse d’un emplacement qui reçoit un pointeur vers l’interface IWDFMemory d’un objet mémoire UMDF.

Valeur retournée

RetrieveOutputMemory 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 d’entrée.
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 valeur d’erreur status.

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 les données d’un disque, que le pilote fournit à l’initiateur de la demande. Votre pilote peut appeler RetrieveOutputMemory 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 RetrieveOutputMemory 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 d’E/S directe pour accéder aux mémoires tampons de données.

Si RetrieveOutputMemory retourne S_OK, le pilote reçoit un pointeur vers l’interface IWDFMemory d’un objet mémoire UMDF qui représente la mémoire tampon de sortie. Pour accéder à la mémoire tampon, le pilote doit appeler IWDFMemory ::GetDataBuffer.

Le pilote peut accéder à l’objet mémoire du framework récupéré jusqu’à ce qu’il termine la demande d’E/S. Avant que le pilote termine la demande d’E/S, il doit appeler IWDFMemory ::Release.

Au lieu d’appeler RetrieveOutputMemory, le pilote peut appeler IWDFIoRequest2 ::RetrieveOutputBuffer, qui récupère l’adresse et la longueur de 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 comment une fonction de rappel IQueueCallbackRead ::OnRead peut obtenir l’interface IWDFMemory de l’objet de mémoire 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
STDMETHODCALLTYPE
  CMyQueue::OnRead(
     __in IWDFIoQueue *pWdfQueue,
     __in IWDFIoRequest *pWdfRequest,
     __in SIZE_T BytesToRead
     )
{
    HRESULT hr = S_OK;
    IWDFMemory * pOutputMemory = NULL;

    //
    // Declare an IWDFIoRequest2 interface pointer and obtain the
    // IWDFIoRequest2 interface from the IWDFIoRequest interface.
    //
    CComQIPtr<IWDFIoRequest2> r2 = pWdfRequest;

    r2->RetrieveOutputMemory(&pOutputMemory);
    if (FAILED(hr)) goto Exit;

    hr = m_Device->GetInputPipe()->FormatRequestForRead(pWdfRequest,
                                                        NULL,
                                                        pOutputMemory,
                                                        NULL,
                                                        NULL);
Exit:
    if (FAILED(hr))
    {
        pWdfRequest->Complete(hr);
    }
    else
    {
        ForwardFormattedRequest(pWdfRequest, m_Device->GetInputPipe());
    }
    SAFE_RELEASE(pOutputMemory);
    return;
}

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