Software and Services, Portable Libraries  2019.Mar.01
A library for managing digital certificates
SoftwareAndServices::Library::Common::File Class Reference

Like 'FILE', except C++ implementation and allows sockets and disk files to use same object on WINDOWS. More...

#include "<SaS/Common/File.hpp>"

+ Inheritance diagram for SoftwareAndServices::Library::Common::File:
+ Collaboration diagram for SoftwareAndServices::Library::Common::File:

Public Types

enum  Whence_t { SEEK_SET_t = SEEK_SET, SEEK_CUR_t = SEEK_CUR, SEEK_END_t = SEEK_END }
 How to apply the offset variable in the lseek() member function. More...
 

Public Member Functions

 File ()
 File - default Constructor. More...
 
 File (const int fd, const char *aFileName)
 File - Constructor. More...
 
 File (const void *buffer, uint32_t BufferSize=0)
 File - Constructor. More...
 
 File (const wchar_t *buffer, uint32_t BufferSize=0)
 File - Constructor. More...
 
 File (char **buffer, uint32_t *BufferSize=nullptr)
 File - Constructor. More...
 
 File (wchar_t **buffer, uint32_t *BufferSize=nullptr)
 File - Constructor. More...
 
virtual ~File ()
 File - Destructor. More...
 
bool AtEOF ()
 
uint32_t CanRead ()
 
bool Close ()
 Close the file. More...
 
virtual InstanceCount_t decInstance () const
 Decrement the instance. More...
 
bool Encrypt (bool DoEncryption)
 Turn encryption ON/OFF. More...
 
bool Flush ()
 Force write all data. More...
 
const char * GetBuffer () const
 
uint32_t GetBufferSize () const
 
int GetFd ()
 
const char * GetFileName () const
 
virtual InstanceCount_t getInstance () const
 
virtual InstanceCount_t incInstance () const
 Increment the instance. More...
 
bool IsMMapped () const
 
bool Keys (const char *Private, const char *Public)
 Set the TLS/SSL public/private key to use. More...
 
char LookNext ()
 
off_t Lseek (off_t offset, Whence_t whence)
 Seek to a position in this File. More...
 
bool Mkdir (const char *path, mode_t mode)
 Make a directory, and all path components when needed. More...
 
bool NextIsLwsp ()
 
bool Open (const char *file, int RWmode)
 Open the named file for reading or writing. More...
 
void operator delete (void *ToFree)
 
int Printf (const char *Format,...)
 printf like method, wrapper for vprintf() More...
 
uint32_t Read (void *data, const uint32_t Length, bool force=true)
 Read with our without blocking. More...
 
bool ReadLine (uint8_t **Results, uint32_t &Length, bool Force=true, bool DiscardEol=true)
 Read with our without blocking. More...
 
off_t Tell ()
 
void ThrowExceptions (bool Enable)
 Turn on C++ exceptions. More...
 
uint32_t Write (const void *data, const uint32_t Length)
 Write to File. More...
 
uint32_t Write (const char *data)
 Write a C-string (const char*) to File. More...
 

Static Public Member Functions

static const char * GetTopDir ()
 
static bool Lock (const char *fileName)
 Lock the file - block until locked. More...
 
static bool LockFileOnly (const char *fileName)
 Lock the file - block until locked. More...
 
static bool SetTopDir (const char *theTop)
 
static bool Trylock (const char *fileName)
 Try to lock the file. More...
 
static bool Unlock (const char *fileName)
 UnLock the file - block until unlocked. More...
 
static bool UnlockFileOnly (const char *fileName)
 UnLock the file - block until unlocked. More...
 

Static Public Attributes

static const char * DefaultTopDir
 The current topDir. More...
 
static const char * NewTmpFileExt
 defult extension for temporary files created. More...
 

Detailed Description

Like 'FILE', except C++ implementation and allows sockets and disk files to use same object on WINDOWS.

Definition at line 150 of file File.hpp.

Member Enumeration Documentation

◆ Whence_t

How to apply the offset variable in the lseek() member function.

Enumerator
SEEK_SET_t 

From the beginning.

SEEK_CUR_t 

From the current position.

SEEK_END_t 

From the end of the file.

Definition at line 560 of file File.hpp.

Constructor & Destructor Documentation

◆ File() [1/6]

SoftwareAndServices::Library::Common::File::File ( )

File - default Constructor.

Note
This constructor calls ThrowErrors(false), if you do want C++ excaptions thrown, call ThrowErrors(true) after construction.

◆ File() [2/6]

SoftwareAndServices::Library::Common::File::File ( const int  fd,
const char *  aFileName 
)

File - Constructor.

Parameters
fdAn open file descriptor to connect to a file name.
aFileNameThe file name to use.
Note
This constructor calls ThrowErrors(false), if you do want C++ excaptions thrown, call ThrowErrors(true) after construction.
This constructor calls pthread_sigmask(SIG_BLOCK, ..SIGPIPE.., nullptr) blocking SIGPIPE for socket I/O (when fd is a socket). Errors are returned by throwing an (Error_t*), or a return value less that the amount requested to be written or read from a pipe.

◆ File() [3/6]

SoftwareAndServices::Library::Common::File::File ( const void *  buffer,
uint32_t  BufferSize = 0 
)
explicit

File - Constructor.

Parameters
bufferInitialize File to point to buffer. This is a read only buffer.
BufferSizeThe size of buffer. May be nullptr,
Note
This constructor calls ThrowErrors(true), if you do not want C++ excaptions thrown, call ThrowErrors(false) after construction.

◆ File() [4/6]

SoftwareAndServices::Library::Common::File::File ( const wchar_t *  buffer,
uint32_t  BufferSize = 0 
)
explicit

File - Constructor.

Parameters
bufferInitialize File to point to buffer. This is a read only buffer.
BufferSizeThe size of buffer. May be nullptr,
Note
This constructor calls ThrowErrors(true), if you do not want C++ excaptions thrown, call ThrowErrors(false) after construction.

◆ File() [5/6]

SoftwareAndServices::Library::Common::File::File ( char **  buffer,
uint32_t *  BufferSize = nullptr 
)
explicit

File - Constructor.

Parameters
bufferA pointer to a buffer pointer. Used for writing to a buffer.
BufferSizeA pointer to the size of buffer. May be nullptr, After a write, BufferSize will point to the size of what buffer points to. Each write may update the value that buffer points to and what BufferSize points to.
Note
This constructor calls ThrowErrors(true), if you do not want C++ excaptions thrown, call ThrowErrors(false) after construction.

◆ File() [6/6]

SoftwareAndServices::Library::Common::File::File ( wchar_t **  buffer,
uint32_t *  BufferSize = nullptr 
)
explicit

File - Constructor.

Parameters
bufferA pointer to a buffer pointer. Used for writing to a buffer.
BufferSizeA pointer to the size of buffer. May be nullptr, After a write, BufferSize will point to the size of what buffer points to. Each write may update the value that buffer points to and what BufferSize points to.
Note
This constructor calls ThrowErrors(true), if you do not want C++ excaptions thrown, call ThrowErrors(false) after construction.

◆ ~File()

virtual SoftwareAndServices::Library::Common::File::~File ( )
virtual

File - Destructor.

Member Function Documentation

◆ AtEOF()

bool SoftwareAndServices::Library::Common::File::AtEOF ( )
Returns
TRUE when at end of file.

◆ CanRead()

uint32_t SoftwareAndServices::Library::Common::File::CanRead ( )
Returns
How many octets can be read without blocking.

◆ Close()

bool SoftwareAndServices::Library::Common::File::Close ( )

Close the file.

Returns
TRUE if closed, else FALSE with errno set.

◆ decInstance()

virtual InstanceCount_t SoftwareAndServices::Library::Common::instance< File >::decInstance ( ) const
inlinevirtualinherited

Decrement the instance.

Returns
The instance count, after decrementing it.

Definition at line 129 of file instance.hpp.

◆ Encrypt()

bool SoftwareAndServices::Library::Common::File::Encrypt ( bool  DoEncryption)

Turn encryption ON/OFF.

Parameters
DoEncryptionWhen true, I/O encrypted is turned ON. When false, encryption is turned OFF.
Returns
true if the Private and Public keys are valid. And encryption is turned ON (or OFF).

◆ Flush()

bool SoftwareAndServices::Library::Common::File::Flush ( )

Force write all data.

Returns
true if everything was written. False when their was an underlying write error.

◆ GetBuffer()

const char* SoftwareAndServices::Library::Common::File::GetBuffer ( ) const
Returns
a pointer to the MMAP()'d buffer, or nullptr if not MMAPed.

◆ GetBufferSize()

uint32_t SoftwareAndServices::Library::Common::File::GetBufferSize ( ) const
Returns
The size of the MMAPed buffer, or -1 if not MMAPed.

◆ GetFd()

int SoftwareAndServices::Library::Common::File::GetFd ( )
Returns
The OS FD or handle for this file object. Or -1 on error.

◆ GetFileName()

const char* SoftwareAndServices::Library::Common::File::GetFileName ( ) const
Returns
The file name used during open, or nullptr if none (socket).

◆ getInstance()

virtual InstanceCount_t SoftwareAndServices::Library::Common::instance< File >::getInstance ( ) const
inlinevirtualinherited
Returns
The current instance count.

Definition at line 118 of file instance.hpp.

◆ GetTopDir()

static const char* SoftwareAndServices::Library::Common::File::GetTopDir ( )
static
Returns
Get the top most directory - license file creation.

◆ incInstance()

virtual InstanceCount_t SoftwareAndServices::Library::Common::instance< File >::incInstance ( ) const
inlinevirtualinherited

Increment the instance.

Returns
The instance value, after incrementing it.

Definition at line 109 of file instance.hpp.

◆ IsMMapped()

bool SoftwareAndServices::Library::Common::File::IsMMapped ( ) const
Returns
TRUE if this is File is MMAPed.

◆ Keys()

bool SoftwareAndServices::Library::Common::File::Keys ( const char *  Private,
const char *  Public 
)

Set the TLS/SSL public/private key to use.

This MUST be set before any encrypted I/O can be used. Once set, the reads and writes are encrypted. The data in the buffer is not encrypted. Only when it reads to or writes from the file descriptor.

Parameters
PrivateThe PEM private key to use.
PublicThe PEM public key to use.
Returns
true if the keys are accepted.

◆ Lock()

static bool SoftwareAndServices::Library::Common::File::Lock ( const char *  fileName)
static

Lock the file - block until locked.

Parameters
fileNameThe file (directory) to lock.
Returns
TRUE if locked.

◆ LockFileOnly()

static bool SoftwareAndServices::Library::Common::File::LockFileOnly ( const char *  fileName)
static

Lock the file - block until locked.

Parameters
fileNameThe file (no directory) to lock.
Returns
TRUE if locked.

◆ LookNext()

char SoftwareAndServices::Library::Common::File::LookNext ( )
Returns
The next octet. This is a look only method. To get the character you still have to Read it.

◆ Lseek()

off_t SoftwareAndServices::Library::Common::File::Lseek ( off_t  offset,
Whence_t  whence 
)

Seek to a position in this File.

Parameters
offsetHow many octets.
whenceFrom beginning (SEEK_SET_t), from current position (SEEK_CUR_t), from end (SEEK_END_t).
Returns
The current position.

◆ Mkdir()

bool SoftwareAndServices::Library::Common::File::Mkdir ( const char *  path,
mode_t  mode 
)

Make a directory, and all path components when needed.

Parameters
pathWhat path to make as a directory.
modeThe directory mode.
Returns
TRUE if made, else FALSE with errno set.

◆ NextIsLwsp()

bool SoftwareAndServices::Library::Common::File::NextIsLwsp ( )
Returns
TRUE if the next character is a SPACE or TAB

◆ Open()

bool SoftwareAndServices::Library::Common::File::Open ( const char *  file,
int  RWmode 
)

Open the named file for reading or writing.

Parameters
fileThe file to open.
RWmodeO_RDONLY -or- O_WRONLY.
Returns
TRUE if opened, else FALSE with errno set.

◆ Printf()

int SoftwareAndServices::Library::Common::File::Printf ( const char *  Format,
  ... 
)

printf like method, wrapper for vprintf()

Parameters
FormatThe printf format string.
...The values to be processed.
Returns
The number of characters written.

◆ Read()

uint32_t SoftwareAndServices::Library::Common::File::Read ( void *  data,
const uint32_t  Length,
bool  force = true 
)

Read with our without blocking.

Parameters
dataWhere to put the data.
LengthRead up to this much data.
forceWhen TRUE, block until Length octets are read. When FALSE, read what you can without blocking, then return the number of octets read. Can also return if socket is closed or end of file.
Exceptions
Errorwith EINVAL when ThrowErrors(true) was set and an attempt to read past the buffer end occurs.
Returns
The number of octets read.

◆ ReadLine()

bool SoftwareAndServices::Library::Common::File::ReadLine ( uint8_t **  Results,
uint32_t &  Length,
bool  Force = true,
bool  DiscardEol = true 
)

Read with our without blocking.

Reads characters until a '\r' or '\n' is found. Also reads the end of line characters.

When DiscardEol is true (the defult): The end of line characters are read from the input, then discarded.

The results will be terminated with a zero (0), so that standard c-string functions will work.

Only the first end of line, or set of end of line will be discarded. This allows empty lines to be detected.

Examples:

  • aline\r The \r will be read and discarded.
  • aline\r\n The \r\n will both be discarded.
  • aline\n\n Only the first \n will be discarded. The second call will result in a zero length line.
  • aline\r\n\r\n Only the first set of \r\n will be discarded. The second call will result in a zero length line.

When DiscardEold is false: The end of line characters are read from the input and returned.

Only the first end of line, or set of end of line will be returned. This allows empty lines to be detected.

Examples:

  • aline\r The \r will be read and returned.
  • aline\r\n The \r\n will both be returned.
  • aline\n\n Only the first \n will be returned. The second call will result in a zero length line.
  • aline\r\n\r\n Only the first set of \r\n will be returned. The second call will result in a zero length line.
Parameters
ResultsWhere to put the data. This is a pointer to a pointer. The value (*Results) will be updated to point to the newly allocated storage for the line.
LengthRead up to this much data. When zero, keep reading until end of line. The results will be one octet larger than Length, to accomidate the terminating zero.

On return, Length will be updated with the length of the string. The returned Length will not count the terminating zero. Ex: The string "abcd" will return 4.

Parameters
DiscardEolWhen true (the default), this method will read the end of line characters, and discard them. When false, the end of line characters will be read, and appended to Results.
ForceWhen TRUE, block until Length octets are read. When FALSE, read what you can without blocking, then return the number of octets read. Can also return if socket is closed or end of file.
Exceptions
Errorwith EINVAL when ThrowErrors(true) was set and an attempt to read past the buffer end occurs.
Returns
True if end of line was found before Length or end of file.
Note
Caller is responsible for deleteing (*Results) when the data is no longer used.

◆ SetTopDir()

static bool SoftwareAndServices::Library::Common::File::SetTopDir ( const char *  theTop)
static
Parameters
theTopthe top most directory to use - license file creation.
Returns
TRUE if set.

◆ Tell()

off_t SoftwareAndServices::Library::Common::File::Tell ( )
Returns
The current position in the File.

◆ ThrowExceptions()

void SoftwareAndServices::Library::Common::File::ThrowExceptions ( bool  Enable)

Turn on C++ exceptions.

The I/O methods may throw (Error*) on error.

Parameters
EnableWhen true, enables C++ exceptions. When Enable is false, no C++ exceptions will be thrown.

◆ Trylock()

static bool SoftwareAndServices::Library::Common::File::Trylock ( const char *  fileName)
static

Try to lock the file.

Parameters
fileNameThe file (directory) to lock.
Returns
TRUE if locked, return FALSE if already locked.

◆ Unlock()

static bool SoftwareAndServices::Library::Common::File::Unlock ( const char *  fileName)
static

UnLock the file - block until unlocked.

Parameters
fileNameThe file (directory) to unlock.
Returns
TRUE if unlocked.

◆ UnlockFileOnly()

static bool SoftwareAndServices::Library::Common::File::UnlockFileOnly ( const char *  fileName)
static

UnLock the file - block until unlocked.

Parameters
fileNameThe file (NO directory) to unlock.
Returns
TRUE if unlocked.

◆ Write() [1/2]

uint32_t SoftwareAndServices::Library::Common::File::Write ( const void *  data,
const uint32_t  Length 
)

Write to File.

Parameters
dataWhere to get the data that is to be written.
LengthThe number of octets to write.
Returns
The number of octets written.
Exceptions
Errorwith EBIG when ThrowErrors(true) was set and an attempt to write past the user supplied buffer that was set when the File object was constructed.
See also
File(const char * buffer, uint32_t BufferSize)

◆ Write() [2/2]

uint32_t SoftwareAndServices::Library::Common::File::Write ( const char *  data)

Write a C-string (const char*) to File.

Parameters
dataWhere to get the data that is to be written.
Returns
The number of octets written.
Exceptions
Errorwith EBIG when ThrowErrors(true) was set and an attempt to write past the user supplied buffer that was set when the File object was constructed.
See also
File(const char * buffer, uint32_t BufferSize)

Member Data Documentation

◆ DefaultTopDir

const char* SoftwareAndServices::Library::Common::File::DefaultTopDir
static

The current topDir.

Definition at line 661 of file File.hpp.

◆ NewTmpFileExt

const char* SoftwareAndServices::Library::Common::File::NewTmpFileExt
static

defult extension for temporary files created.

Definition at line 667 of file File.hpp.


The documentation for this class was generated from the following file: