RtlUnicodeStringCbCopyStringNEx 함수(ntstrsafe.h)
RtlUnicodeStringCbCopyStringNEx 함수는 복사된 문자열의 크기를 제한하면서 문자열을 UNICODE_STRING 구조로 복사합니다.
NTSTRSAFEDDI RtlUnicodeStringCbCopyStringNEx(
[out] PUNICODE_STRING DestinationString,
[in] NTSTRSAFE_PCWSTR pszSrc,
[in] size_t cbToCopy,
[out, optional] PUNICODE_STRING RemainingString,
[in] DWORD dwFlags
);
[out] DestinationString
선택 사항입니다. 복사된 문자열을 수신하는 UNICODE_STRING 구조체에 대한 포인터입니다. pszSrc 매개 변수가 가리키는 문자열(종료 null 제외)은 DestinationString 매개 변수의 UNICODE_STRING 구조가 가리키는 버퍼에 복사됩니다. 문자열의 최대 바이트 수는 입니다 NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR)
. DestinationString 은 NULL일 수 있지만 dwFlags에서 STRSAFE_IGNORE_NULLS 설정된 경우에만 가능합니다.
[in] pszSrc
선택 사항입니다. 복사할 문자열에 대한 포인터입니다. 이 포인터는 NULL일 수 있지만 dwFlags에서 STRSAFE_IGNORE_NULLS 설정된 경우에만 가능합니다.
[in] cbToCopy
원본에서 대상으로 복사할 바이트 수입니다.
[out, optional] RemainingString
선택 사항입니다. 호출자가 UNICODE_STRING 구조체에 NULL이 아닌 포인터를 제공하는 경우 함수는 이 구조체의 Buffer 멤버를 연결된 문자열의 끝으로 설정하고, 구조체의 Length 멤버를 0으로 설정하고, 구조체의 MaximumLength 멤버를 대상 버퍼에 남아 있는 바이트 수로 설정합니다. RemainingString 은 NULL일 수 있지만 dwFlags에서 STRSAFE_IGNORE_NULLS 설정된 경우에만 가능합니다.
[in] dwFlags
하나 이상의 플래그 및 선택적으로 채우기 바이트입니다. 플래그는 다음과 같이 정의됩니다.
값 | 의미 |
---|---|
STRSAFE_FILL_BEHIND_NULL | 이 플래그가 설정되고 함수가 성공하면 dwFlags 의 하위 바이트가 문자열의 마지막 문자 뒤에 오는 대상 버퍼의 부분을 채우는 데 사용됩니다. |
STRSAFE_IGNORE_NULLS | 이 플래그가 설정되면 원본 또는 대상 포인터 또는 둘 다 NULL일 수 있습니다. RtlUnicodeStringCbCopyStringNEx 는 복사할 수 있는 빈 문자열(TEXT(""))과 같은 NULL 원본 버퍼 포인터를 처리합니다. NULL 대상 버퍼 포인터는 흠이 없는 문자열을 받을 수 없습니다. |
STRSAFE_FILL_ON_FAILURE | 이 플래그가 설정되고 함수가 실패하면 dwFlags 의 하위 바이트가 전체 대상 버퍼를 채우는 데 사용됩니다. 이 작업은 기존의 버퍼 콘텐츠를 덮어씁니다. |
STRSAFE_NULL_ON_FAILURE | 이 플래그가 설정되고 함수가 실패하면 대상 버퍼가 빈 문자열(TEXT("")로 설정됩니다. 이 작업은 기존의 버퍼 콘텐츠를 덮어씁니다. |
STRSAFE_NO_TRUNCATION |
이 플래그가 설정되고 함수가 STATUS_BUFFER_OVERFLOW 반환하는 경우:
|
STRSAFE_ZERO_LENGTH_ON_FAILURE | 이 플래그가 설정되고 함수가 STATUS_BUFFER_OVERFLOW 반환하는 경우 대상 문자열 길이는 0바이트로 설정됩니다. |
RtlUnicodeStringCbCopyStringNEx 는 다음 NTSTATUS 값 중 하나를 반환합니다.
반환 코드 | 설명 |
---|---|
STATUS_SUCCESS | 이 성공 상태 원본 데이터가 있고 문자열이 잘림 없이 연결되었음을 의미합니다. |
STATUS_BUFFER_OVERFLOW | 이 경고 상태 대상 버퍼의 공간이 부족하여 복사 작업이 완료되지 않았음을 의미합니다. STRSAFE_NO_TRUNCATIONdwFlags에 설정된 경우 대상 버퍼는 수정되지 않습니다. 플래그가 설정되지 않은 경우 대상 버퍼에는 잘린 버전의 복사된 문자열이 포함됩니다. |
STATUS_INVALID_PARAMETER | 이 오류 상태 함수가 잘못된 입력 매개 변수를 수신했음을 의미합니다. 자세한 내용은 다음 목록을 참조하세요. |
RtlUnicodeStringCbCopyStringNEx 는 다음 중 하나가 발생하면 STATUS_INVALID_PARAMETER 값을 반환합니다.
- UNICODE_STRING 구조체의 내용이 잘못되었습니다.
- 잘못된 플래그가 dwFlags에 지정되었습니다.
- 대상 버퍼가 이미 가득 찼습니다.
- 버퍼 포인터는 NULL 이고 STRSAFE_IGNORE_NULLS 플래그는 dwFlags에 지정되지 않습니다.
- 대상 버퍼 포인터는 NULL이지만 버퍼 크기는 0이 아닙니다.
- 대상 버퍼 포인터가 NULL이거나 길이가 0이지만 길이가 0이 아닌 원본 문자열이 있습니다.
- cbToCopy 매개 변수의 값이 NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR)보다 큽니다.
NTSTATUS 값을 테스트하는 방법에 대한 자세한 내용은 NTSTATUS 값 사용을 참조하세요.
RtlUnicodeStringCbCopyStringNEx 함수는 대상 버퍼의 크기를 사용하여 복사 작업이 버퍼의 끝을 지나서 작성되지 않도록 합니다. 기본적으로 함수는 null 문자 값(즉, 0)으로 결과 문자열을 종료 하지 않습니다. 옵션으로 호출자는 STRSAFE_FILL_BEHIND 플래그와 0의 채우기 바이트 값을 사용하여 전체 대상 버퍼를 차지하지 않는 결과 문자열을 null로 종료할 수 있습니다.
RtlUnicodeStringCbCopyStringNEx는 대상 문자열의 끝과 해당 문자열에서 사용되지 않은 바이트 수를 식별하는 UNICODE_STRING 구조를 반환하여 RtlUnicodeStringCbCopyStringN 함수의 기능을 추가합니다. 추가 제어를 위해 RtlUnicodeStringCbCopyStringNEx 플래그를 전달할 수 있습니다.
원본 문자열과 대상 문자열이 겹치면 함수의 동작이 정의되지 않습니다.
dwFlags에서 STRSAFE_IGNORE_NULLS 플래그를 설정하지 않으면 pszSrc 및 DestinationString 포인터는 NULL일 수 없습니다. STRSAFE_IGNORE_NULLS 설정된 경우 이러한 포인터 중 하나 또는 둘 다 NULL일 수 있습니다. DestinationString 포인터가 NULL인 경우 pszSrc 포인터는 NULL이거나 빈 문자열을 가리킵니다.
안전한 문자열 함수에 대한 자세한 내용은 안전한 문자열 함수 사용을 참조하세요.
요구 사항 | 값 |
---|---|
지원되는 최소 클라이언트 | Windows XP SP1(서비스 팩 1)부터 사용할 수 있습니다. |
대상 플랫폼 | 데스크톱 |
머리글 | ntstrsafe.h(Ntstrsafe.h 포함) |
라이브러리 | Ntstrsafe.lib |
IRQL | 조작되는 문자열이 항상 메모리에 상주하는 경우 이고, 그렇지 않으면 PASSIVE_LEVEL |