Delen via

Aantekeningen toevoegen aan functieparameters en retourwaarden

In dit artikel worden typische toepassingen van aantekeningen voor eenvoudige functieparameters, scalaire waarden en aanwijzers naar structuren en klassen, en de meeste soorten buffers beschreven. Dit artikel bevat ook algemene gebruikspatronen voor aantekeningen. Zie Annotating function behavior (Aantekeningen toevoegen aan functiegedrag) voor aanvullende aantekeningen die betrekking hebben op functies.

Aanwijzerparameters

Voor de aantekeningen in de volgende tabel, wanneer een aanwijzerparameter wordt geannoteerd, rapporteert de analyse een fout als de aanwijzer null is. Deze aantekening is van toepassing op aanwijzers en op gegevensitems waarnaar wordt verwezen.

Aantekeningen en beschrijvingen

  • _In_

    Aantekeningen maken bij invoerparameters die scalaire, structuren, aanwijzers naar structuren en dergelijke zijn. Kan expliciet worden gebruikt voor eenvoudige scalaire waarden. De parameter moet geldig zijn in de oorspronkelijke staat en zal niet worden gewijzigd.

  • _Out_

    Aantekeningen maken bij uitvoerparameters die scalaire, structuren, aanwijzers naar structuren en dergelijke zijn. Pas deze aantekening niet toe op een object dat geen waarde kan retourneren, bijvoorbeeld een scalaire waarde die wordt doorgegeven door een waarde. De parameter hoeft niet geldig te zijn in de beginstatus, maar moet geldig zijn in de eindstatus.

  • _Inout_

    Hiermee maakt u aantekeningen voor een parameter die door de functie wordt gewijzigd. Deze moet geldig zijn in zowel de status vooraf als na de aanroep, maar wordt ervan uitgegaan dat deze verschillende waarden vóór en na de aanroep heeft. Moet van toepassing zijn op een wijzigbare waarde.

  • _In_z_

    Een aanwijzer naar een door null beëindigde tekenreeks die wordt gebruikt als invoer. De tekenreeks moet geldig zijn in de voorafgaande toestand. Varianten van PSTR, die al de juiste aantekeningen hebben, hebben de voorkeur.

  • _Inout_z_

    Een aanwijzer naar een door null beëindigde tekenmatrix die wordt gewijzigd. Deze moet geldig zijn voor en na de aanroep, maar wordt ervan uitgegaan dat de waarde is gewijzigd. Het null-eindteken kan worden verplaatst, maar alleen de elementen tot de oorspronkelijke null-eindteken kunnen worden benaderd.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    Een aanwijzer naar een matrix, die wordt gelezen door de functie. De array heeft een grootte van s elementen, die allemaal geldig moeten zijn.

    De _bytes_ variant geeft de grootte in bytes in plaats van elementen. Gebruik deze variant alleen als de grootte niet als elementen kan worden uitgedrukt. Tekenreeksen gebruiken de char variant alleen als een vergelijkbare functie, die _bytes_ gebruikt, dat ook zou doen.

  • _In_reads_z_(s)

    Een aanwijzer naar een matrix die null-beëindigd is en een bekende grootte heeft. De elementen tot aan het nul-eindteken (of s als er geen nul-eindteken is) moeten geldig zijn in de voorafgaande status. Als de grootte in bytes bekend is, schaal s naar de grootte van het element.

  • _In_reads_or_z_(s)

    Een aanwijzer naar een matrix die null-beëindigd is of een bekende grootte heeft, of beide. De elementen tot aan het nul-eindteken (of s als er geen nul-eindteken is) moeten geldig zijn in de voorafgaande status. Als de grootte in bytes bekend is, schaal s naar de grootte van het element. (Wordt gebruikt voor de strn familie.)

  • _Out_writes_(s)

    _Out_writes_bytes_(s)

    Een aanwijzer naar een matrix met s elementen (resp. bytes) die door de functie worden geschreven. De array-elementen hoeven niet geldig te zijn in de prestatus en het aantal elementen dat geldig is in de poststatus is niet opgegeven. Als er aantekeningen zijn voor het parametertype, worden deze toegepast in de naverwerking. Denk bijvoorbeeld aan de volgende code.

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

    In dit voorbeeld biedt de aanroeper een buffer van size elementen voor p1. MyStringCopy maakt sommige van deze elementen geldig. Belangrijker is dat de _Null_terminated_ aantekening op PWSTR betekent dat p1 nul-beëindigd is in de poststatus. Op deze manier is het aantal geldige elementen nog steeds goed gedefinieerd, maar is er geen specifiek aantal elementen vereist.

    De _bytes_ variant geeft de grootte in bytes in plaats van elementen. Gebruik deze variant alleen als de grootte niet als elementen kan worden uitgedrukt. Tekenreeksen gebruiken de char variant alleen als een vergelijkbare functie, die _bytes_ gebruikt, dat ook zou doen.

  • _Out_writes_z_(s)

    Een aanwijzer naar een matrix met s elementen. De elementen hoeven niet geldig te zijn in de voorgaande staat. Na de post-toestand moeten de elementen tot en met de null-terminator, die aanwezig moet zijn, geldig zijn. Als de grootte in bytes bekend is, schaal s naar de grootte van het element.

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    Een aanwijzer naar een matrix, waarnaar zowel wordt gelezen als geschreven in de functie. Het heeft een grootte van s elementen, en is geldig in de voor- en nastatus.

    De _bytes_ variant geeft de grootte in bytes in plaats van elementen. Gebruik deze variant alleen als de grootte niet als elementen kan worden uitgedrukt. Tekenreeksen gebruiken de char variant alleen als een vergelijkbare functie, die _bytes_ gebruikt, dat ook zou doen.

  • _Inout_updates_z_(s)

    Een aanwijzer naar een matrix die null-beëindigd is en een bekende grootte heeft. De elementen tot en met de nulpunt, die aanwezig moet zijn, moeten geldig zijn in zowel de toestand vóór als na. De waarde in de posttoestand wordt verondersteld anders te zijn dan de waarde in de pretoestand; inclusief de locatie van de nulterminatie. Als de grootte in bytes bekend is, schaal s naar de grootte van het element.

  • _Out_writes_to_(s,c)

    _Out_writes_bytes_to_(s,c)

    _Out_writes_all_(s)

    _Out_writes_bytes_all_(s)

    Een aanwijzer naar een matrix met s elementen. De elementen hoeven niet geldig te zijn in de voorgaande staat. Na de post-status moeten de elementen tot en met het cde element geldig zijn. De _bytes_ variant kan worden gebruikt als de grootte bekend is in bytes in plaats van het aantal elementen.

    Voorbeeld:

    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)

    Een aanwijzer naar een matrix, die zowel wordt gelezen als geschreven door de functie. Het bestaat uit s elementen van grootte, die allemaal geldig moeten zijn in de voorstatus en c elementen moeten geldig zijn in de poststatus.

    De _bytes_ variant geeft de grootte in bytes in plaats van elementen. Gebruik deze variant alleen als de grootte niet als elementen kan worden uitgedrukt. Tekenreeksen gebruiken de char variant alleen als een vergelijkbare functie, die _bytes_ gebruikt, dat ook zou doen.

  • _Inout_updates_all_(s)

    _Inout_updates_bytes_all_(s)

    Een aanwijzer naar een matrix, die zowel wordt gelezen als geschreven door de functie van grootte-elementen s . Gedefinieerd als gelijkwaardig aan:

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

    Met andere woorden, elk element dat in de buffer tot s in de pre-toestand bestaat, is geldig in zowel de pre-toestand als de post-toestand.

    De _bytes_ variant geeft de grootte in bytes in plaats van elementen. Gebruik deze variant alleen als de grootte niet als elementen kan worden uitgedrukt. Tekenreeksen gebruiken de char variant alleen als een vergelijkbare functie, die _bytes_ gebruikt, dat ook zou doen.

  • _In_reads_to_ptr_(p)

    Een aanwijzer naar een array waarvoor p - _Curr_ (dat wil zeggen, p min _Curr_) een geldige expressie is. De elementen vóór p moeten geldig zijn in de voorafgaande toestand.

    Voorbeeld:

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

  • _In_reads_to_ptr_z_(p)

    Een aanwijzer naar een door null beëindigde matrix waarvoor een expressie p - _Curr_ (dat wil p zeggen min _Curr_) een geldige expressie is. De elementen vóór p moeten geldig zijn in de voorafgaande toestand.

  • _Out_writes_to_ptr_(p)

    Een aanwijzer naar een array waarvoor p - _Curr_ (dat wil zeggen, p min _Curr_) een geldige expressie is. De elementen hoeven vóór p niet geldig te zijn in de prestatus en moeten geldig zijn in de poststatus.

  • _Out_writes_to_ptr_z_(p)

    Een aanwijzer naar een null-beëindigde matrix waarvoor p - _Curr_ (dat wil p zeggen min _Curr_) een geldige expressie is. De elementen hoeven vóór p niet geldig te zijn in de prestatus en moeten geldig zijn in de poststatus.

Optionele aanwijzerparameters

Wanneer een aanwijzerparameteraantekening bevat _opt_, geeft deze aan dat de parameter null kan zijn. Anders gedraagt de aantekening zich hetzelfde als de versie zonder _opt_. Hier volgt een lijst met de _opt_ varianten van de aanwijzerparameteraantekeningen:

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

Parameters voor uitvoerpointer

Voor de parameters van de uitvoerwijzer is een speciale notatie vereist om de nullness voor de parameter en de locatie waarop wordt gewezen te verduidelijken.

Aantekeningen en beschrijvingen

  • _Outptr_

    De parameter kan niet null zijn, en in de toestand daarna kan de aangewezen locatie niet null zijn en moet geldig zijn.

  • _Outptr_opt_

    De parameter kan null zijn, maar in de posttoestand kan de doellocatie niet null zijn en moet geldig zijn.

  • _Outptr_result_maybenull_

    De parameter kan niet null zijn en in de posttoestand kan de doellocatie null zijn.

  • _Outptr_opt_result_maybenull_

    Een parameter kan null zijn, en in de nablijvende toestand kan de verwezen locatie null zijn.

    In de volgende tabel worden extra subtekenreeksen ingevoegd in de naam van de aantekening om de betekenis van de aantekening verder te kwalificeren. De verschillende subtekenreeksen zijn _z, _COM_, _buffer_, en _bytebuffer__to_.

Belangrijk

Als de interface die u aantekeningen maakt COM is, gebruikt u de COM-vorm van deze aantekeningen. Gebruik de COM-aantekeningen niet met een andere typeinterface.

  • _Outptr_result_z_

    _Outptr_opt_result_z_

    _Outptr_result_maybenull_z_

    _Outptr_opt_result_maybenull_z_

    De geretourneerde aanwijzer heeft de _Null_terminated_ aantekening.

  • _COM_Outptr_

    _COM_Outptr_opt_

    _COM_Outptr_result_maybenull_

    _COM_Outptr_opt_result_maybenull_

    De geretourneerde aanwijzer heeft COM-semantiek, daarom heeft deze een _On_failure_ postvoorwaarde dat de geretourneerde aanwijzer null is.

  • _Outptr_result_buffer_(s)

    _Outptr_result_bytebuffer_(s)

    _Outptr_opt_result_buffer_(s)

    _Outptr_opt_result_bytebuffer_(s)

    De geretourneerde aanwijzer wijst naar een geldige buffer met een grootte van s elementen of bytes.

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

    De geretourneerde aanwijzer verwijst naar een buffer van grootte-elementen s of bytes waarvan de eerste c geldig is.

Bij bepaalde interfaceconventies wordt ervan uitgegaan dat uitvoerparameters op nul worden gezet bij een fout. Behalve voor expliciet COM-code hebben de formulieren in de volgende tabel de voorkeur. Gebruik voor COM-code de bijbehorende COM-formulieren die in de vorige sectie worden vermeld.

  • _Result_nullonfailure_

    Hiermee wijzigt u andere aantekeningen. Het resultaat wordt ingesteld op null als de functie mislukt.

  • _Result_zeroonfailure_

    Hiermee wijzigt u andere aantekeningen. Het resultaat wordt ingesteld op nul als de functie mislukt.

  • _Outptr_result_nullonfailure_

    De geretourneerde aanwijzer verwijst naar een geldige buffer als de functie slaagt of null als de functie mislukt. Deze aantekening is bedoeld voor een niet-optionele parameter.

  • _Outptr_opt_result_nullonfailure_

    De geretourneerde aanwijzer verwijst naar een geldige buffer als de functie slaagt of null als de functie mislukt. Deze aantekening is bedoeld voor een optionele parameter.

  • _Outref_result_nullonfailure_

    De geretourneerde aanwijzer verwijst naar een geldige buffer als de functie slaagt of null als de functie mislukt. Deze aantekening is bedoeld voor een referentieparameter.

Uitvoerreferentieparameters

Een veelvoorkomend gebruik van de referentieparameter is voor uitvoerparameters. Voor eenvoudige uitvoerreferentieparameters, zoals int&, _Out_ biedt de juiste semantiek. Als de uitvoerwaarde echter een aanwijzer is zoals int *&, geven de equivalente aanwijzeraantekeningen, zoals _Outptr_ int ** niet de juiste semantiek. Als u beknopt de semantiek van uitvoerreferentieparameters voor aanwijzertypen wilt uitdrukken, gebruikt u deze samengestelde aantekeningen:

Aantekeningen en beschrijvingen

  • _Outref_

    Het resultaat moet geldig zijn na de uitvoering en mag niet nul zijn.

  • _Outref_result_maybenull_

    Het resultaat moet geldig zijn in de eindtoestand, maar kan nul zijn in de eindtoestand.

  • _Outref_result_buffer_(s)

    Het resultaat moet geldig zijn na de uitvoering en mag niet nul zijn. Verwijst naar een geldige buffer van grootte s elementen.

  • _Outref_result_bytebuffer_(s)

    Het resultaat moet geldig zijn na de uitvoering en mag niet nul zijn. Verwijst naar een geldige buffer van grootte s bytes.

  • _Outref_result_buffer_to_(s, c)

    Het resultaat moet geldig zijn na de uitvoering en mag niet nul zijn. Verwijst naar buffer van s elementen waarvan de eerste c geldig zijn.

  • _Outref_result_bytebuffer_to_(s, c)

    Het resultaat moet geldig zijn na de uitvoering en mag niet nul zijn. Verwijst naar buffer van s bytes waarvan de eerste c geldig zijn.

  • _Outref_result_buffer_all_(s)

    Het resultaat moet geldig zijn na de uitvoering en mag niet nul zijn. Verwijst naar een geldige buffer met een grootte van s geldige elementen.

  • _Outref_result_bytebuffer_all_(s)

    Het resultaat moet geldig zijn na de uitvoering en mag niet nul zijn. Verwijst naar een geldige buffer van s bytes aan geldige elementen.

  • _Outref_result_buffer_maybenull_(s)

    Het resultaat moet geldig zijn in de eindtoestand, maar kan nul zijn in de eindtoestand. Verwijst naar een geldige buffer van grootte s elementen.

  • _Outref_result_bytebuffer_maybenull_(s)

    Het resultaat moet geldig zijn in de eindtoestand, maar kan nul zijn in de eindtoestand. Verwijst naar een geldige buffer van grootte s bytes.

  • _Outref_result_buffer_to_maybenull_(s, c)

    Het resultaat moet geldig zijn in de eindtoestand, maar kan nul zijn in de eindtoestand. Verwijst naar buffer van s elementen waarvan de eerste c geldig zijn.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    Het resultaat moet geldig zijn in de poststatus, maar kan null zijn in de poststatus. Verwijst naar buffer van s bytes waarvan de eerste c geldig zijn.

  • _Outref_result_buffer_all_maybenull_(s)

    Het resultaat moet geldig zijn in de poststatus, maar kan null zijn in de poststatus. Verwijst naar een geldige buffer met een grootte van s geldige elementen.

  • _Outref_result_bytebuffer_all_maybenull_(s)

    Het resultaat moet geldig zijn in de poststatus, maar kan null zijn in de poststatus. Verwijst naar een geldige buffer van s bytes aan geldige elementen.

Retourwaarden

De retourwaarde van een functie lijkt op een _Out_ parameter, maar bevindt zich op een ander niveau van dereferentie, en u hoeft zich geen zorgen te maken over het concept van een pointer naar het resultaat. Voor de volgende aantekeningen is de retourwaarde het geannoteerde object: een scalaire waarde, een aanwijzer naar een struct of een aanwijzer naar een buffer. Deze aantekeningen hebben dezelfde semantiek als de bijbehorende _Out_ aantekening.

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

Tekenreeksparameters opmaken

  • _Printf_format_string_ Geeft aan dat de parameter een notatietekenreeks is voor gebruik in een printf expressie.

    Voorbeeld

    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_ Geeft aan dat de parameter een notatietekenreeks is voor gebruik in een scanf expressie.

    Voorbeeld

    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_ Geeft aan dat de parameter een notatietekenreeks is voor gebruik in een scanf_s expressie.

    Voorbeeld

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

Andere algemene aantekeningen

Aantekeningen en beschrijvingen

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

    De parameter, het veld of het resultaat bevindt zich in het bereik (inclusief) van low tot hi. Gelijk aan _Satisfies_(_Curr_ >= low && _Curr_ <= hi), dat wordt toegepast op het geannoteerde object, samen met de juiste voorafgaande of volgende toestandsvoorwaarden.

    Belangrijk

    Hoewel de namen 'in' en 'uit' bevatten, zijn de semantiek van _In_ en _Out_niet van toepassing op deze aantekeningen.

  • _Pre_equal_to_(expr)

    _Post_equal_to_(expr)

    De geannoteerde waarde is precies expr. Gelijk aan _Satisfies_(_Curr_ == expr), dat wordt toegepast op het geannoteerde object, samen met de juiste voorafgaande of volgende toestandsvoorwaarden.

  • _Struct_size_bytes_(size)

    Van toepassing op een struct- of klassedeclaratie. Hiermee wordt aangegeven dat een geldig object van dat type groter kan zijn dan het opgegeven type, waarbij het aantal bytes wordt bepaald door size. Voorbeeld:

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

    De buffergrootte in bytes van een parameter pM van het type MyStruct * wordt vervolgens als volgt beschouwd:

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

Zie ook

  • Last updated on