WinHttpAddRequestHeaders 함수(winhttp.h)

  • 아티클

WinHttpAddRequestHeaders 함수는 HTTP 요청 핸들에 하나 이상의 HTTP 요청 헤더를 추가합니다.

구문

WINHTTPAPI BOOL WinHttpAddRequestHeaders(
  [in] HINTERNET hRequest,
  [in] LPCWSTR   lpszHeaders,
  [in] DWORD     dwHeadersLength,
  [in] DWORD     dwModifiers
);

매개 변수

[in] hRequest

WinHttpOpenRequest 함수를 호출하여 반환된 HINTERNET 핸들입니다.

[in] lpszHeaders

요청에 추가할 헤더를 포함하는 문자열 변수에 대한 포인터입니다. 마지막을 제외한 각 헤더는 CR/LF(캐리지 리턴/줄 바꿈)로 종료되어야 합니다.

[in] dwHeadersLength

pwszHeaders의 길이(문자)를 포함하는 부호 없는 긴 정수 값입니다. 이 매개 변수가 -1L인 경우 함수는 pwszHeaders 가 ASCIIZ(0-terminated)이고 길이가 계산된다고 가정합니다.

[in] dwModifiers

이 함수의 의미 체계를 수정하는 데 사용되는 플래그를 포함하는 부호 없는 긴 정수 값입니다. 다음 플래그 중 하나 이상일 수 있습니다.

값 의미
WINHTTP_ADDREQ_FLAG_ADD
 헤더가 없으면 헤더를 추가합니다. WINHTTP_ADDREQ_FLAG_REPLACE 함께 사용됩니다.
WINHTTP_ADDREQ_FLAG_ADD_IF_NEW
 헤더가 없는 경우에만 추가합니다. 그렇지 않으면 오류가 반환됩니다.
WINHTTP_ADDREQ_FLAG_COALESCE
 같은 이름의 헤더를 병합합니다.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA
 쉼표로 같은 이름의 헤더를 병합합니다. 예를 들어 이 플래그와 함께 "Accept: text/*" 뒤에 "Accept: audio/*"를 추가하면 단일 헤더 "Accept: text/*, audio/*"가 생성됩니다. 이렇게 하면 첫 번째 헤더가 병합됩니다. 호출 애플리케이션은 병합된 헤더와 별도의 헤더와 관련하여 응집력 있는 체계를 보장해야 합니다.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON
 세미콜론을 사용하여 동일한 이름의 헤더를 병합합니다.
WINHTTP_ADDREQ_FLAG_REPLACE
 헤더를 바꾸거나 제거합니다. 헤더 값이 비어 있고 헤더가 있으면 제거됩니다. 값이 비어 있지 않으면 이 값이 바뀝니다.

반환 값

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

오류 코드 Description
ERROR_WINHTTP_INCORRECT_HANDLE_STATE
 제공된 핸들이 올바른 상태가 아니므로 요청된 작업을 수행할 수 없습니다.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
 이 작업에 대해 제공된 핸들의 형식이 올바르지 않습니다.
ERROR_WINHTTP_INTERNAL_ERROR
 내부 오류가 발생했습니다.
ERROR_NOT_ENOUGH_MEMORY
 메모리가 부족하여 요청된 작업을 완료할 수 없습니다.

설명

헤더는 리디렉션 간에 전송됩니다. 이는 보안 문제일 수 있습니다. 리디렉션이 발생할 때 헤더가 전송되지 않도록 하려면 WINHTTP_STATUS_CALLBACK 콜백을 사용하여 리디렉션이 발생할 때 특정 헤더를 수정합니다.

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

WinHttpAddRequestHeaders 함수는 추가 자유 형식 헤더를 HTTP 요청 핸들에 추가하며 HTTP 서버로 전송된 정확한 요청에 대한 자세한 제어가 필요한 정교한 클라이언트에서 사용하기 위한 것입니다.

이 함수와 함께 추가된 요청 헤더의 이름과 값의 유효성이 검사됩니다. 헤더는 잘 구성되어야 합니다. 유효한 HTTP 헤더에 대한 자세한 내용은 RFC 2616을 참조하세요. 잘못된 헤더를 사용하면 이 함수가 실패하고 GetLastError가ERROR_INVALID_PARAMETER 반환합니다. 잘못된 헤더가 추가되지 않았습니다.

Date: request 헤더를 보내는 경우 WinHttpTimeFromSystemTime 함수를 사용하여 헤더에 대한 구조를 만들 수 있습니다.

기본 WinHttpAddRequestHeaders의 경우 애플리케이션은 단일 버퍼에서 여러 헤더를 전달할 수 있습니다.

또한 애플리케이션은 WinHttpSendRequest 를 사용하여 요청을 보내기 전에 HTTP 요청 핸들에 헤더를 추가할 수 있습니다.

참고 자세한 내용은 런타임 요구 사항을 참조하세요.
 

예제

다음 코드 예제에는 요청에 If-Modified-Since 헤더가 포함되어 있습니다. 응답 헤더는 대상 문서가 업데이트되었는지 여부를 확인하기 위해 해석됩니다.


  DWORD dwSize = sizeof(DWORD);
  DWORD dwStatusCode = 0;
  BOOL  bResults = FALSE;
  HINTERNET hSession = NULL,
        hConnect = NULL,
        hRequest = NULL;

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

  // Specify an HTTP server.
  if( hSession )
    hConnect = WinHttpConnect( hSession,
                               L"www.microsoft.com",
                               INTERNET_DEFAULT_HTTP_PORT,
                               0 );

  // Create an HTTP Request handle.
  if( hConnect )
    hRequest = WinHttpOpenRequest( hConnect,
                                   L"GET",
                                   NULL, 
                                   NULL,
                                   WINHTTP_NO_REFERER, 
                                   WINHTTP_DEFAULT_ACCEPT_TYPES,
                                   0 );

  // Add a request header.
  if( hRequest )
    bResults = WinHttpAddRequestHeaders( hRequest, 
                 L"If-Modified-Since: Mon, 20 Nov 2000 20:00:00 GMT",
                                         (ULONG)-1L,
                                         WINHTTP_ADDREQ_FLAG_ADD );

  // Send a Request.
  if( bResults ) 
    bResults = WinHttpSendRequest( hRequest, 
                                   WINHTTP_NO_ADDITIONAL_HEADERS,
                                   0,
                                   WINHTTP_NO_REQUEST_DATA,
                                   0, 
                                   0,
                                   0 );

  // End the request.
  if( bResults )
    bResults = WinHttpReceiveResponse( hRequest, NULL);

  // Use WinHttpQueryHeaders to obtain the header buffer.
  if( bResults )
    bResults = WinHttpQueryHeaders( hRequest, 
                WINHTTP_QUERY_STATUS_CODE | WINHTTP_QUERY_FLAG_NUMBER,
                                    NULL, 
                                    &dwStatusCode,
                                    &dwSize,
                                    WINHTTP_NO_HEADER_INDEX );

  // Based on the status code, determine whether 
  // the document was recently updated.
  if( bResults )
  {
    if( dwStatusCode == 304 ) 
      printf( "Document has not been updated.\n" );
    else if( dwStatusCode == 200 ) 
      printf( "Document has been updated.\n" );
    else 
      printf( "Status code = %u.\n",dwStatusCode );
  }

  // Report any errors.
  if( !bResults )
    printf( "Error %d has occurred.\n", GetLastError( ) );

  // Close open handles.
  if( hRequest ) WinHttpCloseHandle( hRequest );
  if( hConnect ) WinHttpCloseHandle( hConnect );
  if( hSession ) WinHttpCloseHandle( hSession );

요구 사항

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

WinHttpOpenRequest

WinHttpSendRequest