Aracılığıyla paylaş

İşlev parametrelerine ve dönüş değerlerine açıklama ekleme

Bu makalede, basit işlev parametreleri (skalerler, yapılar ve sınıflar işaretçileri) ve çoğu arabellek türü için ek açıklamaların tipik kullanımları açıklanmaktadır. Bu makalede ek açıklamalar için yaygın kullanım desenleri de gösterilir. İşlevlerle ilgili ek açıklamalar için bkz . İşlev davranışına açıklama ekleme.

İşaretçi parametreleri

Aşağıdaki tablodaki ek açıklamalar için, işaretçi parametresine ek açıklama eklendiğinde çözümleyici işaretçi null olduğunda bir hata bildirir. Bu ek açıklama işaretçiler ve işaret edilen tüm veri öğeleri için geçerlidir.

Ek açıklamalar ve açıklamalar

  • _In_

    Skaler, yapılar, yapı işaretçileri ve benzeri giriş parametrelerine açıklama ekler. Basit skalerlerde açıkça kullanılabilir. Parametrenin ön durumda geçerli olması gerekir ve değiştirilmez.

  • _Out_

    Skaler, yapılar, yapıların işaretçileri ve benzeri çıkış parametrelerine açıklama ekler. Bu ek açıklamayı değer döndüremez bir nesneye (örneğin, değere göre geçirilen bir skaler) uygulamayın. Parametresinin ön durumda geçerli olması gerekmez, ancak post-state içinde geçerli olmalıdır.

  • _Inout_

    İşlev tarafından değiştirilecek bir parametreye açıklama ekler. Hem ön hem de son durumda geçerli olmalıdır, ancak çağrıdan önce ve sonra farklı değerlere sahip olduğu varsayılır. Değiştirilebilir bir değere uygulanmalıdır.

  • _In_z_

    Giriş olarak kullanılan null ile sonlandırılan bir dizenin işaretçisi. Dizenin ön durumda geçerli olması gerekir. Zaten doğru ek açıklamalara PSTRsahip olan değişkenlerinin tercih edilir.

  • _Inout_z_

    Değiştirilecek null ile sonlandırılan bir karakter dizisinin işaretçisi. Çağrıdan önce ve sonra geçerli olmalıdır, ancak değerin değiştiği varsayılır. Null sonlandırıcı taşınabilir, ancak yalnızca özgün null sonlandırıcıya kadar olan öğelere erişilebilir.

  • _In_reads_(s)

    _In_reads_bytes_(s)

    İşlev tarafından okunan bir dizi işaretçisi. Dizi, tümü geçerli olması gereken boyut s öğelerine sahiptir.

    Değişken _bytes_ , boyutu öğeler yerine bayt cinsinden verir. Bu değişkeni yalnızca boyut öğe olarak ifade edilemiyorsa kullanın. Örneğin, char dizeler değişkenini _bytes_ yalnızca kullanan benzer bir işlev kullanırsa kullanır wchar_t .

  • _In_reads_z_(s)

    Null ile sonlandırılan ve bilinen bir boyuta sahip bir dizi işaretçisi. Null sonlandırıcıya kadar olan öğeler (veya s null sonlandırıcı yoksa) ön durumda geçerli olmalıdır. Boyut bayt cinsinden biliniyorsa, öğe boyutuna göre ölçeklendirin s .

  • _In_reads_or_z_(s)

    Null olarak sonlandırılan veya bilinen bir boyuta ya da her ikisine de sahip bir dizi işaretçisi. Null sonlandırıcıya kadar olan öğeler (veya s null sonlandırıcı yoksa) ön durumda geçerli olmalıdır. Boyut bayt cinsinden biliniyorsa, öğe boyutuna göre ölçeklendirin s . (Aile için strn kullanılır.)

  • _Out_writes_(s)

    _Out_writes_bytes_(s)

    İşlev tarafından yazılacak bir öğe dizisi s (resp. bayt) işaretçisi. Dizi öğelerinin ön durumda geçerli olması gerekmez ve son durumda geçerli olan öğelerin sayısı belirtilmez. Parametre türünde ek açıklamalar varsa, bunlar post-state olarak uygulanır. Örneğin, aşağıdaki kodu göz önünde bulundurun.

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

    Bu örnekte, çağıran için sizebir öğe arabelleği p1 sağlar. MyStringCopy bu öğelerden bazılarını geçerli hale getirir. Daha da önemlisi, _Null_terminated_ üzerindeki PWSTR ek açıklama son p1 durumunda null olarak sonlandırıldığı anlamına gelir. Bu şekilde geçerli öğelerin sayısı hala iyi tanımlanmıştır, ancak belirli bir öğe sayısı gerekli değildir.

    Değişken _bytes_ , boyutu öğeler yerine bayt cinsinden verir. Bu değişkeni yalnızca boyut öğe olarak ifade edilemiyorsa kullanın. Örneğin, char dizeler değişkenini _bytes_ yalnızca kullanan benzer bir işlev kullanırsa kullanır wchar_t .

  • _Out_writes_z_(s)

    Bir öğe dizisi işaretçisi s . Öğelerin ön durumda geçerli olması gerekmez. Post-state içinde, null sonlandırıcı aracılığıyla yukarı öğelerin (mevcut olması gerekir) geçerli olması gerekir. Boyut bayt cinsinden biliniyorsa, öğe boyutuna göre ölçeklendirin s .

  • _Inout_updates_(s)

    _Inout_updates_bytes_(s)

    İşlevde hem okunan hem de yazılan bir dizi işaretçisi. Boyut s öğeleridir ve durum öncesi ve son durum için geçerlidir.

    Değişken _bytes_ , boyutu öğeler yerine bayt cinsinden verir. Bu değişkeni yalnızca boyut öğe olarak ifade edilemiyorsa kullanın. Örneğin, char dizeler değişkenini _bytes_ yalnızca kullanan benzer bir işlev kullanırsa kullanır wchar_t .

  • _Inout_updates_z_(s)

    Null olarak sonlandırılan ve bilinen bir boyuta sahip bir dizi işaretçisi. Null sonlandırıcı aracılığıyla yukarı öğelerin (mevcut olması gerekir) hem ön durumda hem de son durumda geçerli olması gerekir. Post-state içindeki değerin, ön durumdaki değerden farklı olduğu varsayılır; null sonlandırıcının konumunu içerir. Boyut bayt cinsinden biliniyorsa, öğe boyutuna göre ölçeklendirin s .

  • _Out_writes_to_(s,c)

    _Out_writes_bytes_to_(s,c)

    _Out_writes_all_(s)

    _Out_writes_bytes_all_(s)

    Bir öğe dizisi işaretçisi s . Öğelerin ön durumda geçerli olması gerekmez. Son durumda, -th öğesine kadar olan cöğelerin geçerli olması gerekir. Boyut _bytes_ , öğe sayısı yerine bayt cinsinden biliniyorsa değişken kullanılabilir.

    Örneğin:

    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)

    İşlev tarafından hem okunan hem de yazılan bir dizi işaretçisi. Bu boyut s öğeleridir; bunların tümü ön durumda geçerli olmalı ve c öğelerin son durumda geçerli olması gerekir.

    Değişken _bytes_ , boyutu öğeler yerine bayt cinsinden verir. Bu değişkeni yalnızca boyut öğe olarak ifade edilemiyorsa kullanın. Örneğin, char dizeler değişkenini _bytes_ yalnızca kullanan benzer bir işlev kullanırsa kullanır wchar_t .

  • _Inout_updates_all_(s)

    _Inout_updates_bytes_all_(s)

    Boyut s öğelerinin işlevi tarafından hem okunan hem de yazılan bir dizi işaretçisi. Aşağıdakilere eşdeğer olarak tanımlanır:

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

    Başka bir deyişle, ön durumda kadar arabellekte s bulunan her öğe, ön durumda ve son durumda geçerlidir.

    Değişken _bytes_ , boyutu öğeler yerine bayt cinsinden verir. Bu değişkeni yalnızca boyut öğe olarak ifade edilemiyorsa kullanın. Örneğin, char dizeler değişkenini _bytes_ yalnızca kullanan benzer bir işlev kullanırsa kullanır wchar_t .

  • _In_reads_to_ptr_(p)

    (eksip - _Curr_) için geçerli bir ifade olan p_Curr_ bir dizi işaretçisi. Önceki p öğelerin ön durumda geçerli olması gerekir.

    Örneğin:

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

  • _In_reads_to_ptr_z_(p)

    İfadenin ( p - _Curr_ eksip) geçerli bir ifade _Curr_ olduğu null olarak sonlandırılan dizi işaretçisi. Önceki p öğelerin ön durumda geçerli olması gerekir.

  • _Out_writes_to_ptr_(p)

    (eksip - _Curr_) için geçerli bir ifade olan p_Curr_ bir dizi işaretçisi. Önceki p öğelerin ön durumda geçerli olması ve son durumda geçerli olması gerekmez.

  • _Out_writes_to_ptr_z_(p)

    (eksi) için geçerli bir ifade olan p - _Curr_p_Curr_null olarak sonlandırılan bir diziye yönelik bir işaretçi. Önceki p öğelerin ön durumda geçerli olması ve son durumda geçerli olması gerekmez.

