NetBurner 3.3.4
PDF Version
HTTP and HTML Functions

Classes

struct  HTTP_Request
 HTTP Request Structure. More...
 
class  HtmlPageHandler
 Base class for all GET handlers. To handle GET requests for a specific URL in your application, build a GET handler object for that specifif URL. A NULL name will be a catch all for all GET requests. More...
 
class  CallBackFunctionPageHandler
 Implements the HtmlPageHandler class as a function pointer callback for GET requests. More...
 
class  HtmlPostVariableListCallback
 Implements the HtmlPostVariableListHandler class as a function pointer callback for HTTP POST submissions. More...
 

Enumerations

enum  HTTP_RequestTypes { tUnknown , tGet , tPost , tHead }
 HTTP request types for HTTP page handler callback functions. More...
 
enum  HTTP_ACCESS
 HTTP page access return values.
 

Functions

int SendEmailResponse (int sock, const char *name, const char *attachment)
 Send an email with HTML formatting. More...
 
int SendFullResponse (char const *name, int fd)
 Send a file with the proper HTTP header, file specified by file name. More...
 
int SendFullResponse (HTML_FILE_RECORD *fr, int fd, const char *pUrl)
 Send a file with the proper HTTP header, file specified by HTML_FILE_RECORD. More...
 
int SendHeaderResponse (char const *name, int fd)
 Send a HTTP header response for the specified file type. More...
 
int SendHeaderResponse (HTML_FILE_RECORD *fr, int fd)
 Send a HTTP header response for the specified HTML_FILE_RECORD type. More...
 
int32_t SendFileFragment (char const *name, int32_t fd, PCSTR url=NULL)
 Send a file fragment without a header. More...
 
HTML_FILE_RECORD * GetRecordFromName (char const *name)
 Returns a pointer to a HTML_FILE_RECORD for the specified file name. More...
 
CONFIG_RENDER_OBJ ConfigRenderFunc (int mode, const char *pobj, int len=20, const char *extra=0)
 Render a configuration object as HTML for the specified configuration object. More...
 
CONFIG_RENDER_OBJ ConfigRenderFunc (int mode, config_leaf &cl, int len=20, const char *extra=0)
 Render a configuration object as HTML for the specified configuration leaf object. More...
 
void WriteHtmlVariable (int fd, CONFIG_RENDER_OBJ co)
 Send a CONFIG_RENDER_OBJ to the client. More...
 
HTTP_ACCESS CheckHttpAccess (int sock, int access_level, HTTP_Request &Req)
 All HTTP requests go though this function. More...
 
void StartHttp (uint16_t port, bool RunConfigMirror)
 Start the HTTP web server. Further documentation in the Initialization section Initialization - System Initialization Functions. More...
 
void StopHttp ()
 Stop the HTTP web server. More...
 
void SendHTMLHeader (int sock)
 Send a HTML response header. More...
 
void SendHTMLHeaderWCookie (int sock, char *cookie)
 Send a HTML response header and cookie. More...
 
void SendTextHeader (int sock)
 Send a HTML plain text header. More...
 
void SendGifHeader (int sock)
 Send a HTML GIF header. More...
 
void EmptyResponse (int sock)
 Send an empty response back. More...
 
void RedirectResponse (int sock, PCSTR new_page)
 Redirect a HTTP request to a different page. More...
 
void NotFoundResponse (int sock, PCSTR new_page)
 Send a page not found response. More...
 
void ForbiddenResponse (int sock, PCSTR new_page)
 Send a page is forbidden response. More...
 
void NotAvailableResponse (int sock, PCSTR new_page)
 Send a response indicating that the requested resource is not available at this time. More...
 
void BadRequestResponse (int sock, PCSTR url, PCSTR data)
 Send a response indicating that the client request itself is faulty in some manner. More...
 
int writeallsafestring (int fd, PCSTR str)
 Send a string and escape all special characters. More...
 
int writesafestring (int fd, PCSTR str, size_t strLength)
 Send a string with a specified length and escape all special characters. More...
 
int httpstricmp (PCSTR str1, PCSTR strIsUpper2)
 Special string compare. Returns 1 if the strings match until one string ends with a null (0). More...
 
void StartHttps (uint16_t ssl_port, uint16_t http_port)
 Start the HTTPS secure web server. More...
 

Detailed Description

