HttpServCon.h File Reference

#include <HttpConnection.h>
#include <SoDisp.h>

Include dependency graph for HttpServCon.h:

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

Go to the source code of this file.

Classes
struct	HttpServCon
	Create a server listen object. More...

Macros
#define	HttpServCon_isValid(o)    SoDispCon_isValid((SoDispCon*)(o))

Typedefs
typedef void(*	HttpServCon_AcceptNewCon) (struct HttpServCon *scon, HttpConnection *newcon)
	Handle a newly accepted connection while the dispatcher mutex is held. More...
typedef struct HttpServCon	HttpServCon
	Create a server listen object. More...

Functions
BA_API void	HttpServCon_constructor (HttpServCon *o, struct HttpServer *server, struct SoDisp *dispatcher, U16 port, BaBool setIP6, const void *interfaceName, HttpServCon_AcceptNewCon userDefinedAccept)
	Create a Server Connection. More...
BA_API int	HttpServCon_setPort (HttpServCon *o, U16 portNumber, BaBool setIp6, const void *interfaceName)
	Open a replacement listening endpoint before closing the old one. More...
BA_API void	HttpServCon_destructor (HttpServCon *o)
	Close and unregister a listener; does not close its accepted connections. More...

Macro Definition Documentation

HttpServCon_isValid

#define HttpServCon_isValid

(

o

)

SoDispCon_isValid((SoDispCon*)(o))

Parameters

[in]

o

Initialized listener.

Returns

TRUE if its socket is valid, FALSE otherwise.

Typedef Documentation

HttpServCon

typedef struct HttpServCon HttpServCon

Create a server listen object.

The object binds itself to the SoDisp object and makes the web-server listen for new connections on the port specified. The default port is 80. You can create several of these objects and bind to the dispatcher if you want the web-server to listen to more than one port.

HttpServCon_AcceptNewCon

typedef void(* HttpServCon_AcceptNewCon) (struct HttpServCon *scon, HttpConnection *newcon)

Handle a newly accepted connection while the dispatcher mutex is held.

Parameters

[in]	scon	Borrowed listener that accepted the socket.
[in,out]	newcon	Temporary connection, valid only during this callback. Move it with HttpConnection_moveCon into an initialized application-owned connection before returning to accept it. Otherwise its socket is closed. Do not memcpy the connection or retain the temporary pointer. A TLS listener can invoke this callback before the TLS handshake has completed.

Function Documentation

HttpServCon_constructor()

BA_API void HttpServCon_constructor	(	HttpServCon *	o,
		struct HttpServer *	server,
		struct SoDisp *	dispatcher,
		U16	port,
		BaBool	setIP6,
		const void *	interfaceName,
		HttpServCon_AcceptNewCon	userDefinedAccept
	)

Create a Server Connection.

Parameters

server	Borrowed server, valid throughout listener use. Required for the default HTTP handler and for setPort.
dispatcher	Required borrowed dispatcher, valid throughout use.
port	TCP port in host byte order, default 80. Zero requests an OS-assigned port if supported by the socket port.
setIP6	TRUE selects IPv6, FALSE IPv4 (default). This parameter is ignored unless the underlying TCP/IP stack is a dual IP V4 and IP V6 stack.
interfaceName	Borrowed platform binding address/interface, used during construction; normally a NUL-terminated textual address. NULL binds the wildcard address. Accepted representation is port-specific.
userDefinedAccept	The default (argument is NULL) is to accept connections for the web-server. A custom callback is required in NO_BA_SERVER builds; omitting it calls baFatalE.

A ServerConnection object is normally used for accepting new connections for the web-server. It is possible to redirect new connections to the "userDefinedAccept" callback function. This makes it possible to use the socket dispatcher logic in the web-server for implementing other services such as a telnet server.

The "user defined accept" callback function is called when a new connection is established. The HttpConnection object passed in as the argument to the callback function is a temporary object that will be destroyed as soon as the callback function returns. You must, therefore, move the connection into an initialized application object.

Example C code:

typedef struct { HttpConnection con; } MyHttpCon;
 
static void MyHttpCon_dispatchData(SoDispCon* socket)
{
   MyHttpCon* o = (MyHttpCon*)socket;
   char buf[512];
   int len = HttpConnection_readData(&o->con, buf, sizeof(buf));
   if(len < 0)
   {
      HttpConnection_destructor(&o->con); // Unregister and close.
      baFree(o);
      return;
   }
   if(len > 0)
   {
      // Consume exactly len bytes here; buf is not NUL-terminated.
   }
}
 
static void MyHttpCon_myAccept(HttpServCon* listener,
                               HttpConnection* temporary)
{
   MyHttpCon* o = (MyHttpCon*)baMalloc(sizeof(MyHttpCon));
   SoDisp* disp = HttpConnection_getDispatcher(temporary);
   (void)listener;
   if(!o) return; // The listener closes the unclaimed socket.
   HttpConnection_constructor(&o->con,
      HttpConnection_getServer(temporary), disp,
      MyHttpCon_dispatchData);
   HttpConnection_moveCon(temporary, &o->con);
   SoDisp_addConnection(disp, (SoDispCon*)&o->con);
   SoDisp_activateRec(disp, (SoDispCon*)&o->con);
}

Parameters

[in,out]

o

Caller-owned listener.

HttpServCon_destructor()

BA_API void HttpServCon_destructor

(

HttpServCon *

o

)

Close and unregister a listener; does not close its accepted connections.

Parameters

[in,out]

o

Initialized listener; its storage is not freed.

HttpServCon_setPort()

BA_API int HttpServCon_setPort	(	HttpServCon *	o,
		U16	portNumber,
		BaBool	setIp6,
		const void *	interfaceName
	)

Open a replacement listening endpoint before closing the old one.

Parameters

[in]	portNumber	New TCP port, in host byte order.
[in]	setIp6	True selects IPv6, false IPv4 (default).
[in]	interfaceName	Platform binding address/interface, or NULL for wildcard; borrowed for this call only.

Returns

Zero on success, -1 if creating/binding/listening fails. The old listener remains on failure. Requires a non-NULL server and uses that server's dispatcher. Existing accepted connections are unaffected. Perform listener changes while holding the dispatcher mutex.

Parameters

[in,out]

o

Caller-owned listener.