OS Cooperative File Function Extended Enviroment


Detailed Description

OSCOFFEE is a multiplatform layer for OS level file functions.

In some systems, file function may not be cooperating with threading system.

In example, it's sensible to provide immediate cancelation from system endless waits, caused by a failing network read, so that thread cancelation requests (Thread::stop()) are immediately honored, and proper cleanup actions are taken. Some systems provides support for this behavior, some other don't, some other provides some hooks that should be used by applications to implement this.

OSCOFFEE is a layer that parifies file function cooperativeness with respect to threading library, so that programs can be isomorphic across platforms; no special care must be taken by applications using Wefts's OSCOFFEE to warp around OS deficiencies in helping a good threading model. Wefts++ does it for you.

Other than that, by using OSCOFFEE instead of low level file system operations, you gain immediate portability of the code across all platforms that are supported by wefts. OSCOFFEE use the lowest level available, and it often resolves in just an inlined macro calling those functions; so if you aim to write portable programs, you should rely on OSCOFFEE to access files.

Finally, as functions in OSCOFFEE are limited to file creation, opening, read, write and seek, you may get the raw low level i/o handle and use system specific function where OSCOFFEE is not enough for your needs.

See also:
How to use OS Cooperative File Function Extended Environment layer


Classes

class  Wefts::OSFileFuncBase
 Abstracts an OS specific file fucntion set. More...

class  Wefts::OSProcessBase
 Representation of subprocesses on the platform. More...

class  Wefts::OSFileFuncUnix
 OS COFFEE Unix implementation. More...

class  Wefts::OSFileFuncWin
 Implements COFFEE file specific extensions for MS-Windows. More...


Typedefs

typedef long long Wefts::file_size_t
 The longest integer available on the platform.

typedef OSFileFuncUnix Wefts::OSFileFunc
 Definition that hooks COFFEE in your application.


Enumerations

enum  Wefts::LockMode { Wefts::LM_SHARED, Wefts::LM_SHARED_RO, Wefts::LM_EXCLUSIVE }
 Basic locking schemes used by various systems at open time. More...

enum  Wefts::OpenMode {
  Wefts::OM_RO, Wefts::OM_WO, Wefts::OM_RW, Wefts::OM_TRUNC_WO,
  Wefts::OM_TRUNC_RW, Wefts::OM_APPEND_WO, Wefts::OM_APPEND_RW
}
 Basic open modes used by various systems. More...

enum  Wefts::CreateMode {
  Wefts::CM_ARCHIVE, Wefts::CM_SYSTEM, Wefts::CM_EXECUTABLE, Wefts::CM_PRIVATE,
  Wefts::CM_PRIVATE_EX
}
 Creation modes. More...

enum  Wefts::CffStatus {
  Wefts::CFF_DONE, Wefts::CFF_WAITING, Wefts::CFF_TIMEDOUT, Wefts::CFF_SOFTERROR,
  Wefts::CFF_HARDERROR, Wefts::CFF_PROGERROR
}
 Cooperative File Functions Status. More...

enum  Wefts::SeekWhence { Wefts::SW_FROM_BEGIN = 0, Wefts::SW_FROM_CUR = 1, Wefts::SW_FROM_CURENT = 1, Wefts::SW_FROM_END = 2 }
 Position indicators for file seeks. More...


Typedef Documentation

typedef long long Wefts::file_size_t
 

The longest integer available on the platform.

typedef OSFileFuncWin Wefts::OSFileFunc
 

Definition that hooks COFFEE in your application.


Enumeration Type Documentation

enum Wefts::CffStatus
 

Cooperative File Functions Status.

Cooperative file functions retunrs this os-independent high level status code to inform the caller about the status of the operation, and give the caller the ability to take corrective actions indipendently from operating system error codes.

Theoretically, this would leave operating system error codes only to be used for logging/reporting to use reasons, but if the application still needs to know why the underlying system reported a failure, the OS specific error can be accessed with i.e. OSFileFuncBase::OSerrorCode(); it can be directly used if the application is not meant to be portable, or it's meaning can be decoded in #ifthef OS_TYPE sections, or by subclasses implementing this semantic.

Enumeration values:
CFF_DONE  Operation completed.
CFF_WAITING  Operation cannot be completed immediately...

...but up to date everything is fine.

CFF_TIMEDOUT  Timed out.

There is no phisical error (up to date), but a requested timeout has expired.

As CffStatus is an ordered enum, CFF_WAITING acts as a separator between errors and success (also partial) reports; every CffStatus greater than CFF_WAITING is an error, while any status equal or below CFF_WAITING is a success (or partial success).

CFF_SOFTERROR  Soft error.

There is an error that is catalogued as "soft": usually, this means that operation failed temporarily (i.e. failed to acquire an exclusive lock on an existing file).

CFF_HARDERROR  Hard error.

There is an error that is catalogued as "hard": the operation failed hopelessy.

CFF_PROGERROR  Program's error.

The program is misbehaving, i.e. passing invalid parameters, or invalid file names, or any other thing that should have not happened.

Usually, this should rise an exception, but we don't as the error may be caused with the cooperation of the user. In example, if the user enters a unexisting filename that the program tires to open, the error returned will be CFF_HARDERROR, but if she enters an invalid filename, the error will be CFF_PROGERROR. Anyhow, the program may use this information to feedback the user, so it is not advisable to break the program flow with an exception.

Subclasses of the OS specific COFFEE implementation may rise an exception instead of returning this error in some situation, if they wants to.

enum Wefts::CreateMode
 

Creation modes.

This creation modes are meant to be as portable as possible, and to be just an "indication" for the underlying OS operation on how to create a file. Applications that need a greater control over file creation attribute, and that not need to coordinate file creation with Wefts++, may create the file and then pass the descriptor to the OSFileFunc class they wish to use. Refer to the os-specific OSFileFunc documentation to know what kind of OS-Level file descriptor are accepted.

Also, refer to os-specific implementation documentation to know how this reuqest are interpreted and passed to the underlying system.

Note:
Also if the creation modes mimics the names of known filesystem attributes, they do not necessarily map directly to the attribute they refer to; also they cannot be mixed with an bitwise OR operator.
Enumeration values:
CM_ARCHIVE  Create as a standard archive.
CM_SYSTEM  Create as system-relevant file.
CM_EXECUTABLE  Create a file meant to be executed.

Implementations will behave so that OM_SYSTEM is considered a subset of OM_EXECUTABLE capabilites given to the file. That is, a file created with OM_EXECUTABLE should have all the characteristics of a OM_SYSTEM file, where applicable.

CM_PRIVATE  Creates a file meant to be used only by the creator.
CM_PRIVATE_EX  Creates a file meant to be used or executed only by the creator.

enum Wefts::LockMode
 

Basic locking schemes used by various systems at open time.

Enumeration values:
LM_SHARED 
LM_SHARED_RO 
LM_EXCLUSIVE 

enum Wefts::OpenMode
 

Basic open modes used by various systems.

Enumeration values:
OM_RO  To open the file in read-only mode.
OM_WO  To open the file in write-only mode.
OM_RW  To open the file in read-write mode.
OM_TRUNC_WO  To open the file in write-only mode.

The file is truncated it at beginning if it is not empty. A file open with this flag should not be read nor seeked; the unterlying system may or may not support it.

OM_TRUNC_RW  To open the file in read-write mode.

The file is truncated it at beginning if it is not empty. A file open with this flag should not be read nor seeked; the unterlying system may or may not support it.

OM_APPEND_WO  To open for write-only and position the file pointer at bottom.
OM_APPEND_RW  To open for read-write and position the file pointer at bottom.

enum Wefts::SeekWhence
 

Position indicators for file seeks.

Enumeration values:
SW_FROM_BEGIN  Seek from beginning of file.
SW_FROM_CUR  Seek from current position of file.
SW_FROM_CURENT  Seek from current position of file (synonim of SW_FROM_CUR).
SW_FROM_END  Seek from end of file.


Generated on Tue Oct 5 14:57:01 2004 for Wefts by doxygen 1.3.7