İsteğe bağlı işaretçi parametreleri

İşaretçi parametresi ek açıklaması içerdiğinde _opt_, parametrenin null olabileceğini gösterir. Aksi takdirde, ek açıklama içermeyen _opt_sürümle aynı şekilde davranır. İşaretçi parametresi ek açıklamalarının değişkenlerinin listesi _opt_ aşağıdadır:

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

Çıkış işaretçisi parametreleri

Çıkış işaretçisi parametreleri, parametrede ve işaret edilen konumda null değerinin belirsizliğini belirtmek için özel bir gösterimi gerektirir.

Ek açıklamalar ve açıklamalar

  • _Outptr_

    Parametre null olamaz ve son durumda işaret edilen konum null olamaz ve geçerli olmalıdır.

  • _Outptr_opt_

    Parametre null olabilir, ancak son durumda işaret edilen konum null olamaz ve geçerli olmalıdır.

  • _Outptr_result_maybenull_

    Parametre null olamaz ve son durumda işaret edilen konum null olabilir.

  • _Outptr_opt_result_maybenull_

    Parametre null olabilir ve son durumda işaret edilen konum null olabilir.

    Aşağıdaki tabloda, ek açıklamanın anlamını daha da nitelemesi için ek açıklama adına ek alt dizeler eklenir. Çeşitli alt dizeler , , _z_COM_, _buffer_ve _bytebuffer_şeklindedir_to_.

Önemli

Açıklama eklediğiniz arabirim COM ise, bu ek açıklamaların COM biçimini kullanın. COM ek açıklamalarını başka bir tür arabirimiyle kullanmayın.

  • _Outptr_result_z_

    _Outptr_opt_result_z_

    _Outptr_result_maybenull_z_

    _Outptr_opt_result_maybenull_z_

    Döndürülen işaretçi ek açıklamaya _Null_terminated_ sahiptir.

  • _COM_Outptr_

    _COM_Outptr_opt_

    _COM_Outptr_result_maybenull_

    _COM_Outptr_opt_result_maybenull_

    Döndürülen işaretçi COM semantiğine sahiptir ve bu nedenle döndürülen işaretçinin null olduğu bir _On_failure_ son koşul taşır.

  • _Outptr_result_buffer_(s)

    _Outptr_result_bytebuffer_(s)

    _Outptr_opt_result_buffer_(s)

    _Outptr_opt_result_bytebuffer_(s)

    Döndürülen işaretçi, boyut s öğelerinin veya baytların geçerli bir arabelleğine işaret eder.

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

    Döndürülen işaretçi, ilkinin s geçerli olduğu boyut c öğelerinin veya baytların arabelleğine işaret eder.

Bazı arabirim kuralları, hata durumunda çıkış parametrelerinin null olarak atandığını kabul eder. Açıkça COM kodu dışında, aşağıdaki tablodaki formlar tercih edilir. COM kodu için, önceki bölümde listelenen ilgili COM formlarını kullanın.

  • _Result_nullonfailure_

    Diğer ek açıklamaları değiştirir. İşlev başarısız olursa sonuç null olarak ayarlanır.

  • _Result_zeroonfailure_

    Diğer ek açıklamaları değiştirir. İşlev başarısız olursa sonuç sıfır olarak ayarlanır.

  • _Outptr_result_nullonfailure_

    Döndürülen işaretçi, işlev başarılı olursa geçerli bir arabelleğe veya işlev başarısız olursa null değerine işaret eder. Bu ek açıklama isteğe bağlı olmayan bir parametre içindir.

  • _Outptr_opt_result_nullonfailure_

    Döndürülen işaretçi, işlev başarılı olursa geçerli bir arabelleğe veya işlev başarısız olursa null değerine işaret eder. Bu ek açıklama isteğe bağlı bir parametre içindir.

  • _Outref_result_nullonfailure_

    Döndürülen işaretçi, işlev başarılı olursa geçerli bir arabelleğe veya işlev başarısız olursa null değerine işaret eder. Bu ek açıklama bir başvuru parametresi içindir.

Çıkış başvuru parametreleri

Başvuru parametresinin yaygın kullanımlarından biri çıkış parametreleridir. gibi int&_Out_ basit çıkış başvuru parametreleri için doğru semantiği sağlar. Ancak, çıkış değeri gibi int *&bir işaretçi olduğunda, gibi _Outptr_ int ** eşdeğer işaretçi ek açıklamaları doğru semantiği sağlamaz. İşaretçi türleri için çıkış başvuru parametrelerinin semantiğini kısa bir şekilde ifade etmek için şu bileşik ek açıklamaları kullanın:

