Функция WinHttpOpenRequest (winhttp.h)

  • Статья

Функция WinHttpOpenRequest создает дескриптор HTTP-запроса.

Синтаксис

WINHTTPAPI HINTERNET WinHttpOpenRequest(
  [in] HINTERNET hConnect,
  [in] LPCWSTR   pwszVerb,
  [in] LPCWSTR   pwszObjectName,
  [in] LPCWSTR   pwszVersion,
  [in] LPCWSTR   pwszReferrer,
  [in] LPCWSTR   *ppwszAcceptTypes,
  [in] DWORD     dwFlags
);

Параметры

[in] hConnect

Дескриптор подключения HINTERNET к сеансу HTTP, возвращаемого WinHttpConnect.

[in] pwszVerb

Указатель на строку, содержащую HTTP-команду , используемую в запросе. Если этот параметр имеет значение NULL, функция использует GET в качестве HTTP-команды. Примечание Эта строка должна быть в верхнем регистре. Многие серверы обрабатывают HTTP-команды как чувствительные к регистру, а запросы примечаний (RFC) целевой группы интернет-инженеров (IETF) пишут эти команды только символами верхнего регистра.

[in] pwszObjectName

Указатель на строку, содержащую имя целевого ресурса указанной HTTP-команды. Обычно это имя файла, исполняемый модуль или описатель поиска.

[in] pwszVersion

Указатель на строку, содержащую версию HTTP. Если этот параметр имеет значение NULL, функция использует HTTP/1.1.

[in] pwszReferrer

Указатель на строку, указывающую URL-адрес документа, из которого был получен URL-адрес в запросе pwszObjectName . Если для этого параметра задано значение WINHTTP_NO_REFERER, ссылающийся документ не указан.

[in] ppwszAcceptTypes

Указатель на массив строковых указателей со значением NULL, указывающий типы мультимедиа, принимаемые клиентом. Если для этого параметра задано значение WINHTTP_DEFAULT_ACCEPT_TYPES, клиент не принимает типы. Как правило, серверы обрабатывают отсутствие принятых типов как признак того, что клиент принимает только документы типа "text/*"; то есть только текстовые документы — нет изображений или других двоичных файлов. Список допустимых типов мультимедиа см. в разделе Типы мультимедиа, определенные IANA по адресу http://www.iana.org/assignments/media-types/.

[in] dwFlags

Длинное целочисленное значение без знака, содержащее значения флага Интернета. Здесь могут содержаться одно или несколько значений из следующего списка:

Значение Значение
WINHTTP_FLAG_BYPASS_PROXY_CACHE
 Этот флаг обеспечивает то же поведение, что и WINHTTP_FLAG_REFRESH.
WINHTTP_FLAG_ESCAPE_DISABLE
 Небезопасные символы в URL-адресе, переданном для pwszObjectName , не преобразуются в escape-последовательности.
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY
 Небезопасные символы в компоненте запроса URL-адреса, переданного для pwszObjectName , не преобразуются в escape-последовательности.
WINHTTP_FLAG_ESCAPE_PERCENT
 Строка, передаваемая для pwszObjectName , преобразуется из LPCWSTR в LPSTR. Все небезопасные символы преобразуются в escape-последовательность, включая символ процента. По умолчанию все небезопасные символы, кроме символа процента, преобразуются в escape-последовательность.
WINHTTP_FLAG_NULL_CODEPAGE
 Предполагается, что строка, передаваемая для pwszObjectName , состоит из допустимых символов ANSI, представленных WCHAR. Для небезопасных символов не выполняется проверка.

Windows 7: Этот параметр устарел.
WINHTTP_FLAG_REFRESH
 Указывает, что запрос должен быть переадресован на исходный сервер, а не отправлять кэшированную версию ресурса с прокси-сервера. При использовании этого флага в дескриптор запроса добавляется заголовок Pragma: no-cache. При создании заголовка запроса HTTP/1.1 также добавляется элемент Cache-Control: no-cache.
WINHTTP_FLAG_SECURE
 Использует безопасную семантику транзакций. Это преобразуется в использование протокола SSL или tls.

Возвращаемое значение

Возвращает допустимый дескриптор HTTP-запроса в случае успешного выполнения или значение NULL , если нет. Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError. Среди возвращаемых кодов ошибок приведены следующие.

Код ошибки Описание
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
 Для этой операции указан неправильный тип дескриптора.
ERROR_WINHTTP_INTERNAL_ERROR
 Произошла внутренняя ошибка.
ERROR_WINHTTP_INVALID_URL
 Недопустимый URL-адрес.
ERROR_WINHTTP_OPERATION_CANCELLED
 Операция была отменена, как правило, из-за того, что дескриптор, с которым работал запрос, был закрыт до завершения операции.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
 URL-адрес указывает схему, отличаемую от "http:" или "https:".
ERROR_NOT_ENOUGH_MEMORY
 Недостаточно памяти для выполнения запрошенной операции. (Код ошибки Windows)

Комментарии

Возвращаемое значение указывает на успех или сбой. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Функция WinHttpOpenRequest создает новый дескриптор HTTP-запроса и сохраняет указанные параметры в этом дескрипторе. Дескриптор HTTP-запроса содержит запрос для отправки на HTTP-сервер и содержит все заголовки RFC822/MIME/HTTP, отправляемые как часть запроса.

Если для pwszVerb задано значение "HEAD", заголовок Content-Length игнорируется.

Если функция обратного вызова состояния была установлена с winHttpSetStatusCallback, WINHTTP_CALLBACK_STATUS_HANDLE_CREATED уведомление указывает , что WinHttpOpenRequest создал дескриптор запроса.

После завершения работы вызывающего приложения с помощью дескриптора HINTERNET , возвращаемого WinHttpOpenRequest, его необходимо закрыть с помощью функции WinHttpCloseHandle .

Примечание Для Windows XP и Windows 2000 см. раздел Требования во время выполнения начальной страницы WinHttp.
 

Примеры

В этом примере показано, как получить дескриптор HINTERNET , открыть сеанс HTTP, создать заголовок запроса и отправить его на сервер.


    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.wingtiptoys.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

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

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

    // PLACE ADDITIONAL CODE HERE.

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

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

Требования

Требование Значение
Минимальная версия клиента Windows XP, Windows 2000 Профессиональная с пакетом обновления 3 (SP3) [только классические приложения]
Минимальная версия сервера Windows Server 2003, Windows 2000 Server с пакетом обновления 3 (SP3) [только классические приложения]
Целевая платформа Windows
Header winhttp.h
Библиотека Winhttp.lib
DLL Winhttp.dll
Распространяемые компоненты WinHTTP 5.0 и Internet Обозреватель 5.01 или более поздней версии в Windows XP и Windows 2000.

См. также раздел

Сведения о службах HTTP Microsoft Windows (WinHTTP)

Версии WinHTTP

WinHttpConnect

WinHttpOpen