WinHttpCrackUrl 함수(winhttp.h)

  • 아티클

WinHttpCrackUrl 함수는 URL을 호스트 이름 및 경로와 같은 구성 요소 부분으로 구분합니다.

구문

WINHTTPAPI BOOL WinHttpCrackUrl(
  [in]      LPCWSTR          pwszUrl,
  [in]      DWORD            dwUrlLength,
  [in]      DWORD            dwFlags,
  [in, out] LPURL_COMPONENTS lpUrlComponents
);

매개 변수

[in] pwszUrl

구분할 정식 URL이 포함된 문자열에 대한 포인터입니다. WinHttpCrackUrl은 이 URL을 해독하기 전에 유효성 또는 올바른 형식에 대해 이 URL을 검사 않습니다.

[in] dwUrlLength

pwszUrl 문자열의 길이(문자)입니다. dwUrlLength가 0으로 설정된 경우 WinHttpCrackUrl은 pwszUrl 문자열이 null로 종료되었다고 가정하고 해당 가정에 따라 pwszUrl 문자열의 길이를 결정합니다.

[in] dwFlags

작업을 제어하는 플래그입니다. 이 매개 변수는 다음 플래그 중 하나 이상의 조합일 수 있습니다(값은 비트 OR 조합일 수 있음). 또는 매개 변수는 특수 작업을 수행하지 않는 0일 수 있습니다.

값 의미
ICU_DECODE
 "이스케이프 인코딩된" 문자(%xx)를 이스케이프되지 않은 형식으로 변환합니다. UTF-8과 같은 다른 인코딩은 디코딩되지 않습니다. 이 기능은 사용자가 구성 요소를 복사하기 위해 URL_COMPONENTS 구조에 버퍼를 제공하는 경우에만 사용할 수 있습니다.
ICU_ESCAPE
 특정 문자를 이스케이프 시퀀스(%xx)로 이스케이프합니다. 이스케이프할 문자는 ASCII가 아닌 문자이거나 HTTP 요청에 표시되도록 이스케이프해야 하는 ASCII 문자입니다. 이 기능은 사용자가 구성 요소를 복사하기 위해 URL_COMPONENTS 구조에 버퍼를 제공하는 경우에만 사용할 수 있습니다.
ICU_REJECT_USERPWD
 포함된 자격 증명(사용자 이름, 암호 또는 둘 다)이 포함된 입력으로 URL을 거부합니다. 잘못된 URL로 인해 함수가 실패하면 GetLastError에 대한 후속 호출은 ERROR_WINHTTP_INVALID_URL 반환합니다.

[in, out] lpUrlComponents

URL 구성 요소를 수신하는 URL_COMPONENTS 구조체에 대한 포인터입니다.

반환 값

함수가 성공하면 TRUE 를 반환하고, 그렇지 않으면 FALSE 를 반환합니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다. 반환된 오류 코드 중에는 다음과 같습니다.

오류 코드 Description
ERROR_WINHTTP_INTERNAL_ERROR
 내부 오류가 발생했습니다.
ERROR_WINHTTP_INVALID_URL
 URL이 올바르지 않습니다.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
 URL 체계를 인식할 수 없거나 지원되지 않습니다.
ERROR_NOT_ENOUGH_MEMORY
 요청된 작업을 완료하는 데 사용할 수 있는 메모리가 부족합니다. (Windows 오류 코드)

설명

WinHTTP가 비동기 모드에서 사용되는 경우에도(즉, WinHttpOpen에서 WINHTTP_FLAG_ASYNC 설정된 경우) 이 함수는 동기적으로 작동합니다. 반환 값은 성공 또는 실패를 나타냅니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

필요한 구성 요소는 URL_COMPONENTS 구조체의 멤버로 표시됩니다. 각 구성 요소에는 값에 대한 포인터가 있으며 저장된 값의 길이를 저장하는 멤버가 있습니다. 구성 요소의 값과 길이가 모두 0이면 해당 구성 요소가 반환되지 않습니다. 구성 요소 값에 대한 포인터가 NULL 이 아니고 해당 길이 멤버의 값이 0이 아니면 pwszUrl 문자열에 있는 해당 구성 요소의 첫 번째 문자 주소가 포인터에 저장되고 구성 요소의 길이가 길이 멤버에 저장됩니다.

포인터에 사용자가 제공한 버퍼의 주소가 포함된 경우 길이 멤버는 버퍼의 크기를 포함해야 합니다. WinHttpCrackUrl 함수는 구성 요소를 버퍼에 복사하고 길이 멤버는 복사된 구성 요소의 길이(후행 문자열 종결자에 대해 1을 뺀 값)로 설정됩니다. 사용자가 제공한 버퍼가 충분히 크지 않으면 WinHttpCrackUrl 은 FALSE를 반환하고 GetLastError 는 ERROR_INSUFFICIENT_BUFFER 반환합니다.

WinHttpCrackUrl이 제대로 작동하려면 URL_COMPONENTS 구조체의 크기를 해당 구조체의 dwStructSize 멤버에 저장해야 합니다.

pwszUrl에 대해 전달된 URL의 인터넷 프로토콜이 HTTP 또는 HTTPS가 아닌 경우 WinHttpCrackUrl은 FALSE를 반환하고 GetLastError는
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.

WinHttpCrackUrl은 URL을 해독하기 전에 URL의 유효성 또는 형식을 검사 않습니다. 따라서 ""http://server?Bad=URL""와 같은 문자열이 전달되면 함수는 잘못된 결과를 반환합니다.

참고 Windows XP 및 Windows 2000의 경우 WinHttp 시작 페이지의 런타임 요구 사항 섹션을 참조하세요.
 

예제

이 예제에서는 URL을 구성 요소로 분리하고 구성 요소를 업데이트한 다음 URL을 다시 구성하는 방법을 보여 줍니다.

    URL_COMPONENTS urlComp;
    LPCWSTR pwszUrl1 = 
      L"http://search.msn.com/results.asp?RS=CHECKED&FORM=MSNH&v=1&q=wininet";
    DWORD dwUrlLen = 0;

    // Initialize the URL_COMPONENTS structure.
    ZeroMemory(&urlComp, sizeof(urlComp));
    urlComp.dwStructSize = sizeof(urlComp);

    // Set required component lengths to non-zero 
    // so that they are cracked.
    urlComp.dwSchemeLength    = (DWORD)-1;
    urlComp.dwHostNameLength  = (DWORD)-1;
    urlComp.dwUrlPathLength   = (DWORD)-1;
    urlComp.dwExtraInfoLength = (DWORD)-1;

    // Crack the URL.
    if (!WinHttpCrackUrl( pwszUrl1, (DWORD)wcslen(pwszUrl1), 0, &urlComp))
    {
        printf("Error %u in WinHttpCrackUrl.\n", GetLastError());
    }
    else
    {
        // Change the search information.  
        // New info is the same length.
        urlComp.lpszExtraInfo = L"?RS=CHECKED&FORM=MSNH&v=1&q=winhttp";

        // Obtain the size of the new URL and allocate memory.
        WinHttpCreateUrl( &urlComp, 0, NULL, &dwUrlLen);
        LPWSTR pwszUrl2 = new WCHAR[dwUrlLen];

        // Create a new URL.
        if(!WinHttpCreateUrl( &urlComp, 0, pwszUrl2, &dwUrlLen))
        {
            printf("Error %u in WinHttpCreateUrl.\n", GetLastError());
        }
        else
        {
            // Show both URLs.
            printf("Old URL:  %S\nNew URL:  %S\n", pwszUrl1, pwszUrl2);
        }

        // Free allocated memory.
        delete [] pwszUrl2;
    }

요구 사항

   
지원되는 최소 클라이언트 Windows XP, Windows 2000 Professional SP3 포함 [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2003, Windows 2000 Server SP3 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 winhttp.h
라이브러리 Winhttp.lib
DLL Winhttp.dll
재배포 가능 파일 Windows XP 및 Windows 2000에서 WinHTTP 5.0 및 인터넷 Explorer 5.01 이상.

추가 정보

Microsoft Windows HTTP 서비스 정보(WinHTTP)

균일한 리소스 로케이터 처리

WinHTTP 버전

WinHttpCreateUrl