Bagikan melalui

Menganotasi parameter fungsi dan mengembalikan nilai

  • Artikel

Artikel ini menjelaskan penggunaan anotasi umum untuk parameter fungsi sederhana—skalar, dan penunjuk ke struktur dan kelas—dan sebagian besar jenis buffer. Artikel ini juga memperlihatkan pola penggunaan umum untuk anotasi. Untuk anotasi tambahan yang terkait dengan fungsi, lihat Menganotasi perilaku fungsi.

Parameter penunjuk

Untuk anotasi dalam tabel berikut, saat parameter pointer dianotasi, penganalisis melaporkan kesalahan jika pointer null. Anotasi ini berlaku untuk penunjuk dan item data apa pun yang ditujukkan.

Anotasi dan deskripsi

  • _In_

    Anotasi parameter input yang skalar, struktur, penunjuk ke struktur dan segitunya. Secara eksplisit dapat digunakan pada skalar sederhana. Parameter harus valid dalam pra-status dan tidak akan dimodifikasi.

  • _Out_

    Membuat anotasi parameter output yang bersifat skalar, struktur, penunjuk ke struktur dan segitunya. Jangan terapkan anotasi ini ke objek yang tidak dapat mengembalikan nilai—misalnya, skalar yang diteruskan oleh nilai. Parameter tidak harus valid dalam pra-status tetapi harus valid dalam status pasca-status.

  • _Inout_

    Membuat anotasi parameter yang akan diubah oleh fungsi . Ini harus valid dalam pra-status dan pasca-status, tetapi diasumsikan memiliki nilai yang berbeda sebelum dan sesudah panggilan. Harus berlaku untuk nilai yang dapat dimodifikasi.

  • _In_z_

    Penunjuk ke string null-terminated yang digunakan sebagai input. String harus valid dalam pra-status. Varian PSTR, yang sudah memiliki anotasi yang benar, lebih disukai.

  • _Inout_z_

    Penunjuk ke array karakter null-terminated yang akan dimodifikasi. Ini harus valid sebelum dan sesudah panggilan, tetapi diasumsikan nilainya telah berubah. Terminator null dapat dipindahkan, tetapi hanya elemen hingga terminator null asli yang dapat diakses.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    Penunjuk ke array, yang dibaca oleh fungsi . Array berukuran elemen ukuran s , yang semuanya harus valid.

    _bytes_ Varian memberikan ukuran dalam byte alih-alih elemen. Gunakan varian ini hanya ketika ukuran tidak dapat diekspresikan sebagai elemen. Misalnya, char string akan menggunakan _bytes_ varian hanya jika fungsi serupa yang menggunakannya wchar_t .

  • _In_reads_z_(s)

    Penunjuk ke array yang dihentikan null dan memiliki ukuran yang diketahui. Elemen hingga terminator null—atau s jika tidak ada terminator null—harus valid dalam pra-status. Jika ukurannya diketahui dalam byte, skalakan s menurut ukuran elemen.

  • _In_reads_or_z_(s)

    Penunjuk ke array yang dihentikan null atau memiliki ukuran yang diketahui, atau keduanya. Elemen hingga terminator null—atau s jika tidak ada terminator null—harus valid dalam pra-status. Jika ukurannya diketahui dalam byte, skalakan s menurut ukuran elemen. (Digunakan untuk strn keluarga.)

  • _Out_writes_(s)

    _Out_writes_bytes_(s)

    Penunjuk ke array s elemen (resp. byte) yang akan ditulis oleh fungsi. Elemen array tidak harus valid dalam pra-status, dan jumlah elemen yang valid dalam pasca-status tidak ditentukan. Jika ada anotasi pada jenis parameter, anotasi diterapkan dalam pasca-status. Sebagai contoh, perhatikan kode berikut.

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

    Dalam contoh ini, pemanggil menyediakan buffer size elemen untuk p1. MyStringCopy membuat beberapa elemen tersebut valid. Lebih penting lagi, _Null_terminated_ anotasi pada PWSTR berarti bahwa p1 null-dihentikan dalam pasca-status. Dengan cara ini, jumlah elemen yang valid masih terdefinisi dengan baik, tetapi jumlah elemen tertentu tidak diperlukan.

    _bytes_ Varian memberikan ukuran dalam byte alih-alih elemen. Gunakan varian ini hanya ketika ukuran tidak dapat diekspresikan sebagai elemen. Misalnya, char string akan menggunakan _bytes_ varian hanya jika fungsi serupa yang menggunakannya wchar_t .

  • _Out_writes_z_(s)

    Penunjuk ke array s elemen. Elemen tidak harus valid dalam pra-status. Dalam status pasca-status, elemen hingga hingga terminator null—yang harus ada—harus valid. Jika ukurannya diketahui dalam byte, skalakan s menurut ukuran elemen.

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    Penunjuk ke array, yang dibaca dan ditulis dalam fungsi . Ini dari elemen ukuran s , dan valid dalam pra-status dan pasca-status.

    _bytes_ Varian memberikan ukuran dalam byte alih-alih elemen. Gunakan varian ini hanya ketika ukuran tidak dapat diekspresikan sebagai elemen. Misalnya, char string akan menggunakan _bytes_ varian hanya jika fungsi serupa yang menggunakannya wchar_t .

  • _Inout_updates_z_(s)

    Penunjuk ke array yang dihentikan null dan memiliki ukuran yang diketahui. Elemen sampai melalui terminator null—yang harus ada—harus valid dalam status pra-status dan pasca-status. Nilai dalam pasca-status diduga berbeda dari nilai dalam pra-status; yang mencakup lokasi terminator null. Jika ukurannya diketahui dalam byte, skalakan s menurut ukuran elemen.

  • _Out_writes_to_(s,c)

    _Out_writes_bytes_to_(s,c)

    _Out_writes_all_(s)

    _Out_writes_bytes_all_(s)

    Penunjuk ke array s elemen. Elemen tidak harus valid dalam pra-status. Dalam pasca-status, elemen hingga celemen -th harus valid. _bytes_ Varian dapat digunakan jika ukurannya diketahui dalam byte daripada jumlah elemen.

    Contohnya:

    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)

    Penunjuk ke array, yang dibaca dan ditulis oleh fungsi . Ini dari elemen ukuran s , yang semuanya harus valid dalam pra-status, dan c elemen harus valid dalam pasca-status.

    _bytes_ Varian memberikan ukuran dalam byte alih-alih elemen. Gunakan varian ini hanya ketika ukuran tidak dapat diekspresikan sebagai elemen. Misalnya, char string akan menggunakan _bytes_ varian hanya jika fungsi serupa yang menggunakannya wchar_t .

  • _Inout_updates_all_(s)

    _Inout_updates_bytes_all_(s)

    Penunjuk ke array, yang dibaca dan ditulis oleh fungsi elemen ukuran s . Didefinisikan setara dengan:

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

    Dengan kata lain, setiap elemen yang ada di buffer hingga s dalam pra-status valid dalam pra-status dan pasca-status.

    _bytes_ Varian memberikan ukuran dalam byte alih-alih elemen. Gunakan varian ini hanya ketika ukuran tidak dapat diekspresikan sebagai elemen. Misalnya, char string akan menggunakan _bytes_ varian hanya jika fungsi serupa yang menggunakannya wchar_t .

  • _In_reads_to_ptr_(p)

    Penunjuk ke array yang p - _Curr_ (yaitu, p minus _Curr_) adalah ekspresi yang valid. Elemen sebelumnya p harus valid dalam pra-status.

    Contohnya:

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

  • _In_reads_to_ptr_z_(p)

    Penunjuk ke array null-terminated yang ekspresinya p - _Curr_ (yaitu, p minus _Curr_) adalah ekspresi yang valid. Elemen sebelumnya p harus valid dalam pra-status.

  • _Out_writes_to_ptr_(p)

    Penunjuk ke array yang p - _Curr_ (yaitu, p minus _Curr_) adalah ekspresi yang valid. Elemen sebelumnya p tidak harus valid dalam pra-status dan harus valid dalam status pasca-status.

  • _Out_writes_to_ptr_z_(p)

    Pointer ke array null-terminated yang p - _Curr_ (yaitu, p minus _Curr_) adalah ekspresi yang valid. Elemen sebelumnya p tidak harus valid dalam pra-status dan harus valid dalam status pasca-status.

Parameter penunjuk opsional

Ketika anotasi parameter pointer menyertakan _opt_, itu menunjukkan bahwa parameter mungkin null. Jika tidak, anotasi berulah sama dengan versi yang tidak menyertakan _opt_. Berikut adalah daftar _opt_ varian anotasi parameter pointer:

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

Parameter penunjuk output

Parameter penunjuk output memerlukan notasi khusus untuk membedakan ketimpangan pada parameter dan lokasi yang ditujukan ke.

Anotasi dan deskripsi

  • _Outptr_

    Parameter tidak boleh null, dan dalam status pasca lokasi yang ditunjukkan ke tidak boleh null dan harus valid.

  • _Outptr_opt_

    Parameter mungkin null, tetapi dalam status pasca lokasi yang ditunjukkan ke tidak boleh null dan harus valid.

  • _Outptr_result_maybenull_

    Parameter tidak boleh null, dan dalam status pasca lokasi yang ditunjukkan ke bisa null.

  • _Outptr_opt_result_maybenull_

    Parameter mungkin null, dan dalam status pasca lokasi yang ditunjukkan ke bisa null.

    Dalam tabel berikut, substring tambahan disisipkan ke dalam nama anotasi untuk lebih memenuhi syarat arti anotasi. Berbagai substring adalah _z, , _COM_, _buffer__bytebuffer_, dan _to_.

