PChannel Class Reference

Abstract class defining I/O channel semantics. More...

`#include <channel.h>`

Inheritance diagram for PChannel:

## Classes

struct | Slice
| Structure that defines a "slice" of memory to be written to. More...

## Public Types

enum | PXBlockType { PXReadBlock, PXWriteBlock, PXAcceptBlock, PXConnectBlock }
Public Types inherited from PObject
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
| Result of the comparison operation performed by the `Compare()` function. More...

## Public Member Functions

PBoolean | SetErrorValues (Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
| Set error values to those specified. More...
Construction
| PChannel ()
| Create the channel. More...
| ~PChannel ()
| Close down the channel. More...
Overrides from class PObject
virtual Comparison | Compare (const PObject &obj) const
| Get the relative rank of the two strings. More...
virtual PINDEX | HashFunction () const
| Calculate a hash value for use in sets and dictionaries. More...
Information functions
virtual PBoolean | IsOpen () const
| Determine if the channel is currently open. More...
virtual PString | GetName () const
| Get the platform and I/O channel type name of the channel. More...
int | GetHandle () const
| Get the integer operating system handle for the channel. More...
virtual PChannel * | GetBaseReadChannel () const
| Get the base channel of channel indirection using PIndirectChannel. More...
virtual PChannel * | GetBaseWriteChannel () const
| Get the base channel of channel indirection using PIndirectChannel. More...
Reading functions
void | SetReadTimeout (const PTimeInterval &time)
| Set the timeout for read operations. More...
PTimeInterval | GetReadTimeout () const
| Get the timeout for read operations. More...
virtual PBoolean | Read (void *buf, PINDEX len)
| Low level read from the channel. More...
virtual PINDEX | GetLastReadCount () const
| Get the number of bytes read by the last Read() call. More...
virtual int | ReadChar ()
| Read a single 8 bit byte from the channel. More...
PBoolean | ReadBlock (void *buf, PINDEX len)
| Read len bytes into the buffer from the channel. More...
PString | ReadString (PINDEX len)
| Read `len` character into a string from the channel. More...
virtual PBoolean | ReadAsync (void *buf, PINDEX len)
| Begin an asynchronous read from channel. More...
virtual void | OnReadComplete (void *buf, PINDEX len)
| User callback function for when a `ReadAsync()` call has completed or timed out. More...
Writing functions
void | SetWriteTimeout (const PTimeInterval &time)
| Set the timeout for write operations to complete. More...
PTimeInterval | GetWriteTimeout () const
| Get the timeout for write operations to complete. More...
virtual PBoolean | Write (const void *buf, PINDEX len)
| Low level write to the channel. More...
virtual PBoolean | Write (const void *buf, PINDEX len, const void *mark)
| Low level write to the channel with marker. More...
virtual PINDEX | GetLastWriteCount () const
| Get the number of bytes written by the last Write() call. More...
PBoolean | WriteChar (int c)
| Write a single character to the channel. More...
PBoolean | WriteString (const PString &str)
| Write a string to the channel. More...
virtual PBoolean | WriteAsync (const void *buf, PINDEX len)
| Begin an asynchronous write from channel. More...
virtual void | OnWriteComplete (const void *buf, PINDEX len)
| User callback function for when a WriteAsync() call has completed or timed out. More...
Public Member Functions inherited from PObject
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const
| Determine the byte wise comparison of two objects. More...
bool | operator== (const PObject &obj) const
| Compare the two objects. More...
bool | operator!= (const PObject &obj) const
| Compare the two objects. More...
bool | operator< (const PObject &obj) const
| Compare the two objects. More...
bool | operator> (const PObject &obj) const
| Compare the two objects. More...
bool | operator<= (const PObject &obj) const
| Compare the two objects. More...
bool | operator>= (const PObject &obj) const
| Compare the two objects. More...
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified class. More...
virtual void | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the object from the stream. More...

## Static Public Member Functions

static PBoolean | ConvertOSError (int libcReturnValue, Errors &lastError, int &osError)
| Convert an operating system error into platform independent error. More...
Static Public Member Functions inherited from PObject
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
| Internal function caled from CompareObjectMemoryDirect() More...
static const char * | Class ()
| Get the name of the class as a C string. More...

## Protected Member Functions

| PChannel (const PChannel &)
PChannel & | operator= (const PChannel &)
virtual PBoolean | ConvertOSError (int libcReturnValue, ErrorGroup group=LastGeneralError)
| Convert an operating system error into platform independent error. More...
int | ReadCharWithTimeout (PTimeInterval &timeout)
| Read a character with specified timeout. More...
PBoolean | ReceiveCommandString (int nextChar, const PString &reply, PINDEX &pos, PINDEX start)
PBoolean | PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout)
int | PXClose ()
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## Protected Attributes

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. More...
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]

## Miscellaneous functions

enum | ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }
virtual PBoolean | Close ()
| Close the channel, shutting down the link to the data source. More...
virtual PBoolean | Shutdown (ShutdownValue option)
| Close one or both of the data streams associated with a channel. More...
virtual bool | SetLocalEcho (bool localEcho)
| Set local echo mode. More...
virtual bool | FlowControl (const void *flowData)
| Flow Control information Pass data to the channel for flowControl determination. More...
PBoolean | SetBufferSize (PINDEX newSize)
| Set the iostream buffer size for reads and writes. More...
PBoolean | SendCommandString (const PString &command)
| Send a command meta-string. More...
void | AbortCommandString ()
| Abort a command string that is in progress. More...

