ArSocket Class Reference

#include <ArSocket.h>

Detailed Description

socket communication wrapper

ArSocket is a layer which allows people to use the sockets networking interface in an operating system independent manner. All of the standard commonly used socket functions are implemented (such as open(), close(), connect(), accept(), read(), write(), hostToNetOrder(), netToHostOrder()). It also provides additional useful functions like writeString(), readString, setCloseCallback(). This class also contains the file descriptor which identifies the socket to the operating system.

In Windows, the sockets subsystem needs to be initialized and shutdown by the program. So when a program starts it must call Aria::init() and call Aria::shutdown() when it exits. (Or, to only initialize the socket system, and not do any other global Aria initialization, use ArSocket::init() and ArSocket::shutdown().)

See also:: socketServerExample::cpp
socketClientExample::cpp

Examples:: netServerExample.cpp, socketClientExample.cpp, and socketServerExample.cpp.

Definition at line 72 of file ArSocket.h.

Public Types

enum Error {
NoErr, NetFail, ConBadHost, ConNoRoute,
ConRefused
}

enum Type { UDP, TCP, Unknown }

Public Member Functions

bool accept (ArSocket *sock)

Accept a new connection.

ArSocket (int port, bool doClose, Type type)

Constructor which outomatically opens a server port.

ArSocket (const char *host, int port, Type type)

Constructor which automatically connects to a server as a client.

ArSocket ()

Constructor.

bool close ()

Close the socket.

bool connect (const char *host, int port, Type type=TCP)

Connect as a client to a server.

bool connectTo (struct sockaddr_in *sin)

Connect the socket to the given address.

bool connectTo (const char *host, int port)

Connect the socket to the given address.

void copy (ArSocket *s)

Copy socket structures.

bool copy (int fd, bool doclose)

Copy socket structures.

bool create (Type type)

Simply create a port.

bool findValidPort (int startPort, const char *openOnIP=NULL)

long getBytesRecvd (void)

Gets the number of bytes we've read.

long getBytesSent (void)

Gets the number of bytes we've written.

ArFunctor * getCloseCallback (void)

Sets the callback for when the socket is closed (nicely or harshly).

bool getEcho (void)

Gets if we are echoing on the readString calls this socket does.

Error getError () const

Get the last error.

const std::string & getErrorStr () const

Get the last error string.

int getFD () const

Get the file descriptor.

const char * getIPString (void) const

Gets the ip number as a string.

bool getLogWriteStrings (void)

Gets whether we log the writeStrings or not.

long getRecvs (void)

Gets the number of reads we've done.

long getSends (void)

Gets the number of writes we've done.

bool getSockName ()

Get the socket name. Stored in ArSocket::mySin.

Type getType () const

Get the protocol type.

in_addr * inAddr ()

Accessor for the in_addr.

unsigned short int inPort ()

Accessor for the port of the sockaddr.

bool open (int port, Type type, const char *openOnIP=NULL)

int read (void *buff, size_t len, unsigned int msWait=0)

Read from the socket.

char * readString (void)

Reads a string from the socket.

int recvFrom (void *msg, int len, sockaddr_in *sin)

Receive a message from the socket.

void resetTracking (void)

Resets the tracking information on the socket.

int sendTo (const void *msg, int len, struct sockaddr_in *sin)

Send a message on the socket.

int sendTo (const void *msg, int len)

Send a message on the socket.

bool setBroadcast ()

Set broadcast value.

void setCloseCallback (ArFunctor *functor)

Sets the callback for when the socket is closed (nicely or harshly).

void setDoClose (bool yesno)

Change the doClose value.

void setEcho (bool echo)

Sets echoing on the readString calls this socket does.

bool setLinger (int time)

Set the linger value.

void setLogWriteStrings (bool logWriteStrings)

Sets whether we log the writeStrings or not.

bool setNoDelay (bool flag)

Sets NODELAY option on TCP socket, which can reduce latency for small packet sizes.

bool setNonBlock ()

Set socket to nonblocking.

bool setReuseAddress ()

Set the reuse address value.

sockaddr_in * sockAddrIn ()

Accessor for the sockaddr.

void transfer (ArSocket *s)

Transfer ownership of a socket.

int write (const void *buff, size_t len)

