estrutura WDF_OBJECT_ATTRIBUTES (wdfobject.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

A estrutura WDF_OBJECT_ATTRIBUTES descreve atributos que podem ser associados a qualquer objeto de estrutura.

Sintaxe

typedef struct _WDF_OBJECT_ATTRIBUTES {
  ULONG                          Size;
  PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
  PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
  WDF_EXECUTION_LEVEL            ExecutionLevel;
  WDF_SYNCHRONIZATION_SCOPE      SynchronizationScope;
  WDFOBJECT                      ParentObject;
  size_t                         ContextSizeOverride;
  PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
} WDF_OBJECT_ATTRIBUTES, *PWDF_OBJECT_ATTRIBUTES;

Membros

Size

O tamanho, em bytes, dessa estrutura.

EvtCleanupCallback

Um ponteiro para a função de retorno de chamada EvtCleanupCallback do driver ou NULL.

EvtDestroyCallback

Um ponteiro para a função de retorno de chamada EvtDestroyCallback do driver ou NULL.

ExecutionLevel

Um valor de tipo WDF_EXECUTION_LEVEL que especifica o IRQL máximo no qual a estrutura chamará as funções de retorno de chamada de evento do objeto. Para obter uma lista de objetos de estrutura para os quais o driver pode especificar um valor ExecutionLevel , consulte WDF_EXECUTION_LEVEL.

SynchronizationScope

Um valor de tipo WDF_SYNCHRONIZATION_SCOPE que especifica como a estrutura sincronizará a execução das funções de retorno de chamada de evento do objeto. Para obter uma lista de objetos de estrutura para os quais o driver pode especificar um valor SynchronizationScope , consulte WDF_SYNCHRONIZATION_SCOPE.

ParentObject

Um identificador para o objeto pai do objeto ou NULL se o objeto não tiver um pai especificado pelo driver.

Consulte Resumo de Objetos de Estrutura para uma tabela que mostra os objetos que permitem um pai especificado pelo driver. A tabela também mostra o pai padrão de cada objeto.

ContextSizeOverride

Se não for zero, esse valor substituirá o membro ContextSize da estrutura WDF_OBJECT_CONTEXT_TYPE_INFO referenciada pelo membro ContextTypeInfo . Esse valor é opcional e pode ser zero. Se o valor não for zero, ele deverá especificar um tamanho, em bytes, maior que o valor especificado para o membro ContextSize da estrutura WDF_OBJECT_CONTEXT_TYPE_INFO. Para obter mais informações, consulte a seção Comentários a seguir.

ContextTypeInfo

Um ponteiro para uma estrutura WDF_OBJECT_CONTEXT_TYPE_INFO . A macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE define esse ponteiro.

Comentários

A estrutura WDF_OBJECT_ATTRIBUTES é usada como um argumento de entrada para vários métodos que criam objetos de estrutura.

Para inicializar uma estrutura de WDF_OBJECT_ATTRIBUTES, o driver deve chamar WDF_OBJECT_ATTRIBUTES_INIT.

Além disso, se você estiver definindo informações de contexto específicas do objeto para um objeto, deverá usar a macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE .

Como alternativa, você pode usar a macro WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE em vez das macros WDF_OBJECT_ATTRIBUTES_INIT e WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE.

Para obter mais informações sobre como usar essas macros, consulte Espaço de contexto do objeto framework.

Use o membro ContextSizeOverride do WDF_OBJECT_ATTRIBUTES se quiser criar um espaço de contexto de objeto que tenha um comprimento variável. Por exemplo, você pode definir uma estrutura de espaço de contexto que contém uma matriz, da seguinte maneira:

typedef struct _MY_REQUEST_CONTEXT {
  ULONG  ByteCount;
  BYTE  Bytes[1];
} MY_REQUEST_CONTEXT, *PMY_REQUEST_CONTEXT;

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

Quando o driver cria um objeto que usa a estrutura de espaço de contexto, ele pode usar o membro ContextSizeOverride para especificar o tamanho de contexto necessário para cada objeto individual. Por exemplo, o driver pode calcular o número de bytes necessários na matriz do exemplo anterior e, em seguida, usar ContextSizeOverride para especificar os bytes extras, da seguinte maneira:

WDF_OBJECT_ATTRIBUTES MyRequestObjectAttributes;
PMY_REQUEST_CONTEXT pMyContext;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &MyRequestObjectAttributes,
                                        MY_REQUEST_CONTEXT
                                        );
MyRequestObjectAttributes.ContextSizeOverride =
                          sizeof(MY_REQUEST_CONTEXT) + Num_Extra_Bytes - 1;

Em seguida, o driver pode criar um objeto com um tamanho de contexto personalizado.

status = WdfRequestCreate(
                          &MyRequestObjectAttributes,
                          ioTarget,
                          &newRequest
                          );

Para obter mais informações sobre as regras de limpeza de uma hierarquia de objetos de estrutura, consulte Ciclo de vida do objeto framework.