共用方式為

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
共用模式。 請參閱 中的 CreateFile dwShareMode 。

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

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

lpsa
安全性屬性。 請參閱 中的 CreateFile lpSecurityAttributes 。

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

傳回值

傳回成功時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
傳輸的位元組。 請參閱 中的 GetOverlappedResult lpNumberOfBytesTransferred 。

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

傳回值

傳回成功時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 類別