Parameters Configuration

All µC/HTTP-server instances require their own configuration structure. Each web server instance are highly customizable using the instance configuration structure HTTPs_CFG. Instance configuration template files are provided (see µC/HTTP-server Directories and Files). For each web server instance, these instance configuration template file (http-s_instance_cfg.*) should be copied into application folder and modified following your web application instance requirements.

Micrium provides sample configuration code free of charge; however, most sample code will likely require modification depending on the combination feature requirements and memory limitation.

`HTTPs_CFG` Structure

µC/HTTP-server instance configuration is based on large structure that contains different configuration sections with many parameter settings. This section describes the instance configuration settings, and should provide you an in-depth understanding of all instance parameter configuration. You will also discover which settings to modify in order to enhance the functionalities and the performances. Refer to the configuration field description section for further details. The HTTPs_CFG object must be passed to the HTTPs_InstanceInit() API function during the initialization of the HTTP server instance.

Structure Fields

HTTPs Instance Configuration Structure

const  HTTPs_CFG  HTTPs_CfgInstance = {
/* ------------------------------- OS CONFIGURATION ------------------------------- */
    10,                                     /* .OS_TaskDly_ms                       */
/* ------------------------- LISTEN SOCKET CONFIGURATION -------------------------- */
    HTTPs_SOCK_SEL_IPv4_IPv6,               /* .SockSel                             */       
    DEF_NULL,                               /* .SecurePtr                           */
    HTTPs_CFG_DFLT_PORT,                    /* .Port                                */
/* --------------------------- CONNECTION CONFIGURATION --------------------------- */
    15,                                     /* .ConnNbrMax                          */
    1,                                      /* .ConnInactivityTimeout_s             */
    1460,                                   /* .BufLen                              */
	DEF_ENABLED,                            /* .ConnPersistentEn                    */
/* -------------------------- FILE SYSTEM CONFIGURATION --------------------------- */
	HTTPs_FS_TYPE_NONE,                     /* .FS_Type                             */
   &HTTPs_CfgFS_None,                       /* .FS_CfgPtr                           */
    HTTPs_CFG_INSTANCE_STR_FILE_DEFAULT,    /* .DfltResourceNamePtr                 */
/* ----------------------------- PROXY CONFIGURATION ------------------------------ */
    128,                                    /* .HostNameLenMax                      */
/* ------------------------------ HOOK CONFIGURATION ------------------------------ */
	DEF_NULL,								/* .HooksPtr                            */
    DEF_NULL,								/* .Hooks_CfgPtr	                    */
/* -------------------------- HEADER FIELD CONFIGURATION -------------------------- */
	DEF_NULL,								/* .HdrRxCfgPtr 			            */
	DEF_NULL,                               /* .HdrTxCfgPtr 			            */
/* -------------------------- QUERY STRING CONFIGURATION -------------------------- */
	DEF_NULL,								/* .QueryStrCfgPtr						*/
/* ------------------------------ FORM CONFIGURATION ------------------------------ */
	DEF_NULL,                               /* .FormCfgPtr                          */
/* ------------------- DYNAMIC TOKEN REPLACEMENT CONFIGURATION -------------------- */
	DEF_NULL                                /* .Token_CfgPtr                        */
};

Fields Description

Task

Table - Task Configuration

Structure Field

Type

Description

Possible Values

OS_TaskDly_ms

CPU_INT32U

Configure instance task delay in integer milliseconds

The web server can delay his task periodically to allow other task with lower priority to run.

MUST be >= 0

Listen Socket

Table - Listen Socket Configuration

Structure Field Type Description Possible Values

SockSel

HTTPs_SOCK_SEL

Configure socket type. Select which kind of IP addresses can be accepted by the web server instance.

When only one IP type is selected, only one socket and TCP connection will be reserved to listen for incoming connections.
When the two IP types are selected, two sockets and TCP connections will be reserved for listening.

HTTPs_SOCK_SEL_IPv4 (Accept Only IPv4)
HTTPs_SOCK_SEL_IPv6 (Accept Only IPv6)
HTTPs_SOCK_SEL_IPv4_IPv6 (Accept IPv4 and IPv6)

SecurePtr

HTTPs_SECURE_CFG

Configure instance secure (SSL/TLS) configuration structure.

'Secure' field is used to enabled or disable SSL/TLS:

DEF_NULL, the web server instance is not secure and doesn't use SSL/TLS.
Point to a secure configuration structure, the web server is secure and use SSL/TLS.

The secure web server can be enabled ONLY if the application project contains a secure module supported by uC/TCPIP such as:

NanoSSL provided by Mocana.
CyaSSL provided by YaSSL.

DEF_NULL for a non-secure web server
Pointer to the secure configuration to be used.

Port

CPU_INT16U

Configure instance server port.

Default HTTP port used by all web browser is 80. The default port number is defined by the following value:
HTTPs_CFG_DFLT_PORT
When default port is used the web server instance can be access using the IP address of the target from any web browser:
http://<target ip address>
If the web server instance is configured with the non default port, the instance server should be accessed via this kind of address:
http://<target ip address>:<port number>
Where:
<target ip address> must be replaced by the IP address of the target.
<port number> must be replaced by the configured port number.
Default secure port used by all browser is 443. The default secure port number is defined by the following value:
HTTPs_CFG_FDLT_PORT_SECURE
When default port is used the web server instance can be access using the IP address of the target from any web browser:
https://<target ip address>
If the web server instance is configured with the non default port, the instance server should be accessed via this kind of address:
https://<target ip address>:<port number>
Where
<target ip address> must be replaced by the IP address of the target.
<port number> must be replaced by the configured port number.
Port number must be unique, i.e. it's not possible to start two instance with the same port number.

HTTPs_CFG_DFLT_PORT (Default HTTP port)
HTTPs_CFG_FDLT_PORT_SECURE Default (HTTP SSL port)

Connection

Table - Connection Configuration

Structure Field	Type	Description	Possible Values
`ConnNbrMax`	`CPU_INT08U`	Configure maximum number of simultaneous connections. '`ConnNbrMax`' is used to configure maximum number of connection that the web server will be able to serve simultaneously. Maximum number of connections must be configured following your requirements about the memory usage and the number of connection: Each connection requires memory space. So the memory required by the web server is greatly affected by the number of connection configured. When a client download an items such as HTML document, image, CSS file, Javascript file, it should open a new connection for each of these items when the Persistent Connection feature is disabled. Also most common web server can open up to 15 simultaneously connections. As example, for an HTML document which includes 2 images + 1 CSS file, 4 connections could be opened simultaneously. The number of connection and uC/TCP-IP configuration must be configured accordingly. Each connection requires 1 TCP socket and the server require 1 or 2 TCP socket depending if IPv4 and IPv6 connection can be accepted, see TCP Layer Configuration and Socket Layer Configuration to properly configure the web instance and µC/TCP-IP.	MUST be >= 1
`ConnInactivityTimeout_s`	`CPU_INT16U`	Configure connection maximum inactivity timeout in integer seconds. For each connection when the inactivity timeout occurs the connection is automatically closed whatever what the state of the connection was.	SHOULD be >= 1
`BufLen`	`CPU_INT16U`	Configure connection buffer length. Each connection has a buffer to receive & transmit data and to read file. If the memory is limited the buffer size can be reduced, but the performance could be impacted.	MUST be >= 512
`ConnPersistentEn`	`CPU_BOOLEAN`	Configure Persistent Connection feature. See section Persistent Connection for more details on the Persistent Connection concept.	`DEF_DISABLED` `DEF_ENABLED`

File System

See section File System Configuration for additional details on the File System configuration and configuration structures.

Table - File System Configuration

Structure Field Type Description Possible Values

FS_Type

HTTPs_FS_TYPE

Configure the Type of File System to use with the HTTP server :

HTTPs_FS_TYPE_NONE : No File System is present.
HTTPs_FS_TYPE_STATIC : Use the HTTP Static File System offered inside the HTTP-server.
HTTPs_FS_TYPE_DYN : Use a standard dynamic File System (e.g. µC/FS)

HTTPs_FS_TYPE_NONE
HTTPs_FS_TYPE_STATIC
HTTPs_FS_TYPE_DYN

FS_CfgPtr

const void*

Configure Pointer to the File System Configuration object.

Each File System Type has its configuration structure:

HTTPs_CFG_FS_NONE
HTTPs_CFG_FS_STATIC
HTTPs_CFG_FS_DYN

MUST be a valid pointer.

DfltResourceNamePtr

CPU_CHAR*

Configure instance default HTML document.

The default HTML document is returned when no file is specified in the request of the client, i.e. accessing with only the web server address. Most of the time this file should be "index.html".

MUST be a string pointer

Proxy

Table - Proxy Configuration

Structure Field Type Description Possible Values

HostNameLenMax

CPU_INT16U

Configure maximum host name length.

When a HTTP Server is behind a HTTP Proxy, the HTTP client must send its requests with an absolute URI. For example :

GET http://example.com/index.html HTTP/1.1

When the absolute URI feature is enable, the HTTP server will support absolute URI in the first line of the HTTP request messages (see example just above). The server will also look for the 'Host' header field in the received request messages and save it in the HostPtr field of the HTTPs_CONN structure.

The maximum host name length is the maximum length the server will allow for the received host name in a request message.

Proxy support must be enabled to allow the web server to support absolute URI. See Proxy Configuration for further information.

SHOULD be >= 1.

Hook Functions

See Section Hook Configuration for additional details on the hook functions configuration structure.

Table - Hook Function Configuration

Structure Field	Type	Description	Possible Values
`HookPtr`	`const` `HTTPs_HOOK_CFG` `Pointer`	Pointer to an HTTPs_HOOK_CFG type object. This object contains all the hook function pointers available to personalize the processing of HTTP requests received.	Pointer to Hook object or DEF_NULL.
`Hook_CfgPtr`	`void*`	Data associated with the Hook set-up that will be available inside each hook function.	Pointer to Hook Configuration object or DEF_NULL.

Header Field

See Section HTTP Header Configuration for additional details on the Header Configuration structures.

Table - Header Field Configuration

Structure Field Type Description Possible Values

HdrRxCfgPtr

const HTTPs_HDR_RX_CFG

 Pointer

Configure pointer to HTTP Request (RX) Header Configuration object structure.

Pointer to Configuration object structure.

DEF_NULL, if feature not necessary.

HdrTxCfgPtr

const HTTPs_HDR_TX_CFG Pointer

Configure pointer to HTTP Response (TX) Header Configuration object structure.

Pointer to Configuration object structure.

DEF_NULL, if feature not necessary.

Query String

See section Query String Configuration for additional details on Query String Configuration structure.

Table - Query String Configuration

Structure Field Type Description Possible Values

QueryStrCfgPtr

const HTTPs_QUERY_STR_CFG Pointer

Configure pointer to HTTP Query String Configuration object structure.

Pointer to Configuration object structure.

DEF_NULL, if feature not necessary.

Form

See section HTTP Form Configuration for additional details on Form Configuration structure.

Table - Form Configuration

Structure Field Type Description Possible Values

FormCfgPtr

const HTTPs_FORM_CFG Pointer

Configure pointer to HTML Form Configuration object structure.

Pointer to Configuration object structure.

DEF_NULL, if feature not necessary.

Dynamic Token Replacement

See section Token Configuration for additional details on Token Configuration structure.

Table - Token Configuration

Structure Field Type Description Possible Values

Token_CfgPtr

const HTTPs_TOEKN_CFG Pointer

Configure pointer to Token Replacement Configuration object structure.

Pointer to Configuration object structure.

DEF_NULL, if feature not necessary.

Parameters Configuration

HTTPs_CFG Structure

Structure Fields

Fields Description

Task

Listen Socket

Connection

File System

Proxy

Hook Functions

Header Field

Query String

Form

Dynamic Token Replacement

`HTTPs_CFG` Structure