The HTTP server provides APIs to instantiate an HTTP server, and handle requests from HTTP clients. More...

Data Structures
struct	HTTPServer_Params
	HTTPServer instance create parameters. More...

struct	URLHandler_Setup
	Structure containing URL Handler components. More...

Macros
#define	HTTPServer_EACCEPTFAIL (-2)
	Internal accept() call failed. More...

#define	HTTPServer_ESOCKETFAIL (-3)
	Internal network socket creation failure. More...

#define	HTTPServer_EBINDFAIL (-4)
	Internal bind() call failed. More...

#define	HTTPServer_ELISTENFAIL (-5)
	Internal listen() call failed. More...

#define	HTTPServer_EMEMFAIL (-6)
	Internal memory allocation or object creation failure. More...

#define	HTTPServer_EMQFAIL (-7)
	Internal mq creation failure. More...

#define	HTTPServer_EMUTEXFAIL (-8)
	Internal mutex-related failure. More...

#define	URLHandler_GET 1

#define	URLHandler_POST 2

#define	URLHandler_PUT 3

#define	URLHandler_PATCH 4

#define	URLHandler_DELETE 5

#define	URLHandler_ENOTHANDLED 0

#define	URLHandler_EHANDLED 1

#define	URLHandler_EERRORHANDLED 2

#define	URLHandler_EHANDLEDSTOP 3

Typedefs
typedef struct HTTPServer_Params	HTTPServer_Params
	HTTPServer instance create parameters. More...

typedef struct HTTPServer_Object *	HTTPServer_Handle
	HTTPServer instance object handle. More...

typedef struct URLHandler_Object *	URLHandler_Handle
	A placeholder used to refer to a user-defined type. More...

typedef struct URLHandler_State *	URLHandler_Session

typedef URLHandler_Handle(*	URLHandler_CreateFxn) (void *params, URLHandler_Session session)
	Create a user-defined URLHandler_Object. More...

typedef int(*	URLHandler_ProcessFxn) (URLHandler_Handle u, int method, const char url, const char urlArgs, int contentLength, int s)
	Process an HTTP request. More...

typedef void(*	URLHandler_ScanFieldFxn) (URLHandler_Handle u, int method, const char url, const char field)
	Scan for specific request headers. More...

typedef void(*	URLHandler_DeleteFxn) (URLHandler_Handle *u)
	Delete a URLHandler. More...

typedef struct URLHandler_Setup	URLHandler_Setup
	Structure containing URL Handler components. More...

Functions
void	HTTPServer_init (void)
	Initialize the HTTPServer module. More...

void	HTTPServer_Params_init (HTTPServer_Params *params)
	Initialize the instance create params structure. More...

void	HTTPServer_enableSecurity (HTTPServer_Handle srv, SlNetSockSecAttrib_t *securityAttributes, bool beginSecurely)
	Attach security params to the created, but not yet initialized server. More...

HTTPServer_Handle	HTTPServer_create (const URLHandler_Setup urlh, int numURLh, HTTPServer_Params params)
	Create an HTTPServer instance. More...

void	HTTPServer_delete (HTTPServer_Handle *srv)
	Delete an HTTPServer instance. More...

void	HTTPServer_sendSimpleResponse (int s, int status, const char type, size_t len, const void buf)
	Send a simple, complete response to a client. More...

void	HTTPServer_sendResponse (int s, int status, const char headers[], int numHeaders, size_t len, const void buf)
	Send a complete response to a client. More...

void	HTTPServer_sendErrorResponse (int s, int status)
	Send an error response to a client. More...

void	HTTPServer_sendResponseChunked (int s, int status, const char *type)
	Begin the process of sending a chunked response to a client. More...

void	HTTPServer_sendChunk (int s, const void *buf, size_t len)
	Continue and complete the process of sending a chunked response to a client. More...

int	HTTPServer_serveSelect (HTTPServer_Handle srv, const struct sockaddr *addr, int len, int backlog)
	Begin the HTTP Server's main processing loop. More...

bool	HTTPServer_stop (HTTPServer_Handle srv, uint32_t timeout)
	Stop a currently running server. More...

bool	HTTPServer_isSessionSecure (URLHandler_Session sess)
	Obtain the session's security status. More...

Detailed Description

The HTTP server provides APIs to instantiate an HTTP server, and handle requests from HTTP clients.

Library Usage

To use the HTTPServer APIs, the application should include its header file as follows:

#include <ti/net/http/httpserver.h>

And, add the following HTTP library to the link line:

.../source/ti/net/http/{toolchain}/{isa}/httpserver_{profile}.a

Macro Definition Documentation

§ HTTPServer_EACCEPTFAIL

#define HTTPServer_EACCEPTFAIL (-2)

Internal accept() call failed.

§ HTTPServer_ESOCKETFAIL

#define HTTPServer_ESOCKETFAIL (-3)

Internal network socket creation failure.

§ HTTPServer_EBINDFAIL

#define HTTPServer_EBINDFAIL (-4)

Internal bind() call failed.

§ HTTPServer_ELISTENFAIL

#define HTTPServer_ELISTENFAIL (-5)

Internal listen() call failed.

§ HTTPServer_EMEMFAIL

#define HTTPServer_EMEMFAIL (-6)

Internal memory allocation or object creation failure.

§ HTTPServer_EMQFAIL

#define HTTPServer_EMQFAIL (-7)

Internal mq creation failure.

§ HTTPServer_EMUTEXFAIL

#define HTTPServer_EMUTEXFAIL (-8)

Internal mutex-related failure.

§ URLHandler_GET

#define URLHandler_GET 1

§ URLHandler_POST

#define URLHandler_POST 2

§ URLHandler_PUT

#define URLHandler_PUT 3

§ URLHandler_PATCH

#define URLHandler_PATCH 4

§ URLHandler_DELETE

#define URLHandler_DELETE 5

§ URLHandler_ENOTHANDLED

#define URLHandler_ENOTHANDLED 0

§ URLHandler_EHANDLED

#define URLHandler_EHANDLED 1

§ URLHandler_EERRORHANDLED

#define URLHandler_EERRORHANDLED 2

§ URLHandler_EHANDLEDSTOP

#define URLHandler_EHANDLEDSTOP 3

Typedef Documentation

§ HTTPServer_Params

typedef struct HTTPServer_Params HTTPServer_Params

HTTPServer instance create parameters.

§ HTTPServer_Handle

typedef struct HTTPServer_Object* HTTPServer_Handle

HTTPServer instance object handle.

§ URLHandler_Handle

typedef struct URLHandler_Object* URLHandler_Handle

A placeholder used to refer to a user-defined type.

This object handle is the type returned from the URLHandler_CreateFxn and passed to all other URLHandler_* functions.

§ URLHandler_Session

typedef struct URLHandler_State* URLHandler_Session

§ URLHandler_CreateFxn

typedef URLHandler_Handle(* URLHandler_CreateFxn) (void *params, URLHandler_Session session)

Create a user-defined URLHandler_Object.

This function (if used) should be used to instantiate a user-defined URLHandler_Handle object that contains whatever information is deemed necessary to pass to other URLHandler_* functions while the server is running. The handle of the user-defined type should be cast as a URLHandler_Handle before returning it from this function. The handle is later passed to other URLHandler_* functions in order to access session-specific data. The handle should be recast as the user-defined type before accessing it in other URLHandler_* functions.

Parameters

[in]	params	Optional parameters to specify characteristics
[in]	session	Handler to current client session

Remarks: The session argument is not yet used, but may be in the future

Return values

URLHandler instance handle

See also: URLHandler_ProcessFxn(); URLHandler_ScanFieldFxn(); URLHandler_DeleteFxn()

§ URLHandler_ProcessFxn

typedef int(* URLHandler_ProcessFxn) (URLHandler_Handle u, int method, const char *url, const char *urlArgs, int contentLength, int s)

Process an HTTP request.

This function is called after an HTTP request is received and the request headers have been processed, possibly by calling the URLHandler_ScanFieldFxn(). For every request received by the server this method is called once per URLHandler until a URLHandler handles the request.

The body of a request can be retrieved by calling recv() with the supplied socket s argument. The length of the request body is available in the contentLength parameter. Given the HTTP method, URL, and request body, this function can determine how to proceed. i.e. if a GET request is received, this is where the resource identified by the URL should be fetched; If a POST request is made, this is where the data passed within urlArgs or the request body can be parsed and acted upon (i.e. stored within the server); etc.

After processing a request, this function should construct a response. This involves selecting a status code (see the HTTP_STATUS_CODE enum in ti/net/http/http.h), creating any desired headers, and creating the response body.

Once the components of the response have been created, they can be sent to the client via the recommended HTTPServer_send* methods. Note that users can directly send a response using send(), however the user is then responsible for creating well-formed headers and responses.

The u argument contains the URLHandler_Handle that was returned from URLHandler_CreateFxn(), or NULL if the handler didn't provide one.

The return value of this function determines how the server proceeds:

If URLHandler_ENOTHANDLED is returned and there are more URLHandlers whose process methods have not been called, the server will proceed to call said process methods, one by one, until the request is handled or until there are no more URLHandler->process methods available.
If URLHandler_ENOTHANDLED is returned and no URLHandlers are able to handle the request, a 404 response will be sent to the client.
If URLHandler_EHANDLEDSTOP is returned, the server will remove all open sessions, close its listening socket, and shut down.
If URLHandler_EERRORHANDLED is returned, the current session (client connection) is closed and the server continues.

Parameters

[in]	u	Handle to the URL Handler containing relevant data
[in]	method	HTTP method of the request being parsed
[in]	url	URI of the current request
[in]	urlArgs	The query string, if present
[in]	contentLength	Content-Length (body length) header value, if present
[in]	s	TCP/IP socket connected to a client

Return values

int	Return status

See also: HTTPServer_sendSimpleResponse(); URLHandler_ScanFieldFxn()

§ URLHandler_ScanFieldFxn

typedef void(* URLHandler_ScanFieldFxn) (URLHandler_Handle u, int method, const char *url, const char *field)

Scan for specific request headers.

This function can be used to process headers of incoming requests. Every URL Handler with this function defined will have each header passed into this function, one by one. It is called when a request is received by the server, before the request is sent to the URLHandler_ProcessFxn. The Content-Length header is parsed automatically by the server (however, it will still be passed into this function, should the developer want to examine it).

Parameters

[in]	u	Handle to the URL Handler containing relevant data
[in]	method	HTTP method of the request being parsed
[in]	url	URI of the current request
[in]	field	Specific request line containing the header

See also: URLHandler_ProcessFxn()

§ URLHandler_DeleteFxn

typedef void(* URLHandler_DeleteFxn) (URLHandler_Handle *u)

Delete a URLHandler.

This function is called when the session associated with the handler parameter is closed. Any memory allocated for the URLHandler (i.e. in the _create function) should be cleaned up here.

Parameters

[in] u The Handler for deletion

See also: URLHandler_CreateFxn()

§ URLHandler_Setup

typedef struct URLHandler_Setup URLHandler_Setup

Structure containing URL Handler components.

This structure contains parameters needed for setup of a user- defined URLHandler object and pointers to associated user-defined URLHandler_* functions. The created HTTP Server maintains a table of this data structure for each unique URL Handler.

Function Documentation

§ HTTPServer_init()

void HTTPServer_init ( void )

Initialize the HTTPServer module.

Remarks: This function is used to initialize the HTTPServer module. Call this function before calling any other HTTPServer functions.; This function must be serialized by the caller.

§ HTTPServer_Params_init()

void HTTPServer_Params_init ( HTTPServer_Params * params )

Initialize the instance create params structure.

Parameters

[in] params params structure to initialize

§ HTTPServer_enableSecurity()

void HTTPServer_enableSecurity	(	HTTPServer_Handle	srv,
		SlNetSockSecAttrib_t *	securityAttributes,
		bool	beginSecurely
	)

Attach security params to the created, but not yet initialized server.

