estructura WDF_OBJECT_ATTRIBUTES (wdfobject.h)

Artículo
02/29/2024

[Se aplica a KMDF y UMDF]

La estructura WDF_OBJECT_ATTRIBUTES describe los atributos que se pueden asociar a cualquier objeto de marco.

Sintaxis

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;

Miembros

Size

Tamaño, en bytes, de esta estructura.

EvtCleanupCallback

Puntero a la función de devolución de llamada EvtCleanupCallback del controlador o NULL.

EvtDestroyCallback

Puntero a la función de devolución de llamada EvtDestroyCallback del controlador o NULL.

ExecutionLevel

Valor WDF_EXECUTION_LEVEL con tipo que especifica el IRQL máximo en el que el marco llamará a las funciones de devolución de llamada de eventos del objeto. Para obtener una lista de objetos de marco para los que el controlador puede especificar un valor ExecutionLevel , consulte WDF_EXECUTION_LEVEL.

SynchronizationScope

Valor con tipo WDF_SYNCHRONIZATION_SCOPE que especifica cómo sincronizará la ejecución del marco de trabajo de las funciones de devolución de llamada de eventos del objeto. Para obtener una lista de objetos de marco para los que el controlador puede especificar un valor SynchronizationScope , consulte WDF_SYNCHRONIZATION_SCOPE.

ParentObject

Identificador del objeto primario del objeto o NULL si el objeto no tiene un elemento primario especificado por el controlador.

Consulte Resumen de objetos de marco para obtener una tabla que muestre los objetos que permiten un elemento primario especificado por el controlador. La tabla también muestra el elemento primario predeterminado de cada objeto.

ContextSizeOverride

Si no es cero, este valor invalida el miembro ContextSize de la estructura WDF_OBJECT_CONTEXT_TYPE_INFO a la que hace referencia el miembro ContextTypeInfo . Este valor es opcional y puede ser cero. Si el valor no es cero, debe especificar un tamaño, en bytes, mayor que el valor especificado para el miembro ContextSize de la estructura WDF_OBJECT_CONTEXT_TYPE_INFO. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

ContextTypeInfo

Puntero a una estructura de WDF_OBJECT_CONTEXT_TYPE_INFO . La macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE establece este puntero.

Comentarios

La estructura WDF_OBJECT_ATTRIBUTES se usa como argumento de entrada para varios métodos que crean objetos de marco.

Para inicializar una estructura de WDF_OBJECT_ATTRIBUTES, el controlador debe llamar a WDF_OBJECT_ATTRIBUTES_INIT.

Además, si va a definir información de contexto específica del objeto para un objeto, debe usar la macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE .

Como alternativa, puede usar la macro WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE en lugar de las macros WDF_OBJECT_ATTRIBUTES_INIT y WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE.

Para obtener más información sobre el uso de estas macros, vea Espacio de contexto de objetos de marco.

Use el miembro ContextSizeOverride de WDF_OBJECT_ATTRIBUTES si desea crear un espacio de contexto de objeto que tenga una longitud variable. Por ejemplo, puede definir una estructura de espacio de contexto que contenga una matriz, como se indica a continuación:

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

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

Cuando el controlador crea un objeto que usa la estructura del espacio de contexto, puede usar el miembro ContextSizeOverride para especificar el tamaño de contexto necesario para cada objeto individual. Por ejemplo, el controlador podría calcular el número de bytes necesarios en la matriz del ejemplo anterior y, a continuación, usar ContextSizeOverride para especificar los bytes adicionales, como se indica a continuación:

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;

A continuación, el controlador puede crear un objeto con un tamaño de contexto personalizado.

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

Para obtener más información sobre las reglas de limpieza de una jerarquía de objetos de marco, vea Ciclo de vida de objetos de marco.