Share via

헤더 주석

  • 아티클

[이 항목에서는 Windows 7을 통해 Windows 헤더에서 지원되는 주석에 대해 설명합니다. Windows 8 위해 개발하는 경우 SAL 주석에 설명된 주석을 사용해야 합니다.]

헤더 주석은 함수가 매개 변수 및 반환 값을 사용하는 방법을 설명합니다. 이러한 주석은 Windows API를 올바르게 호출하는 데 도움이 되도록 많은 Windows 헤더 파일에 추가되었습니다. Visual Studio 2005부터 사용할 수 있는 코드 분석을 사용하도록 설정하면 주석을 통해 설명된 사용량에 따라 이러한 함수를 호출하지 않는 경우 컴파일러에서 수준 6000 경고를 생성합니다. 이러한 주석을 사용자 고유의 코드에 추가하여 올바르게 호출되도록 할 수도 있습니다. Visual Studio에서 코드 분석을 사용하도록 설정하려면 Visual Studio 버전에 대한 설명서를 참조하세요.

이러한 주석은 Specstrings.h에 정의되어 있습니다. SAL(표준 주석 언어)의 일부인 기본 형식을 기반으로 하며 를 사용하여 _declspec("SAL_*")구현됩니다.

주석에는 버퍼 주석과 고급 주석의 두 가지 클래스가 있습니다.

버퍼 주석

버퍼 주석은 함수가 포인터를 사용하는 방법과 버퍼 오버런을 검색하는 데 사용할 수 있는 방법을 설명합니다. 각 매개 변수는 0개 또는 1개의 버퍼 주석을 사용할 수 있습니다. 버퍼 주석은 선행 밑줄과 다음 섹션에 설명된 구성 요소를 사용하여 생성됩니다.

버퍼 크기 Description
(크기)
 버퍼의 총 크기를 지정합니다. _bcount 및 _ecount 함께 사용; _part 사용하지 마세요. 이 값은 액세스 가능한 공간입니다. 할당된 공간보다 작을 수 있습니다.
(size,length)
 버퍼의 총 크기 및 초기화된 길이를 지정합니다. _bcount_part 및 _ecount_part 함께 사용합니다. 총 크기가 할당된 공간보다 작을 수 있습니다.
버퍼 크기 단위 Description
_bcount
 버퍼 크기는 바이트입니다.
_ecount
 버퍼 크기는 요소에 있습니다.
Direction 설명
_in
 함수는 버퍼에서 읽습니다. 호출자는 버퍼를 제공하고 초기화합니다.
_Inout
 함수는 버퍼에서 읽고 버퍼에 씁니다. 호출자는 버퍼를 제공하고 초기화합니다. _deref 함께 사용하는 경우 함수에서 버퍼를 다시 할당할 수 있습니다.
_out
 함수는 버퍼에 씁니다. 반환 값 또는 _deref 사용하는 경우 함수는 버퍼를 제공하고 초기화합니다. 그렇지 않으면 호출자는 버퍼를 제공하고 함수는 버퍼를 초기화합니다.
간접 참조 설명
_Deref
 매개 변수를 역참조하여 버퍼 포인터를 가져옵니다. 이 매개 변수는 NULL이 아닐 수 있습니다.
_deref_opt
 매개 변수를 역참조하여 버퍼 포인터를 가져옵니다. 이 매개 변수는 NULL일 수 있습니다.
초기화 설명
_전체
 함수는 전체 버퍼를 초기화합니다. 출력 버퍼에만 사용합니다.
_부분
 함수는 버퍼의 일부를 초기화하고 양을 명시적으로 나타냅니다. 출력 버퍼에만 사용합니다.
필수 또는 선택적 버퍼 Description
_선택
 이 매개 변수는 NULL일 수 있습니다.

다음 예제에서는 GetModuleFileName 함수에 대한 주석을 보여 줍니다. hModule 매개 변수는 선택적 입력 매개 변수입니다. lpFilename 매개 변수는 출력 매개 변수입니다. 문자의 크기는 nSize 매개 변수로 지정되고 길이에는 null 종결 문자가 포함됩니다. nSize 매개 변수는 입력 매개 변수입니다.

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

다음은 Specstrings.h에 정의된 주석입니다. 위의 표에 있는 정보를 사용하여 해당 의미를 해석합니다.

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

고급 주석

고급 주석은 매개 변수 또는 반환 값에 대한 추가 정보를 제공합니다. 각 매개 변수 또는 반환 값은 0개 또는 1개의 고급 주석을 사용할 수 있습니다.

Annotation 설명
__blocksOn(resource)
 함수는 지정된 리소스에서 차단합니다.
__콜백
 함수를 함수 포인터로 사용할 수 있습니다.
__checkReturn
 호출자는 반환 값을 검사 합니다.
__format_string
 매개 변수는 printf 스타일 % 마커를 포함하는 문자열입니다.
__in_awcount(expr,size)
 식이 종료 시 true이면 입력 버퍼의 크기가 바이트로 지정됩니다. 식이 false이면 크기가 요소에 지정됩니다.
__nullnullterminated
 두 개의 null 문자 또는 포인터의 첫 번째 시퀀스를 포함하여 버퍼에 액세스할 수 있습니다.
__nullterminated
 버퍼는 첫 번째 null 문자 또는 포인터까지 액세스할 수 있습니다.
__out_awcount(expr,size)
 식이 종료 시 true이면 출력 버퍼의 크기가 바이트로 지정됩니다. 식이 false이면 크기가 요소에 지정됩니다.
__재정의
 가상 메서드에 대한 C#스타일 재정의 동작을 지정합니다.
__예약
 매개 변수는 나중에 사용하도록 예약되어 있으며 0 또는 NULL이어야 합니다.
__success(expr)
 종료 시 식이 true이면 호출자는 다른 주석으로 지정된 모든 보장을 사용할 수 있습니다. 식이 false이면 호출자는 보증을 사용할 수 없습니다. 이 주석은 HRESULT 값을 반환하는 함수에 자동으로 추가됩니다.
__typefix(ctype)
 매개 변수를 선언된 형식이 아닌 지정된 형식으로 처리합니다.

다음 예제에서는 DeleteTimerQueueTimer, FreeEnvironmentStrings 및 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
    );

SAL 주석

연습: C/C++ 코드 결함 분석