CSocket Class Reference

#include <CSocket.h>

List of all members.

Public Types
enum	State { Disconnected, Bound, Listening, Connected }
	Captures the state of the socket. See general remarks for more info. More...
Public Member Functions
	CSocket (int am_Fd, CSocket::State am_State)
virtual	~CSocket ()
int	getSocketFd () const
	Get accessor function socket file descriptor.
CSocket::State	getState () const
	Get accessor function for socket state.
void	Connect (const STD(string)&host, const STD(string)&service)
void	Connect (unsigned long int IpAddress, unsigned short service)
void	Bind (const STD(string)&service)
void	Listen (unsigned int nBacklog=5)
CSocket *	Accept (STD(string)&client)
void	Shutdown ()
int	Read (void *pBuffer, size_t nBytes)
int	Write (void *pBuffer, size_t nBytes)
void	getPeer (unsigned short &port, STD(string)&peer)
void	OOBInline (bool State=TRUE)
bool	isOOBInline ()
void	setRcvLowWaterMark (size_t nBytes)
size_t	getRcvLowWaterMark ()
void	setSndLowWaterMark (size_t nBytes)
size_t	getSndLowWaterMark ()
void	setRcvTimeout (unsigned int nMs)
unsigned int	getRcvTimeout ()
void	setSndTimeout (unsigned int nMs)
unsigned int	getSndTimeout ()
void	Debug (bool fState=TRUE)
bool	isDebug ()
void	SetNotRoutable (bool fRoutable=TRUE)
bool	isNotRoutable ()
void	setSndBufSize (size_t nBufferSize)
size_t	getSndBufSize ()
void	setRcvBufSize (size_t nBytes)
size_t	getRcvBufSize ()
void	setLinger (bool lOn, int nLingerSeconds)
void	getLinger (bool &isLingering, int &nLingerSeconds)
Static Public Member Functions
	CSocket ()
	< State name lookup tbl.
Protected Member Functions
void	setSocketFd (const int am_Fd)
	Set accessor function for Socket file descriptor.
void	setState (const CSocket::State am_State)
	Set accessor function for current socket state.
unsigned short	Service (const STD(string)&rService)
	STD (string) AddressToHostString(in_addr peer)
void	OpenSocket ()
Static Protected Member Functions
void	StockStateMap ()
Private Member Functions
	CSocket (const CSocket &aCSocket)
	Copy Constructor forbidden.
CSocket &	operator= (const CSocket &aCSocket)
	Assignment Operator Forbidden.
int	operator== (const CSocket &aCSocket) const
	Equality Operator Forbidden.
Private Attributes
int	m_Fd
	Socket.
CSocket::State	m_State
	State of socket.

---

Detailed Description

Encapsulates a generalized TCP/IP SOCK_STREAM socket. Note that TCP/IP Sockets can come in two flavors: Clients and Servers. Clients must perform a connect, while servers perform a bind, listen and then serveral accepts to create 'server instances'. The state of a socket is maintained in the m_State variable and is from the enumerator: CSocket::State

• Disconnected: The socket is not connected to anything.
• Bound: The socket is a server socket which is not connected, but has been bound to a service port.
• Listening: The socket is a server port which is listening and can therefore accept connections
• Connected The socket is either a client or a server instance and is connected to it's counterpart.

Definition at line 338 of file CSocket.h.

---

Member Enumeration Documentation

enum CSocket::State

Captures the state of the socket. See general remarks for more info. Enumeration values: Disconnected  Bound  Listening  Connected  Definition at line 343 of file CSocket.h. Referenced by getState().

---

Constructor & Destructor Documentation

CSocket::CSocket (   )  [static]

< State name lookup tbl. The default constructor initializes the fd to an illegal value and sets the state to Disconnected. The body of the constructor attempts to set the m_Fd member via a call to socket(2) to create an INET domain SOCK_STREAM, protocl tcp. It is up to the user to call Connect or alternatively set up the socket as a server by binding and listening. Exceptions: CErrnoException if getprotoent for tcp fails or if the socket call itself fails. Definition at line 371 of file CSocket.cpp. References OpenSocket().

CSocket::CSocket (  int  am_Fd, CSocket::State  am_State )

This parameterized constructor is intended to allow a program which already has created a socket in some arbitrary state to wrap it inside a CSocket object. It must be used with care.. in the sense that the am_State parameter must match the actual socket state. Parameters: am_Fd  The file descriptor already open on a socket. am_State  The current state of the socket am_Fd Definition at line 404 of file CSocket.cpp. References StockStateMap().

CSocket::~CSocket (   )  [virtual]

Destructor action depends on the state: sockets which are Connected are shutdown and then closed. Sockets which are in other states are just closed if the fd > 0. Definition at line 384 of file CSocket.cpp. References m_Fd, m_State, and Shutdown().

CSocket::CSocket (  const CSocket &  aCSocket  )  [private]

Copy Constructor forbidden.

---

Member Function Documentation

CSocket* CSocket::Accept (  STD(string)&  client  )

void CSocket::Bind (  const STD(string)&  service  )

void CSocket::Connect (  unsigned long int  IpAddress, unsigned short  service )

Connects a socket as a client given numerical host, and port numbers in host byte order. For the host that means that an ip address of form: aa.bb.cc.dd is stored Hi->Low as aabbccdd in a longword. See Connect(const string&host, const string& service) for more information. Parameters: IpAddress  The numerical ip address of the server in host byte order. service  The port number of the service. Definition at line 501 of file CSocket.cpp. References Disconnected, CApplicationSerializer::getInstance(), CThreadRecursiveMutex::Lock(), m_Fd, m_State, and CThreadRecursiveMutex::UnLock().

void CSocket::Connect (  const STD(string)&  host, const STD(string)&  service )

void CSocket::Debug (  bool  fState = TRUE  )

Purpose: Attempts to turn on Socket debugging. To support this. The user must have effective UID = 0. . Throws: CErrnoException if an error was returned from setsockopt(2) At present we don't know of systems which don't implement this so all errors will throw. Parameters: fState  [TRUE] Desired state of debugging. TRUE will cause debugging to be turned on. FALSE turned off. Definition at line 1207 of file CSocket.cpp. References m_Fd.

void CSocket::getLinger (  bool &  isLingering, int &  nLingerSeconds )

Purpose: Retrieve the linger parameters. Throws: CErrnoException if the setsockopt(2) call failed. Parameters: isLingering  [out] Receives the value of the linger state: TRUE linger is enabled. FALSE linger is not enabled. nLingerSeconds  [out] Receives the value of the linger timeout. This only has meaning in the event that isLingering == TRUE. Definition at line 1453 of file CSocket.cpp. References m_Fd.

void CSocket::getPeer (  unsigned short &  port, STD(string)&  peer )

Referenced by CServerInstance::getPeerPort().

size_t CSocket::getRcvBufSize (   )

Purpose: Returns the maximum number of bytes which can be recieved in a single read(2) call. Throws: CErrnoException if getsockopt(2) fails. Definition at line 1387 of file CSocket.cpp. References m_Fd.

size_t CSocket::getRcvLowWaterMark (   )

Returns the size of the current receive low water mark. See setRcvLowWaterMark for information about what this parameter does. Note that the value returned is inquired from the socket rather than stored in internal state. Throws: CErrnoException if an error from getsockopt is detected. Definition at line 1011 of file CSocket.cpp. References m_Fd.

unsigned int CSocket::getRcvTimeout (   )

Purpose: Retrieve the protocol receive timeout. The time out is returned as an integer number of milliseconds. Throws: CErrnoException if getsockopt(3) returns an error. Definition at line 1112 of file CSocket.cpp. References m_Fd.

size_t CSocket::getSndBufSize (   )

Purpose: Returns the number of bytes that can be written in a single write(2) call. Throws: CErrnoException if getsockopt(2) fails. Definition at line 1340 of file CSocket.cpp. References m_Fd.

size_t CSocket::getSndLowWaterMark (   )

Return the value of the current Send Low Water Mark Set setSndLowWaterMarrk for more information. Throws: CErrnoException if an error from getsockopt is detected. Definition at line 1058 of file CSocket.cpp. References m_Fd.

unsigned int CSocket::getSndTimeout (   )

Purpose: Returns the current send timeout in ms. Throws: CErrnoException if there was an error in getsockopt(2). Definition at line 1173 of file CSocket.cpp. References m_Fd.

int CSocket::getSocketFd (   )  const [inline]

Get accessor function socket file descriptor. Definition at line 383 of file CSocket.h. Referenced by CTCPConnectionLost::Host(), and CTCPConnectionLost::Port().

CSocket::State CSocket::getState (   )  const [inline]

Get accessor function for socket state. Definition at line 388 of file CSocket.h. References State. Referenced by CServerInstance::Shutdown(), and CServerInstance::~CServerInstance().

bool CSocket::isDebug (   )

Purpose: Returns TRUE if socket debugging is turned on and False otherwise. Exceptions: CErrnoException if an error is returned from the getsockopt(2) call. Definition at line 1228 of file CSocket.cpp. References m_Fd, and TRUE.

bool CSocket::isNotRoutable (   )

Purpose: Returns the state of the routability flag. Throws: CErrnoException If getsockopt(2) failed. Return values: TRUE Routing is turned off. FALSE Routing is tured on. Definition at line 1286 of file CSocket.cpp. References m_Fd, and TRUE.

bool CSocket::isOOBInline (   )

Purpose: Returns TRUE if OOBinline is set FALSE otherwise. Note that the underlying socket state is inquired, not some saved internal state. This function is valid in any socket state. Throws: CErrnoException if getsockopt(2) fails Definition at line 955 of file CSocket.cpp. References m_Fd, and TRUE.

void CSocket::Listen (  unsigned int  nBacklog = 5  )

Indicates that the specified server listener socket is ready to listen for connections. The Following exceptions can be thrown: CTCPBadSocketState - m_State != Bound CErrnoException - listen(2) failed. On success, m_State = Listening Parameters: nBacklog  The limit on the queue size for incomming connections. This value of this parameter defaults to 5. If a a connection is requested when the listen queue is full, it is refused or allowed to retry depending on the protocol (according to linux man connect(2)). On some systems this parameter may be ignored or have other meaning. Definition at line 624 of file CSocket.cpp. References Bound, m_Fd, and m_State.

void CSocket::OOBInline (  bool  State = TRUE  )

Purpose: Allows Out Of Band (OOB) data to be inserted in line with buffered data. OOB data is data with a higher delivery priority than 'normal data'. If this flag is not set, then by default OOB data must be read through normal socket interface functions by specifying it in the recv flags parameter. If this flag is set, oob data is queue at the front of the data to be read with the Read member. This is allowed in any socket state. Exceptions: CErrnoException if the setsockopt(2) function failed. Parameters: State  This can be (Defaults to TRUE): TRUE Enables out of band inline data. FALSE disables out of band inline data. Definition at line 930 of file CSocket.cpp. References m_Fd.

void CSocket::OpenSocket (   )  [protected]

Opens the socket on a TCP/IP endpoint. Definition at line 1569 of file CSocket.cpp. References CApplicationSerializer::getInstance(), CThreadRecursiveMutex::Lock(), m_Fd, StockStateMap(), and CThreadRecursiveMutex::UnLock(). Referenced by CSocket(), and Shutdown().

CSocket& CSocket::operator= (  const CSocket &  aCSocket  )  [private]

Assignment Operator Forbidden.

int CSocket::operator== (  const CSocket &  aCSocket  )  const [private]

Equality Operator Forbidden.

int CSocket::Read (  void *  pBuffer, size_t  nBytes )

Purpose: Performs a read on the socket. The read will transfer all of the bytes currently waiting in the socket buffers or block until data is avaialble. The return valiue will be the number of bytes transferred. If the connection is lost, CTCPConnectionLost will be thrown. Multiple reads will not be performed so that any known messaging structure can be maintained. Throws: CErrnoException - the read(2) system service returned an error. CTCPConnectionLost - the read(2) system service returned 0 indicating an end of file condition. CTCPBadSocketState - m_State != Connected. Definition at line 763 of file CSocket.cpp. References Connected, m_Fd, and m_State.

unsigned short CSocket::Service (  const STD(string)&  rService  )  [protected]

void CSocket::setLinger (  bool  lOn, int  nLingerSeconds )

Purpose: Sets the socket linger parameters. Linger properties govern the way a shutdown, operates. Note that object destruction which requires a shutdown implicitly turns off linger. If linger is enabled, then the close will block until all pending data has been successfully sent or until the linger timeout is exceeded. Throws: CErrnoException if the setsockopt(2) call failed. Parameters: lOn  Determines if linger is on or off: TRUE Linger is on. FALSE Linger is off. nLingerSeconds  (only used if lOn is TRUE). Indicates how many seconds to linger on the close until a timeout is declared and the close unblocks. Definition at line 1419 of file CSocket.cpp. References m_Fd.

void CSocket::SetNotRoutable (  bool  fRoutable = TRUE  )

Purpose: Allows the caller to control the routability of messages sent on the socket. If set, messages will not be sent through a gateway. Note: The socket need not be connected. Presumably, if this flag is set prior to Connect on a client socket the client will be unable to connect outside the local subnet, and if set prior to Bind for a server, the server will be unable to accept connections from outside the subnet. Exceptions: -CErrnoException if the setsockopt(2) call failed. Parameters: fRoutable  [TRUE] : TRUE to turn OFF Routing FALSE to turn ON Routing. Definition at line 1261 of file CSocket.cpp. References m_Fd.

void CSocket::setRcvBufSize (  size_t  nBytes  )

Sets the maximum number of bytes which can be received in a single read(2) operation. Note that CTCPSocket::Read does >NOT< automatically segment or else you may block when you'd like to believe that a message has been received. Exceptions: CErrnoException  if setsockopt(2) fails. Parameters: nBytes  Number of bytes which can be sent in one write(2) call Definition at line 1365 of file CSocket.cpp. References m_Fd.

void CSocket::setRcvLowWaterMark (  size_t  nBytes  )

Purpose: Sets the Receive low water mark for the socket. This is the number of bytes received by the protocol before any is made available to the user. Note that some systems do not allow this to be changed. It is not an error at this level to attempt to do so, however you will need to call getRcvlowWaterMark to be sure the change was actually made. Throws: CErrnoException if an error from setsockopt is detected other than that the system doesn't support resetting the low water mark. Definition at line 987 of file CSocket.cpp. References m_Fd.

void CSocket::setRcvTimeout (  unsigned int  nMs  )

Set the protocol receive timeouts. Note that in some systems, these are not settable. However it is not an error to attempt to do so. Parameters: nMs  number of milliseconds of timeout to set. Throws: CErrnoException if a setsockopt(3) returns an error other than that this is unsupported. Definition at line 1081 of file CSocket.cpp. References m_Fd.

void CSocket::setSndBufSize (  size_t  nBufferSize  )

Operation Type: Configuration Purpose: Sets the socket send buffer size. This has to do with how many bytes can be sent in a single write(2) service call. Messages larger than that must be segmented into multiple write(2) calls. Note howerver that CTCPSocket::Write automatically handles any necessary segmentation. Throws: CErrnoException if setsockopt(2) fails. Parameters: nBufferSize  Number of bytes which can be sent in one write(2) call Definition at line 1319 of file CSocket.cpp. References m_Fd.

void CSocket::setSndLowWaterMark (  size_t  nBytes  )

Sets the new value of the Send Low water mark. This controls the number of bytes which must be written before transferring data to the protocol layers for transmission. Note that some systems don't allow this value to be changed. It is not an error to attempt to change this value on those systems, however you should use getSndLowWaterMark to determine the actual value negotiated by the system. Parameters: nBytes  Number of bytes in the low water mark. Throws: CErrnoException if an error from setsockopt is detected other than that the system doesn't support resetting the low water mark. Definition at line 1040 of file CSocket.cpp. References m_Fd.

void CSocket::setSndTimeout (  unsigned int  nMs  )

Purpose: Set the number of milliseconds in the send timeout. Some systems may not allow this to be set, however it is not an error to try. Throws: CErrnoException if setsockop(2) returned an error other than this option is not supported. Parameters: nMs  Number of milliseconds in the desired timeout. Definition at line 1145 of file CSocket.cpp. References m_Fd.

void CSocket::setSocketFd (  const int  am_Fd  )  [inline, protected]

Set accessor function for Socket file descriptor. Definition at line 397 of file CSocket.h.

void CSocket::setState (  const CSocket::State  am_State  )  [inline, protected]

Set accessor function for current socket state. Definition at line 401 of file CSocket.h.

void CSocket::Shutdown (   )

Purpose: Shuts down a connection to a remote system. Unlike shutdown(2) this function does not support selectively shutting down reads or writes. Both are unconditionally shutdown. Note that the destructor will automatically call Shutdown if necessary. Exceptions: CTCPBadSocketState m_State != Connected. CErrnoException shutdown(2) failed. Definition at line 722 of file CSocket.cpp. References Connected, m_Fd, m_State, and OpenSocket(). Referenced by CServerConnectionEvent::OnConnection(), CServerInstance::Shutdown(), CServerConnectionEvent::~CServerConnectionEvent(), CServerInstance::~CServerInstance(), and ~CSocket().

CSocket::STD (  string   )  [protected]

void CSocket::StockStateMap (   )  [static, protected]

Purpose: Stocks the static member: m_StateNames with the states and their names. This is only done if the map is empty. This function must be updated if the set of states is modified. Definition at line 1556 of file CSocket.cpp. Referenced by CSocket(), and OpenSocket().

int CSocket::Write (  void *  pBuffer, size_t  nBytes )

Purpose: Writes data to the socket. Note that this member will block as needed until all data has been queued to the socket buffers. This may require multiple write(2) function calls if the amount of data to be written is larger than the socket's blocking factor. Note that if the connection is lost during the write, CTCPConnectionLost will be thrown. Exceptions: CTCPBadSocketState m_State != Connected CErrnoException write(2) returned an error condition. CTCPConnectionLost write(2) indicated an EPIPE condition which says the peer closed the socket. Bug: There's not a good way to handle failures on the second or later call to write(2). Since we'd like to indicate that part of the write completed before an error occured. The current assumption is that a followup write will produce the same error. Perhaps the best long term thing to do is to define a CTCPSocketIOError which will include as data the number of bytes written along with a CErrnoException which describes why the write actually failed?? Definition at line 824 of file CSocket.cpp. References m_Fd, and m_State.

---

Member Data Documentation

int CSocket::m_Fd [private]

Socket. Definition at line 353 of file CSocket.h. Referenced by Connect(), Debug(), getLinger(), getRcvBufSize(), getRcvLowWaterMark(), getRcvTimeout(), getSndBufSize(), getSndLowWaterMark(), getSndTimeout(), isDebug(), isNotRoutable(), isOOBInline(), Listen(), OOBInline(), OpenSocket(), Read(), setLinger(), SetNotRoutable(), setRcvBufSize(), setRcvLowWaterMark(), setRcvTimeout(), setSndBufSize(), setSndLowWaterMark(), setSndTimeout(), Shutdown(), Write(), and ~CSocket().

CSocket::State CSocket::m_State [private]

State of socket. Definition at line 354 of file CSocket.h. Referenced by Connect(), Listen(), Read(), Shutdown(), Write(), and ~CSocket().

---

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

• CSocket.h
• CSocket.cpp

---