Função WdfObjectAllocateContext (wdfobject.h)
[Aplica-se a KMDF e UMDF]
O método WdfObjectAllocateContext aloca espaço de contexto para um objeto de estrutura especificado.
Sintaxe
NTSTATUS WdfObjectAllocateContext(
[in] WDFOBJECT Handle,
[in] PWDF_OBJECT_ATTRIBUTES ContextAttributes,
[out] PVOID *Context
);
Parâmetros
[in] Handle
Um identificador para um objeto de estrutura.
[in] ContextAttributes
Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES fornecida pelo chamador que descreve o espaço de contexto.
[out] Context
Um ponteiro para um local que recebe um ponteiro para o espaço de contexto alocado.
Retornar valor
WdfObjectAllocateContext 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. |
|
O membro ContextTypeInfo da estrutura WDF_OBJECT_ATTRIBUTES especificada pelo parâmetro ContextAttributes era inválido. |
|
Não foi possível alocar espaço de contexto. |
|
O driver já alocou espaço de contexto que corresponde ao membro ContextTypeInfo da estrutura WDF_OBJECT_ATTRIBUTES especificada por ContextAttributes . Nessa situação, o ponteiro no parâmetro Context recebe um ponteiro para o espaço de contexto existente e não aloca espaço de contexto duplicado. |
|
O objeto que o parâmetro Handle especifica está sendo excluído. Nessa situação, a estrutura não aloca espaço de contexto. |
Esse método também pode retornar outros valores NTSTATUS.
Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.
Comentários
Normalmente, os drivers criam espaço de contexto de objeto especificando uma estrutura WDF_OBJECT_ATTRIBUTES quando chamam o método de criação de um objeto de estrutura, como WdfDeviceCreate.
Se você quiser que o driver aloque mais de um tipo de espaço de contexto para alguns de seus objetos, o driver poderá chamar WdfObjectAllocateContext uma ou mais vezes depois de ter chamado o método de criação de um objeto. Cada chamada para WdfObjectAllocateContext deve especificar um tipo de contexto diferente. (O membro ContextTypeInfo da estrutura WDF_OBJECT_ATTRIBUTES identifica o tipo de contexto.)
Se o driver chamar WdfObjectAllocateContext mais de uma vez para um determinado objeto, você poderá fornecer funções separadas de retorno de chamada EvtCleanupCallback e EvtDestroyCallback para cada contexto.
Ao chamar WdfObjectAllocateContext, não especifique um ParentObject na estrutura WDF_OBJECT_ATTRIBUTES .
Quando a estrutura aloca espaço de contexto para um objeto, ela também inicializa zero o espaço de contexto.
Para obter mais informações sobre o espaço de contexto do objeto, consulte Espaço de contexto do objeto framework.
Para obter mais informações sobre as regras de limpeza de uma hierarquia de objetos de estrutura, consulte Ciclo de vida do objeto framework.
Exemplos
O exemplo de código a seguir cria espaço de contexto para um objeto de solicitação. O espaço de contexto é baseado na estrutura REQUEST_CONTEXT do exemplo.
typedef struct _REQUEST_CONTEXT {
WDFMEMORY InputMemoryBuffer;
WDFMEMORY OutputMemoryBuffer;
} REQUEST_CONTEXT, *PREQUEST_CONTEXT;
PREQUEST_CONTEXT reqContext = NULL;
WDF_OBJECT_ATTRIBUTES attributes;
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
&attributes,
REQUEST_CONTEXT
);
status = WdfObjectAllocateContext(
Request,
&attributes,
&reqContext
);
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 | wdfobject.h (inclua Wdf.h) |
| Biblioteca | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Regras de conformidade da DDI | DriverCreate(kmdf) |