Control Interface

Functions to work with the HTTP server. More...

Functions
netStatus	netHTTPs_Start (void)
	Start the HTTP server. [thread-safe]. More...
netStatus	netHTTPs_Stop (void)
	Stop the HTTP server. [thread-safe]. More...
bool	netHTTPs_Running (void)
	Check if the HTTP server is running. [thread-safe]. More...
uint16_t	netHTTPs_GetPort (void)
	Get port number of the HTTP server. [thread-safe]. More...
netStatus	netHTTPs_SetPort (uint16_t port)
	Set port number of the HTTP server. [thread-safe]. More...
const char *	netHTTPs_GetRootPath (void)
	Retrieve path to the root directory on HTTP server. [thread-safe]. More...
netStatus	netHTTPs_SetRootPath (const char *path)
	Set path to the root directory on HTTP server. [thread-safe]. More...
const char *	netHTTPs_GetUsername (void)
	Retrieve username of the built-in user account. [thread-safe]. More...
netStatus	netHTTPs_SetUsername (const char *username)
	Set username of the built-in user account. [thread-safe]. More...
const char *	netHTTPs_GetPassword (void)
	Retrieve password of the built-in user account. [thread-safe]. More...
netStatus	netHTTPs_SetPassword (const char *password)
	Reset password of the built-in user account. [thread-safe]. More...
bool	netHTTPs_LoginActive (void)
	Determine if the HTTP server authentication is enabled. [thread-safe]. More...
netStatus	netHTTPs_LoginOnOff (bool login)
	Enable or disable HTTP server authentication. [thread-safe]. More...
netStatus	netHTTPs_GetClient (NET_ADDR *addr, uint32_t addr_len)
	Get IP address and port number of a connected remote HTTP client. [thread-safe]. More...
int32_t	netHTTPs_GetSession (void)
	Get current session number of the HTTP server. [thread-safe]. More...
const char *	netHTTPs_GetLanguage (void)
	Retrieve the preferred language setting from the browser. [thread-safe]. More...
const char *	netHTTPs_GetContentType (void)
	Get Content-Type HTML header, received in XML post request. [thread-safe]. More...

Description

Functions to work with the HTTP server.

Like all services, the HTTP server is normally started automatically if NET_START_SERVICE is set to 1 in the Net_Config.c configuration file. If it is set to 0, the HTTP server needs to be started manually in the user application using netHTTPs_Start. At runtime, it is always possible to stop the HTTP server using the function netHTTPs_Stop. The user application can check for a running server using the netHTTPs_Running function.

To change the port of the HTTP server at runtime, first call netHTTPs_Stop (if the server is running) and then use the netHTTPs_SetPort function. Afterwards, the HTTP server needs to be (re-)started by the application calling netHTTPs_Start.

To change the path to a root folder of the HTTP server at runtime, first call netHTTPs_Stop (if the server is running) and then use the netHTTPs_SetRootPath function. Afterwards, the HTTP server needs to be (re-)started by the application calling netHTTPs_Start.

The HTTP server supports a built-in user account if the HTTP_SERVER_AUTH_ADMIN is set to 1. In this case, the user specified by HTTP_SERVER_AUTH_USER is created and the password HTTP_SERVER_AUTH_PASS is used for this user. The HTTP server control interface provides functions to work with this built-in account. To retrieve the username in the application, use netHTTPs_GetUsername. To change this username at runtime, use netHTTPs_SetUsername. The same pair of functions is available for managing the password (netHTTPs_GetPassword / netHTTPs_SetPassword).

It is also possible to check if this login is active (netHTTPs_LoginActive) and to enable or disable it at runtime using netHTTPs_LoginOnOff. Please note that the function netHTTPs_LoginOnOff is only available at runtime if the define HTTP_SERVER_AUTH_ENABLE is set to 1 in the Net_Config_HTTP_Server.h file. Otherwise, this command will not be compiled into the project to save resources. For more complex account management, use the Access and Multi-User Interface.

For some of the Dynamic Web Content you need information from the client/browser that is connected to the HTTP server. To retrieve the IP address and port number of the connected client, use netHTTPs_GetClient. For the current session number you are working with, use netHTTPs_GetSession. To display web sites in the correct language, you can examine the preferred language used by the browser with netHTTPs_GetLanguage. netHTTPs_GetContentType returns the content-type HTML header for further processing.

Function Documentation

netHTTPs_GetClient()

netStatus netHTTPs_GetClient	(	NET_ADDR *	addr,
		uint32_t	addr_len
	)

Get IP address and port number of a connected remote HTTP client. [thread-safe].

