WinHttpOpen 함수(winhttp.h)

  • 아티클

WinHttpOpen 함수는 애플리케이션의 경우 WinHTTP 함수를 초기화하고 WinHTTP 세션 핸들을 반환합니다.

구문

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

매개 변수

[in, optional] pszAgentW

WinHTTP 함수를 호출하는 애플리케이션 또는 엔터티의 이름을 포함하는 문자열 변수에 대한 포인터입니다. 이 이름은 HTTP 프로토콜에서 사용자 에이전트 로 사용됩니다.

[in] dwAccessType

필요한 액세스 유형입니다. 다음 값 중 하나일 수 있습니다.

값 의미
WINHTTP_ACCESS_TYPE_NO_PROXY
 프록시 없이 모든 호스트 이름을 직접 확인합니다.
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
중요 이 옵션의 사용은 Windows 8.1 이상에서 더 이상 사용되지 않습니다. 대신 WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY 사용합니다.
 
레지스트리에서 정적 프록시 또는 직접 구성을 검색합니다. WINHTTP_ACCESS_TYPE_DEFAULT_PROXY 브라우저 프록시 설정을 상속하지 않습니다.

WinHTTP 프록시 구성은 이러한 메커니즘 중 하나에 의해 설정됩니다.
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 프록시 바이패스 목록을 제공하고 확인할 이름이 프록시를 무시하지 않는 한 프록시에 요청을 전달합니다. 이 경우 이 함수는 pwszProxyName 및 pwszProxyBypass에 전달된 값을 사용합니다.
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 시스템 및 사용자별 프록시 설정(인터넷 Explorer 프록시 구성 포함)을 사용하여 사용할 프록시/프록시를 결정합니다. 여러 프록시, 인터페이스당 다른 프록시 구성 및 인증 간에 장애 조치(failover)를 자동으로 처리하려고 시도합니다. Windows 8.1 이상에서 지원합니다.

[in] pszProxyW

dwAccessType을 WINHTTP_ACCESS_TYPE_NAMED_PROXY 설정하여 프록시 액세스를 지정할 때 사용할 프록시 서버의 이름을 포함하는 문자열 변수에 대한 포인터입니다. WinHTTP 함수는 HTTP에 대한 CERN 형식 프록시만 인식합니다. dwAccessType이 WINHTTP_ACCESS_TYPE_NAMED_PROXY 설정되지 않은 경우 이 매개 변수를 WINHTTP_NO_PROXY_NAME 설정해야 합니다.

[in] pszProxyBypassW

dwAccessType이 WINHTTP_ACCESS_TYPE_NAMED_PROXY 설정된 경우 프록시를 통해 라우팅되지 않아야 하는 선택적 세미콜론으로 구분된 호스트 이름 또는 IP 주소 목록을 포함하는 문자열 변수에 대한 포인터입니다. 목록에 와일드카드 문자가 포함될 수 있습니다. WinHttpOpen 함수는 이를 프록시 바이패스 목록으로 사용하므로 빈 문자열을 사용하지 마세요. 이 매개 변수가 목록의 "<로컬>" 매크로를 유일한 항목으로 지정하는 경우 이 함수는 마침표를 포함하지 않는 호스트 이름을 무시합니다. dwAccessType이 WINHTTP_ACCESS_TYPE_NAMED_PROXY 설정되지 않은 경우 이 매개 변수를 WINHTTP_NO_PROXY_BYPASS 설정해야 합니다.

[in] dwFlags

이 함수의 동작에 영향을 주는 다양한 옵션을 나타내는 플래그를 포함하는 부호 없는 긴 정수 값입니다. 이 매개 변수는 다음 값을 가질 수 있습니다.

값 의미
WINHTTP_FLAG_ASYNC
 WinHTTP 함수를 비동기적으로 사용합니다. 기본적으로 반환된 HINTERNET 핸들을 사용하는 모든 WinHTTP 함수는 동기적으로 수행됩니다. 이 플래그가 설정되면 호출자는 WinHttpSetStatusCallback을 통해 콜백 함수를 지정해야 합니다.
WINHTTP_FLAG_SECURE_DEFAULTS
 이 플래그가 설정되면 WinHttp에서 TLS 1.2 이상을 사용해야 합니다. 호출자가 WINHTTP_OPTION_SECURE_PROTOCOLS 설정하여 이전 TLS 버전을 사용하도록 설정하려고 하면 ERROR_ACCESS_DENIED 함께 실패합니다. 또한 TLS 대체는 사용하지 않도록 설정됩니다. 이 플래그를 설정하면 플래그 WINHTTP_FLAG_ASYNC 설정됩니다.

반환 값

성공하면 유효한 세션 핸들을 반환하고, 그렇지 않으면 NULL 을 반환합니다. 확장된 오류 정보를 검색하려면 GetLastError를 호출합니다. 반환된 오류 코드 중에는 다음과 같습니다.

오류 코드 Description
ERROR_WINHTTP_INTERNAL_ERROR
 내부 오류가 발생했습니다.
ERROR_NOT_ENOUGH_MEMORY
 요청된 작업을 완료하는 데 사용할 수 있는 메모리가 부족합니다. (Windows 오류 코드)

설명

비동기 모드에서 WinHTTP를 사용하는 것이 좋습니다(즉, WinHttpOpen에서 WINHTTP_FLAG_ASYNC 설정된 경우 반환된 HINTERNET의 사용이 비동기화되도록). 반환 값은 성공 또는 실패를 나타냅니다. 확장된 오류 정보를 검색하려면 GetLastError를 호출합니다.

WinHttpOpen 함수는 애플리케이션에서 호출하는 WinHTTP 함수 중 첫 번째 함수입니다. 내부 WinHTTP 데이터 구조를 초기화하고 애플리케이션에서 향후 호출을 준비합니다. 애플리케이션이 WinHTTP 함수를 사용하여 완료되면 WinHttpCloseHandle 을 호출하여 세션 핸들 및 연결된 리소스를 해제해야 합니다.

애플리케이션은 WinHttpOpen을 호출할 수 있지만 일반적으로 단일 호출로 충분합니다. WinHttpOpen에 대한 각 호출은 새 세션 컨텍스트를 엽니다. 사용자 데이터는 여러 세션 컨텍스트 간에 공유되지 않으므로 여러 사용자를 대신하여 요청을 하는 애플리케이션은 사용자별 쿠키 및 인증 상태를 공유하지 않도록 각 사용자에 대해 별도의 세션을 만들어야 합니다. 애플리케이션은 각각에 대해 구성된 서로 다른 프록시 서버와 같이 각 WinHttpOpen instance 대해 별도의 동작을 정의해야 합니다.

WinHttpOpen에서 반환된 HINTERNET 핸들을 사용하여 호출 애플리케이션을 완료한 후에는 WinHttpCloseHandle 함수를 사용하여 닫아야 합니다.

참고 Windows XP 및 Windows 2000의 경우 런타임 요구 사항을 참조하세요.
 

예제

다음 예제 코드에서는 기본 연결 제한 시간 값을 검색하는 방법을 보여 있습니다.


    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {


        // Use WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", 
                    GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

요구 사항

   
지원되는 최소 클라이언트 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 버전

WinHttpCloseHandle