Network Services API  2.75.00.17
Data Structures | Macros | Typedefs | Functions
HTTP Server

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:

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

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]paramsOptional parameters to specify characteristics
[in]sessionHandler to current client session
Remarks
The session argument is not yet used, but may be in the future
Return values
URLHandlerinstance 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]uHandle to the URL Handler containing relevant data
[in]methodHTTP method of the request being parsed
[in]urlURI of the current request
[in]urlArgsThe query string, if present
[in]contentLengthContent-Length (body length) header value, if present
[in]sTCP/IP socket connected to a client
Return values
intReturn 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]uHandle to the URL Handler containing relevant data
[in]methodHTTP method of the request being parsed
[in]urlURI of the current request
[in]fieldSpecific 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]uThe Handler for deletion
See also
URLHandler_CreateFxn()

§ 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]paramsparams 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]srvPointer to the server that will take on the attributes.
[in]securityAttributesA list of security objects as detailed in slnetsock.h.
beginSecurelyWhether 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]urlhArray of URLHandler setup descriptors
numURLhNumber of elements in the urlh array
[in]paramsOptional parameters to specify characteristics - use NULL for defaults
Precondition
As with all HTTPServer API's, HTTPServer_init() must have previously been called.
Return values
HTTPServerinstance handle
NULLif 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]srvPointer 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]sTCP/IP socket connected to a client
[in]statusStatus Code associated with the response
[in]typeContent-type of the response
[in]lenNumber of bytes in the response buffer buf
[in]bufResponse 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]sTCP/IP socket connected to a client
[in]statusStatus Code associated with the response
[in]headersOptional response headers
[in]numHeadersnumber of elements in headers
[in]lenNumber of bytes in the response buffer buf
[in]bufResponse 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]sTCP/IP socket connected to a client
[in]statusStatus 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]sTCP/IP socket connected to a client
[in]statusStatus Code associated with the response
[in]typeContent-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]sTCP/IP socket connected to a client
[in]bufResponse buffer
[in]lenNumber 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]srvHandle to the server
[in]addrAddress information for server startup
[in]lenLength of the address information structure
[in]backlogMaximum number of pending connections to server
Return values
0Server received stop command
-1Server shutdown unexpectedly
<-1See 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]srvHandle to the server being stopped
timeoutThe time in which the server is expected to halt

§ HTTPServer_isSessionSecure()

bool HTTPServer_isSessionSecure ( URLHandler_Session  sess)

Obtain the session's security status.

Parameters
sessA handle containing session state.
See also
HTTPServer_enableSecurity()
© Copyright 1995-2020, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale