CAtlFile 類別

這個類別提供 Windows 檔案處理 API 的精簡包裝函式。

重要

這個類別及其成員不能用於在 Windows 執行階段 中執行的應用程式。

語法

class CAtlFile : public CHandle

成員

公用建構函式

名稱	描述
CAtlFile：：CAtlFile	建構函式。

公用方法

名稱	描述
CAtlFile：：Create	呼叫此方法以建立或開啟檔案。
CAtlFile：：Flush	呼叫此方法以清除檔案的緩衝區，並導致所有緩衝的數據寫入檔案。
CAtlFile：：GetOverlappedResult	呼叫這個方法，以取得檔案上重迭作業的結果。
CAtlFile：：GetPosition	呼叫這個方法，從檔案取得目前的檔案指標位置。
CAtlFile：：GetSize	呼叫這個方法以取得檔案位元組的大小。
CAtlFile：：LockRange	呼叫此方法以鎖定檔案中的區域，以防止其他進程存取它。
CAtlFile：：Read	呼叫這個方法，從檔案指標所指示的位置開始，從檔案讀取數據。
CAtlFile：：Seek	呼叫此方法以移動檔案的檔案指標。
CAtlFile：：SetSize	呼叫這個方法來設定檔案的大小。
CAtlFile：：UnlockRange	呼叫此方法以解除鎖定檔案的區域。
CAtlFile：：Write	呼叫這個方法，將數據寫入檔案，從檔案指標所指示的位置開始。

受保護的資料成員

名稱	描述
CAtlFile：：m_pTM	CAtlTransactionManager物件的指標

備註

當檔案處理需求相對簡單時，請使用這個類別，但比 Windows API 提供更多的抽象概念，而不需要包含 MFC 相依性。

繼承階層架構

CHandle

CAtlFile

需求

標頭： atlfile.h

CAtlFile：：CAtlFile

建構函式。

CAtlFile() throw();
CAtlFile(CAtlTransactionManager* pTM = NULL) throw();
CAtlFile(CAtlFile& file) throw();
explicit CAtlFile(HANDLE hFile) throw();

參數

file
檔案物件。

hFile
檔句柄。

pTM
CAtlTransactionManager 物件的指標

備註

複製建構函式會將檔句柄的擁有權從原始 CAtlFile 物件傳輸到新建構的物件。

CAtlFile：：Create

呼叫此方法以建立或開啟檔案。

HRESULT Create(
    LPCTSTR szFilename,
    DWORD dwDesiredAccess,
    DWORD dwShareMode,
    DWORD dwCreationDisposition,
    DWORD dwFlagsAndAttributes = FILE_ATTRIBUTE_NORMAL,
    LPSECURITY_ATTRIBUTES lpsa = NULL,
    HANDLE hTemplateFile = NULL) throw();

參數

szFilename
檔案名稱。

dwDesiredAccess
所需的存取權。 請參閱 Windows SDK 中 CreateFile 中的 dwDesiredAccess。

dwShareMode
共用模式。 請參閱 中的 CreateFiledwShareMode。

dwCreationDisposition
建立處置。 請參閱 中的 CreateFiledwCreationDisposition。

dwFlagsAndAttributes
旗標和屬性。 請參閱 中的 CreateFiledwFlagsAndAttributes。

lpsa
安全性屬性。 請參閱 中的 CreateFilelpSecurityAttributes。

hTemplateFile
範本檔案。 請參閱 中的 CreateFilehTemplateFile。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

呼叫 CreateFile 來建立或開啟檔案。

CAtlFile：：Flush

呼叫此方法以清除檔案的緩衝區，並導致所有緩衝的數據寫入檔案。

HRESULT Flush() throw();

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

呼叫 FlushFileBuffers ，將緩衝處理的數據排清至檔案。

CAtlFile：：GetOverlappedResult

呼叫這個方法，以取得檔案上重迭作業的結果。

HRESULT GetOverlappedResult(
    LPOVERLAPPED pOverlapped,
    DWORD& dwBytesTransferred,
    BOOL bWait) throw();

參數

pOverlapped
重疊的結構。 請參閱 Windows SDK 中的 GetOverlappedResult 中的 lpOverlapped。

dwBytesTransferred
傳輸的位元組。 請參閱 中的 GetOverlappedResultlpNumberOfBytesTransferred。

bWait
等候選項。 請參閱 中的 GetOverlappedResultbWait。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

呼叫 GetOverlappedResult 以取得檔案上重迭作業的結果。

CAtlFile：：GetPosition

呼叫此方法以取得目前的檔案指標位置。

HRESULT GetPosition(ULONGLONG& nPos) const throw();

參數

