# PTCPSocket Class Reference

A socket that uses the TCP transport on the Internet Protocol. More...

`#include <tcpsock.h>`

Inheritance diagram for PTCPSocket:

List of all members.

## Public Member Functions

virtual PBoolean | Read (void *buf, PINDEX len)
| Low level read from the channel.
Construction.
| PTCPSocket (WORD port=0)
| Create a TCP/IP protocol socket channel.
| PTCPSocket (const PString &service)
| PTCPSocket (const PString &address, WORD port)
| PTCPSocket (const PString &address, const PString &service)
| PTCPSocket (PSocket &socket)
| PTCPSocket (PTCPSocket &tcpSocket)
Overrides from class PObject.
virtual PObject * | Clone () const
| Create a copy of the class on the heap.
Overrides from class PChannel.
virtual PBoolean | Write (const void *buf, PINDEX len)
| Low level write to the channel.
Overrides from class PSocket.
virtual PBoolean | Listen (unsigned queueSize=5, WORD port=0, Reusability reuse=AddressIsExclusive)
| Listen on a socket for a remote host on the specified port number.
virtual PBoolean | Listen (const Address &bind, unsigned queueSize=5, WORD port=0, Reusability reuse=AddressIsExclusive)
virtual PBoolean | Accept (PSocket &socket)
| Open a socket to a remote host on the specified port number.
New functions for class.
virtual PBoolean | WriteOutOfBand (const void *buf, PINDEX len)
| Write out of band data from the TCP/IP stream.
virtual void | OnOutOfBand (const void *buf, PINDEX len)
| This is callback function called by the system whenever out of band data from the TCP/IP stream is received.

## Protected Member Functions

virtual PBoolean | OpenSocket ()
virtual PBoolean | OpenSocket (int ipAdressFamily)
| Open an IPv4 or IPv6 socket.
virtual const char * | GetProtocolName () const
| This function returns the protocol name for the socket type.

## Detailed Description

A socket that uses the TCP transport on the Internet Protocol.

## Constructor & Destructor Documentation

PTCPSocket::PTCPSocket | ( | WORD | port = `0` | ) |

Create a TCP/IP protocol socket channel.

If a remote machine address or a "listening" socket is specified then the channel is also opened.

Note that what looks like a "copy" constructor here is really a the accept of a "listening" socket the same as the PSocket & parameter version constructor.

Parameters:

  port | Port number to use for the connection.

PTCPSocket::PTCPSocket | ( | const PString & | service | ) |

Parameters:

  service | Service name to use for the connection.

PTCPSocket::PTCPSocket | ( | const PString & | address,
|  | WORD | port |
| ) |  |  |

Parameters:

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

PTCPSocket::PTCPSocket | ( | const PString & | address,
|  | const PString & | service |
| ) |  |  |

Parameters:

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

PTCPSocket::PTCPSocket | ( | PSocket & | socket | ) |

Parameters:

  socket | Listening socket making the connection.

PTCPSocket::PTCPSocket | ( | PTCPSocket & | tcpSocket | ) |

Parameters:

  tcpSocket | Listening socket making the connection.

## Member Function Documentation

virtual PBoolean PTCPSocket::Accept | ( | PSocket & | socket | ) | `[virtual]`

Open a socket to a remote host on the specified port number.

This is an "accepting" socket. When a "listening" socket has a pending connection to make, this will accept a connection made by the "connecting" socket created to establish a link.

The port that the socket uses is the one used in the `Listen()` command of the `socket` parameter.

Note that this function will block until a remote system connects to the port number specified in the "listening" socket.

Returns:
  true if the channel was successfully opened.

Parameters:

  socket | Listening socket making the connection.

Reimplemented from PSocket.

Reimplemented in PSocksSocket, and PTelnetSocket.

virtual PObject* PTCPSocket::Clone | ( |  | ) | const`[virtual]`

Create a copy of the class on the heap.

The exact semantics of the descendent class determine what is required to make a duplicate of the instance. Not all classes can even {do} a clone operation.

