Método IWDFDriver::CreatePreallocatedWdfMemory (wudfddi.h)

Artículo
03/05/2024

[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los controladores UMDF nuevos deben escribirse con UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2. Para obtener más información, consulta Introducción con UMDF.

El método CreatePreallocatedWdfMemory crea un objeto de memoria de marco para el búfer especificado.

Sintaxis

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

Parámetros

[in] pBuff

Puntero a un búfer de datos proporcionado por el controlador para el objeto de memoria.

[in] BufferSize

Tamaño, en bytes, de datos a los que apunta pBuff .

[in, optional] pCallbackInterface

Puntero a la interfaz IUnknown que usa el marco para determinar las funciones de devolución de llamada de eventos relacionadas con objetos a las que se suscribe el controlador en el objeto de memoria recién creado. Este parámetro es opcional. El controlador puede pasar NULL si el controlador no requiere notificación. La interfaz IUnknown se usa para la limpieza y eliminación de objetos. Si el controlador pasa un puntero válido, el marco llamará a QueryInterface en la interfaz IUnknown para la interfaz IObjectCleanup . Si el marco obtiene la interfaz IObjectCleanup del controlador, el marco puede llamar posteriormente al método IObjectCleanup::OnCleanup del controlador para notificar al controlador que se limpia el objeto de memoria.

[in, optional] pParentObject

Puntero a la interfaz IWDFObject del objeto primario del objeto de memoria creado. Si es NULL, el objeto de controlador se convierte en el elemento primario predeterminado.

[out] ppWdfMemory

Puntero a un búfer que recibe un puntero a la interfaz IWDFMemory del objeto de memoria WDF recién creado.

Valor devuelto

CreatePreallocatedWdfMemory devuelve S_OK si la operación se realiza correctamente. De lo contrario, este método devuelve uno de los códigos de error definidos en Winerror.h.

Comentarios

El método CreatePreallocatedWdfMemory crea un objeto de memoria de marco para un búfer que el controlador asignó o obtuvo anteriormente.

Un controlador UMDF puede llamar a CreatePreallocatedWdfMemory si debe crear un objeto de memoria que represente un búfer de memoria preexistente. Por ejemplo, el controlador podría recibir una estructura definida por el controlador dentro de un búfer para una solicitud de E/S que contiene un código de control de E/S interno. El controlador puede llamar a CreatePreallocatedWdfMemory para crear un objeto de memoria para que el controlador pueda pasar la estructura a un destino de E/S.

Después de que un controlador UMDF llame a CreatePreallocatedWdfMemory, el controlador puede llamar a IWDFMemory::SetBuffer para asignar un búfer diferente al objeto de memoria que creó CreatePreallocatedWdfMemory .

Cuando se elimina el objeto de memoria del marco que creó CreatePreallocatedWdfMemory , el marco no desasigna el búfer preexistente. Del mismo modo, una llamada a IWDFMemory::SetBuffer no desasigna el búfer asignado previamente.

Ejemplos

En el ejemplo de código siguiente se muestra cómo crear un objeto de memoria para un búfer.

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

Requisitos

Requisito	Value
Finalización del soporte técnico	No disponible en UMDF 2.0 y versiones posteriores.
Plataforma de destino	Escritorio
Versión mínima de UMDF	1.5
Encabezado	wudfddi.h (incluya Wudfddi.h)
Archivo DLL	WUDFx.dll