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

Artículo
08/08/2023

[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 CreateWdfMemory crea un objeto de memoria de marco y asigna, para el objeto de memoria, un búfer de datos del tamaño distinto de cero especificado.

Sintaxis

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

Parámetros

[in] BufferSize

Tamaño distinto de cero especificado, en bytes, de datos para el búfer de datos del objeto de memoria WDF recién creado.

[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

CreateWdfMemory 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 CreateWdfMemory asigna un búfer del tamaño que especifica el parámetro BufferSize y crea un objeto de memoria de marco que representa el búfer.

Si se especifica NULL en el parámetro pParentObject , el objeto de controlador se convierte en el objeto primario predeterminado para el objeto de memoria recién creado. Si un controlador UMDF crea un objeto de memoria que el controlador usa con un objeto de dispositivo específico, un objeto de solicitud u otro objeto de marco, el controlador debe establecer el objeto primario del objeto de memoria de forma adecuada. Cuando se elimina el objeto primario, se eliminan el objeto de memoria y su búfer.

Un controlador UMDF también puede eliminar un objeto de memoria y su búfer llamando a IWDFObject::D eleteWdfObject.

Un controlador UMDF no puede crear un objeto de memoria con un búfer de tamaño especificado por cero. Si un controlador debe usar un búfer de tamaño especificado con cero, el controlador debe usar un objeto de memoria NULL en su lugar. Por ejemplo, si el controlador debe usar un búfer de tamaño especificado con cero en una solicitud de lectura, el controlador debe pasar NULL al parámetro pOutputMemory en una llamada al método IWDFIoTarget::FormatRequestForRead .

Ejemplos

En el ejemplo de código siguiente se muestra cómo crear un objeto de memoria que puede contener información que se lee desde un punto de conexión 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;
}

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