Wefts::OSFileFuncBase Class Reference
[OS Cooperative File Function Extended Enviroment]

#include <wefts_coffee_base.h>

Inheritance diagram for Wefts::OSFileFuncBase:

[legend]List of all members.

---

Detailed Description

Abstracts an OS specific file fucntion set.

This class provides basic cooperative file access; cooperative file access means that the os specific implementation will have to take care of messages that wefts sends to them to i.e. interrupt operations and eventually terminate calling thread, doing a cleanup function.

The class implementations must be made so that their data is fungible also to standard non-cooperative functions that are present in the system.

This class and subclasses methods are not required to be locked. Underlying OS operations are generally thread safe, and this would make locking of this class methods generally an overkill; the risk of concurrent access to the method of this class must be minimized with correct programming techniques (i.e. accessing to an object only within a thread) or with outher mutex encapsulation (i.e. deriving a class both from this one and from a mutex of some kind).

See also:

How to use OS Cooperative File Function Extended Environment layer

Public Member Functions
virtual CffStatus	open (std::string filespec, OpenMode openMode=OM_RO, LockMode lockMode=LM_SHARED)=0
	Creates a file.
virtual CffStatus	create (std::string filespec, CreateMode cMode=CM_ARCHIVE, LockMode lockMode=LM_EXCLUSIVE)=0
	Creates the file.
virtual void	getDescriptor (void *data) const =0
	Get the descriptor OS value.
virtual void	setDescriptor (void *data)=0
	Set the descriptor OS value.
CffStatus	status () const
	Get the status returned by the last operation.
void	status (const CffStatus st)
	Set the internal status.
int	osError () const
	Get OS dependant error code caused by the last operation.
void	osError (const int osError)
	Set the OS dependant error.
double	timeout () const
	Get the standard operation timeout.
void	timeout (const double to)
	Set the standard operation timeout.
void	clearTimeout ()
void	dontBlock ()
virtual file_size_t	read (void *buffer, const file_size_t len)=0
	Read data from the underlying file.
virtual file_size_t	write (void *buffer, const file_size_t len)=0
	Write data to the underlying file.
virtual file_size_t	seek (const file_size_t position, const SeekWhence swFrom=SW_FROM_BEGIN)=0
	Change the position in the file.
virtual CffStatus	close ()=0
	Closes a file.
virtual void	setStdIn ()=0
	Set this file to stdin.
virtual void	setStdOut ()=0
	Set this file to stdout.
virtual void	setStdErr ()=0
	Set this file to stderr.
Protected Member Functions
	OSFileFuncBase ()
	Initializes the internal data of the FileFunction.
Protected Attributes
double	m_timeout
CffStatus	m_status
int	m_osError

---

Constructor & Destructor Documentation

Wefts::OSFileFuncBase::OSFileFuncBase (   )  [inline, protected]

Initializes the internal data of the FileFunction. This constructor forces subclassess to accept an OS dependant descriptor that may be open with other functions outside the OS-COFFEE model. Refer to specific OS-COFFEE implementation to know what kind of descriptor they can accept. Accepting the descriptor is done via acall to the setDescriptior() pure virtual method.

---

Member Function Documentation

void Wefts::OSFileFuncBase::clearTimeout (   )  [inline]

virtual CffStatus Wefts::OSFileFuncBase::close (   )  [pure virtual]

Closes a file. Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

virtual CffStatus Wefts::OSFileFuncBase::create (  std::string  filespec, CreateMode  cMode = CM_ARCHIVE, LockMode  lockMode = LM_EXCLUSIVE )  [inline, pure virtual]

Creates the file. The create-lock parameter is provided because some systems may not allow to lock the file after the create step (the lock politic must be chosen at open time). The timeout is provided because the file may be located on a network disk, or a COFFEE implementation may use a network protocol as underlying layer. It is theoretically possible to provide a COFFEE for FTP. Anyhow, a reasonable timeout may also protect against program deadlocks due to local filesystem failure on systems that do not provide a prompt error diagniostic. File is always created with read-write access from the creator, and it can be locked against concurrent access from other processes. By default, the timeout is not set; to set a given timeout, use the setTimeout() method. Note: Please note that you can use OS system dependant routine to open the file descriptor, and then setup the Parameters: filespec  the file name cMode  the file open mode lockMode  wether the file may be accessed by other processes willing to open it or not. Returns: a Cff Status indicating success or failure (see CffStatus) Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

void Wefts::OSFileFuncBase::dontBlock (   )  [inline]

virtual void Wefts::OSFileFuncBase::getDescriptor (  void *  data  )  const [inline, pure virtual]

Get the descriptor OS value. This function can be hooked by OS specific implementation to copy the descriptor value in the address passed as parameter. This allows to extract the handle, descriptor or structure of that represents the file from this class and use non-cooperative functions (or os-level function that provide native cooperation with the OSTAIL). Parameters: data  a pointer to the memory area that will receive the OS native file descriptor. See also: oslevel Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

