PTLib: PChannel Class Reference

typedef std::vector<Slice> PChannel::VectorOfSlice

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

Enumerator:

LastReadError	Error during Read() operation.
LastWriteError	Error during Write() operation.
LastGeneralError	Error during other operation, eg Open().
NumErrorGroups

enum PChannel::Errors

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

Enumerator:

NoError
NotFound	Open fail due to device or file not found.
FileExists	Open fail due to file already existing.
DiskFull	Write fail due to disk full.
AccessDenied	Operation fail due to insufficient privilege.
DeviceInUse	Open fail due to device already open for exclusive use.
BadParameter	Operation fail due to bad parameters.
NoMemory	Operation fail due to insufficient memory.
NotOpen	Operation fail due to channel not being open yet.
Timeout	Operation failed due to a timeout.
Interrupted	Operation was interrupted.
BufferTooSmall	Operations buffer was too small for data.
Miscellaneous	Miscellaneous error.
ProtocolFailure	High level protocol failure.
NumNormalisedErrors

enum PChannel::PXBlockType

Enumerator:

PXReadBlock
PXWriteBlock
PXAcceptBlock
PXConnectBlock

enum PChannel::ShutdownValue

Enumerator:

ShutdownRead
ShutdownWrite
ShutdownReadAndWrite

PChannel::PChannel ( )

Create the channel.

PChannel::~PChannel ( )

Close down the channel.

PINLINE PChannel::PChannel ( const PChannel & ) [protected]

PINLINE void PChannel::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.

virtual PBoolean PChannel::Close ( ) [virtual]

Close the channel, shutting down the link to the data source.

Returns:: PTrue if the channel successfully closed.

Reimplemented in PConsoleChannel, PEthSocket, PFile, PIndirectChannel, PPipeChannel, PSerialChannel, PSoundChannel, PFTPClient, PSMTPClient, PPOP3Client, PRFC822Channel, PModem, PMonitoredSocketChannel, PSSLChannel, PWAVFile, and PQueueChannel.

virtual Comparison PChannel::Compare ( const PObject & obj ) const [virtual]

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.

Reimplemented from PObject.

Reimplemented in PFile, PIndirectChannel, PPipeChannel, and PMemoryFile.

virtual PBoolean PChannel::ConvertOSError	(	int	libcReturnValue,
		ErrorGroup	group = `LastGeneralError`
	)			`[protected, virtual]`

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:: PTrue if there was no error.

Parameters:

group

Error group to set

static PBoolean PChannel::ConvertOSError	(	int	libcReturnValue,
		Errors &	lastError,
		int &	osError
	)			`[static]`

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:: PTrue if there was no error.

virtual PChannel* PChannel::GetBaseReadChannel ( ) const [virtual]

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.

Reimplemented in PIndirectChannel.

virtual PChannel* PChannel::GetBaseWriteChannel ( ) const [virtual]

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.

Reimplemented in PIndirectChannel.

PINLINE PChannel::Errors PChannel::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

PINLINE int PChannel::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

static PString PChannel::GetErrorText	(	Errors	lastError,
		int	osError = `0`
	)			`[static]`

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.

virtual PString PChannel::GetErrorText ( ErrorGroup group = NumErrorGroups ) const [virtual]

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

PINLINE int PChannel::GetHandle ( ) const

Get the integer operating system handle for the channel.

Returns:: standard OS descriptor integer.

Reimplemented in PSoundChannel.

virtual PINDEX PChannel::GetLastReadCount ( ) const [virtual]

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
characters will result in the number of bytes returned being less than the size of the buffer supplied.

Returns:: the number of bytes read.

Reimplemented in PSoundChannel.

virtual PINDEX PChannel::GetLastWriteCount ( ) const [virtual]

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
to CR/LF pairs. This will result in the number of bytes returned being more than that requested.

Returns:: the number of bytes written.

Reimplemented in PSoundChannel.

virtual PString PChannel::GetName ( ) const [virtual]

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.

Reimplemented in PConsoleChannel, PFile, PIndirectChannel, PIPSocket, PPipeChannel, and PSoundChannel.

