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

WinHttpConnect 返回的 HTTP 会话的 HINTERNET 连接句柄。

[in] pwszVerb

指向包含要用于请求的 HTTP 谓词 的字符串的指针。 如果此参数为 NULL，则该函数使用 GET 作为 HTTP 谓词。 注意 此字符串应全部为大写。 许多服务器将 HTTP 谓词视为区分大小写，Internet 工程任务组 (IETF) 注释请求 (RFC) 仅使用大写字符拼写这些谓词。

[in] pwszObjectName

指向包含指定 HTTP 谓词的目标资源名称的字符串的指针。 这通常是文件名、可执行模块或搜索说明符。

[in] pwszVersion

指向包含 HTTP 版本的字符串的指针。 如果此参数为 NULL，则该函数使用 HTTP/1.1。

[in] pwszReferrer

指向字符串的指针，该字符串指定从中获取 请求 pwszObjectName 中的 URL 的文档的 URL。 如果此参数设置为 WINHTTP_NO_REFERER，则不指定引用文档。

[in] ppwszAcceptTypes

指向以 null 结尾的字符串指针数组的指针的指针，该数组指定客户端接受的媒体类型。 如果此参数设置为 WINHTTP_DEFAULT_ACCEPT_TYPES，则客户端不会接受任何类型。 通常，服务器处理缺少接受的类型，指示客户端仅接受类型为“text/*”的文档;即，仅文本文档-无图片或其他二进制文件。 有关有效媒体类型的列表，请参阅 上 http://www.iana.org/assignments/media-types/由 IANA 定义的媒体类型。

[in] dwFlags

包含 Internet 标志值的无符号长整数值。 该选项可以是如下一个或多个值：

值 含义
WINHTTP_FLAG_BYPASS_PROXY_CACHE
 此标志提供与 WINHTTP_FLAG_REFRESH相同的行为。
WINHTTP_FLAG_ESCAPE_DISABLE
 为 pwszObjectName 传入的 URL 中的不安全字符不会转换为转义序列。
WINHTTP_FLAG_ESCAPE_DISABLE_QUERY
 为 pwszObjectName 传入的 URL 的查询组件中的不安全字符不会转换为转义序列。
WINHTTP_FLAG_ESCAPE_PERCENT
 为 pwszObjectName 传入的字符串将从 LPCWSTR 转换为 LPSTR。 所有不安全字符都转换为包含百分比符号的转义序列。 默认情况下，除百分比符号之外的所有不安全字符都转换为转义序列。
WINHTTP_FLAG_NULL_CODEPAGE
 为 pwszObjectName 传入的字符串假定由 WCHAR 表示的有效 ANSI 字符组成。 不会对不安全字符执行任何检查。

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 已创建请求句柄。

调用应用程序使用 WinHttpOpenRequest 返回的 HINTERNET 句柄后，必须使用 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 Professional SP3 [仅限桌面应用]
最低受支持的服务器 Windows Server 2003、Windows 2000 Server SP3 [仅限桌面应用]
目标平台 Windows
标头 winhttp.h
Library Winhttp.lib
DLL Winhttp.dll
可再发行组件 Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。

另请参阅

关于 Microsoft Windows HTTP Services (WinHTTP)

WinHTTP 版本

WinHttpConnect

WinHttpOpen