Yate: File Class Reference

Yate

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

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 | ( |  | ) |

Default constructor, creates a closed file

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

Constructor from an existing handle

Parameters

  handle | Operating system handle to an open file

virtual ~File | ( |  | ) |
| virtual

Destructor, closes the file

## Member Function Documentation

void attach | ( | HANDLE | handle | ) |

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

Parameters

  handle | Operating system handle to an open file

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.

void copyError | ( |  | ) |
| protected

Copy the last error code from the operating system

static 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

HANDLE detach | ( |  | ) |

Detaches the object from the file handle

Returns
  The handle previously owned by this object

static 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

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

static 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

HANDLE handle | ( |  | ) | const
| inline

Get the operating system handle to the file

Returns
  File handle

static HANDLE invalidHandle | ( |  | ) |
| static

Get the operating system specific handle value for an invalid file

Returns
  Handle value for an invalid file

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.

static 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

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

static 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

static 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

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

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.

static 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

static 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)

static 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

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.

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.

static 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

virtual bool terminate | ( |  | ) |
| virtual

Closes the file handle

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

Implements Stream.

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.

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.

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

- yateclass.h