Udostępnij za pośrednictwem

Dodawanie adnotacji struktur i klas

  • Artykuł

Można dodawać adnotacje do struktur i składowych klas przy użyciu adnotacji, które działają jak niezmienne — są one uważane za prawdziwe w dowolnym wywołaniu funkcji lub wpisie/wyjściu funkcji, które obejmują otaczającą strukturę jako parametr lub wartość wyniku.

Struct and Class Annotations

  • _Field_range_(low, high)

    Pole znajduje się w zakresie (włącznie) od low do high. Odpowiednik zastosowany do _Satisfies_(_Curr_ >= low && _Curr_ <= high) obiektu z adnotacjami przy użyciu odpowiednich warunków wstępnych lub postów.

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

    Pole, które ma zapisywalny rozmiar w elementach (lub bajtach), zgodnie z wartością 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)

    Pole o rozmiarze zapisywalnym w elementach (lub bajtach) określonym przez sizeelement i count tych elementów (bajtach), które można odczytać.

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

    Pole, które ma zarówno czytelny, jak i zapisywalny rozmiar w elementach (lub bajtach), zgodnie z parametrem size.

  • _Field_z_

    Pole, które ma ciąg zakończony wartością null.

  • _Struct_size_bytes_(size)

    Dotyczy deklaracji struktury lub klasy. Wskazuje, że prawidłowy obiekt tego typu może być większy niż zadeklarowany typ, z liczbą bajtów określonych przez size. Na przykład:

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

    Rozmiar buforu w bajtach parametru pM typu MyStruct * jest następnie przyjmowany jako:

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

Przykład

#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
};

Uwagi dotyczące tego przykładu:

  • _Field_z_ jest równoważne z _Null_terminated_. _Field_z_ dla pola nazwy określa, że pole nazwy jest ciągiem zakończonym o wartości null.
  • _Field_range_ for bufferSize określa, że wartość bufferSize powinna mieścić się w zakresie 1 i MaxBufferSize (włącznie).
  • Wyniki _Struct_size_bytes_ końcowe adnotacji i _Field_size_ są równoważne. W przypadku struktur lub klas, które mają podobny układ, _Field_size_ łatwiej jest odczytywać i konserwować, ponieważ ma mniej odwołań i obliczeń niż równoważna _Struct_size_bytes_ adnotacja. _Field_size_ nie wymaga konwersji na rozmiar bajtów. Jeśli rozmiar bajtu jest jedyną opcją, na przykład dla pola wskaźnika pustki, _Field_size_bytes_ można użyć. Jeśli oba _Struct_size_bytes_ _Field_size_ te elementy i istnieją, będą dostępne dla narzędzi. To do narzędzia, co zrobić, jeśli dwie adnotacje się nie zgadzają.

Zobacz też