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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ File() [1/2]

◆ File() [2/2]

◆ ~File()

Member Function Documentation

◆ attach()

◆ canRetry()

◆ copyError()

◆ createPipe()

◆ detach()

◆ exists()

◆ getFileTime() [1/2]

◆ getFileTime() [2/2]

◆ handle()

◆ invalidHandle()

◆ length()

◆ listDirectory()

◆ md5() [1/2]

◆ md5() [2/2]

◆ mkDir()

◆ openPath()

◆ readData()

◆ remove()

◆ rename()

◆ rmDir()

◆ seek()

◆ setBlocking()

◆ setFileTime()

◆ terminate()

◆ valid()

◆ writeData()