Clase CAtlFile

Esta clase proporciona un contenedor fino en torno a la API de control de archivos de Windows.

Importante

Esta clase y sus miembros no se pueden usar en las aplicaciones que se ejecutan en Windows Runtime.

Sintaxis

class CAtlFile : public CHandle

Miembros

Constructores públicos

Nombre	Descripción
CAtlFile::CAtlFile	Constructor .

Métodos públicos

Nombre	Descripción
CAtlFile::Create	Llame a este método para crear o abrir un archivo.
CAtlFile::Flush	Llame a este método para borrar los búferes del archivo y hacer que todos los datos almacenados en búfer se escriban en el archivo.
CAtlFile::GetOverlappedResult	Llame a este método para obtener los resultados de una operación superpuesta en el archivo.
CAtlFile::GetPosition	Llame a este método para obtener la posición actual del puntero del archivo desde el archivo.
CAtlFile::GetSize	Llame a este método para obtener el tamaño del archivo en bytes.
CAtlFile::LockRange	Llame a este método para bloquear una región del archivo para evitar que otros procesos accedan a ella.
CAtlFile::Read	Llame a este método para leer datos de un archivo a partir de la posición indicada por el puntero del archivo.
CAtlFile::Seek	Llame a este método para mover el puntero del archivo perteneciente al archivo.
CAtlFile::SetSize	Llame a este método para establecer el tamaño del archivo.
CAtlFile::UnlockRange	Llame a este método para desbloquear una región del archivo.
CAtlFile::Write	Llame a este método para escribir datos en el archivo a partir de la posición indicada por el puntero del archivo.

Miembros de datos protegidos

Nombre	Descripción
CAtlFile::m_pTM	Puntero al objeto CAtlTransactionManager

Comentarios

Use esta clase cuando las necesidades de control de archivos sean relativamente sencillas, pero se requiere más abstracción que la API de Windows, sin incluir las dependencias de MFC.

Jerarquía de herencia

CHandle

CAtlFile

Requisitos

Encabezado: atlfile.h

CAtlFile::CAtlFile

Constructor .

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

Parámetros

file
Objeto de archivo.

hFile
Manipulador de archivo.

pTM
Puntero al objeto CAtlTransactionManager

Comentarios

El constructor de copia transfiere la propiedad del manipulador de archivo del objeto original CAtlFile al objeto recién construido.

CAtlFile::Create

Llame a este método para crear o abrir un archivo.

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

Parámetros

szFilename
Nombre de archivo.

dwDesiredAccess
Acceso deseado. Consulte dwDesiredAccess en CreateFile en Windows SDK.

dwShareMode
Modo de recurso compartido. Consulte dwShareMode en CreateFile.

dwCreationDisposition
Disposición de creación. Consulte dwCreationDisposition en CreateFile.

dwFlagsAndAttributes
Marcas y atributos. Consulte dwFlagsAndAttributes en CreateFile.

lpsa
Atributos de seguridad. Consulte lpSecurityAttributes en CreateFile.

hTemplateFile
Archivo de plantilla. Consulte hTemplateFile en CreateFile.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Llama a CreateFile para crear o abrir el archivo.

CAtlFile::Flush

Llame a este método para borrar los búferes del archivo y hacer que todos los datos almacenados en búfer se escriban en el archivo.

HRESULT Flush() throw();

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Llama a FlushFileBuffers para vaciar los datos almacenados en búfer en el archivo.

CAtlFile::GetOverlappedResult

Llame a este método para obtener los resultados de una operación superpuesta en el archivo.

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

Parámetros

pOverlapped
Estructura superpuesta. Consulte lpOverlapped en GetOverlappedResult en Windows SDK.

dwBytesTransferred
Bytes transferidos. Consulte lpNumberOfBytesTransferred en GetOverlappedResult.

bWait
Opción de espera. Consulte bWait en GetOverlappedResult.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Llama a GetOverlappedResult para obtener los resultados de una operación superpuesta en el archivo.

CAtlFile::GetPosition

Llame a este método para obtener la posición actual del puntero del archivo.

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

Parámetros

nPos
Posición, en bytes.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Llama a SetFilePointer para obtener la posición actual del puntero del archivo.

CAtlFile::GetSize

Llame a este método para obtener el tamaño del archivo en bytes.

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

Parámetros

nLen
El número de bytes en el archivo.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Llama a GetFileSize para obtener el tamaño en bytes del archivo.

CAtlFile::LockRange

Llame a este método para bloquear una región del archivo para evitar que otros procesos accedan a ella.

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

Parámetros

nPos
Posición en el archivo donde debe comenzar el bloqueo.

nCount
Longitud del intervalo de bytes que se va a bloquear.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Llama a LockFile para bloquear una región en el archivo. 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 una región mediante CAtlFile::UnlockRange, el intervalo de bytes debe corresponder exactamente a la región que se ha bloqueado anteriormente. LockRange no combina regiones adyacentes; si dos regiones bloqueadas son adyacentes, debe desbloquearlas por separado.

CAtlFile::m_pTM

Un puntero a un objeto CAtlTransactionManager.

CAtlTransactionManager* m_pTM;

Comentarios

CAtlFile::Read

Llame a este método para leer datos de un archivo a partir de la posición indicada por el puntero del archivo.

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

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

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

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

Parámetros

pBuffer
Puntero al búfer que recibirá los datos leídos del archivo.

nBufSize
El tamaño del búfer en bytes.

nBytesRead
El número de bytes leídos.

pOverlapped
Estructura superpuesta. Consulte lpOverlapped en ReadFile en Windows SDK.

pfnCompletionRoutine
Rutina de finalización. Consulte lpCompletionRoutine en ReadFileEx en Windows SDK.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Los tres primeros formularios llaman a ReadFile y el último llama a ReadFileEx para leer datos del archivo. Use CAtlFile::Seek para mover el puntero del archivo.

CAtlFile::Seek

Llame a este método para mover el puntero del archivo perteneciente al archivo.

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

Parámetros

nOffset
Desplazamiento desde el punto inicial proporcionado por dwFrom.

dwFrom
Punto de partida (FILE_BEGIN, FILE_CURRENT o FILE_END).

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Llama a SetFilePointer para mover el puntero del archivo.

CAtlFile::SetSize

Llame a este método para establecer el tamaño del archivo.

HRESULT SetSize(ULONGLONG nNewLen) throw();

Parámetros

nNewLen
Nueva longitud del archivo, en bytes.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Llama a SetFilePointer y SetEndOfFile para establecer el tamaño del archivo. A cambio, el puntero del archivo se coloca al final del archivo.

CAtlFile::UnlockRange

Llame a este método para desbloquear una región del archivo.

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

Parámetros

nPos
Posición en el archivo donde debe comenzar el desbloqueo.

nCount
Longitud del intervalo de bytes que se va a desbloquear.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Llama a UnlockFile para desbloquear una región del archivo.

CAtlFile::Write

Llame a este método para escribir datos en el archivo a partir de la posición indicada por el puntero del archivo.

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

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

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

Parámetros

pBuffer
Búfer que contiene los datos que se van a escribir en el archivo.

nBufSize
Número de bytes que se van a transferir desde el búfer.

pOverlapped
Estructura superpuesta. Consulte lpOverlapped en WriteFile en Windows SDK.

pfnCompletionRoutine
Rutina de finalización. Consulte lpCompletionRoutine en WriteFileEx en Windows SDK.

pnBytesWritten
Bytes escritos.

Valor devuelto

Devuelve S_OK si es correcto o un error HRESULT en caso de error.

Comentarios

Los tres primeros formularios llaman a WriteFile y el último llama a WriteFileEx para escribir datos en el archivo. Use CAtlFile::Seek para mover el puntero del archivo.

Consulte también

Ejemplo de marquesina
Información general sobre la clase
CHandle (clase)