Aria: ArSocket Class Reference

- Main Page
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# ArSocket Class Reference

`#include <ArSocket.h>`

List of all members.

## Detailed Description

socket communication wrapper

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

See also:
  socketServerExample::cpp

  socketClientExample::cpp

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

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

- ArSocket.h