Abstract class defining I/O channel semantics.
![]() | ConvertOSError ( int libcReturnValue, Errors & lastError, int & osError ) Convert an operating system error into platform independent error. |
![]() | Construction |
![]() | Overrides from class PObject |
![]() | Information functions |
![]() | Reading functions |
![]() | Writing functions |
![]() | Miscellaneous functions |
![]() | Error functions |
![]() | os_handle The operating system file handle return by standard open() function. |
![]() | lastErrorCode [NumErrorGroups+1] The platform independant error code. |
![]() | lastErrorNumber [NumErrorGroups+1] The operating system error number (eg as returned by errno). |
![]() | lastReadCount Number of byte last read by the Read() function. |
![]() | lastWriteCount Number of byte last written by the Write() function. |
![]() | readTimeout Timeout for read operations. |
![]() | writeTimeout Timeout for write operations. |
![]() | ConvertOSError ( int libcReturnValue, ErrorGroup group = LastGeneralError ) Convert an operating system error into platform independent error. |
![]() | SetErrorValues ( Errors errorCode, int osError, ErrorGroup group = LastGeneralError ) Set error values to those specified. |
![]() | ReadCharWithTimeout ( PTimeInterval & timeout ) Read a character with specified timeout. |
Run Time Type functions
Comparison functions
I/O functions
Abstract class defining I/O channel semantics. An I/O channel can be a serial port, pipe, network socket or even just a simple file. Anything that requires opening and closing then reading and/or writing from.A descendent would typically have constructors and an Open() function which enables access to the I/O channel it represents. The Read() and Write() functions would then be overridden to the platform and I/O specific mechanisms required.
The general model for a channel is that the channel accepts and/or supplies a stream of bytes. The access to the stream of bytes is via a set of functions that allow certain types of transfer. These include direct transfers, buffered transfers (via iostream) or asynchronous transfers.
The model also has the fundamental state of the channel being
open orclosed . A channel instance that is closed contains sufficient information to describe the channel but does not allocate or lock any system resources. An open channel allocates or locks the particular system resource. The act of opening a channel is a key event that may fail. In this case the channel remains closed and error values are set.
The hash function for strings will produce a value based on the sum of
the first three characters of the string. This is a fairly basic
function and make no assumptions about the string contents. A user may
descend from PString and override the hash function if they can take
advantage of the types of strings being used, eg if all strings start
with the letter 'A' followed by 'B or 'C' then the current hash function
will not perform very well.
virtual PINDEX HashFunction() const
The behaviour for this function is to return "this".
The behaviour for this function is to return "this".
virtual PString GetName() const
int GetHandle() const
virtual PChannel* GetBaseReadChannel() const
virtual PChannel* GetBaseWriteChannel() const
Note that this function may not be available, or meaningfull, for all channels. In that case it is set but ignored.
The GetErrorCode() function should be consulted after Read() returns
FALSE to determine what caused the failure.
Note that the number of bytes read may often be less than that asked
for. Aside from the most common case of being at end of file, which the
applications semantics may regard as an exception, there are some cases
where this is normal. For example, if a PTextFile channel on the
MSDOS platform is read from, then the translation of CR/LF pairs to \n
characters will result in the number of bytes returned being less than
the size of the buffer supplied.
Note that if the channel is not capable of asynchronous read then this
will do a sychronous read is in the Read() function with the addition
of calling the OnReadComplete() before returning.
PTimeInterval GetReadTimeout() const
virtual BOOL Read( void * buf, PINDEX len )
len - Maximum number of bytes to read into the buffer.PINDEX GetLastReadCount() const
virtual int ReadChar()
BOOL ReadBlock( void * buf, PINDEX len )
len - Maximum number of bytes to read into the buffer.PString ReadString(PINDEX len)
virtual BOOL ReadAsync( void * buf, PINDEX len )
len - Maximum number of bytes to read into the buffer.virtual void OnReadComplete( void * buf, PINDEX len )
len - Actual number of bytes to read into the buffer.
Note that this function may not be available, or meaningfull, for all channels. In this case the parameter is et but ignored.
The GetErrorCode() function should be consulted after Write() returns
FALSE to determine what caused the failure.
Note that the number of bytes written may often be less, or even more,
than that asked for. A common case of it being less is where the disk
is full. An example of where the bytes written is more is as follows.
On a PTextFile channel on the MSDOS platform, there is
translation of \n to CR/LF pairs. This will result in the number of
bytes returned being more than that requested.
Note that this asserts if the value is not in the range 0..255.
PTimeInterval GetWriteTimeout() const
virtual BOOL Write( const void * buf, PINDEX len )
len - Number of bytes to write.PINDEX GetLastWriteCount() const
BOOL WriteChar(int c)
BOOL WriteString(const PString & str)
virtual BOOL WriteAsync( const void * buf, PINDEX len )
len - Number of bytes to write.virtual void OnWriteComplete( const void * buf, PINDEX len )
len - Number of bytes to write.
The default behavour is to do nothing and return FALSE.
The escape commands are:
virtual BOOL Shutdown( ShutdownValue option )
BOOL SendCommandString( const PString & command )
void AbortCommandString()
FileExists
DiskFull
AccessDenied
DeviceInUse
BadParameter
NoMemory
NotOpen
Timeout
Interrupted
BufferTooSmall
int GetErrorNumber( ErrorGroup group = NumErrorGroups ) const
virtual PString GetErrorText( ErrorGroup group = NumErrorGroups ) const
static PString GetErrorText( Errors lastError, int osError = 0 )
osError - OS error number to translate.
virtual BOOL ConvertOSError( int libcReturnValue, ErrorGroup group = LastGeneralError )
BOOL SetErrorValues( Errors errorCode, int osError, ErrorGroup group = LastGeneralError )
osError - OS error number to translate.
group - Error group to setint ReadCharWithTimeout( PTimeInterval & timeout )
int os_handle
Errors lastErrorCode[NumErrorGroups+1]
int lastErrorNumber[NumErrorGroups+1]
PINDEX lastReadCount
PINDEX lastWriteCount
Alphabetic index HTML hierarchy of classes or Java