Penting

Jika antarmuka yang Anda anotasi adalah COM, gunakan bentuk COM dari anotasi ini. Jangan gunakan anotasi COM dengan antarmuka jenis lainnya.

  • _Outptr_result_z_

    _Outptr_opt_result_z_

    _Outptr_result_maybenull_z_

    _Outptr_opt_result_maybenull_z_

    Pointer yang dikembalikan memiliki _Null_terminated_ anotasi.

  • _COM_Outptr_

    _COM_Outptr_opt_

    _COM_Outptr_result_maybenull_

    _COM_Outptr_opt_result_maybenull_

    Pointer yang dikembalikan memiliki semantik COM, itulah sebabnya ia membawa _On_failure_ kondisi pasca-bahwa pointer yang dikembalikan null.

  • _Outptr_result_buffer_(s)

    _Outptr_result_bytebuffer_(s)

    _Outptr_opt_result_buffer_(s)

    _Outptr_opt_result_bytebuffer_(s)

    Pointer yang dikembalikan menunjuk ke buffer elemen ukuran s atau byte yang valid.

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

    Pointer yang dikembalikan menunjuk ke buffer elemen ukuran s atau byte, yang pertama c valid.

Konvensi antarmuka tertentu berasumsi bahwa parameter output nullified on failure. Kecuali untuk kode COM secara eksplisit, formulir dalam tabel berikut lebih disukai. Untuk kode COM, gunakan formulir COM terkait yang tercantum di bagian sebelumnya.

  • _Result_nullonfailure_

    Memodifikasi anotasi lainnya. Hasilnya diatur ke null jika fungsi gagal.

  • _Result_zeroonfailure_

    Memodifikasi anotasi lainnya. Hasilnya diatur ke nol jika fungsi gagal.

  • _Outptr_result_nullonfailure_

    Pointer yang dikembalikan menunjuk ke buffer yang valid jika fungsi berhasil, atau null jika fungsi gagal. Anotasi ini untuk parameter non-opsional.

  • _Outptr_opt_result_nullonfailure_

    Pointer yang dikembalikan menunjuk ke buffer yang valid jika fungsi berhasil, atau null jika fungsi gagal. Anotasi ini untuk parameter opsional.

  • _Outref_result_nullonfailure_

    Pointer yang dikembalikan menunjuk ke buffer yang valid jika fungsi berhasil, atau null jika fungsi gagal. Anotasi ini untuk parameter referensi.

Parameter referensi output

Penggunaan umum parameter referensi adalah untuk parameter output. Untuk parameter referensi output sederhana seperti int&, _Out_ menyediakan semantik yang benar. Namun, ketika nilai output adalah pointer seperti int *&, anotasi pointer yang setara seperti _Outptr_ int ** tidak memberikan semantik yang benar. Untuk secara ringkas mengekspresikan semantik parameter referensi output untuk jenis penunjuk, gunakan anotasi komposit ini:

