IWDFDriver ::CreateWdfMemory, méthode (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 CreateWdfMemory crée un objet de mémoire framework et alloue, pour l’objet mémoire, une mémoire tampon de données de la taille différente de zéro spécifiée.

Syntaxe

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

Paramètres

[in] BufferSize

Taille différente de zéro spécifiée, en octets, des données pour la mémoire tampon de données de l’objet mémoire WDF nouvellement créée.

[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

CreateWdfMemory 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 CreateWdfMemory alloue une mémoire tampon de la taille spécifiée par le paramètre BufferSize et crée un objet mémoire d’infrastructure qui représente la mémoire tampon.

Si NULL est spécifié dans le paramètre pParentObject , l’objet driver devient l’objet parent par défaut pour l’objet mémoire nouvellement créé. Si un pilote UMDF crée un objet mémoire qu’il utilise avec un objet de périphérique, un objet de requête ou un autre objet framework spécifique, le pilote doit définir l’objet parent de l’objet mémoire de manière appropriée. Lorsque l’objet parent est supprimé, l’objet mémoire et sa mémoire tampon sont supprimés.

Un pilote UMDF peut également supprimer un objet mémoire et sa mémoire tampon en appelant IWDFObject ::D eleteWdfObject.

Un pilote UMDF ne peut pas créer un objet mémoire avec une mémoire tampon de taille zéro spécifiée. Si un pilote doit utiliser une mémoire tampon de taille zéro spécifiée, le pilote doit utiliser un objet de mémoire NULL à la place. Par exemple, si le pilote doit utiliser une mémoire tampon de taille zéro spécifiée dans une demande de lecture, le pilote doit passer NULL au paramètre pOutputMemory dans un appel à la méthode IWDFIoTarget ::FormatRequestForRead .

Exemples

L’exemple de code suivant montre comment créer un objet mémoire pouvant contenir des informations lues à partir d’un point de terminaison USB.

HRESULT
CUmdfHidDevice::PrepareReader(
    VOID
    )
{
    CComPtr<IWDFDevice> wdfDevice;
    CComPtr<IWDFDriver> wdfDriver;
    CComPtr<IWDFIoRequest> wdfRequest;

    HRESULT hr;

    GetWdfDevice(&wdfDevice);
    wdfDevice->GetDriver(&wdfDriver);

    // Open the interrupt pipe.
    hr = m_HidInterface->RetrieveUsbPipeObject(
                         USB_HID_INTERRUPT_PIPE_INDEX,
                         &m_InterruptPipe
                         );

    // Allocate a memory object to hold information that 
    // is read from the interrupt pipe. 
    // This memory object will be reused.
    if (SUCCEEDED(hr))
    {
        hr = wdfDriver->CreateWdfMemory(m_ReadBufferSize,
                                        NULL,
                                        wdfDevice,
                                        &m_ReadMemory);
    }

    return hr;
}

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