RtlUnicodeStringCopyEx 함수(ntstrsafe.h)
RtlUnicodeStringCopyEx 함수는 한 UNICODE_STRING 구조체에서 다른 구조체로 문자열을 복사합니다.
통사론
NTSTRSAFEDDI RtlUnicodeStringCopyEx(
[out] PUNICODE_STRING DestinationString,
[in] PCUNICODE_STRING SourceString,
[out, optional] PUNICODE_STRING RemainingString,
[in] DWORD dwFlags
);
매개 변수
[out] DestinationString
선택적.
UNICODE_STRING 구조체에 대한 포인터입니다. 원본 문자열이 대상 문자열에 복사됩니다. 구조체의 문자열 버퍼에서 최대 바이트 수는 NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR).
DestinationString NULL 수 있지만 STRSAFE_IGNORE_NULLS dwFlags설정된 경우에만 가능합니다.
[in] SourceString
선택적.
UNICODE_STRING 구조체에 대한 포인터입니다. 이 구조에는 원본 문자열을 포함하는 버퍼가 포함됩니다. 이 문자열은 대상 문자열에 복사됩니다. 구조체의 문자열 버퍼에서 최대 바이트 수는 NTSTRSAFE_UNICODE_STRING_MAX_CCH * sizeof(WCHAR).
SourceString NULL 수 있지만 STRSAFE_IGNORE_NULLS dwFlags설정된 경우에만 가능합니다.
[out, optional] RemainingString
선택적. 호출자가 UNICODE_STRING 구조에NULL 포인터를 제공하는 경우 함수는 이 구조체의 Buffer 멤버를 복사된 문자열의 끝으로 설정하고, 구조체의 Length 멤버를 0으로 설정하고, 구조체의 MaximumLength 멤버를 대상 버퍼에 남아 있는 바이트 수로 설정합니다. RemainingString NULL 수 있지만 STRSAFE_IGNORE_NULLS dwFlags설정된 경우에만 가능합니다.
[in] dwFlags
하나 이상의 플래그 및 선택적으로 채우기 바이트입니다. 플래그는 다음과 같이 정의됩니다.
| 값 | 의미 |
|---|---|
| STRSAFE_FILL_BEHIND | 이 플래그가 설정되고 함수가 성공하면 dwFlags 낮은 바이트를 사용하여 문자열의 마지막 문자 뒤에 오는 대상 버퍼 부분을 채웁니다. |
| STRSAFE_IGNORE_NULLS | 이 플래그가 설정되면 원본 또는 대상 포인터 또는 둘 다 NULL 수 있습니다. RtlUnicodeStringCopyEx 복사할 수 있는 빈 문자열(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바이트로 설정됩니다. |
반환 값
RtlUnicodeStringCopyEx 다음 NTSTATUS 값 중 하나를 반환합니다.
| 반환 코드 | 묘사 |
|---|---|
| STATUS_SUCCESS | 이 성공 상태는 원본 데이터가 있고 문자열이 잘림 없이 연결되었음을 의미합니다. |
| STATUS_BUFFER_OVERFLOW | 이 경고 상태는 대상 버퍼의 공간이 부족하여 복사 작업이 완료되지 않았음을 의미합니다. dwFlagsSTRSAFE_NO_TRUNCATION 설정되면 대상 버퍼가 수정되지 않습니다. 플래그가 설정되지 않은 경우 대상 버퍼에는 잘린 버전의 복사된 문자열이 포함됩니다. |
| STATUS_INVALID_PARAMETER | 이 오류 상태는 함수가 잘못된 입력 매개 변수를 수신했음을 의미합니다. 자세한 내용은 다음 목록을 참조하세요. |
RtlUnicodeStringCopyEx 다음 중 하나가 발생하면 STATUS_INVALID_PARAMETER 값을 반환합니다.
- UNICODE_STRING 구조체의 내용이 잘못되었습니다.
- dwFlags잘못된 플래그가 지정되었습니다.
- 대상 버퍼가 이미 가득 찼습니다.
- 버퍼 포인터는 NULL STRSAFE_IGNORE_NULLS 플래그는 dwFlags지정되지 않습니다.
- 대상 버퍼 포인터는 NULL 버퍼 크기는 0이 아닙니다.
- 대상 버퍼 포인터는 NULL 길이가 0이지만 길이가 0이 아닌 원본 문자열이 있습니다.
NTSTATUS 값을 테스트하는 방법에 대한 자세한 내용은 NTSTATUS 값 사용참조하세요.
발언
RtlUnicodeStringCopyEx 함수는 대상 버퍼의 크기를 사용하여 연결 작업이 버퍼의 끝을 지나서 작성되지 않도록 합니다. 기본적으로 함수는 null 문자 값(즉, 0)으로 결과 문자열을 종료하지 않습니다. 옵션으로 호출자는 STRSAFE_FILL_BEHIND 플래그와 0의 채우기 바이트 값을 사용하여 전체 대상 버퍼를 차지하지 않는 결과 문자열을 null로 종료할 수 있습니다.
RtlUnicodeStringCopyEx 대상 문자열의 끝과 해당 문자열에서 사용되지 않은 바이트 수를 식별하는 UNICODE_STRING 구조를 반환하여 RtlUnicodeStringCopy 함수의 기능을 추가합니다. 추가 제어를 위해 RtlUnicodeStringCopyEx 플래그를 전달할 수 있습니다.
원본 문자열과 대상 문자열이 겹치면 함수의 동작이 정의되지 않습니다.
STRSAFE_IGNORE_NULLS 플래그가 dwFlags설정되지 않는 한 SourceString 및 DestinationString 포인터는 NULL 수 없습니다. STRSAFE_IGNORE_NULLS 설정되면 이러한 포인터 중 하나 또는 둘 다 NULL 수 있습니다. DestinationString 포인터가 NULL 경우 SourceString 포인터는 NULL UNICODE_STRING 구조체에서 빈 문자열을 설명해야 합니다.
안전한 문자열 함수에 대한 자세한 내용은 safe string 함수 사용참조하세요.
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | SP1(서비스 팩 1)을 사용하여 Windows XP부터 사용할 수 있습니다. |
| 대상 플랫폼 | 바탕 화면 |
| 헤더 | ntstrsafe.h(Ntstrsafe.h 포함) |
| 라이브러리 | Ntstrsafe.lib |
| IRQL | 조작되는 문자열이 항상 메모리에 상주하는 경우, 그렇지 않으면 PASSIVE_LEVEL |