CFile クラスCFile Class

• 06/12/2018
• • T
  • o
  • O
  • S
  • v

ファイルに関する MFC の基底クラスです。The base class for Microsoft Foundation Class file classes.

構文Syntax

class CFile : public CObject

メンバーMembers

パブリック コンストラクターPublic Constructors

パブリック メソッドPublic Methods

パブリック演算子Public Operators

パブリック データ メンバーPublic Data Members

プロテクト データ メンバーProtected Data Members

解説Remarks

このクラスは、バッファリングされていないバイナリディスク入出力サービスを直接提供し、派生クラスを通じてテキストファイルとメモリファイルを間接的にサポートします。It directly provides unbuffered, binary disk input/output services, and it indirectly supports text files and memory files through its derived classes. CFile は、クラスと連携して、 CArchive Microsoft Foundation class オブジェクトのシリアル化をサポートします。CFile works in conjunction with the CArchive class to support serialization of Microsoft Foundation Class objects.

このクラスとその派生クラスの間の階層リレーションシップにより、プログラムはポリモーフィックインターフェイスを介してすべてのファイルオブジェクトを操作でき CFile ます。The hierarchical relationship between this class and its derived classes allows your program to operate on all file objects through the polymorphic CFile interface. たとえば、メモリファイルはディスクファイルのように動作します。A memory file, for example, behaves like a disk file.

CFile汎用ディスク i/o には、とその派生クラスを使用します。Use CFile and its derived classes for general-purpose disk I/O. ofstreamまたはその他の Microsoft クラスを使用し iostream て、フォーマットされたテキストをディスクファイルに送信します。Use ofstream or other Microsoft iostream classes for formatted text sent to a disk file.

通常、ディスクファイルは構築時に自動的に開かれ、 CFile 破棄時に閉じられます。Normally, a disk file is opened automatically on CFile construction and closed on destruction. 静的メンバー関数を使用すると、ファイルを開かずにファイルの状態を問い合わせることができます。Static member functions permit you to interrogate a file's status without opening the file.

の使用方法の詳細については CFile 、「 MFC の記事ファイル」と「ランタイムライブラリリファレンス」の「ファイル処理」を参照してください。For more information on using CFile, see the articles Files in MFC and File Handling in the Run-Time Library Reference.

継承階層Inheritance Hierarchy

CObjectCObject

CFile

要件Requirements

ヘッダー: afxHeader: afx.h

CFile:: AbortCFile::Abort

このオブジェクトに関連付けられているファイルを閉じて、読み取りまたは書き込みのためにファイルを使用できないようにします。Closes the file associated with this object and makes the file unavailable for reading or writing.

virtual void Abort();

解説Remarks

オブジェクトを破棄する前にファイルを閉じていない場合は、デストラクターによってファイルが閉じられます。If you haven't closed the file before destroying the object, the destructor closes it for you.

例外を処理する場合、は、 CFile::Abort CFile::Close 2 つの重要な点でとは異なります。When handling exceptions, CFile::Abort differs from CFile::Close in two important ways. まず、 Abort ではエラーが無視されるため、関数はエラー発生時に例外をスローしません Abort 。First, the Abort function won't throw an exception on failures, because failures are ignored by Abort. 2番目は、 Abort ファイルが開かれていない場合、または以前に閉じられた場合には アサート しません。Second, Abort won't ASSERT if the file hasn't been opened, or was closed previously.

new ヒープにオブジェクトを割り当てる場合は CFile 、ファイルを閉じた後でオブジェクトを削除する必要があります。If you used new to allocate the CFile object on the heap, then you must delete it after closing the file. Abort``m_hFileをに設定 CFile::hFileNull します。Abort sets m_hFile to CFile::hFileNull.

例Example

CStdioFile fileTest;
TCHAR* pszFileName = _T("Abort_File.dat");

// do stuff that may cause exceptions
CFileException ex;
if (!fileTest.Open(pszFileName, CFile::modeWrite, &ex))
{
   ex.ReportError();
   fileTest.Abort();   // close file safely and quietly
}

CFile:: CFileCFile::CFile

CFile オブジェクトを構築して初期化します。Constructs and initializes a CFile object.

CFile();
CFile(CAtlTransactionManager* pTM);
CFile(HANDLE hFile);

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags);

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags,
CAtlTransactionManager* pTM);

パラメーターParameters

hFilehFile
CFile オブジェクトにアタッチするためのファイル ハンドル。Handle of a file to attach to the CFile object.

lpszFileNamelpszFileName
CFile オブジェクトにアタッチするための相対パスまたは完全パス。Relative or full path of a file to attach to the CFile object.

NoペンフラグnOpenFlags
指定されたファイルのファイル アクセス オプションのビットごとの組み合わせ (OR)。Bitwise combination (OR) of file access options for the specified file. 使用できるオプションについては、「解説」を参照してください。See the Remarks section for possible options.

pTMpTM
CAtlTransactionManager オブジェクトへのポインター。Pointer to CAtlTransactionManager object

解説Remarks

次の5つの表は、 Noの flags パラメーターで使用可能なオプションを示しています。The following five tables list the possible options for the nOpenFlags parameter.

次のファイル アクセス モード オプションから 1 つのみ選択します。Choose only one of the following file access mode options. 既定のファイル アクセス モードは CFile::modeRead であり、これは読み取り専用です。The default file access mode is CFile::modeRead, which is read only.

次の文字モード オプションのいずれかを選択します。Choose one of the following character mode options.

