#include <inetprot.h>

Inheritance diagram for PInternetProtocol:

Public Member Functions
virtual BOOL	Read (void *buf, PINDEX len)
virtual BOOL	Write (const void *buf, PINDEX len)
void	SetReadLineTimeout (const PTimeInterval &t)
virtual BOOL	Connect (const PString &address, WORD port=0)
virtual BOOL	Connect (const PString &address, const PString &service)
virtual BOOL	Accept (PSocket &listener)
const PString &	GetDefaultService () const
PIPSocket *	GetSocket () const
virtual BOOL	WriteLine (const PString &line)
virtual BOOL	ReadLine (PString &line, BOOL allowContinuation=FALSE)
virtual void	UnRead (int ch)
virtual void	UnRead (const PString &str)
virtual void	UnRead (const void *buffer, PINDEX len)
virtual BOOL	WriteCommand (PINDEX cmdNumber)
virtual BOOL	WriteCommand (PINDEX cmdNumber, const PString &param)
virtual BOOL	ReadCommand (PINDEX &num, PString &args)
virtual BOOL	WriteResponse (unsigned numericCode, const PString &info)
virtual BOOL	WriteResponse (const PString &code, const PString &info)
virtual BOOL	ReadResponse ()
virtual BOOL	ReadResponse (int &code, PString &info)
virtual int	ExecuteCommand (PINDEX cmdNumber)
virtual int	ExecuteCommand (PINDEX cmdNumber, const PString &param)
int	GetLastResponseCode () const
PString	GetLastResponseInfo () const
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)
Protected Attributes
PString	defaultServiceName
PStringArray	commandNames
PCharArray	unReadBuffer
PINDEX	unReadCount
PTimeInterval	readLineTimeout
enum PInternetProtocol::StuffState	stuffingState
BOOL	newLineToCRLF
int	lastResponseCode
PString	lastResponseInfo

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 BOOL 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 BOOL 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 BOOL 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 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 ) [protected, virtual]

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 PHTTP, and PPOP3.

virtual BOOL 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 BOOL 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 BOOL PInternetProtocol::ReadLine	(	PString &	line,
		BOOL	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 BOOL PInternetProtocol::ReadResponse	(	int &	code,
		PString &	info
	)		`[virtual]`

Parameters:

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

virtual BOOL 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 '
' 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.

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 void *	buffer,
		PINDEX	len
	)		`[virtual]`

Parameters:

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

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

Parameters:

str	String to be put back into data stream.

virtual BOOL 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 '
' 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 ) [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.

virtual BOOL PInternetProtocol::WriteCommand	(	PINDEX	cmdNumber,
		const PString &	param
	)		`[virtual]`

Parameters:

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

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