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
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_OBJECT_NAME_INVALID	O membro ContextTypeInfo da estrutura WDF_OBJECT_ATTRIBUTES especificada pelo parâmetro ContextAttributes era inválido.
STATUS_INSUFFICIENT_RESOURCES	Não foi possível alocar espaço de contexto.
STATUS_OBJECT_NAME_EXISTS	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.
STATUS_DELETE_PENDING	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)

Confira também

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WdfDeviceCreate