PSocket Class Reference

#include <socket.h>

Inheritance diagram for PSocket:

List of all members.

Socket establishment functions
enum	Reusability { CanReuseAddress, AddressIsExclusive }
	Flags to reuse of port numbers in Listen() function. More...
virtual PBoolean	Connect (const PString &address)
virtual PBoolean	Listen (unsigned queueSize=5, WORD port=0, Reusability reuse=AddressIsExclusive)
virtual PBoolean	Accept (PSocket &socket)
virtual PBoolean	Shutdown (ShutdownValue option)
Port/Service database functions
virtual WORD	GetPortByService (const PString &service) const
virtual PString	GetServiceByPort (WORD port) const
void	SetPort (WORD port)
void	SetPort (const PString &service)
WORD	GetPort () const
PString	GetService () const
static WORD	GetProtocolByName (const PString &name)
static PString	GetNameByProtocol (WORD proto)
static WORD	GetPortByService (const char *protocol, const PString &service)
static PString	GetServiceByPort (const char *protocol, WORD port)
Public Member Functions
PBoolean	Read (void *ptr, PINDEX len)
	~PSocket ()
Socket options functions
PBoolean	SetOption (int option, int value, int level=SOL_SOCKET)
PBoolean	SetOption (int option, const void *valuePtr, PINDEX valueSize, int level=SOL_SOCKET)
PBoolean	GetOption (int option, int &value, int level=SOL_SOCKET)
PBoolean	GetOption (int option, void *valuePtr, PINDEX valueSize, int level=SOL_SOCKET)
Static Public Member Functions
Multiple socket selection functions
static int	Select (PSocket &sock1, PSocket &sock2)
static int	Select (PSocket &sock1, PSocket &sock2, const PTimeInterval &timeout)
static Errors	Select (SelectList &read)
static Errors	Select (SelectList &read, const PTimeInterval &timeout)
static Errors	Select (SelectList &read, SelectList &write)
static Errors	Select (SelectList &read, SelectList &write, const PTimeInterval &timeout)
static Errors	Select (SelectList &read, SelectList &write, SelectList &except)
static Errors	Select (SelectList &read, SelectList &write, SelectList &except, const PTimeInterval &timeout)
Integer conversion functions
static WORD	Host2Net (WORD v)
	Convert from host to network byte order.
static DWORD	Host2Net (DWORD v)
	Convert from host to network byte order.
static WORD	Net2Host (WORD v)
	Convert from network to host byte order.
static DWORD	Net2Host (DWORD v)
	Convert from network to host byte order.
Protected Member Functions
	PSocket ()
virtual PBoolean	OpenSocket ()=0
virtual const char *	GetProtocolName () const =0
int	os_close ()
int	os_socket (int af, int type, int proto)
PBoolean	os_connect (struct sockaddr *sin, PINDEX size)
PBoolean	os_recvfrom (void *buf, PINDEX len, int flags, struct sockaddr *from, PINDEX *fromlen)
PBoolean	os_sendto (const void *buf, PINDEX len, int flags, struct sockaddr *to, PINDEX tolen)
PBoolean	os_accept (PSocket &listener, struct sockaddr *addr, PINDEX *size)
Protected Attributes
WORD	port
	Port to be used by the socket when opening the channel.
Classes
class	SelectList
	List of sockets used for Select() function. More...

---

Detailed Description

A network communications channel. This is based on the concepts in the Berkley Sockets library.

A socket represents a bidirectional communications channel to a port at a remote host.

---

Member Enumeration Documentation

enum PSocket::Reusability

Flags to reuse of port numbers in Listen() function.

Enumerator:

CanReuseAddress
AddressIsExclusive

---

Constructor & Destructor Documentation

PSocket::PSocket

(

)

[protected]

PSocket::~PSocket

(

)

---

Member Function Documentation

virtual PBoolean PSocket::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 an error occurs if the socket parameter has not had the Listen() function called on it.

Note that this function will block until a remote system connects to the port number specified in the "listening" socket. The time that the function will block is determined by the read timeout of the socket parameter. This will normally be PMaxTimeInterval which indicates an infinite time.

The default behaviour is to assert.

Returns:

PTrue if the channel was successfully opened.

Parameters:

socket

Listening socket making the connection.

Reimplemented in PTCPSocket, PSocksSocket, and PTelnetSocket.

virtual PBoolean PSocket::Connect

(

const PString &

address

)

[virtual]

Connect a socket to a remote host on the specified port number. This is typically used by the client or initiator of a communications channel. This connects to a "listening" socket at the other end of the communications channel.

Use the SetReadTimeout() function to set a maximum time for the Connect().

Returns:

PTrue if the channel was successfully connected to the remote host.

Parameters:

address

Address of remote machine to connect to.

Reimplemented in PEthSocket, PIPSocket, PUDPSocket, PSocksSocket, PSocksUDPSocket, and PTelnetSocket.

static PString PSocket::GetNameByProtocol

(

WORD

proto

)

[static]

Get the name of the protocol number specified.

Returns:

Name of protocol or the number if the protocol was not found.

Parameters:

proto

Number of protocol.

PBoolean PSocket::GetOption	(	int	option,
		void *	valuePtr,
		PINDEX	valueSize,
		int	level = SOL_SOCKET
	)

Get options on the socket. These options are defined as Berkeley socket options of the class SOL_SOCKET.

Returns:

PTrue if the option was successfully retrieved.

Parameters:

option	Option to get.
valuePtr	Pointer to buffer for value.
valueSize	Size of buffer to receive value.
level	Level for option

PBoolean PSocket::GetOption	(	int	option,
		int &	value,
		int	level = SOL_SOCKET
	)

Get options on the socket. These options are defined as Berkeley socket options of the class SOL_SOCKET.

Returns:

PTrue if the option was successfully retrieved.

Parameters:

option	Option to get.
value	Integer to receive value.
level	Level for option.

WORD PSocket::GetPort

(

)

const

Get the port the TCP socket channel object instance is using.

Returns:

Port number.

static WORD PSocket::GetPortByService	(	const char *	protocol,
		const PString &	service
	)			[static]

Get the port number for the specified service name.

A name is a unique string contained in a system database. The parameter here may be either this unique name, an integer value or both separated by a space (name then integer). In the latter case the integer value is used if the name cannot be found in the database.

The exact behviour of this function is dependent on whether TCP or UDP transport is being used. The PTCPSocket and PUDPSocket classes will implement this function.

The static version of the function is independent of the socket type as its first parameter may be "tcp" or "udp".

Returns:

Port number for service name, or 0 if service cannot be found.

Parameters:

protocol	Protocol type for port lookup.
service	Name of service to get port number for.

virtual WORD PSocket::GetPortByService

(

const PString &

service

)

const [virtual]

Get the port number for the specified service name.

Parameters:

service

Name of service to get port number for.

static WORD PSocket::GetProtocolByName

(

const PString &

name

)

[static]

Get the number of the protocol associated with the specified name.

Returns:

Number of protocol or 0 if the protocol was not found.

Parameters:

name	Name of protocol.

virtual const char* PSocket::GetProtocolName

(

)

const [protected, pure virtual]

This function returns the protocol name for the socket type.

Implemented in PEthSocket, PICMPSocket, PTCPSocket, and PUDPSocket.

PString PSocket::GetService

(

)

const

Get a service name for the port number the TCP socket channel object instance is using.

Returns:

String service name or a string representation of the port number if no service with that number can be found.

static PString PSocket::GetServiceByPort	(	const char *	protocol,
		WORD	port
	)			[static]

Get the service name from the port number.

A service name is a unique string contained in a system database. The parameter here may be either this unique name, an integer value or both separated by a space (name then integer). In the latter case the integer value is used if the name cannot be found in the database.

The exact behviour of this function is dependent on whether TCP or UDP transport is being used. The PTCPSocket and PUDPSocket classes will implement this function.

The static version of the function is independent of the socket type as its first parameter may be "tcp" or "udp".

Returns:

Service name for port number.

Parameters:

protocol	Protocol type for port lookup
port	Number for service to find name of.

virtual PString PSocket::GetServiceByPort

(

WORD

port

)

const [virtual]

Get the service name from the port number.

Parameters:

port	Number for service to find name of.

static DWORD PSocket::Host2Net

(

DWORD

v

)

[inline, static]

Convert from host to network byte order.

static WORD PSocket::Host2Net

(

WORD

v

)

[inline, static]

Convert from host to network byte order.

virtual PBoolean PSocket::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.

If the port parameter is zero then the port number as defined by the object instance construction or the descendent classes SetPort() or SetService() function.

Returns:

PTrue 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/Cant listen more than once.

static DWORD PSocket::Net2Host

(

DWORD

v

)

[inline, static]

Convert from network to host byte order.

static WORD PSocket::Net2Host

(

WORD

v

)

[inline, static]

Convert from network to host byte order.

virtual PBoolean PSocket::OpenSocket

(

)

[protected, pure virtual]

Implemented in PEthSocket, PICMPSocket, PTCPSocket, and PUDPSocket.

PBoolean PSocket::os_accept	(	PSocket &	listener,
		struct sockaddr *	addr,
		PINDEX *	size
	)			[protected]

int PSocket::os_close

(

)

[protected]

PBoolean PSocket::os_connect	(	struct sockaddr *	sin,
		PINDEX	size
	)			[protected]

PBoolean PSocket::os_recvfrom	(	void *	buf,
		PINDEX	len,
		int	flags,
		struct sockaddr *	from,
		PINDEX *	fromlen
	)			[protected]

PBoolean PSocket::os_sendto	(	const void *	buf,
		PINDEX	len,
		int	flags,
		struct sockaddr *	to,
		PINDEX	tolen
	)			[protected]

int PSocket::os_socket	(	int	af,
		int	type,
		int	proto
	)			[protected]

PBoolean PSocket::Read	(	void *	ptr,
		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 PFalse to determine what caused the failure.

Returns:

PTrue indicates that at least one character was read from the channel. PFalse means no bytes were read due to timeout or some other I/O error.

Reimplemented from PChannel.

Reimplemented in PEthSocket, PTCPSocket, PUDPSocket, and PTelnetSocket.

static Errors PSocket::Select	(	SelectList &	read,
		SelectList &	write,
		SelectList &	except,
		const PTimeInterval &	timeout
	)			[static]

Select a socket with available data. This function will block until the timeout or data is available to be read or written to the specified sockets.

The read, write and except lists are modified by the call so that only the sockets that have data available are present. If the call timed out then all of these lists will be empty.

If no timeout is specified then the call will block until a socket has data available.

Returns:

PTrue if the select was successful or timed out, PFalse if an error occurred. If a timeout occurred then the lists returned will be empty.

For the versions taking sockets directly instead of lists the integer returned is >0 for an error being a value from the PChannel::Errors enum, 0 for a timeout, -1 for the first socket having read data, -2 for the second socket and -3 for both.

Parameters:

read	List of sockets to check for readability.
write	List of sockets to check for writability.
except	List of sockets to check for exceptions.
timeout	Timeout for wait on read/write data.

static Errors PSocket::Select	(	SelectList &	read,
		SelectList &	write,
		SelectList &	except
	)			[static]

Select a socket with available data.

Parameters:

read	List of sockets to check for readability.
write	List of sockets to check for writability.
except	List of sockets to check for exceptions.

static Errors PSocket::Select	(	SelectList &	read,
		SelectList &	write,
		const PTimeInterval &	timeout
	)			[static]

Select a socket with available data.

Parameters:

read	List of sockets to check for readability.
write	List of sockets to check for writability.
timeout	Timeout for wait on read/write data.

static Errors PSocket::Select	(	SelectList &	read,
		SelectList &	write
	)			[static]

Select a socket with available data.

Parameters:

read	List of sockets to check for readability.
write	List of sockets to check for writability.

static Errors PSocket::Select	(	SelectList &	read,
		const PTimeInterval &	timeout
	)			[static]

Select a socket with available data.

Parameters:

read	List of sockets to check for readability.
timeout	Timeout for wait on read/write data.

static Errors PSocket::Select

(

SelectList &

read

)

[static]

Select a socket with available data.

Parameters:

read	List of sockets to check for readability.

static int PSocket::Select	(	PSocket &	sock1,
		PSocket &	sock2,
		const PTimeInterval &	timeout
	)			[static]

Select a socket with available data.

Parameters:

sock1	First socket to check for readability.
sock2	Second socket to check for readability.
timeout	Timeout for wait on read/write data.

static int PSocket::Select	(	PSocket &	sock1,
		PSocket &	sock2
	)			[static]

Select a socket with available data.

Parameters:

sock1	First socket to check for readability.
sock2	Second socket to check for readability.

PBoolean PSocket::SetOption	(	int	option,
		const void *	valuePtr,
		PINDEX	valueSize,
		int	level = SOL_SOCKET
	)

Set options on the socket. These options are defined as Berkeley socket options of the class SOL_SOCKET.

Returns:

PTrue if the option was successfully set.

Parameters:

option	Option to set.
valuePtr	Pointer to new value for option.
valueSize	Size of new value.
level	Level for option.

PBoolean PSocket::SetOption	(	int	option,
		int	value,
		int	level = SOL_SOCKET
	)

Set options on the socket. These options are defined as Berkeley socket options of the class SOL_SOCKET.

Returns:

PTrue if the option was successfully set.

Parameters:

option	Option to set.
value	New value for option.
level	Level for option.

void PSocket::SetPort

(

const PString &

service

)

Set the port number for the channel. This a 16 bit number representing an agreed high level protocol type. The string version looks up a database of names to find the number for the string name.

A service name is a unique string contained in a system database. The parameter here may be either this unique name, an integer value or both separated by a space (name then integer). In the latter case the integer value is used if the name cannot be found in the database.

The port number may not be changed while the port is open and the function will assert if an attempt is made to do so.

Parameters:

service

Service name to describe the port number.

void PSocket::SetPort

(

WORD

port

)

Set the port number for the channel.

Parameters:

port	New port number for the channel.

virtual PBoolean PSocket::Shutdown

(

ShutdownValue

option

)

[virtual]

Close one or both of the data streams associated with a socket.

Returns:

PTrue if the shutdown was performed

Parameters:

option

Flag for shutdown of read, write or both.

---

Member Data Documentation

WORD PSocket::port [protected]

Port to be used by the socket when opening the channel.

---

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

• socket.h

---