Parameters

[out]	addr	structure that will receive IP address and port number.
[in]	addr_len	size of NET_ADDR structure for the client.

Returns

status code that indicates the execution status of the function.

The function netHTTPs_GetClient obtains information about the remote machine that has connected to the HTTP server.

The argument addr points to a structure that will receive the IP address and port of the remote machine.

The argument addr_len specifies the length of the addr structure. Using IPv4 only, you can optimize memory usage by specifying an addr_len that is equal to the size of NET_ADDR4 (8 bytes). The HTTP server checks the addr_len argument, whether it can enter the IP address of the client into the structure.

Possible netStatus return values:

• netOK: Operation completed successfully.
• netInvalidParameter: Invalid parameter provided.
• netWrongState: Server session not active.

Note

Use this function to restrict machines from performing system changes.

Code Example

NET_ADDR client;
char ip_ascii[40];
 ..
netHTTPs_GetClient (&client, sizeof(client));
netIP_ntoa (client.addr_type, client.addr, ip_ascii, sizeof(ip_ascii));
printf ("IP address: %s\n", ip_ascii);
printf ("TCP port:   %d\n", client.port);

netHTTPs_GetContentType()

const char * netHTTPs_GetContentType

(

void

)

Get Content-Type HTML header, received in XML post request. [thread-safe].

Returns

pointer to content type header, a null-terminated string.

The function netHTTPs_GetContentType returns a pointer to the Content-Type HTML header, which was received with a XML or any other type POST request. You can use this function to check for the content type, which was submitted by a web service application.

When a web service application sends a request to a web server, it specifies the Content-Type in the HTTP header that is sent to the web server. This information is processed by the Network Component and stored internally.

Code Example

void netCGI_ProcessData (uint8_t code, const char *data, uint32_t len) {
  char var[40];
 
  switch (code) {
    ...
    case 4:
      // Other content type data, last packet
      // Example
      if (strcmp (netHTTPs_GetContentType(), "text/xml; charset=utf-8" == 0) {
        // Content type xml, utf-8 encoding
         ...
      }
      break;
 
    default:
      // Ignore all other codes
      break;
  }
}

netHTTPs_GetLanguage()

const char * netHTTPs_GetLanguage

(

void

)

Retrieve the preferred language setting from the browser. [thread-safe].

Returns

pointer to the language code, a null-terminated string.

The function netHTTPs_GetLanguage retrieves the preferred language setting from the browser. You can use this information to implement automatic language selection for your embedded web pages.

When a web browser requests a web page, it specifies the preferred language in the HTTP header that is sent to the web server. This information is processed by the Network Component and stored internally.

Note

You can set the language preference in Internet Explorer by selecting Tools -> Internet Options -> Languages. In Mozilla Firefox, you can set the language preference by selecting Options -> Options -> Content -> Languages.

Code Example

uint32_t netCGI_Script (const char *env, char *buf, uint32_t buf_len, uint32_t *pcgi) {
  uint32_t len = 0;
  char *lang;
 
  switch (env[0]) {
     ..
    case 'e':
      // Browser Language - file 'language.cgi' 
      lang = netHTTPs_GetLanguage();
      if (strcmp (lang, "en") == 0) {
        lang = "English";
      }
      else if (strcmp (lang, "en-us") == 0) {
        lang = "English USA";
      }
      else if (strcmp (lang, "de") == 0) {
        lang = "German";
      }
      else if (strcmp (lang, "de-at") == 0) {
        lang = "German AT";
      }
      else if (strcmp (lang, "fr") == 0) {
        lang = "French";
      }
      else {
        lang = "Unknown";
      }
      len = sprintf (buf, &env[2], lang, netHTTPs_GetLanguage());
      break;
  }
  return (len);
}

netHTTPs_GetPassword()

const char * netHTTPs_GetPassword

(

void

)

Retrieve password of the built-in user account. [thread-safe].

Returns

pointer to password, a null-terminated string.

• NULL if authentication is disabled in the configuration.

The function netHTTPs_GetPassword returns the password of the built-in user if HTTP_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_HTTP_Server.h file. If this define is set to 0, the function is not available at runtime and returns NULL.

Code Example (see netHTTPs_LoginActive)

netHTTPs_GetPort()

uint16_t netHTTPs_GetPort

(

void

)

Get port number of the HTTP server. [thread-safe].

Returns

port number.

The function netHTTPs_GetPort returns the port that is used for the HTTP server.

Code Example

printf ("HTTP server is listening on port %d\n", netHTTPs_GetPort ());

netHTTPs_GetRootPath()

const char * netHTTPs_GetRootPath

(

void

)

Retrieve path to the root directory on HTTP server. [thread-safe].

Returns

pointer to root path, a null-terminated string.

• NULL if root folder is disabled in the configuration.

The function netHTTPs_GetRootPath returns the path to the current root directory if HTTP_SERVER_ROOT_ENABLE is set to 1 in the Net_Config_HTTP_Server.h file. If this define is set to 0, the function is not available at runtime and returns NULL.

Code Example

if (netHTTPs_GetRootPath() != NULL) {
  printf ("Web recources are stored here: %s\n", netHTTPs_GetRootPath ());
}

netHTTPs_GetSession()

int32_t netHTTPs_GetSession

(

void

)

Get current session number of the HTTP server. [thread-safe].

Returns

current session number.

The function netHTTPs_GetSession returns the current session number of the HTTP server running on the Network Component. The session number can be any value between 0 and HTTP_SERVER_NUM_SESSIONS, defined in Net_Config_HTTP_Server.h.

Note

Storing the HTTP query string in a single global variable can result in the HTTP server sending the wrong reply to a client when several clients try to access a dynamic HTTP page at the same time. Hence, it is better to have a separate variable for each session, for example an array of query strings.

Code Example

// Should be the same value as set in 'Net_Config_HTTP_Server.h' file. 
#define HTTP_SERVER_NUM_SESSIONS 10
 
int32_t answer[HTTP_SERVER_NUM_SESSIONS];
 
uint32_t netCGI_Script (const char *env, char *buf, uint32_t buf_len, uint32_t *pcgi) {
  uint32_t len = 0;
  int32_t http_session;
  ..
  http_session = netHTTPs_GetSession ();
  len += sprintf (buf+len,"Answer is: %d",answer[http_session]);
   ..
  return (len);
}

netHTTPs_GetUsername()

const char * netHTTPs_GetUsername

(

void

)

Retrieve username of the built-in user account. [thread-safe].

Returns

pointer to username, a null-terminated string.

• NULL if authentication is disabled in the configuration.

The function netHTTPs_GetUsername returns the user name of the built-in user if HTTP_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_HTTP_Server.h file. If this define is set to 0, the function is not available at runtime and returns NULL.

Code Example (see netHTTPs_LoginActive)

netHTTPs_LoginActive()

bool netHTTPs_LoginActive

(

void

)

Determine if the HTTP server authentication is enabled. [thread-safe].

Returns

• true = Authentication enabled in the configuration.
• false = Authentication is not enabled.

The function netHTTPs_LoginActive checks if the HTTP server is accepting log-in data.

Code Example

if (netHTTPs_LoginActive() == true) {
  printf ("Authentication is enabled\n");
  printf ("Username is: %s\n", netHTTPs_GetUsername());
  printf ("Password is: %s\n", netHTTPs_GetPassword());
}

netHTTPs_LoginOnOff()

netStatus netHTTPs_LoginOnOff

(

bool

login

)

Enable or disable HTTP server authentication. [thread-safe].

Parameters

[in]

login

new authentication state: true = Enable authentication. false = Disable authentication.

Returns

status code that indicates the execution status of the function.

The function netHTTPs_LoginOnOff enables or disables the user authentication on the HTTP server. If HTTP_SERVER_AUTH_ENABLE is set to 0 in the Net_Config_HTTP_Server.h file, the function is not available at runtime.

The argument login switches the log-in on (true) or off (false).

Possible netStatus return values:

• netOK: Login enabled or disabled successfully.
• netError: Authentication not enabled in the configuration.

Code Example

if (netHTTPs_LoginActive () == true) {
  netHTTPs_LoginOnOff (false);
}

netHTTPs_Running()

bool netHTTPs_Running

(

void

)

Check if the HTTP server is running. [thread-safe].

Returns

• true = Server is running.
• false = Server is not running.

The function netHTTPs_Running checks whether the HTTP server is running. It returns true if the server is up and running.

Code Example (see netHTTPs_SetPort)

netHTTPs_SetPassword()

netStatus netHTTPs_SetPassword

(

const char *

password

)

Reset password of the built-in user account. [thread-safe].

Parameters

[in]

password

new password, a null-terminated string.

Returns

status code that indicates the execution status of the function.

The function netHTTPs_SetPassword sets the password of the built-in user if HTTP_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_HTTP_Server.h file. If this define is set to 0, the function is not available at runtime.

The argument password is a pointer to the password that is to be set, which is a null-terminated string. The function copies the content of the password to the password of the build-in user. The maximum length of the password string is limited to 15 characters.

If the authentication type is Digest, the argument password can be either a plain text password or a pre-calculated HA1 hash value. The password for HA1 should be 32 bytes, lowercase hexadecimal. (see netHTTPs_GetUserSecret)

Possible netStatus return values:

• netOK: Password successfully set.
• netInvalidParameter: Invalid password provided.
• netError: Administrator account not enabled in the configuration.

Note

When the function ends, the content of password becomes irrelevant and may be discarded.

Code Example (see netHTTPs_SetUsername)

netHTTPs_SetPort()

netStatus netHTTPs_SetPort

(

uint16_t

port

)

Set port number of the HTTP server. [thread-safe].

Parameters

[in]

port

port number.

Returns

status code that indicates the execution status of the function.

The function netHTTPs_SetPort sets the port that is to be used for the HTTP server. The HTTP server must not run while setting the port. If required, stop it first using netHTTPs_Stop.

The argument port specifies the port number to be used.

Possible netStatus return values:

• netOK: Port successfully set.
• netWrongState: HTTP server is running.

Code Example

void change_server_port (uint16_t port) {}
  if (netHTTPs_Running() == true) {
    netHTTPs_Stop();
  }
  netHTTPs_SetPort (port);
  netHTTPs_Start();
}

netHTTPs_SetRootPath()

*netStatus netHTTPs_SetRootPath

(

const char *

path

)

Set path to the root directory on HTTP server. [thread-safe].

Parameters

[in]

path

new root path, a null-terminated string.

Returns

status code that indicates the execution status of the function.

The function netHTTPs_SetRootPath sets the path to the root directory of HTTP server if HTTP_SERVER_ROOT_ENABLE is set to 1 in the Net_Config_HTTP_Server.h file. If this define is set to 0, the function is not available at runtime. Root directory specifies a path on a storage device, where the WEB recources are stored.

The argument path is a pointer to the new root path to be set, which is a null-terminated string. The function copies the content of the path to the root path of the HTTP server. The maximum length of the path string is limited to 79 characters.

Possible netStatus return values:

• netOK: Root path successfully set.
• netInvalidParameter: Invalid path parameter provided.
• netWrongState: HTTP server is running.
• netError: Root path not enabled in the configuration.

Note

When the function ends, the content of path becomes irrelevant and may be discarded.

Code Example

netHTTPs_Stop ();
netHTTPs_SetRootPath ("/Web/Update");
netHTTPs_Start ();

netHTTPs_SetUsername()

netStatus netHTTPs_SetUsername

(

const char *

username

)

Set username of the built-in user account. [thread-safe].

Parameters

[in]

username

new username, a null-terminated string.

Returns

status code that indicates the execution status of the function.

The function netHTTPs_SetUsername sets the user name of the built-in user if HTTP_SERVER_AUTH_ADMIN is set to 1 in the Net_Config_HTTP_Server.h file. If this define is set to 0, the function is not available at runtime.

The argument username is a pointer to the user name to be set, which is a null-terminated string. The function copies the content of the username to the user name of the built-in user. The maximum length of the username string is limited to 15 characters.

Possible netStatus return values:

• netOK: Username successfully set.
• netInvalidParameter: Invalid username provided.
• netError: Administrator account not enabled in the configuration.

Note

When the function ends, the content of username becomes irrelevant and may be discarded.

Code Example

if (netHTTPs_LoginActive() == true) {
  netHTTPs_SetUsername ("sysadmin");
  netHTTPs_SetPassword ("a$Min#77");
}

netHTTPs_Start()

netStatus netHTTPs_Start

(

void

)

Start the HTTP server. [thread-safe].

Returns

status code that indicates the execution status of the function.

The function netHTTPs_Start starts the HTTP server at runtime. It can be stopped using netHTTPs_Stop.

Possible netStatus return values:

• netOK: HTTP server started successfully.

Note

If you set the NET_START_SERVICE to 1 in Net_Config.c, all selected services will be started automatically. Thus, you only need to call this function, if you have either stopped the HTTP server previously using netHTTPs_Stop or have set NET_START_SERVICE to 0.

Code Example (see netHTTPs_SetPort)

netHTTPs_Stop()

netStatus netHTTPs_Stop

(

void

)

Stop the HTTP server. [thread-safe].

Returns

status code that indicates the execution status of the function.

The function netHTTPs_Stop stops the HTPP server at runtime. It can be restarted using netHTTPs_Start.

Possible netStatus return values:

• netOK: HTTP server stopped successfully.

Code Example (see netHTTPs_SetPort)