#include <inetsocketclient.h>

Inherits socketclient, and inetsocketutil.

Public Member Functions
	inetsocketclient ()

virtual	~inetsocketclient ()

void	setParameters (dictionary< const char , const char > *cd)

void	randomizeHosts (bool randomize)

void	randomizeAddresses (bool randomize)

void	setRandomSeed (uint32_t seed)

int32_t	connect ()

Public Member Functions inherited from socketclient
	socketclient ()

virtual	~socketclient ()

virtual bool	supportsBlockingAndNonBlockingModes ()

virtual bool	setNonBlockingMode (bool nonblockingmode)

virtual bool	getNonBlockingMode ()

virtual int32_t	ioCtl (int32_t command, void *arg)

Public Member Functions inherited from client
	client ()

virtual	~client ()

void	setTimeoutSeconds (int32_t timeoutsec)

void	setTimeoutMicroseconds (int32_t timeoutusec)

void	setRetryWait (uint32_t retrywait)

void	setTries (uint32_t tries)

void	setVerboseConnectError (const char *error)

int32_t	getTimeoutSeconds ()

int32_t	getTimeoutMicroseconds ()

uint32_t	getRetryWait ()

uint32_t	getTries ()

const char *	getVerboseConnectError ()

Public Member Functions inherited from filedescriptor
	filedescriptor ()

virtual	~filedescriptor ()

virtual bool	close ()

int32_t	getFileDescriptor ()

void	setFileDescriptor (int32_t filedesc)

bool	setIsStream (bool isstream)

bool	getIsStream ()

int32_t	duplicate ()

bool	duplicate (int32_t newfd)

void	setSocketLayer (socketlayer *layer)

socketlayer *	getSocketLayer ()

virtual off64_t	getPosition ()

virtual off64_t	setPositionRelativeToBeginning (off64_t offset)

virtual off64_t	setPositionRelativeToCurrent (off64_t offset)

virtual off64_t	setPositionRelativeToEnd (off64_t offset)

ssize_t	write (uint16_t number)

ssize_t	write (uint32_t number)

ssize_t	write (uint64_t number)

ssize_t	write (int16_t number)

ssize_t	write (int32_t number)

ssize_t	write (int64_t number)

ssize_t	write (float number)

ssize_t	write (double number)

ssize_t	write (byte_t character)

ssize_t	write (char character)

ssize_t	write (wchar_t character)

ssize_t	writeUcs2 (ucs2_t character)

ssize_t	write (bool value)

ssize_t	write (const byte_t *string)

ssize_t	write (const char *string)

ssize_t	write (const wchar_t *string)

ssize_t	writeUcs2 (const ucs2_t *string)

ssize_t	write (const byte_t *string, size_t size)

ssize_t	write (const char *string, size_t length)

ssize_t	write (const wchar_t *string, size_t length)

ssize_t	writeUcs2 (const ucs2_t *string, size_t length)

ssize_t	write (const void *buffer, size_t size)

ssize_t	write (uint16_t number, int32_t sec, int32_t usec)

ssize_t	write (uint32_t number, int32_t sec, int32_t usec)

ssize_t	write (uint64_t number, int32_t sec, int32_t usec)

ssize_t	write (int16_t number, int32_t sec, int32_t usec)

ssize_t	write (int32_t number, int32_t sec, int32_t usec)

ssize_t	write (int64_t number, int32_t sec, int32_t usec)

ssize_t	write (float number, int32_t sec, int32_t usec)

ssize_t	write (double number, int32_t sec, int32_t usec)

ssize_t	write (byte_t character, int32_t sec, int32_t usec)

ssize_t	write (char character, int32_t sec, int32_t usec)

ssize_t	write (wchar_t character, int32_t sec, int32_t usec)

ssize_t	writeUcs2 (ucs2_t character, int32_t sec, int32_t usec)

ssize_t	write (bool value, int32_t sec, int32_t usec)

ssize_t	write (const byte_t *string, int32_t sec, int32_t usec)

ssize_t	write (const char *string, int32_t sec, int32_t usec)

ssize_t	write (const wchar_t *string, int32_t sec, int32_t usec)

ssize_t	writeUcs2 (const ucs2_t *string, int32_t sec, int32_t usec)

ssize_t	write (const byte_t *string, size_t size, int32_t sec, int32_t usec)

ssize_t	write (const char *string, size_t length, int32_t sec, int32_t usec)

ssize_t	write (const wchar_t *string, size_t length, int32_t sec, int32_t usec)

ssize_t	writeUcs2 (const ucs2_t *string, size_t length, int32_t sec, int32_t usec)

ssize_t	write (const void *buffer, size_t size, int32_t sec, int32_t usec)

ssize_t	read (uint16_t *buffer)

ssize_t	read (uint32_t *buffer)

ssize_t	read (uint64_t *buffer)

ssize_t	read (int16_t *buffer)

ssize_t	read (int32_t *buffer)

ssize_t	read (int64_t *buffer)

ssize_t	read (float *buffer)

ssize_t	read (double *buffer)

ssize_t	read (byte_t *buffer)

ssize_t	read (char *buffer)

ssize_t	read (wchar_t *buffer)

ssize_t	readUcs2 (ucs2_t *buffer)

ssize_t	read (bool *buffer)

ssize_t	read (byte_t *buffer, size_t size)

ssize_t	read (char *buffer, size_t length)

ssize_t	read (wchar_t *buffer, size_t length)

ssize_t	readUcs2 (ucs2_t *buffer, size_t length)

ssize_t	read (void *buf, size_t size)

ssize_t	read (char *buffer, const char terminator)

ssize_t	read (char *buffer, const char terminator, size_t maxbytes)

ssize_t	read (uint16_t *buffer, int32_t sec, int32_t usec)

ssize_t	read (uint32_t *buffer, int32_t sec, int32_t usec)

ssize_t	read (uint64_t *buffer, int32_t sec, int32_t usec)

ssize_t	read (int16_t *buffer, int32_t sec, int32_t usec)

ssize_t	read (int32_t *buffer, int32_t sec, int32_t usec)

ssize_t	read (int64_t *buffer, int32_t sec, int32_t usec)

ssize_t	read (float *buffer, int32_t sec, int32_t usec)

ssize_t	read (double *buffer, int32_t sec, int32_t usec)

ssize_t	read (byte_t *buffer, int32_t sec, int32_t usec)

ssize_t	read (char *buffer, int32_t sec, int32_t usec)

ssize_t	read (wchar_t *buffer, int32_t sec, int32_t usec)

ssize_t	readUcs2 (ucs2_t *buffer, int32_t sec, int32_t usec)

ssize_t	read (bool *buffer, int32_t sec, int32_t usec)

ssize_t	read (byte_t *buffer, size_t size, int32_t sec, int32_t usec)

ssize_t	read (char *buffer, size_t length, int32_t sec, int32_t usec)

ssize_t	read (wchar_t *buffer, size_t length, int32_t sec, int32_t usec)

ssize_t	readUcs2 (ucs2_t *buffer, size_t length, int32_t sec, int32_t usec)

ssize_t	read (void *buf, size_t size, int32_t sec, int32_t usec)

ssize_t	read (char *buffer, const char terminator, int32_t sec, int32_t usec)

ssize_t	read (char *buffer, const char terminator, size_t maxbytes, int32_t sec, int32_t usec)

ssize_t	read (char *buffer, const char terminator, size_t maxbytes, char escapechar, int32_t sec, int32_t usec)

int32_t	waitForNonBlockingRead (int32_t sec, int32_t usec)

int32_t	waitForNonBlockingWrite (int32_t sec, int32_t usec)

void	setRetryInterruptedReads (bool retry)

bool	getRetryInterruptedReads ()

void	setRetryInterruptedWrites (bool retry)

bool	getRetryInterruptedWrites ()

void	setRetryInterruptedWaits (bool retry)

bool	getRetryInterruptedWaits ()

void	setRetryInterruptedFcntl (bool retry)

bool	getRetryInterruptedFcntl ()

void	setRetryInterruptedIoctl (bool retry)

bool	getRetryInterruptedIoctl ()

void	setAllowShortReads (bool allow)

bool	getAllowShortReads ()

void	setAllowShortWrites (bool allow)

bool	getAllowShortWrites ()

virtual bool	passFileDescriptor (int32_t fd)

virtual bool	passFileDescriptor (int32_t fd, int32_t sec, int32_t usec)

virtual bool	receiveFileDescriptor (int32_t *fd)

virtual bool	receiveFileDescriptor (int32_t *fd, int32_t sec, int32_t usec)

virtual bool	passSocket (int32_t sock)

virtual bool	passSocket (int32_t sock, int32_t sec, int32_t usec)

virtual bool	receiveSocket (int32_t *sock)

virtual bool	receiveSocket (int32_t *sock, int32_t sec, int32_t usec)

void	setTranslateByteOrder (bool translate)

bool	getTranslateByteOrder ()

virtual int32_t	fCntl (int32_t command, long arg)

bool	setNaglesAlgorithmEnabled (bool enabled)

bool	getNaglesAlgorithmEnabled ()

bool	setSocketWriteBufferSize (int32_t size)

bool	getSocketWriteBufferSize (int32_t *size)

bool	setSocketReadBufferSize (int32_t size)

bool	getSocketReadBufferSize (int32_t *size)

bool	disableIPv4 ()

bool	enableIPv4 ()

const char *	getType ()

char *	getPeerAddress ()

bool	setWriteBufferSize (size_t size)

size_t	getWriteBufferSize ()

bool	flushWriteBuffer (int32_t sec, int32_t usec)

bool	setReadBufferSize (size_t size)

size_t	getReadBufferSize ()

void	setMmapBufferingEnabled (bool enabled)

bool	getMmapBufferingEnabled ()

bool	isCurrentBlockMmapBuffered ()

off64_t	getCurrentBlockOffset ()

bool	setCloseOnExec (bool close)

bool	getCloseOnExec ()

Public Member Functions inherited from input
	input ()

virtual	~input ()

ssize_t	read (char *buffer, const char terminator)

ssize_t	read (char *buffer, const char terminator, size_t maxbytes)

ssize_t	read (char *buffer, const char terminator, int32_t sec, int32_t usec)

ssize_t	read (char *buffer, const char terminator, size_t maxbytes, int32_t sec, int32_t usec)

ssize_t	read (char *buffer, const char terminator, size_t maxbytes, char escapechar, int32_t sec, int32_t usec)

Public Member Functions inherited from object
virtual	~object ()

Public Member Functions inherited from output
	output ()

virtual	~output ()

virtual ssize_t	printf (const char *format,...)

virtual ssize_t	printf (const char format, va_list argp)

virtual ssize_t	printf (const wchar_t *format,...)

virtual ssize_t	printf (const wchar_t format, va_list argp)

virtual ssize_t	printfUcs2 (const ucs2_t *format,...)

virtual ssize_t	printfUcs2 (const ucs2_t format, va_list argp)

void	safePrint (byte_t c)

void	safePrint (const byte_t *str)

void	safePrint (const byte_t *str, int32_t length)

void	safePrint (char c)

void	safePrint (const char *str)

void	safePrint (const char *str, int32_t length)

void	printBits (byte_t value)

void	printBits (uint16_t value)

void	printBits (uint32_t value)

void	printBits (uint64_t value)

void	printBits (char value)

void	printBits (int16_t value)

void	printBits (int32_t value)

void	printBits (int64_t value)

void	printBits (const byte_t *bits, uint64_t size)

void	printHex (const byte_t *data, uint64_t size)

void	printHex (const byte_t *data, uint64_t size, uint16_t indent)

Public Member Functions inherited from inetsocketutil
	inetsocketutil ()

virtual	~inetsocketutil ()

void	setHost (const char *host)

void	setPort (uint16_t port)

const char *	getHost ()

uint16_t	getPort ()

Additional Inherited Members
Static Public Member Functions inherited from filedescriptor
static bool	supportsPassAndReceiveFileDescriptor ()

static bool	supportsPassAndReceiveSocket ()

static bool	createPipe (filedescriptor readfd, filedescriptor writefd)

static uint16_t	convertHostToNet (uint16_t value)

static uint32_t	convertHostToNet (uint32_t value)

static uint64_t	convertHostToNet (uint64_t value)

static uint16_t	convertNetToHost (uint16_t value)

static uint32_t	convertNetToHost (uint32_t value)

static uint64_t	convertNetToHost (uint64_t value)

static uint16_t	convertHostToLittleEndian (uint16_t value)

static uint32_t	convertHostToLittleEndian (uint32_t value)

static uint64_t	convertHostToLittleEndian (uint64_t value)

static uint16_t	convertLittleEndianToHost (uint16_t value)

static uint32_t	convertLittleEndianToHost (uint32_t value)

static uint64_t	convertLittleEndianToHost (uint64_t value)

Detailed Description

The inetsocketclient class allows you to write programs that can talk to other programs across a network over TCP stream sockets.

The inetsocketclient class provides methods for connecting to servers. Its ultimate parent class: filedescriptor provides methods for reading and writing data and closing connections.

Constructor & Destructor Documentation

◆ inetsocketclient()

inetsocketclient::inetsocketclient ( )

Creates an instance of the inetsocketclient class.

◆ ~inetsocketclient()

virtual inetsocketclient::~inetsocketclient ( )

virtual

Deletes this instance of the inetsocketclient class.

Member Function Documentation

◆ connect()

int32_t inetsocketclient::connect ( )

virtual

Attempts to connect to the "host" and "port" set earlier using one of the setParameters() methods. If the connection fails, it will retry, for a total of "tries" attempts, waiting "retrywait" seconds between each attempt.

If "host" is a comma-separated list of hosts, then an attempt will be made to connect to each until the attempt succeeds, or there are no more hosts left to try.

If each host resolves to multiple addresses (ie. if round-robin DNS or another DNS-based load-balancing strategy is used), then an attempt will be made to connect to each address until the attempt succeeds or there are no more addresses left to try. This process will be tried "tries" times.

For example, if...

"host" is: "serverset1,serverset2"
serverset1 resolves to 10.0.0.1 and 10.0.0.2
serverset2 resolves to 10.0.1.1 and 10.0.1.2
"tries" is set to 2 then 2 attempts will be made to connect to each of 10.0.0.1, 10.0.0.2, 10.0.1.1, and 10.0.1.2, by default, in random order.

Setting "tries" to 0 will cause it to try to connect to the first host/address indefinitely (not recommended with multiple hosts). Setting "retrywait" to 0 will cause it to try to connect over and over as fast as possible (not recommended).

Each attempt to connect will wait "timeoutsec" seconds and "timeoutusec" microseconds for the connect to succeed. Specifying -1 for either parameter will cause the attempt to wait until the underlying protocol times out which may be up to 2 minutes.

Returns RESULT_SUCCESS on success and RESULT_ERROR on failure.

Note that if your system does not support getaddrinfo() then connect() uses the hostentry and protocolentry classes. If you are using this method in a multithreaded application, you may need to supply those classes with mutexes. See hostentry.h and protocolentry.h for more detail.

Notes on round-robin DNS and DNS-based load-balancing:

By default, connect() randomizes the list of addresses that each host resolves to. This is intended to work around two issues.

Issue 1: When round-robin DNS is used, if one host is down, then the next host in the list receives all of the traffic that would have gone to the downed host. It is usually prefereable for the traffic to be distributed among the remaining hosts instead. Randomization of the list of addresses accomplishes this.

Issue 2: Rudiments uses getaddrinfo() if it is available, but implementations of getaddrinfo() vary widely.

Some implementations sort the list of addresses that each host resolves to rather than returning them in the order returned by the DNS server, defeating any attempt at DNS-based load-balancing.

Some implementations support a sortv4=no directive in /etc/gai.conf that instructs getaddrinfo() not to sort the addresses but many do not.

Some implementations randomize the list.

Some implementations return the list in the order returned by DNS.

Rudiments doesn't have a good way of knowing how getaddrinfo() is implemented or configured, so to err on the side of caution, connect() randomizes the list of addresses that each host resolves to.

Randomization can be disabled and configured using randomizeHosts(false) and/or randomizeAddresses(false).

Reimplemented from client.

◆ randomizeAddresses()

void inetsocketclient::randomizeAddresses ( bool randomize )

Instructs connect() whether or not to randomize the list of addresses that "host" resolves to. Defaults to true.

See connect() for issues that this can cause on some platforms or environments.

◆ randomizeHosts()

void inetsocketclient::randomizeHosts ( bool randomize )

"host" may be a list of comma-separated hosts/addresses. This method instructs connect() whether or not to randomize this list.

Randomizing the list can provide inexpensive load balancing.

Not randomizing the list can provide inexpensive failover.

Defaults to true.

◆ setParameters()

void inetsocketclient::setParameters ( dictionary< const char *, const char * > * cd )

virtual

Queries "cd" for "host", "port", "timeoutsec", "timeoutusec", "retrywait" and "tries" and configures this instance to use the result when connect() is called.

Reimplemented from client.

◆ setRandomSeed()

void inetsocketclient::setRandomSeed ( uint32_t seed )

Sets thte seed used when randomizing addresses to "seed".

By default the random number generator used internally is seeded using randomnumber::getSeed(). This may or may not be suitable as it will fall back to seeding the generator with the time of day on platforms that don't support any other method.

This method allows you to provide a more suitable seed if necessary.

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ inetsocketclient()

◆ ~inetsocketclient()

Member Function Documentation

◆ connect()

◆ randomizeAddresses()

◆ randomizeHosts()

◆ setParameters()

◆ setRandomSeed()