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
필요한 액세스 유형입니다. 다음 값 중 하나일 수 있습니다.
| 값 | 의미 |
|---|---|
|
프록시 없이 모든 호스트 이름을 직접 확인합니다. |
|
중요 이 옵션의 사용은 Windows 8.1 이상에서 더 이상 사용되지 않습니다. 대신 WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY 사용합니다.
WinHTTP 프록시 구성은 이러한 메커니즘 중 하나에 의해 설정됩니다.
|
|
프록시 바이패스 목록을 제공하고 확인할 이름이 프록시를 무시하지 않는 한 프록시에 요청을 전달합니다. 이 경우 이 함수는 pwszProxyName 및 pwszProxyBypass에 전달된 값을 사용합니다. |
|
시스템 및 사용자별 프록시 설정(인터넷 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 함수를 비동기적으로 사용합니다. 기본적으로 반환된 HINTERNET 핸들을 사용하는 모든 WinHTTP 함수는 동기적으로 수행됩니다. 이 플래그가 설정되면 호출자는 WinHttpSetStatusCallback을 통해 콜백 함수를 지정해야 합니다. |
|
이 플래그가 설정되면 WinHttp에서 TLS 1.2 이상을 사용해야 합니다. 호출자가 WINHTTP_OPTION_SECURE_PROTOCOLS 설정하여 이전 TLS 버전을 사용하도록 설정하려고 하면 ERROR_ACCESS_DENIED 함께 실패합니다. 또한 TLS 대체는 사용하지 않도록 설정됩니다. 이 플래그를 설정하면 플래그 WINHTTP_FLAG_ASYNC 설정됩니다. |
반환 값
성공하면 유효한 세션 핸들을 반환하고, 그렇지 않으면 NULL 을 반환합니다. 확장된 오류 정보를 검색하려면 GetLastError를 호출합니다. 반환된 오류 코드 중에는 다음과 같습니다.
| 오류 코드 | Description |
|---|---|
|
내부 오류가 발생했습니다. |
|
요청된 작업을 완료하는 데 사용할 수 있는 메모리가 부족합니다. (Windows 오류 코드) |
설명
비동기 모드에서 WinHTTP를 사용하는 것이 좋습니다(즉, WinHttpOpen에서 WINHTTP_FLAG_ASYNC 설정된 경우 반환된 HINTERNET의 사용이 비동기화되도록). 반환 값은 성공 또는 실패를 나타냅니다. 확장된 오류 정보를 검색하려면 GetLastError를 호출합니다.
WinHttpOpen 함수는 애플리케이션에서 호출하는 WinHTTP 함수 중 첫 번째 함수입니다. 내부 WinHTTP 데이터 구조를 초기화하고 애플리케이션에서 향후 호출을 준비합니다. 애플리케이션이 WinHTTP 함수를 사용하여 완료되면 WinHttpCloseHandle 을 호출하여 세션 핸들 및 연결된 리소스를 해제해야 합니다.
애플리케이션은 WinHttpOpen을 호출할 수 있지만 일반적으로 단일 호출로 충분합니다. WinHttpOpen에 대한 각 호출은 새 세션 컨텍스트를 엽니다. 사용자 데이터는 여러 세션 컨텍스트 간에 공유되지 않으므로 여러 사용자를 대신하여 요청을 하는 애플리케이션은 사용자별 쿠키 및 인증 상태를 공유하지 않도록 각 사용자에 대해 별도의 세션을 만들어야 합니다. 애플리케이션은 각각에 대해 구성된 서로 다른 프록시 서버와 같이 각 WinHttpOpen instance 대해 별도의 동작을 정의해야 합니다.
WinHttpOpen에서 반환된 HINTERNET 핸들을 사용하여 호출 애플리케이션을 완료한 후에는 WinHttpCloseHandle 함수를 사용하여 닫아야 합니다.
예제
다음 예제 코드에서는 기본 연결 제한 시간 값을 검색하는 방법을 보여 있습니다.
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 이상. |