StringCbCopyNExW 함수(strsafe.h)
지정된 바이트 수를 한 문자열에서 다른 문자열로 복사합니다. 대상 버퍼의 크기는 이 버퍼의 끝을 지나서 작성되지 않도록 함수에 제공됩니다.
StringCbCopyNEx 는 대상 문자열의 끝에 대한 포인터와 해당 문자열에 사용되지 않은 바이트 수를 반환하여 StringCbCopyN 의 기능에 추가합니다. 플래그는 추가 제어를 위해 함수에 전달될 수도 있습니다.
StringCbCopyNEx 는 다음 함수를 대체합니다.
구문
STRSAFEAPI StringCbCopyNExW(
[out] STRSAFE_LPWSTR pszDest,
[in] size_t cbDest,
[in] STRSAFE_PCNZWCH pszSrc,
[in] size_t cbToCopy,
[out, optional] STRSAFE_LPWSTR *ppszDestEnd,
[out, optional] size_t *pcbRemaining,
[in] DWORD dwFlags
);
매개 변수
[out] pszDest
형식: LPTSTR
복사된 문자열을 수신하는 대상 버퍼입니다.
[in] cbDest
형식: size_t
pszDest의 크기(바이트)입니다. 이 값은 복사된 바이트( pszSrc 의 길이 또는 cbSrc 값 중 더 작은 값)를 보유할 수 있을 만큼 충분히 크고 종료되는 null 문자를 고려해야 합니다. 허용되는 최대 바이트 수는 입니다 STRSAFE_MAX_CCH * sizeof(TCHAR).
[in] pszSrc
형식: LPCTSTR
원본 문자열입니다. 이 문자열은 null로 종료되어야 합니다.
[in] cbToCopy
형식: size_t
pszSrc에서 pszDest로 복사할 최대 바이트 수입니다.
[out, optional] ppszDestEnd
형식: LPTSTR*
pszDest의 끝에 대한 포인터의 주소입니다. ppszDestEnd가 NULL이 아니고 데이터가 대상 버퍼에 복사되는 경우 문자열 끝에 있는 종료 null 문자를 가리킵니다.
[out, optional] pcbRemaining
형식: size_t*
종료 null 문자에 사용되는 바이트를 포함하여 pszDest에서 사용되지 않는 바이트 수입니다. pcbRemaining이 NULL이면 개수가 유지되거나 반환되지 않습니다.
[in] dwFlags
형식:DWORD
다음 값 중 하나 이상입니다.
반환 값
형식: HRESULT
이 함수는 다음 값 중 하나를 반환할 수 있습니다. SUCCEEDED 및 FAILED 매크로를 사용하여 이 함수의 반환 값을 테스트하는 것이 좋습니다.
| 반환 코드 | Description |
|---|---|
|
원본 데이터가 있고 잘림 없이 완전히 복사되었으며 결과 대상 버퍼는 null로 종료됩니다. |
|
pszDest 또는 pszSrc가 보다 STRSAFE_MAX_CCH * sizeof(TCHAR)크거나 복사할 원본 데이터가 있거나 잘못된 플래그가 전달된 경우 pszDest는 NULL입니다.
|
|
버퍼 공간이 부족하여 복사 작업이 실패했습니다. dwFlags 값에 따라 대상 버퍼에는 의도한 결과의 잘린 null 종료 버전이 포함될 수 있습니다. 잘림이 허용되는 상황에서는 반드시 실패 조건으로 간주되지 않을 수 있습니다. |
이 함수는 대체되는 함수와 달리 HRESULT 값을 반환합니다.
설명
StringCbCopyNEx 는 코드에서 적절한 버퍼 처리를 위한 추가 처리를 제공합니다. 버퍼 처리 불량은 버퍼 오버런과 관련된 많은 보안 문제에 연루됩니다. StringCbCopyNEx 는 작업 중에 원본 문자열의 내용이 변경되더라도 항상 null을 종료하고 유효한 대상 버퍼를 오버플로하지 않습니다.
이 루틴은 strncpy를 대체하기 위한 것이지만 동작에는 차이가 있습니다. cbSrc가 pszSrc의 바이트 수보다 큰 경우 stringCbCopyNEx는 strncpy와 달리 cbSrc 바이트가 복사될 때까지 pszDest를 null 문자로 채우지 않습니다.
pszSrc 및 pszDest가 가리키는 문자열이 겹치면 동작이 정의되지 않습니다.
STRSAFE_IGNORE_NULLS 플래그를 지정하지 않는 한 pszSrc 또는 pszDest는 NULL이 아니어야 합니다. 이 경우 둘 다 NULL일 수 있습니다. 그러나 NULL 값이 무시되더라도 공간 부족으로 인한 오류는 여전히 반환될 수 있습니다.
StringCbCopyNEx 는 제네릭 형식 또는 보다 구체적인 형식으로 사용할 수 있습니다. 문자열의 데이터 형식은 다음 표와 같이 사용해야 하는 이 함수의 형식을 결정합니다.
| 문자열 데이터 형식 | 문자열 리터럴 | 함수 |
|---|---|---|
| char | "문자열" | StringCbCopyNExA |
| TCHAR | TEXT("string") | StringCbCopyNEx |
| Wchar | L"string" | StringCbCopyNExW |
참고
strsafe.h 헤더는 STRINGCbCopyNEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | WINDOWS XP SP2 [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | WINDOWS Server 2003 SP1 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | strsafe.h |
추가 정보
참조