class PSocket: public PChannel

A network communications channel.

Inheritance:


Public

[more] Socket establishment functions
[more] Socket options functions
[more] Port/Service database functions
[more] Multiple socket selection functions
[more] Integer conversion functions

Protected Fields

[more]WORD port
Port to be used by the socket when opening the channel.

Protected Methods

[more]virtual const char* GetProtocolName () const
This function returns the protocol name for the socket type


Inherited from PChannel:

Public Methods

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

Public

Construction

Overrides from class PObject

Information functions

Reading functions

Writing functions

Miscellaneous functions

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

Run Time Type functions

Comparison functions

I/O functions


Documentation

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.

o Socket establishment functions

ovirtual BOOL Connect( const PString & address )
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.

Returns:
TRUE if the channel was successfully connected to the remote host.
Parameters:
address - Address of remote machine to connect to.

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

ovirtual BOOL Listen( unsigned queueSize = 5, WORD port = 0, Reusability reuse = AddressIsExclusive )
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 äccepting" 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:
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/Cant listen more than once.

ovirtual BOOL Accept( PSocket & socket )
Open a socket to a remote host on the specified port number. This is an äccepting" 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:
TRUE if the channel was successfully opened.
Parameters:
socket - Listening socket making the connection.

ovirtual BOOL Shutdown( ShutdownValue option )
Close one or both of the data streams associated with a socket

Returns:
TRUE if the shutdown was performed
Parameters:
option - Flag for shutdown of read, write or both.

o Socket options functions

oBOOL 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:
TRUE if the option was successfully set.
Parameters:
option - Option to set.
value - New value for option.
level - Level for option

oBOOL 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:
TRUE 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

oBOOL 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:
TRUE if the option was successfully retreived.
Parameters:
option - Option to get.
value - Integer to receive value.
level - Level for option

oBOOL 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:
TRUE if the option was successfully retreived.
Parameters:
option - Option to get.
valuePtr - Pointer to buffer for value.
valueSize - Size of buffer to receive value.
level - Level for option

o Port/Service database functions

ostatic WORD GetProtocolByName( const PString & name )
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

ostatic PString GetNameByProtocol( WORD proto )
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

ovirtual WORD GetPortByService( const PString & service ) const
Get the port number for the specified service name.
Parameters:
service - Name of service to get port number for.

ostatic WORD GetPortByService( const char * protocol, const PString & service )
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 üdp",

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.

ovirtual PString GetServiceByPort( WORD port ) const
Get the service name from the port number.
Parameters:
port - Number for service to find name of.

ostatic PString GetServiceByPort( const char * protocol, WORD port )
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 üdp",

Returns:
Service name for port number.
Parameters:
protocol - Protocol type for port lookup
port - Number for service to find name of.

ovoid SetPort( WORD port )
Set the port number for the channel.
Parameters:
port - New port number for the channel.

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

oWORD GetPort() const
Get the port the TCP socket channel object instance is using.

Returns:
Port number.

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

o Multiple socket selection functions

oclass SelectList: public PSocketList
List of sockets used for Select() function

ostatic int Select( PSocket & sock1, PSocket & sock2 )
Select a socket with available data.
Parameters:
sock1 - First socket to check for readability.
sock2 - Second socket to check for readability.

ostatic int Select( PSocket & sock1, PSocket & sock2, const PTimeInterval & timeout )
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.

ostatic Errors Select( SelectList & read )
Select a socket with available data.
Parameters:
read - List of sockets to check for readability.

ostatic Errors Select( SelectList & read, const PTimeInterval & timeout )
Select a socket with available data.
Parameters:
read - List of sockets to check for readability.
timeout - Timeout for wait on read/write data.

ostatic Errors Select( SelectList & read, SelectList & write )
Select a socket with available data.
Parameters:
read - List of sockets to check for readability.
write - List of sockets to check for writability.

ostatic Errors Select( SelectList & read, SelectList & write, const PTimeInterval & timeout )
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.

ostatic Errors Select( SelectList & read, SelectList & write, SelectList & except )
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.

ostatic Errors Select( SelectList & read, SelectList & write, SelectList & except, const PTimeInterval & timeout )
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 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:
TRUE if the select was successful or timed out, FALSE 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.

o Integer conversion functions

oinline static WORD Host2Net(WORD v)
Convert from host to network byte order

oinline static DWORD Host2Net(DWORD v)
Convert from host to network byte order

oinline static WORD Net2Host(WORD v)
Convert from network to host byte order

oinline static DWORD Net2Host(DWORD v)
Convert from network to host byte order

ovirtual const char* GetProtocolName() const
This function returns the protocol name for the socket type

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


Direct child classes:
PIPXSocket
PIPSocket
PEthSocket

Alphabetic index HTML hierarchy of classes or Java



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