PINLINE PTimeInterval PChannel::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.

PINLINE PTimeInterval PChannel::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.

virtual PINDEX PChannel::HashFunction ( ) const [virtual]

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.

Reimplemented from PObject.

virtual PBoolean PChannel::IsOpen ( ) const [virtual]

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:: PTrue if the channel is open.

Reimplemented in PIndirectChannel, PSoundChannel, and PMonitoredSocketChannel.

virtual void PChannel::OnReadComplete	(	void *	buf,
		PINDEX	len
	)			`[virtual]`

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.

virtual void PChannel::OnWriteComplete	(	const void *	buf,
		PINDEX	len
	)			`[virtual]`

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.

PINLINE PChannel & PChannel::operator= ( const PChannel & ) [protected]

int PChannel::PXClose ( ) [protected]

PBoolean PChannel::PXSetIOBlock	(	PXBlockType	type,
		const PTimeInterval &	timeout
	)			`[protected]`

virtual PBoolean PChannel::Read ( const VectorOfSlice & slices ) [virtual]

Low level scattered read from the channel. This is identical to Read except that the data will be read into a series of scattered memory slices. By default, this call will default to calling Read multiple times, but this may be implemented by operating systems to do a real scattered read

Returns:: PTrue indicates that at least one character was read from the channel. PFalse means no bytes were read due to timeout or some other I/O error.

virtual PBoolean PChannel::Read	(	void *	buf,
		PINDEX	len
	)			`[virtual]`

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 PFalse to determine what caused the failure.

Returns:: PTrue indicates that at least one character was read from the channel. PFalse 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.

Reimplemented in PEthSocket, PFile, PIndirectChannel, PPipeChannel, PSocket, PSoundChannel, PTCPSocket, PUDPSocket, PDelayChannel, PInternetProtocol, PMemoryFile, PMonitoredSocketChannel, PSSLChannel, PWAVFile, PQueueChannel, and PTelnetSocket.

virtual PBoolean PChannel::ReadAsync	(	void *	buf,
		PINDEX	len
	)			`[virtual]`

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:: PTrue 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.

PBoolean PChannel::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:: PTrue 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.

virtual int PChannel::ReadChar ( ) [virtual]

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.

int PChannel::ReadCharWithTimeout ( PTimeInterval & timeout ) [protected]

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:: PTrue if there was no error.

PString PChannel::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.

PBoolean PChannel::ReceiveCommandString	(	int	nextChar,
		const PString &	reply,
		PINDEX &	pos,
		PINDEX	start
	)			`[protected]`

