共用方式為

CInternetFile 類別

  • 發行項

允許存取使用因特網通訊協定之遠程系統上的檔案。

語法

class CInternetFile : public CStdioFile

成員

受保護的建構函式

名稱 描述
CInternetFile：：CInternetFile 建構 CInternetFile 物件。

公用方法

名稱 描述
CInternetFile：：Abort 關閉檔案，忽略所有警告和錯誤。
CInternetFile：：Close 關閉 CInternetFile 並釋放其資源。
CInternetFile：：Flush 排清寫入緩衝區的內容，並確定記憶體中的數據已寫入目標計算機。
CInternetFile：：GetLength 傳回檔案的大小。
CInternetFile：：Read 讀取指定的位元組數目。
CInternetFile：：ReadString 讀取字元數據流。
CInternetFile：：Seek 將指標重新置放在開啟的檔案中。
CInternetFile：：SetReadBufferSize 設定要讀取數據的緩衝區大小。
CInternetFile：：SetWriteBufferSize 設定將寫入數據的緩衝區大小。
CInternetFile：：Write 寫入指定的位元組數目。
CInternetFile：：WriteString 將 Null 終止的字串寫入檔案。

公用運算子

名稱 描述
CInternetFile：：operator HINTERNET 因特網句柄的轉型運算符。

受保護的資料成員

名稱 描述
CInternetFile：：m_hFile 檔案的句柄。

備註

提供 CHttpFile 和 CGopherFile 檔案類別的基類。 您永遠不會直接建立 CInternetFile 物件。 相反地，呼叫 CGopherConnection：：OpenFile 或 CHttpConnection：：OpenRequest 來建立其中一個衍生類別的物件。 您也可以呼叫 CFtpConnection：：OpenFile 來建立CInternetFile物件。

成員 CInternetFile 函式 Open、 LockRange、 UnlockRange和 Duplicate 不會針對 實作 CInternetFile。 如果您在 物件上 CInternetFile 呼叫這些函式，您將會收到 CNotSupportedException。

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

繼承階層架構

CObject

CFile

CStdioFile

CInternetFile

需求

標頭： afxinet.h

CInternetFile：：Abort

關閉與此對象相關聯的檔案，並讓檔案無法讀取或寫入。

virtual void Abort();

備註

如果您尚未在終結物件之前關閉檔案，解構函式會為您關閉它。

處理例外狀況時， Abort 有兩個重要方式與 Close 不同。 首先，函 Abort 式不會在失敗時擲回例外狀況，因為它會忽略失敗。 其次， Abort 如果檔案尚未開啟或先前已關閉，則不會 ASSERT 。

CInternetFile：：CInternetFile

建立 CInternetFile 物件時，會呼叫這個成員函式。

CInternetFile(
    HINTERNET hFile,
    LPCTSTR pstrFileName,
    CInternetConnection* pConnection,
    BOOL bReadMode);

CInternetFile(
    HINTERNET hFile,
    HINTERNET hSession,
    LPCTSTR pstrFileName,
    LPCTSTR pstrServer,
    DWORD_PTR dwContext,
    BOOL bReadMode);

參數

hFile
因特網檔案的句柄。

pstrFileName
包含檔名之字串的指標。

pConnection
CInternetConnection 物件的指標。

bReadMode
指出檔案是否為唯讀。

hSession
因特網會話的句柄。

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

dwContext
對象的內容識別碼 CInternetFile 。 如需內容識別碼的詳細資訊，請參閱 WinInet 基本 概念。

備註

您永遠不會直接建立 CInternetFile 物件。 相反地，呼叫 CGopherConnection：：OpenFile 或 CHttpConnection：：OpenRequest 來建立其中一個衍生類別的物件。 您也可以呼叫 CFtpConnection：：OpenFile 來建立CInternetFile物件。

CInternetFile：：Close

關閉 CInternetFile 並釋放其任何資源。

virtual void Close();

備註

如果檔案已開啟以供寫入，則會隱含呼叫 Flush 以確保所有緩衝的數據都會寫入主機。 您應該在使用檔案完成時呼叫 Close 。

CInternetFile：：Flush

呼叫這個成員函式以清除寫入緩衝區的內容。

virtual void Flush();

備註

用來 Flush 確保記憶體中的所有數據都已實際寫入目標計算機，並確保已完成與主計算機的交易。 Flush 只有在開啟以供寫入的物件上 CInternetFile 才有效。

CInternetFile：：GetLength

傳回檔案的大小。

virtual ULONGLONG GetLength() const;

CInternetFile：：m_hFile

與這個 對象相關聯的檔案句柄。

HINTERNET m_hFile;

CInternetFile：：operator HINTERNET

使用此運算子取得目前網際網路工作階段的 Windows 控制代碼。

operator HINTERNET() const;

CInternetFile：：Read

呼叫此成員函式以讀取指定的記憶體，從 lpvBuf 開始，指定位元組數目 nCount。 

virtual UINT Read(
    void* lpBuf,
    UINT nCount);

參數

lpBuf
將檔案資料讀取到的記憶體位址指標。

nCount
要寫入的位元組數目。

傳回值

傳輸至緩衝區的位元組數目。 如果到達檔尾，傳回值可能小於 nCount 。

備註

函式會傳回實際讀取的位元元組數目， 如果檔案結束時，可能小於 nCount 的數位。 如果在讀取檔案時發生錯誤，函式會 擲回描述錯誤的 CInternetException 物件。 請注意，讀取超過檔案結尾不被視為錯誤，而且會擲回任何例外狀況。

為了確保擷取所有數據，應用程式必須繼續呼叫 CInternetFile::Read 方法，直到方法傳回零為止。

CInternetFile：：ReadString

呼叫此成員函式以讀取字元數據流，直到找到換行符為止。

virtual BOOL ReadString(CString& rString);

virtual LPTSTR ReadString(
    LPTSTR pstr,
    UINT nMax);

參數

pstr
字串的指標，將接收正在讀取的行。

nMax
要讀取的字元數上限。

rString
接收讀取行之 CString 對象的參考。

傳回值

緩衝區的指標，其中包含從 CInternetFile 物件擷取的純文字數據。 不論傳遞至此方法的緩衝區數據類型為何，它都不會對數據執行任何操作（例如，轉換成 Unicode），因此您必須將傳回的數據對應至所預期的結構，就像傳回類型一樣void*。

如果在未讀取任何數據的情況下到達檔尾，則為 NULL;或者，如果布爾值，則為 FALSE，如果到達檔尾而不讀取任何數據。

備註

函式會將產生的行放入 pstr 參數所參考的記憶體中。 它會在到達 nMax 所指定的最大字元數時停止讀取字元。 緩衝區一律會收到終止的 Null 字元。

如果您在未先呼叫 SetReadBufferSize 的情況下呼叫 ReadString ，則會收到 4096 個字節的緩衝區。

CInternetFile：：Seek

呼叫這個成員函式，以將指標重新置放在先前開啟的檔案中。

virtual ULONGLONG Seek(
    LONGLONG lOffset,
    UINT nFrom);

參數

lOffset
以位元組為單位的位移，以移動檔案中的讀取/寫入指標。

nFrom
位移的相對參考。 必須是下列其中一個值：

  • CFile::begin 將檔案指標 lOff 位元組從檔案開頭往前移動。

  • CFile::current 將檔案指標 lOff 位元組從檔案的目前位置移動。

  • CFile::end 將檔案指標 lOff 位元組從檔案結尾移動。 lOff 必須是負數，才能搜尋現有的檔案;正值會搜尋超過檔案結尾。

傳回值

如果要求的位置合法，則為檔案開頭的新位元組位移;否則，此值為未定義，而且 會擲回 CInternetException 物件。

備註

函 Seek 式允許以絕對或相對的方式移動指標，以隨機存取檔案的內容。 搜尋期間實際上不會讀取任何數據。

此時，只有與 CHttpFile 對象相關聯的數據才支援對這個成員函式的呼叫。 FTP 或 gopher 要求不支援此要求。 如果您呼叫 Seek 其中一個不支援的服務，則會將您傳回 Win32 錯誤碼ERROR_INTERNET_INVALID_OPERATION。

開啟檔案時，檔案指標位於位移0，也就是檔案的開頭。

注意

使用 Seek 可能會導致 Flush 的隱含呼叫。

範例

請參閱基類實作的範例 （ CFile：：Seek）。

CInternetFile：：SetReadBufferSize

呼叫這個成員函式，以設定衍生物件所使用的 CInternetFile暫存讀取緩衝區大小。

BOOL SetReadBufferSize(UINT nReadSize);

參數

nReadSize
需要的緩衝區大小 (以位元組為單位)。

傳回值

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

備註

基礎 WinInet API 不會執行緩衝處理，因此請選擇緩衝區大小，讓您的應用程式能夠有效率地讀取數據，而不論要讀取的數據量為何。 如果每次呼叫 Read 通常牽涉到大量的數據（例如，四個以上的 KB），就不需要緩衝區。 不過，如果您呼叫 Read 來取得少量的數據區塊，或者如果您使用 ReadString 一次讀取個別行，則讀取緩衝區可改善應用程式效能。

根據預設， CInternetFile 物件不會提供任何緩衝來讀取。 如果您呼叫這個成員函式，您必須確定檔案已開啟以供讀取存取。

您可以隨時增加緩衝區大小，但壓縮緩衝區不會有任何作用。 如果您呼叫 ReadString 而不先呼叫 SetReadBufferSize，則會收到 4096 個字節的緩衝區。

CInternetFile：：SetWriteBufferSize

呼叫這個成員函式，以設定衍生物件所使用的 CInternetFile暫存寫入緩衝區大小。

BOOL SetWriteBufferSize(UINT nWriteSize);

參數

nWriteSize
以位元組為單位的緩衝區大小。

傳回值

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

備註

基礎 WinInet API 不會執行緩衝處理，因此請選擇緩衝區大小，讓您的應用程式能夠有效率地寫入數據，而不論要寫入的數據量為何。 如果每次呼叫 Write 通常都牽涉到大量數據（例如，一次有四個以上的 KB），就不需要緩衝區。 不過，如果您呼叫 Write 來寫入小型數據區塊，寫入緩衝區可改善應用程式的效能。

根據預設， CInternetFile 物件不會提供任何緩衝來寫入。 如果您呼叫這個成員函式，您必須確定檔案已開啟以供寫入存取。 您可以隨時變更寫入緩衝區的大小，但這樣做會導致 Flush 的隱含呼叫。

CInternetFile：：Write

呼叫此成員函式以寫入指定的記憶體 lpvBuf、指定的位元元數目 nCount。 

virtual void Write(
    const void* lpBuf,
    UINT nCount);

參數

lpBuf
要寫入之第一個字節的指標。

nCount
指定要寫入的位元組數目。

備註

如果寫入數據時發生任何錯誤，函式會 擲回描述錯誤的 CInternetException 物件。

CInternetFile：：WriteString

此函式會將以 Null 終止的字串寫入相關聯的檔案。

virtual void WriteString(LPCTSTR pstr);

參數

pstr
字串的指標，其中包含要寫入的內容。

備註

如果寫入數據時發生任何錯誤，函式會 擲回描述錯誤的 CInternetException 物件。

另請參閱

CStdioFile 類別
階層架構圖表
CInternetConnection 類別