WinHttpSetStatusCallback 函数 (winhttp.h)

  • 项目

WinHttpSetStatusCallback 函数设置一个回调函数，WinHTTP 可以在操作过程中进行进度时调用该回调函数。

语法

WINHTTPAPI WINHTTP_STATUS_CALLBACK WinHttpSetStatusCallback(
  [in] HINTERNET               hInternet,
  [in] WINHTTP_STATUS_CALLBACK lpfnInternetCallback,
  [in] DWORD                   dwNotificationFlags,
  [in] DWORD_PTR               dwReserved
);

参数

[in] hInternet

要为其设置回调的 HINTERNET 句柄。

[in] lpfnInternetCallback

指向进度时要调用的回调函数的指针。 将此设置为 NULL 可删除现有的回调函数。 有关回调函数的详细信息，请参阅 WINHTTP_STATUS_CALLBACK。

[in] dwNotificationFlags

无符号长整数值，该值指定标志以指示哪些事件激活回调函数。

可能的值如下所示。

值 含义
WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS
 在任何完成通知后激活。 此标志指定使用读取或写入操作所需的所有通知。 有关完成列表 ，请参阅WINHTTP_STATUS_CALLBACK 。
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS
 在任何状态更改通知（包括完成）时激活。 有关通知列表，请参阅 WINHTTP_STATUS_CALLBACK 。
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME
 在开始和完成名称解析时激活。
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER
 在开始和完成与服务器的连接时激活。
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY
 检测代理服务器时激活。
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE
 在完成数据查询时激活。
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE
 当响应标头可供检索时激活。
WINHTTP_CALLBACK_FLAG_READ_COMPLETE
 数据读取操作完成后激活。
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR
 发生异步错误时激活。
WINHTTP_CALLBACK_FLAG_SEND_REQUEST
 使用 WinHttpSendRequest 开始并完成请求标头的发送时激活。
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE
 使用 WinHttpSendRequest 发送请求标头时激活。
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE
 数据后操作完成后激活。
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE
 从 HTTP 服务器开始并完成资源接收时激活。
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION
 在开始和完成 HTTP 连接关闭时激活。
WINHTTP_CALLBACK_FLAG_HANDLES
 在创建或关闭 HINTERNET 句柄时激活。
WINHTTP_CALLBACK_FLAG_REDIRECT
 重定向请求时激活。
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE
 从服务器接收中间 (100 级别) 状态代码消息时激活。
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE
 在安全连接失败时激活。

[in] dwReserved

此参数是保留的，必须为 NULL。

返回值

如果成功，则返回指向以前定义的状态回调函数的指针;如果没有以前定义的状态回调函数，则返回 NULL 。 如果无法安装回调函数，则返回 WINHTTP_INVALID_STATUS_CALLBACK 。 有关扩展的错误信息，请调用 GetLastError。 返回的错误代码如下。

错误代码 说明
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
 为此操作提供的句柄类型不正确。
ERROR_WINHTTP_INTERNAL_ERROR
 发生了内部错误。
ERROR_NOT_ENOUGH_MEMORY
 内存不足，无法完成请求的操作。 (Windows 错误代码)

注解

如果在创建请求句柄之前对会话句柄设置回调，则请求句柄会从其父会话继承回调函数指针。

即使在异步模式下使用 WinHTTP (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC时，此函数也会同步运行。 返回值指示成功或失败。 要获得更多的错误信息，请调用 GetLastError。

同步函数和异步函数都使用回调函数来指示请求的进度，例如解析名称、连接到服务器等。 异步操作需要回调函数。

回调函数可以在任何句柄上设置，并由派生的句柄继承。 可以使用 WinHttpSetStatusCallback 更改回调函数，前提是没有需要使用以前的回调值的挂起请求。 但是，更改句柄上的回调函数不会更改派生句柄上的回调，例如 WinHttpConnect 返回的回调。 必须在每个级别更改回调函数。

许多 WinHTTP 函数在网络上执行多个操作。 每个操作可能需要一段时间才能完成，并且每个操作都可能失败。

启动 WinHttpSetStatusCallback 函数后，可以从 WinHTTP 内部访问回调函数，以监视耗时的网络操作。

在异步处理结束时，应用程序可能会将回调函数设置为 NULL。 这会阻止客户端应用程序接收其他通知。

以下代码片段显示了将回调函数设置为 NULL 的建议方法。

WinHttpSetStatusCallback( hOpen,
                          NULL,
                          WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
                          NULL );

但请注意，WinHTTP 不会将 WinHttpSetStatusCallback 与工作线程同步。 如果应用程序调用 WinHttpSetStatusCallback 时，源自另一个线程的回调正在进行中，则即使 WinHttpSetStatusCallback 成功将回调函数设置为 NULL 并返回，应用程序仍会收到回调通知。

注意 对于 Windows XP 和 Windows 2000，请参阅 WinHttp 起始页的 运行时要求 部分。
 

示例

以下示例演示如何为异步 WinHTTP 函数安装回调函数。 该示例假定之前已实现名为“AsyncCallback ( ) ”的WINHTTP_STATUS_CALLBACK函数：

    // 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)
    {
        // Install the status callback function.
        WINHTTP_STATUS_CALLBACK isCallback = WinHttpSetStatusCallback( hSession,
                                               (WINHTTP_STATUS_CALLBACK)AsyncCallback,
                                               WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS, 
                                               NULL);
                                               
        // Place additional code here.
    
        // 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
Library Winhttp.lib
DLL Winhttp.dll
可再发行组件 Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。

另请参阅

关于 Microsoft Windows HTTP Services (WinHTTP)

WINHTTP_STATUS_CALLBACK

WinHTTP 版本

WinHttpConnect

WinHttpOpen