Anotar structs y clases

  • Artículo

Puede anotar miembros de clase y estructura mediante anotaciones que actúan como invariantes: se supone que son true en cualquier llamada a función o entrada o salida de función que implique la estructura envolvente como un parámetro o un valor de resultado.

Anotaciones de estructura y clase

  • _Field_range_(low, high)

    El campo está en el intervalo (incluido) de low a high. Equivalente a _Satisfies_(_Curr_ >= low && _Curr_ <= high) aplicado al objeto anotado mediante las condiciones previas o posteriores adecuadas.

  • _Field_size_(size), _Field_size_opt_(size), _Field_size_bytes_(size), _Field_size_bytes_opt_(size)

    Campo que tiene un tamaño grabable en elementos (o bytes) según lo especificado por size.

  • _Field_size_part_(size, count), _Field_size_part_opt_(size, count), _Field_size_bytes_part_(size, count), _Field_size_bytes_part_opt_(size, count)

    Campo que tiene un tamaño grabable en elementos (o bytes) según lo especificado por size, y el valor count de esos elementos (bytes) que se pueden leer.

  • _Field_size_full_(size), _Field_size_full_opt_(size), _Field_size_bytes_full_(size), _Field_size_bytes_full_opt_(size)

    Campo que tiene un tamaño legible y grabable en elementos (o bytes) según lo especificado por size.

  • _Field_z_

    Campo que tiene una cadena terminada en NULL.

  • _Struct_size_bytes_(size)

    Se aplica a la declaración de clase o estructura. Indica que un objeto válido de ese tipo puede ser mayor que el tipo declarado, con el número de bytes especificado por size. Por ejemplo:

    
typedef _Struct_size_bytes_(nSize)
struct MyStruct {
    size_t nSize;
    ...
};

    A continuación, se toma el tamaño del búfer en bytes de un parámetro pM de tipo MyStruct * para que sea:

    min(pM->nSize, sizeof(MyStruct))

Ejemplo

#include <sal.h>

// This _Struct_size_bytes_ is equivalent to what below _Field_size_ means.
_Struct_size_bytes_(__builtin_offsetof(MyBuffer, buffer) + bufferSize * sizeof(int))
struct MyBuffer
{
    static int MaxBufferSize;

    _Field_z_
    const char* name;

    int firstField;

    // ... other fields

    _Field_range_(1, MaxBufferSize)
    int bufferSize;

    _Field_size_(bufferSize)        // Preferred way - easier to read and maintain.
    int buffer[]; // Using C99 Flexible array member
};

Notas de este ejemplo:

  • _Field_z_ equivale a _Null_terminated_. _Field_z_ para el campo de nombre especifica que el campo de nombre es una cadena terminada en NULL.
  • _Field_range_ para bufferSize especifica que el valor de bufferSize debe estar dentro de 1 y MaxBufferSize (ambos inclusive).
  • Los resultados finales de las anotaciones _Struct_size_bytes_ y _Field_size_ son equivalentes. En el caso de las estructuras o clases que tienen un diseño similar, _Field_size_ es más fácil de leer y mantener, ya que tiene menos referencias y cálculos que la anotación _Struct_size_bytes_ equivalente. _Field_size_ no requiere la conversión al tamaño de bytes. Si el tamaño de bytes es la única opción, por ejemplo, para un campo de puntero nulo, se puede usar _Field_size_bytes_. Si _Struct_size_bytes_ y _Field_size_ existen, ambos estarán disponibles para las herramientas. Depende de la herramienta qué hacer si las dos anotaciones no coinciden.

Consulte también