Aracılığıyla paylaş

Üst Bilgi Ek Açıklamaları

  • Makale

[Bu konu başlığında, Windows 7 aracılığıyla Windows üst bilgilerinde desteklenen ek açıklamalar açıklanmaktadır. Windows 8 için geliştiriyorsanız, SAL Ek Açıklamaları.] bölümünde açıklanan ek açıklamaları kullanmanız gerekir.

Üst bilgi ek açıklamaları, bir işlevin parametrelerini ve dönüş değerini nasıl kullandığını açıklar. Bu ek açıklamalar, Windows API'sini doğru çağırdığınızdan emin olmanıza yardımcı olmak için Windows üst bilgi dosyalarının çoğuna eklenmiştir. Visual Studio 2005'den itibaren kullanılabilen kod analizini etkinleştirirseniz, ek açıklamalar aracılığıyla açıklanan kullanım başına bu işlevleri çağırmıyorsanız derleyici düzey 6000 uyarıları üretir. Doğru çağrıldığından emin olmak için bu ek açıklamaları kendi kodunuza da ekleyebilirsiniz. Visual Studio'da kod analizini etkinleştirmek için Visual Studio sürümünüzle ilgili belgelere bakın.

Bu ek açıklamalar Specstrings.h içinde tanımlanır. Bunlar, Standart Ek Açıklama Dili'nin (SAL) parçası olan ve _declspec("SAL_*")kullanılarak uygulanan temel öğeler üzerine kurulmuştur.

İki ek açıklama sınıfı vardır: arabellek ek açıklamaları ve gelişmiş ek açıklamalar.

Arabellek Ek Açıklamaları

Arabellek ek açıklamaları işlevlerin işaretçilerini nasıl kullandığını açıklar ve arabellek taşmalarını algılamak için kullanılabilir. Her parametre sıfır veya bir arabellek ek açıklaması kullanabilir. Arabellek ek açıklaması, öndeki alt çizgi ve aşağıdaki bölümlerde açıklanan bileşenlerle oluşturulur.

Arabellek boyutu Açıklama
(boyut)
 Arabelleğin toplam boyutunu belirtir. _bcount ve _ecount ile kullanın; _part ile kullanmayın. Bu değer erişilebilir alantır; ayrılan alandan küçük olabilir.
(boyut,uzunluk)
 Arabelleğin toplam boyutunu ve başlatılan uzunluğunu belirtir. _bcount_part ve _ecount_part ile kullanın. Toplam boyut ayrılan alandan küçük olabilir.
Arabellek boyutu birimleri Açıklama
_bcount
 Arabellek boyutu bayt cinsindendir.
_ecount
 Arabellek boyutu öğelerdedir.
Yön Açıklama
_in
 işlevi arabellekten okur. Çağıran, arabelleği sağlar ve başlatır.
_inout
 İşlev, arabellekten okur ve bu arabelleğe yazar. Çağıran, arabelleği sağlar ve başlatır. _deref ile kullanılırsa, arabellek işlev tarafından yeniden yerleştirilebilir.
_out
 işlevi arabelleğe yazar. dönüş değerinde veya _deref kullanıldığında işlev arabelleği sağlar ve başlatır. Aksi takdirde, çağıran arabelleği sağlar ve işlev onu başlatır.
Gerekebilen Açıklama
_deref
 Arabellek işaretçisini almak için parametresine başvurmayın. Bu parametre NULL olmayabilir.
_deref_opt
 Arabellek işaretçisini almak için parametresine başvurmayın. Bu parametre NULL olabilir.
İlklendirme Açıklama
_full
 işlevi tüm arabelleği başlatır. Yalnızca çıkış arabellekleriyle kullanın.
_part
 işlevi arabelleğin bir bölümünü başlatır ve ne kadar olduğunu açıkça gösterir. Yalnızca çıkış arabellekleriyle kullanın.
Gerekli veya isteğe bağlı arabellek Açıklama
_opt
 Bu parametre NULL olabilir.

Aşağıdaki örnek, GetModuleFileName işlevinin ek açıklamalarını gösterir. hModule parametresi isteğe bağlı bir giriş parametresidir. lpFilename parametresi bir çıkış parametresidir; karakter cinsinden boyutu nSize parametresi tarafından belirtilir ve uzunluğu null-terminating karakterini içerir. nSize parametresi bir giriş parametresidir.

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

Specstrings.h dosyasında tanımlanan ek açıklamalar aşağıdadır. Anlamlarını yorumlamak için yukarıdaki tablolardaki bilgileri kullanın.

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

Gelişmiş Ek Açıklamalar

Gelişmiş ek açıklamalar parametre veya dönüş değeri hakkında ek bilgi sağlar. Her parametre veya dönüş değeri sıfır veya bir gelişmiş ek açıklama kullanabilir.

Ek açıklama Açıklama
__blocksOn(kaynak)
 İşlevler belirtilen kaynağı engeller.
__callback
 İşlev, işlev işaretçisi olarak kullanılabilir.
__checkReturn
 Çağıranların dönüş değerini denetlemesi gerekir.
__format_string
 parametresi, printf stili % işaretçileri içeren bir dizedir.
__in_awcount(ifade,boyut)
 çıkışta ifade true ise, giriş arabelleğinin boyutu bayt cinsinden belirtilir. İfade false ise, boyut öğelerde belirtilir.
__nullnullterminated
 Arabelleğe en fazla iki null karakteri veya işaretçisinin ilk dizisi dahil olmak üzere erişilebilir.
__nullterminated
 Arabelleğe ilk null karakteri veya işaretçisi dahil olmak üzere en fazla erişilebilir.
__out_awcount(ifade,boyut)
 çıkışta ifade true ise, çıkış arabelleğinin boyutu bayt cinsinden belirtilir. İfade false ise, boyut öğelerde belirtilir.
__override
 Sanal yöntemler için C#stili geçersiz kılma davranışını belirtir.
__reserved
 parametresi gelecekte kullanılmak üzere ayrılmıştır ve sıfır veya NULLolmalıdır.
__success(ifade)
 İfade çıkışta true ise, çağıran diğer ek açıklamalar tarafından belirtilen tüm garantileri kullanabilir. İfade false ise, çağıran garantilere güvenemez. Bu ek açıklama, HRESULT değeri döndüren işlevlere otomatik olarak eklenir.
__typefix(ctype)
 parametresini bildirilen türü yerine belirtilen tür olarak değerlendirin.

Aşağıdaki örneklerde, DeleteTimerQueueTimer, FreeEnvironmentStringsve unhandledExceptionFilter işlevleri için arabellek ve gelişmiş ek açıklamalar gösterilmektedir.

__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
    );

SAL Ek Açıklamaları

İzlenecek Yol: Hata için C/C++ Kodunu Çözümleme