Anotasi Header

Artikel
06/13/2023

[Topik ini menjelaskan anotasi yang didukung di header Windows melalui Windows 7. Jika Anda mengembangkan untuk Windows 8, Anda harus menggunakan anotasi yang dijelaskan dalam Anotasi SAL.]

Anotasi header menjelaskan bagaimana fungsi menggunakan parameternya dan mengembalikan nilai. Anotasi ini telah ditambahkan ke banyak file header Windows untuk membantu Anda memastikan bahwa Anda memanggil Windows API dengan benar. Jika Anda mengaktifkan analisis kode, yang tersedia dimulai dengan Visual Studio 2005, pengompilasi akan menghasilkan peringatan tingkat 6000 jika Anda tidak memanggil fungsi ini per penggunaan yang dijelaskan melalui anotasi. Anda juga dapat menambahkan anotasi ini dalam kode Anda sendiri untuk memastikan bahwa anotasi tersebut dipanggil dengan benar. Untuk mengaktifkan analisis kode di Visual Studio, lihat dokumentasi untuk versi Visual Studio Anda.

Anotasi ini didefinisikan dalam Specstrings.h. Mereka dibangun di atas primitif yang merupakan bagian dari Bahasa Anotasi Standar (SAL) dan diimplementasikan menggunakan _declspec("SAL_*").

Ada dua kelas anotasi: anotasi buffer dan anotasi lanjutan.

Anotasi Buffer

Anotasi buffer menjelaskan bagaimana fungsi menggunakan pointer mereka dan dapat digunakan untuk mendeteksi overrun buffer. Setiap parameter dapat menggunakan nol atau satu anotasi buffer. Anotasi buffer dibangun dengan garis bawah terkemuka dan komponen yang dijelaskan di bagian berikut.

Ukuran buffer	Deskripsi
(ukuran)	Menentukan ukuran total buffer. Gunakan dengan _bcount dan _ecount; jangan gunakan dengan _part. Nilai ini adalah ruang yang dapat diakses; mungkin kurang dari ruang yang dialokasikan.
(ukuran, panjang)	Menentukan ukuran total dan panjang penyangga yang diinisialisasi. Gunakan dengan _bcount_part dan _ecount_part. Ukuran total mungkin kurang dari ruang yang dialokasikan.

Unit ukuran buffer	Deskripsi
_bcount	Ukuran buffer dalam byte.
_ecount	Ukuran buffer ada dalam elemen.

Petunjuk	Deskripsi
_In	Fungsi ini berbunyi dari buffer. Pemanggil menyediakan buffer dan menginisialisasinya.
_Inout	Fungsi ini membaca dari dan menulis ke buffer. Pemanggil menyediakan buffer dan menginisialisasinya. Jika digunakan dengan _deref, buffer dapat dialokasikan kembali oleh fungsi .
_Out ekspres	Fungsi menulis ke buffer. Jika digunakan pada nilai pengembalian atau dengan _deref, fungsi menyediakan buffer dan menginisialisasinya. Jika tidak, pemanggil menyediakan buffer dan fungsi menginisialisasinya.

Tidak langsung	Deskripsi
_deref	Dereferensi parameter untuk mendapatkan penunjuk buffer. Parameter ini mungkin bukan NULL.
_deref_opt	Dereferensi parameter untuk mendapatkan penunjuk buffer. Parameter ini bisa NULL.

Inisialisasi	Deskripsi
_Penuh	Fungsi ini menginisialisasi seluruh buffer. Gunakan hanya dengan buffer output.
_Bagian	Fungsi ini menginisialisasi bagian dari buffer, dan secara eksplisit menunjukkan berapa banyak. Gunakan hanya dengan buffer output.

Buffer yang diperlukan atau opsional	Deskripsi
_Memilih	Parameter ini bisa NULL.

Contoh berikut menunjukkan anotasi untuk fungsi GetModuleFileName . Parameter hModule adalah parameter input opsional . Parameter lpFilename adalah parameter output; ukurannya dalam karakter ditentukan oleh parameter nSize dan panjangnya mencakup karakter null-terminating. Parameter nSize adalah parameter input.

