WINHTTP_STATUS_CALLBACK回呼函式 (winHTTP.h)

發行項
03/04/2024

WINHTTP_STATUS_CALLBACK類型代表應用程式定義的狀態回呼函式。

語法

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

參數

[in] hInternet

呼叫回呼函式的句柄。

[in] dwContext

DWORD 的指標，指定與 hInternet 參數中句柄相關聯的應用程式定義內容值。

使用 WINHTTP_OPTION_CONTEXT_VALUE 選項呼叫 WinHttpSetOption，即可將內容值指派給會話、連線或要求句柄。或者， WinHttpSendRequest 可用來將內容值與要求句柄產生關聯。

[in] dwInternetStatus

指向指定呼叫回呼函式原因的狀態代碼的 DWORD 。這個值可以是下列其中一個值：

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION

關閉與伺服器的連線。 lpvStatusInformation 參數為 NULL。

WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER

已成功連線到伺服器。 lpvStatusInformation 參數包含 LPWSTR 的指標，表示以虛線表示法表示伺服器的 IP 位址。

WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER

線上到伺服器。 lpvStatusInformation 參數包含 LPWSTR 的指標，表示以虛線表示法表示伺服器的 IP 位址。

WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

已成功關閉與伺服器的連線。 lpvStatusInformation 參數為 NULL。

WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

可以使用 WinHttpReadData 來擷取數據。 lpvStatusInformation 參數會指向包含可用數據位元組數目的 DWORD。 dwStatusInformationLength 參數本身是 4 (DWORD) 的大小。

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

已建立 HINTERNET 句柄。 lpvStatusInformation 參數包含 HINTERNET 句柄的指標。

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

這個句柄值已終止。 lpvStatusInformation 參數包含 HINTERNET 句柄的指標。此句柄不會再回呼。

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

已收到響應標頭，並可供 WinHttpQueryHeaders 使用。 lpvStatusInformation 參數為 NULL。

WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE

收到來自伺服器的中繼 (100 個層級) 狀態代碼訊息。 lpvStatusInformation 參數包含指出狀態代碼的 DWORD 指標。

WINHTTP_CALLBACK_STATUS_NAME_RESOLVED

已成功找到伺服器的IP位址。 lpvStatusInformation 參數包含 LPWSTR 的指標，指出已解析的名稱。

WINHTTP_CALLBACK_STATUS_READ_COMPLETE

已成功從伺服器讀取數據。 lpvStatusInformation 參數包含 WinHttpReadData 呼叫中指定的緩衝區指標。 dwStatusInformationLength 參數包含讀取的位元組數目。

WinHttpWebSocketReceive 使用時，lpvStatusInformation 參數包含WINHTTP_WEB_SOCKET_STATUS結構的指標，而 dwStatusInformationLength 參數表示 lpvStatusInformation 的大小。

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE

等候伺服器回應要求。 lpvStatusInformation 參數為 NULL。

WINHTTP_CALLBACK_STATUS_REDIRECT

HTTP 要求即將自動重新導向要求。 lpvStatusInformation 参數包含指出新 URL 的 LPWSTR 指標。此時，應用程式可以使用重新導向回應讀取伺服器傳回的任何數據，並可查詢回應標頭。它也可以藉由關閉句柄來取消作業。

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

傳送 HTTP 要求時發生錯誤。 lpvStatusInformation 參數包含WINHTTP_ASYNC_RESULT結構的指標。其 dwResult 成員表示所呼叫函式的標識碼， 而 dwError 則表示傳回值。

WINHTTP_CALLBACK_STATUS_REQUEST_SENT

成功將資訊要求傳送至伺服器。 lpvStatusInformation 參數包含指出所傳送位元組數目的 DWORD 指標。

WINHTTP_CALLBACK_STATUS_RESOLVING_NAME

查閱伺服器名稱的IP位址。 lpvStatusInformation 參數包含要解析的伺服器名稱指標。

WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED

已成功從伺服器收到回應。 lpvStatusInformation 參數包含 DWORD 的指標，指出收到的位元組數目。

WINHTTP_CALLBACK_STATUS_SECURE_FAILURE

建立與伺服器的安全 (HTTPS) 連線時，發生一或多個錯誤。 lpvStatusInformation 參數包含 DWORD 的指標，這是錯誤值的位 OR 組合。如需詳細資訊，請參閱 lpvStatusInformation 的描述。

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

將資訊要求傳送至伺服器。 lpvStatusInformation 參數為 NULL。

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

要求已順利完成。 lpvStatusInformation 參數是傳遞至 WinHttpSendRequest 的 lpOptional 值， (初始要求本文) ，而 dwStatusInformationLength 參數會指出 (傳遞至 WinHttpSendRequest) 的 dwOptionalLength 值成功寫入這類初始本文字節數目。

WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

數據已成功寫入伺服器。 lpvStatusInformation 參數包含指出寫入位元組數目的 DWORD 指標。

WinHttpWebSocketSend 使用時，lpvStatusInformation 參數包含WINHTTP_WEB_SOCKET_STATUS結構的指標，而 dwStatusInformationLength 參數表示 lpvStatusInformation 的大小。

WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE

呼叫 WinHttpGetProxyForUrlEx 所起始的作業已完成。可以使用 WinHttpReadData 來擷取數據。

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

透過呼叫 WinHttpWebSocketClose 成功關閉連線。 lpvStatusInformation 參數為 NULL。

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

線上已成功透過對 WinHttpWebSocketShutdown 的呼叫關閉。 lpvStatusInformation 參數為 NULL。

[in] lpvStatusInformation

緩衝區的指標，指定這個回呼函式呼叫的相關信息。這些數據的格式取決於 dwInternetStatus 自變數的值。如需詳細資訊，請參閱 dwInternetStatus。

如果 dwInternetStatus 自變數是WINHTTP_CALLBACK_STATUS_SECURE_FAILURE， 則 lpvStatusInformation 會指向 DWORD，這是下列一或多個值的位 OR 組合。

值	意義
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED	憑證撤銷檢查已啟用，但撤銷檢查無法驗證是否已撤銷憑證。用來檢查撤銷的伺服器可能無法連線。
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT	SSL 憑證無效。
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED	SSL 憑證已撤銷。
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA	函式不熟悉產生伺服器證書的證書頒發機構單位。
WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID	SSL 憑證一般名稱 (主機名字段) 不正確，例如，如果您輸入 www.microsoft.com，且憑證上的一般名稱會顯示 www.msn.com。
WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID	從伺服器收到的 SSL 憑證日期不正確。憑證已過期。
WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR	應用程式載入 SSL 連結庫時發生內部錯誤。

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT狀態回呼會提供 dwStatusInformationLength 值，其對應於 lpvStatusInformation 所指向之 LPWSTR 的字元計數。

傳回值

無

備註

回呼函式必須是 threadafe 和 reentrant，因為它可以在另一個線程上針對個別要求呼叫，並在目前要求的相同線程上重新輸入。因此，必須撰寫程序代碼，才能在處理時安全地處理重新進入。當 dwInternetStatus 參數等於 WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING時，回呼不需要能夠處理相同要求的重新輸入，因為此回呼保證為最後一個，而且不會在處理此要求的其他訊息時發生。

狀態回呼函式會透過通知旗標接收異步操作狀態的更新。指出特定作業已完成的通知稱為完成通知，或只是完成。下表列出六個完成旗標，以及收到此旗標時完成的對應函式。

完成旗標	函式
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE	WinHttpQueryDataAvailable
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE	WinHttpReceiveResponse
WINHTTP_CALLBACK_STATUS_READ_COMPLETE	WinHttpReadData
WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE	WinHttpSendRequest
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE	WinHttpWriteData
WINHTTP_CALLBACK_STATUS_REQUEST_ERROR	發生錯誤時，上述任何函式。

因為回呼是在處理要求期間進行，所以應用程式應該花較少的時間在回呼函式中，以避免降低網路上的數據輸送量。例如，在回呼函式中顯示對話方塊可能是伺服器終止要求的冗長作業。

回呼函式可以在與起始要求之線程不同的線程內容中呼叫。

同樣地，當您以異步方式呼叫 WinHttp 時，沒有回呼線程親和性：呼叫可能會從一個線程啟動，但任何其他線程都可以接收回呼。

注意如需在 Windows XP 和 Windows 2000 中實作的詳細資訊，請參閱運行時間需求。

規格需求

需求	值
最低支援的用戶端	Windows XP、Windows 2000 Professional 與 SP3 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003、具有 SP3 的 Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winhttp.h
可轉散發套件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更新版本。

另請參閱

WinHTTP 版本

WinHttpSetStatusCallback

共用方式為