estructura WDF_OBJECT_ATTRIBUTES (wdfobject.h)

Artículo
03/22/2025

[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 EvtCleanupCall back del controlador o null.

EvtDestroyCallback

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

ExecutionLevel

Valor de tipo WDF_EXECUTION_LEVELque 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 de ExecutionLevel, vea WDF_EXECUTION_LEVEL.

SynchronizationScope

Valor de tipo WDF_SYNCHRONIZATION_SCOPEque especifica cómo sincronizará la ejecución 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 de SynchronizationScope, vea 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 ver una tabla que muestra 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 de. 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 ContextSize miembro de la estructura WDF_OBJECT_CONTEXT_TYPE_INFO. Para obtener más información, vea la siguiente sección Comentarios.

ContextTypeInfo

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

Observaciones

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 Framework Object Context Space.

Use el miembro contextSizeOverride de de WDF_OBJECT_ATTRIBUTES si desea crear 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 contextSizeOverride miembro para especificar el tamaño de contexto necesario para cada objeto individual. Por ejemplo, el controlador puede 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 del objeto framework.