Write to the socket.

int writeString (const char *str,...)

Writes a string to the socket (adding end of line characters)
Java and Python Wrappers: Not available in Java or Python wrapper libraries.

int writeStringPlain (const char *str)

Same as writeString, but no varargs, wrapper for java.

~ArSocket ()

Destructor.

Static Public Member Functions

static bool addrHost (struct in_addr &addr, char *host)

Convert an address structure to a host string.

static std::string getHostName ()

Get the localhost address.

static bool hostAddr (const char *host, struct in_addr &addr)

Convert a host string to an address structure.

static unsigned int hostToNetOrder (int i)

Convert an int from host byte order to network byte order.

static bool init ()

Initialize the OS sockets system, if neccesary.

static void inToA (struct in_addr *addr, char *buff)

Convert addr into string numerical address.

static const size_t maxHostNameLen ()

Max host name length.

static unsigned int netToHostOrder (int i)

Convert an int from network byte order to host byte order.

static void shutdown ()

Shutdown the OS sockets system, if neccesary.

static const size_t sockAddrLen ()

Size of the sockaddr.

Static Public Attributes

static bool ourInitialized = true

We're always initialized in Linux.

Protected Member Functions

void doStringEcho (void)

internal function that echos strings from read string

void internalInit (void)

void setIPString (void)

internal function that sets the ip string from the inAddr

Protected Attributes

long myBytesRecvd

long myBytesSent

ArFunctor * myCloseFunctor

bool myDoClose

Error myError

std::string myErrorStr

int myFD

char myIPString [128]

bool myLogWriteStrings

bool myNonBlocking

ArMutex myReadStringMutex

long myRecvs

long mySends

sockaddr_in mySin

bool myStringAutoEcho

char myStringBuf [1100]

char myStringBufEmpty [1]

bool myStringEcho

bool myStringGotComplete

bool myStringGotEscapeChars

bool myStringHaveEchoed

size_t myStringPos

size_t myStringPosLast

Type myType

ArMutex myWriteStringMutex

Constructor & Destructor Documentation

ArSocket::ArSocket ( const char * host,

int port,

Type type

)

Constructor which automatically connects to a server as a client.
Constructs the socket and connects it to the given host.
Parameters:

host hostname of the server to connect to

port port number of the server to connect to

type protocol type to use

Definition at line 88 of file ArSocket_LIN.cpp.

ArSocket::ArSocket ( int port,

bool doClose,

Type type

)

Constructor which outomatically opens a server port.
Constructs the socket and opens it as a server port.
Parameters:

port port number to bind the socket to

doClose automaticaly close the port if the socket is destructed

type protocol type to use

Definition at line 107 of file ArSocket_LIN.cpp.

Member Function Documentation

bool ArSocket::accept ( ArSocket * sock )

Accept a new connection.

Returns:
true if there are no errors, false if there are errors... not that if you're in non-blocking mode and there is no socket to connect that is NOT an error, you'll want to check the getFD on the sock you pass in to see if it is actually a valid socket.

Examples:
socketServerExample.cpp.

Definition at line 546 of file ArSocket_LIN.cpp.

bool ArSocket::copy ( int fd,

bool doclose

)

Copy socket structures.
Copy socket structures. Copy from one Socket to another will still have the first socket close the file descripter when it is destructed.
Definition at line 520 of file ArSocket_LIN.cpp.

bool ArSocket::findValidPort ( int startPort,

const char * openOnIP = NULL

)

Find the first valid unused port after startPort, and bind the socket to it.
Parameters:

startPort first port to try

openOnIP If given, only check ports open on the interface accociated with this address (Linux only)

Definition at line 336 of file ArSocket_LIN.cpp.

bool ArSocket::init ( void ) [static]

Initialize the OS sockets system, if neccesary.
In Windows, the networking subsystem needs to be initialized and shutdown individyaly by each program. So when a program starts they will need to call the static function ArSocket::init() and call ArSocket::shutdown() when it exits. For programs that use Aria::init() and Aria::uninit() calling the ArSocket::init() and ArSocket::shutdown() is unnecessary. The Aria initialization functions take care of this. These functions do nothing in Linux.
Definition at line 52 of file ArSocket_LIN.cpp.

bool ArSocket::open ( int port,

Type type,

const char * openOnIP = NULL

)

Open a server port
Parameters:

openOnIP If given, only check ports open on the interface accociated with this address (Linux only)

Examples:
socketServerExample.cpp.

Definition at line 236 of file ArSocket_LIN.cpp.

int ArSocket::read ( void * buff,

size_t len,

unsigned int msWait = 0

)

Read from the socket.

Parameters:

buff buffer to read into

len how many bytes to read

msWait if 0, don't block, if > 0 wait this long for data

Returns:
number of bytes read

Examples:
socketClientExample.cpp, and socketServerExample.cpp.

Definition at line 139 of file ArSocket.cpp.

char * ArSocket::readString ( void )

Reads a string from the socket.

Note:
This function can only read strings less than 512 characters long as it reads the characters into its own internal buffer (to compensate for some of the things the DOS telnet does).

Returns:
Data read, or an empty string (first character will be '\0') if no data was read. If there was an error reading from the socket, NULL is returned.

Definition at line 216 of file ArSocket.cpp.

bool ArSocket::setNoDelay ( bool flag )

Sets NODELAY option on TCP socket, which can reduce latency for small packet sizes.
If this socket is a TCP socket, then set the TCP_NODELAY flag, to disable the use of the Nagle algorithm (which waits until enough data is ready to send to fill a TCP frame, rather then sending the packet immediately).
Parameters:

flag true to turn on NoDelay, false to turn it off.

Returns:
true of the flag was successfully set, false if there was an error or this socket is not a TCP socket.

Definition at line 613 of file ArSocket_LIN.cpp.

void ArSocket::shutdown ( ) [static]

Shutdown the OS sockets system, if neccesary.
In Windows, the networking subsystem needs to be initialized and shutdown individyaly by each program. So when a program starts they will need to call the static function ArSocket::init() and call ArSocket::shutdown() when it exits. For programs that use Aria::init() and Aria::uninit() calling the ArSocket::init() and ArSocket::shutdown() is unnecessary. The Aria initialization functions take care of this. These functions do nothing in Linux.
Definition at line 66 of file ArSocket_LIN.cpp.

void ArSocket::transfer ( ArSocket * s ) [inline]

Transfer ownership of a socket.
transfer() will transfer ownership to this socket. The input socket will no longer close the file descriptor when it is destructed.
Definition at line 110 of file ArSocket.h.

int ArSocket::write ( const void * buff,

size_t len

)

Write to the socket.

Parameters:

buff buffer to write from

len how many bytes to write

Returns:
number of bytes written

Examples:
socketClientExample.cpp, and socketServerExample.cpp.

Definition at line 98 of file ArSocket.cpp.

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

Generated on Tue Feb 20 10:51:45 2007 for Aria by

1.4.0


Public Types
enum	Error { NoErr, NetFail, ConBadHost, ConNoRoute, ConRefused }
enum	Type { UDP, TCP, Unknown }
Public Member Functions
bool	accept (ArSocket *sock)
	Accept a new connection.
	ArSocket (int port, bool doClose, Type type)
	Constructor which outomatically opens a server port.
	ArSocket (const char *host, int port, Type type)
	Constructor which automatically connects to a server as a client.
	ArSocket ()
	Constructor.
bool	close ()
	Close the socket.
bool	connect (const char *host, int port, Type type=TCP)
	Connect as a client to a server.
bool	connectTo (struct sockaddr_in *sin)
	Connect the socket to the given address.
bool	connectTo (const char *host, int port)
	Connect the socket to the given address.
void	copy (ArSocket *s)
	Copy socket structures.
bool	copy (int fd, bool doclose)
	Copy socket structures.
bool	create (Type type)
	Simply create a port.
bool	findValidPort (int startPort, const char *openOnIP=NULL)
long	getBytesRecvd (void)
	Gets the number of bytes we've read.
long	getBytesSent (void)
	Gets the number of bytes we've written.
ArFunctor *	getCloseCallback (void)
	Sets the callback for when the socket is closed (nicely or harshly).
bool	getEcho (void)
	Gets if we are echoing on the readString calls this socket does.
Error	getError () const
	Get the last error.
const std::string &	getErrorStr () const
	Get the last error string.
int	getFD () const
	Get the file descriptor.
const char *	getIPString (void) const
	Gets the ip number as a string.
bool	getLogWriteStrings (void)
	Gets whether we log the writeStrings or not.
long	getRecvs (void)
	Gets the number of reads we've done.
long	getSends (void)
	Gets the number of writes we've done.
bool	getSockName ()
	Get the socket name. Stored in ArSocket::mySin.
Type	getType () const
	Get the protocol type.
in_addr *	inAddr ()
	Accessor for the in_addr.
unsigned short int	inPort ()
	Accessor for the port of the sockaddr.
bool	open (int port, Type type, const char *openOnIP=NULL)
int	read (void *buff, size_t len, unsigned int msWait=0)
	Read from the socket.
char *	readString (void)
	Reads a string from the socket.
int	recvFrom (void msg, int len, sockaddr_in sin)
	Receive a message from the socket.
void	resetTracking (void)
	Resets the tracking information on the socket.
int	sendTo (const void msg, int len, struct sockaddr_in sin)
	Send a message on the socket.
int	sendTo (const void *msg, int len)
	Send a message on the socket.
bool	setBroadcast ()
	Set broadcast value.
void	setCloseCallback (ArFunctor *functor)
	Sets the callback for when the socket is closed (nicely or harshly).
void	setDoClose (bool yesno)
	Change the doClose value.
void	setEcho (bool echo)
	Sets echoing on the readString calls this socket does.
bool	setLinger (int time)
	Set the linger value.
void	setLogWriteStrings (bool logWriteStrings)
	Sets whether we log the writeStrings or not.
bool	setNoDelay (bool flag)
	Sets NODELAY option on TCP socket, which can reduce latency for small packet sizes.
bool	setNonBlock ()
	Set socket to nonblocking.
bool	setReuseAddress ()
	Set the reuse address value.
sockaddr_in *	sockAddrIn ()
	Accessor for the sockaddr.
void	transfer (ArSocket *s)
	Transfer ownership of a socket.
int	write (const void *buff, size_t len)
	Write to the socket.
int	writeString (const char *str,...)
	Writes a string to the socket (adding end of line characters) Java and Python Wrappers: Not available in Java or Python wrapper libraries.
int	writeStringPlain (const char *str)
	Same as writeString, but no varargs, wrapper for java.
	~ArSocket ()
	Destructor.
Static Public Member Functions
static bool	addrHost (struct in_addr &addr, char *host)
	Convert an address structure to a host string.
static std::string	getHostName ()
	Get the localhost address.
static bool	hostAddr (const char *host, struct in_addr &addr)
	Convert a host string to an address structure.
static unsigned int	hostToNetOrder (int i)
	Convert an int from host byte order to network byte order.
static bool	init ()
	Initialize the OS sockets system, if neccesary.
static void	inToA (struct in_addr addr, char buff)
	Convert addr into string numerical address.
static const size_t	maxHostNameLen ()
	Max host name length.
static unsigned int	netToHostOrder (int i)
	Convert an int from network byte order to host byte order.
static void	shutdown ()
	Shutdown the OS sockets system, if neccesary.
static const size_t	sockAddrLen ()
	Size of the sockaddr.
Static Public Attributes
static bool	ourInitialized = true
	We're always initialized in Linux.
Protected Member Functions
void	doStringEcho (void)
	internal function that echos strings from read string
void	internalInit (void)
void	setIPString (void)
	internal function that sets the ip string from the inAddr
Protected Attributes
long	myBytesRecvd
long	myBytesSent
ArFunctor *	myCloseFunctor
bool	myDoClose
Error	myError
std::string	myErrorStr
int	myFD
char	myIPString [128]
bool	myLogWriteStrings
bool	myNonBlocking
ArMutex	myReadStringMutex
long	myRecvs
long	mySends
sockaddr_in	mySin
bool	myStringAutoEcho
char	myStringBuf [1100]
char	myStringBufEmpty [1]
bool	myStringEcho
bool	myStringGotComplete
bool	myStringGotEscapeChars
bool	myStringHaveEchoed
size_t	myStringPos
size_t	myStringPosLast
Type	myType
ArMutex	myWriteStringMutex