次のファイル共有モード オプションから 1 つのみ選択します。Choose only one of the following file share mode options. 既定のファイル共有モードは CFile::shareExclusive であり、これは排他的です。The default file share mode is CFile::shareExclusive, which is exclusive.

次のファイル作成モード オプションから最初のオプションまたは両方を選択します。Choose the first, or both, of the following file creation mode options. 既定の作成モードは CFile::modeNoTruncate であり、これは既存を開くです。The default creation mode is CFile::modeNoTruncate, which is open existing.

説明に従って次のファイル キャッシュ オプションを選択します。Choose the following file caching options as described. 既定では、オプションとして使用できない汎用のキャッシュスキームがシステムによって使用されます。By default, the system uses a general-purpose caching scheme that isn't available as an option.

ファイル ハンドルが継承されないようにするために、次のセキュリティ オプションを選択します。Choose the following security option to prevent the file handle from being inherited. 既定では、新しい子プロセスはファイル ハンドルを使用できます。By default, any new child processes can use the file handle.

既定のコンストラクターはメンバーを初期化しますが、オブジェクトにはファイルをアタッチしません CFile 。The default constructor initializes members but doesn't attach a file to the CFile object. このコンストラクターを使用した後、 CFile:: open メソッドを使用してファイルを開き、オブジェクトにアタッチし CFile ます。After using this constructor, use the CFile::Open method to open a file and attach it to the CFile object.

1 つのパラメーターを持つコンストラクターでは、メンバーは初期化され、既存のファイルが CFile オブジェクトにアタッチされます。The constructor with one parameter initializes members and attaches an existing file to the CFile object.

2 つのパラメーターを持つコンストラクターでは、メンバーは初期化され、指定されたファイルを開くことが試行されます。The constructor with two parameters initializes members and tries to open the specified file. このコンストラクターによって、指定されたファイルが正常に開かれると、ファイルは CFile オブジェクトにアタッチされます。それ以外の場合は、このコンストラクターによって CInvalidArgException オブジェクトへのポインターがスローされます。If this constructor successfully opens the specified file, the file is attached to the CFile object; otherwise, this constructor throws a pointer to a CInvalidArgException object. 例外の処理方法の詳細については、「 例外」を参照してください。For more information about how to handle exceptions, see Exceptions.

CFile指定されたファイルが正常に開かれた場合、オブジェクトが破棄されると、このファイルは自動的に閉じられます CFile 。それ以外の場合は、オブジェクトにアタッチされなくなった後に、ファイルを明示的に閉じる必要があり CFile ます。If a CFile object successfully opens a specified file, it will close this file automatically when the CFile object is destroyed; otherwise, you must explicitly close the file after it's no longer attached to the CFile object.

例Example

CFile の使用例を次のコードに示します。The following code shows how to use a CFile.

HANDLE hFile = CreateFile(_T("CFile_File.dat"),
   GENERIC_WRITE, FILE_SHARE_READ,
   NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);

