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
 偵測 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、具有 SP3 的 Windows 2000 Server [僅限傳統型應用程式]
目標平台 Windows
標頭 winhttp.h
程式庫 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