Share via

StringCchVPrintfExW 함수(strsafe.h)

  • 아티클

인수 목록에 대한 포인터를 사용하여 지정된 문자열에 서식이 지정된 데이터를 씁니다. 대상 버퍼의 크기는 이 버퍼의 끝을 지나서 작성되지 않도록 함수에 제공됩니다.

StringCchVPrintfEx 는 대상 문자열의 끝에 대한 포인터와 해당 문자열에 사용되지 않은 문자 수를 반환하여 StringCchVPrintf 의 기능을 추가합니다. 플래그는 추가 제어를 위해 함수에 전달될 수도 있습니다.

StringCchVPrintfEx 는 다음 함수를 대체합니다.

구문

STRSAFEAPI StringCchVPrintfExW(
  [out]           STRSAFE_LPWSTR  pszDest,
  [in]            size_t          cchDest,
  [out, optional] STRSAFE_LPWSTR  *ppszDestEnd,
  [out, optional] size_t          *pcchRemaining,
  [in]            DWORD           dwFlags,
  [in]            STRSAFE_LPCWSTR pszFormat,
  [in]            va_list         argList
);

매개 변수

[out] pszDest

형식: LPTSTR

pszFormat 및 argList에서 만든 형식이 지정된 null로 끝나는 문자열을 수신하는 대상 버퍼입니다.

[in] cchDest

형식: size_t

대상 버퍼의 크기(문자)입니다. 이 값은 종료되는 null 문자를 고려하기 위해 최종 형식 문자열에 1을 더하기 위해 충분히 커야 합니다. 허용되는 최대 문자 수는 STRSAFE_MAX_CCH.

[out, optional] ppszDestEnd

형식: LPTSTR*

pszDest의 끝에 대한 포인터의 주소입니다. ppszDestEnd가 NULL이 아니고 데이터가 대상 버퍼에 복사되는 경우 문자열 끝에 있는 종료 null 문자를 가리킵니다.

[out, optional] pcchRemaining

형식: size_t*

종료 null 문자를 포함하여 pszDest에서 사용되지 않는 문자의 수입니다. pcchRemaining이 NULL이면 개수가 유지되거나 반환되지 않습니다.

[in] dwFlags

형식:DWORD

다음 값 중 하나 이상입니다.

값 의미
STRSAFE_FILL_BEHIND_NULL
0x00000200
 함수가 성공하면 종료되는 null 문자 다음에 초기화되지 않은 pszDest 부분을 채우는 데 dwFlags(0)의 하위 바이트가 사용됩니다.
STRSAFE_IGNORE_NULLS
0x00000100
 NULL 문자열 포인터를 빈 문자열(TEXT(""))과 같이 처리합니다.
STRSAFE_FILL_ON_FAILURE
0x00000400
 함수가 실패하면 전체 pszDest 버퍼를 채우는 데 dwFlags(0)의 하위 바이트가 사용되고 버퍼는 null로 종료됩니다. STRSAFE_E_INSUFFICIENT_BUFFER 오류가 발생하면 반환된 잘린 문자열을 덮어씁니다.
STRSAFE_NULL_ON_FAILURE
0x00000800
 함수가 실패하면 pszDest 가 빈 문자열(TEXT(""))로 설정됩니다. STRSAFE_E_INSUFFICIENT_BUFFER 오류가 발생하면 잘린 문자열을 덮어씁니다.
STRSAFE_NO_TRUNCATION
0x00001000
 STRSAFE_NULL_ON_FAILURE 경우처럼 함수가 실패하면 pszDest가 빈 문자열(TEXT("")으로 설정됩니다. STRSAFE_E_INSUFFICIENT_BUFFER 오류가 발생하면 잘린 문자열을 덮어씁니다.

[in] pszFormat

형식: LPCTSTR

서식 문자열입니다. 이 문자열은 null로 종료되어야 합니다. 자세한 내용은 형식 사양 구문을 참조하세요.

[in] argList

형식: va_list

pszFormat 문자열에 삽입할 인수입니다.

반환 값

형식: HRESULT

이 함수는 다음 값 중 하나를 반환할 수 있습니다. SUCCEEDED 및 FAILED 매크로를 사용하여 이 함수의 반환 값을 테스트하는 것이 좋습니다.

반환 코드 Description
S_OK
 잘림 없이 결과를 pszDest 에 복사할 수 있는 충분한 공간이 있었고 버퍼가 null로 종료됩니다.
STRSAFE_E_INVALID_PARAMETER
 cchDest의 값은 0이거나 STRSAFE_MAX_CCH보다 크거나 대상 버퍼가 이미 가득 찼습니다.
STRSAFE_E_INSUFFICIENT_BUFFER
 버퍼 공간이 부족하여 복사 작업이 실패했습니다. dwFlags 값에 따라 대상 버퍼에는 의도한 결과의 잘린 null 종료 버전이 포함될 수 있습니다. 잘림이 허용되는 상황에서는 반드시 실패 조건으로 간주되지 않을 수 있습니다.
 

이 함수는 대체되는 함수와 달리 HRESULT 값을 반환합니다.

설명

StringCchVPrintfEx 는 코드에서 적절한 버퍼 처리를 위한 추가 처리를 제공합니다. 버퍼 처리 불량은 버퍼 오버런과 관련된 많은 보안 문제에 연루됩니다. StringCchVPrintfEx 는 항상 null 길이가 아닌 대상 버퍼를 종료합니다.

va_lists 대한 자세한 내용은 Stdarg.h에 정의된 규칙을 참조하세요.

pszDest, pszFormat 또는 인수 문자열이 가리키는 문자열이 겹치면 동작이 정의되지 않습니다.

STRSAFE_IGNORE_NULLS 플래그를 지정하지 않는 한 pszFormat 또는 pszDest는 NULL이 아니어야 합니다. 이 경우 둘 다 NULL일 수 있습니다. 그러나 NULL 값이 무시되더라도 공간 부족으로 인한 오류는 여전히 반환될 수 있습니다.

StringCchVPrintfEx 는 제네릭 형식 또는 보다 구체적인 형식으로 사용할 수 있습니다. 문자열의 데이터 형식은 다음 표와 같이 사용해야 하는 이 함수의 형식을 결정합니다.

문자열 데이터 형식 문자열 리터럴 함수
char "문자열" StringCchVPrintfExA
TCHAR TEXT("string") StringCchVPrintfEx
Wchar L"string" StringCchVPrintfExW
 

참고

strsafe.h 헤더는 STRINGCchVPrintfEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 WINDOWS XP SP2 [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 WINDOWS Server 2003 SP1 [데스크톱 앱 | UWP 앱]
대상 플랫폼 Windows
헤더 strsafe.h

추가 정보

참조

StringCbVPrintfEx

StringCchPrintfEx

StringCchVPrintf