CHttpFile 類別

發行項
08/04/2024

提供在 HTTP 伺服器上要求和讀取檔案的功能。

語法

class CHttpFile : public CInternetFile

成員

受保護的建構函式

名稱	描述
CHttpFile：：CHttpFile	建立 `CHttpFile` 物件。

公用方法

名稱	描述
CHttpFile：：AddRequestHeaders	將標頭新增至傳送至 HTTP 伺服器的要求。
CHttpFile：：EndRequest	使用 SendRequestEx 成員函式結束傳送至 HTTP 伺服器的要求。
CHttpFile：：GetFileURL	取得指定檔案的 URL。
CHttpFile：：GetObject	取得 HTTP 伺服器要求中動詞命令的目標物件。
CHttpFile：：GetVerb	取得在 HTTP 伺服器要求中使用的動詞。
CHttpFile：：QueryInfo	從 HTTP 伺服器傳回回應或要求標頭。
CHttpFile：：QueryInfoStatusCode	擷取與 HTTP 要求相關聯的狀態代碼，並將它放在提供的 `dwStatusCode` 參數中。
CHttpFile：：SendRequest	將要求傳送至 HTTP 伺服器。
CHttpFile：：SendRequestEx	使用的 Write 或 WriteString 方法 `CInternetFile`，將要求傳送至 HTTP 伺服器。

備註

如果您的因特網會話從 HTTP 伺服器讀取數據，您必須建立的 CHttpFile實例。

若要深入瞭解如何使用CHttpFile其他 MFC 因特網類別，請參閱使用 WinInet 進行因特網程式設計一文。

繼承階層架構

CHttpFile

需求

標頭： afxinet.h

CHttpFile：：AddRequestHeaders

呼叫此成員函式，將一或多個 HTTP 要求標頭新增至 HTTP 要求句柄。

BOOL AddRequestHeaders(
    LPCTSTR pstrHeaders,
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW,
    int dwHeadersLen = -1);

BOOL AddRequestHeaders(
    CString& str,
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW);

參數

pstrHeaders
字串的指標，包含要附加至要求的標頭或標頭。每個標頭都必須由CR/LF配對終止。

dwFlags
修改新標頭的語意。可以是下列其中一項：

HTTP_ADDREQ_FLAG_COALESCE合併相同名稱的標頭，使用旗標將找到的第一個標頭新增至後續標頭。例如，“Accept： text/*” 後面接著 “Accept： audio/*” 會導致形成單一標頭 “Accept： text/*， audio/*”。由呼叫應用程式決定，以確保與以聯合或個別標頭傳送的要求所接收的數據相一致配置。
HTTP_ADDREQ_FLAG_REPLACE執行移除並新增以取代目前的標頭。標頭名稱將用來移除目前的標頭，而完整值將用來新增標頭。如果標頭值是空的，而且找到標頭，則會將其移除。如果不是空的，則會取代標頭值。
HTTP_ADDREQ_FLAG_ADD_IF_NEW只有在標頭不存在時才會新增標頭。如果存在，則會傳回錯誤。
HTTP_ADDREQ_FLAG_ADD與 REPLACE 搭配使用。如果標頭不存在，請加入標頭。

dwHeadersLen
pstrHeaders 的長度，以字元為單位。如果這是 -1L，則 pstrHeaders 會假設為零終止，並計算長度。

str
CString 對象的參考，其中包含要加入的要求標頭或標頭。

傳回值

如果成功則為非零；否則為 0。如果呼叫失敗，可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。

備註

AddRequestHeaders 將額外的免費格式標頭附加至 HTTP 要求句柄。它適用於需要詳細控制傳送至 HTTP 伺服器之確切要求的複雜用戶端。

注意

應用程式可以使用 HTTP_ADDREQ_FLAG_ADD 或 HTTP_ADDREQ_FLAG_ADD_IF_NEW，在 pstrHeaders 或 str 中傳遞多個標頭來AddRequestHeaders呼叫。如果應用程式嘗試使用 HTTP_ADDREQ_FLAG_REMOVE 或 HTTP_ADDREQ_FLAG_REPLACE 移除或取代標頭，則 lpszHeaders 中只能提供一個標頭。

CHttpFile：：CHttpFile

呼叫這個成員函式來建構 CHttpFile 物件。

CHttpFile(
    HINTERNET hFile,
    HINTERNET hSession,
    LPCTSTR pstrObject,
    LPCTSTR pstrServer,
    LPCTSTR pstrVerb,
    DWORD_PTR dwContext);

CHttpFile(
    HINTERNET hFile,
    LPCTSTR pstrVerb,
    LPCTSTR pstrObject,
    CHttpConnection* pConnection);

參數

hFile
因特網檔案的句柄。

hSession
因特網會話的句柄。

pstrObject
包含 CHttpFile 物件的字串指標。

pstrServer
字串的指標，其中包含伺服器的名稱。

pstrVerb
字串的指標，包含傳送要求時要使用的方法。可以是 POST、HEAD 或 GET。

dwContext
對象的內容識別碼 CHttpFile 。如需此參數的詳細資訊，請參閱。

pConnection
CHttpConnection 物件的指標。

備註

您永遠不會直接建構 CHttpFile 物件，而是改為呼叫 CInternetSession：：OpenURL 或 CHttpConnection：：OpenRequest 。

的預設值dwContext是由 MFC 從建立CHttpFile物件的 CInternetSession 物件傳送至 CHttpFile 物件。當您呼叫 CInternetSession::OpenURL 或 CHttpConnection 建構 CHttpFile 物件時，可以覆寫預設值，將內容標識碼設定為您選擇的值。內容標識符會傳回至 CInternetSession：：OnStatusCallback ，以提供識別物件的狀態。如需內容標識碼的詳細資訊，請參閱因特網第一個步驟：WinInet 一文。

CHttpFile：：EndRequest

呼叫此成員函式，以使用 SendRequestEx 成員函式結束傳送至 HTTP 伺服器的要求。

BOOL EndRequest(
    DWORD dwFlags = 0,
    LPINTERNET_BUFFERS lpBuffIn = NULL,
    DWORD_PTR dwContext = 1);

參數

dwFlags
描述作業的旗標。如需適當旗標的清單，請參閱 Windows SDK 中的 HttpEndRequest 。

lpBuffIn
初始化 INTERNET_BUFFERS 指標，描述用於作業的輸入緩衝區。

dwContext
作業的內容識別碼 CHttpFile 。如需此參數的詳細資訊，請參閱。

傳回值

如果成功則為非零；否則為 0。如果呼叫失敗，請檢查擲回的 CInternetException 對象來判斷失敗的原因。

備註

dwContext 的預設值是由 MFC 從建立CHttpFile物件的 CInternetSession 物件傳送至 CHttpFile 物件。當您呼叫 CInternetSession：：OpenURL 或 CHttpConnection 來建構 CHttpFile 物件時，您可以覆寫預設值，將內容識別符設定為您選擇的值。內容標識符會傳回至 CInternetSession：：OnStatusCallback ，以提供識別物件的狀態。如需內容標識碼的詳細資訊，請參閱因特網第一個步驟：WinInet 一文。

CHttpFile：：GetFileURL

呼叫此成員函式，以取得 HTTP 檔案的名稱作為 URL。

virtual CString GetFileURL() const;

傳回值

CString 物件，包含參考與這個檔案相關聯之資源的 URL。

備註

只有在成功呼叫 SendRequest 或 OpenURL 成功建立的物件之後CHttpFile，才使用此成員函式。

CHttpFile：：GetObject

呼叫這個成員函式，以取得與此 CHttpFile相關聯的物件名稱。

CString GetObject() const;

傳回值

包含物件名稱的 CString 物件。

備註

只有在成功呼叫 SendRequest 或 OpenURL 成功建立的物件之後CHttpFile，才使用此成員函式。

CHttpFile：：GetVerb

呼叫這個成員函式，以取得與此 CHttpFile相關聯的 HTTP 動詞命令（或方法）。

CString GetVerb() const;

傳回值

包含 HTTP 動詞指令（或方法）名稱的 CString 物件。

備註

只有在成功呼叫 SendRequest 或 OpenURL 成功建立的物件之後CHttpFile，才使用此成員函式。

CHttpFile：：QueryInfo

呼叫這個成員函式，以從 HTTP 要求傳回回應或要求標頭。

BOOL QueryInfo(
    DWORD dwInfoLevel,
    LPVOID lpvBuffer,
    LPDWORD lpdwBufferLength,
    LPDWORD lpdwIndex = NULL) const;

BOOL QueryInfo(
    DWORD dwInfoLevel,
    CString& str,
    LPDWORD dwIndex = NULL) const;

BOOL QueryInfo(
    DWORD dwInfoLevel,
    SYSTEMTIME* pSysTime,
    LPDWORD dwIndex = NULL) const;

參數

dwInfoLevel
要查詢的屬性組合，以及下列旗標，指定所要求的信息類型：

HTTP_QUERY_CUSTOM尋找標頭名稱，並在輸出時以 lpvBuffer 傳回此值。如果找不到標頭，HTTP_QUERY_CUSTOM會擲回判斷提示。
HTTP_QUERY_FLAG_REQUEST_HEADERS 應用程式通常會查詢回應標頭，但應用程式也可以使用這個旗標來查詢要求標頭。
HTTP_QUERY_FLAG_SYSTEMTIME 對於值為日期/時間字串的標頭，例如 “Last-Modified-Time”，此旗標會將標頭值當做標準 Win32 SYSTEMTIME 結構傳回，而不需要應用程式剖析數據。如果您使用這個旗標，您可能想要使用函 SYSTEMTIME 式的覆寫。
HTTP_QUERY_FLAG_NUMBER 對於值為數字的標頭，例如狀態代碼，此旗標會以 32 位數位傳回數據。

如需可能值的清單，請參閱一節。

lpvBuffer
接收信息的緩衝區指標。

lpdwBufferLength
在進入時，這會以字元數或位元組數指向包含數據緩衝區長度的值。 如需此參數的詳細資訊，請參閱一節。

lpdwIndex
以零起始之標頭索引的指標。可以是 NULL。使用此旗標來列舉具有相同名稱的多個標頭。在輸入時， lpdwIndex 表示要傳回之指定標頭的索引。在輸出上， lpdwIndex 表示下一個標頭的索引。如果找不到下一個索引，則會傳回ERROR_HTTP_HEADER_NOT_FOUND。

str
接收傳回資訊的 CString 對象的參考。

dwIndex
索引值。請參閱 lpdwIndex。

pSysTime
Win32 SYSTEMTIME 結構的指標。

傳回值

如果成功則為非零；否則為 0。如果呼叫失敗，可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。

備註

只有在成功呼叫 SendRequest 或 OpenURL 成功建立的物件之後CHttpFile，才使用此成員函式。

您可以從擷取下列類型的資料 QueryInfo：

字串（預設值）
SYSTEMTIME （適用於 “Data：” “Expires：” etc， headers）
DWORD （適用於STATUS_CODE、CONTENT_LENGTH等）

當字串寫入緩衝區，而成員函式成功時， lpdwBufferLength 會包含終止 NULL 字元的字元減 1 字串長度。

可能的 dwInfoLevel 值包括：

HTTP_QUERY_MIME_VERSION
HTTP_QUERY_CONTENT_TYPE
HTTP_QUERY_CONTENT_TRANSFER_ENCODING
HTTP_QUERY_CONTENT_ID
HTTP_QUERY_CONTENT_DESCRIPTION
HTTP_QUERY_CONTENT_LENGTH
HTTP_QUERY_ALLOWED_METHODS
HTTP_QUERY_PUBLIC_METHODS
HTTP_QUERY_DATE
HTTP_QUERY_EXPIRES
HTTP_QUERY_LAST_MODIFIED
HTTP_QUERY_MESSAGE_ID
HTTP_QUERY_URI
HTTP_QUERY_DERIVED_FROM
HTTP_QUERY_LANGUAGE
HTTP_QUERY_COST
HTTP_QUERY_WWW_LINK
HTTP_QUERY_PRAGMA
HTTP_QUERY_VERSION
HTTP_QUERY_STATUS_CODE
HTTP_QUERY_STATUS_TEXT
HTTP_QUERY_RAW_HEADERS
HTTP_QUERY_RAW_HEADERS_CRLF

CHttpFile：：QueryInfoStatusCode

呼叫這個成員函式以取得與 HTTP 要求相關聯的狀態代碼，並將它放在提供的 dwStatusCode 參數中。

BOOL QueryInfoStatusCode(DWORD& dwStatusCode) const;

參數

dwStatusCode
狀態代碼的參考。狀態代碼表示要求事件的成功或失敗。如需選取狀態代碼描述，請參閱<備註>。

傳回值

如果成功則為非零；否則為 0。如果呼叫失敗，可能會呼叫 Win32 函式 GetLastError 來判斷錯誤的原因。

備註

只有在成功呼叫 SendRequest 或 OpenURL 成功建立的物件之後CHttpFile，才使用此成員函式。

HTTP 狀態代碼屬於指出要求成功或失敗的群組。下表概述狀態代碼群組和最常見的 HTTP 狀態代碼。

群組	意義
200-299	成功
300-399	資訊
400-499	要求錯誤
500-599	伺服器錯誤

常見的 HTTP 狀態代碼：

狀態碼	意義
200	找到 URL，接著進行傳輸
400	難以理解的要求
404	找不到要求的 URL
405	伺服器不支援所要求的方法
500	未知的伺服器錯誤
503	伺服器容量已達

CHttpFile：：SendRequest

呼叫這個成員函式，將要求傳送至 HTTP 伺服器。

BOOL SendRequest(
    LPCTSTR pstrHeaders = NULL,
    DWORD dwHeadersLen = 0,
    LPVOID lpOptional = NULL,
    DWORD dwOptionalLen = 0);

BOOL SendRequest(
    CString& strHeaders,
    LPVOID lpOptional = NULL,
    DWORD dwOptionalLen = 0);

參數

pstrHeaders
字串的指標，其中包含要傳送的標頭名稱。

dwHeadersLen
pstrHeaders 所識別的標頭長度。

lpOptional
要求標頭之後要立即傳送的任何選擇性數據。這通常用於 POST 和 PUT 作業。如果沒有選擇性的數據要傳送，這可以是 NULL。

dwOptionalLen
lpOptional 的長度。

strHeaders
字串，包含所傳送要求之標頭的名稱。

傳回值

如果成功則為非零；否則為 0。如果呼叫失敗，請檢查擲回的 CInternetException 對象來判斷失敗的原因。

CHttpFile：：SendRequestEx

呼叫這個成員函式，將要求傳送至 HTTP 伺服器。

BOOL SendRequestEx(
    DWORD dwTotalLen,
    DWORD dwFlags = HSR_INITIATE,
    DWORD_PTR dwContext = 1);

BOOL SendRequestEx(
    LPINTERNET_BUFFERS lpBuffIn,
    LPINTERNET_BUFFERS lpBuffOut,
    DWORD dwFlags = HSR_INITIATE,
    DWORD_PTR dwContext = 1);

參數

dwTotalLen
要求中要傳送的位元組數目。

dwFlags
描述作業的旗標。如需適當旗標的清單，請參閱 Windows SDK 中的 HttpSendRequestEx 。

dwContext
作業的內容識別碼 CHttpFile 。如需此參數的詳細資訊，請參閱。

lpBuffIn
初始化 INTERNET_BUFFERS 指標，描述用於作業的輸入緩衝區。

lpBuffOut
初始化INTERNET_BUFFERS指標，描述用於作業的輸出緩衝區。

傳回值

如果成功，則為非零。如果呼叫失敗，請檢查擲回的 CInternetException 對象來判斷失敗的原因。

備註

此函式可讓您的應用程式使用的 Write 和 WriteString 方法來CInternetFile傳送數據。您必須知道要傳送的數據長度，才能呼叫此函式的任一覆寫。第一個覆寫可讓您指定您想要傳送的數據長度。第二個覆寫會接受INTERNET_BUFFERS結構的指標，可用來非常詳細地描述緩衝區。

將內容寫入檔案之後，請呼叫 EndRequest 以結束作業。

範例

此代碼段會將字串的內容傳送至 LOCALHOST 伺服器上名為 MFCISAPI.DLL的 DLL。雖然此範例只使用對的一個呼叫 WriteString，但使用多個呼叫在區塊中傳送數據是可接受的。

CString strData = _T("Some very long data to be POSTed here!");
pServer = session.GetHttpConnection(_T("localhost"));
pFile = pServer->OpenRequest(CHttpConnection::HTTP_VERB_POST,
                             _T("/MFCISAPI/MFCISAPI.dll?"));
pFile->SendRequestEx(strData.GetLength());

pFile->WriteString(strData);
pFile->EndRequest();

另請參閱

CInternetFile 類別
 階層架構圖表
 CInternetFile 類別
 CGopherFile 類別
 CHttpConnection 類別

共用方式為

CHttpFile 類別

語法

成員

受保護的建構函式

公用方法

備註

繼承階層架構

需求

CHttpFile：：AddRequestHeaders

參數

傳回值

備註

CHttpFile：：CHttpFile

參數

備註

CHttpFile：：EndRequest

參數

傳回值

備註

CHttpFile：：GetFileURL

傳回值

備註

CHttpFile：：GetObject

傳回值

備註

CHttpFile：：GetVerb

傳回值

備註

CHttpFile：：QueryInfo

參數

傳回值

備註

CHttpFile：：QueryInfoStatusCode

參數

傳回值

備註

CHttpFile：：SendRequest

參數

傳回值

CHttpFile：：SendRequestEx

參數

傳回值

備註

範例

另請參閱

意見反應

其他資源