UrlEscapeW 함수(shlwapi.h)
인터넷을 통해 전송하는 동안 변경될 수 있는 URL의 문자 또는 서로게이트 쌍("안전하지 않은" 문자)을 해당 이스케이프 시퀀스로 변환합니다. 서로게이트 쌍은 U+10000에서 U+10FFFF(UTF-32) 사이 또는 DC00에서 DFFF(UTF-16) 사이의 문자입니다.
구문
LWSTDAPI UrlEscapeW(
[in] PCWSTR pszUrl,
[out] PWSTR pszEscaped,
[in, out] DWORD *pcchEscaped,
DWORD dwFlags
);
매개 변수
[in] pszUrl
형식: PCTSTR
dwFlags의 값에 적합한 전체 또는 부분 URL을 포함하는 최대 길이 INTERNET_MAX_URL_LENGTH null로 끝나는 문자열입니다.
[out] pszEscaped
형식: PTSTR
변환된 문자열을 수신하는 버퍼이며 안전하지 않은 문자는 이스케이프 시퀀스로 변환됩니다.
[in, out] pcchEscaped
형식: DWORD*
항목에서 pszEscaped 버퍼의 문자 수를 포함하는 DWORD 값에 대한 포인터입니다. UrlEscape를 호출하기 전에 호출 애플리케이션은 pcchEscaped에서 참조하는 값을 버퍼 크기로 설정해야 합니다. 이 함수가 성공적으로 반환되면 값은 종료 되는 NULL 문자를 포함하지 않고 버퍼에 기록된 문자 수를 받습니다.
E_POINTER 오류 코드가 반환되면 버퍼가 너무 작아서 결과를 저장할 수 없으며 pcchEscaped 에서 참조하는 값이 버퍼에 필요한 문자 수로 설정됩니다. 다른 오류가 반환되면 pcchEscaped 에서 참조하는 값이 정의되지 않습니다.
dwFlags
형식:DWORD
pszURL에서 제공되는 URL 부분과 이스케이프 시퀀스로 변환해야 하는 문자열의 문자를 나타내는 플래그입니다. 다음 플래그가 정의됩니다.
URL_DONT_ESCAPE_EXTRA_INFO(0x02000000)
쿼리에서 문자의 변환을 방지하기 위해 URL_ESCAPE_SPACES_ONLY 함께만 사용됩니다(문자열에서 발생한 첫 번째 # 또는 ? 문자 다음에 URL의 부분). 이 플래그는 단독으로 사용하거나 URL_ESCAPE_SEGMENT_ONLY 함께 사용하면 안 됩니다.
URL_BROWSER_MODE
URL_DONT_ESCAPE_EXTRA_INFO 같도록 정의됩니다.
URL_ESCAPE_SPACES_ONLY(0x04000000)
URL의 쿼리 부분에 있는 공백 문자를 포함하여 공백 문자만 이스케이프 시퀀스로 변환합니다. 다른 안전하지 않은 문자는 이스케이프 시퀀스로 변환되지 않습니다. 이 플래그는 pszURL 에 전체 URL이 포함되어 있지 않다고 가정합니다. 서버 사양을 따르는 부분만 필요합니다.
URL의 쿼리 부분에서 공백 문자가 변환되지 않도록 이 플래그를 URL_DONT_ESCAPE_EXTRA_INFO 결합합니다.
이 플래그는 URL_ESCAPE_PERCENT 또는 URL_ESCAPE_SEGMENT_ONLY 결합할 수 없습니다.
URL_ESCAPE_PERCENT(0x00001000)
URL의 세그먼트 섹션에 있는 % 문자를 변환합니다(해당 섹션은 서버 사양과 첫 번째 # 또는 ? 문자 사이에 해당). 기본적으로 % 문자는 이스케이프 시퀀스로 변환되지 않습니다. 세그먼트의 다른 안전하지 않은 문자도 정상적으로 변환됩니다.
이 플래그를 URL_ESCAPE_SEGMENT_ONLY 결합하면 URL의 쿼리 부분에 해당 % 문자가 포함됩니다. 그러나 URL_ESCAPE_SEGMENT_ONLY 플래그로 인해 전체 문자열이 세그먼트로 간주될 수 있으므로 # 또는 ? 문자도 변환됩니다.
이 플래그는 URL_ESCAPE_SPACES_ONLY 함께 사용할 수 없습니다.
URL_ESCAPE_SEGMENT_ONLY(0x00002000)
pszURL이 서버 구성 요소 다음에 쿼리 앞에 있는 URL의 해당 섹션만 포함됨을 나타냅니다. 문자열의 모든 안전하지 않은 문자가 변환됩니다. 이 플래그가 설정될 때 전체 URL이 제공되면 # 및 ? 문자를 포함한 전체 문자열의 모든 안전하지 않은 문자가 변환됩니다.
변환에 해당 문자를 포함하려면 이 플래그를 URL_ESCAPE_PERCENT 결합합니다.
이 플래그는 URL_ESCAPE_SPACES_ONLY 또는 URL_DONT_ESCAPE_EXTRA_INFO 결합할 수 없습니다.
URL_ESCAPE_AS_UTF8(0x00040000)
Windows 7 이상. ASCII가 아닌 모든 문자를 UTF-8 등가물로 백분율로 인코딩합니다.
URL_ESCAPE_ASCII_URI_COMPONENT(0x00080000)
Windows 8 이상. URI RFC 3986(a-zA-Z0-9-.~_)에서 예약되지 않은 집합 외부의 모든 ASCII 문자를 백분율로 인코딩합니다.
반환 값
형식: HRESULT
성공하면 S_OK 반환합니다. pcchEscaped 버퍼가 너무 작아서 결과를 포함할 수 없는 경우 E_POINTER 반환되고 pcchEscaped에서 가리키는 값이 필요한 버퍼 크기로 설정됩니다. 그렇지 않으면 표준 오류 값이 반환됩니다.
설명
이 문서의 목적을 위해 일반적인 URL은 서버, 세그먼트 및 쿼리의 세 가지 섹션으로 나뉩니다. 예를 들면 다음과 같습니다.
http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment
서버 부분은 "http://microsoft.com/"입니다. 후행 슬래시는 서버 부분의 일부로 간주됩니다.
세그먼트 부분은 서버 부분 다음에 있는 경로의 일부이지만 첫 번째 # 또는 ? 문자, 이 경우 단순히 "test.asp".
쿼리 부분은 첫 번째 # 또는 ? 경로의 나머지 부분입니다. 끝에 문자(포함)입니다. 이 예제에서는 "?url=/example/abc.asp?frame=true#fragment"입니다.
안전하지 않은 문자는 인터넷을 통해 전송하는 동안 변경될 수 있는 문자입니다. 이 함수는 안전하지 않은 문자를 해당하는 "%xy" 이스케이프 시퀀스로 변환합니다. 다음 표에서는 안전하지 않은 문자와 해당 이스케이프 시퀀스를 보여 줍니다.
| 문자 | 이스케이프 시퀀스 |
|---|---|
| ^ | %5E |
| & | %26 |
| ` | %60 |
| { | %7B |
| } | %7D |
| | | %7C |
| ] | %5D |
| [ | %5B |
| " | %22 |
| < | %3C |
| > | %3E |
| \ | %5C |
URL_ESCAPE_SEGMENT_ONLY 플래그를 사용하면 #(%23)도 변환됩니다. ? (%3F) 및 /(%2F) 문자입니다.
기본적으로 UrlEscape 는 # 또는 ? 다음 텍스트를 무시합니다. 문자가 포함되지 않습니다. URL_ESCAPE_SEGMENT_ONLY 플래그는 전체 문자열을 세그먼트로 간주하여 이 동작을 재정의합니다. URL_ESCAPE_SPACES_ONLY 플래그는 공백 문자에 대해서만 이 동작을 재정의합니다.
예제
다음 예제에서는 다양한 플래그가 URL에 미치는 영향을 보여 줍니다. 예제 URL은 유효하지 않지만 데모용으로 과장됩니다.
// The full original URL
http://microsoft.com/test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY
// Only space characters are escaped. Other unsafe characters are ignored.
// Note: This flag expects the server portion of the URL to be omitted.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex%%20ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY | URL_DONT_ESCAPE_EXTRA_INFO
// Spaces in the segment are converted into their escape sequences, but
// spaces in the query are not.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_PERCENT
// Here only the segment and query are supplied and the server component is
// omitted, although that is not required. Only the segment is considered.
// All unsafe characters plus the % character are converted in the segment.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%25e%3Cs%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SEGMENT_ONLY
// Note: This flag expects only the segment, omitting the server and query
// components.
// The / character is escaped as well as the usual unsafe characters.
Original = test/t%e<s t.asp
Result = test%2Ft%e%3Cs%20t.asp
참고
shlwapi.h 헤더는 URLEscape를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional, Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | shlwapi.h |
| 라이브러리 | Shlwapi.lib |
| DLL | Shlwapi.dll(버전 5.0 이상) |