Função WdfMemoryCreatePreallocated (wdfmemory.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfMemoryCreatePreallocated cria um objeto de memória de estrutura para um buffer de memória fornecido pelo driver.

Sintaxe

NTSTATUS WdfMemoryCreatePreallocated(
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]           __drv_aliasesMem PVOID Buffer,
  [in]           size_t                 BufferSize,
  [out]          WDFMEMORY              *Memory
);

Parâmetros

[in, optional] Attributes

Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que contém atributos de objeto para o novo objeto de memória. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[in] Buffer

Um ponteiro para um buffer fornecido pelo driver.

[in] BufferSize

O tamanho diferente de zero, em bytes, do buffer para o qual o Buffer aponta.

[out] Memory

Um ponteiro para um local que recebe um identificador para o novo objeto de memória.

Retornar valor

WdfMemoryCreatePreallocated retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_INSUFFICIENT_RESOURCES	Não havia memória suficiente.

Para obter uma lista de outros valores retornados que o método WdfMemoryCreatePreallocated pode retornar, consulte Erros de criação de objeto de estrutura.

Esse método também pode retornar outros valores NTSTATUS.

Comentários

O método WdfMemoryCreatePreallocated cria um objeto de memória de estrutura para um buffer que o driver alocou ou obteve anteriormente.

Seu driver poderá chamar WdfMemoryCreatePreallocated se você precisar criar objetos de memória que representem buffers de memória pré-existentes. Por exemplo, o driver pode receber uma estrutura definida pelo driver dentro de um buffer para uma solicitação de E/S que contém um código de controle de E/S interno. O driver pode chamar WdfMemoryCreatePreallocated para criar um objeto de memória para que o driver possa passar a estrutura para um destino de E/S.

Depois que um driver tiver chamado WdfMemoryCreatePreallocated, o driver poderá chamar WdfMemoryAssignBuffer para atribuir um buffer diferente ao objeto de memória que WdfMemoryCreatePreallocated criou.

O objeto pai padrão para cada objeto de memória é o objeto de driver de estrutura que representa o driver chamado WdfMemoryCreatePreallocated. Se o driver criar um objeto de memória que ele usa com um objeto de dispositivo específico, objeto de solicitação ou outro objeto de estrutura, ele deverá definir o pai do objeto de memória adequadamente. O objeto de memória será excluído quando o objeto pai for excluído. Se você não alterar o objeto pai padrão, o objeto de memória permanecerá na memória até que o gerenciador de E/S descarregue o driver.

Um driver também pode excluir um objeto de memória chamando WdfObjectDelete.

Quando o objeto de memória da estrutura que WdfMemoryCreatePreallocated criou é excluído, a estrutura não desaloca o buffer pré-existente. Da mesma forma, uma chamada para WdfMemoryAssignBuffer não desaloca o buffer atribuído anteriormente.

Para obter mais informações sobre objetos de memória de estrutura, consulte Usando buffers de memória.

Exemplos

O exemplo de código a seguir aloca um buffer e cria um objeto de memória de estrutura para o buffer.

PVOID  pBuffer = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;
WDFMEMORY  memHandle;

pBuffer = ExAllocatePoolWithTag(
                                NonPagedPool,
                                MY_BUFFER_SIZE,
                                MY_DRIVER_TAG
                                );
if (pBuffer == NULL){
    goto Error;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;

status = WdfMemoryCreatePreallocated(
                                     &attributes,
                                     pBuffer,
                                     MY_BUFFER_SIZE,
                                     &memHandle
                                     );

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfmemory.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade da DDI	BufAfterReqCompletedIntIoctlA(kmdf), BufAfterReqCompletedIoctlA(kmdf), BufAfterReqCompletedReadA(kmdf), BufAfterReqCompletedWriteA(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)