virtual CffStatus Wefts::OSFileFuncBase::open (  std::string  filespec, OpenMode  openMode = OM_RO, LockMode  lockMode = LM_SHARED )  [inline, pure virtual]

Creates a file. The file may be opened with a locking sckeme, if the underlying provides it, and may be triggered with a given timeout. The open-lock parameter is provided because some systems may not allow to lock the file after the open step (the lock politic must be chosen at open time). The timeout is provided because the file may be located on a network disk, or a COFFEE implementation may use a network protocol as underlying layer. It is theoretically possible to provide a COFFEE for FTP. Anyhow, a reasonable timeout may also protect against program deadlocks due to local filesystem failure on systems that do not provide a prompt error diagniostic. File can be opened for reading, for writing, can be open truncated or in append mode (see OpenMode). Text-to-binary translation is not provided: data is read as is on all systems. By default, the timeout is not set; to set a given timeout, use the setTimeout() method. Note: Please note that you can use OS system dependant routine to open the file descriptor, and then setup the Parameters: filespec  the file name openMode  the file open mode lockMode  wether the file may be accessed by other processes willing to open it or not. Returns: a Cff Status indicating success or failure (see CffStatus) Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

void Wefts::OSFileFuncBase::osError (  const int  osError  )  [inline]

Set the OS dependant error. Generally, applications should not use this.

int Wefts::OSFileFuncBase::osError (   )  const [inline]

Get OS dependant error code caused by the last operation. Implementations must not use shorthands as returing directly the OS error, as it may have changed before the thread has a chance to call this function. Even if the OS error is thread specific at OS level, the thread may do other operations before calling this function, or it mai send this object to another thread that is responsible to retreive the error that has been found.

virtual file_size_t Wefts::OSFileFuncBase::read (  void *  buffer, const file_size_t  len )  [pure virtual]

Read data from the underlying file. Application should not rely on osError() if the function retunrs a vaild number. file_size_t is the longest integer type provided by the platform. Parameters: buffer  memory area where to load the data len  amount of byte to be read on the memory data Returns: the amount of byte read from the file, 0 on end of file and -1 on error. On error status() and osError() will return proper values. Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

virtual file_size_t Wefts::OSFileFuncBase::seek (  const file_size_t  position, const SeekWhence  swFrom = SW_FROM_BEGIN )  [pure virtual]

Change the position in the file. Must return current position after change, so that seek( 0, SW_FROM_END ) return the current file length (that is one past last byte). Returns: current position after seek or -1 on error Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

virtual void Wefts::OSFileFuncBase::setDescriptor (  void *  data  )  [inline, pure virtual]

Set the descriptor OS value. This function can be hooked by OS specific implementation to copy the descriptor value from the address passed as parameter. The implementations must just discard the previous value of the internal descriptor, and applications must take care to retreive it before destriong it with getDescriptor and correctly dispose it following the OS requirements. Parameters: data  a pointer to the memory area that will receive the OS native file descriptor. Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

virtual void Wefts::OSFileFuncBase::setStdErr (   )  [inline, pure virtual]

Set this file to stderr. This method is to be overloaded by subclasses so that following operations on this OSFileFunc are applied to the standard error file. Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

virtual void Wefts::OSFileFuncBase::setStdIn (   )  [inline, pure virtual]

Set this file to stdin. This method is to be overloaded by subclasses so that following operations on this OSFileFunc are applied to the standard input file. Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

virtual void Wefts::OSFileFuncBase::setStdOut (   )  [inline, pure virtual]

Set this file to stdout. This method is to be overloaded by subclasses so that following operations on this OSFileFunc are applied to the standard output file. Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

void Wefts::OSFileFuncBase::status (  const CffStatus  st  )  [inline]

Set the internal status. Generally, applications should not use this. Parameters: st  the new status

CffStatus Wefts::OSFileFuncBase::status (   )  const [inline]

Get the status returned by the last operation.

void Wefts::OSFileFuncBase::timeout (  const double  to  )  [inline]

Set the standard operation timeout. Timeout can be also set to 0.0 (never block) or less than zero (block forever). Methods clearTimeout() and dontBlock() are inline provided for candy grammar. Parameters: to  the timeout in seconds (with fractional part as fraction of seconds).

double Wefts::OSFileFuncBase::timeout (   )  const [inline]

Get the standard operation timeout.

virtual file_size_t Wefts::OSFileFuncBase::write (  void *  buffer, const file_size_t  len )  [pure virtual]

Write data to the underlying file. Application should not rely on osError() if the function retunrs a vaild number. file_size_t is the longest integer type provided by the platform. Parameters: buffer  memory area where from which to write len  amount of byte to be written from the memory data Returns: the amount of bytes written to the file, 0 if the timeout has elapsed and -1 on error. On error status() and osError() will return proper values. Implemented in Wefts::OSFileFuncUnix, and Wefts::OSFileFuncWin.

---

Member Data Documentation

int Wefts::OSFileFuncBase::m_osError [protected]

CffStatus Wefts::OSFileFuncBase::m_status [protected]

double Wefts::OSFileFuncBase::m_timeout [protected]

---

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

• wefts_coffee_base.h

---