IWDFDriver::CreatePreallocatedWdfMemory-Methode (wudfddi.h)

[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 für neuere 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 CreatePreallocatedWdfMemory-Methode erstellt ein Frameworkspeicherobjekt für den angegebenen Puffer.

Syntax

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

Parameter

[in] pBuff

Ein Zeiger auf einen vom Treiber bereitgestellten Datenpuffer für das Speicherobjekt.

[in] BufferSize

Die Größe der Daten, auf die pBuff verweist.

[in, optional] pCallbackInterface

Ein Zeiger auf die IUnknown-Schnittstelle , die das Framework verwendet, um die objektbezogenen Ereignisrückruffunktionen zu bestimmen, die der Treiber für das neu erstellte Speicherobjekt abonniert. Dieser Parameter ist optional. Der Treiber kann NULL übergeben, wenn der Treiber keine Benachrichtigung erfordert. 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 wird.

[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

CreatePreallocatedWdfMemory 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 CreatePreallocatedWdfMemory-Methode erstellt ein Frameworkspeicherobjekt für einen Puffer, den der Treiber zuvor zugewiesen oder abgerufen hat.

Ein UMDF-Treiber kann CreatePreallocatedWdfMemory aufrufen, wenn er ein Speicherobjekt erstellen muss, das einen bereits vorhandenen Speicherpuffer darstellt. Beispielsweise kann der Treiber eine vom Treiber definierte Struktur innerhalb eines Puffers für eine E/A-Anforderung empfangen, die einen internen E/A-Steuerungscode enthält. Der Treiber kann CreatePreallocatedWdfMemory aufrufen, um ein Speicherobjekt zu erstellen, damit der Treiber die Struktur an ein E/A-Ziel übergeben kann.

Nachdem ein UMDF-Treiber CreatePreallocatedWdfMemory aufgerufen hat, kann der Treiber IWDFMemory::SetBuffer aufrufen, um dem von CreatePreallocatedWdfMemory erstellten Speicherobjekt einen anderen Puffer zuzuweisen.

Wenn das Von CreatePreallocatedWdfMemory erstellte Frameworkspeicherobjekt gelöscht wird, wird der bereits vorhandene Puffer nicht vom Framework zugeordnet. Ebenso wird bei einem Aufruf von IWDFMemory::SetBuffer die Zuordnung des zuvor zugewiesenen Puffers nicht aufgehoben.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie ein Speicherobjekt für einen Puffer erstellen.

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

Anforderungen

Weitere Informationen

IObjectCleanup

IObjectCleanup::OnCleanup

IWDFDriver

IWDFMemory

IWDFMemory::SetBuffer

IWDFObject