Aria: ArSocket Class Reference

ArSocket is a layer which allows you 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(). ArSocket extends some of these functions to set useful options (see method documentation for details). It also provides additional useful functions like writeString(), readString, setCloseCallback(), and more.

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().)

Some calls set an error code on failure in addition to returning false. This value is available from getError(). If getError() returns something other than NoErr, a text description of the error may be available from getErrorStr().


Public Types
enum	Error { NoErr, NetFail, ConBadHost, ConNoRoute, ConRefused, NameLookup }
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.
void	clearPartialReadString (void)
	Clears the partial string read.
bool	close ()
	Close the socket.
int	comparePartialReadString (const char *partialString)
	Compares a string against what was partially read.
bool	connect (const char host, int port, Type type=TCP, const char openOnIP=NULL)
	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)
bool	getBadRead (void) const
	Gets if we've had a bad read (you have to use error tracking for this).
bool	getBadWrite (void) const
	Gets if we've had a bad write (you have to use error tracking for this).
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 a code representing the last error.
const std::string &	getErrorStr () const
	Get a string containing a description of the last error. Only valid if getError() does not return NoErr.
bool	getErrorTracking (void)
	Gets whether we're doing error tracking or not.
int	getFD () const
	Get the file descriptor.
const char *	getIPString (void) const
	Gets the ip number as a string (this can be modified though).
ArTime	getLastStringReadTime (void)
	Gets the time we last successfully read a string from the socket.
bool	getLogWriteStrings (void)
	Gets whether we log the writeStrings or not.
const char *	getRawIPString (void) const
	Gets the raw ip number as a string.
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 socket information (socket "name"). Aspects of this "name" are accessible with sockAddrIn(), inAddr(), inPort().
bool	getStringUseWrongEndChars (void)
	Gets whether we log the writeStrings or not.
Type	getType () const
	Get the protocol type.
in_addr *	inAddr ()
	Accessor for the in_addr part of sockaddr.
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 data from the socket.
char *	readString (unsigned int msWait=0)
	Reads a string from the socket.
int	recvFrom (void msg, int len, sockaddr_in sin)
	Receive a message (short string) 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 (short string) on the socket.
int	sendTo (const void *msg, int len)
	Send a message (short string) 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.
void	setErrorTracking (bool errorTracking)
	Sets whether we're error tracking or not.
void	setIPString (const char *ipString)
	Sets the ip string.
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. Most importantly, calls to read() will return immediately, even if no data is available.
void	setReadStringIgnoreReturn (bool ignore)
	Whether to ignore carriage return characters in readString or not.
bool	setReuseAddress ()
	Set the reuse address value.
void	setStringUseWrongEndChars (bool useWrongEndChars)
	Sets whether we use the wrong (legacy) end chars or not.
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 data to the socket.
int	writeString (const char *str,...)
	Writes a string to the socket (adding end of line characters).
int	writeStringPlain (const char *str)
	Same as writeString(), but no varargs.
	~ArSocket ()
	Destructor.
Static Public Member Functions
static bool	addrHost (struct in_addr &addr, char *host)
	Convert an address structure to a hostname string.
static std::string	getHostName ()
	Get the localhost address.
static bool	hostAddr (const char *host, struct in_addr &addr)
	Convert a hostname 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 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 size_t	sockAddrLen ()
	Size of the sockaddr.
Static Public Attributes
static bool	ourInitialized
Protected Member Functions
void	doStringEcho (void)
	internal function that echos strings from read string
void	internalInit (void)
void	separateHost (const char rawHost, int rawPort, char useHost, size_t useHostSize, int *port)
void	setRawIPString (void)
	internal function that sets the ip string from the inAddr
Protected Attributes
bool	myBadRead
bool	myBadWrite
long	myBytesRecvd
long	myBytesSent
ArFunctor *	myCloseFunctor
bool	myDoClose
Error	myError
std::string	myErrorStr
bool	myErrorTracking
int	myFD
std::string	myIPString
ArTime	myLastStringReadTime
bool	myLogWriteStrings
bool	myNonBlocking
char	myRawIPString [128]
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
bool	myStringIgnoreReturn
size_t	myStringPos
size_t	myStringPosLast
bool	myStringWrongEndChars
Type	myType
ArMutex	myWriteStringMutex

Member Function Documentation

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)

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

Open a server port

Opens a server port, that is, a port that is bound to a local port (and optionally, address) and listens for new incoming connections. Use accept() to wait for a new incoming connection from a client.

In additon, internally this method calls setLinger(0), setReuseAddress(), and setNonBlock() to turn on these options (having these on is particularly useful for servers).

Parameters:

	port	Port number
	type	ArSocket::TCP or ArSocket::UDP.
	openOnIP	If given, only bind to the interface accociated with this address (Linux only) (by default, all interfaces are used)

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.

int ArSocket::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.

See also:: writeStringPlain()

ArSocket Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Member Function Documentation