nPos
以位元組為單位的位置。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

呼叫 SetFilePointer 以取得目前的檔案指標位置。

CAtlFile：：GetSize

呼叫這個方法以取得檔案位元組的大小。

HRESULT GetSize(ULONGLONG& nLen) const throw();

參數

nLen
檔案中的位元組數目。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

呼叫 GetFileSize 以取得檔案位元組的大小。

CAtlFile：：LockRange

呼叫此方法以鎖定檔案中的區域，以防止其他進程存取它。

HRESULT LockRange(ULONGLONG nPos, ULONGLONG nCount) throw();

參數

nPos
檔案中應該開始鎖定的位置。

nCount
要鎖定的位元組範圍長度。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

呼叫 LockFile 來鎖定檔案中的區域。 鎖定檔案中的位元組可防止其他處理序存取這些位元組。 您可以鎖定檔案的多個區域，但不允許重疊的區域。 當您使用 CAtlFile：：UnlockRange 解除鎖定區域時，位元組範圍必須完全符合先前鎖定的區域。 LockRange 不會合併相鄰區域;如果兩個鎖定的區域相鄰，您必須個別解除鎖定。

CAtlFile：：m_pTM

指向 CAtlTransactionManager 物件的指標。

CAtlTransactionManager* m_pTM;

備註

CAtlFile：：Read

呼叫這個方法，從檔案指標所指示的位置開始，從檔案讀取數據。

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize) throw();

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize,
    DWORD& nBytesRead) throw();

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped) throw();

HRESULT Read(
    LPVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped,
    LPOVERLAPPED_COMPLETION_ROUTINE pfnCompletionRoutine) throw();

參數

pBuffer
將接收從檔案讀取之數據的緩衝區指標。

nBufSize
緩衝區大小，以位元組為單位。

nBytesRead
讀取的位元組數。

pOverlapped
重疊的結構。 請參閱 Windows SDK 的 ReadFile 中的 lpOverlapped。

pfnCompletionRoutine
完成例程。 請參閱 Windows SDK 中 ReadFileEx 中的 lpCompletionRoutine。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

前三個窗體會呼叫 ReadFile，這是從檔案讀取數據的最後 一個 ReadFileEx 。 使用 CAtlFile：：Seek 移動檔案指標。

CAtlFile：：Seek

呼叫此方法以移動檔案的檔案指標。

HRESULT Seek(
    LONGLONG nOffset,
    DWORD dwFrom = FILE_CURRENT) throw();

參數

nOffset
dwFrom 所指定起點的 位移。

dwFrom
起點（FILE_BEGIN、FILE_CURRENT或FILE_END）。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

呼叫 SetFilePointer 來移動檔案指標。

CAtlFile：：SetSize

呼叫這個方法來設定檔案的大小。

HRESULT SetSize(ULONGLONG nNewLen) throw();

參數

nNewLen
檔案的新長度，以位元組為單位。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

呼叫 SetFilePointer 和 SetEndOfFile 來設定檔案的大小。 傳回時，檔案指標會位於檔案的結尾。

CAtlFile：：UnlockRange

呼叫此方法以解除鎖定檔案的區域。

HRESULT UnlockRange(ULONGLONG nPos, ULONGLONG nCount) throw();

參數

nPos
檔案中應該開始解除鎖定的位置。

nCount
要解除鎖定的位元組範圍長度。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

呼叫 UnlockFile 以解除鎖定檔案的區域。

CAtlFile：：Write

呼叫這個方法，將數據寫入檔案，從檔案指標所指示的位置開始。

HRESULT Write(
    LPCVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped,
    LPOVERLAPPED_COMPLETION_ROUTINE pfnCompletionRoutine) throw();

HRESULT Write(
    LPCVOID pBuffer,
    DWORD nBufSize,
    DWORD* pnBytesWritten = NULL) throw();

HRESULT Write(
    LPCVOID pBuffer,
    DWORD nBufSize,
    LPOVERLAPPED pOverlapped) throw();

參數

pBuffer
包含要寫入檔案之數據的緩衝區。

nBufSize
要從緩衝區傳輸的位元組數目。

pOverlapped
重疊的結構。 請參閱 Windows SDK 中的 WriteFile 中的 lpOverlapped。

pfnCompletionRoutine
完成例程。 請參閱 Windows SDK 中的 WriteFileEx 中的 lpCompletionRoutine。

pnBytesWritten
寫入的位元組。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

前三個窗體會呼叫 WriteFile，最後一個會呼叫 WriteFileEx 將數據寫入檔案。 使用 CAtlFile：：Seek 移動檔案指標。

另請參閱

選框範例
類別概觀
CHandle 類別