Megosztás a következőn keresztül:

Függvényparaméterek és visszaadott értékek megjegyzése

Ez a cikk az egyszerű függvényparaméterek – skalárok és struktúrákra és osztályokra mutató mutatók – és a legtöbb puffertípus megjegyzéseinek tipikus használatát ismerteti. Ez a cikk a széljegyzetek gyakori használati mintáit is ismerteti. A függvényekhez kapcsolódó további széljegyzetekért lásd a függvények viselkedésének megjegyzésekkel történő megjelenítését.

Mutatóparaméterek

A következő táblázatban szereplő széljegyzetek esetében, ha a mutatóparamétert széljegyzetek jelzik, az elemző hibát jelez, ha a mutató null értékű. Ez a széljegyzet a mutatókra és a mutatott adatelemekre vonatkozik.

Széljegyzetek és leírások

  • _In_

    Jegyzetekkel láthatja el a skalárokat, struktúrákat, struktúrákra mutató mutatókat és hasonlókat tartalmazó bemeneti paramétereket. Kifejezetten használható egyszerű skalárisokon. A paraméternek előállapotban kell érvényesnek lennie, és nem módosítható.

  • _Out_

    Annotálja a kimeneti paramétereket, amelyek skalárok, struktúrák, struktúramutatók és hasonlók. Ne alkalmazza ezt a széljegyzetet olyan objektumra, amely nem tud értéket visszaadni– például egy érték által átadott skalárt. A paraméternek nem kell előzetes állapotban érvényesnek lennie, de utóállapotban is érvényesnek kell lennie.

  • _Inout_

    A függvény által módosítandó paramétert megjegyzéssel látja el. Az állapotnak mind a hívás előtti, mind az utáni időszakban érvényesnek kell lennie, de feltételezzük, hogy a hívás előtt és után különböző értékekkel rendelkezik. Módosítható értékre kell vonatkoznia.

  • _In_z_

    Egy bemenetként használt nullával lezárt karakterláncra mutató mutató. A karakterláncnak az előző állapotban kell érvényesnek lennie. Előnyben részesítik azokat a PSTR változatokat, amelyek már rendelkeznek a megfelelő széljegyzetekkel.

  • _Inout_z_

    Egy nullával lezárt, módosítandó karaktertömbre mutató. A hívás előtt és után érvényesnek kell lennie, de feltételezzük, hogy az érték megváltozott. A null terminátor áthelyezhető, de csak az eredeti null terminátorig elérhető elemek érhetők el.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    Egy tömbre mutató mutató, amelyet a függvény olvas be. A tömb méretelemekből s áll, amelyek mindegyikének érvényesnek kell lennie.

    A _bytes_ variáns az elemek helyett bájtban adja meg a méretet. Ezt a változatot csak akkor használja, ha a méret nem fejezhető ki elemként. Például a karakterláncok char csak akkor használnák a _bytes_ variánst, ha egy hasonló függvény, amely wchar_t-t használ, szintén azt tenné.

  • _In_reads_z_(s)

    Egy nullával lezárt és ismert méretű tömbre mutató mutató. A null terminátorig ( vagy s ha nincs null terminátor) lévő elemeknek előállapotban kell érvényesnek lenniük. Ha a méret bájtban ismert, skálázható s az elemméret alapján.

  • _In_reads_or_z_(s)

    Null értékkel lezárt vagy ismert méretű tömbre mutató mutató, vagy mindkettő. A null terminátorig ( vagy s ha nincs null terminátor) lévő elemeknek előállapotban kell érvényesnek lenniük. Ha a méret bájtban ismert, skálázható s az elemméret alapján. (A strn családnál használják.)

  • _Out_writes_(s)

    _Out_writes_bytes_(s)

    A függvény által leírandó elemek (bájtok) tömbjére mutató s mutató. A tömbelemeknek nem kell előállapotban érvényesnek lenniük, és az utóállapotban érvényes elemek száma nincs meghatározva. Ha a paramétertípuson vannak széljegyzetek, a rendszer utóállapotban alkalmazza őket. Vegyük például az alábbi kódot.

    typedef _Null_terminated_ wchar_t *PWSTR;
void MyStringCopy(_Out_writes_(size) PWSTR p1, _In_ size_t size, _In_ PWSTR p2);

    Ebben a példában a hívó egy size elemű puffert biztosít a p1 számára. MyStringCopy érvényessé tesz néhány elemet. Ennél is fontosabb, hogy a _Null_terminated_ annotáció a PWSTR azt jelenti, hogy a p1 a végállapotban nullával lezárt. Ily módon az érvényes elemek száma továbbra is jól definiálva van, de nincs szükség egy adott elemszámra.

    A _bytes_ variáns az elemek helyett bájtban adja meg a méretet. Ezt a változatot csak akkor használja, ha a méret nem fejezhető ki elemként. Például a karakterláncok char csak akkor használnák a _bytes_ variánst, ha egy hasonló függvény, amely wchar_t-t használ, szintén azt tenné.

  • _Out_writes_z_(s)

    Mutató egy s elemeket tartalmazó tömbre. Az elemeknek nem kell előzetes állapotban érvényesnek lenniük. Az utóállapotban az elemeknek, egészen a null terminátorig – amelynek jelen kell lennie –, érvényesnek kell lenniük. Ha a méret bájtban ismert, skálázható s az elemméret alapján.

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    Egy tömbre mutató mutató, amely a függvényben olvasható és írható is. s méretű elemekből áll, és érvényes mind a kezdeti állapotban, mind a végső állapotban.

    A _bytes_ variáns az elemek helyett bájtban adja meg a méretet. Ezt a változatot csak akkor használja, ha a méret nem fejezhető ki elemként. Például a karakterláncok char csak akkor használnák a _bytes_ variánst, ha egy hasonló függvény, amely wchar_t-t használ, szintén azt tenné.

  • _Inout_updates_z_(s)

    Egy nullával lezárt és ismert méretű tömbre mutató mutató. A null terminátoron keresztüli elemeknek – amelyeknek jelen kell lenniük – elő- és utóállapotban egyaránt érvényeseknek kell lenniük. A post-state értéke vélelmezhetően eltér az előállapot értékétől; a null terminátor helyét is tartalmazza. Ha a méret bájtban ismert, skálázható s az elemméret alapján.

  • _Out_writes_to_(s,c)

    _Out_writes_bytes_to_(s,c)

    _Out_writes_all_(s)

    _Out_writes_bytes_all_(s)

    Mutató egy s elemeket tartalmazó tömbre. Az elemeknek nem kell előzetes állapotban érvényesnek lenniük. Utóállapotban a c. elemig az elemeknek érvényesnek kell lenniük. A _bytes_ variáns akkor használható, ha a méret bájtban ismert az elemek száma helyett.

    Például:

    void *memcpy(_Out_writes_bytes_all_(s) char *p1, _In_reads_bytes_(s) char *p2, _In_ int s);
void *wordcpy(_Out_writes_all_(s) DWORD *p1, _In_reads_(s) DWORD *p2, _In_ int s);

  • _Inout_updates_to_(s,c)

    _Inout_updates_bytes_to_(s,c)

    Egy tömbre mutató mutató, amelyet a függvény olvas és ír. A méret s elemekből áll, amelyeknek érvényesnek kell lenniük az előállapotban, és a c elemeknek érvényesnek kell lenniük az utóállapotban.

    A _bytes_ variáns az elemek helyett bájtban adja meg a méretet. Ezt a változatot csak akkor használja, ha a méret nem fejezhető ki elemként. Például a karakterláncok char csak akkor használnák a _bytes_ variánst, ha egy hasonló függvény, amely wchar_t-t használ, szintén azt tenné.

  • _Inout_updates_all_(s)

    _Inout_updates_bytes_all_(s)

    Egy tömbre mutató mutató, amelyet a méretelemek s függvénye olvas és ír. Az alábbiaknak megfelelőként definiálva:

    _Inout_updates_to_(_Old_(s), _Old_(s)) _Inout_updates_bytes_to_(_Old_(s), _Old_(s))

    Más szóval, a pufferben az s előtti állapotig létező összes elem érvényes az előállapotban és az utóállapotban.

    A _bytes_ variáns az elemek helyett bájtban adja meg a méretet. Ezt a változatot csak akkor használja, ha a méret nem fejezhető ki elemként. Például a karakterláncok char csak akkor használnák a _bytes_ variánst, ha egy hasonló függvény, amely wchar_t-t használ, szintén azt tenné.

  • _In_reads_to_ptr_(p)

    Egy tömbre mutató mutató, amelynél a p - _Curr_ mínusz p érvényes kifejezésként szerepel. A korábbi p elemeknek előállapotban kell érvényesnek lenniük.

    Például:

    int ReadAllElements(_In_reads_to_ptr_(EndOfArray) const int *Array, const int *EndOfArray);

  • _In_reads_to_ptr_z_(p)

    Nullára végződő tömbre mutató mutató, amelyekre a p - _Curr_ kifejezés (vagyis p mínusz _Curr_) érvényes kifejezés. A korábbi p elemeknek előállapotban kell érvényesnek lenniük.

  • _Out_writes_to_ptr_(p)

    Egy tömbre mutató mutató, amelynél a p - _Curr_ mínusz p érvényes kifejezésként szerepel. A korábbi p elemeknek nem kell előzetes állapotban érvényesnek lenniük, és utóállapotban is érvényesnek kell lenniük.

  • _Out_writes_to_ptr_z_(p)

    Érvénytelen karakterrel lezárt tömbre mutató mutató, amelyhez p - _Curr_ (azaz p mínusz _Curr_) érvényes kifejezés. A korábbi p elemeknek nem kell előzetes állapotban érvényesnek lenniük, és utóállapotban is érvényesnek kell lenniük.

Nem kötelező mutatóparaméterek

Ha egy mutatóparaméter széljegyzete is szerepel _opt_, az azt jelzi, hogy a paraméter null értékű lehet. Ellenkező esetben a széljegyzet ugyanúgy viselkedik, mint a nem tartalmazó _opt_verzió. Íme a mutatóparaméter-széljegyzetek változatainak listája _opt_ :

_In_opt_
_Out_opt_
_Inout_opt_
_In_opt_z_
_Inout_opt_z_
_In_reads_opt_
_In_reads_bytes_opt_
_In_reads_opt_z_

_Out_writes_opt_
_Out_writes_opt_z_
_Inout_updates_opt_
_Inout_updates_bytes_opt_
_Inout_updates_opt_z_
_Out_writes_to_opt_
_Out_writes_bytes_to_opt_
_Out_writes_all_opt_
_Out_writes_bytes_all_opt_

_Inout_updates_to_opt_
_Inout_updates_bytes_to_opt_
_Inout_updates_all_opt_
_Inout_updates_bytes_all_opt_
_In_reads_to_ptr_opt_
_In_reads_to_ptr_opt_z_
_Out_writes_to_ptr_opt_
_Out_writes_to_ptr_opt_z_

Kimeneti mutató paraméterei

A kimeneti mutató paraméterei speciális jelölést igényelnek a paraméter és a mutató hely nullságának egyértelműsítéséhez.

Széljegyzetek és leírások

  • _Outptr_

    A paraméter nem lehet null értékű, és a post-state esetében a hivatkozott hely nem lehet null értékű, és érvényesnek kell lennie.

  • _Outptr_opt_

    A paraméter lehet null, de az utóállapotban az átadott hely nem lehet null értékű, és érvényesnek kell lennie.

  • _Outptr_result_maybenull_

    A paraméter nem lehet null értékű, az utóállapotban a hivatkozott hely null értékű lehet.

  • _Outptr_opt_result_maybenull_

    A paraméter lehet null, és utánállapotban a mutatott hely is lehet null.

    Az alábbi táblázatban további részszűkítések lesznek beszúrva a széljegyzet nevére, hogy tovább minősítse a széljegyzet jelentését. A különböző részláncok: _z, _COM_, _buffer_, _bytebuffer_, és _to_.

Fontos

Ha az a felület, amelyet jegyzetel, COM, használja ezeknek az annotációknak a COM formáját. Ne használja a COM-széljegyzeteket más típusú felülettel.

  • _Outptr_result_z_

    _Outptr_opt_result_z_

    _Outptr_result_maybenull_z_

    _Outptr_opt_result_maybenull_z_

    A visszaadott mutató megkapta a _Null_terminated_ jelölést.

  • _COM_Outptr_

    _COM_Outptr_opt_

    _COM_Outptr_result_maybenull_

    _COM_Outptr_opt_result_maybenull_

    A visszaadott mutató COM szemantikával rendelkezik, ezért a visszaadott mutató null értékű utófeltételt hordoz _On_failure_ .

  • _Outptr_result_buffer_(s)

    _Outptr_result_bytebuffer_(s)

    _Outptr_opt_result_buffer_(s)

    _Outptr_opt_result_bytebuffer_(s)

    A visszaadott mutató egy s elem vagy bájt méretű érvényes pufferre mutat.

  • _Outptr_result_buffer_to_(s, c)

    _Outptr_result_bytebuffer_to_(s, c)

    _Outptr_opt_result_buffer_to_(s,c)

    _Outptr_opt_result_bytebuffer_to_(s,c)

    A visszaadott mutató egy s elemre vagy bájtra méretezett pufferre mutat, amelyek közül az első c érvényes.

Bizonyos illesztőkonvenciák feltételezik, hogy a kimeneti paraméterek hiba esetén null értékűek. A kifejezetten COM-kód kivételével a következő táblázatban szereplő űrlapok előnyben részesülnek. COM-kód esetén használja az előző szakaszban felsorolt megfelelő COM-űrlapokat.

  • _Result_nullonfailure_

    Módosítja az egyéb széljegyzeteket. Az eredmény null értékre van állítva, ha a függvény meghibásodik.

  • _Result_zeroonfailure_

    Módosítja az egyéb széljegyzeteket. Az eredmény nullára van állítva, ha a függvény meghibásodik.

  • _Outptr_result_nullonfailure_

    A visszaadott mutató érvényes pufferre mutat, ha a függvény sikeres, vagy null értékű, ha a függvény meghiúsul. Ez a széljegyzet egy nem választható paraméterhez készült.

  • _Outptr_opt_result_nullonfailure_

    A visszaadott mutató érvényes pufferre mutat, ha a függvény sikeres, vagy null értékű, ha a függvény meghiúsul. Ez a széljegyzet egy opcionális paraméterhez készült.

  • _Outref_result_nullonfailure_

    A visszaadott mutató érvényes pufferre mutat, ha a függvény sikeres, vagy null értékű, ha a függvény meghiúsul. Ez a széljegyzet egy referenciaparaméterhez készült.

Kimeneti referenciaparaméterek

A referenciaparaméter gyakori használata a kimeneti paraméterek esetében. Egyszerű kimeneti referenciaparaméterekhez, például int&a _Out_ megfelelő szemantikát adja meg. Ha azonban a kimeneti érték egy ilyen int *&mutató, akkor az egyenértékű mutatójegyzetek, például _Outptr_ int ** nem adják meg a megfelelő szemantikát. A mutatótípusok kimeneti referenciaparamétereinek szemantikájának tömör kifejezéséhez használja az alábbi összetett széljegyzeteket:

Széljegyzetek és leírások

  • _Outref_

    Az eredménynek utóállapotban kell érvényesnek lennie, és nem lehet null értékű.

  • _Outref_result_maybenull_

    Az eredménynek utóállapotban kell érvényesnek lennie, de lehet, hogy az utóállapotban null.

  • _Outref_result_buffer_(s)

    Az eredménynek utóállapotban kell érvényesnek lennie, és nem lehet null értékű. A s méretű elemekből álló érvényes pufferre mutat.

  • _Outref_result_bytebuffer_(s)

    Az eredménynek utóállapotban kell érvényesnek lennie, és nem lehet null értékű. Az s bájt méretű érvényes pufferre mutat.

  • _Outref_result_buffer_to_(s, c)

    Az eredménynek utóállapotban kell érvényesnek lennie, és nem lehet null értékű. Az elemek pufferére mutat s, amelyből az első c érvényes.

  • _Outref_result_bytebuffer_to_(s, c)

    Az eredménynek utóállapotban kell érvényesnek lennie, és nem lehet null értékű. Egy puffer s bájtnyi adatra, amelyből az első c érvényes.

  • _Outref_result_buffer_all_(s)

    Az eredménynek utóállapotban kell érvényesnek lennie, és nem lehet null értékű. Érvényes méretű s érvényes elemeket tartalmazó pufferre mutat.

  • _Outref_result_bytebuffer_all_(s)

    Az eredménynek utóállapotban kell érvényesnek lennie, és nem lehet null értékű. Az elemek s bájtjainak érvényes pufferére mutat.

  • _Outref_result_buffer_maybenull_(s)

    Az eredménynek utóállapotban kell érvényesnek lennie, de lehet, hogy az utóállapotban null. A s méretű elemekből álló érvényes pufferre mutat.

  • _Outref_result_bytebuffer_maybenull_(s)

    Az eredménynek utóállapotban kell érvényesnek lennie, de lehet, hogy az utóállapotban null. Az s bájt méretű érvényes pufferre mutat.

  • _Outref_result_buffer_to_maybenull_(s, c)

    Az eredménynek utóállapotban kell érvényesnek lennie, de lehet, hogy az utóállapotban null. Az elemek pufferére mutat s, amelyből az első c érvényes.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    Az eredménynek érvényesnek kell lennie az utóállapotban, de lehet, hogy null értékű. Egy puffer s bájtnyi adatra, amelyből az első c érvényes.

  • _Outref_result_buffer_all_maybenull_(s)

    Az eredménynek érvényesnek kell lennie az utóállapotban, de lehet, hogy null értékű. Érvényes méretű s érvényes elemeket tartalmazó pufferre mutat.

  • _Outref_result_bytebuffer_all_maybenull_(s)

    Az eredménynek érvényesnek kell lennie az utóállapotban, de lehet, hogy null értékű. Az elemek s bájtjainak érvényes pufferére mutat.

Visszaadott értékek

Egy függvény visszatérési értéke hasonlít egy _Out_ paraméterre, de más hivatkozási szinten van, és nem kell figyelembe vennie az eredményre mutató mutató fogalmát. A következő annotációk esetében a visszatérési érték az annotációval ellátott objektum – egy skalár, egy struktúrára mutató vagy egy pufferre mutató. Ezek a széljegyzetek ugyanolyan szemantikával rendelkeznek, mint a megfelelő _Out_ széljegyzetek.

_Ret_z_
_Ret_writes_(s)
_Ret_writes_bytes_(s)
_Ret_writes_z_(s)
_Ret_writes_to_(s,c)
_Ret_writes_maybenull_(s)
_Ret_writes_to_maybenull_(s)
_Ret_writes_maybenull_z_(s)

_Ret_maybenull_
_Ret_maybenull_z_
_Ret_null_
_Ret_notnull_
_Ret_writes_bytes_to_
_Ret_writes_bytes_maybenull_
_Ret_writes_bytes_to_maybenull_

Sztringparaméterek formázása

  • _Printf_format_string_ Azt jelzi, hogy a paraméter egy formátumstring, amely egy printf kifejezésben használható.

    Példa

    int MyPrintF(_Printf_format_string_ const wchar_t* format, ...)
{
       va_list args;
       va_start(args, format);
       int ret = vwprintf(format, args);
       va_end(args);
       return ret;
}

  • _Scanf_format_string_ Azt jelzi, hogy a paraméter egy formátumstring, amely egy scanf kifejezésben használható.

    Példa

    int MyScanF(_Scanf_format_string_ const wchar_t* format, ...)
{
       va_list args;
       va_start(args, format);
       int ret = vwscanf(format, args);
       va_end(args);
       return ret;
}

  • _Scanf_s_format_string_ Azt jelzi, hogy a paraméter egy formátumstring, amely egy scanf_s kifejezésben használható.

    Példa

    int MyScanF_s(_Scanf_s_format_string_ const wchar_t* format, ...)
{
       va_list args;
       va_start(args, format);
       int ret = vwscanf_s(format, args);
       va_end(args);
       return ret;
}

Egyéb gyakori széljegyzetek

Széljegyzetek és leírások

  • _In_range_(low, hi)

    _Out_range_(low, hi)

    _Ret_range_(low, hi)

    _Deref_in_range_(low, hi)

    _Deref_out_range_(low, hi)

    _Deref_inout_range_(low, hi)

    _Field_range_(low, hi)

    A paraméter, mező vagy eredmény a low és hi közötti tartományban van. Az annotált objektummal együtt alkalmazott _Satisfies_(_Curr_ >= low && _Curr_ <= hi) a megfelelő elő-állapot vagy utóállapot feltételeivel egyenértékű.

    Fontos

    Bár a nevek tartalmazzák az "in" és a "out" kifejezést, a megjegyzések szemantikája _In__Out_nem vonatkozik ezekre a széljegyzetekre.

  • _Pre_equal_to_(expr)

    _Post_equal_to_(expr)

    A jelölt érték pontosan expr. Az annotált objektummal együtt alkalmazott _Satisfies_(_Curr_ == expr) a megfelelő elő-állapot vagy utóállapot feltételeivel egyenértékű.

  • _Struct_size_bytes_(size)

    Egy szerkezetre vagy osztálydeklarációra vonatkozik. Azt jelzi, hogy egy ilyen típusú érvényes objektum nagyobb lehet a deklarált típusnál, és a bájtok száma éppen a size által megadott. Például:

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

    A paraméter pM bájtban kifejezett puffer mérete a MyStruct * típushoz a következő:

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

Lásd még

  • Last updated on