Функция 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-команды как конфиденциальные регистры, а запросы IETF (IETF) заклинания для комментариев (RFCS) выполняют эти команды только с использованием символов верхнего регистра.

[in] pwszObjectName

Указатель на строку, завершающую значение NULL, содержащую имя целевого ресурса указанной 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

Целое число без знака, содержащее значения флага Интернета. Это может быть одно или несколько следующих значений:

Ценность Meaning
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. Среди возвращенных кодов ошибок приведены следующие коды.

Код ошибки Description
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 см. в разделе "Требования кRun-Time " начальной страницы 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) [классические приложения только]
целевая платформа Виндоус
Header winhttp.h
Library Winhttp.lib
DLL Winhttp.dll
Распространяемый WinHTTP 5.0 и Internet Explorer 5.01 или более поздней версии в Windows XP и Windows 2000.

См. также

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

Версии WinHTTP

WinHttpConnect

WinHttpOpen

  • Last updated on