API to process and delivery files from the web server to clients. In particular, processing of files in a project's html folder.

For the majority of applications these functions will not be necessary; the web server system will automatically handle both static and dynamic content. This API is available if more advances processing is required, such as sending custom response headers or very large amounts of data.

In addition to the functions to start a web server, StartHttp(), this module provides functions used to create a custom web interface. Please refer to the Programmers Guide for additional details on web interface programming and dynamic content.

See also
StartHttps()

Enumeration Type Documentation

◆ HTTP_RequestTypes

HTTP request types for HTTP page handler callback functions.

Enumerator
tUnknown 

The type of request is not yet known.

tGet 

GET request.

tPost 

POST request.

tHead 

Header request, does not include content.

Function Documentation

◆ BadRequestResponse()

void BadRequestResponse ( int  sock,
PCSTR  url,
PCSTR  data 
)

Send a response indicating that the client request itself is faulty in some manner.

Parameters
sockSocket to send response
urlThe URL of the page to display
dataAn explanation or segment of data to display indicating the fault
Returns
Nothing
See also
RedirectResponse(), NotFoundResponse(), ForbiddenResponse()
NotAvailableResponse()

◆ CheckHttpAccess()

HTTP_ACCESS CheckHttpAccess ( int  sock,
int  access_level,
HTTP_Request Req 
)

All HTTP requests go though this function.

By default the library provides a weak reference implimentaion that approves all transactions. To provide your own just add an implmentaion of this function to your code.

Parameters
sockThe socket the request came in on.
access_levelThe user defined access level for this request. See HtmlPageHandler
ReqThe HTTP request where one can extract the URL , access type, password, etc
Returns
The desired response.

◆ ConfigRenderFunc() [1/2]

CONFIG_RENDER_OBJ ConfigRenderFunc ( int  mode,
config_leaf &  cl,
int  len = 20,
const char *  extra = 0 
)

Render a configuration object as HTML for the specified configuration leaf object.

Parameters
modeCONFIG_RENDER_OBJ eMode value
clReference to the config_leaf object to render
lenOptional length parameter for text input elements
extraPointer to any additional information to be added to the HTML input element. Will be added to the end of the <input> tag.
Returns
A CONFIG_RENDER_OBJ that can be sent to the client using WriteHtmlVariable()

◆ ConfigRenderFunc() [2/2]

CONFIG_RENDER_OBJ ConfigRenderFunc ( int  mode,
const char *  pobj,
int  len = 20,
const char *  extra = 0 
)

Render a configuration object as HTML for the specified configuration object.

Parameters
modeCONFIG_RENDER_OBJ eMode value
pobjPointer to a configuration object. Can be specified as the JSON configuration path. For example, "Config/Sys/NetIf/Ethernet0/StaticAddr".
lenOptional length parameter for text input elements
extraPointer to any additional information to be added to the HTML input element. Will be added to the end of the <input> tag.
Returns
A CONFIG_RENDER_OBJ that can be sent to the client using WriteHtmlVariable()

◆ EmptyResponse()

void EmptyResponse ( int  sock)

Send an empty response back.

Parameters
sockSocket to send response
Returns
Nothing
See also
ForbiddenResponse(), ForbiddenResponse(), SendHTMLHeaderWCookie()
NotAvailableResponse(), BadRequestResponse(), RedirectResponse()

◆ ForbiddenResponse()

void ForbiddenResponse ( int  sock,
PCSTR  new_page 
)

Send a page is forbidden response.

Parameters
sockSocket to send response
new_pageThe URL of the page to display
Returns
Nothing
See also
RedirectResponse(), NotFoundResponse()
NotAvailableResponse(), BadRequestResponse()

◆ GetRecordFromName()

HTML_FILE_RECORD* GetRecordFromName ( char const *  name)

Returns a pointer to a HTML_FILE_RECORD for the specified file name.

Parameters
nameName of file in htmldata.cpp to search for
Return values
Apointer to a HTML_FILE_RECORD if found
NULLif file name not found

◆ httpstricmp()

int httpstricmp ( PCSTR  str1,
PCSTR  strIsUpper2 
)

Special string compare. Returns 1 if the strings match until one string ends with a null (0).

strIsUpper2 must be specified in upper case

Used to match URL with stored file prefixes.

Parameters
str1The string to search
strIsUpper2The string to search for, must be specified in upper case
Return values
0if the prefixes do not match
1if the prefixes match

