CFile (Clase)

Artículo
06/16/2023

La clase base para las clases de archivo de MFC (Microsoft Foundation Classes).

Sintaxis

class CFile : public CObject

Miembros

Constructores públicos

Nombre	Descripción
CFile::CFile	Construye un objeto `CFile` a partir de una ruta de acceso o un identificador de archivo.

Métodos públicos

Nombre	Descripción
CFile::Abort	Cierra un archivo y omite todas las advertencias y los errores.
CFile::Close	Cierra un archivo y elimina el objeto.
CFile::Duplicate	Construye un objeto duplicado basado en este archivo.
CFile::Flush	Vacía los datos que quedan por escribir.
CFile::GetFileName	Recupera el nombre de archivo del archivo seleccionado.
CFile::GetFilePath	Recupera la ruta de acceso completa del archivo seleccionado.
CFile::GetFileTitle	Recupera el título del archivo seleccionado.
CFile::GetLength	Recupera la longitud del archivo.
CFile::GetPosition	Recupera el puntero de archivo actual.
CFile::GetStatus	Recupera el estado del archivo abierto, o en la versión estática, recupera el estado del archivo especificado (función virtual,estática).
CFile::LockRange	Bloquea un intervalo de bytes de un archivo.
CFile::Open	Abre de forma segura un archivo con una opción de prueba de errores.
CFile::Read	Lee datos (no almacenados en el búfer) de un archivo en la posición del archivo actual.
CFile::Remove	Elimina el archivo especificado (función estática).
CFile::Rename	Cambia el nombre del archivo especificado (función estática).
CFile::Seek	Coloca el puntero de archivo actual.
CFile::SeekToBegin	Coloca el puntero de archivo actual al principio del archivo.
CFile::SeekToEnd	Coloca el puntero de archivo actual al final del archivo.
CFile::SetFilePath	Establece la ruta de acceso completa del archivo seleccionado.
CFile::SetLength	Cambia la longitud del archivo.
CFile::SetStatus	Establece el estado del archivo especificado (función virtual, estática).
CFile::UnlockRange	Desbloquea un intervalo de bytes de un archivo.
CFile::Write	Escribe datos (no almacenados en el búfer) en un archivo en la posición del archivo actual.

Operadores públicos

Nombre	Descripción
CFile::operator HANDLE	Identificador de un objeto `CFile`.

Miembros de datos públicos

Nombre	Descripción
CFile::hFileNull	Determina si el objeto `CFile` tiene un identificador válido.
CFile::m_hFile	Normalmente contiene el identificador de archivo del sistema operativo.

Miembros de datos protegidos

Nombre	Descripción
CFile::m_pTM	Puntero al objeto `CAtlTransactionManager`.

Comentarios

Proporciona directamente servicios de entrada y salida de disco binarios no almacenados en el búfer, y admite indirectamente archivos de texto y archivos de memoria por medio de sus clases derivadas. CFile funciona junto con la clase CArchive para admitir la serialización de objetos de Microsoft Foundation Class.

La relación jerárquica entre esta clase y sus clases derivadas permite al programa operar en todos los objetos de archivo por medio de la interfaz polimórfica CFile. Un archivo de memoria, por ejemplo, se comporta como un archivo de disco.

Use CFile y sus clases derivadas para E/S de disco de uso general. Use ofstream u otras clases iostream de Microsoft para el texto con formato enviado a un archivo de disco.

Normalmente, un archivo de disco se abre automáticamente al construir CFile y se cierra durante la destrucción. Las funciones miembro estáticas permiten preguntar el estado de un archivo sin abrirlo.

Para obtener más información sobre el uso de CFile, vea los artículos Archivos en MFC y Control de archivos en la Referencia de la biblioteca en tiempo de ejecución.

Jerarquía de herencia

CObject

CFile

Requisitos

Encabezado: afx.h

CFile::Abort

Cierra el archivo asociado a este objeto y hace que no esté disponible para su lectura o escritura.

virtual void Abort();

Comentarios

Si no ha cerrado el archivo antes de destruir el objeto, el destructor lo cierra automáticamente.

Al controlar excepciones, CFile::Abort difiere de CFile::Close de dos maneras importantes. En primer lugar, la función Abort no inicia una excepción en caso de error, ya que Abort omite los errores. En segundo lugar, Abort no se DECLARA si el archivo no se ha abierto o se ha cerrado anteriormente.