Parameters

[in]	srv	Pointer to the server that will take on the attributes.
[in]	securityAttributes	A list of security objects as detailed in slnetsock.h.
	beginSecurely	Whether to activate security right away or not. This is typically set to true.

Remarks: The securityAttributes passed to this function must remain in memory for the duration of the program. They cannot be safely freed before the server has been deleted.; Call this function before HTTPServer_serveSelect. beginSecurely is typically set to true as there is currently no way to activate security after this function has been called and returns.

§ HTTPServer_create()

HTTPServer_Handle HTTPServer_create	(	const URLHandler_Setup *	urlh,
		int	numURLh,
		HTTPServer_Params *	params
	)

Create an HTTPServer instance.

Parameters

[in]	urlh	Array of URLHandler setup descriptors
	numURLh	Number of elements in the `urlh` array
[in]	params	Optional parameters to specify characteristics - use NULL for defaults

Precondition: As with all HTTPServer API's, HTTPServer_init() must have previously been called.

Return values

HTTPServer	instance handle
NULL	if unable to create the instance

See also: HTTPServer_Params_init(); HTTPServer_delete()

§ HTTPServer_delete()

void HTTPServer_delete ( HTTPServer_Handle * srv )

Delete an HTTPServer instance.

Parameters

[in,out] srv Pointer containing a handle to the instance to delete.

Precondition: As with all HTTPServer API's, HTTPServer_init() must have previously been called.

Remarks: Upon successful return, the handle pointed to by handlePtr will be invalid.

§ HTTPServer_sendSimpleResponse()

void HTTPServer_sendSimpleResponse	(	int	s,
		int	status,
		const char *	type,
		size_t	len,
		const void *	buf
	)

Send a simple, complete response to a client.

This function is typically called by a URL Handler, in response to handling a URL request.

Parameters

[in]	s	TCP/IP socket connected to a client
[in]	status	Status Code associated with the response
[in]	type	Content-type of the response
[in]	len	Number of bytes in the response buffer `buf`
[in]	buf	Response buffer

Precondition: As with all HTTPServer API's, HTTPServer_init() must have previously been called.

Remarks: This function sends 2 response headers, "Content-Length" and "Content-Type". To send custom response headers, use HTTPServer_sendResponse().

See also: HTTPServer_sendErrorResponse(); HTTPServer_sendResponseChunked()

§ HTTPServer_sendResponse()

void HTTPServer_sendResponse	(	int	s,
		int	status,
		const char *	headers[],
		int	numHeaders,
		size_t	len,
		const void *	buf
	)

Send a complete response to a client.

This function is typically called by a URL Handler, in response to handling a URL request.

Parameters

[in]	s	TCP/IP socket connected to a client
[in]	status	Status Code associated with the response
[in]	headers	Optional response headers
[in]	numHeaders	number of elements in `headers`
[in]	len	Number of bytes in the response buffer `buf`
[in]	buf	Response buffer

Precondition: As with all HTTPServer API's, HTTPServer_init() must have previously been called.

Remarks: This function sends the user supplied headers as response headers, followed by a generated "Content-Length" header (with a value of len). If you only need to send "Content-Length" and "Content-Type" headers, consider using HTTPServer_sendSimpleResponse().

See also: HTTPServer_sendErrorResponse(); HTTPServer_sendResponseChunked()

§ HTTPServer_sendErrorResponse()

void HTTPServer_sendErrorResponse	(	int	s,
		int	status
	)

Send an error response to a client.

This function is typically called by a URL Handler, in response to handling a URL request.

Parameters

[in]	s	TCP/IP socket connected to a client
[in]	status	Status Code associated with the response

Precondition: As with all HTTPServer API's, HTTPServer_init() must have previously been called.

See also: HTTPServer_sendResponse()

§ HTTPServer_sendResponseChunked()

void HTTPServer_sendResponseChunked	(	int	s,
		int	status,
		const char *	type
	)

Begin the process of sending a chunked response to a client.

This function is typically called by a URL Handler, in response to handling a URL request.

Parameters

[in]	s	TCP/IP socket connected to a client
[in]	status	Status Code associated with the response
[in]	type	Content-type of the response

Precondition: As with all HTTPServer API's, HTTPServer_init() must have previously been called.

Remarks: HTTPServer_sendResponseChunked() starts the process of sending a chunked reply. It sends a line with the status field (e.g. "Status: 200 OK"), followed by the "Transfer-Encoding: chunked\r\n\r\n" field. The rest of the response can then be sent using HTTPServer_sendChunk().

See also: HTTPServer_sendChunk()

§ HTTPServer_sendChunk()

void HTTPServer_sendChunk	(	int	s,
		const void *	buf,
		size_t	len
	)

Continue and complete the process of sending a chunked response to a client.

This function is typically called by a URL Handler, in response to handling a URL request.

Parameters

[in]	s	TCP/IP socket connected to a client
[in]	buf	Response buffer
[in]	len	Number of bytes in the response buffer `buf`

Precondition: As with all HTTPServer API's, HTTPServer_init() must have previously been called.

Remarks: HTTPServer_sendChunked() sends the requisite ASCII-encoded hex size of the data being sent (len), followed by the data in buf.; To indicate the end of a chunked reply, call HTTPServer_sendChunk() with len set to zero.

See also: HTTPServer_sendChunkedResponse()

§ HTTPServer_serveSelect()

int HTTPServer_serveSelect	(	HTTPServer_Handle	srv,
		const struct sockaddr *	addr,
		int	len,
		int	backlog
	)

Begin the HTTP Server's main processing loop.

Parameters

[in]	srv	Handle to the server
[in]	addr	Address information for server startup
[in]	len	Length of the address information structure
[in]	backlog	Maximum number of pending connections to server

Return values

0	Server received stop command
-1	Server shutdown unexpectedly
<-1	See HTTPServer_E error codes

§ HTTPServer_stop()

bool HTTPServer_stop	(	HTTPServer_Handle	srv,
		uint32_t	timeout
	)

Stop a currently running server.

In order to stop the server using this function, this must be called from an outside thread.

Parameters

[in]	srv	Handle to the server being stopped
	timeout	The time in which the server is expected to halt

§ HTTPServer_isSessionSecure()

bool HTTPServer_isSessionSecure ( URLHandler_Session sess )

Obtain the session's security status.

Parameters

sess	A handle containing session state.

See also: HTTPServer_enableSecurity()

Data Structures

Macros

Typedefs

Functions

Detailed Description

Library Usage

Macro Definition Documentation

§ HTTPServer_EACCEPTFAIL

§ HTTPServer_ESOCKETFAIL

§ HTTPServer_EBINDFAIL

§ HTTPServer_ELISTENFAIL

§ HTTPServer_EMEMFAIL

§ HTTPServer_EMQFAIL

§ HTTPServer_EMUTEXFAIL

§ URLHandler_GET

§ URLHandler_POST

§ URLHandler_PUT

§ URLHandler_PATCH

§ URLHandler_DELETE

§ URLHandler_ENOTHANDLED

§ URLHandler_EHANDLED

§ URLHandler_EERRORHANDLED

§ URLHandler_EHANDLEDSTOP

Typedef Documentation

§ HTTPServer_Params

§ HTTPServer_Handle

§ URLHandler_Handle

§ URLHandler_Session

§ URLHandler_CreateFxn

§ URLHandler_ProcessFxn

§ URLHandler_ScanFieldFxn

§ URLHandler_DeleteFxn

§ URLHandler_Setup

Function Documentation

§ HTTPServer_init()

§ HTTPServer_Params_init()

§ HTTPServer_enableSecurity()

§ HTTPServer_create()

§ HTTPServer_delete()

§ HTTPServer_sendSimpleResponse()

§ HTTPServer_sendResponse()

§ HTTPServer_sendErrorResponse()

§ HTTPServer_sendResponseChunked()

§ HTTPServer_sendChunk()

§ HTTPServer_serveSelect()

§ HTTPServer_stop()

§ HTTPServer_isSessionSecure()