The main user of the clone function is the `PDictionary` class as it requires copies of the dictionary keys.

The default behaviour is for this function to assert.

Returns:
  pointer to new copy of the class instance.

Reimplemented from PObject.

Reimplemented in PSocks4Socket, and PSocks5Socket.

virtual const char* PTCPSocket::GetProtocolName | ( |  | ) | const`[protected, virtual]`

This function returns the protocol name for the socket type.

Implements PSocket.

virtual PBoolean PTCPSocket::Listen | ( | const Address & | bind,
|  | unsigned | queueSize = `5`,
|  | WORD | port = `0`,
|  | Reusability | reuse = `AddressIsExclusive` |
| ) |  |  | `[virtual]`

Parameters:

  bind | Local interface address to bind to.
  queueSize | Number of pending accepts that may be queued.
  port | Port number to use for the connection.
  reuse | Can/Can't listen more than once.

virtual PBoolean PTCPSocket::Listen | ( | unsigned | queueSize = `5`,
|  | WORD | port = `0`,
|  | Reusability | reuse = `AddressIsExclusive` |
| ) |  |  | `[virtual]`

Listen on a socket for a remote host on the specified port number.

This may be used for server based applications. A "connecting" socket begins a connection by initiating a connection to this socket. An active socket of this type is then used to generate other "accepting" sockets which establish a two way communications channel with the "connecting" socket.

The Listen() method is only used once in the entire lifetime of the socket. In contrast, the Accept() may be used many more times. Thus, if you have a socket to collect incoming connections, do a Listen() on it to get things ready, and then Accept(). With each incoming connection, you will do Accept again.

If the `port` parameter is zero then the port number as defined by the object instance construction or the `PIPSocket::SetPort()` function.

Returns:
  true if the channel was successfully opened.

Parameters:

  queueSize | Number of pending accepts that may be queued.
  port | Port number to use for the connection.
  reuse | Can/Can't listen more than once.

Reimplemented from PIPSocket.

Reimplemented in PSocksSocket.

virtual void PTCPSocket::OnOutOfBand | ( | const void * | buf,
|  | PINDEX | len |
| ) |  |  | `[virtual]`

This is callback function called by the system whenever out of band data from the TCP/IP stream is received.

A descendent class may interpret this data according to the semantics of the high level protocol.

The default behaviour is for the out of band data to be ignored.

Parameters:

  buf | Data to be received as URGENT TCP data.
  len | Number of bytes pointed to by `buf`.

Reimplemented in PTelnetSocket.

virtual PBoolean PTCPSocket::OpenSocket | ( | int | ipAdressFamily | ) | `[protected, virtual]`

Open an IPv4 or IPv6 socket.

Implements PIPSocket.

virtual PBoolean PTCPSocket::OpenSocket | ( |  | ) | `[protected, virtual]`

Implements PSocket.

virtual PBoolean PTCPSocket::Read | ( | void * | buf,
|  | PINDEX | len |
| ) |  |  | `[virtual]`

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.

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.

Reimplemented from PSocket.

Reimplemented in PTelnetSocket.

virtual PBoolean PTCPSocket::Write | ( | const void * | buf,
|  | PINDEX | len |
| ) |  |  | `[virtual]`

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.

The GetErrorCode() function should be consulted after Write() returns false to determine what caused the failure.

This override repeatedly writes if there is no error until all of the requested bytes have been written.

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

Reimplemented in PTelnetSocket.

virtual PBoolean PTCPSocket::WriteOutOfBand | ( | const void * | buf,
|  | PINDEX | len |
| ) |  |  | `[virtual]`

Write out of band data from the TCP/IP stream.

This data is sent as TCP URGENT data which does not follow the usual stream sequencing of the normal channel data.

This is subject to the write timeout and sets the `lastWriteCount` member variable in the same way as usual `PChannel::Write()` function.

Returns:
  true if all the bytes were sucessfully written.

Parameters:

  buf | Data to be written as URGENT TCP data.
  len | Number of bytes pointed to by `buf`.

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

- tcpsock.h