Example: httpstricmp( str1, "LED.HTML");

str1 Return Value
LED 1
led.HTML 1
led.html 1
LED.HTM? 0

◆ NotAvailableResponse()

void NotAvailableResponse ( int  sock,
PCSTR  new_page 
)

Send a response indicating that the requested resource is not available at this time.

Parameters
sockSocket to send response
new_pageThe URL of the page to display
Returns
Nothing
See also
RedirectResponse(), NotFoundResponse(), ForbiddenResponse()
BadRequestResponse()

◆ NotFoundResponse()

void NotFoundResponse ( int  sock,
PCSTR  new_page 
)

Send a page not found response.

Parameters
sockSocket to send response
new_pageThe URL of the page to display
Returns
Nothing
See also
ForbiddenResponse(), RedirectResponse()
NotAvailableResponse(), BadRequestResponse()

◆ RedirectResponse()

void RedirectResponse ( int  sock,
PCSTR  new_page 
)

Redirect a HTTP request to a different page.

Parameters
sockSocket to send response
new_pageThe URL of the new page
Returns
Nothing
See also
ForbiddenResponse(), ForbiddenResponse(), SendHTMLHeaderWCookie()
NotAvailableResponse(), BadRequestResponse(), EmptyResponse()

◆ SendEmailResponse()

int SendEmailResponse ( int  sock,
const char *  name,
const char *  attachment 
)

Send an email with HTML formatting.

Parameters
sockNetwork socket in which to send the data
nameName of file from project's html folder, this is the email body
attachment
Return values
1Success, the file specified the name parameter was found
0File does not exist

◆ SendFileFragment()

int32_t SendFileFragment ( char const *  name,
int32_t  fd,
PCSTR  url = NULL 
)

Send a file fragment without a header.

Search through the files stored in the system by comphtml in the project's html folder for the specified file name. If found, the file content is sent as a file fragment. A SendHeaderRespose function must be sent prior to sending file fragments.

This function is useful when building HTML responses with large amounts of data. If the file has embedded dynamic HTML function tags and/or variable tags, such a CPPCALL and VARIABLE, they will be processed as the content is delivered.

Parameters
nameName of the file
fdFile descriptor used to send the file fragment
urlOptional URL string in fragment header
Return values
1if the file was found
0otherwise

◆ SendFullResponse() [1/2]

int SendFullResponse ( char const *  name,
int  fd 
)

Send a file with the proper HTTP header, file specified by file name.

This function searches through the files stored in the system by comphtml in the project's html folder for the specified file name. If found, it sends the proper HTTP header and file to the client. If the file has embedded dynamic HTML function tags and/or variable tags, such a CPPCALL and VARIABLE, they will be processed as the content is delivered.

Parameters
nameName of the file
fdFile descriptor used to send the file
Return values
1Succes, file was found
0File does not exist
See also
SendFullResponse(HTML_FILE_RECORD *fr, int fd, const char *pUrl)

◆ SendFullResponse() [2/2]

int SendFullResponse ( HTML_FILE_RECORD *  fr,
int  fd,
const char *  pUrl 
)

Send a file with the proper HTTP header, file specified by HTML_FILE_RECORD.

While the SendFullResponse(char const *name, int fd) function will resolve the file name, this lower level function requires knowledge of the file pointer to the HTML_FILE_RECORD in htmldata.cpp.

Parameters
frPointer to the HTML_FILE_RECORD in htmldata.cpp
fdFile descriptor used to send the file
pUrlPointer to a URL string used by response functions such a CPPCALL and VARIABLE callbacks. In default web server processing the URL is automatically set to what the client requested. When processing web requests manually you must specify the URL string. If you are not using dynamic content that relies on the URL, this can be set to NULL.
Return values
1if the file was found
0otherwise
See also
SendFullResponse(char const *name, int fd)

◆ SendGifHeader()

void SendGifHeader ( int  sock)

Send a HTML GIF header.

Sends a GIF response header. Can be useful when dynamically creating your own GIF images.

Parameters
sockSocket to send response
Returns
Nothing
See also
SendHTMLHeader(), SendTextHeader(), SendHTMLHeaderWCookie()

◆ SendHeaderResponse() [1/2]

int SendHeaderResponse ( char const *  name,
int  fd 
)

Send a HTTP header response for the specified file type.

This function searches through the files stored in the system by comphtml in the project's html folder for the specified file name. If found, it sends the proper HTTP header only to the client. Unlike a full response, only the header is sent.

Parameters
nameName of the file
fdFile descriptor used to send the file
Return values
1Succes, file was found
0File does not exist
See also
SendHeaderResponse(HTML_FILE_RECORD *fr, int fd)

◆ SendHeaderResponse() [2/2]

int SendHeaderResponse ( HTML_FILE_RECORD *  fr,
int  fd 
)

Send a HTTP header response for the specified HTML_FILE_RECORD type.

While the SendFullResponse(HTML_FILE_RECORD *fr, int fd, const char *pUrl); function will resolve the file name, this lower level function requires knowledge of the file pointer to the HTML_FILE_RECORD array in htmldata.cpp.

Parameters
frPointer to the HTML_FILE_RECORD in htmldata.cpp
fdFile descriptor used to send the file
Return values
1Succes, file was found
0File does not exist
See also
SendHeaderResponse(char const *name, int fd)

◆ SendHTMLHeader()

void SendHTMLHeader ( int  sock)

Send a HTML response header.

Used to build your own HTML response

Parameters
sockSocket to send response
Returns
Nothing
See also
SendHTMLHeaderWCookie(), SendTextHeader(), SendGifHeader()

◆ SendHTMLHeaderWCookie()

void SendHTMLHeaderWCookie ( int  sock,
char *  cookie 
)

Send a HTML response header and cookie.

Sends a header as well as a cookie to be stored by the client browser.

Parameters
sockSocket to send response
cookiePointer to the cookie
Returns
Nothing
See also
SendHTMLHeader(), SendGifHeader(), SendTextHeader()

◆ SendTextHeader()

void SendTextHeader ( int  sock)

Send a HTML plain text header.

Use as the first part of building your own plain text response.

Parameters
sockSocket to send response
Returns
Nothing
See also
SendHTMLHeader(), SendGifHeader(), SendHTMLHeaderWCookie()

◆ StartHttp()

void StartHttp ( uint16_t  port,
bool  RunConfigMirror 
)

Start the HTTP web server. Further documentation in the Initialization section Initialization - System Initialization Functions.

If no parameters are specified it will listen on port 80, and enable the configuration mirror feature so an application can create its own custom configuration web page.

Parameters
portListen port, defaults to port 80
RunConfigMirrorEnable configuration mirror, default is true
Returns
nothing
See also
StopHttp(), StartHttps()

◆ StartHttps()

void StartHttps ( uint16_t  ssl_port,
uint16_t  http_port 
)

Start the HTTPS secure web server.

If no parameters are specified, the web server will listen on ports 443 and 80, and enable the configuration mirror feature so an application can create its own custom configuration web page. If no user certificate/key is installed, the default system key will be used.

Default parameter values defined in init.h

Parameters
ssl_portSecure listen port, defaults to port 443
http_portNon-secure listen port, defaults to port 80
Returns
nothing
See also
StartHttp(), StopHttp()

◆ StopHttp()

void StopHttp ( )

Stop the HTTP web server.

Returns
nothing
See also
StartHttp()

◆ writeallsafestring()

int writeallsafestring ( int  fd,
PCSTR  str 
)

Send a string and escape all special characters.

When sending a HTML text response, certain characters (e.g. '<') are interpreted by the browser as formatting. This function properly escapes the text so it will appear as intended.

Parameters
fdFile descriptor used to send response
strString to send
Returns
The number of characters sent

◆ WriteHtmlVariable()

void WriteHtmlVariable ( int  fd,
CONFIG_RENDER_OBJ  co 
)

Send a CONFIG_RENDER_OBJ to the client.

The CONFIG_RENDER_OBJ must have been previously created with a ConfigRenderFunc() function.

Parameters
fdFile descriptor to send data to
coCONFIG_RENDER_OBJ to send

◆ writesafestring()

int writesafestring ( int  fd,
PCSTR  str,
size_t  strLength 
)

Send a string with a specified length and escape all special characters.

When sending a HTML text response, certain characters (e.g. '<') are interpreted by the browser as formatting. This function properly escapes the text so it will appear as intended.

Parameters
fdFile descriptor used to send response
strString to send
strLengthnumber of characters from str to send
Returns
The number of characters sent