Cabal::Socket Class Reference

Basic socket encapsulation class. More...

#include <cabal_socket.h>

Inheritance diagram for Cabal::Socket:

[legend]Collaboration diagram for Cabal::Socket:

[legend]List of all members.

Public Member Functions
virtual	~Socket ()
	Destroys the socket.
	Socket (const Socket &) throw ( InitError )
	Copies a socket.
bool	bind (const Address &local)
	Binds a socket with an address.
virtual int	recv (void *buffer, const int len)
	Reads the data ready to be received on the socket.
virtual int	send (const void *buffer, const int len)
	Send a single packet of data.
bool	continueOp ()
virtual bool	close ()
	Closes the socket.
const Address &	remote () const
	Returns the remote address.
const Address &	local () const
	Returns local address of the connection.
long	timeout () const
	Returns currently set timeout in milliseconds.
void	timeout (const long to)
	Sets a timeout in seconds.
bool	hasTimedOut () const
	Returns true if the last operation timed out.
int	osError () const
	Return last OS error.
bool	closed () const
	Returns true if the socket has been closed.
RawSocket	rawSocket () const
	Returns underlying system socket.
void	channel (Channel *chn, Reception *rcpt)
	Binds this socket to a certain channel.
Reception *	reception () const
Channel *	channel () const
	Returns the channel this socket is bound to, or 0 if the channel is unbound.
bool	managed () const
	Returns the managed status of this socket.
const char *	remote_ip ()
	Returns the remote IP address.
int	remote_port () const
	Commodity shortut for remote().port();.
const char *	local_ip ()
	Returns the local ip address.
int	local_port () const
	Commodity shortut for local().port();.
virtual void	incref ()
	Increment the reference count.
virtual void	decref ()
	Increment the reference count.
Protected Member Functions
int	Socket::selectFor (bool rw)
virtual int	rawRecv (void *data, const int len)=0
	Subclasses hook to receive data.
virtual int	rawSend (const void *data, const int len)=0
	Subclasses hook to send data.
	Socket (const SockType type)
	Creates an empty socket.
	Socket (const SockType type, const char *ipaddr_local, const int port_local)
	Socket (const SockType type, const char *ipaddr_local, const int port_local, const char *ipaddr_remote, const int port_remote)
Protected Attributes
SockType	m_type
long	m_timeout
bool	m_bTout
int	m_osError
int	m_refcount
Channel *	m_channel
Reception *	m_recpt
Address	m_remote
Address	m_local
RawSocket	m_skCom
Friends
class	ServerSocket
	Creates custom socket.

---

Detailed Description

Basic socket encapsulation class.

This class has the ability to encapsulate a TCP/IP socket. This class handles at an abstract level both UDP and TCP sockets, as well as client sockets or serever sockets (when they are generated by a request being accepted by a socket).

All the operations may be made blocking, non blocking or timed with the Socket::timeout() method. When the timeout is set to -1, all the calls are blocking forever. When the timeout is 0, all the method calls in the class will return immediately. When the timeout is greater than zero, then the calls will block for the given time in milliseconds.

If some operations timed out, it is possible to continue them calling the method Socket::continueOp(); this is useful for example in timed connection. Once the connection try has timed out, the program can try to continue connection request or to stop it.

Note:

Blocking behavior is always emulated. Internally, socket are all set to non-blocking and select() call is used to wait temporarily or indefinitely on the socket.

Some operations, as the connection, are available depending on the socket type.

Definition at line 74 of file cabal_socket.h.

---

Constructor & Destructor Documentation

Cabal::Socket::Socket (  const SockType  type  )  [inline, protected]

Creates an empty socket. All internal fields are set to reasonable defaults. Subclasses have the responsibility to initiate proper connection, or to fill with consistent data before the use. Local and remote ports and address are meant to be helper for subclasses that are willing to be built using literal strings. Definition at line 134 of file cabal_socket.h.

virtual Cabal::Socket::~Socket (   )  [inline, virtual]

Destroys the socket. If the socket is currently conencted, the connection is cleanly closed. Definition at line 196 of file cabal_socket.h. References close().

Cabal::Socket::Socket (  const Socket &   )  throw ( InitError )

Copies a socket. The underlying system level socket is duplicated with dup() or equivalent system call. This makes the two socket (the original one and this copy) completely independent after this call. Exceptions: InitError  if the system cannot allocate a new socket. Definition at line 26 of file ltlib/cabal_socket.cpp.

---

Member Function Documentation

bool Cabal::Socket::bind (  const Address &  local  )

Binds a socket with an address. Both UDP and TCP sockets may be bound to a determinate address, or not bound at all. To decide the port at which the address should be bound, use "0.0.0.0" as address. Parameters: local  the address and port at which the socket has to be bound locally. Returns: true if sucessful Definition at line 45 of file ltlib/cabal_socket.cpp. References Cabal::Address::address().

Channel* Cabal::Socket::channel (   )  const [inline]

Returns the channel this socket is bound to, or 0 if the channel is unbound. See also: channel( Channel * ) Definition at line 378 of file cabal_socket.h.

void Cabal::Socket::channel (  Channel *  chn, Reception *  rcpt )

Binds this socket to a certain channel. Channels automatically listen for incoming data from sockets and invokes automatically transmissions when the network is clear to send. As channels are doing this operations in behalf of the sockets, a bound socket becomes "managed". A managed socket does not handles timeout and does not checks for data to become ready, because this operations are supposed to be taken by the manager of that socket. Sockets are created unbound, and can be bound at a later moment. To unbound a socket, call this method with parameter 0. If a socket is read-write, that is, if some data can be received by the socket, a reception object must be also given. The object becomes property of the socket, and is disposed when the socket is destroyed or when the channel is removed. The reception will be periodically called back by the channel when it senses new data incoming on the socket, and must perform its operations as fast as possible. See also: Cabal::Reception for more details. Parameters: chn  channel on which the socket is to be channelled rcpt  Reception object listening for incoming data on the socket. Definition at line 178 of file ltlib/cabal_socket.cpp. References Cabal::Channel::addSocket(), and Cabal::Channel::removeSocket(). Referenced by Cabal::Connection::schedule().

bool Cabal::Socket::close (   )  [virtual]

Closes the socket. Releases the low level communication socket, as well as internal resources as local and remote Address pointers. Returns: true on success, false on failure. If the failure is due to an OS error, then osError() returns 0. Reimplemented in Cabal::TCPSocket. Definition at line 154 of file ltlib/cabal_socket.cpp. Referenced by ~Socket().

bool Cabal::Socket::closed (   )  const [inline]

Returns true if the socket has been closed. Returns: true if the socket is closed. Definition at line 328 of file cabal_socket.h. Referenced by Cabal::Channel::process().

bool Cabal::Socket::hasTimedOut (   )  const [inline]

Returns true if the last operation timed out. A timeout has not (always) to be considered an error, so a separate method is provided to test if a function returned because a timeout has elapsed. Returns: true if last operation timed out. Definition at line 316 of file cabal_socket.h. Referenced by Cabal::TCPSocket::recvAll(), and Cabal::TCPSocket::sendAll().

const Address& Cabal::Socket::local (   )  const [inline]

Returns local address of the connection. This method returns the address of the local connection if it has been bound to any given port or local address; it returns 0 if no binding has been done. Returns: local address. Definition at line 294 of file cabal_socket.h.

const char* Cabal::Socket::local_ip (   )  [inline]

Returns the local ip address. See also: remote_ip(); Definition at line 404 of file cabal_socket.h. References Cabal::Address::ip().

bool Cabal::Socket::managed (   )  const [inline]

Returns the managed status of this socket. A managed socket does not handles timeout and does not checks for data to become ready, because this operations are supposed to be taken by the manager of that socket. By default, sockets are created unmanaged. Returns: true if the socket is managed, false otherwise Definition at line 388 of file cabal_socket.h. Referenced by Cabal::Connection::Connection(), and Cabal::Connection::schedule().

int Cabal::Socket::osError (   )  const [inline]

Return last OS error. This returns the OS dependant error that has been caused by the last operation on the socket, or 0 if the last operation was successful. Returns: last oepration error or 0 if successful Definition at line 323 of file cabal_socket.h. Referenced by Cabal::Channel::process().

virtual int Cabal::Socket::rawRecv (  void *  data, const int  len )  [protected, pure virtual]

Subclasses hook to receive data. This is called by recv() method to allow subclasses to specialize the job. All the preparation and error handling part are done by recv(), subclasses just need to implement this abstract method. Parameters: data  buffer of data be received. len  maximum length of received data (lenght of the buffer). Returns: amount of data received. Implemented in Cabal::TCPSocket, and Cabal::UDPSocket. Referenced by recv().

virtual int Cabal::Socket::rawSend (  const void *  data, const int  len )  [protected, pure virtual]

Subclasses hook to send data. This is called by send() method to allow subclasses to specialize the job. All the preparation and error handling part are done by send(), subclasses just need to implement this abstract method. Parameters: data  buffer where to get the data to be sent. len  amount of data to be sent. Returns: amount of data received. Implemented in Cabal::TCPSocket, and Cabal::UDPSocket. Referenced by send().

RawSocket Cabal::Socket::rawSocket (   )  const [inline]

Returns underlying system socket. This is used to put the low level OS socket into functions that are not provided or managed by the Cabal layer. The RawSocket type maps to the OS dependant socket type (is a typedef to it). Returns: OS dependant socket value. Definition at line 337 of file cabal_socket.h. Referenced by Cabal::Channel::process().

int Cabal::Socket::recv (  void *  buffer, const int  len )  [virtual]

Reads the data ready to be received on the socket. This method only returns data that is currently available on the sockets; if the socket has a certain timeout set, it blocks until the timeout expires, or until a first data is available. The function fills the buffer with the minimum between len and the data immediately available. Notice that on UDP connection, whole packet (datagrams) are always made available altogether, so if the buffer is big enough ( len > 1448 ), a whole datagram is transferred into it. This is true also for TCP, but packet lenght may vary and is not determined by either part of the transmission. Under UDP, the remote() member will return the origin address of the last received packet. This is true also for TCP, but under TCP there isn't the possibility that the remote end of the communication changes. Parameters: buffer  the place where to store the incoming data len  the size of buffer, and also the maximum length of data available. Returns: amount of data stored in the buffer, zero if no data can't be read or -1 on error. Definition at line 91 of file ltlib/cabal_socket.cpp. References rawRecv(). Referenced by Cabal::TCPSocket::recvAll(), and Cabal::TCPSocket::recvLine().

const Address& Cabal::Socket::remote (   )  const [inline]

Returns the remote address. This method returns the address of the other side of the connection, if the socket is connection oriented (TCP), or the address of the last received packet sender, if the connection is datagram oriented (UDP). Returns: remote address. Definition at line 287 of file cabal_socket.h.

const char* Cabal::Socket::remote_ip (   )  [inline]

Returns the remote IP address. ip() method of Address class is not const; for this reason, m_remote.address().ip() does not respect const correctness. This method respects const correctness and returns a const pointer to the ip of remote address. Returns: the IP of the remote address Definition at line 397 of file cabal_socket.h. References Cabal::Address::ip().

int Cabal::Socket::send (  const void *  buffer, const int  len )  [virtual]

Send a single packet of data. Sends data from buffer; the transmission may not be sucessful, or may transfer only part of the data requested to be sent. In either case, the amount of sent data is returned. Usually, if the underlying protocol is TCP, it is possible that the underlying kernel TCP stack is willing to accept but a part of the data for a complete packet; or, under advanced OS, the stack may have determined an optimal MTU that is currently available on the stream, and accept only that amount. The user must take care to send again the par of the data stream that has not been transferred with the previous call. If the protocol used is UDP, the data is usually transferred as a whole packet (datagram); user should take extra care to provide data that can fit a suitable UDP datagram; the maximum theorical lenght is 1500 bytes, but it may be lower depending on the quality and MTU (maximum tranfer unit) of the connection with the target. The function must be used only on a connected socket, if TCP is used, or only after having set the remote address, if UDP is used. Parameters: buffer  the area that will be transferred len  the amount of data to be transferred. Returns: amount of data transferred, or -1 on error. It may be 0 if the function had not been able to send the data in the given timelapse. Definition at line 121 of file ltlib/cabal_socket.cpp. References rawSend().

void Cabal::Socket::timeout (  const long  to  )  [inline]

Sets a timeout in seconds. To set infinite timeout (blocking sockets), use -1; to set nonblocking, use 0. Else, use the amount of milliseconds that the socket should block before to returning an unsucessful operation- Parameters: to  timeout to set in milliseconds, 0 for nonblocking and -1 for infinite. Definition at line 309 of file cabal_socket.h.

long Cabal::Socket::timeout (   )  const [inline]

Returns currently set timeout in milliseconds. If timeout is infinite, it returns -1, while if it returns 0, the socket are nonblocking. Returns: timeout setting in milliseconds. Definition at line 301 of file cabal_socket.h.

---

Friends And Related Function Documentation

friend class ServerSocket [friend]

Creates custom socket. This constructor creates a socket of kind TCP or UDP, depending on the type parameter. A timeout can be provided to determine the blocking nature of the socket; -1 meaning that the socket operations will be blocking, 0 that the operations will be unblocking, and > 0 that the operations will block for a certain number of milliseconds, and then return the control to the program. A local address may be immediately provided; if so, the socket is immediately bound to a local address. A remote address may also be given; if the socket is of TCP type, a connection try is immediately initiated, while if the socket is UDP, the remote field is just stored for sending datagrams later on. Addresses ownership is set to the socket, so they will be deleted by this class destructor; do not pass address to static Addresses object, and do not destroy them. If there are no particular interface or address requirements, the local address may be set to new Address( "0.0.0.0:port" ); be careful: if you do this with an UDP socket, the remote host won't be able to send packets back to you (as the local address is sent as real source address in UDP; in TCP it is overwritten by the real used interface address). An init error is thrown if the addresses are invalid, or if the binding and/or connection process fail. For nonblocking TCP sockets having a remote field, the connection returns immediately without failing; the status of the socket is set to OT_CONNECTING and the application can call continueOp() later on to complete connection operation. Parameters: type  ST_TCP to create a TCP socket, or ST_UDP to create an UDP socket. timeout  -1 to set the socket to blocking, 0 for nonblocking and > 0 for automatic timeout. local  optional local address where to bind our socket. Definition at line 190 of file cabal_socket.h.

---

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

• cabal_socket.h
• ltlib/cabal_socket.cpp
• src/cabal_socket.cpp

---