class PChannel: public PObject, public iostream

Abstract class defining I/O channel semantics.

Inheritance:


Public Methods

[more]static BOOL ConvertOSError ( int libcReturnValue, Errors & lastError, int & osError )
Convert an operating system error into platform independent error.

Public

[more] Construction
[more] Overrides from class PObject
[more] Information functions
[more] Reading functions
[more] Writing functions
[more] Miscellaneous functions
[more] Error functions

Protected Fields

[more]int os_handle
The operating system file handle return by standard open() function.
[more]Errors lastErrorCode [NumErrorGroups+1]
The platform independant error code.
[more]int lastErrorNumber [NumErrorGroups+1]
The operating system error number (eg as returned by errno).
[more]PINDEX lastReadCount
Number of byte last read by the Read() function.
[more]PINDEX lastWriteCount
Number of byte last written by the Write() function.
[more]PTimeInterval readTimeout
Timeout for read operations.
[more]PTimeInterval writeTimeout
Timeout for write operations.

Protected Methods

[more]virtual BOOL ConvertOSError ( int libcReturnValue, ErrorGroup group = LastGeneralError )
Convert an operating system error into platform independent error.
[more]BOOL SetErrorValues ( Errors errorCode, int osError, ErrorGroup group = LastGeneralError )
Set error values to those specified.
[more]int ReadCharWithTimeout ( PTimeInterval & timeout )
Read a character with specified timeout.


Inherited from PObject:

Public

Run Time Type functions

Comparison functions

I/O functions


Documentation

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 or closed. 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.

o Construction

o PChannel()
Create the channel.

o ~PChannel()
Close down the channel.

o Overrides from class PObject

ovirtual Comparison Compare( const PObject & obj ) const
Get the relative rank of the two strings. The system standard function, eg strcmp(), is used.

Returns:
comparison of the two objects, EqualTo for same, LessThan for obj logically less than the object and GreaterThan for obj logically greater than the object.
Parameters:
obj - Other PString to compare against.

ovirtual PINDEX HashFunction() const
Calculate a hash value for use in sets and dictionaries.

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.

Returns:
hash value for string.

o Information functions

ovirtual BOOL IsOpen() const
Determine if the channel is currently open. This indicates that read and write operations can be executed on the channel. For example, in the PFile class it returns if the file is currently open.

Returns:
TRUE if the channel is open.

ovirtual PString GetName() const
Get the platform and I/O channel type name of the channel. For example, it would return the filename in PFile type channels.

Returns:
the name of the channel.

oint GetHandle() const
Get the integer operating system handle for the channel.

Returns:
standard OS descriptor integer.

ovirtual PChannel* GetBaseReadChannel() const
Get the base channel of channel indirection using PIndirectChannel. This function returns the eventual base channel for reading of a series of indirect channels provided by descendents of PIndirectChannel.

The behaviour for this function is to return "this".

Returns:
Pointer to base I/O channel for the indirect channel.

ovirtual PChannel* GetBaseWriteChannel() const
Get the base channel of channel indirection using PIndirectChannel. This function returns the eventual base channel for writing of a series of indirect channels provided by descendents of PIndirectChannel.

The behaviour for this function is to return "this".

Returns:
Pointer to base I/O channel for the indirect channel.

o Reading functions

ovoid SetReadTimeout( const PTimeInterval & time )
Set the timeout for read operations. This may be zero for immediate return of data through to PMaxMilliseconds which will wait forever for the read request to be filled.

Note that this function may not be available, or meaningfull, for all channels. In that case it is set but ignored.

Parameters:
time - The new time interval for read operations.

oPTimeInterval GetReadTimeout() const
Get the timeout for read operations. Note that this function may not be available, or meaningfull, for all channels. In that case it returns the previously set value.

Returns:
time interval for read operations.

ovirtual BOOL Read( void * buf, PINDEX len )
Low level read from the channel. This function may block until the requested number of characters were read or the read timeout was reached. The GetLastReadCount() function returns the actual number of bytes read.

The GetErrorCode() function should be consulted after Read() returns FALSE to determine what caused the failure.

Returns:
TRUE indicates that at least one character was read from the channel. FALSE means no bytes were read due to timeout or some other I/O error.
Parameters:
buf - Pointer to a block of memory to receive the read bytes.
len - Maximum number of bytes to read into the buffer.

oPINDEX GetLastReadCount() const
Get the number of bytes read by the last Read() call. This will be from 0 to the maximum number of bytes as passed to the Read() call.

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.

Returns:
the number of bytes read.

ovirtual int ReadChar()
Read a single 8 bit byte from the channel. If one was not available within the read timeout period, or an I/O error occurred, then the function gives with a -1 return value.

Returns:
byte read or -1 if no character could be read.

oBOOL ReadBlock( void * buf, PINDEX len )
Read len bytes into the buffer from the channel. This function uses Read(), so most remarks pertaining to that function also apply to this one. The only difference being that this function will not return until all of the bytes have been read, or an error occurs.

Returns:
TRUE if the read of len bytes was sucessfull.
Parameters:
buf - Pointer to a block of memory to receive the read bytes.
len - Maximum number of bytes to read into the buffer.

oPString ReadString(PINDEX len)
Read len character into a string from the channel. This function simply uses ReadBlock(), so all remarks pertaining to that function also apply to this one.

Returns:
String that was read.

ovirtual BOOL ReadAsync( void * buf, PINDEX len )
Begin an asynchronous read from channel. The read timeout is used as in other read operations, in this case calling the OnReadComplete() function.

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.

Returns:
TRUE if the read was sucessfully queued.
Parameters:
buf - Pointer to a block of memory to receive the read bytes.
len - Maximum number of bytes to read into the buffer.

ovirtual void OnReadComplete( void * buf, PINDEX len )
User callback function for when a ReadAsync() call has completed or timed out. The original pointer to the buffer passed in ReadAsync() is passed to the function.
Parameters:
buf - Pointer to a block of memory that received the read bytes.
len - Actual number of bytes to read into the buffer.

o Writing functions

ovoid SetWriteTimeout( const PTimeInterval & time )
Set the timeout for write operations to complete. This may be zero for immediate return through to PMaxMilliseconds which will wait forever for the write request to be completed.

Note that this function may not be available, or meaningfull, for all channels. In this case the parameter is et but ignored.

Parameters:
time - The new time interval for write operations.

oPTimeInterval GetWriteTimeout() const
Get the timeout for write operations to complete. Note that this function may not be available, or meaningfull, for all channels. In that case it returns the previously set value.

Returns:
time interval for writing.

ovirtual BOOL Write( const void * buf, PINDEX len )
Low level write to the channel. This function will block until the requested number of characters are written or the write timeout is reached. The GetLastWriteCount() function returns the actual number of bytes written.

The GetErrorCode() function should be consulted after Write() returns FALSE to determine what caused the failure.

Returns:
TRUE if at least len bytes were written to the channel.
Parameters:
buf - Pointer to a block of memory to write.
len - Number of bytes to write.

oPINDEX GetLastWriteCount() const
Get the number of bytes written by the last Write() call.

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.

Returns:
the number of bytes written.

oBOOL WriteChar(int c)
Write a single character to the channel. This function simply uses the Write() function so all comments on that function also apply.

Note that this asserts if the value is not in the range 0..255.

Returns:
TRUE if the byte was successfully written.

oBOOL WriteString(const PString & str)
Write a string to the channel. This function simply uses the Write() function so all comments on that function also apply.

Returns:
TRUE if the character written.

ovirtual BOOL WriteAsync( const void * buf, PINDEX len )
Begin an asynchronous write from channel. The write timeout is used as in other write operations, in this case calling the OnWriteComplete() function. Note that if the channel is not capable of asynchronous write then this will do a sychronous write as in the Write() function with the addition of calling the OnWriteComplete() before returning.

Returns:
TRUE of the write operation was succesfully queued.
Parameters:
buf - Pointer to a block of memory to write.
len - Number of bytes to write.

ovirtual void OnWriteComplete( const void * buf, PINDEX len )
User callback function for when a WriteAsync() call has completed or timed out. The original pointer to the buffer passed in WriteAsync() is passed in here and the len parameter is the actual number of characters written.
Parameters:
buf - Pointer to a block of memory to write.
len - Number of bytes to write.

o Miscellaneous functions

ovirtual BOOL Close()
Close the channel, shutting down the link to the data source.

Returns:
TRUE if the channel successfully closed.

ovirtual BOOL Shutdown( ShutdownValue option )
Close one or both of the data streams associated with a channel.

The default behavour is to do nothing and return FALSE.

Returns:
TRUE if the shutdown was successfully performed.

oBOOL SendCommandString( const PString & command )
Send a command meta-string. A meta-string is a string of characters that may contain escaped commands. The escape command is the as in the C language.

The escape commands are:

\a
alert (ascii value 7)
\b
backspace (ascii value 8)
\f
formfeed (ascii value 12)
\n
newline (ascii value 10)
\r
return (ascii value 13)
\t
horizontal tab (ascii value 9)
\v
vertical tab (ascii value 11)
\\
backslash
\ooo
where ooo is octal number, ascii value ooo
\xhh
where hh is hex number (ascii value 0xhh)
\0
null character (ascii zero)
\dns
delay for n seconds
\dnm
delay for n milliseconds
\s
characters following this, up to a \w command or the end of string, are to be sent to modem
\wns
characters following this, up to a \s, \d or another \w or the end of the string are expected back from the modem. If the string is not received within n seconds, a failed command is registered. The exception to this is if the command is at the end of the string or the next character in the string is the \s, \d or \w in which case all characters are ignored from the modem until n seconds of no data.
\wnm
as for above but timeout is in milliseconds.
Returns:
TRUE if the command string was completely processed.
Parameters:
command - Command to send to the channel

ovoid AbortCommandString()
Abort a command string that is in progress. Note that as the SendCommandString() function blocks the calling thread when it runs, this can only be called from within another thread.

o Error functions

oenum Errors
Normalised error codes. The error result of the last file I/O operation in this object.

o NotFound
Open fail due to device or file not found

o FileExists
Open fail due to file already existing

o DiskFull
Write fail due to disk full

o AccessDenied
Operation fail due to insufficient privilege

o DeviceInUse
Open fail due to device already open for exclusive use

o BadParameter
Operation fail due to bad parameters

o NoMemory
Operation fail due to insufficient memory

o NotOpen
Operation fail due to channel not being open yet

o Timeout
Operation failed due to a timeout

o Interrupted
Operation was interrupted

o BufferTooSmall
Operations buffer was too small for data.

o Miscellaneous
Miscellaneous error.

o ProtocolFailure
High level protocol failure

oenum ErrorGroup
Error groups. To aid in multithreaded applications where reading and writing may be happening simultaneously, read and write errors are separated from other errors.

o LastWriteError
Error during Read() operation

o LastGeneralError
Error during Write() operation

o NumErrorGroups
Error during other operation, eg Open()

oErrors GetErrorCode( ErrorGroup group = NumErrorGroups ) const
Get normalised error code. Return the error result of the last file I/O operation in this object.
Returns:
Normalised error code.
Parameters:
group - Error group to get

oint GetErrorNumber( ErrorGroup group = NumErrorGroups ) const
Get OS errro code. Return the operating system error number of the last file I/O operation in this object.
Returns:
Operating System error code.
Parameters:
group - Error group to get

ovirtual PString GetErrorText( ErrorGroup group = NumErrorGroups ) const
Get error message description. Return a string indicating the error message that may be displayed to the user. The error for the last I/O operation in this object is used.
Returns:
Operating System error description string.
Parameters:
group - Error group to get

ostatic PString GetErrorText( Errors lastError, int osError = 0 )
Get error message description. Return a string indicating the error message that may be displayed to the user. The osError parameter is used unless zero, in which case the lastError parameter is used.
Returns:
Operating System error description string.
Parameters:
lastError - Error code to translate.
osError - OS error number to translate.

ostatic BOOL ConvertOSError( int libcReturnValue, Errors & lastError, int & osError )
Convert an operating system error into platform independent error. This will set the lastError and osError member variables for access by GetErrorCode() and GetErrorNumber().

Returns:
TRUE if there was no error.

ovirtual BOOL ConvertOSError( int libcReturnValue, ErrorGroup group = LastGeneralError )
Convert an operating system error into platform independent error. The internal error codes are set by this function. They may be obtained via the GetErrorCode() and GetErrorNumber() functions.

Returns:
TRUE if there was no error.
Parameters:
group - Error group to set

oBOOL SetErrorValues( Errors errorCode, int osError, ErrorGroup group = LastGeneralError )
Set error values to those specified. Return TRUE if errorCode is NoError, FALSE otherwise
Parameters:
errorCode - Error code to translate.
osError - OS error number to translate.
group - Error group to set

oint ReadCharWithTimeout( PTimeInterval & timeout )
Read a character with specified timeout. This reads a single character from the channel waiting at most the amount of time specified for it to arrive. The timeout parameter is adjusted for amount of time it actually took, so it can be used for a multiple character timeout.

Returns:
TRUE if there was no error.

oint os_handle
The operating system file handle return by standard open() function.

oErrors lastErrorCode[NumErrorGroups+1]
The platform independant error code.

oint lastErrorNumber[NumErrorGroups+1]
The operating system error number (eg as returned by errno).

oPINDEX lastReadCount
Number of byte last read by the Read() function.

oPINDEX lastWriteCount
Number of byte last written by the Write() function.

oPTimeInterval readTimeout
Timeout for read operations.

oPTimeInterval writeTimeout
Timeout for write operations.


Direct child classes:
PTerminalChannel
PSocket
PVideoChannel
PSoundChannel
PSerialChannel
PPipeChannel
PIndirectChannel
PFile
PConsoleChannel

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.