PTLib
Version 2.18.8
|
A TCP/IP socket for process/application layer high level protocols. More...
#include <inetprot.h>
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 ¶m=PString::Empty()) |
Write a single line for a command. More... | |
virtual bool | WriteCommand (PINDEX cmdNumber, const PString ¶m, 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 ¶m) |
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... | |
![]() | |
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 bool | CloseBaseReadChannel () |
Close the base channel of channel indirection using PIndirectChannel. More... | |
virtual bool | CloseBaseWriteChannel () |
Close the base channel of channel indirection using 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... | |
template<class ChannelClass > | |
ChannelClass * | FindChannel () |
Locate a channel of a specific class in the indirect chain. More... | |
![]() | |
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... | |
virtual PINDEX | GetLastReadCount () const |
Get the number of bytes read by the last Read() call. More... | |
virtual PINDEX | SetLastReadCount (PINDEX count) |
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... | |
virtual PINDEX | SetLastWriteCount (PINDEX count) |
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... | |
![]() | |
__inline unsigned | GetTraceContextIdentifier () const |
Get PTRACE context identifier. More... | |
__inline void | SetTraceContextIdentifier (unsigned id) |
__inline void | SetTraceContextIdentifier (const PObject &obj) |
__inline void | SetTraceContextIdentifier (const PObject *obj) |
__inline void | CopyTraceContextIdentifier (PObject &obj) const |
__inline void | CopyTraceContextIdentifier (PObject *obj) const |
virtual | ~PObject () |
__inline const char * | GetClass () const |
__inline bool | IsClass (const char *name) const |
__inline const PObject * | PTraceObjectInstance () const |
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 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... | |
bool | SetLastResponse (int code, const PString &info, ErrorGroup group=LastGeneralError) |
![]() | |
virtual PBoolean | OnOpen () |
This callback is executed when the Open() function is called with open channels. More... | |
PDECLARE_READ_WRITE_MUTEX (channelPointerMutex) | |
Race condition prevention on closing channel. More... | |
![]() | |
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) |
bool | CheckNotOpen () |
virtual int | os_errno () const |
PBoolean | PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout) |
P_INT_PTR | GetOSHandleAsInt () const |
int | PXClose () |
PDECLARE_MUTEX (px_threadMutex) | |
PDECLARE_MUTEX (px_writeMutex) | |
PChannel () | |
Create the channel. More... | |
![]() | |
PObject () | |
Constructor for PObject, made protected so cannot ever create one on its own. More... | |
Additional Inherited Members | |
![]() | |
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 } |
![]() | |
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 } |
Result of the comparison operation performed by the Compare() function. More... | |
![]() | |
static PString | GetErrorText (Errors lastError, int osError=0) |
Get error message description. More... | |
![]() | |
static __inline void | CopyTraceContextIdentifier (PObject &to, const PObject &from) |
static __inline void | CopyTraceContextIdentifier (PObject &to, const PObject *from) |
static __inline void | CopyTraceContextIdentifier (PObject *to, const PObject &from) |
static __inline void | CopyTraceContextIdentifier (PObject *to, const PObject *from) |
static __inline const char * | Class () |
static __inline const PObject * | PTraceObjectInstance (const char *) |
static __inline const PObject * | PTraceObjectInstance (const PObject *obj) |
template<typename T > | |
static Comparison | Compare2 (T v1, T v2) |
Compare two types, returning Comparison type. More... | |
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size) |
Internal function caled from CompareObjectMemoryDirect() More... | |
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.
|
protected |
|
protected |
defaultServiceName | Service name for the protocol. |
cmdCount | Number of command strings. |
cmdNames | Strings for each command. |
Accept a server socket to a remote host for the internet protocol.
listener | Address of remote machine to connect to. |
Connect a socket to a remote host for the internet protocol.
address | Address of remote machine to connect to. |
port | Port number to use for the connection. |
|
virtual |
address | Address of remote machine to connect to. |
service | Service name to use for the connection. |
|
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.
cmdNumber | Number of command to write. |
|
virtual |
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.
|
inline |
Return the code associated with the last response received by the socket.
References m_lastResponseCode.
|
inline |
Return the last response received by the socket.
References m_lastResponseInfo.
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.
|
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.
line | Input response line to be parsed |
|
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.
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 |
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.
Reimplemented from PIndirectChannel.
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.
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 |
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 |
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.
line | String to receive a CR/LF terminated line. |
allowContinuation | Flag to handle continued lines. |
|
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.
code | Response code for command response. |
info | Extra information available after response code. |
|
virtual |
code | Response code for command response. |
info | Extra information available after response code. |
mime | MIME information supplied in reply |
|
protected |
void PInternetProtocol::SetReadLineTimeout | ( | const PTimeInterval & | t | ) |
Set the maximum timeout between characters within a line.
Default value is 10 seconds.
|
virtual |
Put back the characters into the data stream so that the next Read() function call will return them first.
ch | Individual character to be returned. |
|
virtual |
str | String to be put back into data stream. |
|
virtual |
buffer | Characters to be put back into data stream. |
len | Number of characters to be returned. |
|
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.
buf | Pointer to a block of memory to write. |
len | Number of bytes to write. |
Reimplemented from PIndirectChannel.
|
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.
cmdNumber | Number of command to write. |
param | Extra parameters required by the command. |
|
virtual |
cmdNumber | Number of command to write. |
param | Extra parameters required by the command. |
mime | Optional MIME info sent after the command. |
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.
line | String to write as a command line. |
|
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.
numericCode | Response code for command response. |
info | Extra information available after response code. |
|
virtual |
code | Response code for command response. |
info | Extra information available after response code. |
|
protected |
|
protected |
|
protected |
Referenced by GetLastResponseCode().
|
protected |
Referenced by GetLastResponseInfo().
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |