Bagikan melalui

Anotasi Header

  • Artikel

[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