A TCP/IP socket for process/application layer high level protocols. More...

#include <inetprot.h>

Inheritance diagram for PInternetProtocol:

Collaboration diagram for PInternetProtocol:

Public Member Functions
virtual PBoolean	Read (void *buf, PINDEX len)
	Low level read from the channel. More...

virtual int	ReadChar ()
	Read a single 8 bit byte from the channel. More...

virtual PBoolean	Write (const void *buf, PINDEX len)
	Low level write to the channel. More...

void	SetReadLineTimeout (const PTimeInterval &t)
	Set the maximum timeout between characters within a line. More...

virtual PBoolean	Connect (const PString &address, WORD port=0)
	Connect a socket to a remote host for the internet protocol. More...

virtual PBoolean	Connect (const PString &address, const PString &service)

virtual PBoolean	Accept (PSocket &listener)
	Accept a server socket to a remote host for the internet protocol. More...

const PString &	GetDefaultService () const
	Get the default service name or port number to use in socket connections. More...

PIPSocket *	GetSocket () const
	Get the eventual socket for the series of indirect channels that may be between the current protocol and the actual I/O channel. More...

virtual PBoolean	WriteLine (const PString &line)
	Write a string to the socket channel followed by a CR/LF pair. More...

virtual PBoolean	ReadLine (PString &line, PBoolean allowContinuation=false)
	Read a string from the socket channel up to a CR/LF pair. More...

virtual void	UnRead (int ch)
	Put back the characters into the data stream so that the next Read() function call will return them first. More...

virtual void	UnRead (const PString &str)

virtual void	UnRead (const void *buffer, PINDEX len)

virtual bool	WriteCommand (PINDEX cmdNumber, const PString &param=PString::Empty())
	Write a single line for a command. More...

virtual bool	WriteCommand (PINDEX cmdNumber, const PString &param, const PMIMEInfo &mime)

virtual PBoolean	ReadCommand (PINDEX &num, PString &args)
	Read a single line of a command which ends with a CR/LF pair. More...

virtual PBoolean	ReadCommand (PINDEX &num, PString &args, PMIMEInfo &mime)

virtual PBoolean	WriteResponse (unsigned numericCode, const PString &info)
	Write a response code followed by a text string describing the response to a command. More...

virtual PBoolean	WriteResponse (const PString &code, const PString &info)

virtual PBoolean	ReadResponse ()
	Read a response code followed by a text string describing the response to a command. More...

virtual PBoolean	ReadResponse (int &code, PString &info)

virtual PBoolean	ReadResponse (int &code, PString &info, PMIMEInfo &mime)

virtual int	ExecuteCommand (PINDEX cmdNumber)
	Write a command to the socket, using `WriteCommand()` and await a response using `ReadResponse()`. More...

virtual int	ExecuteCommand (PINDEX cmdNumber, const PString &param)

int	GetLastResponseCode () const
	Return the code associated with the last response received by the socket. More...

PString	GetLastResponseInfo () const
	Return the last response received by the socket. More...

Public Member Functions inherited from PIndirectChannel
	PIndirectChannel ()
	Create a new indirect channel without any channels to redirect to. More...

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

Comparison	Compare (const PObject &obj) const
	Determine if the two objects refer to the same indirect channel. More...

virtual PString	GetName () const
	Get the name of the channel. More...

virtual P_INT_PTR	GetHandle () const
	Get the OS specific handle for the PSoundChannel. More...

virtual PBoolean	Close ()
	Close the channel. More...

virtual PBoolean	IsOpen () const
	Determine if the channel is currently open and read and write operations can be executed on it. 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 PChannel *	GetBaseReadChannel () const
	This function returns the eventual base channel for reading of a series of indirect channels provided by descendents of `PIndirectChannel`. More...

virtual PChannel *	GetBaseWriteChannel () const
	This function returns the eventual base channel for writing of a series of indirect channels provided by descendents of `PIndirectChannel`. More...

virtual PString	GetErrorText (ErrorGroup group=NumErrorGroups) const
	Get error message description. More...

PBoolean	Open (PChannel &channel)
	Set the channel for both read and write operations. More...

PBoolean	Open (PChannel *channel, PBoolean autoDelete=true)
	Set the channel for both read and write operations. More...

PBoolean	Open (PChannel readChannel, PChannel writeChannel, PBoolean autoDeleteRead=true, PBoolean autoDeleteWrite=true)
	Set the channel for both read and write operations. More...

PChannel *	Detach (ShutdownValue option=ShutdownReadAndWrite)
	Detach without closing the read/write channel. More...

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

bool	SetReadChannel (PChannel *channel, bool autoDelete=true, bool closeExisting=false)
	Set the channel for read operations. More...

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

PBoolean	SetWriteChannel (PChannel *channel, bool autoDelete=true, bool closeExisting=false)
	Set the channel for read operations. More...

Public Member Functions inherited from PChannel
PBoolean	SetErrorValues (Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
	Set error values to those specified. More...

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

FILE *	FDOpen (const char *mode)
	Re-open the device using the stdio library. More...

void	SetReadTimeout (const PTimeInterval &time)
	Set the timeout for read operations. More...

PTimeInterval	GetReadTimeout () const
	Get the timeout for read operations. More...

PINDEX	GetLastReadCount () const
	Get the number of bytes read by the last Read() call. 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...

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, const void )
	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...

	~PChannel ()
	Close down the channel. More...

Errors	GetErrorCode (ErrorGroup group=NumErrorGroups) const
	Get normalised error code. More...

int	GetErrorNumber (ErrorGroup group=NumErrorGroups) const
	Get OS errro code. More...

virtual bool	ReadAsync (AsyncContext &context)
	Begin an asynchronous read from channel. More...

virtual void	OnReadComplete (AsyncContext &context)
	User callback function for when a `ReadAsync()` call has completed or timed out. More...

virtual bool	WriteAsync (AsyncContext &context)
	Begin an asynchronous write from channel. More...

virtual void	OnWriteComplete (AsyncContext &context)
	User callback function for when a WriteAsync() call has completed or timed out. 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...

Public Member Functions inherited from PObject
unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

void	SetTraceContextIdentifier (unsigned id)

void	GetTraceContextIdentifier (PObject &obj)

void	GetTraceContextIdentifier (PObject *obj)

void	SetTraceContextIdentifier (const PObject &obj)

void	SetTraceContextIdentifier (const PObject *obj)

virtual	~PObject ()

virtual PObject *	Clone () const
	Create a copy of the class on the heap. More...

template<class CLS >
CLS *	CloneAs () const
	As for Clone() but converts to specified type. 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...

__inline const PObject *	PTraceObjectInstance () const

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

Protected Types
enum	StuffState { DontStuff, StuffIdle, StuffCR, StuffCRLF, StuffCRLFdot, StuffCRLFdotCR }

Protected Member Functions
	PInternetProtocol (const char defaultServiceName, PINDEX cmdCount, char const const *cmdNames)

virtual PINDEX	ParseResponse (const PString &line)
	Parse a response line string into a response code and any extra info on the line. More...

Protected Member Functions inherited from PIndirectChannel
virtual PBoolean	OnOpen ()
	This callback is executed when the Open() function is called with open channels. More...

Protected Member Functions inherited from PChannel
	PChannel (const PChannel &)

PChannel &	operator= (const PChannel &)

virtual PBoolean	ConvertOSError (P_INT_PTR 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)

virtual int	os_errno () const

PBoolean	PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout)

P_INT_PTR	GetOSHandleAsInt () const

int	PXClose ()

	PChannel ()
	Create the channel. More...

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Protected Attributes
PString	defaultServiceName

PStringArray	commandNames

PCharArray	unReadBuffer

PINDEX	unReadCount

PTimeInterval	readLineTimeout

enum PInternetProtocol::StuffState	stuffingState

PBoolean	newLineToCRLF

int	lastResponseCode

PString	lastResponseInfo

Protected Attributes inherited from PIndirectChannel
PChannel *	readChannel
	Channel for read operations. More...

PBoolean	readAutoDelete
	Automatically delete read channel on destruction. More...

PChannel *	writeChannel
	Channel for write operations. More...

PBoolean	writeAutoDelete
	Automatically delete write channel on destruction. More...

PReadWriteMutex	channelPointerMutex
	Race condition prevention on closing channel. More...

Protected Attributes inherited from PChannel
P_INT_PTR	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
	Name of channel. More...

PMutex	px_threadMutex

PXBlockType	px_lastBlockType

PThread *	px_readThread

PThread *	px_writeThread

PMutex	px_writeMutex

PThread *	px_selectThread [3]

PMutex	px_selectMutex [3]

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

Additional Inherited Members
Public Types inherited from PChannel
enum	PXBlockType { PXReadBlock, PXWriteBlock, PXAcceptBlock, PXConnectBlock }

enum	Errors { NoError, NotFound, FileExists, DiskFull, AccessDenied, DeviceInUse, BadParameter, NoMemory, NotOpen, Timeout, Interrupted, BufferTooSmall, Miscellaneous, ProtocolFailure, Unavailable, NumNormalisedErrors }
	Normalised error codes. More...

enum	ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
	Error groups. More...

typedef PNotifierTemplate < PChannel::AsyncContext & >	AsyncNotifier

enum	ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }

Static Public Member Functions inherited from PChannel
static PString	GetErrorText (Errors lastError, int osError=0)
	Get error message description. 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...

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

Friends inherited from PObject

Detailed Description

A TCP/IP socket for process/application layer high level protocols.

All of these protocols execute commands and responses in a standard manner.

A command consists of a line starting with a short, case insensitive command string terminated by a space or the end of the line. This may be followed by optional arguments.

A response to a command is usually a number and/or a short string eg "OK". The response may be followed by additional information about the response but this is not typically used by the protocol. It is only for user information and may be tracked in log files etc.

All command and reponse lines of the protocol are terminated by a CR/LF pair. A command or response line may be followed by additional data as determined by the protocol, but this data is "outside" the protocol specification as defined by this class.

The default read timeout is to 10 minutes by the constructor.

Member Enumeration Documentation

enum PInternetProtocol::StuffState

protected

Enumerator
DontStuff
StuffIdle
StuffCR
StuffCRLF
StuffCRLFdot
StuffCRLFdotCR

Constructor & Destructor Documentation

PInternetProtocol::PInternetProtocol	(	const char *	defaultServiceName,
		PINDEX	cmdCount,
		char const const	cmdNames
	)

protected

Parameters

defaultServiceName	Service name for the protocol.
cmdCount	Number of command strings.
cmdNames	Strings for each command.

Member Function Documentation

virtual PBoolean PInternetProtocol::Accept ( PSocket & listener )

virtual

Accept a server socket to a remote host for the internet protocol.

Returns: true if the channel was successfully connected to the remote host.

Parameters

listener Address of remote machine to connect to.

virtual PBoolean PInternetProtocol::Connect	(	const PString &	address,
		WORD	port = `0`
	)

virtual

Connect a socket to a remote host for the internet protocol.

Returns: true if the channel was successfully connected to the remote host.

Parameters

address	Address of remote machine to connect to.
port	Port number to use for the connection.

virtual PBoolean PInternetProtocol::Connect	(	const PString &	address,
		const PString &	service
	)

virtual

Parameters

address	Address of remote machine to connect to.
service	Service name to use for the connection.

virtual int PInternetProtocol::ExecuteCommand ( PINDEX cmdNumber )

virtual

Write a command to the socket, using WriteCommand() and await a response using ReadResponse().

The first character of the response is returned, as well as the entire response being saved into the protected member variables lastResponseCode and lastResponseInfo.

This function is typically used by client forms of the socket.

Returns: First character of response string or '\0' if a socket error occurred.

Parameters

cmdNumber Number of command to write.

virtual int PInternetProtocol::ExecuteCommand	(	PINDEX	cmdNumber,
		const PString &	param
	)

virtual

Parameters

cmdNumber	Number of command to write.
param	Extra parameters required by the command.

const PString& PInternetProtocol::GetDefaultService ( ) const

Get the default service name or port number to use in socket connections.

Returns: string for the default service name.

int PInternetProtocol::GetLastResponseCode ( ) const

Return the code associated with the last response received by the socket.

Returns: Response code

PString PInternetProtocol::GetLastResponseInfo ( ) const

Return the last response received by the socket.

Returns: Response as a string

PIPSocket* PInternetProtocol::GetSocket ( ) const

Get the eventual socket for the series of indirect channels that may be between the current protocol and the actual I/O channel.

This will assert if the I/O channel is not an IP socket.

Returns: true if the string and CR/LF were completely written.

virtual PINDEX PInternetProtocol::ParseResponse ( const PString & line )

protectedvirtual

Parse a response line string into a response code and any extra info on the line.

Results are placed into the member variables lastResponseCode and lastResponseInfo.

The default bahaviour looks for a space or a '-' and splits the code and info either side of that character, then returns false.

Returns: Position of continuation character in response, 0 if no continuation lines are possible.

Parameters

line	Input response line to be parsed

Reimplemented in PPOP3, and PHTTP.

virtual PBoolean PInternetProtocol::Read	(	void *	buf,
		PINDEX	len
	)

virtual

Low level read from the channel.

This override also supports the mechanism in the UnRead() function allowing characters to be be "put back" into the data stream. This allows a look-ahead required by the logic of some protocols. This is completely independent of the standard iostream mechanisms which do not support the level of timeout control required by the protocols.

Returns: true if at least len bytes were written to the channel.

Parameters

buf	Pointer to a block of memory to receive the read bytes.
len	Maximum number of bytes to read into the buffer.

Reimplemented from PIndirectChannel.

virtual int PInternetProtocol::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.

Reimplemented from PIndirectChannel.

virtual PBoolean PInternetProtocol::ReadCommand	(	PINDEX &	num,
		PString &	args
	)

virtual

Read a single line of a command which ends with a CR/LF pair.

The command number for the command name is parsed from the input, then the remaining text on the line is returned in the args parameter.

If the command does not match any of the command names then the entire line is placed in the args parameter and a value of P_MAX_INDEX is returned.

Note this function will block for the time specified by the PChannel::SetReadTimeout() function.

This function is typically used by server forms of the socket.

Returns: true if something was read, otherwise an I/O error occurred.

Parameters

num	Number of the command parsed from the command line, or P_MAX_INDEX if no match.
args	String to receive the arguments to the command.

virtual PBoolean PInternetProtocol::ReadCommand	(	PINDEX &	num,
		PString &	args,
		PMIMEInfo &	mime
	)

virtual

Parameters

num	Number of the command parsed from the command line, or P_MAX_INDEX if no match.
args	String to receive the arguments to the command.
mime	MIME info received after command line.

virtual PBoolean PInternetProtocol::ReadLine	(	PString &	line,
		PBoolean	allowContinuation = `false`
	)

virtual

Read a string from the socket channel up to a CR/LF pair.

If the unstuffLine parameter is set then the function will remove the '.' character from the start of any line that begins with two consecutive '.' characters. A line that has is exclusively a '.' character will make the function return false.

Note this function will block for the time specified by the PChannel::SetReadTimeout() function for only the first character in the line. The rest of the characters must each arrive within the time set by the readLineTimeout member variable. The timeout is set back to the original setting when the function returns.

Returns: true if a CR/LF pair was received, false if a timeout or error occurred.

Parameters

line	String to receive a CR/LF terminated line.
allowContinuation	Flag to handle continued lines.

virtual PBoolean PInternetProtocol::ReadResponse ( )

virtual

Read a response code followed by a text string describing the response to a command.

The form of the response is to have the code string, then the info string.

The response may have multiple lines in it. A '-' character separates the code from the text on all lines but the last where a ' ' character is used. The info parameter will have placed in it all of the response lines separated by a single '\n' character.

The first form places the response code and info into the protected member variables lastResponseCode and lastResponseInfo.

This function is typically used by client forms of the socket.

Returns: true if the response was completely read without a socket error.

virtual PBoolean PInternetProtocol::ReadResponse	(	int &	code,
		PString &	info
	)