PBoolean PChannel::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: {description} [# #] alert (ascii value 7) [# #] backspace (ascii value 8) [##] formfeed (ascii value 12) [#
#] newline (ascii value 10) [##] return (ascii value 13) [##] horizontal tab (ascii value 9) [##] vertical tab (ascii value 11) [#\#] backslash [##] where ooo is octal number, ascii value ooo [##] where hh is hex number (ascii value 0xhh) [##] null character (ascii zero) [##] delay for n seconds [##] delay for n milliseconds [##] characters following this, up to a command or the end of string, are to be sent to modem [##] characters following this, up to a , or another 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 , or in which case all characters are ignored from the modem until n seconds of no data. [##] as for above but timeout is in milliseconds. {description}

Returns:: PTrue if the command string was completely processed.

Parameters:

command

Command to send to the channel

PBoolean PChannel::SetBufferSize ( PINDEX newSize )

Set the iostream buffer size for reads and writes.

Returns:: PTrue if the new buffer size was set.

Parameters:

newSize

New buffer size

PBoolean PChannel::SetErrorValues	(	Errors	errorCode,
		int	osError,
		ErrorGroup	group = `LastGeneralError`
	)

Set error values to those specified. Return PTrue if errorCode is NoError, PFalse otherwise

Parameters:

errorCode	Error code to translate.
osError	OS error number to translate.
group	Error group to set

PINLINE void PChannel::SetReadTimeout ( const PTimeInterval & time )

Set the timeout for read operations. This may be zero for immediate return of data through to PMaxTimeInterval# 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.

PINLINE void PChannel::SetWriteTimeout ( const PTimeInterval & time )

Set the timeout for write operations to complete. This may be zero for immediate return through to PMaxTimeInterval 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.

virtual PBoolean PChannel::Shutdown ( ShutdownValue option ) [virtual]

Close one or both of the data streams associated with a channel.

The default behavour is to do nothing and return PFalse.

Returns:: PTrue if the shutdown was successfully performed.

virtual PBoolean PChannel::Write ( const VectorOfSlice & slices ) [virtual]

Low level scattered write to the channel. This is identical to Write except that the data will be written from a series of scattered memory slices. By default, this call will default to calling Write multiple times, but this can be actually implemented by operating systems to do a real scattered write

Returns:: PTrue indicates that at least one character was read from the channel. PFalse means no bytes were read due to timeout or some other I/O error.

virtual PBoolean PChannel::Write	(	const void *	buf,
		PINDEX	len
	)			`[virtual]`

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 PFalse to determine what caused the failure.

Returns:: PTrue 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.

Reimplemented in PEthSocket, PFile, PIndirectChannel, PPipeChannel, PSoundChannel, PTCPSocket, PUDPSocket, PDelayChannel, PRFC822Channel, PInternetProtocol, PMemoryFile, PMonitoredSocketChannel, PSSLChannel, PWAVFile, PQueueChannel, and PTelnetSocket.

virtual PBoolean PChannel::WriteAsync	(	const void *	buf,
		PINDEX	len
	)			`[virtual]`

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:: PTrue of the write operation was succesfully queued.

Parameters:

buf	Pointer to a block of memory to write.
len	Number of bytes to write.

PBoolean PChannel::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:: PTrue if the byte was successfully written.

PBoolean PChannel::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:: PTrue if the character written.

PString PChannel::channelName [protected]

Errors PChannel::lastErrorCode[NumErrorGroups+1] [protected]

The platform independant error code.

int PChannel::lastErrorNumber[NumErrorGroups+1] [protected]

The operating system error number (eg as returned by errno).

PINDEX PChannel::lastReadCount [protected]

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

PINDEX PChannel::lastWriteCount [protected]

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

int PChannel::os_handle [protected]

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

PXBlockType PChannel::px_lastBlockType [protected]

PThread* PChannel::px_readThread [protected]

PMutex PChannel::px_selectMutex[3] [protected]

PThread* PChannel::px_selectThread[3] [protected]

PMutex PChannel::px_threadMutex [protected]

PMutex PChannel::px_writeMutex [protected]

PThread* PChannel::px_writeThread [protected]

PTimeInterval PChannel::readTimeout [protected]

Timeout for read operations.

PTimeInterval PChannel::writeTimeout [protected]

Timeout for write operations.

PChannel Class Reference

Scattered read/write functions

Miscellaneous functions

Error functions

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Classes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation


Scattered read/write functions
typedef std::vector< Slice >	VectorOfSlice
virtual PBoolean	Read (const VectorOfSlice &slices)
virtual PBoolean	Write (const VectorOfSlice &slices)
Miscellaneous functions
enum	ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }
virtual PBoolean	Close ()
virtual PBoolean	Shutdown (ShutdownValue option)
PBoolean	SetBufferSize (PINDEX newSize)
PBoolean	SendCommandString (const PString &command)
void	AbortCommandString ()
Error functions
enum	Errors { NoError, NotFound, FileExists, DiskFull, AccessDenied, DeviceInUse, BadParameter, NoMemory, NotOpen, Timeout, Interrupted, BufferTooSmall, Miscellaneous, ProtocolFailure, NumNormalisedErrors }
enum	ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
Errors	GetErrorCode (ErrorGroup group=NumErrorGroups) const
int	GetErrorNumber (ErrorGroup group=NumErrorGroups) const
virtual PString	GetErrorText (ErrorGroup group=NumErrorGroups) const
static PString	GetErrorText (Errors lastError, int osError=0)
Public Types
	ShutdownRead = 0
	ShutdownWrite = 1
	ShutdownReadAndWrite = 2
	NoError
	NotFound
	Open fail due to device or file not found.
	FileExists
	Open fail due to file already existing.
	DiskFull
	Write fail due to disk full.
	AccessDenied
	Operation fail due to insufficient privilege.
	DeviceInUse
	Open fail due to device already open for exclusive use.
	BadParameter
	Operation fail due to bad parameters.
	NoMemory
	Operation fail due to insufficient memory.
	NotOpen
	Operation fail due to channel not being open yet.
	Timeout
	Operation failed due to a timeout.
	Interrupted
	Operation was interrupted.
	BufferTooSmall
	Operations buffer was too small for data.
	Miscellaneous
	Miscellaneous error.
	ProtocolFailure
	High level protocol failure.
	NumNormalisedErrors
	LastReadError
	Error during Read() operation.
	LastWriteError
	Error during Write() operation.
	LastGeneralError
	Error during other operation, eg Open().
	NumErrorGroups
	PXReadBlock
	PXWriteBlock
	PXAcceptBlock
	PXConnectBlock
enum	PXBlockType { PXReadBlock, PXWriteBlock, PXAcceptBlock, PXConnectBlock }
Public Member Functions
PBoolean	SetErrorValues (Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
Construction
	PChannel ()
	Create the channel.
	~PChannel ()
	Close down the channel.
Overrides from class PObject
virtual Comparison	Compare (const PObject &obj) const
virtual PINDEX	HashFunction () const
Information functions
virtual PBoolean	IsOpen () const
virtual PString	GetName () const
int	GetHandle () const
virtual PChannel *	GetBaseReadChannel () const
virtual PChannel *	GetBaseWriteChannel () const
Reading functions
void	SetReadTimeout (const PTimeInterval &time)
PTimeInterval	GetReadTimeout () const
virtual PBoolean	Read (void *buf, PINDEX len)
virtual PINDEX	GetLastReadCount () const
virtual int	ReadChar ()
PBoolean	ReadBlock (void *buf, PINDEX len)
PString	ReadString (PINDEX len)
virtual PBoolean	ReadAsync (void *buf, PINDEX len)
virtual void	OnReadComplete (void *buf, PINDEX len)
Writing functions
void	SetWriteTimeout (const PTimeInterval &time)
PTimeInterval	GetWriteTimeout () const
virtual PBoolean	Write (const void *buf, PINDEX len)
virtual PINDEX	GetLastWriteCount () const
PBoolean	WriteChar (int c)
PBoolean	WriteString (const PString &str)
virtual PBoolean	WriteAsync (const void *buf, PINDEX len)
virtual void	OnWriteComplete (const void *buf, PINDEX len)
Static Public Member Functions
static PBoolean	ConvertOSError (int libcReturnValue, Errors &lastError, int &osError)
Protected Member Functions
	PChannel (const PChannel &)
PChannel &	operator= (const PChannel &)
virtual PBoolean	ConvertOSError (int libcReturnValue, ErrorGroup group=LastGeneralError)
int	ReadCharWithTimeout (PTimeInterval &timeout)
PBoolean	ReceiveCommandString (int nextChar, const PString &reply, PINDEX &pos, PINDEX start)
PBoolean	PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout)
int	PXClose ()
Protected Attributes
int	os_handle
	The operating system file handle return by standard open() function.
Errors	lastErrorCode [NumErrorGroups+1]
	The platform independant error code.
int	lastErrorNumber [NumErrorGroups+1]
	The operating system error number (eg as returned by errno).
PINDEX	lastReadCount
	Number of byte last read by the Read() function.
PINDEX	lastWriteCount
	Number of byte last written by the Write() function.
PTimeInterval	readTimeout
	Timeout for read operations.
PTimeInterval	writeTimeout
	Timeout for write operations.
PString	channelName
PMutex	px_threadMutex
PXBlockType	px_lastBlockType
PThread *	px_readThread
PThread *	px_writeThread
PMutex	px_writeMutex
PThread *	px_selectThread [3]
PMutex	px_selectMutex [3]
Classes
struct	Slice