Yate: File Class Reference

Yate

Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
File Class Reference

A stream file class. More...

`#include <yateclass.h>`

Inheritance diagram for File:

## Public Member Functions
| File ()
| File (HANDLE handle)
virtual | ~File ()
virtual bool | openPath (const char *name, bool canWrite=false, bool canRead=true, bool create=false, bool append=false, bool binary=false, bool pubReadable=false, bool pubWritable=false)
virtual bool | terminate ()
void | attach (HANDLE handle)
HANDLE | detach ()
HANDLE | handle () const
virtual bool | canRetry () const
virtual bool | valid () const
virtual bool | setBlocking (bool block=true)
virtual int64_t | length ()
virtual int64_t | seek (SeekPos pos, int64_t offset=0)
virtual int | writeData (const void *buffer, int length)
virtual int | readData (void *buffer, int length)
bool | getFileTime (unsigned int &secEpoch)
virtual bool | md5 (String &buffer)
Public Member Functions inherited from Stream
virtual | ~Stream ()
int | error () const
virtual bool | inProgress () const
int | writeData (const char *str)
int | writeData (const String &str)
int | writeData (const DataBlock &buf)
int64_t | seek (int64_t offset)

## Static Public Member Functions
static HANDLE | invalidHandle ()
static bool | setFileTime (const char *name, unsigned int secEpoch, int *error=0)
static bool | getFileTime (const char *name, unsigned int &secEpoch, int *error=0)
static bool | exists (const char *name, int *error=0)
static bool | rename (const char *oldFile, const char *newFile, int *error=0)
static bool | remove (const char *name, int *error=0)
static bool | md5 (const char *name, String &buffer, int *error=0)
static bool | mkDir (const char *path, int *error=0, int mode=-1)
static bool | rmDir (const char *path, int *error=0)
static bool | listDirectory (const char *path, ObjList *dirs, ObjList *files, int *error=0)
static bool | createPipe (File &reader, File &writer)
Static Public Member Functions inherited from Stream
static bool | allocPipe (Stream *&reader, Stream *&writer)
static bool | allocPair (Stream *&str1, Stream *&str2)
static bool | supportsPipes ()
static bool | supportsPairs ()

## Protected Member Functions
void | copyError ()
Protected Member Functions inherited from Stream
| Stream ()
void | clearError ()

## Protected Attributes
HANDLE | m_handle
Protected Attributes inherited from Stream
int | m_error

## Additional Inherited Members
Public Types inherited from Stream
enum | SeekPos { SeekBegin , SeekEnd , SeekCurrent }

## Detailed Description

A stream file class.

Class to encapsulate a system dependent file in a system independent abstraction

## Constructor & Destructor Documentation

## ◆ File() [1/2]

File | ( |  | ) |

Default constructor, creates a closed file

Referenced by createPipe().

## ◆ File() [2/2]

File | ( | HANDLE | handle | ) |
| explicit

Constructor from an existing handle

Parameters

  handle | Operating system handle to an open file

References handle().

## ◆ ~File()

virtual ~File | ( |  | ) |
| virtual

Destructor, closes the file

## Member Function Documentation

## ◆ attach()

void attach | ( | HANDLE | handle | ) |

Attach an existing handle to the file, closes any existing first

Parameters

  handle | Operating system handle to an open file

References handle().

## ◆ canRetry()

virtual bool canRetry | ( |  | ) | const
| virtual

Check if the last error code indicates a retryable condition

Returns
  True if error was temporary and operation should be retried

Reimplemented from Stream.

## ◆ copyError()

void copyError | ( |  | ) |
| protected

Copy the last error code from the operating system

## ◆ createPipe()

bool createPipe | ( | File & | reader,
|  | File & | writer )
| static

Create a pair of unidirectionally pipe connected streams

Parameters

  reader | Reference to a File that becomes the reading side of the pipe
  writer | Reference to a File that becomes the writing side of the pipe

Returns
  True is the pipe was created successfully

References File().

## ◆ detach()

HANDLE detach | ( |  | ) |

Detaches the object from the file handle

Returns
  The handle previously owned by this object

## ◆ exists()

bool exists | ( | const char * | name,
|  | int * | error = 0 )
| static

Check if a file exists

Parameters

  name | The file to check
  error | Optional pointer to error code to be filled on failure

Returns
  True if the file exists

References Stream::error().

## ◆ getFileTime() [1/2]

bool getFileTime | ( | const char * | name,
|  | unsigned int & | secEpoch,
|  | int * | error = 0 )
| static

Retrieve a file's modification time

Parameters

  name | Path and name of the file
  secEpoch | File modification time (seconds since Epoch)
  error | Optional pointer to error code to be filled on failure

Returns
  True on success

References Stream::error().

## ◆ getFileTime() [2/2]

bool getFileTime | ( | unsigned int & | secEpoch | ) |

Retrieve the file's modification time (the file must be already opened)

Parameters

  secEpoch | File creation time (seconds since Epoch)

Returns
  True on success

## ◆ handle()

HANDLE handle | ( |  | ) | const
| inline

Get the operating system handle to the file

Returns
  File handle

Referenced by attach(), and File().

## ◆ invalidHandle()

HANDLE invalidHandle | ( |  | ) |
| static

Get the operating system specific handle value for an invalid file

Returns
  Handle value for an invalid file

## ◆ length()

virtual int64_t length | ( |  | ) |
| virtual

Find the length of the file if it has one

Returns
  Length of the file or zero if length is not defined

Reimplemented from Stream.

Referenced by readData(), and writeData().

## ◆ listDirectory()

bool listDirectory | ( | const char * | path,
|  | ObjList * | dirs,
|  | ObjList * | files,
|  | int * | error = 0 )
| static

Enumerate a folder (directory) content. Fill the given lists with children item names

Parameters

  path | The folder path
  dirs | List to be filled with child directories. It can be NULL if not requested
  files | List to be filled with child files. It can be NULL if not requested
  error | Optional pointer to error code to be filled on failure

Returns
  True on success

References Stream::error().

## ◆ md5() [1/2]

bool md5 | ( | const char * | name,
|  | String & | buffer,
|  | int * | error = 0 )
| static

Build the MD5 hex digest of a file.

Parameters

  name | The file to build MD5 from
  buffer | Destination buffer
  error | Optional pointer to error code to be filled on failure

Returns
  True on success

References Stream::error().

## ◆ md5() [2/2]

virtual bool md5 | ( | String & | buffer | ) |
| virtual

Build the MD5 hex digest of a file. The file must be opened for read access. This method will move the file pointer

Parameters

  buffer | Destination buffer

Returns
  True on success

## ◆ mkDir()

bool mkDir | ( | const char * | path,
|  | int * | error = 0,
|  | int | mode = -1 )
| static

Create a folder (directory). It only creates the last directory in the path

Parameters

  path | The folder path
  error | Optional pointer to error code to be filled on failure
  mode | Optional file mode, ignored on some platforms

Returns
  True on success

References Stream::error().

## ◆ openPath()

virtual bool openPath | ( | const char * | name,
|  | bool | canWrite = false,
|  | bool | canRead = true,
|  | bool | create = false,
|  | bool | append = false,
|  | bool | binary = false,
|  | bool | pubReadable = false,
|  | bool | pubWritable = false )
| virtual

Opens a file from the filesystem pathname

Parameters

  name | Name of the file according to the operating system's conventions
  canWrite | Open the file for writing
  canRead | Open the file for reading
  create | Create the file if it doesn't exist
  append | Set the write pointer at the end of an existing file
  binary | Open the file in binary mode if applicable
  pubReadable | If the file is created make it public readable
  pubWritable | If the file is created make it public writable

Returns
  True if the file was successfully opened

## ◆ readData()

virtual int readData | ( | void * | buffer,
|  | int | length )
| virtual

Read data from an open file

Parameters

  buffer | Buffer for data transfer
  length | Length of the buffer

Returns
  Number of bytes transferred, negative if an error occurred

Implements Stream.

References length().

## ◆ remove()

bool remove | ( | const char * | name,
|  | int * | error = 0 )
| static

Deletes a file entry from the filesystem

Parameters

  name | Absolute path and name of the file to delete
  error | Optional pointer to error code to be filled on failure

Returns
  True if the file was successfully deleted

References Stream::error().

## ◆ rename()

bool rename | ( | const char * | oldFile,
|  | const char * | newFile,
|  | int * | error = 0 )
| static

Rename (move) a file (or directory) entry from the filesystem

Parameters

  oldFile | Path and name of the file to rename
  newFile | The new path and name of the file
  error | Optional pointer to error code to be filled on failure

Returns
  True if the file was successfully renamed (moved)

References Stream::error().

## ◆ rmDir()

bool rmDir | ( | const char * | path,
|  | int * | error = 0 )
| static

Remove an empty folder (directory)

Parameters

  path | The folder path
  error | Optional pointer to error code to be filled on failure

Returns
  True on success

References Stream::error().

## ◆ seek()

virtual int64_t seek | ( | SeekPos | pos,
|  | int64_t | offset = 0 )
| virtual

Set the file read/write pointer

Parameters

  pos | The seek start as enumeration
  offset | The number of bytes to move the pointer from starting position

Returns
  The new position of the file read/write pointer. Negative on failure

Reimplemented from Stream.

## ◆ setBlocking()

virtual bool setBlocking | ( | bool | block = true | ) |
| virtual

Set the blocking or non-blocking operation mode of the file

Parameters

  block | True if I/O operations should block, false for non-blocking

Returns
  True if operation was successfull, false if an error occured

Reimplemented from Stream.

## ◆ setFileTime()

bool setFileTime | ( | const char * | name,
|  | unsigned int | secEpoch,
|  | int * | error = 0 )
| static

Set a file's modification time.

Parameters

  name | Path and name of the file
  secEpoch | File modification time (seconds since Epoch)
  error | Optional pointer to error code to be filled on failure

Returns
  True on success

References Stream::error().

## ◆ terminate()

virtual bool terminate | ( |  | ) |
| virtual

Closes the file handle

Returns
  True if the file was (already) closed, false if an error occured

Implements Stream.

## ◆ valid()

virtual bool valid | ( |  | ) | const
| virtual

Check if this file is valid

Returns
  True if the file is valid, false if it's invalid or closed

Implements Stream.

## ◆ writeData()

virtual int writeData | ( | const void * | buffer,
|  | int | length )
| virtual

Write data to an open file

Parameters

  buffer | Buffer for data transfer
  length | Length of the buffer

Returns
  Number of bytes transferred, negative if an error occurred

Implements Stream.

References length().

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

- yateclass.h