NetBurner 3.5.0
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  CallBackFunctionPostHandler
 Implements the HtmlPostHandler class as a function pointer callback for POST requests. More...
 
class  HtmlPostVariableListCallback
 Implements the HtmlPostVariableListHandler class as a function pointer callback for HTTP POST submissions. More...
 

Typedefs

typedef int http_gethandlerfunc(int sock, HTTP_Request &pd)
 Implements the HtmlPageHandler class as a function pointer callback for GET requests.
 
typedef int http_posthandler(int sock, HTTP_Request &httpReqInfo)
 Type definition of the HtmlPostHandler callback for POST requests.
 

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.
 
int SendFullResponse (char const *name, int fd)
 Send a file with the proper HTTP header, file specified by file name.
 
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.
 
int SendHeaderResponse (char const *name, int fd)
 Send a HTTP header response for the specified file type.
 
int SendHeaderResponse (HTML_FILE_RECORD *fr, int fd)
 Send a HTTP header response for the specified HTML_FILE_RECORD type.
 
int32_t SendFileFragment (char const *name, int32_t fd, PCSTR url=NULL)
 Send a file fragment without a header.
 
HTML_FILE_RECORD * GetRecordFromName (char const *name)
 Returns a pointer to a HTML_FILE_RECORD for the specified file name.
 
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.
 
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.
 
void WriteHtmlVariable (int fd, CONFIG_RENDER_OBJ co)
 Send a CONFIG_RENDER_OBJ to the client.
 
HTTP_RequestGetActiveHttpRequest ()
 Get thc curent active running http request. Only valid fromwithing http get or post handeling. Also valid during page fill in operations.
 
HTTP_ACCESS CheckHttpAccess (int sock, int access_level, HTTP_Request &Req)
 All HTTP requests go though this function.
 
void StartHttp (uint16_t port, bool RunConfigMirror)
 Start the HTTP web server. Further documentation in the Initialization section Initialization - System Initialization Functions.
 
void StopHttp ()
 Stop the HTTP web server.
 
void SendHTMLHeader (int sock)
 Send a HTML response header.
 
void SendHTMLHeaderWCookie (int sock, char *cookie)
 Send a HTML response header and cookie.
 
void SendTextHeader (int sock)
 Send a HTML plain text header.
 
void SendGifHeader (int sock)
 Send a HTML GIF header.
 
void EmptyResponse (int sock)
 Send an empty response back.
 
void NoContentResponse (int sock)
 Send a no content response back.
 
void RedirectResponse (int sock, PCSTR new_page)
 Redirect a HTTP request to a different page.
 
void NotFoundResponse (int sock, PCSTR new_page)
 Send a page not found response.
 
void ForbiddenResponse (int sock, PCSTR new_page)
 Send a page is forbidden response.
 
void NotAvailableResponse (int sock, PCSTR new_page)
 Send a response indicating that the requested resource is not available at this time.
 
void BadRequestResponse (int sock, PCSTR url, PCSTR data)
 Send a response indicating that the client request itself is faulty in some manner.
 
int writeallsafestring (int fd, PCSTR str)
 Send a string and escape all special characters.
 
int writesafestring (int fd, PCSTR str, size_t strLength)
 Send a string with a specified length and escape all special characters.
 
int httpstricmp (PCSTR str1, PCSTR strIsUpper2)
 Special string compare. Returns 1 if the strings match until one string ends with a null (0).
 
void StartHttps (uint16_t ssl_port, uint16_t http_port)
 Start the HTTPS secure web server.
 

Detailed Description

#include< htmlfiles.h >

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.

#include< http.h >

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()

#include< httppost.h >

#include< https.h >

Typedef Documentation

◆ http_gethandlerfunc

typedef int http_gethandlerfunc(int sock, HTTP_Request &pd)

#include <http.h>

Implements the HtmlPageHandler class as a function pointer callback for GET requests.

Return values
0Not handled, no changes are made
1Handled
2TCP socket will be kept. Socket will get closed by some other method. For example, a large file could be sent from a different task. Any return value other than 2 means the page was processed normally.

◆ http_posthandler

typedef int http_posthandler(int sock, HTTP_Request &httpReqInfo)

#include <httppost.h>

Type definition of the HtmlPostHandler callback for POST requests.

This should only be used if the specific variable callback implementions will not work in your application. This is mostly an internal use function.

Parameters
sockThe socket the request came in on.
httpReqInfoInformation about the request HTTP_Request.
Return values
0Not handled, no changes are made
1Handled
2TCP socket will be kept. Socket will get closed by some other method. For example, a large file could be sent from a different task. Any return value other than 2 means the page was processed normally.
See also
HtmlPostVariableListCallback
HtmlPostVariableListHandler

Enumeration Type Documentation

◆ HTTP_RequestTypes

#include <http.h>

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 )

#include <http.h>

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
See also
RedirectResponse(), NotFoundResponse(), ForbiddenResponse()
NotAvailableResponse()

◆ CheckHttpAccess()

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

#include <http.h>

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 )

#include <htmlfiles.h>

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 )

#include <htmlfiles.h>

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)

#include <http.h>

Send an empty response back.

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

◆ ForbiddenResponse()

void ForbiddenResponse ( int sock,
PCSTR new_page )

#include <http.h>

Send a page is forbidden response.

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

◆ GetRecordFromName()

HTML_FILE_RECORD * GetRecordFromName ( char const * name)

#include <htmlfiles.h>

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 )

#include <http.h>

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

◆ NoContentResponse()

void NoContentResponse ( int sock)

#include <http.h>

Send a no content response back.

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

◆ NotAvailableResponse()

void NotAvailableResponse ( int sock,
PCSTR new_page )

#include <http.h>

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
See also
RedirectResponse(), NotFoundResponse(), ForbiddenResponse()
BadRequestResponse()

◆ NotFoundResponse()

void NotFoundResponse ( int sock,
PCSTR new_page )

#include <http.h>

Send a page not found response.

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

◆ RedirectResponse()

void RedirectResponse ( int sock,
PCSTR new_page )

#include <http.h>

Redirect a HTTP request to a different page.

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

◆ SendEmailResponse()

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

#include <htmlfiles.h>

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 )

#include <htmlfiles.h>

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 )

#include <htmlfiles.h>

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 )

#include <htmlfiles.h>

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)

#include <http.h>

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
See also
SendHTMLHeader(), SendTextHeader(), SendHTMLHeaderWCookie()

◆ SendHeaderResponse() [1/2]

int SendHeaderResponse ( char const * name,
int fd )

#include <htmlfiles.h>

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 )

#include <htmlfiles.h>

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)

#include <http.h>

Send a HTML response header.

Used to build your own HTML response

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

◆ SendHTMLHeaderWCookie()

void SendHTMLHeaderWCookie ( int sock,
char * cookie )

#include <http.h>

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
See also
SendHTMLHeader(), SendGifHeader(), SendTextHeader()

◆ SendTextHeader()

void SendTextHeader ( int sock)

#include <http.h>

Send a HTML plain text header.

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

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

◆ StartHttp()

void StartHttp ( uint16_t port,
bool RunConfigMirror )

#include <http.h>

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
See also
StopHttp(), StartHttps()

◆ StartHttps()

void StartHttps ( uint16_t ssl_port,
uint16_t http_port )

#include <https.h>

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
See also
StartHttp(), StopHttp()

◆ StopHttp()

void StopHttp ( )

#include <http.h>

Stop the HTTP web server.

See also
StartHttp()

◆ writeallsafestring()

int writeallsafestring ( int fd,
PCSTR str )

#include <http.h>

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 )

#include <htmlfiles.h>

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 )

#include <http.h>

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