Anotasi dan deskripsi

  • _Outref_

    Hasil harus valid dalam pasca-status dan tidak boleh null.

  • _Outref_result_maybenull_

    Hasil harus valid dalam pasca-status, tetapi mungkin null dalam pasca-status.

  • _Outref_result_buffer_(s)

    Hasil harus valid dalam pasca-status dan tidak boleh null. Menunjuk ke buffer elemen ukuran s yang valid.

  • _Outref_result_bytebuffer_(s)

    Hasil harus valid dalam pasca-status dan tidak boleh null. Menunjuk ke buffer byte ukuran s yang valid.

  • _Outref_result_buffer_to_(s, c)

    Hasil harus valid dalam pasca-status dan tidak boleh null. Menunjuk ke buffer s elemen, yang pertama c valid.

  • _Outref_result_bytebuffer_to_(s, c)

    Hasil harus valid dalam pasca-status dan tidak boleh null. Menunjuk ke buffer s byte yang pertama c valid.

  • _Outref_result_buffer_all_(s)

    Hasil harus valid dalam pasca-status dan tidak boleh null. Menunjuk ke buffer elemen valid ukuran s yang valid.

  • _Outref_result_bytebuffer_all_(s)

    Hasil harus valid dalam pasca-status dan tidak boleh null. Menunjuk ke buffer valid byte s elemen yang valid.

  • _Outref_result_buffer_maybenull_(s)

    Hasil harus valid dalam pasca-status, tetapi mungkin null dalam pasca-status. Menunjuk ke buffer elemen ukuran s yang valid.

  • _Outref_result_bytebuffer_maybenull_(s)

    Hasil harus valid dalam pasca-status, tetapi mungkin null dalam pasca-status. Menunjuk ke buffer byte ukuran s yang valid.

  • _Outref_result_buffer_to_maybenull_(s, c)

    Hasil harus valid dalam pasca-status, tetapi mungkin null dalam pasca-status. Menunjuk ke buffer s elemen, yang pertama c valid.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    Hasil harus valid dalam pasca-status, tetapi mungkin null dalam status pos. Menunjuk ke buffer s byte yang pertama c valid.

  • _Outref_result_buffer_all_maybenull_(s)

    Hasil harus valid dalam pasca-status, tetapi mungkin null dalam status pos. Menunjuk ke buffer elemen valid ukuran s yang valid.

  • _Outref_result_bytebuffer_all_maybenull_(s)

    Hasil harus valid dalam pasca-status, tetapi mungkin null dalam status pos. Menunjuk ke buffer valid byte s elemen yang valid.

Mengembalikan nilai

Nilai pengembalian fungsi menyerupai _Out_ parameter tetapi berada pada tingkat de-referensi yang berbeda, dan Anda tidak perlu mempertimbangkan konsep pointer ke hasil. Untuk anotasi berikut, nilai yang dikembalikan adalah objek yang dianotasikan—skalar, penunjuk ke struct, atau pointer ke buffer. Anotasi ini memiliki semantik yang sama dengan anotasi yang sesuai _Out_ .

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

Format parameter string

  • _Printf_format_string_ Menunjukkan bahwa parameter adalah string format untuk digunakan dalam printf ekspresi.

    Contoh

    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_ Menunjukkan bahwa parameter adalah string format untuk digunakan dalam scanf ekspresi.

    Contoh

    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_ Menunjukkan bahwa parameter adalah string format untuk digunakan dalam scanf_s ekspresi.

    Contoh

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

Anotasi umum lainnya

Anotasi dan deskripsi

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

    Parameter, bidang, atau hasil dalam rentang (inklusif) dari low ke hi. Setara dengan _Satisfies_(_Curr_ >= low && _Curr_ <= hi) yang diterapkan ke objek yang dianotasikan bersama dengan kondisi pra-status atau pasca-status yang sesuai.

    Penting

    Meskipun nama-nama berisi "in" dan "out", semantik _In_ dan _Out_ tidak berlaku untuk anotasi ini.

  • _Pre_equal_to_(expr)

    _Post_equal_to_(expr)

    Nilai yang dianotasi persis expr. Setara dengan _Satisfies_(_Curr_ == expr) yang diterapkan ke objek yang dianotasikan bersama dengan kondisi pra-status atau pasca-status yang sesuai.

  • _Struct_size_bytes_(size)

    Berlaku untuk struct atau deklarasi kelas. Menunjukkan bahwa objek yang valid dari jenis tersebut mungkin lebih besar dari jenis yang dideklarasikan, dengan jumlah byte yang diberikan oleh size. Contohnya:

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

    Ukuran buffer dalam byte dari parameter pM jenis MyStruct * kemudian diambil untuk menjadi:

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

Baca juga