CFile, classe

Article
10/12/2023

Classe de base pour les classes de fichier Microsoft Foundation Class.

Syntaxe

class CFile : public CObject

Membres

Constructeurs publics

Nom	Description
CFile ::CFile	Construit un objet à partir d’un `CFile` chemin d’accès ou d’un handle de fichier.

Méthodes publiques

Nom	Description
CFile ::Abort	Ferme un fichier ignorant tous les avertissements et erreurs.
CFile ::Close	Ferme un fichier et supprime l’objet.
CFile ::D uplicate	Construit un objet en double basé sur ce fichier.
CFile ::Flush	Vide toutes les données à écrire.
CFile ::GetFileName	Récupère le nom de fichier du fichier sélectionné.
CFile ::GetFilePath	Récupère le chemin d’accès complet du fichier sélectionné.
CFile ::GetFileTitle	Récupère le titre du fichier sélectionné.
CFile ::GetLength	Récupère la longueur du fichier.
CFile ::GetPosition	Récupère le pointeur de fichier actuel.
CFile ::GetStatus	Récupère l’état du fichier ouvert, ou dans la version statique, récupère l’état du fichier spécifié (statique, fonction virtuelle).
CFile ::LockRange	Verrouille une plage d’octets dans un fichier.
CFile ::Open	Ouvre en toute sécurité un fichier avec une option de test d’erreur.
CFile ::Read	Lit (nonbuffer) les données d’un fichier à la position actuelle du fichier.
CFile ::Remove	Supprime le fichier spécifié (fonction statique).
CFile ::Rename	Renomme le fichier spécifié (fonction statique).
CFile ::Seek	Positionne le pointeur de fichier actuel.
CFile ::SeekToBegin	Positionne le pointeur de fichier actuel au début du fichier.
CFile ::SeekToEnd	Positionne le pointeur de fichier actif à la fin du fichier.
CFile ::SetFilePath	Définit le chemin d’accès complet du fichier sélectionné.
CFile ::SetLength	Modifie la longueur du fichier.
CFile ::SetStatus	Définit l’état du fichier spécifié (statique, fonction virtuelle).
CFile ::UnlockRange	Déverrouille une plage d’octets dans un fichier.
CFile ::Write	Écrit (non sauvegardé) des données dans un fichier à la position actuelle du fichier.

Opérateurs publics

Nom	Description
CFile ::operator HANDLE	Handle vers un `CFile` objet.

Membres de données publics

Nom	Description
CFile ::hFileNull	Détermine si l’objet `CFile` a un handle valide.
CFile ::m_hFile	Contient généralement le handle de fichier du système d’exploitation.

Membres de données protégés

Nom	Description
CFile ::m_pTM	Pointeur vers l’objet `CAtlTransactionManager` .

Notes

Il fournit directement des services d’entrée/sortie de disque binaire nonbuffer, et prend indirectement en charge les fichiers texte et les fichiers mémoire par le biais de ses classes dérivées. CFile fonctionne conjointement avec la classe pour prendre en charge la CArchive sérialisation des objets microsoft Foundation Class.

La relation hiérarchique entre cette classe et ses classes dérivées permet à votre programme d’opérer sur tous les objets de fichier via l’interface polymorphe CFile . Un fichier mémoire, par exemple, se comporte comme un fichier disque.

Utilisez CFile et ses classes dérivées pour les E/S de disque à usage général. Utilisez ofstream ou d’autres classes Microsoft iostream pour le texte mis en forme envoyé à un fichier de disque.

Normalement, un fichier disque est ouvert automatiquement lors de la CFile construction et fermé lors de la destruction. Les fonctions membres statiques vous permettent d’interroger l’état d’un fichier sans ouvrir le fichier.

Pour plus d’informations sur l’utilisationCFile, consultez les articles Fichiers dans MFC et Gestion des fichiers dans la référence de la bibliothèque d’exécution.

Hiérarchie d'héritage

CObject

CFile

Spécifications

En-tête : afx.h

CFile ::Abort

Ferme le fichier associé à cet objet et rend le fichier indisponible pour la lecture ou l’écriture.

