ot::io
class RandomAccessFile

This class also implements the interfaces defined by the DataInput and DataOutput classes which provide the capability to read and write integer and string data in a cross-platform compatible manner.

When a RandomAccessFile is created, a connection is established with an open file in the file system. The open file is represented internally using a FileDescriptor which ensures that the file is closed when the RandomAccessFile is destroyed. The file can also be closed using the close() method.

The following example opens a file in read-only mode and reads a 4-byte long integer from the 11th-14th bytes:-

    try
    {
        RefPtr<RandomAccessFile> rpFile = 
            new RandomAccessFile("random.txt", RandomAccessFile::Read);
        rpFile->seek(10);              // set offset for next i/o operation
        long val = rpFile->readLong(); // read 4-byte long integer from file
    }
    catch(IOException& e)
    {
        cerr << e.toString() << endl;		
    }

Multi-threaded considerations:

For optimum performance, file operations are not synchronized for safe access from multiple concurrent threads. A RandomAccessFile may be shared between multiple threads, but the application must provide adequate synchronization to ensure that multiple threads do not attempt to alter the file's state simultaneously.

Since:

OpenTop 1.4

RandomAccessFile

 RandomAccessFile(const File& file,
                  Mode mode)

Constructs a RandomAccessFile by opening a connection to the file with the abstract pathname denoted by file. Read or write access permissions are specified using the mode parameter.

If the file does not currently exist on the file system then a file with the abstract pathname will be created if writable access is requested (mode is Read_Write or Read_Write_Sync). If Read access is requested and the file does not exist a FileNotFoundException will be thrown.

Parameters:

file - the abstract pathname of the file to open.
mode - the access mode.

Exceptions:

FileNotFoundException - if a file with the specified name does not exist on the file system and Read access has been requested.
IOException - if the specified file could not be opened. This includes the case where file refers to a directory instead of a normal file.

RandomAccessFile

 RandomAccessFile(const String& name,
                  Mode mode)

Constructs a RandomAccessFile by opening a connection to the file with the abstract pathname denoted by name. Read or write access permissions are specified using the mode parameter.

If the file does not currently exist on the file system then a file with the abstract pathname will be created if writable access is requested (mode is Read_Write or Read_Write_Sync). If Read access is requested and the file does not exist a FileNotFoundException will be thrown.

Parameters:

name - the name of the file to open.
mode - the access mode.

Exceptions:

FileNotFoundException - if a file with the specified name does not exist on the file system and Read access has been requested.
IOException - if the specified file could not be opened. This includes the case where file refers to a directory instead of a normal file.

close

void close()

Closes the random access file. Once a RandomAccessFile is closed, all system resources associated with the file are released, preventing any further input or output operations. Once closed, a RandomAccessFile cannot be re-opened and further calls to close() have no effect.

Exceptions:

IOException - if an I/O error occurs.

See also:

isClosed()

getFD

RefPtr< FileDescriptor > getFD() const

Returns a FileDescriptor for the open file connected to this file. A null RefPtr is returned if this file has been closed.

Returns:

a RefPtr to the FileDescriptor for this file; a null RefPtr when the file is closed.

getFilePointer

Int64Type getFilePointer() const

Returns the current value of the file pointer for this file.

Returns:

the current file pointer.

Exceptions:

IOException - if an I/O error occurs such as when the file is closed or was not opened for write operations.

See also:

seek()

isClosed

bool isClosed()

Tests if this file has been closed.

Returns:

true if this file is closed; false otherwise.

See also:

close()

length

Int64Type length() const

Returns the current length of the file.

Returns:

the current file length (in bytes).

Exceptions:

IOException - if an I/O error occurs such as when the file is closed or was not opened for write operations.

See also:

setLength()

read

long read(Byte* pBuffer,
          size_t bufLen)

Reads up to bufLen bytes into the supplied buffer.

Parameters:

pBuffer - A pointer to the buffer into which the bytes will be copied. This must be capable of holding at least bufLen bytes.
bufLen - The maximum number of bytes to read into the passed buffer. If this exceeds the maximum value that can be represented by a long integer, it is reduced to a value that can be so represented.

Returns:

The number of bytes read or RandomAccessFile::EndOfFile if the end of the file has been reached.

Exceptions:

IllegalArgumentException - if bufLen is zero
NullPointerException - if pBuffer is null
IOException - if an error occurs while reading from the file

readFully

virtual void readFully(Byte* pBuffer,
                       size_t bufLen)

Reads exactly bufLen bytes from the current position in the file. If EndOfFile is reached before bufLen bytes have been read an EOFException is thrown.

Parameters:

pBuffer - A pointer to the buffer into which the bytes will be copied. This must be capable of holding at least bufLen bytes.
bufLen - The required number of bytes to read into the passed buffer.

Exceptions:

EOFException - if EndOfFile was reached before sufficient bytes were read. In this case the file pointer will be left pointing at the end of the file on exit from this function.
IllegalArgumentException - if bufLen is zero
NullPointerException - if pBuffer is null
IOException - if an I/O error occurs.

seek

void seek(Int64Type pos)

Sets the file pointer for this file to the given position, which is an offset (in bytes) from the start of the file. Subsequent read() or write() operations will read/write data from/to this location. If pos is greater than the current length of the file, the file will not be extended until data is written to the new location via a write() call.

Parameters:

pos - the new file pointer value

Exceptions:

IOException - if an I/O error occurs.

See also:

getFilePointer()

setLength

void setLength(Int64Type newLength)

Sets the length of this file, either by extending or truncating it. If the current length of the file is greater than newLength then the file will be truncated. In this case, if the file pointer is currently greater than newLength then it will be reset to equal newLength.

If the current length of the file is less than newLength then the file will be extended. On some platforms (mainly UNIX), the contents of the extended portion of the file will be initialized to zeros. On others (notably Windows), the contents of the extended portion of the file is undefined.

Parameters:

newLength - The desired length of the file (in bytes)

Exceptions:

IOException - if an I/O error occurs or the file is closed.

skipBytes

virtual size_t skipBytes(size_t n)

Repositions the file pointer forward n bytes. This function increments the file pointer as if a read operation was performed, but without physically transferring any data.

Returns:

The number of bytes skipped, which will be equal to n unless the end of file was reached first.

Exceptions:

IOException - if an I/O error occurs.

write

virtual void write(const Byte* pBuffer,
                   size_t bufLen)

Writes an array of bytes at the current file position. The file pointer will be incremented by bufLen. The file length will be extended to accommodate the new bytes if necessary.

Parameters:

pBuffer - pointer to the start of an array of bytes to be written
bufLen - length of the byte array

Exceptions:

NullPointerException - if pBuffer is null.
IOException - if an I/O error occurs such as when the file is closed or was not opened for write operations.