IWDFDriver::CreateWdfMemory-Methode (wudfddi.h)

Artikel
02/27/2024

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 in neueren Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die CreateWdfMemory-Methode erstellt ein Frameworkspeicherobjekt und weist für das Speicherobjekt einen Datenpuffer der angegebenen Größe ungleich null zu.

Syntax

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

Parameter

[in] BufferSize

Die angegebene Größe der Daten für den datenpuffer des neu erstellten WDF-Speicherobjekts ungleich 0 (in Bytes).

[in, optional] pCallbackInterface

Ein Zeiger auf die IUnknown-Schnittstelle , mit der das Framework die objektbezogenen Ereignisrückruffunktionen bestimmt, die der Treiber für das neu erstellte Speicherobjekt abonniert. Dieser Parameter ist optional. Der Treiber kann NULL übergeben, wenn der Treiber keine Benachrichtigung benötigt. Die IUnknown-Schnittstelle wird für die Objektbereinigung und -entsorgung verwendet. Wenn der Treiber einen gültigen Zeiger übergibt, ruft das Framework QueryInterface auf der IUnknown-Schnittstelle für die IObjectCleanup-Schnittstelle auf . Wenn das Framework die IObjectCleanup-Schnittstelle des Treibers abruft, kann das Framework anschließend die IObjectCleanup::OnCleanup-Methode des Treibers aufrufen, um den Treiber darüber zu informieren, dass das Speicherobjekt bereinigt wurde.

[in, optional] pParentObject

Ein Zeiger auf die IWDFObject-Schnittstelle für das übergeordnete Objekt des erstellten Speicherobjekts. Bei NULL wird das Treiberobjekt zum übergeordneten Standardobjekt.

[out] ppWdfMemory

Ein Zeiger auf einen Puffer, der einen Zeiger auf die IWDFMemory-Schnittstelle für das neu erstellte WDF-Speicherobjekt empfängt.

Rückgabewert

CreateWdfMemory gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode einen der Fehlercodes zurück, die in Winerror.h definiert sind.

Hinweise

Die CreateWdfMemory-Methode ordnet einen Puffer der Größe zu, die der BufferSize-Parameter angibt, und erstellt ein Frameworkspeicherobjekt, das den Puffer darstellt.

Wenn NULL im pParentObject-Parameter angegeben ist, wird das Treiberobjekt zum übergeordneten Standardobjekt für das neu erstellte Speicherobjekt. Wenn ein UMDF-Treiber ein Speicherobjekt erstellt, das der Treiber mit einem bestimmten Geräteobjekt, Anforderungsobjekt oder einem anderen Frameworkobjekt verwendet, sollte der Treiber das übergeordnete Objekt des Speicherobjekts entsprechend festlegen. Wenn das übergeordnete Objekt gelöscht wird, werden das Speicherobjekt und sein Puffer gelöscht.

Ein UMDF-Treiber kann auch ein Speicherobjekt und seinen Puffer löschen, indem er IWDFObject::D eleteWdfObject aufruft.

Ein UMDF-Treiber kann kein Speicherobjekt mit einem null angegebenen Größenpuffer erstellen. Wenn ein Treiber einen null-angegebenen Größenpuffer verwenden muss, sollte der Treiber stattdessen ein NULL-Speicherobjekt verwenden. Wenn der Treiber beispielsweise einen Null-angegebenen Größenpuffer in einer Leseanforderung verwenden muss, muss der Treiber NULL an den pOutputMemory-Parameter in einem Aufruf der IWDFIoTarget::FormatRequestForRead-Methode übergeben.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie ein Speicherobjekt erstellen, das Informationen enthalten kann, die von einem USB-Endpunkt gelesen werden.

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

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform	Desktop
UMDF-Mindestversion	1.5
Kopfzeile	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll