Metodo IWDFDriver::CreatePreallocatedWdfMemory (wudfddi.h)

Articolo
03/05/2024

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Nessuna nuova funzionalità viene aggiunta a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre informazioni, vedere Introduzione con UMDF.]

Il metodo CreatePreallocatedWdfMemory crea un oggetto memoria framework per il buffer specificato.

Sintassi

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

Parametri

[in] pBuff

Puntatore a un buffer di dati fornito dal driver per l'oggetto memory.

[in] BufferSize

Dimensioni, in byte, di dati a cui punta pBuff .

[in, optional] pCallbackInterface

Puntatore all'interfaccia IUnknown usata dal framework per determinare le funzioni di callback degli eventi correlate all'oggetto che il driver sottoscrive nell'oggetto memoria appena creato. Questo parametro è facoltativo e, Il driver può passare NULL se il driver non richiede la notifica. L'interfaccia IUnknown viene usata per la pulizia e lo smaltimento degli oggetti. Se il driver passa un puntatore valido, il framework chiamerà QueryInterface nell'interfaccia IUnknown per l'interfaccia IObjectCleanup . Se il framework ottiene l'interfaccia IObjectCleanup del driver, il framework può successivamente chiamare il metodo IObjectCleanup::OnCleanup del driver per notificare al driver che l'oggetto memoria viene pulito.

[in, optional] pParentObject

Puntatore all'interfaccia IWDFObject per l'oggetto padre dell'oggetto memory creato. Se NULL, l'oggetto driver diventa l'elemento padre predefinito.

[out] ppWdfMemory

Puntatore a un buffer che riceve un puntatore all'interfaccia IWDFMemory per l'oggetto di memoria WDF appena creato.

Valore restituito

CreatePreallocatedWdfMemory restituisce S_OK se l'operazione ha esito positivo. In caso contrario, questo metodo restituisce uno dei codici di errore definiti in Winerror.h.

Commenti

Il metodo CreatePreallocatedWdfMemory crea un oggetto memoria del framework per un buffer allocato o ottenuto in precedenza dal driver.

Un driver UMDF può chiamare CreatePreallocatedWdfMemory se deve creare un oggetto memoria che rappresenta un buffer di memoria preesistente. Ad esempio, il driver potrebbe ricevere una struttura definita dal driver all'interno di un buffer per una richiesta di I/O contenente un codice di controllo I/O interno. Il driver può chiamare CreatePreallocatedWdfMemory per creare un oggetto memoria in modo che il driver possa passare la struttura a una destinazione di I/O.

Dopo che un driver UMDF chiama CreatePreallocatedWdfMemory, il driver può chiamare IWDFMemory::SetBuffer per assegnare un buffer diverso all'oggetto memoria creato da CreatePreallocatedWdfMemory .

Quando l'oggetto memoria del framework creato da CreatePreallocatedWdfMemory viene eliminato, il framework non dealloca il buffer preesistente. Analogamente, una chiamata a IWDFMemory::SetBuffer non dealloca il buffer assegnato in precedenza.

Esempio

Nell'esempio di codice seguente viene illustrato come creare un oggetto memoria per un buffer.

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

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1.5
Intestazione	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll