#include <SoDispCon.h>

Include dependency graph for HttpConnection.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	HttpConnection
	Contains information about the physical socket connection. More...

Macros
#define	HttpConnection_setKeepAlive(o) (o)->keepAlive=TRUE
	Enable persistent reuse after a completed HTTP request. More...

#define	HttpConnection_clearKeepAlive(o) (o)->keepAlive=FALSE
	Disable persistent reuse without immediately closing the socket. More...

#define	HttpConnection_keepAlive(o) (o)->keepAlive

#define	HttpConnection_getState(o) (o)->state

#define	HttpConnection_getServer(o) (o)->server

#define	HttpConnection_getDispatcher(o) SoDispCon_getDispatcher((SoDispCon*)o)

#define	HttpConnection_isSecure(o) SoDispCon_isSecure((SoDispCon*)o)
	Test a successfully installed transport for TLS. More...

#define	HttpConnection_isValid(o) SoDispCon_isValid((SoDispCon*)o)

#define	HttpConnection_sendData(o, data, len) SoDispCon_sendData((SoDispCon*)o, data, len)
	Send an entire buffer through the installed transport. More...

#define	HttpConnection_sendDataNT(o, data, len) SoDispCon_sendDataNT((SoDispCon*)o, data, len)
	Send all bytes with the sendData contract, but omit body tracing. More...

#define	HttpConnection_sendChunkData(o, data, len) SoDispCon_sendChunkData((SoDispCon*)o,data, len)
	Send one HTTP chunk, including its hexadecimal size and CRLF delimiters. More...

#define	HttpConnection_allocAsynchBuf(o, sizePtr) SoDispCon_allocAsynchBuf((SoDispCon*)o, sizePtr)
	Obtain transport-owned asynchronous send storage. More...

#define	HttpConnection_asyncSend(o, len) SoDispCon_asyncSend((SoDispCon*)o,len)
	Begin or advance a send from the transport's asynchronous buffer. More...

#define	HttpConnection_asyncReady(o) SoDispCon_asyncReady((SoDispCon*)o)
	Advance any pending asynchronous send without modifying its payload. More...

#define	HttpConnection_setNonblocking(o) SoDispCon_setNonblocking((SoDispCon*)o)
	Select nonblocking socket mode. More...

#define	HttpConnection_setBlocking(o) SoDispCon_setBlocking((SoDispCon*)o)
	Select blocking socket mode. More...

#define	HttpConnection_setTCPNoDelay(o, enable) SoDispCon_setTCPNoDelay((SoDispCon*)o, enable)
	Disable the TCP delay. More...

#define	HttpConnection_getPeerName(o, addr, port) SoDispCon_getPeerName((SoDispCon*)o, addr,port)
	Read the remote peer endpoint. More...

#define	HttpConnection_getSockName(o, addr, port) SoDispCon_getSockName((SoDispCon*)o, addr,port)
	Read the local socket endpoint. More...

#define	HttpConnection_addr2String(o, addr, buf, len) SoDispCon_addr2String((SoDispCon*)o, addr, buf, len)
	Format a numeric address without a port number. More...

#define	HttpConnection_cmpAddr(o, addr2) SoDispCon_cmpAddr((SoDispCon*)o, addr2)
	Compare an address with the current peer address, ignoring port numbers. More...

#define	HttpConnection_recEvActive(o) SoDispCon_recEvActive((SoDispCon*)o)

#define	HttpConnection_sendEvActive(o) SoDispCon_sendEvActive((SoDispCon*)o)

#define	HttpConnection_hasMoreData(o) (SoDispCon_hasMoreData((SoDispCon*)o) \|\| (o)->pushBackData)

#define	HttpConnection_dispatcherHasCon(o) SoDispCon_dispatcherHasCon((SoDispCon*)o)

#define	HttpConnection_setDispSendEvent(o, dispSendEvFp) SoDispCon_setDispSendEvent((SoDispCon*)o, dispSendEvFp)
	Install the send-ready callback before enabling events. More...

Typedefs
typedef HttpConnection	HttpConnection
	Contains information about the physical socket connection. More...

Enumerations
enum	HttpConnection_State
	Server connection lifecycle states. More...

Functions
BA_API void	HttpConnection_constructor (HttpConnection o, struct HttpServer server, struct SoDisp *dispatcher, SoDispCon_DispRecEv e)
	Initialize connection storage without opening a socket. More...

BA_API void	HttpConnection_setState (HttpConnection *o, HttpConnection_State state)
	Change lifecycle state, performing the associated cleanup. More...

BA_API int	HttpConnection_moveCon (HttpConnection o, HttpConnection newCon)
	Move the socket, transport state and pending input to another object. More...

BA_API void	HttpConnection_destructor (HttpConnection *o)
	Release pushback storage, unregister events, and close the connection. More...

BA_API int	HttpConnection_pushBack (HttpConnection o, const void d, int s)
	Prepend copied bytes to the input returned by subsequent reads. More...

BA_API int	HttpConnection_readData (HttpConnection con, void data, int len)
	Read pending pushback bytes first, otherwise perform an event-oriented read. More...

BA_API int	HttpConnection_blockRead (HttpConnection con, void data, int len)
	Read buffered bytes or wait for socket data. More...

Macro Definition Documentation

◆ HttpConnection_addr2String

#define HttpConnection_addr2String	(	o,
		addr,
		buf,
		len
	)	SoDispCon_addr2String((SoDispCon*)o, addr, buf, 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.

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_allocAsynchBuf

#define HttpConnection_allocAsynchBuf	(	o,
		sizePtr
	)	SoDispCon_allocAsynchBuf((SoDispCon*)o, sizePtr)

Obtain transport-owned asynchronous send storage.

Parameters

[in,out]	o	Connected object.
[in,out]	sizePtr	Positive requested capacity; receives actual capacity.

Returns: Borrowed buffer or NULL. See SoDispCon::allocAsynchBuf for lifetime.

◆ HttpConnection_asyncReady

#define HttpConnection_asyncReady ( o ) SoDispCon_asyncReady((SoDispCon*)o)

Advance any pending asynchronous send without modifying its payload.

Parameters

[in,out] o Connected object with an allocated asynchronous buffer.

Returns: 1 complete, 0 pending, negative transport error. Does not itself register a send-ready callback.

◆ HttpConnection_asyncSend

#define HttpConnection_asyncSend	(	o,
		len
	)	SoDispCon_asyncSend((SoDispCon*)o,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.

Parameters

[in,out] o Connected object with an allocated asynchronous buffer.

◆ HttpConnection_clearKeepAlive

#define HttpConnection_clearKeepAlive ( o ) (o)->keepAlive=FALSE

Disable persistent reuse without immediately closing the socket.

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_cmpAddr

#define HttpConnection_cmpAddr	(	o,
		addr2
	)	SoDispCon_cmpAddr((SoDispCon*)o, 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.

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_dispatcherHasCon

#define HttpConnection_dispatcherHasCon ( o ) SoDispCon_dispatcherHasCon((SoDispCon*)o)

Parameters

[in] o Initialized connection.

Returns: TRUE if registered with the dispatcher, FALSE otherwise.

◆ HttpConnection_getDispatcher

#define HttpConnection_getDispatcher ( o ) SoDispCon_getDispatcher((SoDispCon*)o)

Parameters

[in] o Initialized connection.

Returns: Borrowed associated dispatcher, possibly NULL.

◆ HttpConnection_getPeerName

#define HttpConnection_getPeerName	(	o,
		addr,
		port
	)	SoDispCon_getPeerName((SoDispCon*)o, addr,port)

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.

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_getServer

#define HttpConnection_getServer ( o ) (o)->server

Parameters

[in] o Initialized connection.

Returns: Borrowed associated server, possibly NULL.

◆ HttpConnection_getSockName

#define HttpConnection_getSockName	(	o,
		addr,
		port
	)	SoDispCon_getSockName((SoDispCon*)o, addr,port)

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.

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_getState

#define HttpConnection_getState ( o ) (o)->state

Parameters

[in] o Initialized connection.

Returns: Current HttpConnection_State value.

◆ HttpConnection_hasMoreData

#define HttpConnection_hasMoreData ( o ) (SoDispCon_hasMoreData((SoDispCon*)o) || (o)->pushBackData)

Parameters

[in] o Initialized connection.

Returns: TRUE if pushback bytes or transport readiness are recorded; not a byte count.

◆ HttpConnection_isSecure

#define HttpConnection_isSecure ( o ) SoDispCon_isSecure((SoDispCon*)o)

Test a successfully installed transport for TLS.

Parameters

[in] o Connected object with an installed transport.

Returns: TRUE if the transport reports secure, FALSE otherwise. Does not establish handshake completion, certificate trust or peer identity.

◆ HttpConnection_isValid

#define HttpConnection_isValid ( o ) SoDispCon_isValid((SoDispCon*)o)

Parameters

[in] o Initialized connection.

Returns: TRUE if a socket handle is installed; not a peer-liveness test.

◆ HttpConnection_keepAlive

#define HttpConnection_keepAlive ( o ) (o)->keepAlive

Parameters

[in] o Initialized connection.

Returns: TRUE if reuse is enabled, FALSE otherwise.

◆ HttpConnection_recEvActive

#define HttpConnection_recEvActive ( o ) SoDispCon_recEvActive((SoDispCon*)o)

Parameters

[in] o Initialized connection.

Returns: TRUE if receive events are enabled.

◆ HttpConnection_sendChunkData

#define HttpConnection_sendChunkData	(	o,
		data,
		len
	)	SoDispCon_sendChunkData((SoDispCon*)o,data, 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.

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_sendData

#define HttpConnection_sendData	(	o,
		data,
		len
	)	SoDispCon_sendData((SoDispCon*)o, data, 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.

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_sendDataNT

#define HttpConnection_sendDataNT	(	o,
		data,
		len
	)	SoDispCon_sendDataNT((SoDispCon*)o, data, len)

Send all bytes with the sendData contract, but omit body tracing.

Parameters

[in,out]	o	Connected object.
[in]	data	Borrowed source containing len bytes.
[in]	len	Nonnegative byte count.

Returns: Zero complete, -1 invalid socket, E_SOCKET_WRITE_FAILED short/error. No partial count is returned. May release/reacquire the dispatcher mutex.

◆ HttpConnection_sendEvActive

#define HttpConnection_sendEvActive ( o ) SoDispCon_sendEvActive((SoDispCon*)o)

Parameters

[in] o Initialized connection.

Returns: TRUE if send-ready events are enabled.

◆ HttpConnection_setBlocking

#define HttpConnection_setBlocking ( o ) SoDispCon_setBlocking((SoDispCon*)o)

Select blocking socket mode.

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

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_setDispSendEvent

#define HttpConnection_setDispSendEvent	(	o,
		dispSendEvFp
	)	SoDispCon_setDispSendEvent((SoDispCon*)o, dispSendEvFp)

Install the send-ready callback before enabling events.

Parameters

[in,out]	o	Initialized connection.
[in]	dispSendEvFp	Required callback while send events are active.

◆ HttpConnection_setKeepAlive

#define HttpConnection_setKeepAlive ( o ) (o)->keepAlive=TRUE

Enable persistent reuse after a completed HTTP request.

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_setNonblocking

#define HttpConnection_setNonblocking ( o ) SoDispCon_setNonblocking((SoDispCon*)o)

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.

Parameters

[in,out] o Initialized connection.

◆ HttpConnection_setTCPNoDelay

#define HttpConnection_setTCPNoDelay	(	o,
		enable
	)	SoDispCon_setTCPNoDelay((SoDispCon*)o, 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.
[in,out]	o	Initialized connection.

Typedef Documentation

◆ HttpConnection

typedef HttpConnection HttpConnection

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.

Enumeration Type Documentation

◆ HttpConnection_State

enum HttpConnection_State

Server connection lifecycle states.

Use setState for transitions that must release buffered bytes or terminate a socket.

Function Documentation

◆ HttpConnection_blockRead()

BA_API int HttpConnection_blockRead	(	HttpConnection *	con,
		void *	data,
		int	len
	)

Read buffered bytes or wait for socket data.

Parameters

[in,out]	con	Initialized connection configured for blocking reads.
[out]	data	Writable storage of at least len bytes, not NUL-terminated.
[in]	len	Positive capacity in bytes.

Returns: Positive byte count, zero if the transport supplies no bytes, or a negative transport/timeout error. Does not promise to fill the buffer. Pushback bytes are returned immediately; otherwise uses SoDispCon_blockRead. Do not run competing reads on the same connection.

◆ HttpConnection_constructor()

BA_API void HttpConnection_constructor	(	HttpConnection *	o,
		struct HttpServer *	server,
		struct SoDisp *	dispatcher,
		SoDispCon_DispRecEv	e
	)

Initialize connection storage without opening a socket.

Parameters

[out]	o	Caller-owned storage; initially Free and not keep-alive.
[in]	server	Borrowed server, or NULL for non-HTTP use.
[in]	dispatcher	Borrowed dispatcher, valid throughout registered use.
[in]	e	Receive-event callback; required before enabling receive events. Establish or move in a socket separately before registering events.

◆ HttpConnection_destructor()

BA_API void HttpConnection_destructor ( HttpConnection * o )

Release pushback storage, unregister events, and close the connection.

Parameters

[in,out] o Initialized object; its storage and borrowed server are not freed. Stop other users before destruction.

◆ HttpConnection_moveCon()

BA_API int HttpConnection_moveCon	(	HttpConnection *	o,
		HttpConnection *	newCon
	)

Move the socket, transport state and pending input to another object.

Parameters

[in,out]	o	Live source associated with the same server as newCon. Its socket and pushback ownership are removed and its state becomes Moved.
[in,out]	newCon	Initialized empty destination with the appropriate dispatcher/callback setup. It must not own a socket or pending input.

Returns: Zero. Register and activate the destination as required by its owner; the source object itself is not freed. This is not a copy operation.

◆ HttpConnection_pushBack()

BA_API int HttpConnection_pushBack	(	HttpConnection *	o,
		const void *	d,
		int	s
	)

Prepend copied bytes to the input returned by subsequent reads.

Parameters

[in,out]	o	Initialized connection.
[in]	d	Borrowed source containing s bytes.
[in]	s	Positive byte count; combined pending length must fit int.

Returns: Zero when pushback storage exists, -1 if an initial allocation fails.

Warning: When older pushback data exists, an allocation failure while prepending can return zero without adding the new bytes. Do not assume this return proves that an additional prepend succeeded.

◆ HttpConnection_readData()

BA_API int HttpConnection_readData	(	HttpConnection *	con,
		void *	data,
		int	len
	)

Read pending pushback bytes first, otherwise perform an event-oriented read.

Parameters

[in,out]	con	Initialized connection.
[out]	data	Writable storage of at least len bytes, not NUL-terminated.
[in]	len	Positive capacity in bytes.

Returns: Positive byte count, zero when no data is currently available, or a negative transport error. A return may be short even with more bytes pending. Readiness and mutex requirements follow SoDispCon_readData.

◆ HttpConnection_setState()

BA_API void HttpConnection_setState	(	HttpConnection *	o,
		HttpConnection_State	state
	)

Change lifecycle state, performing the associated cleanup.

Parameters

[in,out]	o	Initialized connection; serialize with its dispatcher.
[in]	state	A HttpConnection_State value. Free/Terminated release pushback storage and shut down the socket. HardClose performs an abortive close and stores Terminated. Other states are intended for server lifecycle handling; setting Running alone does not create a usable socket.

Classes

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ HttpConnection_addr2String

◆ HttpConnection_allocAsynchBuf

◆ HttpConnection_asyncReady

◆ HttpConnection_asyncSend

◆ HttpConnection_clearKeepAlive

◆ HttpConnection_cmpAddr

◆ HttpConnection_dispatcherHasCon

◆ HttpConnection_getDispatcher

◆ HttpConnection_getPeerName

◆ HttpConnection_getServer

◆ HttpConnection_getSockName

◆ HttpConnection_getState

◆ HttpConnection_hasMoreData

◆ HttpConnection_isSecure

◆ HttpConnection_isValid

◆ HttpConnection_keepAlive

◆ HttpConnection_recEvActive

◆ HttpConnection_sendChunkData

◆ HttpConnection_sendData

◆ HttpConnection_sendDataNT

◆ HttpConnection_sendEvActive

◆ HttpConnection_setBlocking

◆ HttpConnection_setDispSendEvent

◆ HttpConnection_setKeepAlive

◆ HttpConnection_setNonblocking

◆ HttpConnection_setTCPNoDelay

Typedef Documentation

◆ HttpConnection

Enumeration Type Documentation

◆ HttpConnection_State

Function Documentation

◆ HttpConnection_blockRead()

◆ HttpConnection_constructor()

◆ HttpConnection_destructor()

◆ HttpConnection_moveCon()

◆ HttpConnection_pushBack()

◆ HttpConnection_readData()

◆ HttpConnection_setState()