class PInternetProtocol

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

Inheritance:


Public Methods

[more]virtual BOOL Read ( void* buf, PINDEX len )
Low level read from the channel.
[more]virtual BOOL 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 BOOL Connect ( const PString & address, WORD port = 0 )
Connect a socket to a remote host for the internet protocol.
[more]virtual BOOL 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 BOOL WriteLine ( const PString & line )
Write a string to the socket channel followed by a CR/LF pair.
[more]virtual BOOL ReadLine ( PString & line, BOOL 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 <A>Read()</A> function call will return them first
[more]virtual BOOL WriteCommand ( PINDEX cmdNumber )
Write a single line for a command.
[more]virtual BOOL ReadCommand ( PINDEX & num, PString & args )
Read a single line of a command which ends with a CR/LF pair.
[more]virtual BOOL WriteResponse ( unsigned numericCode, const PString & info )
Write a response code followed by a text string describing the response to a command.
[more]virtual BOOL ReadResponse ()
Read a response code followed by a text string describing the response to a command.
[more]virtual int ExecuteCommand ( PINDEX cmdNumber )
Write a command to the socket, using <CODE>WriteCommand()</CODE> and await a response using <CODE>ReadResponse()</CODE>.
[more]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.

Protected Methods

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


Inherited from PIndirectChannel:

Public Methods

Construction

Overrides from class PObject

Overrides from class PChannel

Channel establish functions

Protected Fields

oPChannel* readChannel
oBOOL readAutoDelete
oPChannel* writeChannel
oBOOL writeAutoDelete
oPReadWriteMutex channelPointerMutex

Protected Methods

ovirtual BOOL OnOpen()


Inherited from PChannel:

Public Methods

Information functions

Reading functions

Writing functions

Miscellaneous functions

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

Public Members

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 Methods

Run Time Type functions

I/O functions

Public Members

Comparison functions


Documentation

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.

ovirtual BOOL Read( void* buf, PINDEX len )
Low level read from the channel.

This override also supports the mechanism in the <A>UnRead()</A> 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.

ovirtual BOOL Write( const void* buf, PINDEX len )
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 <CODE>stuffingState</CODE> has been set to some value other than <CODE>DontStuff</CODE>, usually <CODE>StuffIdle</CODE>. Also, if the <CODE>newLineToCRLF</CODE> 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.

ovoid SetReadLineTimeout( const PTimeInterval & t )
Set the maximum timeout between characters within a line. Default value is 10 seconds.

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

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

ovirtual BOOL Accept( PSocket & listener )
Accept a server socket to a remote host for the internet protocol.

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

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

Returns:
string for the default service name.

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

ovirtual BOOL WriteLine( const PString & line )
Write a string to the socket channel followed by a CR/LF pair. If there are any lone CR or LF characters in the <CODE>line</CODE> parameter string, then these are translated into CR/LF pairs.

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

ovirtual BOOL ReadLine( PString & line, BOOL allowContinuation = FALSE )
Read a string from the socket channel up to a CR/LF pair.

If the <CODE>unstuffLine</CODE> 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 <A>PChannel::SetReadTimeout()</A> function for only the first character in the line. The rest of the characters must each arrive within the time set by the <CODE>readLineTimeout</CODE> 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.

ovirtual void UnRead( int ch )
Put back the characters into the data stream so that the next <A>Read()</A> function call will return them first

ovirtual BOOL WriteCommand( PINDEX cmdNumber )
Write a single line for a command. The command name for the command number is output, then a space, the the <CODE>param</CODE> string followed at the end with a CR/LF pair.

If the <CODE>cmdNumber</CODE> 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.

ovirtual BOOL ReadCommand( PINDEX & num, PString & args )
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 <CODE>args</CODE> parameter.

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

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

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

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

ovirtual BOOL WriteResponse( unsigned numericCode, const PString & info )
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 <CODE>info</CODE> 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.

ovirtual BOOL ReadResponse()
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 <CODE>info</CODE> 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 <CODE>lastResponseCode</CODE> and <CODE>lastResponseInfo</CODE>.

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

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

ovirtual int ExecuteCommand( PINDEX cmdNumber )
Write a command to the socket, using <CODE>WriteCommand()</CODE> and await a response using <CODE>ReadResponse()</CODE>. The first character of the response is returned, as well as the entire response being saved into the protected member variables <CODE>lastResponseCode</CODE> and <CODE>lastResponseInfo</CODE>.

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

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

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

Returns:
Response code

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

Returns:
Response as a string

ovirtual PINDEX ParseResponse( const PString & line )
Parse a response line string into a response code and any extra info on the line. Results are placed into the member variables <CODE>lastResponseCode</CODE> and <CODE>lastResponseInfo</CODE>.

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.


Direct child classes:
PSMTP
PPOP3
PFTP
PHTTP

Alphabetic index HTML hierarchy of classes or Java



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