if (hFile == INVALID_HANDLE_VALUE)
{
   AfxMessageBox(_T("Couldn't create the file!"));
}
else
{
   // Attach a CFile object to the handle we have.
   CFile myFile(hFile);

   static const TCHAR sz[] = _T("I love CFile!");

   // write string
   myFile.Write(sz, sizeof(sz));

   // We need to call Close() explicitly. Note that there's no need to 
   // call CloseHandle() on the handle returned by the API because 
   // Close() automatically calls CloseHandle() for us.
   myFile.Close();

CFile:: CloseCFile::Close

このオブジェクトに関連付けられているファイルを閉じて、読み取りまたは書き込みのためにファイルを使用できないようにします。Closes the file associated with this object and makes the file unavailable for reading or writing.

virtual void Close();

解説Remarks

オブジェクトを破棄する前にファイルを閉じていない場合は、デストラクターによってファイルが閉じられます。If you haven't closed the file before destroying the object, the destructor closes it for you.

new ヒープにオブジェクトを割り当てる場合は CFile 、ファイルを閉じた後でオブジェクトを削除する必要があります。If you used new to allocate the CFile object on the heap, then you must delete it after closing the file. Close``m_hFileをに設定 CFile::hFileNull します。Close sets m_hFile to CFile::hFileNull.

例Example

Cfile:: cfileの例を参照してください。See the example for CFile::CFile.

CFile::D uCFile::Duplicate

CFile指定されたファイルの重複するオブジェクトを構築します。Constructs a duplicate CFile object for a given file.

virtual CFile* Duplicate() const;

戻り値Return Value

重複するオブジェクトへのポインター CFile 。A pointer to a duplicate CFile object.

解説Remarks

この関数は、C ランタイム関数に相当 _dup します。This function is equivalent to the C run-time function _dup.

CFile:: FlushCFile::Flush

ファイルバッファー内の残りのデータを強制的にファイルに書き込みます。Forces any data remaining in the file buffer to be written to the file.

virtual void Flush();

解説Remarks

を使用すると、 Flush バッファーのフラッシュは保証されません CArchive 。The use of Flush doesn't guarantee flushing of CArchive buffers. アーカイブを使用している場合は、最初に CArchive:: Flush を呼び出します。If you're using an archive, call CArchive::Flush first.

例Example

CFile:: SetFilePathの例を参照してください。See the example for CFile::SetFilePath.

CFile:: GetFileNameCFile::GetFileName

このメンバー関数を呼び出して、指定したファイルの名前を取得します。Call this member function to retrieve the name of a specified file.

virtual CString GetFileName() const;

戻り値Return Value

ファイルの名前です。The name of the file.

解説Remarks

たとえば、 GetFileName を呼び出してファイルに関するメッセージをユーザーに生成すると、 c:\windows\write\myfile.wri ファイル名が返され myfile.wri ます。For example, when you call GetFileName to generate a message to the user about the file c:\windows\write\myfile.wri, the filename, myfile.wri, is returned.

名前を含むファイルのパス全体を取得するには、 Getfilepathを呼び出します。To return the entire path of the file, including the name, call GetFilePath. ファイルのタイトル () を返すには myfile 、 GetFileTitleを呼び出します。To return the title of the file ( myfile), call GetFileTitle.

例Example

このコード片では、WINDOWS ディレクトリ内の SYSTEM.INI ファイルを開きます。This code fragment opens the SYSTEM.INI file in your WINDOWS directory. 見つかった場合、この例では、[出力] に示されているように、名前とパス、およびタイトルが出力されます。If found, the example will print out the name and path and title, as shown under Output:

try
{
   // try to open the file
   CFile sysFile(_T("C:\\WINDOWS\\SYSTEM.INI"), CFile::modeRead);

   // print out path name and title information
   _tprintf_s(_T("Path is : \"%s\"\n"),
      (LPCTSTR) sysFile.GetFilePath());
   _tprintf_s(_T("Name is : \"%s\"\n"),
      (LPCTSTR) sysFile.GetFileName());
   _tprintf_s(_T("Title is: \"%s\"\n"), 
      (LPCTSTR) sysFile.GetFileTitle());

   // close the file handle
   sysFile.Close();
}
catch (CFileException* pEx)
{
   // if an error occurs, just make a message box
   pEx->ReportError();
   pEx->Delete();
}

CFile:: GetFilePathCFile::GetFilePath

このメンバー関数を呼び出して、指定したファイルの完全パスを取得します。Call this member function to retrieve the full path of a specified file.

virtual CString GetFilePath() const;

戻り値Return Value

指定されたファイルの完全パス。The full path of the specified file.

解説Remarks

たとえば、を呼び出して、 GetFilePath ファイルに関するメッセージをユーザーに生成すると、 c:\windows\write\myfile.wri ファイルパス c:\windows\write\myfile.wri が返されます。For example, when you call GetFilePath to generate a message to the user about the file c:\windows\write\myfile.wri, the file path, c:\windows\write\myfile.wri, is returned.

ファイル () の名前だけを取得するには myfile.wri 、 getfilenameを呼び出します。To return just the name of the file (myfile.wri), call GetFileName. ファイルのタイトル () を返すには myfile 、 GetFileTitleを呼び出します。To return the title of the file (myfile), call GetFileTitle.

例Example

Getfilenameの例を参照してください。See the example for GetFileName.

CFile:: GetFileTitleCFile::GetFileTitle

ファイルのファイルタイトル (表示名) を取得するには、このメンバー関数を呼び出します。Call this member function to retrieve the file title (the display name) for the file.

virtual CString GetFileTitle() const;

戻り値Return Value

基になるファイルのタイトル。The title of the underlying file.

解説Remarks

このメソッドは、 GetFileTitle を呼び出して、ファイルのタイトルを取得します。This method calls GetFileTitle to retrieve the title of the file. 成功した場合、メソッドは、ユーザーにファイル名を表示するためにシステムが使用する文字列を返します。If successful, the method returns the string that the system would use to display the file name to the user. それ以外の場合、メソッドは Pathfindfilename を呼び出して、基になるファイルのファイル名 (ファイル拡張子を含む) を取得します。Otherwise, the method calls PathFindFileName to retrieve the file name (including the file extension) of the underlying file. つまり、返されたファイルのタイトル文字列にファイル拡張子が必ず含まれているわけではありません。That means the file extension isn't always included in the returned file title string. 詳細については、Windows SDK の「 GetFileTitle と pathfindfilename 」を参照してください。For more information, see GetFileTitle and PathFindFileName in the Windows SDK.

名前を含むファイルのパス全体を取得するには、 Getfilepathを呼び出します。To return the entire path of the file, including the name, call GetFilePath. ファイル名のみを返すには、 Getfilenameを呼び出します。To return just the name of the file, call GetFileName.

例Example

Getfilenameの例を参照してください。See the example for GetFileName.

CFile:: GetLengthCFile::GetLength

ファイルの現在の論理長をバイト単位で取得します。Obtains the current logical length of the file in bytes.

virtual ULONGLONG GetLength() const;

戻り値Return Value

ファイルの長さ。The length of the file.

例Example

CFile* pFile = NULL;
// Constructing a CFile object with this override may throw
// a CFile exception, and won't throw any other exceptions.
// Calling CString::Format() may throw a CMemoryException,
// so we have a catch block for such exceptions, too. Any
// other exception types this function throws will be
// routed to the calling function.
try
{
   pFile = new CFile(_T("C:\\WINDOWS\\SYSTEM.INI"),
      CFile::modeRead | CFile::shareDenyNone);
   ULONGLONG dwLength = pFile->GetLength();
   CString str;
   str.Format(_T("Your SYSTEM.INI file is %I64u bytes long."), dwLength);
   AfxMessageBox(str);
}
catch (CFileException* pEx)
{
   // Simply show an error message to the user.
   pEx->ReportError();
   pEx->Delete();
}
catch(CMemoryException* pEx)
{
   pEx->ReportError();
   pEx->Delete();
   // We can't recover from this memory exception, so we'll
   // just terminate the app without any cleanup. Normally,
   // an application should do everything it possibly can to
   // clean up properly and _not_ call AfxAbort().
   AfxAbort();
}

// If an exception occurs in the CFile constructor,
// the language will free the memory allocated by new
// and will not complete the assignment to pFile.
// Thus, our clean-up code needs to test for NULL.
if (pFile != NULL)
{
   pFile->Close();
   delete pFile;
}         

CFile:: GetPositionCFile::GetPosition

ファイルポインターの現在の値を取得します。これは、後でを呼び出すときに使用でき Seek ます。Obtains the current value of the file pointer, which can be used in later calls to Seek.

virtual ULONGLONG GetPosition() const;

戻り値Return Value

ファイルポインター。The file pointer.

例Example

CFile cfile;
cfile.Open(_T("Seek_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
LONGLONG lOffset = 1000;
ULONGLONG lActual;
lActual = cfile.Seek(lOffset, CFile::begin);
ASSERT(cfile.GetPosition() == lActual);

CFile:: GetStatusCFile::GetStatus

このメソッドは、指定された CFile オブジェクトインスタンスまたは指定されたファイルパスに関連するステータス情報を取得します。This method retrieves status information related to a given CFile object instance or a given file path.

BOOL GetStatus(CFileStatus& rStatus) const;

static BOOL PASCAL GetStatus(
    LPCTSTR lpszFileName,
    CFileStatus& rStatus,
    CAtlTransactionManager* pTM = NULL);

パラメーターParameters

rStatusrStatus
ステータス情報を受け取るユーザー指定の CFileStatus 構造体への参照。A reference to a user-supplied CFileStatus structure that will receive the status information. CFileStatus構造体には、次のフィールドがあります。The CFileStatus structure has the following fields:

• CTime m_ctime ファイルが作成された日付と時刻。CTime m_ctime The date and time the file was created.

• CTime m_mtime ファイルが最後に変更された日付と時刻。CTime m_mtime The date and time the file was last modified.

• CTime m_atime ファイルが読み取り用に最後にアクセスされた日付と時刻。CTime m_atime The date and time the file was last accessed for reading.

• ULONGLONG m_size DIR コマンドによって報告されたファイルの論理サイズ (バイト単位)。ULONGLONG m_size The logical size of the file in bytes, as reported by the DIR command.

• BYTE m_attribute ファイルの属性バイト。BYTE m_attribute The attribute byte of the file.

• char m_szFullName[_MAX_PATH] Windows 文字セットの絶対ファイル名。char m_szFullName[_MAX_PATH] The absolute filename in the Windows character set.

lpszFileNamelpszFileName
Windows 文字セット内の、目的のファイルへのパスを表す文字列。A string in the Windows character set that is the path to the desired file. 相対パスまたは絶対パスを指定することも、ネットワークパス名を含めることもできます。The path can be relative or absolute, or it can contain a network path name.

pTMpTM
CAtlTransactionManager オブジェクトへのポインター。Pointer to CAtlTransactionManager object

戻り値Return Value

指定したファイルのステータス情報が正常に取得された場合は TRUE。それ以外の場合は FALSE。TRUE if the status information for the specified file is successfully obtained; otherwise, FALSE.

解説Remarks

非静的バージョンのは、 GetStatus 指定されたオブジェクトに関連付けられている開いているファイルのステータス情報を取得し CFile ます。The non-static version of GetStatus retrieves status information of the open file associated with the given CFile object. の静的バージョンでは、ファイルを GetStatus 実際に開くことなく、指定されたファイルパスからファイルの状態を取得します。The static version of GetStatus obtains the file status from a given file path without actually opening the file. このバージョンは、ファイルの存在とアクセス権のテストに役立ちます。This version is useful for testing the existence and access rights of a file.

m_attribute構造体のメンバーは、 CFileStatus ファイル属性セットを参照します。The m_attribute member of the CFileStatus structure refers to the file attribute set. クラスは、 CFile ファイル属性をシンボルとして指定できるように、 属性 の列挙型を提供します。The CFile class provides the Attribute enumeration type so file attributes can be specified symbolically:

enum Attribute {
    normal =    0x00,
    readOnly =  0x01,
    hidden =    0x02,
    system =    0x04,
    volume =    0x08,
    directory = 0x10,
    archive =   0x20
    };

例Example

CFile cfile;
cfile.Open(_T("SetLength_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwNewLength = 10000;
cfile.SetLength(dwNewLength);
CFileStatus status;
if(cfile.GetStatus(status))    // virtual member function
{
   TRACE(_T("File size = %u\n"), status.m_size);
}
TCHAR* pszFileName = _T("SetLength_File.dat");
if(CFile::GetStatus(pszFileName, status))   // static function
{
   TRACE(_T("Full file name = %s\n"), status.m_szFullName);
}

CFile:: hFileNullCFile::hFileNull

オブジェクトの有効なファイルハンドルが存在するかどうかを判断し CFile ます。Determines the presence of a valid file handle for the CFile object.

static AFX_DATA const HANDLE hFileNull;

解説Remarks

この定数は、 CFile オブジェクトに有効なファイルハンドルがあるかどうかを判断するために使用されます。This constant is used to determine if the CFile object has a valid file handle.

この操作の例を次に示します。The following example demonstrates this operation:

if (myFile.m_hFile != CFile::hFileNull)
   ;//perform operations on the file
else
   ;//indicate the presence of an invalid handle         

CFile:: LockRangeCFile::LockRange

開いているファイルのバイト範囲をロックし、ファイルが既にロックされている場合は例外をスローします。Locks a range of bytes in an open file, throwing an exception if the file is already locked.

virtual void LockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

パラメーターParameters

dwPosdwPos
ロックするバイト範囲の先頭のバイトオフセット。The byte offset of the start of the byte range to lock.

dwCountdwCount
ロックする範囲内のバイト数。The number of bytes in the range to lock.

解説Remarks

ファイル内のバイトをロックすると、他のプロセスがそれらのバイトにアクセスできなくなります。Locking bytes in a file prevents access to those bytes by other processes. ファイルの複数の領域をロックすることはできますが、重複する領域は許可されません。You can lock more than one region of a file, but no overlapping regions are allowed.

メンバー関数を使用して領域のロックを解除する場合 UnlockRange 、バイト範囲は、以前にロックされていた領域と正確に対応している必要があります。When you unlock the region using the UnlockRange member function, the byte range must correspond exactly to the region that was previously locked. LockRange関数は隣接する領域を結合しません。The LockRange function doesn't merge adjacent regions. 2つのロックされた領域が隣接している場合は、各領域を個別にロック解除する必要があります。If two locked regions are adjacent, you must unlock each region separately.

例Example

CFile cfile;
cfile.Open(_T("LockRange_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwPos = 10;
ULONGLONG dwCount = 100;
cfile.LockRange(dwPos, dwCount);

// do something with the file

cfile.UnlockRange(dwPos, dwCount);

CFile:: m_hFileCFile::m_hFile

開いているファイルのオペレーティングシステムファイルハンドルを格納します。Contains the operating-system file handle for an open file.

HANDLE m_hFile;

解説Remarks

m_hFile UINT 型のパブリック変数です。m_hFile is a public variable of type UINT. これには CFile::hFileNull 、ハンドルが割り当てられていない場合に、オペレーティングシステムに依存しない空のファイルインジケーターが含まれます。It contains CFile::hFileNull, an operating-system-independent empty file indicator, if the handle hasn't been assigned.

m_hFileメンバーの意味は派生クラスに依存しているため、の使用は推奨されていません。Use of m_hFile isn't recommended, because the member's meaning depends on the derived class. m_hFile は、クラスの非ポリモーフィックな使用をサポートするために、パブリックメンバーになりました。m_hFile is made a public member for convenience in supporting nonpolymorphic use of the class.

CFile:: m_pTMCFile::m_pTM

オブジェクトへのポインター CAtlTransactionManager 。Pointer to a CAtlTransactionManager object.

CAtlTransactionManager* m_pTM;

解説Remarks

CFile:: OpenCFile::Open

オーバーロードされます。Overloaded. Open は、既定のコンストラクターで使用するように設計されてい CFile ます。Open is designed for use with the default CFile constructor.

virtual BOOL Open(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CFileException* pError = NULL);

virtual BOOL Open(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CAtlTransactionManager* pTM,
    CFileException* pError = NULL);

パラメーターParameters

lpszFileNamelpszFileName
目的のファイルへのパスを含む文字列。A string that contains the path to the desired file. パスには、相対パス、絶対パス、またはネットワーク名 (UNC) を指定できます。The path can be relative, absolute, or a network name (UNC).

NoペンフラグnOpenFlags
ファイルの共有モードとアクセスモードを定義する UINT。A UINT that defines the file's sharing and access mode. ファイルを開くときに実行するアクションを指定します。It specifies the action to take when opening the file. ビットごとの OR ( | ) 演算子を使用して、オプションを組み合わせることができます。You can combine options by using the bitwise-OR ( | ) operator. 1つのアクセス許可と1つの共有オプションが必要です。 modeCreate モードと modeNoInherit モードは省略可能です。One access permission and one share option are required; the modeCreate and modeNoInherit modes are optional. モードオプションの一覧については、「 CFile コンストラクター」を参照してください。See the CFile constructor for a list of mode options.

pErrorpError
失敗した操作の状態を受け取る既存のファイル例外オブジェクトへのポインター。A pointer to an existing file-exception object that will receive the status of a failed operation.

pTMpTM
CAtlTransactionManager オブジェクトへのポインター。Pointer to CAtlTransactionManager object

戻り値Return Value

開いたが成功した場合は0以外の。それ以外の場合は0です。Nonzero if the open was successful; otherwise 0. この パラメーターは 、0が返された場合にのみ意味があります。The pError parameter is meaningful only if 0 is returned.

解説Remarks

2つの Open 関数は、ファイルを開くための "安全な" メソッドであり、エラーが通常の予期される条件になります。The two Open functions are "safe" methods for opening a file, where a failure is a normal, expected condition.

コンストラクターは CFile エラー条件で例外をスローしますが、 Open エラー状態の場合は FALSE を返します。While the CFile constructor throws an exception in an error condition, Open returns FALSE for error conditions. Open でも、エラーを説明するために CFileException オブジェクトを初期化することはできます。Open can still initialize a CFileException object to describe the error, however. パラメーターを指定しない 場合、またはの 場合に NULL を渡すと、は Open FALSE を返し、をスローしません CFileException 。If you don't supply the pError parameter, or if you pass NULL for pError, Open returns FALSE and doesn't throw a CFileException. 既存のにポインターを渡し、エラーが発生した場合 CFileException Open 、関数はそのエラーを説明する情報を入力します。If you pass a pointer to an existing CFileException, and Open encounters an error, the function fills it with information describing that error. Open どちらの場合も、例外はスローされません。Open doesn't throw an exception in either case.

次の表では、の考えられる結果について説明し Open ます。The following table describes the possible results of Open.

例Example

CFile f;
CFileException e;
TCHAR* pszFileName = _T("Open_File.dat");
if(!f.Open(pszFileName, CFile::modeCreate | CFile::modeWrite, &e))
{
   TRACE(_T("File could not be opened %d\n"), e.m_cause);
}

//A second example for CFile::Open.
//This function uses CFile to copy binary files.
bool BinaryFileCopy(LPCTSTR pszSource, LPCTSTR pszDest)
{
   // constructing these file objects doesn't open them
   CFile sourceFile;
   CFile destFile;

   // we'll use a CFileException object to get error information
   CFileException ex;

   // open the source file for reading
   if (!sourceFile.Open(pszSource,
      CFile::modeRead | CFile::shareDenyWrite, &ex))
   {
      // complain if an error happened
      // no need to delete the ex object

      TCHAR szError[1024];
      ex.GetErrorMessage(szError, 1024);
      _tprintf_s(_T("Couldn't open source file: %1024s"), szError);
      return false;
   }
   else
   {
      if (!destFile.Open(pszDest, CFile::modeWrite |
         CFile::shareExclusive | CFile::modeCreate, &ex))
      {
         TCHAR szError[1024];
         ex.GetErrorMessage(szError, 1024);
         _tprintf_s(_T("Couldn't open source file: %1024s"), szError);

         sourceFile.Close();
         return false;
      }

      BYTE buffer[4096];
      DWORD dwRead;

      // Read in 4096-byte blocks,
      // remember how many bytes were actually read,
      // and try to write that many out. This loop ends
      // when there are no more bytes to read.
      do
      {
         dwRead = sourceFile.Read(buffer, 4096);
         destFile.Write(buffer, dwRead);
      }
      while (dwRead > 0);

      // Close both files

      destFile.Close();
      sourceFile.Close();
   }

   return true;
}

CFile:: operator ハンドルCFile::operator HANDLE

この演算子を使用して、オブジェクトへのハンドルを CFile 、を想定する ReadFileEx や getfiletime などの関数に渡し HANDLE ます。Use this operator to pass a handle to a CFile object to functions such as ReadFileEx and GetFileTime that expect a HANDLE.

operator HANDLE() const;

CFile:: 読み取りCFile::Read

オブジェクトに関連付けられているファイルからバッファーにデータを読み取り CFile ます。Reads data into a buffer from the file associated with the CFile object.

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

パラメーターParameters

lpBuflpBuf
ファイルから読み取ったデータを受信するための、ユーザーが指定したバッファーへのポインター。Pointer to the user-supplied buffer that is to receive the data read from the file.

nCountnCount
ファイルから読み取る最大バイト数です。The maximum number of bytes to be read from the file. テキストモードファイルの場合、キャリッジリターンラインフィードのペアは単一の文字としてカウントされます。For text-mode files, carriage return-line feed pairs are counted as single characters.

戻り値Return Value

バッファーに転送するバイト数。The number of bytes transferred to the buffer. すべてのクラスについて CFile 、ファイルの末尾に到達した場合、戻り値は nCount より小さくなることがあります。For all CFile classes, the return value may be less than nCount if the end of file was reached.

例Example

CFile cfile;
cfile.Open(_T("Write_File.dat"), CFile::modeCreate | 
   CFile::modeReadWrite);
char pbufWrite[100];
memset(pbufWrite, 'a', sizeof(pbufWrite));
cfile.Write(pbufWrite, 100);         
cfile.Flush();
cfile.SeekToBegin();
char pbufRead[100];
cfile.Read(pbufRead, sizeof(pbufRead));
ASSERT(0 == memcmp(pbufWrite, pbufRead, sizeof(pbufWrite)));

別の例については、「 CFile:: Open」を参照してください。For another example, see CFile::Open.

CFile:: RemoveCFile::Remove

この静的関数は、パスで指定されたファイルを削除します。This static function deletes the file specified by the path.

static void PASCAL Remove(
    LPCTSTR lpszFileName,
    CAtlTransactionManager* pTM = NULL);

パラメーターParameters

lpszFileNamelpszFileName
目的のファイルへのパスを表す文字列。A string that is the path to the desired file. パスは、相対パスまたは絶対パスにすることができ、ネットワーク名を含めることができます。The path can be relative or absolute, and can contain a network name.

pTMpTM
CAtlTransactionManager オブジェクトへのポインター。Pointer to CAtlTransactionManager object

解説Remarks

Remove ディレクトリは削除されません。Remove won't remove a directory.

Remove接続されたファイルが開いている場合、またはファイルを削除できない場合、メンバー関数は例外をスローします。The Remove member function throws an exception if the connected file is open or if the file can't be removed. この関数は、DEL コマンドに相当します。This function is equivalent to the DEL command.

例Example

//example for CFile::Remove
TCHAR* pFileName = _T("Remove_File.dat");
try
{
   CFile::Remove(pFileName);
}
catch (CFileException* pEx)
{
   TRACE(_T("File %20s cannot be removed\n"), pFileName);
   pEx->Delete();
}

CFile:: 名前の変更CFile::Rename

この静的関数は、指定されたファイルの名前を変更します。This static function renames the specified file.

static void PASCAL Rename(
    LPCTSTR lpszOldName,
    LPCTSTR lpszNewName,
    CAtlTransactionManager* pTM = NULL);

パラメーターParameters

lpszOldNamelpszOldName
古いパス。The old path.

lpszNewNamelpszNewName
新しいパス。The new path.

pTMpTM
CAtlTransactionManager オブジェクトへのポインター。Pointer to CAtlTransactionManager object

解説Remarks

ディレクトリの名前を変更することはできません。Directories can't be renamed. この関数は、REN コマンドに相当します。This function is equivalent to the REN command.

例Example

TCHAR* pOldName = _T("Oldname_File.dat");
TCHAR* pNewName = _T("Renamed_File.dat");

try
{
    CFile::Rename(pOldName, pNewName);
}
catch(CFileException* pEx )
{
    TRACE(_T("File %20s not found, cause = %d\n"), pOldName, 
       pEx->m_cause);
    pEx->Delete();
}

CFile:: SeekCFile::Seek

開いているファイル内のファイルポインターを移動します。Repositions the file pointer in an open file.

virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom);

パラメーターParameters

lOfflOff
ファイルポインターを移動するバイト数。Number of bytes to move the file pointer. 正の値は、ファイルポインターをファイルの末尾に移動します。負の値を指定すると、ファイルポインターがファイルの先頭に移動します。Positive values move the file pointer towards the end of the file; negative values move the file pointer towards the start of the file.

nnFrom
シークする位置。Position to seek from. 使用可能な値については、「解説」を参照してください。See the Remarks section for possible values.

戻り値Return Value

メソッドが正常に実行された場合は、ファイルポインターの位置。それ以外の場合、戻り値は未定義で、例外へのポインター CFileException がスローされます。The position of the file pointer if the method was successful; otherwise, the return value is undefined and a pointer to a CFileException exception is thrown.

解説Remarks

次の表に、 Nfrom パラメーターに使用できる値を示します。The following table lists possible values for the nFrom parameter.

ファイルが開かれると、ファイルポインターはファイルの先頭の0に位置します。When a file is opened, the file pointer is positioned at 0, the start of the file.

ファイルポインターは、ファイルの末尾を越える位置に設定できます。You can set the file pointer to a position beyond the end of a file. この場合、ファイルに書き込むまでファイルのサイズは増加しません。If you do, the size of the file doesn't increase until you write to the file.

このメソッドの例外ハンドラーは、例外が処理された後に例外オブジェクトを削除する必要があります。The exception handler for this method must delete the exception object after the exception is processed.

例Example

CFile cfile;
cfile.Open(_T("Seek_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
LONGLONG lOffset = 1000;
ULONGLONG lActual;
lActual = cfile.Seek(lOffset, CFile::begin);

CFile:: SeekToBeginCFile::SeekToBegin

ファイルポインターの値をファイルの先頭に設定します。Sets the value of the file pointer to the beginning of the file.

void SeekToBegin();

解説Remarks

SeekToBegin() は Seek( 0L, CFile::begin ) に相当します。SeekToBegin() is equivalent to Seek( 0L, CFile::begin ).

例Example

CFile f;
f.Open(_T("Seeker_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
f.SeekToBegin();
ULONGLONG ullEnd = f.SeekToEnd();

CFile:: SeekToEndCFile::SeekToEnd

ファイルポインターの値をファイルの論理上の末尾に設定します。Sets the value of the file pointer to the logical end of the file.

ULONGLONG SeekToEnd();

戻り値Return Value

ファイルの長さをバイト単位で返します。The length of the file in bytes.

解説Remarks

SeekToEnd() は CFile::Seek( 0L, CFile::end ) に相当します。SeekToEnd() is equivalent to CFile::Seek( 0L, CFile::end ).

例Example

CFile f;
f.Open(_T("Seeker_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
f.SeekToBegin();
ULONGLONG ullEnd = f.SeekToEnd();

CFile:: SetFilePathCFile::SetFilePath

ファイルのパスを指定するには、この関数を呼び出します。Call this function to specify the path of the file. たとえば、 CFile オブジェクトが構築されたときにファイルのパスを使用できない場合は、 SetFilePath を呼び出して指定します。For example, if the path of a file isn't available when a CFile object is constructed, call SetFilePath to provide it.

virtual void SetFilePath(LPCTSTR lpszNewName);

パラメーターParameters

lpszNewNamelpszNewName
新しいパスを指定する文字列へのポインター。Pointer to a string specifying the new path.

解説Remarks

例Example

TCHAR* pstrName = _T("C:\\test\\SetPath_File.dat");

// open a file
HANDLE hFile = ::CreateFile(pstrName, GENERIC_WRITE, FILE_SHARE_READ,
   NULL, CREATE_ALWAYS, 0, NULL);

if (hFile != INVALID_HANDLE_VALUE)
{
   // attach a CFile object to it
   CFile myFile(hFile);

   // At this point, myFile doesn't know the path name for the file
   // it owns because Windows doesn't associate that information
   // with the handle. Any CFileExceptions thrown by this object
   // won't have complete information.

   // Calling SetFilePath() remedies that problem by letting CFile
   // know the name of the file that's associated with the object.

   myFile.SetFilePath(pstrName);

   // write something to the file and flush it immediately
   DWORD dwValue = 1234;
   myFile.Write(&dwValue, sizeof(dwValue));
   myFile.Flush();

   // destroying the CObject here will call ::CloseHandle() on the file
} 

CFile:: SetLengthCFile::SetLength

ファイルの長さを変更するには、この関数を呼び出します。Call this function to change the length of the file.

virtual void SetLength(ULONGLONG dwNewLen);

パラメーターParameters

dwNewLendwNewLen
ファイルの必要な長さ (バイト単位)。Desired length of the file in bytes. この値は、ファイルの現在の長さより大きいか小さくすることができます。This value can be larger or smaller than the current length of the file. ファイルは、必要に応じて拡張または切り捨てられます。The file will be extended or truncated as appropriate.

解説Remarks

例Example

CFile cfile;
cfile.Open(_T("SetLength_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwNewLength = 10000;
cfile.SetLength(dwNewLength);

CFile:: SetStatusCFile::SetStatus

このファイルの場所に関連付けられているファイルの状態を設定します。Sets the status of the file associated with this file location.

static void PASCAL SetStatus(
    LPCTSTR lpszFileName,
    const CFileStatus& status,
    CAtlTransactionManager* pTM = NULL);

パラメーターParameters

lpszFileNamelpszFileName
目的のファイルへのパスを表す文字列。A string that is the path to the desired file. パスは、相対パスまたは絶対パスにすることができ、ネットワーク名を含めることができます。The path can be relative or absolute, and can contain a network name.

statusstatus
新しいステータス情報を格納しているバッファー。The buffer containing the new status information. メンバー関数を呼び出して、 GetStatus 現在の CFileStatus 値で構造体を事前に設定し、必要に応じて変更を行います。Call the GetStatus member function to prefill the CFileStatus structure with current values, then make changes as required. 値が0の場合、対応するステータス項目は更新されません。If a value is 0, then the corresponding status item isn't updated. 構造体の説明については、 GetStatus メンバー関数を参照してください CFileStatus 。See the GetStatus member function for a description of the CFileStatus structure.

pTMpTM
CAtlTransactionManager オブジェクトへのポインター。Pointer to CAtlTransactionManager object

解説Remarks

時刻を設定するには、 m_mtime 状態 のフィールドを変更します。To set the time, modify the m_mtime field of status.

ファイルの属性のみを変更しようとしてを呼び出したときに、 SetStatus m_mtime ファイル状態構造体のメンバーが0以外の場合は、属性も影響を受ける可能性があります (タイムスタンプを変更すると、属性に副作用が生じる可能性があります)。When you make a call to SetStatus in an attempt to change only the attributes of the file, and the m_mtime member of the file status structure is nonzero, the attributes may also be affected (changing the time stamp may have side effects on the attributes). ファイルの属性のみを変更する場合は、まず、 m_mtime ファイル状態構造体のメンバーを0に設定してから、を呼び出し SetStatus ます。If you want to only change the attributes of the file, first set the m_mtime member of the file status structure to zero and then make a call to SetStatus.

例Example

TCHAR* pFileName = _T("ReadOnly_File.dat");
CFileStatus status;
CFile::GetStatus(pFileName, status);
status.m_attribute |= CFile::readOnly;
CFile::SetStatus(pFileName, status);         

CFile:: UnlockRangeCFile::UnlockRange

開いているファイルのバイト範囲をロック解除します。Unlocks a range of bytes in an open file.

virtual void UnlockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

パラメーターParameters

dwPosdwPos
ロックを解除するバイト範囲の先頭のバイトオフセット。The byte offset of the start of the byte range to unlock.

dwCountdwCount
ロックを解除する範囲内のバイト数。The number of bytes in the range to unlock.

解説Remarks

詳細については、 LockRange メンバー関数の説明を参照してください。See the description of the LockRange member function for details.

例Example

CFile cfile;
cfile.Open(_T("LockRange_File.dat"), CFile::modeCreate |
   CFile::modeReadWrite);
ULONGLONG dwPos = 10;
ULONGLONG dwCount = 100;
cfile.LockRange(dwPos, dwCount);

// do something with the file

cfile.UnlockRange(dwPos, dwCount);

CFile:: 書き込みCFile::Write

バッファーからオブジェクトに関連付けられたファイルにデータを書き込み CFile ます。Writes data from a buffer to the file associated with the CFile object.

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

パラメーターParameters

lpBuflpBuf
ファイルに書き込まれるデータを格納する、ユーザーが指定したバッファーへのポインター。A pointer to the user-supplied buffer that contains the data to be written to the file.

nCountnCount
バッファーから転送されるバイト数。The number of bytes to be transferred from the buffer. テキストモードファイルの場合、キャリッジリターンラインフィードのペアは単一の文字としてカウントされます。For text-mode files, carriage return-line feed pairs are counted as single characters.

解説Remarks

Write では、ディスク全体の条件など、いくつかの条件に応じて例外がスローされます。Write throws an exception in response to several conditions, including the disk-full condition.

例Example

CFile cfile;
cfile.Open(_T("Write_File.dat"), CFile::modeCreate | 
   CFile::modeReadWrite);
char pbufWrite[100];
memset(pbufWrite, 'a', sizeof(pbufWrite));
cfile.Write(pbufWrite, 100);         
cfile.Flush();

また、 cfile:: cfile と Cfile:: Openの例も参照してください。Also see the examples for CFile::CFile and CFile::Open.

関連項目See also

MFC のサンプル DRAWCLIMFC Sample DRAWCLI
CObject クラスCObject Class
階層図Hierarchy Chart
CStdioFile クラスCStdioFile Class
CMemFile クラスCMemFile Class