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

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

可能的值如下所示。

[in] dwReserved

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

返回值

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

注解

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

即使在异步模式下使用 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 并返回，应用程序仍会收到回调通知。

示例

以下示例演示如何为异步 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());
    }

要求

另请参阅

关于 Microsoft Windows HTTP Services (WinHTTP)

WINHTTP_STATUS_CALLBACK

WinHTTP 版本

WinHttpConnect

WinHttpOpen