Functions to work with the HTTP server. More...
Functions | |
netStatus | netHTTPs_Start (void) |
Start the HTTP server. [thread-safe]. | |
netStatus | netHTTPs_Stop (void) |
Stop the HTTP server. [thread-safe]. | |
bool | netHTTPs_Running (void) |
Check if the HTTP server is running. [thread-safe]. | |
uint16_t | netHTTPs_GetPort (void) |
Get port number of the HTTP server. [thread-safe]. | |
netStatus | netHTTPs_SetPort (uint16_t port) |
Set port number of the HTTP server. [thread-safe]. | |
const char * | netHTTPs_GetRootPath (void) |
Retrieve path to the root directory on HTTP server. [thread-safe]. | |
netStatus | netHTTPs_SetRootPath (const char *path) |
Set path to the root directory on HTTP server. [thread-safe]. | |
const char * | netHTTPs_GetUsername (void) |
Retrieve username of the built-in user account. [thread-safe]. | |
netStatus | netHTTPs_SetUsername (const char *username) |
Set username of the built-in user account. [thread-safe]. | |
const char * | netHTTPs_GetPassword (void) |
Retrieve password of the built-in user account. [thread-safe]. | |
netStatus | netHTTPs_SetPassword (const char *password) |
Reset password of the built-in user account. [thread-safe]. | |
bool | netHTTPs_LoginActive (void) |
Determine if the HTTP server authentication is enabled. [thread-safe]. | |
netStatus | netHTTPs_LoginOnOff (bool login) |
Enable or disable HTTP server authentication. [thread-safe]. | |
netStatus | netHTTPs_GetClient (NET_ADDR *addr, uint32_t addr_len) |
Get IP address and port number of a connected remote HTTP client. [thread-safe]. | |
int32_t | netHTTPs_GetSession (void) |
Get current session number of the HTTP server. [thread-safe]. | |
const char * | netHTTPs_GetLanguage (void) |
Retrieve the preferred language setting from the browser. [thread-safe]. | |
const char * | netHTTPs_GetContentType (void) |
Get Content-Type HTML header, received in XML post request. [thread-safe]. | |
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.h 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.
Get IP address and port number of a connected remote HTTP client. [thread-safe].
[out] | addr | structure that will receive IP address and port number. |
[in] | addr_len | size of NET_ADDR structure for the client. |
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:
Code Example
const char * netHTTPs_GetContentType | ( | void | ) |
Get Content-Type HTML header, received in XML post request. [thread-safe].
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
const char * netHTTPs_GetLanguage | ( | void | ) |
Retrieve the preferred language setting from the browser. [thread-safe].
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.
Code Example
const char * netHTTPs_GetPassword | ( | void | ) |
Retrieve password of the built-in user account. [thread-safe].
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)
uint16_t netHTTPs_GetPort | ( | void | ) |
Get port number of the HTTP server. [thread-safe].
The function netHTTPs_GetPort returns the port that is used for the HTTP server.
Code Example
const char * netHTTPs_GetRootPath | ( | void | ) |
Retrieve path to the root directory on HTTP server. [thread-safe].
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
int32_t netHTTPs_GetSession | ( | void | ) |
Get current session number of the HTTP server. [thread-safe].
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.
Code Example
const char * netHTTPs_GetUsername | ( | void | ) |
Retrieve username of the built-in user account. [thread-safe].
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)
bool netHTTPs_LoginActive | ( | void | ) |
Determine if the HTTP server authentication is enabled. [thread-safe].
The function netHTTPs_LoginActive checks if the HTTP server is accepting log-in data.
Code Example
netStatus netHTTPs_LoginOnOff | ( | bool | login | ) |
Enable or disable HTTP server authentication. [thread-safe].
[in] | login | new authentication state:
|
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:
Code Example
bool netHTTPs_Running | ( | void | ) |
Check if the HTTP server is running. [thread-safe].
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)
netStatus netHTTPs_SetPassword | ( | const char * | password | ) |
Reset password of the built-in user account. [thread-safe].
[in] | password | new password, a null-terminated string. |
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:
Code Example (see netHTTPs_SetUsername)
netStatus netHTTPs_SetPort | ( | uint16_t | port | ) |
Set port number of the HTTP server. [thread-safe].
[in] | port | port number. |
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:
Code Example
*netStatus netHTTPs_SetRootPath | ( | const char * | path | ) |
Set path to the root directory on HTTP server. [thread-safe].
[in] | path | new root path, a null-terminated string. |
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:
Code Example
netStatus netHTTPs_SetUsername | ( | const char * | username | ) |
Set username of the built-in user account. [thread-safe].
[in] | username | new username, a null-terminated string. |
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:
Code Example
netStatus netHTTPs_Start | ( | void | ) |
Start the HTTP server. [thread-safe].
The function netHTTPs_Start starts the HTTP server at runtime. It can be stopped using netHTTPs_Stop.
Possible netStatus return values:
NET_START_SERVICE
to 1 in Net_Config.h, 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)
netStatus netHTTPs_Stop | ( | void | ) |
Stop the HTTP server. [thread-safe].
The function netHTTPs_Stop stops the HTPP server at runtime. It can be restarted using netHTTPs_Start.
Possible netStatus return values:
Code Example (see netHTTPs_SetPort)