virtual

Parameters

code	Response code for command response.
info	Extra information available after response code.

virtual PBoolean PInternetProtocol::ReadResponse	(	int &	code,
		PString &	info,
		PMIMEInfo &	mime
	)

virtual

Parameters

code	Response code for command response.
info	Extra information available after response code.
mime	MIME information supplied in reply

void PInternetProtocol::SetReadLineTimeout ( const PTimeInterval & t )

Set the maximum timeout between characters within a line.

Default value is 10 seconds.

virtual void PInternetProtocol::UnRead ( int ch )

virtual

Put back the characters into the data stream so that the next Read() function call will return them first.

Parameters

ch	Individual character to be returned.

virtual void PInternetProtocol::UnRead ( const PString & str )

virtual

Parameters

str	String to be put back into data stream.

virtual void PInternetProtocol::UnRead	(	const void *	buffer,
		PINDEX	len
	)

virtual

Parameters

buffer	Characters to be put back into data stream.
len	Number of characters to be returned.

virtual PBoolean PInternetProtocol::Write	(	const void *	buf,
		PINDEX	len
	)

virtual

Low level write to the channel.

This override assures that the sequence CR/LF/./CR/LF does not occur by byte stuffing an extra '.' character into the data stream, whenever a line begins with a '.' character.

Note that this only occurs if the member variable stuffingState has been set to some value other than DontStuff, usually StuffIdle. Also, if the newLineToCRLF member variable is true then all occurrences of a '\n' character will be translated to a CR/LF pair.

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

virtual bool PInternetProtocol::WriteCommand	(	PINDEX	cmdNumber,
		const PString &	param = `PString::Empty()`
	)

virtual

Write a single line for a command.

The command name for the command number is output, then a space, the the param string followed at the end with a CR/LF pair.

If the cmdNumber parameter is outside of the range of valid command names, then the function does not send anything and returns false.

This function is typically used by client forms of the socket.

Returns: true if the command was completely written.

Parameters

cmdNumber	Number of command to write.
param	Extra parameters required by the command.

virtual bool PInternetProtocol::WriteCommand	(	PINDEX	cmdNumber,
		const PString &	param,
		const PMIMEInfo &	mime
	)

virtual

Parameters

cmdNumber	Number of command to write.
param	Extra parameters required by the command.
mime	Optional MIME info sent after the command.

virtual PBoolean PInternetProtocol::WriteLine ( const PString & line )

virtual

Write a string to the socket channel followed by a CR/LF pair.

If there are any lone CR or LF characters in the line parameter string, then these are translated into CR/LF pairs.

Returns: true if the string and CR/LF were completely written.

Parameters

line	String to write as a command line.

virtual PBoolean PInternetProtocol::WriteResponse	(	unsigned	numericCode,
		const PString &	info
	)

virtual

Write a response code followed by a text string describing the response to a command.

The form of the response is to place the code string, then the info string.

If the info parameter has multiple lines then each line has the response code at the start. A '-' character separates the code from the text on all lines but the last where a ' ' character is used.

The first form assumes that the response code is a 3 digit numerical code. The second form allows for any arbitrary string to be the code.

This function is typically used by server forms of the socket.

Returns: true if the response was completely written.

Parameters

numericCode	Response code for command response.
info	Extra information available after response code.

virtual PBoolean PInternetProtocol::WriteResponse	(	const PString &	code,
		const PString &	info
	)

virtual

Parameters

code	Response code for command response.
info	Extra information available after response code.

Member Data Documentation

PStringArray PInternetProtocol::commandNames

protected

PString PInternetProtocol::defaultServiceName

protected

int PInternetProtocol::lastResponseCode

protected

PString PInternetProtocol::lastResponseInfo

protected

PBoolean PInternetProtocol::newLineToCRLF

protected

PTimeInterval PInternetProtocol::readLineTimeout

protected

enum PInternetProtocol::StuffState PInternetProtocol::stuffingState

protected

PCharArray PInternetProtocol::unReadBuffer

protected

PINDEX PInternetProtocol::unReadCount

protected

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

inetprot.h

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation