Detailed Description

Contains information about the physical socket connection.

This object is used internally by HttpServer when sending and receiving data on either an insecure or secure SSL connection.

#include <SoDispCon.h>

Inheritance diagram for SoDispCon:

[legend]

Public Member Functions
	SoDispCon ()
	Uninitialized storage; call SoDispCon_constructor before use. More...

int	connect (const char host, U16 port, const void bindIntfName=0, U16 bindPort=0, U32 timeout=1500, BaBool dgram=false, BaBool ipv6=false, char **errinfo=0)
	Connect an initialized, empty connection to a remote endpoint. More...

bool	isSecure ()
	Deprecated: Use getSharkSslCon(NULL). More...

bool	getSharkSslCon (SharkSslCon **sc)
	Inspect a connected transport's TLS implementation. More...

bool	isValid ()

bool	isIP6 ()

int	getPeerName (HttpSockaddr addr, U16 port=0)
	Read the remote peer endpoint. More...

int	getSockName (HttpSockaddr addr, U16 port=0)
	Read the local socket endpoint. More...

char *	addr2String (HttpSockaddr addr, char buf, int len)
	Format a numeric address without a port number. More...

bool	cmpAddr (HttpSockaddr *addr2)
	Compare an address with the current peer address, ignoring port numbers. More...

void	setTCPNoDelay (bool enable)
	Disable the TCP delay. More...

struct SoDisp *	getDispatcher ()

bool	hasMoreData ()

bool	dispatcherHasCon ()

bool	recEvActive ()

bool	sendEvActive ()

void	setDispSendEvent (SoDispCon_DispSendEv ev)
	Install a send-ready callback before enabling send events. More...

void	setDispRecEvent (SoDispCon_DispRecEv ev)
	Install a receive callback before enabling receive events. More...

int	readData (void *data, int len, bool relmutex=false)
	Read through the installed transport using its recorded readiness. More...

int	setNonblocking ()
	Select nonblocking socket mode. More...

int	setBlocking ()
	Select blocking socket mode. More...

int	sendData (const void *data, int len)
	Send an entire buffer through the installed transport. More...

int	asyncSend (int len)
	Begin or advance a send from the transport's asynchronous buffer. More...

int	sendChunkData (const void *data, int len)
	Send one HTTP chunk, including its hexadecimal size and CRLF delimiters. More...

int	asyncReady ()
	Advance pending output and inspect completion. More...

void *	allocAsynchBuf (int *size)
	Obtain transport-owned writable storage for asynchronous sending. More...

Constructor & Destructor Documentation

◆ SoDispCon()

SoDispCon::SoDispCon ( )

Uninitialized storage; call SoDispCon_constructor before use.

Member Function Documentation

◆ addr2String()

char * SoDispCon::addr2String	(	HttpSockaddr *	addr,
		char *	buf,
		int	len
	)

Format a numeric address without a port number.

Parameters

[in]	addr	Required address with the same family as this connection.
[out]	buf	Required writable storage for a NUL-terminated result.
[in]	len	Capacity in bytes including NUL; at least 16 for IPv4 or 46 for IPv6. Always provide writable storage even if capacity is rejected.

Returns: buf on success, NULL on invalid storage, family mismatch or conversion failure. No allocation is performed; do not use the output after failure.

◆ allocAsynchBuf()

void * SoDispCon::allocAsynchBuf ( int * size )

Obtain transport-owned writable storage for asynchronous sending.

Parameters

[in,out] size Required positive requested capacity in bytes; receives the actual capacity, which may differ. Always use the returned capacity.

Returns: Borrowed writable storage, or NULL if allocation fails. Requires a valid connected transport. Do not free it; close or transport buffer release invalidates it. Do not reallocate while an earlier send is pending.

◆ asyncReady()

int SoDispCon::asyncReady ( )

Advance pending output and inspect completion.

Returns: The current C++ wrapper converts the result to 0 or 1, so both completion and a negative error become 1. Use SoDispCon_asyncReady or SoDispCon_asyncReadyF when error handling must distinguish these cases.

◆ asyncSend()

int SoDispCon::asyncSend ( int len )

Begin or advance a send from the transport's asynchronous buffer.

Parameters

[in] len Positive payload byte count within the capacity returned by allocAsynchBuf for a new send. Do not alter the buffer until completion; use asyncReady to continue a pending send.

Returns: 1 complete, 0 pending, negative transport error. For a plain socket with no asynchronous buffer, the implementation returns 1 without sending; always allocate and check the buffer before use.

◆ cmpAddr()

bool SoDispCon::cmpAddr ( HttpSockaddr * addr2 )

Compare an address with the current peer address, ignoring port numbers.

Parameters

[in] addr2 Required address to compare; IPv4-mapped IPv6 is recognized.

Returns: True if equal, false if different or the peer address lookup fails.

◆ connect()

int SoDispCon::connect	(	const char *	host,
		U16	port,
		const void *	bindIntfName = `0`,
		U16	bindPort = `0`,
		U32	timeout = `1500`,
		BaBool	dgram = `false`,
		BaBool	ipv6 = `false`,
		char **	errinfo = `0`
	)

Connect an initialized, empty connection to a remote endpoint.

Parameters

[in]	host	Required NUL-terminated hostname or numeric IP address.
[in]	port	Remote TCP/UDP port in host byte order, 1..65535.
[in]	bindIntfName	Optional borrowed platform local interface/address used during the call; NULL selects the default.
[in]	bindPort	Local port in host byte order; zero lets the OS choose.
[in]	timeout	Positive connect timeout in milliseconds, default 1500. The legacy resolver path ignores this value; USE_ADDRINFO applies it to individual address attempts, not the entire DNS-and-connect operation.
[in]	dgram	TRUE selects UDP, FALSE TCP (default).
[in]	ipv6	TRUE requests IPv6, FALSE IPv4 (default); resolution depends on the selected network port.
[out]	errinfo	Optional output for borrowed platform resolver text; initialized to NULL. Do not free it or rely on text as a stable error code.

Returns: Zero on success, negative socket/resolver error on failure. The owned dispatcher mutex is released around resolution/connect and acquired again before return. Do not use the connection concurrently during this call. Failure can require cleanup; no socket ownership is returned to the caller.

◆ dispatcherHasCon()

bool SoDispCon::dispatcherHasCon ( )

Returns: True if the dispatcher registration flag is set.

◆ getDispatcher()

struct SoDisp * SoDispCon::getDispatcher ( )

Returns: Borrowed associated dispatcher, possibly NULL.

◆ getPeerName()

int SoDispCon::getPeerName	(	HttpSockaddr *	addr,
		U16 *	port = `0`
	)

Read the remote peer endpoint.

Parameters

[out]	addr	Required address output, valid only on success.
[out]	port	Optional port output in host byte order; NULL omits it.

Returns: Zero on success, nonzero platform socket status on failure.

◆ getSharkSslCon()

bool SoDispCon::getSharkSslCon ( SharkSslCon ** sc )

Inspect a connected transport's TLS implementation.

Parameters

[out] sc Optional output for a borrowed SharkSslCon pointer. Use it only when the call reports a SharkSSL connection; no ownership is transferred. NULL requests a secure-transport test, which can also succeed for OpenSSL.

Returns: True for the requested TLS test, false when unsupported. Call only after a transport has been successfully installed; this is not a constructor success test. A returned TLS pointer is invalidated by close or transfer.

◆ getSockName()

int SoDispCon::getSockName	(	HttpSockaddr *	addr,
		U16 *	port = `0`
	)

Read the local socket endpoint.

Parameters

[out]	addr	Required address output, valid only on success.
[out]	port	Optional port output in host byte order; NULL omits it.

Returns: Zero on success, nonzero platform socket status on failure.

◆ hasMoreData()

bool SoDispCon::hasMoreData ( )

Returns: Recorded receive readiness, not a byte count or a live socket probe.

◆ isIP6()

bool SoDispCon::isIP6 ( )

Returns: True for a connection recorded as IPv6, false for IPv4.

◆ isSecure()

bool SoDispCon::isSecure ( )

Deprecated: Use getSharkSslCon(NULL).

◆ isValid()

bool SoDispCon::isValid ( )

Returns: True if a socket handle is installed, false otherwise. This does not establish peer liveness or TLS handshake completion.

◆ readData()

int SoDispCon::readData	(	void *	data,
		int	len,
		bool	relmutex = `false`
	)

Read through the installed transport using its recorded readiness.

Parameters

[out]	data	Required writable buffer; returned bytes are not NUL-terminated.
[in]	len	Positive capacity in bytes.
[in]	relmutex	True allows the transport to release the owned dispatcher mutex while waiting, then reacquire it; false (default) keeps it held.

Returns: Positive byte count (possibly short), zero for no data, or negative transport/timeout error. Do not run concurrent reads on one connection.

◆ recEvActive()

bool SoDispCon::recEvActive ( )

Returns: True if receive events are enabled, false otherwise.

◆ sendChunkData()

int SoDispCon::sendChunkData	(	const void *	data,
		int	len
	)

Send one HTTP chunk, including its hexadecimal size and CRLF delimiters.

Parameters

[in]	data	Borrowed source containing len readable bytes.
[in]	len	Byte count from 0 through 65535. Zero sends the final empty chunk.

Returns: Zero on success, -1 on header, payload or delimiter send failure. Partial wire output can already exist on failure.

◆ sendData()

int SoDispCon::sendData	(	const void *	data,
		int	len
	)

Send an entire buffer through the installed transport.

Parameters

[in]	data	Borrowed source containing len readable bytes.
[in]	len	Nonnegative byte count.

Returns: Zero only if the transport reports the complete byte count; -1 for an invalid socket, E_SOCKET_WRITE_FAILED for a failed or short send. No partial count is supplied. May release/reacquire the dispatcher mutex. Use the async buffer API for nonblocking partial-send handling.

◆ sendEvActive()

bool SoDispCon::sendEvActive ( )

Returns: True if send-ready events are enabled, false otherwise.

◆ setBlocking()

int SoDispCon::setBlocking ( )

Select blocking socket mode.

Returns: Zero success, -1 if already blocking, or a platform failure status.

◆ setDispRecEvent()

void SoDispCon::setDispRecEvent ( SoDispCon_DispRecEv ev )

Install a receive callback before enabling receive events.

Parameters

[in] ev Required callback while receive events are active; borrowed.

◆ setDispSendEvent()

void SoDispCon::setDispSendEvent ( SoDispCon_DispSendEv ev )

Install a send-ready callback before enabling send events.

Parameters

[in] ev Required callback while send events are active; borrowed.

◆ setNonblocking()

int SoDispCon::setNonblocking ( )

Select nonblocking socket mode.

Returns: Zero success, -1 if already nonblocking, or a platform failure status. The recorded mode changes only when the platform operation succeeds.

◆ setTCPNoDelay()

void SoDispCon::setTCPNoDelay ( bool enable )

Disable the TCP delay.

What TCP normally does is queue up data so it only sends full packets out when possible. (This is called Nagle's algorithm.) Call this function if you do not want that behavior.

Parameters

[in] enable True disables Nagle; false enables it. No socket-option error status is returned; errors can be traced.

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ SoDispCon()

Member Function Documentation

◆ addr2String()

◆ allocAsynchBuf()

◆ asyncReady()

◆ asyncSend()

◆ cmpAddr()

◆ connect()

◆ dispatcherHasCon()

◆ getDispatcher()

◆ getPeerName()

◆ getSharkSslCon()

◆ getSockName()

◆ hasMoreData()

◆ isIP6()

◆ isSecure()

◆ isValid()

◆ readData()

◆ recEvActive()

◆ sendChunkData()

◆ sendData()

◆ sendEvActive()

◆ setBlocking()

◆ setDispRecEvent()

◆ setDispSendEvent()

◆ setNonblocking()

◆ setTCPNoDelay()