Si has usado new para asignar el objeto CFile en el montón, debes eliminarlo después de cerrar el fichero. Abort establece m_hFile en CFile::hFileNull.

Ejemplo

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

Construye e inicializa un objeto CFile.

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

CFile(
LPCTSTR lpszFileName,
UINT nOpenFlags);

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

Parámetros

hFile
Identificador de un archivo que se va a adjuntar al objeto CFile.

lpszFileName
Ruta completa o relativa de un archivo que se va a adjuntar al objeto CFile.

nOpenFlags
Combinación bit a bit (OR) de las opciones de acceso de archivo relativas al archivo especificado. Consulte la sección Comentarios para ver las opciones posibles.

pTM
Puntero al objeto CAtlTransactionManager

Comentarios

En las cinco tablas siguientes se enumeran las posibles opciones del parámetro nOpenFlags.

Elija solo una de las siguientes opciones de modo de acceso de archivo. El modo de acceso de archivo predeterminado es CFile::modeRead, que es de solo lectura.

Valor	Descripción
`CFile::modeRead`	Solicita únicamente acceso de lectura.
`CFile::modeWrite`	Solicita únicamente acceso de escritura.
`CFile::modeReadWrite`	Solicita acceso de lectura y escritura.

Elija solo una de las siguientes opciones de modo de carácter.

Valor	Descripción
`CFile::typeBinary`	Establece el modo binario (solo se usa en clases derivadas).
`CFile::typeText`	Establece el modo de texto con procesamiento especial para pares de retorno de carro-avance de línea (solo se usa en clases derivadas).
`CFile::typeUnicode`	Establece el modo Unicode (solo se usa en clases derivadas). El texto se escribe en el archivo en formato Unicode cuando la aplicación se basa en una configuración de Unicode. No se escriba ninguna BOM en el archivo.

Elija solo una de las siguientes opciones de modo de uso compartido de archivo. El modo de uso compartido de archivo predeterminado es CFile::shareExclusive, que es exclusivo.

Valor	Descripción
`CFile::shareDenyNone`	No hay restricciones de uso compartido.
`CFile::shareDenyRead`	Deniega el acceso de lectura al resto.
`CFile::shareDenyWrite`	Deniega el acceso de escritura al resto.
`CFile::shareExclusive`	Deniega el acceso de lectura y escritura al resto.

Elija la primera (o ambas) de las siguientes opciones de modo de creación de archivo. El modo de creación de archivo predeterminado es CFile::modeNoTruncate, que solo permite abrir archivos existentes.

Valor	Descripción
`CFile::modeCreate`	Crea un nuevo archivo si no existe ninguno. Si el archivo ya existe, se sobrescribe y se establece inicialmente en una longitud cero.
`CFile::modeNoTruncate`	Crea un nuevo archivo si no existe ninguno; si, por el contrario, el archivo ya existe, se adjunta al objeto `CFile`.

Elija de entre las siguientes opciones de almacenamiento en caché según la descripción. El sistema usa de manera predeterminada un esquema de almacenamiento en caché de uso general que no está disponible como opción.

Valor	Descripción
`CFile::osNoBuffer`	El sistema no usa una memoria caché intermedia para el archivo. Esta opción anula las dos opciones siguientes.
`CFile::osRandomAccess`	La memoria caché de archivos se optimiza para el acceso aleatorio. No use esta opción junto con la opción de examen secuencial.
`CFile::osSequentialScan`	La memoria caché de archivos se optimiza para el acceso secuencial. No use esta opción junto con la opción de acceso aleatorio.
`CFile::osWriteThrough`	Las operaciones de escritura se efectúan sin retraso.

Elija la siguiente opción de seguridad para impedir que el identificador de archivos se herede. Cualquier proceso secundario nuevo puede usar el identificador de archivos de forma predeterminada.

Valor	Descripción
`CFile::modeNoInherit`	Impide que los procesos secundarios puedan usar el identificador de archivos.

El constructor predeterminado inicializa miembros, pero no adjunta un archivo al objeto CFile. Después de usar este constructor, recurra al método CFile::Open para abrir un archivo y adjuntarlo al objeto CFile.

El constructor con un parámetro inicializa miembros y adjunta un archivo existente al objeto CFile.

El constructor con dos parámetros inicializa miembros y trata de abrir el archivo especificado. Si este constructor abre el archivo especificado sin problemas, dicho archivo se adjunta al objeto CFile; de lo contrario, el constructor produce un puntero al objeto CInvalidArgException. Para obtener más información sobre cómo controlar excepciones, vea Excepciones.

Si un objeto CFile abre un archivo especificado correctamente, lo va a cerrar automáticamente cuando se destruya el objeto CFile; de lo contrario, debe cerrarlo expresamente cuando ya no esté adjunto al objeto CFile.

Ejemplo

En el siguiente código se muestra cómo usar un 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

Cierra el archivo asociado a este objeto y hace que no esté disponible para su lectura o escritura.

virtual void Close();

Comentarios

Si no ha cerrado el archivo antes de destruir el objeto, el destructor lo cierra automáticamente.

Si has usado new para asignar el objeto CFile en el montón, debes eliminarlo después de cerrar el fichero. Close establece m_hFile en CFile::hFileNull.

Ejemplo

Vea el ejemplo de CFile::CFile.

CFile::Duplicate

Construye un objeto duplicado CFile para un archivo determinado.

virtual CFile* Duplicate() const;

Valor devuelto

Puntero a un objeto duplicado CFile.

Comentarios

Esta función es equivalente a la función _dup en tiempo de ejecución de C.

CFile::Flush

Obliga a que los datos que quedan en el búfer de archivos se escriban en el archivo.

virtual void Flush();

Comentarios

El uso de Flush no garantiza el vaciado de búferes CArchive. Si usa un archivo, llame primero a CArchive::Flush.

Ejemplo

Vea el ejemplo de CFile::SetFilePath.

CFile::GetFileName

Llame a esta función miembro para recuperar el nombre de un archivo especificado.

virtual CString GetFileName() const;

Valor devuelto

El nombre del archivo.

Comentarios

Por ejemplo, cuando se llama a GetFileName para generar un mensaje para el usuario sobre el archivo c:\windows\write\myfile.wri, se devuelve el nombre de archivo, myfile.wri.

Para devolver toda la ruta de acceso del archivo, incluido el nombre, llame a GetFilePath. Para devolver el título del archivo (myfile), llame a GetFileTitle.

Ejemplo

Este fragmento de código abre el archivo SYSTEM.INI en el directorio WINDOWS. Si se encuentra, el ejemplo imprime el nombre, la ruta de acceso y el título, como se muestra en la salida:

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

Llame a esta función miembro para recuperar la ruta de acceso completa de un archivo especificado.

virtual CString GetFilePath() const;

Valor devuelto

Ruta de acceso completa del archivo especificado.

Comentarios

Por ejemplo, cuando se llama a GetFilePath para generar un mensaje para el usuario sobre el archivo c:\windows\write\myfile.wri, se devuelve la ruta de acceso del archivo, c:\windows\write\myfile.wri.

Para devolver solo el nombre del archivo (myfile.wri), llame a GetFileName. Para devolver el título del archivo (myfile), llame a GetFileTitle.

Ejemplo

Vea el ejemplo de GetFileName.

CFile::GetFileTitle

Llame a esta función miembro para recuperar el título del archivo (el nombre para mostrar).

virtual CString GetFileTitle() const;

Valor devuelto

Título del archivo subyacente.

Comentarios

Este método llama a GetFileTitle para recuperar el título del archivo. Si se ejecuta correctamente, el método devuelve la cadena que el sistema usaría para mostrar el nombre de archivo al usuario. De lo contrario, el método llama a PathFindFileName para recuperar el nombre de archivo (incluida la extensión de archivo) del archivo subyacente. Esto significa que la extensión de archivo no siempre se incluye en la cadena de título de archivo devuelta. Para obtener más información, vea GetFileTitle y PathFindFileName en Windows SDK.

Para devolver toda la ruta de acceso del archivo, incluido el nombre, llame a GetFilePath. Para devolver solo el nombre del archivo, llame a GetFileName.

Ejemplo

Vea el ejemplo de GetFileName.

CFile::GetLength

Obtiene la longitud lógica actual del archivo en bytes.

virtual ULONGLONG GetLength() const;

Valor devuelto

Longitud del archivo.

Ejemplo

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

Obtiene el valor actual del puntero de archivo, que se puede usar en llamadas posteriores a Seek.

virtual ULONGLONG GetPosition() const;

Valor devuelto

Puntero de archivo.

Ejemplo

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

Este método recupera información de estado relacionada con una instancia de objeto CFile determinada o una ruta de acceso de archivo concreta.

BOOL GetStatus(CFileStatus& rStatus) const;

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

Parámetros

rStatus
Referencia a una estructura CFileStatus proporcionada por el usuario que va a recibir la información de estado. El estructura CFileStatus tiene los siguientes campos:

CTime m_ctime Fecha y hora de creación del archivo.
CTime m_mtime Fecha y hora en que el archivo se modificó por última vez.
CTime m_atime Fecha y hora del último acceso al archivo para su lectura.
ULONGLONG m_size Tamaño lógico del archivo en bytes, según la notificación del comando DIR.
BYTE m_attribute Byte de atributo del archivo.
char m_szFullName[_MAX_PATH] Nombre de archivo absoluto en el juego de caracteres de Windows.

lpszFileName
Cadena del juego de caracteres de Windows que es la ruta de acceso al archivo deseado. La ruta de acceso puede ser relativa o absoluta, o puede contener un nombre de ruta de acceso de red.

pTM
Puntero al objeto CAtlTransactionManager

Valor devuelto

TRUE si la información de estado del archivo especificado se obtiene correctamente; de lo contrario, FALSE.

Comentarios

La versión no estática de GetStatus recupera información de estado del archivo abierto asociado al objeto CFile especificado. La versión estática de GetStatus obtiene el estado del archivo de una ruta de acceso de archivo determinada sin abrir realmente el archivo. Esta versión es útil para comprobar la existencia y los derechos de acceso de un archivo.

El miembro m_attribute de la estructura CFileStatus hace referencia al conjunto de atributos de archivo. La clase CFile proporciona el tipo de enumeración Attribute para que los atributos de archivo se puedan especificar simbólicamente:

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

Ejemplo

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

Determina la presencia de un identificador de archivo válido para el objeto CFile.

static AFX_DATA const HANDLE hFileNull;

Comentarios

Esta constante se usa para determinar si el objeto CFile tiene un identificador de archivo válido.

En el ejemplo siguiente se muestra esta operación:

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

CFile::LockRange

Bloquea un intervalo de bytes en un archivo abierto, lo que inicia una excepción si el archivo ya está bloqueado.

virtual void LockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parámetros

dwPos
Desplazamiento de bytes del inicio del intervalo de bytes que se va a bloquear.

dwCount
Número de bytes del intervalo que se va a bloquear.

Comentarios

El bloqueo de bytes en un archivo impide que otros procesos obtengan acceso a dichos bytes. Puede bloquear más de una región de un archivo, pero no se permiten regiones superpuestas.

Al desbloquear la región mediante la función miembro UnlockRange, el intervalo de bytes debe corresponder exactamente a la región que se ha bloqueado anteriormente. La función LockRange no combina regiones adyacentes. Si dos regiones bloqueadas son adyacentes, debe desbloquear cada región por separado.

Nota:

Esta función no está disponible para la clase derivada de CMemFile.

Ejemplo

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

Contiene el identificador de archivo del sistema operativo de un archivo abierto.

HANDLE m_hFile;

Comentarios

m_hFile es una variable pública de tipo UINT. Contiene CFile::hFileNull, un indicador de archivo vacío independiente del sistema operativo, si no se ha asignado el identificador.

No se recomienda el uso de m_hFile, ya que el significado del miembro depende de la clase derivada. m_hFile se ha convertido en miembro público por comodidad a la hora de permitir el uso no polimórfico de la clase.

CFile::m_pTM

Un puntero a un objeto CAtlTransactionManager.

CAtlTransactionManager* m_pTM;

Comentarios

CFile::Open

Con sobrecarga. Open está diseñado para su uso con el constructor predeterminado CFile.

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

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

Parámetros

lpszFileName
Cadena que contiene la ruta de acceso al archivo deseado. La ruta de acceso puede ser relativa, absoluta o un nombre de red (UNC).

nOpenFlags
UINT que define el modo de acceso y uso compartido del archivo. Especifica la acción que se va a realizar al abrir el archivo. Puede combinar opciones mediante el operador OR bit a bit (|). Se requieren un permiso de acceso y una opción de recurso compartido; los modos modeCreate y modeNoInherit son opcionales. Vea el constructor CFile para obtener una lista de opciones de modo.

pError
Puntero a un objeto de excepción de archivo existente que va a recibir el estado de una operación con error.

pTM
Puntero al objeto CAtlTransactionManager

Valor devuelto

Distinto de cero si la apertura se ha realizado correctamente; de lo contrario, 0. El parámetro pError solo es significativo si se devuelve 0.

Comentarios

Las dos funciones Open son métodos "seguros" para abrir un archivo, donde un error es una condición normal y esperada.

Mientras el constructor CFile inicia una excepción en una condición de error, Open devuelve FALSE en las condiciones de error. Open, sin embargo, puede inicializar un objeto CFileException para describir el error. Si no proporciona el parámetro pError, o si pasa NULL para pError, Open devuelve FALSE y no inicia CFileException. Si pasa un puntero a una excepción CFileException existente y Open detecta un error, la función la rellena con información que describe ese error. Open no inicia ninguna excepción en ningún caso.

En la siguiente tabla se describen los posibles resultados de Open.

`pError`	Error detectado	Valor devuelto	Contenido de CFileException
NULL	No	TRUE	N/D
ptr to `CFileException`	No	TRUE	sin cambios
NULL	Sí	FALSE	N/D
ptr to `CFileException`	Sí	FALSE	inicializado para describir error

Ejemplo

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

Use este operador para pasar un identificador de un objeto CFile a funciones como ReadFileEx y GetFileTime que esperan HANDLE.

operator HANDLE() const;

CFile::Read

Lee datos en un búfer del archivo asociado al objeto CFile.

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

Parámetros

lpBuf
Puntero al búfer proporcionado por el usuario que va a recibir los datos leídos del archivo.

nCount
Número máximo de bytes que se van a leer del archivo. En el caso de los archivos en modo de texto, los pares de retorno de carro-avance de línea se cuentan como caracteres únicos.

Valor devuelto

Número de bytes que se transfieren al búfer. En todas las clases CFile, el valor devuelto puede ser menor que nCount si se ha alcanzado el final del archivo.

Ejemplo

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

Para obtener otro ejemplo, vea CFile::Open.

CFile::Remove

Esta función estática elimina el archivo especificado por la ruta de acceso.

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

Parámetros

lpszFileName
Cadena que es la ruta de acceso al archivo deseado. La ruta de acceso puede ser relativa o absoluta, y puede contener un nombre de red.

pTM
Puntero al objeto CAtlTransactionManager

Comentarios

Remove no quita un directorio.

La función miembro Remove inicia una excepción si el archivo conectado está abierto o si no se puede quitar. Esta función es equivalente al comando DEL.

Ejemplo

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

Esta función estática cambia el nombre del archivo especificado.

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

Parámetros

lpszOldName
Ruta de acceso antigua.

lpszNewName
Nueva ruta de acceso.

pTM
Puntero al objeto CAtlTransactionManager

Comentarios

Los nombres de los directorios no se pueden cambiar. Esta función es equivalente al comando REN.

Ejemplo

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

Cambia la posición del puntero de archivo en un archivo abierto.

virtual ULONGLONG Seek(
LONGLONG lOff,
UINT nFrom);

Parámetros

lOff
Número de bytes para mover el puntero de archivo. Los valores positivos mueven el puntero de archivo hacia el final del archivo; los negativos mueven el puntero de archivo hacia el inicio del archivo.

nFrom
Posición desde la que se va a buscar. Consulte la sección Comentarios para ver los valores posibles.

Valor devuelto

Posición del puntero de archivo si el método se ha ejecutado correctamente; de lo contrario, el valor devuelto no está definido y se inicia un puntero a una excepción CFileException.

Comentarios

En la siguiente tabla se muestran los posibles valores del parámetro nFrom.

Valor	Descripción
`CFile::begin`	Se busca desde el principio del archivo.
`CFile::current`	Se busca desde la ubicación actual del puntero de archivo.
`CFile::end`	Se busca desde el final del archivo.

Cuando se abre un archivo, el puntero de archivo se coloca en 0, el inicio del archivo.

Puede establecer el puntero de archivo en una posición más allá del final de un archivo. Si lo hace, el tamaño del archivo no aumenta hasta que se escribe en él.

El controlador de excepciones de este método debe eliminar el objeto de excepción después de procesar la excepción.

Ejemplo

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

Establece el valor del puntero de archivo en el principio del archivo.

void SeekToBegin();

Comentarios

SeekToBegin() equivale a Seek( 0L, CFile::begin ).

Ejemplo

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

CFile::SeekToEnd

Establece el valor del puntero de archivo en el final lógico del archivo.

ULONGLONG SeekToEnd();

Valor devuelto

La longitud del archivo en bytes.

Comentarios

SeekToEnd() equivale a CFile::Seek( 0L, CFile::end ).

Ejemplo

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

CFile::SetFilePath

Llame a esta función para especificar la ruta de acceso del archivo. Por ejemplo, si la ruta de acceso de un archivo no está disponible cuando se construye un objeto CFile, llame a SetFilePath para proporcionarla.

virtual void SetFilePath(LPCTSTR lpszNewName);

Parámetros

lpszNewName
Puntero a una cadena que especifica la nueva ruta de acceso.

Comentarios

Nota:

SetFilePath no abre el archivo ni lo crea; simplemente asocia el objeto CFile con un nombre de ruta de acceso, que luego se puede usar.

Ejemplo

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

Llame a esta función para cambiar la longitud del archivo.

virtual void SetLength(ULONGLONG dwNewLen);

Parámetros

dwNewLen
Longitud deseada del archivo en bytes. Este valor puede ser mayor o menor que la longitud actual del archivo. El archivo se amplía o se trunca según corresponda.

Comentarios

Nota:

Con CMemFile, esta función podría iniciar un objeto CMemoryException.

Ejemplo

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

CFile::SetStatus

Establece el estado del archivo asociado a esta ubicación de archivo.

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

Parámetros

lpszFileName
Cadena que es la ruta de acceso al archivo deseado. La ruta de acceso puede ser relativa o absoluta, y puede contener un nombre de red.

status
Búfer que contiene la nueva información de estado. Llame a la función miembro GetStatus para rellenar previamente la estructura CFileStatus con valores actuales; luego realice cambios según sea necesario. Si un valor es 0, el elemento de estado correspondiente no se actualiza. Vea la función miembro GetStatus para obtener una descripción de la estructura CFileStatus.

pTM
Puntero al objeto CAtlTransactionManager

Comentarios

Para establecer la hora, modifique el campo m_mtime de status.

Si se realiza una llamada a SetStatus en un intento de cambiar solo los atributos del archivo y el miembro m_mtime de la estructura de estado del archivo es distinto de cero, los atributos también pueden verse afectados (el cambio de la marca de tiempo puede tener efectos secundarios en los atributos). Si solo quiere cambiar los atributos del archivo, primero establezca el miembro m_mtime de la estructura de estado del archivo en cero y luego realice una llamada a SetStatus.

Ejemplo

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

CFile::UnlockRange

Desbloquea un intervalo de bytes en un archivo abierto.

virtual void UnlockRange(
    ULONGLONG dwPos,
    ULONGLONG dwCount);

Parámetros

dwPos
Desplazamiento de bytes del inicio del intervalo de bytes que se va a desbloquear.

dwCount
Número de bytes del intervalo que se va a desbloquear.

Comentarios

Vea la descripción de la función miembro LockRange para obtener detalles.

Nota:

Esta función no está disponible para la clase derivada de CMemFile.

Ejemplo

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

Escribe datos de un búfer en el archivo asociado al objeto CFile.

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

Parámetros

lpBuf
Puntero al búfer proporcionado por el usuario que contiene los datos que se van a escribir en el archivo.

nCount
Número de bytes que se van a transferir desde el búfer. En el caso de los archivos en modo de texto, los pares de retorno de carro-avance de línea se cuentan como caracteres únicos.

Comentarios

Write inicia una excepción en respuesta a varias condiciones, incluida la condición de disco lleno.

Ejemplo

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

Vea también los ejemplos de CFile::CFile y CFile::Open.

Consulte también

Ejemplo DRAWCLI de MFC
CObject (clase)
Gráfico de jerarquías
CStdioFile (clase)
CMemFile (clase)