class PIndirectChannel: public PChannel

This is a channel that operates indirectly through another channel(s).

Inheritance:


Public

[more] Construction
[more] Overrides from class PObject
[more] Overrides from class PChannel
[more] Channel establish functions

Protected Fields

[more]PChannel* readChannel
Channel for read operations.
[more]BOOL readAutoDelete
Automatically delete read channel on destruction.
[more]PChannel* writeChannel
Channel for write operations.
[more]BOOL writeAutoDelete
Automatically delete write channel on destruction.
[more]PReadWriteMutex channelPointerMutex
Race condition prevention on closing channel

Protected Methods

[more]virtual BOOL OnOpen ()
This callback is executed when the Open() function is called with open channels.


Inherited from PChannel:

Public Methods

ostatic BOOL ConvertOSError( int libcReturnValue, Errors & lastError, int & osError )

Public

Information functions

Reading functions

Writing functions

Miscellaneous functions

Error functions

Protected Fields

oint os_handle
oErrors lastErrorCode[NumErrorGroups+1]
oint lastErrorNumber[NumErrorGroups+1]
oPINDEX lastReadCount
oPINDEX lastWriteCount
oPTimeInterval readTimeout
oPTimeInterval writeTimeout

Protected Methods

ovirtual BOOL ConvertOSError( int libcReturnValue, ErrorGroup group = LastGeneralError )
oBOOL SetErrorValues( Errors errorCode, int osError, ErrorGroup group = LastGeneralError )
oint ReadCharWithTimeout( PTimeInterval & timeout )


Inherited from PObject:

Public

Run Time Type functions

Comparison functions

I/O functions


Documentation

This is a channel that operates indirectly through another channel(s). This allows for a protocol to operate through a "channel" mechanism and for its low level byte exchange (Read and Write) to operate via a completely different channel, eg TCP or Serial port etc.
o Construction

o PIndirectChannel()
Create a new indirect channel without any channels to redirect to. If an attempt to read or write is made before Open() is called the the functions will assert.

o ~PIndirectChannel()
Close the indirect channel, deleting read/write channels if desired.

o Overrides from class PObject

oComparison Compare( const PObject & obj ) const
Determine if the two objects refer to the same indirect channel. This actually compares the channel pointers.

Returns:
EqualTo if channel pointer identical.
Parameters:
obj - Another indirect channel to compare against.

o Overrides from class PChannel

ovirtual PString GetName() const
Get the name of the channel. This is a combination of the channel pointers names (or simply the channel pointers name if the read and write channels are the same) or empty string if both null.

Returns:
string for the channel names.

ovirtual BOOL Close()
Close the channel. This will detach itself from the read and write channels and delete both of them if they are auto delete.

Returns:
TRUE if the channel is closed.

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

Returns:
TRUE if the channel is open.

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.

This will use the readChannel pointer to actually do the read. If readChannel is null the this asserts.

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.

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.

This will use the writeChannel pointer to actually do the write. If writeChannel is null the this asserts.

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.

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

The behavour here is to pass the shutdown on to its read and write channels.

Returns:
TRUE if the shutdown was successfully performed.
Parameters:
option - Flag for shut down of read, write or both.

ovirtual PChannel* GetBaseReadChannel() const
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
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.

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

o Channel establish functions

oBOOL Open( PChannel & channel )
Set the channel for both read and write operations. This then checks that they are open and then calls the OnOpen() virtual function. If it in turn returns TRUE then the Open() function returns success.

Returns:
TRUE if both channels are set, open and OnOpen() returns TRUE.
Parameters:
channel - Channel to be used for both read and write operations.

oBOOL Open( PChannel * channel, BOOL autoDelete = TRUE )
Set the channel for both read and write operations. This then checks that they are open and then calls the OnOpen() virtual function. If it in turn returns TRUE then the Open() function returns success.

The channel pointed to by channel may be automatically deleted when the PIndirectChannel is destroyed or a new subchannel opened.

Returns:
TRUE if both channels are set, open and OnOpen() returns TRUE.
Parameters:
channel - Channel to be used for both read and write operations.
autoDelete - Automatically delete the channel

oBOOL Open( PChannel * readChannel, PChannel * writeChannel, BOOL autoDeleteRead = TRUE, BOOL autoDeleteWrite = TRUE )
Set the channel for both read and write operations. This then checks that they are open and then calls the OnOpen() virtual function. If it in turn returns TRUE then the Open() function returns success.

The channels pointed to by readChannel and writeChannel may be automatically deleted when the PIndirectChannel is destroyed or a new subchannel opened.

Returns:
TRUE if both channels are set, open and OnOpen() returns TRUE.

oPChannel* GetReadChannel() const
Get the channel used for read operations.

Returns:
pointer to the read channel.

oBOOL SetReadChannel( PChannel * channel, BOOL autoDelete = TRUE )
Set the channel for read operations.

Returns:
Returns TRUE if both channels are set and are both open.
Parameters:
channel - Channel to be used for both read operations.
autoDelete - Automatically delete the channel

oPChannel* GetWriteChannel() const
Get the channel used for write operations.

Returns:
pointer to the write channel.

oBOOL SetWriteChannel( PChannel * channel, BOOL autoDelete = TRUE )
Set the channel for read operations.

Returns:
Returns TRUE if both channels are set and are both open.
Parameters:
channel - Channel to be used for both write operations.
autoDelete - Automatically delete the channel

ovirtual BOOL OnOpen()
This callback is executed when the Open() function is called with open channels. It may be used by descendent channels to do any handshaking required by the protocol that channel embodies.

The default behaviour is to simply return TRUE.

Returns:
Returns TRUE if the protocol handshaking is successful.

oPChannel* readChannel
Channel for read operations.

oBOOL readAutoDelete
Automatically delete read channel on destruction.

oPChannel* writeChannel
Channel for write operations.

oBOOL writeAutoDelete
Automatically delete write channel on destruction.

oPReadWriteMutex channelPointerMutex
Race condition prevention on closing channel


Direct child classes:
PSSLChannel
PRFC822Channel
PInternetProtocol

Alphabetic index HTML hierarchy of classes or Java



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