共用方式為


WINHTTP_STATUS_CALLBACK回呼函式 (winHTTP.h)

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 參數會指向包含可用數據位元組數目的 DWORDdwStatusInformationLength 參數本身是 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