DWORD
WINAPI
GetModuleFileName(
    __in_opt HMODULE hModule,
    __out_ecount_part(nSize, return + 1) LPTSTR lpFilename,
    __in DWORD nSize
    );

Berikut ini adalah anotasi yang ditentukan dalam Specstrings.h. Gunakan informasi dalam tabel di atas untuk menginterpretasikan maknanya.

__bcount(ukuran)
__bcount_opt(ukuran)
__deref_bcount(ukuran)
__deref_bcount_opt(ukuran)
__deref_ecount(ukuran)
__deref_ecount_opt(ukuran)
__deref_in
__deref_in_bcount(ukuran)
__deref_in_bcount_opt(ukuran)
__deref_in_ecount(ukuran)
__deref_in_ecount_opt(ukuran)
__deref_in_opt
__deref_inout
__deref_inout_bcount(ukuran)
__deref_inout_bcount_full(ukuran)
__deref_inout_bcount_full_opt(ukuran)
__deref_inout_bcount_opt(ukuran)
__deref_inout_bcount_part(ukuran,panjang)
__deref_inout_bcount_part_opt(ukuran,panjang)
__deref_inout_ecount(ukuran)
__deref_inout_ecount_full(ukuran)
__deref_inout_ecount_full_opt(ukuran)
__deref_inout_ecount_opt(ukuran)
__deref_inout_ecount_part(ukuran,panjang)
__deref_inout_ecount_part_opt(ukuran,panjang)
__deref_inout_opt
__deref_opt_bcount(ukuran)
__deref_opt_bcount_opt(ukuran)
__deref_opt_ecount(ukuran)
__deref_opt_ecount_opt(ukuran)
__deref_opt_in
__deref_opt_in_bcount(ukuran)
__deref_opt_in_bcount_opt(ukuran)
__deref_opt_in_ecount(ukuran)
__deref_opt_in_ecount_opt(ukuran)
__deref_opt_in_opt
__deref_opt_inout
__deref_opt_inout_bcount(ukuran)
__deref_opt_inout_bcount_full(ukuran)
__deref_opt_inout_bcount_full_opt(ukuran)
__deref_opt_inout_bcount_opt(ukuran)
__deref_opt_inout_bcount_part(ukuran,panjang)
__deref_opt_inout_bcount_part_opt(ukuran,panjang)
__deref_opt_inout_ecount(ukuran)
__deref_opt_inout_ecount_full(ukuran)
__deref_opt_inout_ecount_full_opt(ukuran)
__deref_opt_inout_ecount_opt(ukuran)
__deref_opt_inout_ecount_part(ukuran,panjang)
__deref_opt_inout_ecount_part_opt(ukuran,panjang)
__deref_opt_inout_opt
__deref_opt_out
__deref_opt_out_bcount(ukuran)
__deref_opt_out_bcount_full(ukuran)
__deref_opt_out_bcount_full_opt(ukuran)
__deref_opt_out_bcount_opt(ukuran)
__deref_opt_out_bcount_part(ukuran,panjang)
__deref_opt_out_bcount_part_opt(ukuran,panjang)
__deref_opt_out_ecount(ukuran)
__deref_opt_out_ecount_full(ukuran)
__deref_opt_out_ecount_full_opt(ukuran)
__deref_opt_out_ecount_opt(ukuran)
__deref_opt_out_ecount_part(ukuran,panjang)
__deref_opt_out_ecount_part_opt(ukuran,panjang)
__deref_opt_out_opt
__deref_out
__deref_out_bcount(ukuran)
__deref_out_bcount_full(ukuran)
__deref_out_bcount_full_opt(ukuran)
__deref_out_bcount_opt(ukuran)
__deref_out_bcount_part(ukuran,panjang)
__deref_out_bcount_part_opt(ukuran,panjang)
__deref_out_ecount(ukuran)
__deref_out_ecount_full(ukuran)
__deref_out_ecount_full_opt(ukuran)
__deref_out_ecount_opt(ukuran)
__deref_out_ecount_part(ukuran,panjang)
__deref_out_ecount_part_opt(ukuran,panjang)
__deref_out_opt
__ecount(ukuran)
__ecount_opt(ukuran)
__In
__in_bcount(ukuran)
__in_bcount_opt(ukuran)
__in_ecount(ukuran)
__in_ecount_opt(ukuran)
__in_opt
__Inout
__inout_bcount(ukuran)
__inout_bcount_full(ukuran)
__inout_bcount_full_opt(ukuran)
__inout_bcount_opt(ukuran)
__inout_bcount_part(ukuran,panjang)
__inout_bcount_part_opt(ukuran,panjang)
__inout_ecount(ukuran)
__inout_ecount_full(ukuran)
__inout_ecount_full_opt(ukuran)
__inout_ecount_opt(ukuran)
__inout_ecount_part(ukuran,panjang)
__inout_ecount_part_opt(ukuran,panjang)
__inout_opt
__Out ekspres
__out_bcount(ukuran)
__out_bcount_full(ukuran)
__out_bcount_full_opt(ukuran)
__out_bcount_opt(ukuran)
__out_bcount_part(ukuran,panjang)
__out_bcount_part_opt(ukuran,panjang)
__out_ecount(ukuran)
__out_ecount_full(ukuran)
__out_ecount_full_opt(ukuran)
__out_ecount_opt(ukuran)
__out_ecount_part(ukuran,panjang)
__out_ecount_part_opt(ukuran,panjang)
__out_opt

Anotasi Tingkat Lanjut

Anotasi tingkat lanjut memberikan informasi tambahan tentang parameter atau nilai yang dikembalikan. Setiap parameter atau nilai yang dikembalikan dapat menggunakan nol atau satu anotasi tingkat lanjut.

Anotasi	Deskripsi
__blocksOn(sumber daya)	Fungsi memblokir sumber daya yang ditentukan.
__Callback	Fungsi ini dapat digunakan sebagai penunjuk fungsi.
__checkReturn	Penelepon harus memeriksa nilai yang dikembalikan.
__format_string	Parameter adalah string yang berisi penanda % gaya printf.
__in_awcount(expr,size)	Jika ekspresi benar saat keluar, ukuran buffer input ditentukan dalam byte. Jika ekspresi salah, ukuran ditentukan dalam elemen.
__nullnullterminated	Buffer dapat diakses hingga dan termasuk urutan pertama dari dua karakter null atau pointer.
__nullterminated	Buffer dapat diakses hingga dan termasuk karakter atau penunjuk null pertama.
__out_awcount(expr,size)	Jika ekspresi benar saat keluar, ukuran buffer output ditentukan dalam byte. Jika ekspresi salah, ukuran ditentukan dalam elemen.
__Menimpa	Menentukan perilaku penimpaan C#-style untuk metode virtual.
__Dipesan	Parameter dicadangkan untuk digunakan di masa mendatang dan harus nol atau NULL.
__success(expr)	Jika ekspresi benar saat keluar, pemanggil dapat mengandalkan semua jaminan yang ditentukan oleh anotasi lain. Jika ekspresi salah, penelepon tidak dapat mengandalkan jaminan. Anotasi ini secara otomatis ditambahkan ke fungsi yang mengembalikan nilai HRESULT .
__typefix(ctype)	Perlakukan parameter sebagai jenis yang ditentukan daripada jenis yang dinyatakan.

Contoh berikut menunjukkan buffer dan anotasi tingkat lanjut untuk fungsi DeleteTimerQueueTimer, FreeEnvironmentStrings, dan UnhandledExceptionFilter .

__checkReturn
BOOL
WINAPI
DeleteTimerQueueTimer(
    __in_opt HANDLE TimerQueue,
    __in     HANDLE Timer,
    __in_opt HANDLE CompletionEvent
    );

BOOL
WINAPI
FreeEnvironmentStrings(
    __in __nullnullterminated LPTCH
    );

__callback
LONG
WINAPI
UnhandledExceptionFilter(
    __in struct _EXCEPTION_POINTERS *ExceptionInfo
    );

Anotasi SAL
Panduan: Menganalisis Kode C/C++ untuk Cacat

Bagikan melalui

Anotasi Header

Anotasi Buffer

Anotasi Tingkat Lanjut

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Anotasi Header

Anotasi Buffer

Anotasi Tingkat Lanjut

Topik terkait

Saran dan Komentar

Sumber Daya Tambahan: