---

Wefts::OSFileFuncWin Class Reference
[Oscoffee]

Implements COFFEE file specific extensions for MS-Windows. More...

#include <wefts_coffee_win.h>

Inheritance diagram for Wefts::OSFileFuncWin:

[legend]Collaboration diagram for Wefts::OSFileFuncWin:

[legend]List of all members.

Public Methods
	OSFileFuncWin (void *descriptor=0)
	~OSFileFuncWin ()
virtual CffStatus	open (std::string filespec, OpenMode openMode=OM_RO, LockMode lockMode=LM_SHARED)
	Creates a file.
virtual CffStatus	create (std::string filespec, CreateMode cMode=CM_ARCHIVE, LockMode lockMode=LM_EXCLUSIVE)
	Creates the file.
virtual void	getDescriptor (void *data) const
	To get the descriptor, pass a pointer to an integer where the descriptor will be placed.
virtual void	setDescriptor (void *data)
	To set the descriptor, pass a pointer to the integer.
virtual file_size_t	read (void *buffer, const file_size_t len)
	Read data from the underlying file.
virtual file_size_t	write (void *buffer, const file_size_t len)
	Write data to the underlying file Application should not rely on osError() if the function retunrs a vaild number.
virtual file_size_t	seek (const file_size_t position, const SeekWhence swFrom=SW_FROM_BEGIN)
	Change the position in the file.
virtual CffStatus	close ()
virtual void	setStdIn ()
	Use STDIN as the handle of this FileFunc object.
virtual void	setStdOut ()
	Use STDOUT as the handle of this FileFunc object.
virtual void	setStdErr ()
	Use STDERR as the handle of this FileFunc object.
Protected Methods
file_size_t	internal_rw (void *buffer, const file_size_t len, bool rw, bool bFile)
Protected Attributes
HANDLE	m_handle
HANDLE	m_evtComplete
LARGE_INTEGER	m_liSize
LARGE_INTEGER	m_liPos
bool	m_bOvlFiles

---

Detailed Description

Implements COFFEE file specific extensions for MS-Windows.

This class is able to understand if the underlying system is capable to do asynchronous file or network operations via OVERLAPPED files; this is possible only with Windows 2000 or later, and only if the target file is not a memory-based character file (that is, a CONSOLE).

If the asynchronous file operations are available, they are used to cleanly cleanup the thread in case of cancelation. If they are not available, two actions may be taken: if cancelation is not allowed in the underlying windows specific OSTAIL, the a blocking read is performed. If cancelation is allowed, then a new thread is started, and the calling thread puts itself in wait for the I/O thread to terminate. The new thread is created with minimal resources available, and it hasn't any data to be cleaned.

In case of cancelation requests arriving while waiting for I/O thread to terminate, the target thread is canceled with TerminateThread(). This is sayed to be an unsafe method (From MSDN), but chances are for the system not allocating resources to be cleaned; this means that this cancelation scheme should be safe, but since internal documentation of ReadFile or WriteFile functions is not available, we cannot be certain.

Anyhow, whenever possible (i.e. whenever it is demonstrable that the I/O call may return data or error in a reasonable time), turn off cancelation BEFORE calling entering read or write methods.

---

Constructor & Destructor Documentation

Wefts::OSFileFuncWin::OSFileFuncWin (  void *    descriptor = 0 )

Wefts::OSFileFuncWin::~OSFileFuncWin (    )  [inline]

---

Member Function Documentation

CffStatus Wefts::OSFileFuncWin::close (    )  [virtual]

Implements Wefts::OSFileFuncBase.

CffStatus Wefts::OSFileFuncWin::create (  std::string    filespec, CreateMode    cMode = CM_ARCHIVE, LockMode    lockMode = LM_EXCLUSIVE )  [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 OpenMode  the file open mode LockScheme  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) Implements Wefts::OSFileFuncBase.

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

To get the descriptor, pass a pointer to an integer where the descriptor will be placed. Implements Wefts::OSFileFuncBase.

file_size_t Wefts::OSFileFuncWin::internal_rw (  void *    buffer, const file_size_t    len, bool    rw, bool    bFile )  [protected]

CffStatus Wefts::OSFileFuncWin::open (  std::string    filespec, OpenMode    openMode = OM_RO, LockMode    lockMode = LM_SHARED )  [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 LockScheme  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) Implements Wefts::OSFileFuncBase.

virtual file_size_t Wefts::OSFileFuncWin::read (  void *    buffer, const file_size_t    len )  [inline, 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. Implements Wefts::OSFileFuncBase.

file_size_t Wefts::OSFileFuncWin::seek (  const file_size_t    position, const SeekWhence    swFrom = SW_FROM_BEGIN )  [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 Implements Wefts::OSFileFuncBase.

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

To set the descriptor, pass a pointer to the integer. Implements Wefts::OSFileFuncBase.

virtual void Wefts::OSFileFuncWin::setStdErr (    )  [inline, virtual]

Use STDERR as the handle of this FileFunc object. Implements Wefts::OSFileFuncBase.

virtual void Wefts::OSFileFuncWin::setStdIn (    )  [inline, virtual]

Use STDIN as the handle of this FileFunc object. Implements Wefts::OSFileFuncBase.

virtual void Wefts::OSFileFuncWin::setStdOut (    )  [inline, virtual]

Use STDOUT as the handle of this FileFunc object. Implements Wefts::OSFileFuncBase.

virtual file_size_t Wefts::OSFileFuncWin::write (  void *    buffer, const file_size_t    len )  [inline, 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. Implements Wefts::OSFileFuncBase.

---

Member Data Documentation

bool Wefts::OSFileFuncWin::m_bOvlFiles [protected]

HANDLE Wefts::OSFileFuncWin::m_evtComplete [protected]

HANDLE Wefts::OSFileFuncWin::m_handle [protected]

LARGE_INTEGER Wefts::OSFileFuncWin::m_liPos [protected]

LARGE_INTEGER Wefts::OSFileFuncWin::m_liSize [protected]

---

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

• wefts_coffee_win.h
• wefts_coffee_win.cpp

---