Ek açıklamalar ve açıklamalar

  • _Outref_

    Sonuç son durumda geçerli olmalıdır ve null olamaz.

  • _Outref_result_maybenull_

    Sonuç son durumda geçerli olmalıdır, ancak post-state içinde null olabilir.

  • _Outref_result_buffer_(s)

    Sonuç son durumda geçerli olmalıdır ve null olamaz. Boyut s öğelerinin geçerli arabelleğine işaret edin.

  • _Outref_result_bytebuffer_(s)

    Sonuç son durumda geçerli olmalıdır ve null olamaz. Boyut s baytlarının geçerli arabelleğine işaret eder.

  • _Outref_result_buffer_to_(s, c)

    Sonuç son durumda geçerli olmalıdır ve null olamaz. İlki sc geçerli olan öğelerin arabelleğine işaret edilir.

  • _Outref_result_bytebuffer_to_(s, c)

    Sonuç son durumda geçerli olmalıdır ve null olamaz. İlkinin sc geçerli olduğu bayt arabelleğine işaret eder.

  • _Outref_result_buffer_all_(s)

    Sonuç son durumda geçerli olmalıdır ve null olamaz. Geçerli öğelerin boyutunun s geçerli arabelleğine işaret edin.

  • _Outref_result_bytebuffer_all_(s)

    Sonuç son durumda geçerli olmalıdır ve null olamaz. Geçerli öğelerin baytlarının s geçerli arabelleğine işaret eder.

  • _Outref_result_buffer_maybenull_(s)

    Sonuç son durumda geçerli olmalıdır, ancak post-state içinde null olabilir. Boyut s öğelerinin geçerli arabelleğine işaret edin.

  • _Outref_result_bytebuffer_maybenull_(s)

    Sonuç son durumda geçerli olmalıdır, ancak post-state içinde null olabilir. Boyut s baytlarının geçerli arabelleğine işaret eder.

  • _Outref_result_buffer_to_maybenull_(s, c)

    Sonuç son durumda geçerli olmalıdır, ancak post-state içinde null olabilir. İlki sc geçerli olan öğelerin arabelleğine işaret edilir.

  • _Outref_result_bytebuffer_to_maybenull_(s,c)

    Sonuç son durumda geçerli olmalıdır, ancak post durumunda null olabilir. İlkinin sc geçerli olduğu bayt arabelleğine işaret eder.

  • _Outref_result_buffer_all_maybenull_(s)

    Sonuç son durumda geçerli olmalıdır, ancak post durumunda null olabilir. Geçerli öğelerin boyutunun s geçerli arabelleğine işaret edin.

  • _Outref_result_bytebuffer_all_maybenull_(s)

    Sonuç son durumda geçerli olmalıdır, ancak post durumunda null olabilir. Geçerli öğelerin baytlarının s geçerli arabelleğine işaret eder.

Dönüş değerleri

İşlevin dönüş değeri bir _Out_ parametreye benzer, ancak farklı bir başvuru kaldırma düzeyindedir ve sonuç için işaretçi kavramını göz önünde bulundurmanız gerekmez. Aşağıdaki ek açıklamalar için dönüş değeri açıklamalı nesnedir( skaler, yapı işaretçisi veya arabelleğe yönelik bir işaretçi). Bu ek açıklamalar, karşılık gelen _Out_ ek açıklamayla aynı semantiklere sahiptir.

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

Dize parametrelerini biçimlendirme

  • _Printf_format_string_ parametresinin bir ifadede printf kullanılmak üzere bir biçim dizesi olduğunu gösterir.

    Örnek

    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_ parametresinin bir ifadede scanf kullanılmak üzere bir biçim dizesi olduğunu gösterir.

    Örnek

    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_ parametresinin bir ifadede scanf_s kullanılmak üzere bir biçim dizesi olduğunu gösterir.

    Örnek

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

Diğer yaygın ek açıklamalar

Ek açıklamalar ve açıklamalar

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

    Parametresi, alanı veya sonucu ile arasında (dahil) lowhibulunur. _Satisfies_(_Curr_ >= low && _Curr_ <= hi) Buna eşdeğer, açıklama eklenen nesneye uygun ön durum veya son durum koşullarıyla birlikte uygulanır.

    Önemli

    Adlar "in" ve "out" içerse de ve anlamları _In_ bu ek açıklamalara uygulanmaz_Out_.

  • _Pre_equal_to_(expr)

    _Post_equal_to_(expr)

    Ek açıklamalı değer tam olarak exprşeklindedir. _Satisfies_(_Curr_ == expr) Buna eşdeğer, açıklama eklenen nesneye uygun ön durum veya son durum koşullarıyla birlikte uygulanır.

  • _Struct_size_bytes_(size)

    Yapı veya sınıf bildirimi için geçerlidir. Bu türdeki geçerli bir nesnenin, tarafından sizeverilen bayt sayısıyla bildirilen türden büyük olabileceğini gösterir. Örneğin:

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

    Daha sonra türdeki pM bir parametrenin MyStruct * bayt cinsinden arabellek boyutu şu şekilde alınır:

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

Ayrıca bkz.