Méthode IWDFDriver ::CreatePreallocatedWdfMemory (wudfddi.h)

Article
03/05/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 CreatePreallocatedWdfMemory crée un objet de mémoire d’infrastructure pour la mémoire tampon spécifiée.

Syntaxe

HRESULT CreatePreallocatedWdfMemory(
  [in]           BYTE       *pBuff,
  [in]           SIZE_T     BufferSize,
  [in, optional] IUnknown   *pCallbackInterface,
  [in, optional] IWDFObject *pParentObject,
  [out]          IWDFMemory **ppWdfMemory
);

Paramètres

[in] pBuff

Pointeur vers une mémoire tampon de données fournie par le pilote pour l’objet mémoire.

[in] BufferSize

Taille, en octets, des données vers laquelle pointe pBuff .

[in, optional] pCallbackInterface

Pointeur vers l’interface IUnknown que le framework utilise pour déterminer les fonctions de rappel d’événement liées à l’objet auxquelles le pilote s’abonne sur l’objet mémoire nouvellement créé. Ce paramètre est facultatif. Le pilote peut passer la valeur NULL si le pilote ne nécessite pas de notification. L’interface IUnknown est utilisée pour le nettoyage et la suppression d’objets. Si le pilote transmet un pointeur valide, l’infrastructure appelle QueryInterface sur l’interface IUnknown pour l’interface IObjectCleanup . Si l’infrastructure obtient l’interface IObjectCleanup du pilote, l’infrastructure peut ensuite appeler la méthode IObjectCleanup ::OnCleanup du pilote pour informer le pilote que l’objet mémoire est nettoyé.

[in, optional] pParentObject

Pointeur vers l’interface IWDFObject pour l’objet parent de l’objet mémoire créé. Si la valeur est NULL, l’objet driver devient le parent par défaut.

[out] ppWdfMemory

Pointeur vers une mémoire tampon qui reçoit un pointeur vers l’interface IWDFMemory pour l’objet mémoire WDF nouvellement créé.

Valeur retournée

CreatePreallocatedWdfMemory retourne S_OK si l’opération réussit. Sinon, cette méthode retourne l’un des codes d’erreur définis dans Winerror.h.

Remarques

La méthode CreatePreallocatedWdfMemory crée un objet de mémoire d’infrastructure pour une mémoire tampon que le pilote a précédemment allouée ou obtenue.

Un pilote UMDF peut appeler CreatePreallocatedWdfMemory s’il doit créer un objet mémoire qui représente une mémoire tampon préexistante. Par exemple, le pilote peut recevoir une structure définie par le pilote dans une mémoire tampon pour une demande d’E/S qui contient un code de contrôle d’E/S interne. Le pilote peut appeler CreatePreallocatedWdfMemory pour créer un objet mémoire afin que le pilote puisse passer la structure à une cible d’E/S.

Après qu’un pilote UMDF appelle CreatePreallocatedWdfMemory, le pilote peut appeler IWDFMemory ::SetBuffer pour affecter une mémoire tampon différente à l’objet mémoire créé par CreatePreallocatedWdfMemory .

Lorsque l’objet de mémoire du framework créé par CreatePreallocatedWdfMemory est supprimé, l’infrastructure ne libère pas la mémoire tampon préexistante. De même, un appel à IWDFMemory ::SetBuffer ne libère pas la mémoire tampon précédemment affectée.

Exemples

L’exemple de code suivant montre comment créer un objet mémoire pour une mémoire tampon.

    //
    // Allocate a request.
    hr = wdfDevice->CreateRequest(NULL, NULL, &request);

    // Allocate a buffer and wrap it in a memory object. 
    // Make the memory object a child of the request. 
    // When the request object is deleted, the memory object 
    // is also deleted. 

    if (SUCCEEDED(hr))
    {
       buffer = new BYTE[m_HidDescriptor->wReportLength];

       if (buffer == NULL)
       {
          hr = E_OUTOFMEMORY;
       }
    }

    if (SUCCEEDED(hr))
    {
       CComPtr<IWDFDriver> driver;
       wdfDevice->GetDriver(&driver);

       hr = driver->CreatePreallocatedWdfMemory(
                       buffer,
                       m_HidDescriptor->wReportLength,
                       NULL,
                       request,
                       &memory
                       );
    }

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.5
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll