# class File

A stream file class. More...

Full name | `TelEngine::File`
Definition | `#include <yateclass.h>`
Inherits | TelEngine::Stream [public ]
List of all Methods

Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- File ()
- explicit 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 ()
- inline 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 Static Methods

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

#### Protected Methods

- void copyError ()

#### Protected Members

- HANDLE m_handle

## Detailed Description

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

File ()

### File

Default constructor, creates a closed file

explicit File (HANDLE handle)

### File

Constructor from an existing handle

Parameters:

handle | Operating system handle to an open file

~File ()

### ~File

[virtual]

Destructor, closes the file

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)

### openPath

[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

bool terminate ()

### terminate

[virtual]

Closes the file handle

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

Reimplemented from Stream.

void attach (HANDLE handle)

### attach

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

Parameters:

handle | Operating system handle to an open file

HANDLE detach ()

### detach

Detaches the object from the file handle

Returns: The handle previously owned by this object

inline HANDLE handle ()

### handle

[const]

Get the operating system handle to the file

Returns: File handle

bool canRetry ()

### 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.

bool valid ()

### valid

[const virtual]

Check if this file is valid

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

Reimplemented from Stream.

HANDLE invalidHandle ()

### invalidHandle

[static]

Get the operating system specific handle value for an invalid file

Returns: Handle value for an invalid file

bool setBlocking (bool block = true)

### setBlocking

[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.

int64_t length ()

### 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.

int64_t seek (SeekPos pos, int64_t offset = 0)

### seek

[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.

int writeData (const void* buffer, int length)

### writeData

[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

Reimplemented from Stream.

int readData (void* buffer, int length)

### readData

[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

Reimplemented from Stream.

bool getFileTime (unsigned int& secEpoch)

### getFileTime

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

Parameters:

secEpoch | File creation time (seconds since Epoch)

Returns: True on success

bool md5 (String& buffer)

### md5

[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

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

### setFileTime

[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

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

### getFileTime

[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

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

### exists

[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 rename (const char* oldFile, const char* newFile, int* error = 0)

### rename

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

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

### remove

[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

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

### md5

[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

bool mkDir (const char* path, int* error = 0)

### mkDir

[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

Returns: True on success

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

### rmDir

[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

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

### listDirectory

[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

bool createPipe (File& reader, File& writer)

### createPipe

[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

void copyError ()

### copyError

[protected]

Copy the last error code from the operating system

HANDLE m_handle

### m_handle

[protected]

Generated by: paulc on bussard on Fri Dec 21 16:28:34 2012, using kdoc 2.0a54.