## Error functions

enum | Errors { NoError, NotFound, FileExists, DiskFull, AccessDenied, DeviceInUse, BadParameter, NoMemory, NotOpen, Timeout, Interrupted, BufferTooSmall, Miscellaneous, ProtocolFailure, NumNormalisedErrors }
| Normalised error codes. More...
enum | ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
| Error groups. More...
Errors | GetErrorCode (ErrorGroup group=NumErrorGroups) const
| Get normalised error code. More...
int | GetErrorNumber (ErrorGroup group=NumErrorGroups) const
| Get OS errro code. More...
virtual PString | GetErrorText (ErrorGroup group=NumErrorGroups) const
| Get error message description. More...
static PString | GetErrorText (Errors lastError, int osError=0)
| Get error message description. More...

## Scattered read/write functions

typedef std::vector< Slice > | VectorOfSlice
virtual PBoolean | Read (const VectorOfSlice &slices)
| Low level scattered read from the channel. More...
virtual PBoolean | Write (const VectorOfSlice &slices)
| Low level scattered write to the channel. More...

## Detailed Description

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.

## Member Typedef Documentation

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

## Member Enumeration Documentation

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

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 |

## Constructor & Destructor Documentation

PChannel::PChannel | ( |  | ) |

Create the channel.

PChannel::~PChannel | ( |  | ) |

Close down the channel.

PChannel::PChannel | ( | const PChannel & |  | ) |

protected

## Member Function Documentation

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
  true if the channel successfully closed.

Reimplemented in PRFC822Channel, PPOP3Client, PVXMLChannel, PSSLChannel, PMonitoredSocketChannel, PSoundChannel, PWAVFile, PPipeChannel, PFile, PVXMLSession, XMPP::Stream, PEthSocket, XMPP::Transport, PSMTPClient, PFTPClient, PMemoryFile, PQueueChannel, PIndirectChannel, PModem, XMPP::C2S::TCPTransport, PConsoleChannel, PVideoChannel, and PSerialChannel.

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 PPipeChannel, PFile, PIndirectChannel, and PMemoryFile.

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

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

Parameters

  libcReturnValue | Return value from standard library
  group | Error group to set

Reimplemented in PSSLChannel.

virtual bool PChannel::FlowControl | ( | const void * | flowData | ) |

virtual

Flow Control information Pass data to the channel for flowControl determination.

Reimplemented in PVideoChannel.

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.

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

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

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

Reimplemented in PSSLChannel, and PIndirectChannel.

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.

int PChannel::GetHandle | ( |  | ) | const

Get the integer operating system handle for the channel.

Returns
  standard OS descriptor integer.

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 PSoundChannel, PIPSocket, PPipeChannel, PFile, PIndirectChannel, PVideoChannel, and PConsoleChannel.

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.

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

Reimplemented in PVXMLChannel, PMonitoredSocketChannel, PSoundChannel, PIndirectChannel, and PVideoChannel.

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.

PChannel& PChannel::operator= | ( | const PChannel & |  | ) |

protected

int PChannel::PXClose | ( |  | ) |

protected

PBoolean PChannel::PXSetIOBlock | ( | PXBlockType | type,
|  | const PTimeInterval & | timeout
| ) |  |

protected

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

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

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

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

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

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
  true 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.

Parameters

  len | Length of string data to 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:

\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

PBoolean PChannel::SetBufferSize | ( | PINDEX | newSize | ) |

Set the iostream buffer size for reads and writes.

Returns
  true 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 true if errorCode is NoError, false otherwise

Parameters

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

virtual bool PChannel::SetLocalEcho | ( | bool | localEcho | ) |

virtual

Set local echo mode.

For some classes of channel, e.g. PConsoleChannel, data read by this channel is automatically echoed. This disables the function so things like password entry can work.

Default behaviour does nothing and return true if the channel is open.

Reimplemented in PIndirectChannel, PTelnetSocket, and PConsoleChannel.

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.

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 false.

Returns
  true if the shutdown was successfully performed.

Reimplemented in PSSLChannel, PIndirectChannel, and PSocket.

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

Reimplemented in PRFC822Channel, PSoundChannel, PVXMLChannel, PMonitoredSocketChannel, PSSLChannel, PWAVFile, PPipeChannel, PDelayChannel, PFile, PEthSocket, XMPP::Stream, PMemoryFile, PIndirectChannel, PVideoChannel, PTCPSocket, PInternetProtocol, PQueueChannel, PCLI::Context, PUDPSocket, and PTelnetSocket.

virtual PBoolean PChannel::Write | ( | const void * | buf,
|  | PINDEX | len,
|  | const void * | mark
| ) |  |

virtual

Low level write to the channel with marker.

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. By default it calls the Write(void *,len) function

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.
  mark | Unique Marker to identify write

Reimplemented in PSoundChannel.

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

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
  true 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
  true 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
  true if the character written.

## Member Data Documentation

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.

Referenced by PWAVFile::SetLastReadCount().

PINDEX PChannel::lastWriteCount

protected

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

Referenced by PWAVFile::SetLastWriteCount().

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.

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

- channel.h