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

Artigo
08/08/2023

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Drivers universais do Windows devem usar UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

O método CreateWdfMemory cria um objeto de memória de estrutura e aloca, para o objeto de memória, um buffer de dados do tamanho diferente de zero especificado.

Sintaxe

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

Parâmetros

[in] BufferSize

O tamanho especificado diferente de zero, em bytes, dos dados para o buffer de dados do objeto de memória WDF recém-criado.

[in, optional] pCallbackInterface

Um ponteiro para a interface IUnknown que a estrutura usa para determinar as funções de retorno de chamada de evento relacionadas ao objeto que o driver assina no objeto de memória recém-criado. Esse parâmetro é opcional. O driver poderá passar NULL se o driver não exigir notificação. A interface IUnknown é usada para limpeza e descarte de objetos. Se o driver passar um ponteiro válido, a estrutura chamará QueryInterface na interface IUnknown para a interface IObjectCleanup . Se a estrutura obtiver a interface IObjectCleanup do driver, a estrutura poderá chamar posteriormente o método IObjectCleanup::OnCleanup do driver para notificar o driver de que o objeto de memória foi limpo.

[in, optional] pParentObject

Um ponteiro para a interface IWDFObject para o objeto pai do objeto de memória criado. Se FOR NULL, o objeto de driver se tornará o pai padrão.

[out] ppWdfMemory

Um ponteiro para um buffer que recebe um ponteiro para a interface IWDFMemory para o objeto de memória WDF recém-criado.

Retornar valor

CreateWdfMemory retornará S_OK se a operação for bem-sucedida. Caso contrário, esse método retornará um dos códigos de erro definidos em Winerror.h.

Comentários

O método CreateWdfMemory aloca um buffer do tamanho especificado pelo parâmetro BufferSize e cria um objeto de memória de estrutura que representa o buffer.

Se NULL for especificado no parâmetro pParentObject , o objeto driver se tornará o objeto pai padrão para o objeto de memória recém-criado. Se um driver UMDF criar um objeto de memória que o driver usa com um objeto de dispositivo específico, objeto de solicitação ou outro objeto de estrutura, o driver deverá definir o objeto pai do objeto de memória adequadamente. Quando o objeto pai é excluído, o objeto de memória e seu buffer são excluídos.

Um driver UMDF também pode excluir um objeto de memória e seu buffer chamando IWDFObject::D eleteWdfObject.

Um driver UMDF não pode criar um objeto de memória com um buffer de tamanho zero especificado. Se um driver precisar usar um buffer de tamanho zero especificado, o driver deverá usar um objeto de memória NULL . Por exemplo, se o driver precisar usar um buffer de tamanho zero especificado em uma solicitação de leitura, o driver deverá passar NULL para o parâmetro pOutputMemory em uma chamada para o método IWDFIoTarget::FormatRequestForRead .

Exemplos

O exemplo de código a seguir mostra como criar um objeto de memória que pode conter informações lidas de um ponto de extremidade 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	Valor
Fim do suporte	Indisponível no UMDF 2.0 e posterior.
Plataforma de Destino	Área de Trabalho
Versão mínima do UMDF	1.5
Cabeçalho	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll