Dela via

Kommentera funktionsparametrar och returvärden

Den här artikeln beskriver typiska annoteringar för enkla funktionsparametrar – skalärer och pekare till strukturer och klasser – och de flesta typer av buffertar. Den här artikeln visar också vanliga användningsmönster för anteckningar. Ytterligare anteckningar som är relaterade till funktioner finns i Kommentera funktionsbeteende.

Pekarparametrar

När en pekarparameter kommenteras för anteckningarna i följande tabell rapporterar analysverktyget ett fel om pekaren är null. Den här kommentaren gäller pekare och alla dataobjekt som pekas på.

Anteckningar och beskrivningar

  • _In_

    Kommenterar indataparametrar som är skalärer, strukturer, pekare till strukturer och liknande. Explicit kan användas på enkla skalärer. Parametern måste vara giltig i förtillstånd och ändras inte.

  • _Out_

    Kommenterar utdataparametrar som är skalärer, strukturer, pekare till strukturer och liknande. Använd inte den här annoteringen på ett objekt som inte kan returnera ett värde, till exempel en skalär som skickas som värde. Parametern behöver inte vara giltig i initialtillståndet, men måste vara giltig i det slutgiltiga tillståndet.

  • _Inout_

    Kommenterar en parameter som kommer att ändras av funktionen. Det måste vara giltigt i både tillstånd före och tillstånd efter, men antas ha olika värden före och efter anropet. Måste gälla för ett ändringsbart värde.

  • _In_z_

    En pekare till en null-avslutad sträng som används som indata. Strängen måste vara giltig i förtillstånd. Varianter av PSTR, som redan har rätt anteckningar, föredras.

  • _Inout_z_

    En pekare till en null-terminerad teckensträng som kommer att ändras. Det måste vara giltigt före och efter anropet, men det antas att värdet har ändrats. Null-avslutaren kan flyttas, men endast elementen upp till den ursprungliga null-avslutaren kan nås.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    En pekare till en matris som läss av funktionen. Matrisen är av storlekselement s , som alla måste vara giltiga.

    Varianten _bytes_ ger storleken i byte i stället för element. Använd endast den här varianten när storleken inte kan uttryckas som element. Strängar skulle till exempel char bara använda varianten _bytes_ om en liknande funktion som använder wchar_t skulle göra det.

  • _In_reads_z_(s)

    En pekare till en matris som är null-avslutad och har en känd storlek. Elementen upp till null-avslutaren – eller s om det inte finns någon null-terminator – måste vara giltiga i förtillstånd. Om storleken är känd i byte skalar du efter s elementstorleken.

  • _In_reads_or_z_(s)

    En pekare till en matris som är null-avslutad eller har en känd storlek, eller både och. Elementen upp till null-avslutaren – eller s om det inte finns någon null-terminator – måste vara giltiga i förtillstånd. Om storleken är känd i byte skalar du efter s elementstorleken. (Används för familjen strn.)

  • _Out_writes_(s)

    _Out_writes_bytes_(s)

    En pekare till en matris med s element (resp. byte) som skrivs av funktionen. Matriselementen behöver inte vara giltiga i förtillstånd och antalet element som är giltiga efter tillstånd är ospecificerat. Om det finns anteckningar för parametertypen tillämpas de därefter. Tänk till exempel på följande kod.

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

    I det här exemplet tillhandahåller anroparen en buffert med size element för p1. MyStringCopy gör vissa av dessa element giltiga. Ännu viktigare är att annoteringen _Null_terminated_ på PWSTR innebär att p1 är null-avslutad i efterläge. På så sätt är antalet giltiga element fortfarande väldefinierat, men ett visst elementantal krävs inte.

    Varianten _bytes_ ger storleken i byte i stället för element. Använd endast den här varianten när storleken inte kan uttryckas som element. Strängar skulle till exempel char bara använda varianten _bytes_ om en liknande funktion som använder wchar_t skulle göra det.

  • _Out_writes_z_(s)

    En pekare till en matris med s element. Elementen behöver inte vara giltiga i ett tidigare tillstånd. I posttillstånd måste elementen fram till null-terminering – som måste finnas – vara giltiga. Om storleken är känd i byte skalar du efter s elementstorleken.

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    En pekare till en matris som både läss och skrivs till i funktionen. Den har storleken s element och är giltig i förtillståndet och eftertillståndet.

    Varianten _bytes_ ger storleken i byte i stället för element. Använd endast den här varianten när storleken inte kan uttryckas som element. Strängar skulle till exempel char bara använda varianten _bytes_ om en liknande funktion som använder wchar_t skulle göra det.

  • _Inout_updates_z_(s)

    En pekare till en matris som är null-avslutad och har en känd storlek. Elementen fram till och med nollterminatorn – som måste finnas – måste vara giltiga både i det tidigare och senare tillståndet. Värdet i posttillståndet antas skilja sig från värdet i förtillståndet, det inkluderar platsen för nul-terminatorn. Om storleken är känd i byte skalar du efter s elementstorleken.

  • _Out_writes_to_(s,c)

    _Out_writes_bytes_to_(s,c)

    _Out_writes_all_(s)

    _Out_writes_bytes_all_(s)

    En pekare till en matris med s element. Elementen behöver inte vara giltiga i ett tidigare tillstånd. I efter tillståndet måste elementen upp till c-elementet vara giltiga. Varianten _bytes_ kan användas om storleken är känd i byte i stället för antalet element.

    Till exempel:

    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)

    En pekare till en matris som både läss och skrivs av funktionen. Det är av storlekselement s , som alla måste vara giltiga i förtillstånd och c element måste vara giltiga i eftertillstånd.

    Varianten _bytes_ ger storleken i byte i stället för element. Använd endast den här varianten när storleken inte kan uttryckas som element. Strängar skulle till exempel char bara använda varianten _bytes_ om en liknande funktion som använder wchar_t skulle göra det.

  • _Inout_updates_all_(s)

    _Inout_updates_bytes_all_(s)

    En pekare till en matris som både läss och skrivs av funktionen för storlekselement s . Definieras som ekvivalent till:

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

    Med andra ord är varje element som finns i bufferten upp till s i förtillståndet giltigt både i förtillståndet och eftertillståndet.

    Varianten _bytes_ ger storleken i byte i stället för element. Använd endast den här varianten när storleken inte kan uttryckas som element. Strängar skulle till exempel char bara använda varianten _bytes_ om en liknande funktion som använder wchar_t skulle göra det.

  • _In_reads_to_ptr_(p)

    En pekare till en matris för vilken p - _Curr_ (det vill säga p minus _Curr_) är ett giltigt uttryck. Elementen innan p måste vara giltiga i förtillstånd.

    Till exempel:

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

  • _In_reads_to_ptr_z_(p)

    En pekare till en null-avslutad matris för vilket uttryck p - _Curr_ (det vill säga p minus _Curr_) är ett giltigt uttryck. Elementen innan p måste vara giltiga i förtillstånd.

  • _Out_writes_to_ptr_(p)

    En pekare till en matris för vilken p - _Curr_ (det vill säga p minus _Curr_) är ett giltigt uttryck. Elementen innan p behöver inte vara giltiga i företillstånd och måste vara giltiga i eftertillstånd.

  • _Out_writes_to_ptr_z_(p)

    En pekare till en null-avslutad matris för vilken p - _Curr_ (det vill säga p minus _Curr_) är ett giltigt uttryck. Elementen innan p behöver inte vara giltiga i företillstånd och måste vara giltiga i eftertillstånd.

Valfria pekarparametrar

När en pekarparameteranteckning innehåller _opt_anger den att parametern kan vara null. Annars fungerar anteckningen på samma sätt som den version som inte innehåller _opt_. Här är en lista över varianterna _opt_ av pekarparameteranteckningarna:

_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_

Parametrar för utdatapekare

Utpekare parametrar kräver särskild notation för att skilja mellan nullbarhet hos parametern och den angivna platsen.

Anteckningar och beskrivningar

  • _Outptr_

    Parametern kan inte vara null, och i eftertillståndet kan den angivna platsen inte vara null och måste vara giltig.

  • _Outptr_opt_

    Parametern kan vara null, men efter tillståndet kan inte den utpekade platsen vara null och måste vara giltig.

  • _Outptr_result_maybenull_

    Parametern kan inte vara null, och i eftertillståndet kan den refererade platsen vara null.

  • _Outptr_opt_result_maybenull_

    Parametern kan vara null, och i eftertillståndet kan det hänvisade läget vara null.

    I följande tabell infogas ytterligare delsträngar i anteckningsnamnet för att ytterligare kvalificera innebörden av anteckningen. De olika delsträngarna är _z, _COM_, _buffer_, _bytebuffer_och _to_.

Viktigt!

Om gränssnittet som du kommenterar är COM använder du COM-formen för dessa anteckningar. Använd inte COM-anteckningarna med något annat typgränssnitt.

  • _Outptr_result_z_

    _Outptr_opt_result_z_

    _Outptr_result_maybenull_z_

    _Outptr_opt_result_maybenull_z_

    Den returnerade pekaren har kommentaren _Null_terminated_ .

  • _COM_Outptr_

    _COM_Outptr_opt_

    _COM_Outptr_result_maybenull_

    _COM_Outptr_opt_result_maybenull_

    Den returnerade pekaren har COM-semantik, vilket är anledningen till att den har ett _On_failure_ eftervillkor att den returnerade pekaren är null.

  • _Outptr_result_buffer_(s)

    _Outptr_result_bytebuffer_(s)

    _Outptr_opt_result_buffer_(s)

    _Outptr_opt_result_bytebuffer_(s)

    Den returnerade pekaren pekar på en giltig buffert med storlek s element eller byte.

  • _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)

    Den returnerade pekaren pekar på en buffert av storleken s element eller byte, av vilka de första c är giltiga.

Vissa gränssnittskonventioner förutsätter att utdataparametrarna är nullifierade vid fel. Förutom explicit COM-kod föredras formulären i följande tabell. För COM-kod använder du motsvarande COM-formulär som visas i föregående avsnitt.

  • _Result_nullonfailure_

    Ändrar andra anteckningar. Resultatet är inställt på null om funktionen misslyckas.

  • _Result_zeroonfailure_

    Ändrar andra anteckningar. Resultatet är inställt på noll om funktionen misslyckas.

  • _Outptr_result_nullonfailure_

    Den returnerade pekaren pekar på en giltig buffert om funktionen lyckas eller null om funktionen misslyckas. Den här kommentaren gäller för en icke-valfri parameter.

  • _Outptr_opt_result_nullonfailure_

    Den returnerade pekaren pekar på en giltig buffert om funktionen lyckas eller null om funktionen misslyckas. Den här kommentaren är för en valfri parameter.

  • _Outref_result_nullonfailure_

    Den returnerade pekaren pekar på en giltig buffert om funktionen lyckas eller null om funktionen misslyckas. Den här kommentaren är avsedd för en referensparameter.

Referensparametrar för utdata

En vanlig användning av referensparametern är för utdataparametrar. För enkla referensparametrar för utdata, såsom int&, tillhandahåller _Out_ den korrekta semantiken. Men när utdatavärdet är en pekare, till exempel int *&, ger motsvarande pekaranteckningar som _Outptr_ int ** inte rätt semantik. Använd följande sammansatta anteckningar för att kortfattat uttrycka semantiken för referensparametrar för utdata för pekartyper:

Anteckningar och beskrivningar

  • _Outref_

    Resultatet måste vara giltigt efter operationen och får inte vara nullvärde.

  • _Outref_result_maybenull_

    Resultatet måste vara giltigt i efterläge, men kan vara null i efterläge.

  • _Outref_result_buffer_(s)

    Resultatet måste vara giltigt efter operationen och får inte vara nullvärde. Pekar på en giltig buffert med storlek s element.

  • _Outref_result_bytebuffer_(s)

    Resultatet måste vara giltigt efter operationen och får inte vara nullvärde. Pekar på en giltig buffert av storlek s byte.

  • _Outref_result_buffer_to_(s, c)

    Resultatet måste vara giltigt efter operationen och får inte vara nullvärde. Pekar på en buffert med s element, varav de första c är giltiga.

  • _Outref_result_bytebuffer_to_(s, c)

    Resultatet måste vara giltigt efter operationen och får inte vara nullvärde. Pekar på en buffert med s byte, varav de första c är giltiga.

  • _Outref_result_buffer_all_(s)

    Resultatet måste vara giltigt efter operationen och får inte vara nullvärde. Pekar på en giltig buffert av storleken s giltiga element.

  • _Outref_result_bytebuffer_all_(s)

    Resultatet måste vara giltigt efter operationen och får inte vara nullvärde. Pekar på en giltig buffert av s bytes med giltiga element.

  • _Outref_result_buffer_maybenull_(s)

    Resultatet måste vara giltigt i efterläge, men kan vara null i efterläge. Pekar på en giltig buffert med storlek s element.

  • _Outref_result_bytebuffer_maybenull_(s)

    Resultatet måste vara giltigt i efterläge, men kan vara null i efterläge. Pekar på en giltig buffert av storlek s byte.

  • _Outref_result_buffer_to_maybenull_(s, c)

    Resultatet måste vara giltigt i efterläge, men kan vara null i efterläge. Pekar på en buffert med s element, varav de första c är giltiga.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    Resultatet måste vara giltigt i efterstadiet, men kan vara null i post-tillstånd. Pekar på en buffert med s byte, varav de första c är giltiga.

  • _Outref_result_buffer_all_maybenull_(s)

    Resultatet måste vara giltigt i efterstadiet, men kan vara null i post-tillstånd. Pekar på en giltig buffert av storleken s giltiga element.

  • _Outref_result_bytebuffer_all_maybenull_(s)

    Resultatet måste vara giltigt i efterstadiet, men kan vara null i post-tillstånd. Pekar på en giltig buffert av s bytes med giltiga element.

Returnera värden

Returvärdet för en funktion liknar en _Out_ parameter men ligger på en annan nivå av referens och du behöver inte tänka på begreppet pekare till resultatet. För följande anvisningar är returvärdet det kommenterade objektet – en skalär, en pekare till en struktur eller en pekare till en buffert. Dessa anteckningar har samma semantik som motsvarande _Out_ anteckning.

_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_

Formatera strängparametrar

  • _Printf_format_string_ Anger att parametern är en formatsträng som ska användas i ett printf uttryck.

    Exempel

    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_ Anger att parametern är en formatsträng som ska användas i ett scanf uttryck.

    Exempel

    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_ Anger att parametern är en formatsträng som ska användas i ett scanf_s uttryck.

    Exempel

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

Andra vanliga anteckningar

Anteckningar och beskrivningar

  • _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)

    Parametern, fältet eller resultatet ligger i intervallet (inklusive) från low till hi. Motsvarar _Satisfies_(_Curr_ >= low && _Curr_ <= hi) som tillämpas på det kommenterade objektet tillsammans med lämpliga villkor för förtillstånd och eftertillstånd.

    Viktigt!

    Även om namnen innehåller "in" och "out", gäller semantiken för _In_ och _Out_inte dessa anmärkningar.

  • _Pre_equal_to_(expr)

    _Post_equal_to_(expr)

    Det kommenterade värdet är exakt expr. Motsvarar _Satisfies_(_Curr_ == expr) som tillämpas på det kommenterade objektet tillsammans med lämpliga villkor för förtillstånd och eftertillstånd.

  • _Struct_size_bytes_(size)

    Gäller för en struct- eller klassdeklaration. Anger att ett giltigt objekt av den typen kan vara större än den deklarerade typen, med antalet byte som anges av size. Till exempel:

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

    Buffertstorleken i byte av en parameter pM av typen MyStruct * anses sedan vara:

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

Se även

  • Last updated on