virtual void Abort();

Notes

Si vous n’avez pas fermé le fichier avant de détruire l’objet, le destructeur le ferme pour vous.

Lors de la gestion des exceptions, CFile::Abort diffère de CFile::Close deux façons importantes. Tout d’abord, la Abort fonction ne lève pas d’exception sur les échecs, car les échecs sont ignorés par Abort. Ensuite, Abort ne s’affirme pas si le fichier n’a pas été ouvert ou a été fermé précédemment.

Si vous avez utilisé new pour allouer l’objet CFile sur le tas, vous devez le supprimer après avoir fermé le fichier. Abort définit m_hFile sur CFile::hFileNull.

Exemple

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 ::CFile

Construit et initialise un objet CFile.

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

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags);

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

Paramètres

hFile
Handle d'un fichier à attacher à l'objet CFile.

lpszFileName
Chemin d'accès relatif ou complet d'un fichier à attacher à l'objet CFile.

nOpenFlags
Combinaison de bits (OR) ou options d'accès au fichier pour le fichier spécifié. Consultez la section Notes pour connaître les options possibles.

pTM
Pointeur vers l'objet CAtlTransactionManager

Notes

Les cinq tableaux suivants répertorient les options possibles pour le paramètre nOpenFlags .

Choisissez une seule des options suivantes pour le mode d'accès aux fichiers. Le mode d'accès aux fichiers par défaut est CFile::modeRead, c'est-à-dire en lecture seule.

Valeur	Description
`CFile::modeRead`	Demande l'accès en lecture uniquement.
`CFile::modeWrite`	Demande l'accès en écriture uniquement.
`CFile::modeReadWrite`	Demande l'accès en lecture et en écriture.

Choisissez l'une des options suivantes pour le mode caractère.

Valeur	Description
`CFile::typeBinary`	Définit le mode binaire (utilisé dans les classes dérivées uniquement).
`CFile::typeText`	Définit le mode texte avec un traitement spécial pour les paires de flux de retour chariot (utilisées uniquement dans les classes dérivées).
`CFile::typeUnicode`	Définit le mode Unicode (utilisé dans les classes dérivées uniquement). Le texte est écrit dans le fichier au format Unicode quand l'application est générée dans une configuration Unicode. Aucune marque d'ordre d'octet n'est écrite dans le fichier.

Choisissez une seule des options suivantes pour le mode de partage de fichiers. Le mode de partage de fichiers par défaut est CFile::shareExclusive, c'est-à-dire exclusif.

Valeur	Description
`CFile::shareDenyNone`	Aucune restriction de partage.
`CFile::shareDenyRead`	Refuse l'accès en lecture à tous les autres.
`CFile::shareDenyWrite`	Refuse l'accès en écriture à tous les autres.
`CFile::shareExclusive`	Refuse l'accès en lecture et en écriture à tous les autres.

Choisissez la première ou les deux options suivantes pour le mode de création de fichiers. Le mode de création par défaut est CFile::modeNoTruncate, c'est-à-dire ouvrir l'existant.

Valeur	Description
`CFile::modeCreate`	Crée un fichier s’il n’existe aucun fichier. Si le fichier existe déjà, il est remplacé et défini initialement sur zéro longueur.
`CFile::modeNoTruncate`	Crée un fichier s’il n’existe aucun fichier ; sinon, si le fichier existe déjà, il est attaché à l’objet `CFile` .

Choisissez les options de mise en cache de fichiers suivantes d'après leur description. Par défaut, le système utilise un schéma de mise en cache à usage général qui n’est pas disponible en tant qu’option.

Valeur	Description
`CFile::osNoBuffer`	Le système n’utilise pas de cache intermédiaire pour le fichier. Cette option annule les deux options suivantes.
`CFile::osRandomAccess`	Le cache de fichiers est optimisé pour l'accès aléatoire. N’utilisez pas cette option et l’option d’analyse séquentielle.
`CFile::osSequentialScan`	Le cache de fichiers est optimisé pour l'accès séquentiel. N’utilisez pas cette option et l’option d’accès aléatoire.
`CFile::osWriteThrough`	Les opérations d’écriture sont effectuées sans délai.

Choisissez l'option de sécurité suivante pour empêcher l'héritage du handle de fichier. Par défaut, tous les nouveaux processus enfants peuvent utiliser le handle de fichier.

Valeur	Description
`CFile::modeNoInherit`	Empêche les processus enfants d'utiliser le handle de fichier.

Le constructeur par défaut initialise les membres, mais n’attache pas de fichier à l’objet CFile . Après avoir utilisé ce constructeur, utilisez la méthode CFile ::Open pour ouvrir un fichier et l’attacher à l’objet CFile .

Le constructeur avec un seul paramètre initialise les membres et attache un fichier existant à l'objet CFile.

Le constructeur avec deux paramètres initialise les membres et tente d'ouvrir le fichier spécifié. Si ce constructeur ouvre correctement le fichier spécifié, le fichier est attaché à l'objet CFile. Sinon, ce constructeur émet un pointeur vers un objet CInvalidArgException. Pour plus d’informations sur la gestion des exceptions, consultez Exceptions.

Si un CFile objet ouvre correctement un fichier spécifié, il ferme automatiquement ce fichier lorsque l’objet CFile est détruit ; sinon, vous devez fermer explicitement le fichier une fois qu’il n’est plus attaché à l’objet CFile .

Exemple

Le code suivant illustre l'utilisation de 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 ::Close

Ferme le fichier associé à cet objet et rend le fichier indisponible pour la lecture ou l’écriture.

virtual void Close();

Notes

Si vous n’avez pas fermé le fichier avant de détruire l’objet, le destructeur le ferme pour vous.

Si vous avez utilisé new pour allouer l’objet CFile sur le tas, vous devez le supprimer après avoir fermé le fichier. Close définit m_hFile sur CFile::hFileNull.

Exemple

Consultez l’exemple de CFile ::CFile.

CFile ::D uplicate

Construit un objet en double CFile pour un fichier donné.

virtual CFile* Duplicate() const;

Valeur de retour

Pointeur vers un objet en double CFile .

Notes

Cette fonction équivaut à la fonction _dupd’exécution C.

CFile ::Flush

Force l’écriture de toutes les données restantes dans la mémoire tampon du fichier.

virtual void Flush();

Notes

L’utilisation de Flush ne garantit pas le vidage des CArchive mémoires tampons. Si vous utilisez une archive, appelez D’abord CArchive ::Flush .

Exemple

Consultez l’exemple de CFile ::SetFilePath.

CFile ::GetFileName

Appelez cette fonction membre pour récupérer le nom d’un fichier spécifié.

virtual CString GetFileName() const;

Valeur de retour

Le nom du fichier.

Notes

Par exemple, lorsque vous appelez GetFileName pour générer un message à l’utilisateur sur le fichier c:\windows\write\myfile.wri, le nom de fichier, myfile.wriest retourné.

Pour retourner l’intégralité du chemin du fichier, y compris le nom, appelez GetFilePath. Pour retourner le titre du fichier ( ), myfileappelez GetFileTitle.

Exemple

Ce fragment de code ouvre le SYSTÈME. Fichier INI dans votre répertoire WINDOWS. Si vous le trouvez, l’exemple affiche le nom et le chemin d’accès et le titre, comme indiqué sous Sortie :

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 ::GetFilePath

Appelez cette fonction membre pour récupérer le chemin complet d’un fichier spécifié.

virtual CString GetFilePath() const;

Valeur de retour

Chemin d’accès complet du fichier spécifié.

Notes

Par exemple, lorsque vous appelez GetFilePath pour générer un message à l’utilisateur sur le fichier c:\windows\write\myfile.wri, le chemin du fichier, c:\windows\write\myfile.wriest retourné.

Pour renvoyer uniquement le nom du fichier (myfile.wri), appelez GetFileName. Pour retourner le titre du fichier (myfile), appelez GetFileTitle.

Exemple

Consultez l’exemple de GetFileName.

CFile ::GetFileTitle

Appelez cette fonction membre pour récupérer le titre du fichier (le nom complet) du fichier.

virtual CString GetFileTitle() const;

Valeur de retour

Titre du fichier sous-jacent.

Notes

Cette méthode appelle GetFileTitle pour récupérer le titre du fichier. Si elle réussit, la méthode retourne la chaîne que le système utiliserait pour afficher le nom de fichier à l’utilisateur. Sinon, la méthode appelle PathFindFileName pour récupérer le nom de fichier (y compris l’extension de fichier) du fichier sous-jacent. Cela signifie que l’extension de fichier n’est pas toujours incluse dans la chaîne de titre de fichier retournée. Pour plus d’informations, consultez GetFileTitle et PathFindFileName dans le Kit de développement logiciel (SDK) Windows.

Pour retourner l’intégralité du chemin du fichier, y compris le nom, appelez GetFilePath. Pour retourner uniquement le nom du fichier, appelez GetFileName.

Exemple

Consultez l’exemple de GetFileName.

CFile ::GetLength

Obtient la longueur logique actuelle du fichier en octets.

virtual ULONGLONG GetLength() const;

Valeur de retour

Longueur du fichier.

Exemple

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 ::GetPosition

Obtient la valeur actuelle du pointeur de fichier, qui peut être utilisée dans les appels ultérieurs à Seek.

virtual ULONGLONG GetPosition() const;

Valeur de retour

Pointeur de fichier.

Exemple

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 ::GetStatus

Cette méthode récupère les informations d’état relatives à une instance d’objet donnée CFile ou à un chemin d’accès de fichier donné.

BOOL GetStatus(CFileStatus& rStatus) const;

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

Paramètres

rStatus
Référence à une structure fournie par CFileStatus l’utilisateur qui recevra les informations d’état. La CFileStatus structure comporte les champs suivants :

CTime m_ctime Date et heure de création du fichier.
CTime m_mtime Date et heure de la dernière modification du fichier.
CTime m_atime Date et heure auxquelles le fichier a été consulté pour la dernière lecture.
ULONGLONG m_size Taille logique du fichier en octets, comme indiqué par la commande DIR.
BYTE m_attribute Octet d’attribut du fichier.
char m_szFullName[_MAX_PATH] Nom de fichier absolu dans le jeu de caractères Windows.

lpszFileName
Chaîne dans le jeu de caractères Windows qui est le chemin d’accès au fichier souhaité. Le chemin d’accès peut être relatif ou absolu, ou il peut contenir un nom de chemin d’accès réseau.

pTM
Pointeur vers l'objet CAtlTransactionManager

Valeur de retour

TRUE si les informations d’état du fichier spécifié sont correctement obtenues ; sinon, FALSE.

Notes

La version non statique de GetStatus récupère les informations d’état du fichier ouvert associé à l’objet donné CFile . La version statique d’obtention de l’état du GetStatus fichier à partir d’un chemin d’accès de fichier donné sans réellement ouvrir le fichier. Cette version est utile pour tester l’existence et les droits d’accès d’un fichier.

Le m_attribute membre de la CFileStatus structure fait référence au jeu d’attributs de fichier. La CFile classe fournit le type d’énumération Attribute afin que les attributs de fichier puissent être spécifiés symboliquement :

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

Exemple

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 ::hFileNull

Détermine la présence d’un handle de fichier valide pour l’objet CFile .

static AFX_DATA const HANDLE hFileNull;

Notes

Cette constante est utilisée pour déterminer si l’objet CFile a un handle de fichier valide.

L’exemple suivant illustre cette opération :

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

CFile ::LockRange

Verrouille une plage d’octets dans un fichier ouvert, lève une exception si le fichier est déjà verrouillé.

virtual void LockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Paramètres

dwPos
Décalage d’octet du début de la plage d’octets à verrouiller.

dwCount
Nombre d’octets dans la plage à verrouiller.

Notes

Le verrouillage d’octets dans un fichier empêche l’accès à ces octets par d’autres processus. Vous pouvez verrouiller plusieurs régions d’un fichier, mais aucune région qui se chevauche n’est autorisée.

Lorsque vous déverrouillez la région à l’aide de la UnlockRange fonction membre, la plage d’octets doit correspondre exactement à la région précédemment verrouillée. La LockRange fonction ne fusionne pas les régions adjacentes. Si deux régions verrouillées sont adjacentes, vous devez déverrouiller chaque région séparément.

Remarque

Cette fonction n’est pas disponible pour la CMemFileclasse dérivée ..

Exemple

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_hFile

Contient le handle de fichier du système d’exploitation pour un fichier ouvert.

HANDLE m_hFile;

Notes

m_hFile est une variable publique de type UINT. Il contient CFile::hFileNull, un indicateur de fichier vide indépendant du système d’exploitation, si le handle n’a pas été affecté.

L’utilisation n’est m_hFile pas recommandée, car la signification du membre dépend de la classe dérivée. m_hFile est rendu un membre public pour faciliter la prise en charge de l’utilisation nonpolymorphe de la classe.

CFile ::m_pTM

Pointeur vers un CAtlTransactionManager objet.

CAtlTransactionManager* m_pTM;

Notes

CFile ::Open

Surcharge. Open est conçu pour une utilisation avec le constructeur par défaut CFile .

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

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

Paramètres

lpszFileName
Chaîne qui contient le chemin d’accès au fichier souhaité. Le chemin d’accès peut être relatif, absolu ou un nom réseau (UNC).

nOpenFlags
UINT qui définit le mode de partage et d’accès du fichier. Elle spécifie l’action à entreprendre lors de l’ouverture du fichier. Vous pouvez combiner des options à l’aide de l’opérateur BITwise-OR ( | ). Une autorisation d’accès et une option de partage sont requises ; les modes et modeNoInherit les modeCreate modes sont facultatifs. Consultez le constructeur CFile pour obtenir la liste des options de mode.

pError
Pointeur vers un objet d’exception de fichier existant qui recevra l’état d’une opération ayant échoué.

pTM
Pointeur vers l'objet CAtlTransactionManager

Valeur de retour

Différent de zéro si l’ouverture a réussi ; sinon 0. Le paramètre pError n’est significatif que si 0 est retourné.

Notes

Les deux Open fonctions sont des méthodes « sécurisées » pour ouvrir un fichier, où une défaillance est une condition normale et attendue.

Pendant que le CFile constructeur lève une exception dans une condition d’erreur, Open retourne FALSE pour les conditions d’erreur. Open peut toujours initialiser un objet CFileException pour décrire l’erreur. Si vous ne fournissez pas le paramètre pError , ou si vous passez NULL pour pError, Open retourne FALSE et ne lève pas de CFileExceptionfichier . Si vous passez un pointeur vers un pointeur existant CFileExceptionet Open rencontre une erreur, la fonction le remplit avec des informations décrivant cette erreur. Open ne lève pas d’exception dans les deux cas.

Le tableau suivant décrit les résultats possibles de Open.

`pError`	Erreur rencontrée	Valeur retournée	Contenu CFileException
NULL	Non	VRAI	n/a
ptr to `CFileException`	Non	VRAI	inchangé
NULL	Oui	FAUX	n/a
ptr to `CFileException`	Oui	FAUX	initialisé pour décrire l’erreur

Exemple

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 HANDLE

Utilisez cet opérateur pour passer un handle à un objet à des CFile fonctions telles que ReadFileEx et GetFileTime qui attendent un HANDLE.

operator HANDLE() const;

CFile ::Read

Lit les données dans une mémoire tampon à partir du fichier associé à l’objet CFile .

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

Paramètres

lpBuf
Pointeur vers la mémoire tampon fournie par l’utilisateur qui doit recevoir les données lues à partir du fichier.

nCount
Nombre maximal d’octets à lire à partir du fichier. Pour les fichiers en mode texte, les paires de flux de retour chariot sont comptabilisées sous forme de caractères uniques.

Valeur de retour

Nombre d'octets transférés dans la mémoire tampon. Pour toutes les CFile classes, la valeur de retour peut être inférieure à nCount si la fin du fichier a été atteinte.

Exemple

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)));

Pour obtenir un autre exemple, consultez CFile ::Open.

CFile ::Remove

Cette fonction statique supprime le fichier spécifié par le chemin d’accès.

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

Paramètres

lpszFileName
Chaîne qui est le chemin d’accès au fichier souhaité. Le chemin d’accès peut être relatif ou absolu et peut contenir un nom réseau.

pTM
Pointeur vers l'objet CAtlTransactionManager

Notes

Remove ne supprime pas un répertoire.

La Remove fonction membre lève une exception si le fichier connecté est ouvert ou si le fichier ne peut pas être supprimé. Cette fonction équivaut à la commande DEL.

Exemple

//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 ::Rename

Cette fonction statique renomme le fichier spécifié.

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

Paramètres

lpszOldName
Chemin d’accès ancien.

lpszNewName
Nouveau chemin d’accès.

pTM
Pointeur vers l'objet CAtlTransactionManager

Notes

Les répertoires ne peuvent pas être renommés. Cette fonction équivaut à la commande REN.

Exemple

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 ::Seek

Repositionne le pointeur de fichier dans un fichier ouvert.

virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom);

Paramètres

lOff
Nombre d’octets pour déplacer le pointeur de fichier. Les valeurs positives déplacent le pointeur de fichier vers la fin du fichier ; les valeurs négatives déplacent le pointeur de fichier vers le début du fichier.

nFrom
Position à partir de laquelle rechercher. Consultez la section Remarques pour connaître les valeurs possibles.

Valeur de retour

Position du pointeur de fichier si la méthode a réussi ; sinon, la valeur de retour n’est pas définie et un pointeur vers une CFileException exception est levée.

Notes

Le tableau suivant répertorie les valeurs possibles pour le paramètre nFrom .

Valeur	Description
`CFile::begin`	Recherchez à partir du début du fichier.
`CFile::current`	Recherchez à partir de l’emplacement actuel du pointeur de fichier.
`CFile::end`	Recherchez à partir de la fin du fichier.

Lorsqu’un fichier est ouvert, le pointeur de fichier est positionné à 0, le début du fichier.

Vous pouvez définir le pointeur de fichier sur une position au-delà de la fin d’un fichier. Si vous le faites, la taille du fichier n’augmente pas tant que vous n’avez pas écrit dans le fichier.

Le gestionnaire d’exceptions de cette méthode doit supprimer l’objet exception une fois l’exception traitée.

Exemple

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

CFile ::SeekToBegin

Définit la valeur du pointeur de fichier au début du fichier.

void SeekToBegin();

Notes

SeekToBegin() est équivalent à Seek( 0L, CFile::begin ).

Exemple

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

CFile ::SeekToEnd

Définit la valeur du pointeur de fichier à la fin logique du fichier.

ULONGLONG SeekToEnd();

Valeur de retour

Longueur du fichier en octets.

Notes

SeekToEnd() est équivalent à CFile::Seek( 0L, CFile::end ).

Exemple

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

CFile ::SetFilePath

Appelez cette fonction pour spécifier le chemin d’accès du fichier. Par exemple, si le chemin d’accès d’un fichier n’est pas disponible lorsqu’un objet CFile est construit, appelez-le SetFilePath pour le fournir.

virtual void SetFilePath(LPCTSTR lpszNewName);

Paramètres

lpszNewName
Pointeur vers une chaîne spécifiant le nouveau chemin d’accès.

Notes

Remarque

SetFilePath n’ouvre pas le fichier ou ne crée pas le fichier ; il associe simplement l’objet CFile à un nom de chemin d’accès, qui peut ensuite être utilisé.

Exemple

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 ::SetLength

Appelez cette fonction pour modifier la longueur du fichier.

virtual void SetLength(ULONGLONG dwNewLen);

Paramètres

dwNewLen
Longueur souhaitée du fichier en octets. Cette valeur peut être supérieure ou inférieure à la longueur actuelle du fichier. Le fichier sera étendu ou tronqué selon les besoins.

Notes

Remarque

Avec CMemFile, cette fonction peut lever un CMemoryException objet.

Exemple

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

CFile ::SetStatus

Définit l’état du fichier associé à cet emplacement de fichier.

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

Paramètres

lpszFileName
Chaîne qui est le chemin d’accès au fichier souhaité. Le chemin d’accès peut être relatif ou absolu et peut contenir un nom réseau.

statut
Mémoire tampon contenant les nouvelles informations d’état. Appelez la GetStatus fonction membre pour préremplir la CFileStatus structure avec les valeurs actuelles, puis apportez des modifications en fonction des besoins. Si une valeur est 0, l’élément d’état correspondant n’est pas mis à jour. Consultez la fonction membre GetStatus pour obtenir une description de la CFileStatus structure.

pTM
Pointeur vers l'objet CAtlTransactionManager

Notes

Pour définir l’heure, modifiez le m_mtime champ d’état.

Lorsque vous effectuez un appel à SetStatus une tentative de modification uniquement des attributs du fichier et que le m_mtime membre de la structure d’état de fichier n’est pas différent de zéro, les attributs peuvent également être affectés (la modification de l’horodatage peut avoir des effets secondaires sur les attributs). Si vous souhaitez uniquement modifier les attributs du fichier, définissez d’abord le m_mtime membre de la structure d’état du fichier sur zéro, puis effectuez un appel à SetStatus.

Exemple

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

CFile ::UnlockRange

Déverrouille une plage d’octets dans un fichier ouvert.

virtual void UnlockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Paramètres

dwPos
Décalage d’octets du début de la plage d’octets à déverrouiller.

dwCount
Nombre d’octets dans la plage à déverrouiller.

Notes

Pour plus d’informations, consultez la description de la fonction membre LockRange .

Remarque

Cette fonction n’est pas disponible pour la CMemFileclasse dérivée ..

Exemple

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 ::Write

Écrit des données d’une mémoire tampon dans le fichier associé à l’objet CFile .

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

Paramètres

lpBuf
Pointeur vers la mémoire tampon fournie par l’utilisateur qui contient les données à écrire dans le fichier.

nCount
Nombre d’octets à transférer à partir de la mémoire tampon. Pour les fichiers en mode texte, les paires de flux de retour chariot sont comptabilisées sous forme de caractères uniques.

Notes

Write lève une exception en réponse à plusieurs conditions, y compris la condition complète du disque.

Exemple

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();

Consultez également les exemples de CFile ::CFile et CFile ::Open.

Voir aussi

Exemple DRAWCLI MFC
CObject, classe
Graphique hiérarchique
CStdioFile, classe
CMemFile, classe

Partager via

CFile, classe

Syntaxe

Membres

Constructeurs publics

Méthodes publiques

Opérateurs publics

Membres de données publics

Membres de données protégés

Notes

Hiérarchie d'héritage

Spécifications

CFile ::Abort

Notes

Exemple

CFile ::CFile

Paramètres

Notes

Exemple

CFile ::Close

Notes

Exemple

CFile ::D uplicate

Valeur de retour

Notes

CFile ::Flush

Notes

Exemple

CFile ::GetFileName

Valeur de retour

Notes

Exemple

CFile ::GetFilePath

Valeur de retour

Notes

Exemple

CFile ::GetFileTitle

Valeur de retour

Notes

Exemple

CFile ::GetLength

Valeur de retour

Exemple

CFile ::GetPosition

Valeur de retour

Exemple

CFile ::GetStatus

Paramètres

Valeur de retour

Notes

Exemple

CFile ::hFileNull

Notes

CFile ::LockRange

Paramètres

Notes

Exemple

CFile ::m_hFile

Notes

CFile ::m_pTM

Notes

CFile ::Open

Paramètres

Valeur de retour

Notes

Exemple

CFile ::operator HANDLE

CFile ::Read

Paramètres

Valeur de retour

Exemple

CFile ::Remove

Paramètres

Notes

Exemple

CFile ::Rename

Paramètres

Notes

Exemple

CFile ::Seek