Clase wxFile
wxFile realiza la E/S de un archivo.
Esta es una clase muy pequeña diseñada para minimizar la sobrecarga de su uso - de hecho, casi no hay sobrecarga en absoluto, pero su uso le trae la comprobación automática de errores y oculta las diferencias entre plataformas y compiladores. wxFile también cierra automáticamente el archivo en su destructor para que no se olvide de hacerlo. wxFile es una envoltura alrededor de descriptor de archivo. - ver también wxFFile para una envoltura alrededor de la estructura FILE.
wxFileOffset es utilizado por las funciones wxFile que requieren offsets como parámetro o los devuelven. Si la plataforma lo soporta, wxFileOffset es un typedef para un entero nativo de 64 bits, de lo contrario se utiliza un entero de 32 bits para wxFileOffset.
Tipos
OpenMode
enum OpenMode { read , write , read_write , write_append , write_excl }
La enumeración OpenMode define los diferentes modos para abrir un archivo con wxFile.
También se utiliza con la función wxFile::Access.
- read
- Abrir el archivo para lectura o probar si se puede abrir para lectura con Access()
- write
- Abrir archivo para escritura borrando el contenido del archivo si ya existe o probar si puede abrirse para escritura con Access().
- read_write
- Abrir archivo para lectura y escritura; no puede usarse con Access().
- write_append
Abrir archivo para añadir: el archivo se abre para escritura, pero el contenido antiguo del archivo no se borra y el puntero del archivo se coloca inicialmente al final del archivo; no puede utilizarse con Access().
Es lo mismo que OpenMode::write si el fichero no existe.
- write_excl
Abre el archivo de forma segura para la escritura (Utiliza O_EXCL | O_CREAT).
Fallará si el archivo ya existe, de lo contrario lo creará y abrirá atómicamente. Útil para abrir archivos temporales sin ser vulnerable a exploits de carrera.
anónimo
enum { fd_invalid = -1 , fd_stdin , fd_stdout , fd_stderr }
Descriptores de archivo estándar.
Funciones miembro
wxFile()
wxFile::wxFile()
Constructor por defecto.
wxFile()
wxFile::wxFile( const wxString & filename, wxFile::OpenMode mode = wxFile::read )
Abre un archivo con un nombre de archivo.
Parámetros
- filename
- El nombre del archivo.
- mode
- El modo en el que se abrirá el archivo.
Advertencia
Se debería utilizar IsOpened() para verificar que el constructor ha tenido éxito.
wxFile()
wxFile::wxFile(int fd)
Asocia el archivo con el descriptor de archivo dado, que ya ha sido abierto.
Ver Attach() para la lista de descriptores predefinidos.
Parámetros
- fd
- Un descriptor de archivo existente.
~wxFile()
wxFile::~wxFile()
El destructor cerrará el archivo.
Nota: Este destructor no es virtual por lo que no se debe usar wxFile polimórficamente.
Access()
static bool wxFile::Access( const wxString & name, wxFile::OpenMode mode )
Esta función verifica si podemos acceder al fichero dado en el modo especificado.
Sólo los valores de wxFile::read o wxFile::write tienen sentido aquí.
Attach()
void wxFile::Attach(int fd)
Adjunta un descriptor de fichero existente al objeto wxFile.
Ejemplos de descriptores de fichero predefinidos son 0, 1 y 2 que corresponden a stdin, stdout y stderr (y tienen nombres simbólicos de wxFile::fd_stdin, wxFile::fd_stdout y wxFile::fd_stderr).
El descriptor debe estar ya abierto y será cerrado por el objeto wxFile.
ClearLastError()
void wxFile::ClearLastError()
Restablece el código de error.
GetLastError() devolverá 0 hasta que se produzca el siguiente error.
Close()
bool wxFile::Close()
Cierra el fichero.
Create()
bool wxFile::Create( const wxString & filename, bool overwrite = false, int access = wxS_DEFAULT )
Crea un archivo para escribir.
Si el archivo ya existe, establecer overwrite a true asegurará que se sobrescriba.
access puede ser una combinación OR de los valores de la enumeración wxPosixPermissions.
Detach()
int wxFile::Detach()
Devuelve un descriptor de archivo del objeto wxFile - la persona que llama es responsable de cerrar el archivo si este descriptor está abierto.
IsOpened() devolverá false después de llamar a Detach().
Valor de retorno
El descriptor de fichero (esto es nuevo desde wxWidgets 3.0.0, en las versiones anteriores este método no devolvía nada).
Eof()
bool wxFile::Eof() const
Devuelve true si se ha alcanzado el final del fichero.
Hay que tener en cuenta que el comportamiento de la clase basada en punteros de fichero wxFFile es diferente, ya que wxFFile::Eof() devolverá aquí true sólo si se ha intentado leer más allá del último byte del fichero, mientras que wxFile::Eof() devolverá true incluso antes de que se haga tal intento si el puntero del fichero está en la última posición del fichero.
Nótese también que esta función no funciona en descriptores de fichero no buscables (los ejemplos incluyen tuberías, terminales y sockets bajo Unix) y un intento de utilizarla resultará en un mensaje de error.
Por lo tanto, para leer todo el fichero en memoria, debe escribir un bucle que utilice Read() repetidamente y compruebe su condición de retorno en lugar de utilizar Eof() ya que esto no funcionará para ficheros especiales bajo Unix.
Exists()
static bool wxFile::Exists(const wxString & filename)
Devuelve true si el nombre dado especifica un archivo regular existente (no un directorio o un enlace).
fd()
int wxFile::fd() const
Devuelve el descriptor de fichero asociado al fichero.
Flush()
bool wxFile::Flush()
Vacía el descriptor de fichero.
Hay que tener en cuenta que Flush() no está implementada en algunos compiladores de Windows debido a la falta de una función fsync, lo que reduce la utilidad de esta función (aún puede ser llamada pero no hará nada en compiladores no soportados).
GetKind()
wxFileKind wxFile::GetKind() const
Devuelve el tipo de archivo.
GetLastError()
int wxFile::GetLastError() const
Devuelve el código de error de la última operación fallida.
El código de error depende del sistema y corresponde al valor de la variable estándar errno cuando se produjo el último error.
Obsérvese que sólo los accesores simples como IsOpened() y Eof() (y este método en sí) no modifican el último valor de error, todos los demás métodos pueden potencialmente cambiarlo si se produce un error, incluyendo los const como Tell() o Length().
IsOpened()
bool wxFile::IsOpened() const
Devuelve true si el archivo ha sido abierto.
Length()
wxFileOffset wxFile::Length() const
Devuelve la longitud del archivo.
Open()
bool wxFile::Open( const wxString & filename, wxFile::OpenMode mode = wxFile::read, int access = wxS_DEFAULT )
Abre el archivo, devolviendo true si tiene éxito.
Parámetros
- filename
- El nombre del archivo.
- mode
- El modo en el que se abrirá el archivo.
- access
- Una combinación OR de valores de la enumeración wxPosixPermissions.
Read()
ssize_t wxFile::Read( void * buffer, size_t count )
Lee del archivo a un búfer de memoria.
Parámetros
- buffer
- Buffer a escribir.
- count
- Bytes a leer.
Valor de retorno
El número de bytes leídos, o el símbolo wxInvalidOffset.
ReadAll()
Lee todo el contenido del archivo en una cadena.
Desde wxWidgets 3.1.1 este método también funciona para ficheros no buscables.
Parámetros
- str
- Puntero no nulo a una cadena en la que leer los datos.
- conv
- Objeto de conversión a usar en la construcción Unicode; por defecto supone que el contenido del archivo está codificado en UTF-8 pero vuelve a la codificación locale actual (o Latin-1 si también es UTF-8) si no lo está.
Valor de retorno
true si el archivo se ha leído correctamente, false en caso contrario.
Seek()
wxFileOffset wxFile::Seek( wxFileOffset ofs, wxSeekMode mode = wxFromStart )
Busca la posición especificada.
Parámetros
- ofs
- Desplazamiento a buscar.
- mode
- Uno de wxFromStart, wxFromEnd, wxFromCurrent.
Valor de retorno
La posición actual alcanzada, o wxInvalidOffset en caso de error.
SeekEnd()
wxFileOffset wxFile::SeekEnd(wxFileOffset ofs = 0)
Mueve el puntero del archivo al número especificado de bytes relativos al final del archivo.
Por ejemplo, SeekEnd(-5) posicionaría el puntero 5 bytes antes del final.
Parámetros
- ofs
- Número de bytes antes del final del archivo.
Valor de retorno
La posición actual alcanzada, o wxInvalidOffset en caso de error.
Tell()
wxFileOffset wxFile::Tell() const
Devuelve la posición actual o wxInvalidOffset si el fichero no está abierto o si se ha producido otro error.
Write()
size_t wxFile::Write( const void * buffer, size_t count )
Escribe datos en el archivo (descriptor).
Parámetros
- buffer
- Buffer desde el que leer los datos.
- count
- Número de bytes a escribir.
Valor de retorno
El número de bytes escritos.
Write()
Escribe el contenido de la cadena en el archivo, devuelve true en caso de éxito.
El segundo argumento sólo tiene sentido en la versión Unicode de wxWidgets cuando se utiliza conv para convertir s a una representación multibyte.
Hay que tener en cuenta que este método sólo funciona con cadenas terminadas en NUL, si desea escribir datos con NULs incrustados en el archivo se debe utilizar la otra sobrecarga Write().