Metodo IWDFDriver::CreateWdfMemory (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. Non vengono aggiunte nuove funzionalità 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 info, vedi Introduzione con UMDF.]

Il metodo CreateWdfMemory crea un oggetto memoria del framework e alloca, per l'oggetto memoria, un buffer di dati delle dimensioni diverse da zero specificate.

Sintassi

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

Parametri

[in] BufferSize

Dimensioni non pari a zero specificate, in byte, di dati per il buffer di dati dell'oggetto memoria WDF appena creato.

[in, optional] pCallbackInterface

Puntatore all'interfaccia IUnknown usata dal framework per determinare le funzioni di callback degli eventi correlate agli oggetti sottoscritte dal driver nell'oggetto memoria appena creato. Questo parametro è facoltativo e, Il driver può passare NULL se il driver non richiede una notifica. L'interfaccia IUnknown viene usata per la pulizia e l'eliminazione 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 memoria 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 memoria WDF appena creato.

Valore restituito

CreateWdfMemory 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 CreateWdfMemory alloca un buffer delle dimensioni specificate dal parametro BufferSize e crea un oggetto memoria framework che rappresenta il buffer.

Se è specificato NULL nel parametro pParentObject , l'oggetto driver diventa l'oggetto padre predefinito per l'oggetto memoria appena creato. Se un driver UMDF crea un oggetto memoria utilizzato dal driver con un oggetto dispositivo specifico, un oggetto richiesta o un altro oggetto framework, il driver deve impostare l'oggetto padre dell'oggetto memoria in modo appropriato. Quando l'oggetto padre viene eliminato, l'oggetto memory e il relativo buffer vengono eliminati.

Un driver UMDF può anche eliminare un oggetto memoria e il relativo buffer chiamando IWDFObject::D eleteWdfObject.

Un driver UMDF non può creare un oggetto memoria con un buffer delle dimensioni specificato zero. Se un driver deve usare un buffer delle dimensioni specificato zero, il driver deve usare invece un oggetto memoria NULL . Ad esempio, se il driver deve usare un buffer di dimensioni pari a zero specificato in una richiesta di lettura, il driver deve passare NULL al parametro pOutputMemory in una chiamata al metodo IWDFIoTarget::FormatRequestForRead .

Esempio

Nell'esempio di codice seguente viene illustrato come creare un oggetto memoria in grado di contenere informazioni lette da un endpoint 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;
}

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