Função WdfMemoryCreate (wdfmemory.h)

[Aplica-se a KMDF e UMDF]

O método WdfMemoryCreate cria um objeto de memória de estrutura e aloca um buffer de memória de um tamanho especificado.

Sintaxe

NTSTATUS WdfMemoryCreate(
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]            POOL_TYPE              PoolType,
  [in, optional]  ULONG                  PoolTag,
  [in]            size_t                 BufferSize,
  [out]           WDFMEMORY              *Memory,
  [out, optional] PVOID                  *Buffer
);

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] PoolType

Um valor do tipo POOL_TYPE que especifica o tipo de memória a ser alocada.

[in, optional] PoolTag

Uma marca de pool definida pelo driver para a memória alocada. Os depuradores exibem essa marca. Os drivers normalmente especificam uma cadeia de caracteres de até quatro caracteres, delimitada por aspas simples, em ordem inversa (por exemplo, 'dcba'). O valor ASCII de cada caractere na marca deve estar entre 0 e 127. A depuração do driver será mais fácil se cada marca de pool for exclusiva.

Se PoolTag for zero, a estrutura fornecerá uma marca de pool padrão que usa os quatro primeiros caracteres do nome do serviço do modo kernel do driver. Se o nome do serviço começar com "WDF" (o nome não diferencia maiúsculas de minúsculas e não inclui as aspas), os próximos quatro caracteres serão usados. Se menos de quatro caracteres estiverem disponíveis, "FxDr" será usado.

Para as versões 1.5 e posteriores do KMDF, o driver pode usar o membro DriverPoolTag da estrutura WDF_DRIVER_CONFIG para especificar uma marca de pool padrão.

[in] BufferSize

O tamanho especificado diferente de zero, em bytes, do buffer.

[out] Memory

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

[out, optional] Buffer

Um ponteiro para um local que recebe um ponteiro para o buffer associado ao novo objeto de memória. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

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

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

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

Comentários

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

Para obter o endereço do buffer, o driver pode fornecer um valor não NULL para o parâmetro Buffer da função WdfMemoryCreate ou o driver pode chamar WdfMemoryGetBuffer.

É uma boa prática zero memória para alocação de memória, especialmente para alocações que serão copiadas para um local não confiável (modo de usuário, pela rede etc.) para evitar a divulgação de informações confidenciais. WdfMemoryCreate não inicializa a memória alocada por padrão.

Com base no padrão de uso do driver da memória alocada, a recomendação para gravadores de driver é considerar:

• RtlZeroMemory imediatamente após chamar WdfMemoryCreate
• Ou use uma API de alocação zero (ExAllocatePool2, ExAllocatePoolZero para o modo kernel; HeapAlloc com o sinalizador HEAP_ZERO_MEMORY para o modo de usuário), seguido por WdfMemoryCreatePreallocated. Como o buffer pré-alocado não é excluído automaticamente como parte do WDFMEMORY ou sua exclusão pai, essa não é a melhor abordagem.

O objeto pai padrão para cada objeto de memória é o objeto de driver de estrutura que representa o driver chamado WdfMemoryCreate. 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 e seu buffer serão excluídos quando o objeto pai for excluído. Se você não alterar o objeto pai padrão, o objeto de memória e seu buffer permanecerão até que o gerenciador de E/S descarregue o driver.

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

Se BufferSize for menor que PAGE_SIZE, o sistema operacional fornecerá ao chamador exatamente o número de bytes de memória solicitados. O buffer não é necessariamente alinhado à página, mas é alinhado pelo número de bytes que a constante MEMORY_ALLOCATION_ALIGNMENT especifica em Ntdef.h.

Se BufferSize for PAGE_SIZE ou superior, para KMDF apenas o sistema alocará um buffer alinhado à página. Se o parâmetro PoolType for NonPagedPool, o sistema alocará o número de páginas necessárias para manter todos os bytes. Todos os bytes não utilizados na última página alocada são essencialmente desperdiçados.

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

Se o driver especificar PagedPool para PoolType, o método WdfMemoryCreate deverá ser chamado em IRQL <= APC_LEVEL. Caso contrário, o método pode ser chamado em IRQL <= DISPATCH_LEVEL.

Exemplos

O exemplo de código a seguir cria um objeto de memória de estrutura e aloca um buffer cujo tamanho é WRITE_BUFFER_SIZE. O pai do objeto de memória é um objeto de solicitação.

NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  attributes;
WDFMEMORY  writeBufferMemHandle;
PVOID  writeBufferPointer;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         0,
                         WRITE_BUFFER_SIZE,
                         &writeBufferMemHandle,
                         &writeBufferPointer
                         );

Requisitos

Confira também

POOL_TYPE

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WdfMemoryCreateFromLookaside

WdfMemoryCreatePreallocated

WdfMemoryGetBuffer

WdfObjectDelete