Menganotasi perilaku fungsi

  • Artikel

Selain menganotasi parameter fungsi dan mengembalikan nilai, Anda dapat membuat anotasi properti dari seluruh fungsi.

Anotasi fungsi

Anotasi berikut berlaku untuk fungsi secara keseluruhan dan menjelaskan bagaimana perilakunya atau apa yang diharapkan benar.

Anotasi Deskripsi
_Called_from_function_class_(name) Tidak dimaksudkan untuk berdiri sendiri; sebaliknya, ini adalah predikat yang akan digunakan dengan _When_ anotasi. Untuk informasi selengkapnya, lihat Menentukan Kapan dan Di mana Anotasi Berlaku.

Parameter name adalah string arbitrer yang juga muncul dalam anotasi _Function_class_ dalam deklarasi beberapa fungsi. _Called_from_function_class_ mengembalikan nonzero jika fungsi yang saat ini sedang dianalisis dianotasi dengan menggunakan _Function_class_ yang memiliki nilai nameyang sama ; jika tidak, fungsi tersebut mengembalikan nol.
_Check_return_ Membuat anotasi nilai pengembalian dan menyatakan bahwa penelepon harus memeriksanya. Pemeriksa melaporkan kesalahan jika fungsi dipanggil dalam konteks yang batal.
_Function_class_(name) Parameter name adalah string arbitrer yang ditunjuk oleh pengguna. Ini ada di namespace yang berbeda dari namespace layanan lain. Fungsi, penunjuk fungsi, atau—yang paling berguna—jenis penunjuk fungsi dapat ditetapkan sebagai milik satu atau beberapa kelas fungsi.
_Raises_SEH_exception_ Membuat anotasi fungsi yang selalu menimbulkan pengecualian handler pengecualian terstruktur (SEH), tunduk pada _When_ kondisi dan _On_failure_ . Untuk informasi selengkapnya, lihat Menentukan Kapan dan Di mana Anotasi Berlaku.
_Maybe_raises_SEH_exception_ Membuat anotasi fungsi yang dapat secara opsional meningkatkan pengecualian SEH, tunduk pada _When_ kondisi dan _On_failure_ .
_Must_inspect_result_ Anotasi nilai output apa pun, termasuk nilai pengembalian, parameter, dan global. Penganalisis melaporkan kesalahan jika nilai dalam objek yang dianotasi tidak kemudian diperiksa. "Inspeksi" mencakup apakah itu digunakan dalam ekspresi bersyarah, ditetapkan ke parameter output atau global, atau diteruskan sebagai parameter. Untuk nilai yang dikembalikan, _Must_inspect_result_ menyiratkan _Check_return_.
_Use_decl_annotations_ Dapat digunakan pada definisi fungsi (juga dikenal sebagai isi fungsi) sebagai pengganti daftar anotasi di header. Ketika _Use_decl_annotations_ digunakan, anotasi yang muncul pada header dalam cakupan untuk fungsi yang sama digunakan seolah-olah mereka juga ada dalam definisi yang memiliki _Use_decl_annotations_ anotasi.

Anotasi keberhasilan/kegagalan

Fungsi dapat gagal, dan ketika itu terjadi, hasilnya mungkin tidak lengkap atau berbeda dari hasil ketika fungsi berhasil. Anotasi dalam daftar berikut menyediakan cara untuk mengekspresikan perilaku kegagalan. Untuk menggunakan anotasi ini, Anda harus mengaktifkannya untuk menentukan keberhasilan; oleh karena itu, diperlukan anotasi _Success_ . Perhatikan bahwa NTSTATUS dan HRESULT sudah memiliki anotasi _Success_ yang terpasang di dalamnya; namun, jika Anda menentukan anotasi Anda sendiri _Success_ pada NTSTATUS atau HRESULT, anotasi bawaan akan diambil alih.

Anotasi Deskripsi
_Always_(anno_list) Setara dengan anno_list _On_failure_(anno_list); yaitu, anotasi dalam anno_list berlaku apakah fungsi berhasil atau tidak.
_On_failure_(anno_list) Untuk digunakan hanya ketika _Success_ juga digunakan untuk membuat anotasi fungsi—baik secara eksplisit, atau implisit melalui _Return_type_success_ pada typedef. _On_failure_ Ketika anotasi ada pada parameter fungsi atau nilai pengembalian, setiap anotasi dalam anno_list (ano) bersifat seolah-olah dikodekan sebagai _When_(!expr, anno), di mana expr adalah parameter untuk anotasi yang diperlukan_Success_. Ini berarti bahwa penerapan tersirat untuk _Success_ semua pasca-kondisi tidak berlaku untuk _On_failure_.
_Return_type_success_(expr) Dapat diterapkan ke typedef. Menunjukkan bahwa semua fungsi yang mengembalikan jenis tersebut dan tidak secara eksplisit memiliki _Success_ anotasi seolah-olah memiliki _Success_(expr). _Return_type_success_ tidak dapat digunakan pada fungsi atau typedef penunjuk fungsi.
_Success_(expr) expr adalah ekspresi yang menghasilkan rvalue. _Success_ Ketika anotasi ada pada deklarasi atau definisi fungsi, setiap anotasi (anno) pada fungsi dan dalam kondisi pasca bertingkah seolah-olah dikodekan sebagai _When_(expr, anno). Anotasi _Success_ hanya dapat digunakan pada fungsi, bukan pada parameter atau jenis pengembaliannya. Mungkin ada paling banyak satu _Success_ anotasi pada fungsi, dan tidak dapat berada di , _When_, _At_atau _Group_. Untuk informasi selengkapnya, lihat Menentukan Kapan dan Di mana Anotasi Berlaku.

Baca juga