Função WdfMemoryCreatePreallocated (wdfmemory.h)
[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 |
|---|---|
|
Um parâmetro inválido foi detectado. |
|
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) |