ADTF  3.18.2
cFile

File class. More...

Public Types

enum  tOpenMode {
  OM_Read = 0x0001 , OM_Write = 0x0002 , OM_Append = 0x0004 , OM_ReadWrite = 0x0008 ,
  OM_SharedRead = 0x0100 , OM_SharedWrite = 0x0200 , OM_SequentialAccess = 0x0400 , OM_TemporaryFile = 0x0800 ,
  OM_ShortLived = 0x1000 , OM_TextMode = 0x2000 , OM_WriteThrough = 0x4000 , OM_DisableFileSystemCache = 0x8000
}
 Several flags to open files. Can be combined with bitwise or. More...
 
enum  tFilePosRef { FP_Begin = 0 , FP_Current = 1 , FP_End = 2 }
 File position reference. More...
 

Public Member Functions

 cFile ()
 Constructor.
 
virtual ~cFile ()
 Destructor. If handling an open file, the file is closed.
 
tResult Open (const cFilename &strFilename, tUInt32 ui32Mode)
 This function opens an existing or creates a new file. More...
 
tResult Close ()
 Close file. More...
 
tResult Attach (cFile &oFile)
 This function attaches an existing instance of a file class to another. More...
 
tResult Detach ()
 This function detaches existing references to file objects. More...
 
tBool SetReadCache (tInt nCacheSize)
 This function sets the file read cache size. More...
 
tInt Read (tVoid *pvBuffer, tInt nBufferSize)
 This function reads data into a buffer from the file associated with the cFile object. More...
 
tResult ReadAll (tVoid *pvBuffer, tInt nBufferSize)
 This function reads data into a buffer from the file associated with the cFile object. More...
 
tInt Skip (tInt nNumberOfBytes)
 This function reads data from a file but does not store it . More...
 
tInt Write (const tVoid *pvBuffer, tInt nBufferSize)
 This function writes data from a buffer to the file associated with the cFile object. More...
 
tResult WriteAll (const tVoid *pvBuffer, tInt nBufferSize)
 This function writes data from a buffer to the file associated with the cFile object. More...
 
tInt Write (const cString &strString)
 This function writes string data from a buffer to the file associated with the cFile object. More...
 
tInt ReadLine (cString &strString)
 This function reads a line of text data into a cString object. More...
 
tInt WriteLine (const cString &strString)
 This function writes string data from a buffer to the file associated with the cFile object. More...
 
tFileSize GetSize () const
 This function retrieves the file size. More...
 
tFilePos GetFilePos () const
 This function retrieves the file pointer offset. More...
 
tFilePos SetFilePos (tFilePos nOffset, tFilePosRef MoveMode)
 This function moves the file pointer. More...
 
tBool IsEof ()
 Checks whether or not the end of the file has been reached. More...
 
tBool IsValid () const
 This function checks if the file object has an valid file handle. More...
 
tResult Truncate (tFilePos nSize)
 This method truncates the file at the given size. More...
 

Static Public Member Functions

static tResult GetTimeAccess (const cFilename filename, A_UTILS_NS::cDateTime &dt)
 This function returns the last access time of the file. More...
 
static tResult GetTimeCreation (const cFilename filename, A_UTILS_NS::cDateTime &dt)
 This function returns the creation time of the file. More...
 
static tResult GetTimeChange (const cFilename filename, A_UTILS_NS::cDateTime &dt)
 This function returns the last change (write) time of the file. More...
 

Protected Member Functions

tVoid Initialize ()
 Initialization.
 
tResult AllocReadCache (tInt nCacheSize)
 Allocate read cache. More...
 
tResult FreeReadCache ()
 Free read cache. More...
 
tVoidInternalMalloc (tInt nSize, tBool bUseSegmentSize=tFalse)
 Internal allocation method. More...
 
tVoid InternalFree (tVoid *pMemory, tBool bUseSegmentSize=tFalse)
 Internal free method. More...
 

Protected Attributes

tFileHandle m_hFile
 File handle.
 
tUInt8m_pReadCache
 File read cache.
 
tInt m_nFileCacheUsage
 File cache usage.
 
tInt m_nFileCacheOffset
 File cache offset.
 
tInt m_nFileCacheSize
 File cache size.
 
tBool m_bReadCacheEnabled
 Read cache enabled.
 
tBool m_bReference
 File is reference.
 
tBool m_bSystemCacheDisabled
 System cache disabled.
 
tInt m_nSectorSize
 Sector size.
 
tFilePos m_nSectorBytesToSkip
 Sector bytes that will be skipped.
 

Detailed Description

File class.

Definition at line 25 of file file.h.

Member Enumeration Documentation

◆ tFilePosRef

File position reference.

Enumerator
FP_Begin 

offsets are measured from the beginning of the file

FP_Current 

offsets are measured from the current file position

FP_End 

offsets are measured from the end of the file

Definition at line 82 of file file.h.

◆ tOpenMode

enum tOpenMode

Several flags to open files. Can be combined with bitwise or.

Enumerator
OM_Read 

Open existing file.

Can be combined with OM_SharedRead under Windows. Under Windows, the file must exist. Under Linux, if the file doesn't exist it will be created.

OM_Write 

Creates a new file or overwrites existing files.

Can be combined with OM_SharedWrite under windows.

OM_Append 

Append data to existing file. Sets seeking position to the end of the file stream.

OM_ReadWrite 

Open file in read-write mode.

Under Windows, the file must exist. Under Linux, if the file doesn't exist it will be created.

OM_SharedRead 

Allows shared read access, use in addition to flags above.

Exclusive write/read permissions for a whole file are not supported under Linux platforms without any file locks. All files are readable!

OM_SharedWrite 

Allows shared write access, use in addition to flags above.

Exclusive write/read permissions for a whole file are not supported under Linux platforms without any file locks

OM_SequentialAccess 

Optimized for sequential access, use in addition to flags above.

OM_TemporaryFile 

File is of temporary purpose and will be deleted after all handles on the file are closed.

Use in addition to flags above

OM_ShortLived 

Advices the OS not to flush any data to the disk. Just supported on POSIX platforms.

OM_TextMode 

Opens the file in text mode instead of binary mode.

Just supported on POSIX platforms

OM_WriteThrough 

Immediately flush file data to disk. Windows only.

OM_DisableFileSystemCache 

Disable all file system caches. Windows only.

Definition at line 31 of file file.h.

Member Function Documentation

◆ AllocReadCache()

tResult AllocReadCache ( tInt  nCacheSize)
protected

Allocate read cache.

Parameters
nCacheSize[in] Size of cache.
Returns
Standard result code.

◆ Attach()

tResult Attach ( cFile oFile)

This function attaches an existing instance of a file class to another.

Parameters
oFile[in] Reference to an existing file object.
Returns
Always return ERR_NOERROR

◆ Close()

tResult Close ( )

Close file.

Return values
Standarderror code.
isalways ERR_NOERROR.

◆ Detach()

tResult Detach ( )

This function detaches existing references to file objects.

Returns
ERR_NOERROR if referenced file was detached
ERR_UNEXPECTED if no file was attached

◆ FreeReadCache()

tResult FreeReadCache ( )
protected

Free read cache.

Returns
Standard result code.

◆ GetFilePos()

tFilePos GetFilePos ( ) const

This function retrieves the file pointer offset.

Returns
The function returns the file pointer offset from the beginning as a 64-bit integer.

Referenced by cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::StartAppending().

◆ GetSize()

tFileSize GetSize ( ) const

This function retrieves the file size.

Returns
The function returns the file size as 64-bit integer.

◆ GetTimeAccess()

static tResult GetTimeAccess ( const cFilename  filename,
A_UTILS_NS::cDateTime dt 
)
static

This function returns the last access time of the file.

Parameters
dtA_UTILS_NS::cDateTime of the last access
filenamecFilename of the file to be checked
Returns
OK if the time has been retrieved, ERR_INVALID_ARG if filename is empty, ERR_UNKNOWN if time cannot be read;
Attention
From MSDN chapter "File Times": Not all file systems can record creation and last access times, and not all file systems record them in the same manner.
For example, the resolution of create time on FAT is 10 milliseconds, while write time has a resolution of 2 seconds and access time has a resolution of 1 day, so it is really the access date.
The NTFS file system delays updates to the last access time for a file by up to 1 hour after the last access.

◆ GetTimeChange()

static tResult GetTimeChange ( const cFilename  filename,
A_UTILS_NS::cDateTime dt 
)
static

This function returns the last change (write) time of the file.

Parameters
dtA_UTILS_NS::cDateTime of the last access
filenamecFilename of the file to be checked
Returns
OK if the time has been retrieved, ERR_INVALID_ARG if filename is empty, ERR_UNKNOWN if time cannot be read;
Attention
From MSDN chapter "File Times": Not all file systems can record creation and last access times, and not all file systems record them in the same manner.
For example, the resolution of create time on FAT is 10 milliseconds, while write time has a resolution of 2 seconds and access time has a resolution of 1 day, so it is really the access date.
The NTFS file system delays updates to the last access time for a file by up to 1 hour after the last access.

◆ GetTimeCreation()

static tResult GetTimeCreation ( const cFilename  filename,
A_UTILS_NS::cDateTime dt 
)
static

This function returns the creation time of the file.

Parameters
dtA_UTILS_NS::cDateTime of the last access
filenamecFilename of the file to be checked
Returns
OK if the time has been retrieved, ERR_INVALID_ARG if filename is empty, ERR_UNKNOWN if time cannot be read;
Attention
From MSDN chapter "File Times": Not all file systems can record creation and last access times, and not all file systems record them in the same manner.
For example, the resolution of create time on FAT is 10 milliseconds, while write time has a resolution of 2 seconds and access time has a resolution of 1 day, so it is really the access date.
The NTFS file system delays updates to the last access time for a file by up to 1 hour after the last access.

◆ InternalFree()

tVoid InternalFree ( tVoid pMemory,
tBool  bUseSegmentSize = tFalse 
)
protected

Internal free method.

Parameters
pMemory[in] Pointer to memory.
bUseSegmentSize[in] Keep segment size in mind.
Returns
void

◆ InternalMalloc()

tVoid* InternalMalloc ( tInt  nSize,
tBool  bUseSegmentSize = tFalse 
)
protected

Internal allocation method.

Parameters
nSize[in] Size of cache.
bUseSegmentSize[in] Keep segment size in mind.
Returns
Void pointer to allocated memory.

◆ IsEof()

tBool IsEof ( )

Checks whether or not the end of the file has been reached.

Returns
Whether or not the end of the file has been reached.

◆ IsValid()

tBool IsValid ( ) const

This function checks if the file object has an valid file handle.

Returns
Returns true, if the file handle is valid, otherwise false.
This method is real-time safe.\nSee @ref page_real_time_safe.\n

◆ Open()

tResult Open ( const cFilename strFilename,
tUInt32  ui32Mode 
)

This function opens an existing or creates a new file.

Parameters
strFilename[in] string that is the path to the desired file. The path can be relative, absolute, or a network name (UNC). tUInt32 Mode: A tUInt32 that defines the file sharing and access mode. It specifies the action to take when opening the file. You can combine options by using the bitwise-OR ( | ) operator.
ui32Mode[in] File open mode. For valid flags see the tOpenMode enum.
Return values
Standarderror code.
ERR_OPEN_FAILEDCould not read file from hard drive.
ERR_INVALID_FLAGSInvalid file open mode ui32Mode.
ERR_NOACCESSCould not set read cache.
ERR_NOERRORif succeeded.

◆ Read()

tInt Read ( tVoid pvBuffer,
tInt  nBufferSize 
)

This function reads data into a buffer from the file associated with the cFile object.

Parameters
pvBuffer[in] Pointer to the user-supplied buffer that is to receive the data read from the file.
nBufferSize[in] The maximum number of bytes to be read from the file. For text-mode files, carriage return-linefeed pairs are counted as single characters.
Returns
The number of bytes transferred to the buffer. Note that the return value may be less than nBufferSize, if the end of file was reached. If there was a severe error, the function returns -1.

◆ ReadAll()

tResult ReadAll ( tVoid pvBuffer,
tInt  nBufferSize 
)

This function reads data into a buffer from the file associated with the cFile object.

It ensures that all requested bytes have been read.

Parameters
pvBuffer[in] Pointer to the user-supplied buffer that is to receive the data read from the file.
nBufferSize[in] The maximum number of bytes to be read from the file. For text-mode files, carriage return-linefeed pairs are counted as single characters.
Return values
ERR_NOERRORnBufferSize bytes have been read.
Returns
ERR_IO_INCOMPLETE not all bytes could be read.

◆ ReadLine()

tInt ReadLine ( cString strString)

This function reads a line of text data into a cString object.

Parameters
strString[inout] cString object to be filled with character data.
Returns
The number of characters transferred to the string.

◆ SetFilePos()

tFilePos SetFilePos ( tFilePos  nOffset,
tFilePosRef  MoveMode 
)

This function moves the file pointer.

Parameters
nOffset[in] Offset value for pointer movement, relative to MoveMode.
MoveMode[in] Fixed reference point for movement.
Remarks
The file pointer may be set beyond the end of the File. The next write will increase the filesize accordingly.
Returns
Returns the file position which was set (must not be equal to nOffset) or -1 if any error occurred.

Referenced by cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::cFileRingBuffer(), cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::AppendItem(), and cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::StartAppending().

◆ SetReadCache()

tBool SetReadCache ( tInt  nCacheSize)

This function sets the file read cache size.

Parameters
nCacheSize[in] Number of bytes to be allocated as read buffer. If this less than zero, a read cache the size of the default sector size is allocated
Return values
tTrueif the read cache was allocated
tFalsein case of error

◆ Skip()

tInt Skip ( tInt  nNumberOfBytes)

This function reads data from a file but does not store it .

Parameters
nNumberOfBytes[in] The maximum number of bytes to be skipped.
Returns
The number of bytes skipped. Note that the return value may be less than nNumberOfBytes, if the end of file was reached. If there was a severe error or the maximum number of bytes to skip was negative, the function returns -1.

◆ Truncate()

tResult Truncate ( tFilePos  nSize)

This method truncates the file at the given size.

If the file is larger than the given size, the extra data is lost. If it was smaller it is extended.

Parameters
nSize
Returns
OK if the operation was successful.

Referenced by cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::AppendItem().

◆ Write() [1/2]

tInt Write ( const cString strString)

This function writes string data from a buffer to the file associated with the cFile object.

Parameters
strString[in] cString object to be written to the file.
Returns
The number of bytes transferred to the file. If there was an error, -1 is returned.

◆ Write() [2/2]

tInt Write ( const tVoid pvBuffer,
tInt  nBufferSize 
)

This function writes data from a buffer to the file associated with the cFile object.

Parameters
pvBuffer[in] Pointer to the user-supplied buffer that is to receive the data read from the file.
nBufferSize[in] The maximum number of bytes to be read from the file. For text-mode files, carriage return-linefeed pairs are counted as single characters. If nBufferSize is 0, the return value is always 0 and nothing is written.
Returns
The number of bytes transferred to the buffer. If there was an error or pvBuffer was nullptr or nBufferSize was less than 0, -1 is returned.
Attention
On win32 platforms only: If the file was opened with OM_DisableFileSystemCache there is a limitation of the maximum buffer size of approx. 64MB on x86 / approx. 32MB on x86-64. For further details have a look at MSDN WriteFile.

◆ WriteAll()

tResult WriteAll ( const tVoid pvBuffer,
tInt  nBufferSize 
)

This function writes data from a buffer to the file associated with the cFile object.

It ensures that all requested bytes have been written.

Parameters
pvBuffer[in] Pointer to the user-supplied buffer that is to receive the data read from the file.
nBufferSize[in] The maximum number of bytes to be read from the file. For text-mode files, carriage return-linefeed pairs are counted as single characters. If nBufferSize is 0, the return value is always 0 and nothing is written.
Return values
ERR_NOERRORnBufferSize bytes have been written.
Returns
ERR_IO_INCOMPLETE not all bytes could be written.

Referenced by cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::AppendItem(), and cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::FillForAlignment().

◆ WriteLine()

tInt WriteLine ( const cString strString)

This function writes string data from a buffer to the file associated with the cFile object.

The string is followed by a carriage return-linefeed pair.

Parameters
strString[in] cString object to be written to the file.
Returns
The number of bytes transferred to the buffer. If there was an error, -1 is returned.