Types, functions and values for Web interfaces with AJAX, CGI etc. More...

#include "weUtil.h"

Macros
#define	QS_MAX_KEY_LEN
	key's / name's max. length including final zero

#define	QS_MAX_STRING_LEN
	Query string's maximum length including final zero.

#define	QS_MAX_VAL_LEN
	key's / name's max. length including final zero

Functions
int	getQSparam (char const name, char const value, int const vLen)
	Get the query string parameter value for a unique and known key. More...

int	getQueryString ()
	Fetch and store the query string. More...

int	jsonBinForm (uint8_t const indent, char const const name, uint8_t const value, char end)
	Output an eight bit value binary formated as JSON name:value. More...

int	jsonBreading (uint8_t const indent, char const const name, uint8_t const value, char end)
	Output a boolean value as JSON name:value. More...

int	jsonFPreadingT (uint8_t const indent, char const const name, uint16_t const valueLo, uint16_t const valueHi, uint8_t dotPos, char const const unit, char end, char title)
	Output a physical value as JSON {object} with name, 32 bit FP value and unit. More...

int	jsonFreading (uint8_t const indent, char const const name, float const value, char const const unit, uint8_t const fractional, char *end)
	Output a float (physical value as JSON {object} with name, value and unit. More...

int	jsonFreadingT (uint8_t const indent, char const const name, float const value, char const const unit, uint8_t const fractional, char end, char title)
	Output a float value as JSON {object} with name, value, unit and help text. More...

int	jsonIreading (uint8_t const indent, char const const name, int const value, char end)
	Output an int value as JSON name:value. More...

int	jsonSreadingT (uint8_t const indent, char const const name, char const value, char const const unit, char end, char *title)
	Output a physical value as JSON {object} with name, value as String and unit. More...

Variables
char	actQSPvalue [64]
	to be used for actual parameter

char	queryString [512]
	holding the query string

char const *	requestMethod
	to hold (environment's) REQUEST_METHOD

Detailed Description

Types, functions and values for Web interfaces with AJAX, CGI etc.

Copyright  (c)  2018   Albrecht Weinert
weinert-automation.de      a-weinert.de
 
    /         /      /\
   /         /___   /  \      |
   \        /____\ /____\ |  _|__
    \  /\  / \    /      \|   |
     \/  \/   \__/        \__/|_                                 

Revision history

Rev. 236 2.02.2021
Rev.  82 14.12.2017 : new
Rev. 187 14.10.2018 : minor typos

In process control applications featuring a web HMI one approach is to use a CGI program communicating with control program by shared memory and semaphores. Both programs and their libraries are written in C. The CGI program is made known to / runnable by the web sever – Apache 2.4 here.

The HMI is a HTML web page using CSS, Javascript etc. communicating with the CGI program by AJAX. The answers (asynchronously) returned may be plain text, plain HTML XML or, preferably JSON.

Function Documentation

◆ getQueryString()

int getQueryString ( )

Fetch and store the query string.

This function gets the raw query string storing it (on success) in queryString. Raw means, all the ugly '+' and 'AB' things are still there.

Returns: 0: from get; 1: from get, truncated; 2: from post; 3: from get, truncated; -1: program probably not run as CGI, no query string

◆ getQSparam()

int getQSparam	(	char const *	name,
		char *const	value,
		int const	vLen
	)

Get the query string parameter value for a unique and known key.

This simple method would fetch the value to a known query string parameter.

Warning: Longer names/keys with the same prefix must come first. When having "carlength=91&length=300", this (simple) function will get "91" for "length".

Parameters

name	the parameter's name or key
value	character array (string) to store the value to, the result may be empty (on name\0, name=\0 or name&)
vLen	value's length including the terminating 0

Returns: 0: OK, got value; -1: got no value (no name, no value, ...) 1: got value truncated to vLen -1 characters

◆ jsonIreading()

int jsonIreading	(	uint8_t const	indent,
		char const *const	name,
		int const	value,
		char *	end
	)

Output an int value as JSON name:value.

This function puts an integer value as "name": "999" respectively "name": "-1" to the standard output.

The text end is appended. According to JSON syntax rules it must contain a comma (,) if and only if other elements follow. Besides that white space (", " " " ",\n" "\n") may enhance human readability.

Parameters

indent	0..36 number of spaces to put before
name	the property's name
value	the integer value (put as string)
end	0-terminated string to put at the end

Returns: >=0: OK; <0: error

◆ jsonBreading()

int jsonBreading	(	uint8_t const	indent,
		char const *const	name,
		uint8_t const	value,
		char *	end
	)

Output a boolean value as JSON name:value.

This function puts a boolean value as "name": true or as "name": false to the standard output.

The text end is appended. According to JSON syntax rules it must contain a comma (,) if and only if other elements follow. Besides that white space (", " " " ",\n" "\n") may enhance human readability.

Parameters

indent	0..36 number of spaces to put before
name	the property's name
value	0: false; else: true
end	0-terminated string to put at the end

Returns: >=0: OK; <0: error

◆ jsonBinForm()

int jsonBinForm	(	uint8_t const	indent,
		char const *const	name,
		uint8_t const	value,
		char *	end
	)

Output an eight bit value binary formated as JSON name:value.

This function puts a boolean value as "name": "1001_1100" to the standard output.

The text end is appended. According to JSON syntax rules it must contain a comma (,) if and only if other elements follow. Besides that white space (", " " " ",\n" "\n") may enhance human readability.

Parameters

indent	0..36 number of spaces to put before
name	the property's name
value	0..255 i.e 0000_0000 .. 1111_1111
end	0-terminated string to put at the end

Returns: >=0: OK; <0: error

◆ jsonFreading()

int jsonFreading	(	uint8_t const	indent,
		char const *const	name,
		float const	value,
		char const *const	unit,
		uint8_t const	fractional,
		char *	end
	)

Output a float (physical value as JSON {object} with name, value and unit.

This function puts a float value as e.g. {"name": "Wimp", "value": "15.22", "unit": "kWh"}

The text by parameter end is appended. According to JSON syntax rules it must contain a comma (,) if and only if other elements follow. Besides that white space (", " " " ",\n" "\n") may enhance human readability.

Parameters

indent	0..36 number of spaces to put before
name	0-terminated string naming the reading (measured value e.g.)
value	the float value
unit	0-terminated string being the value's physical unit
fractional	0..9 number of fractional digits 0: value will be taken as int
end	0-terminated string to put at the end

Returns: >=0: OK; <0: error

◆ jsonFreadingT()

int jsonFreadingT	(	uint8_t const	indent,
		char const *const	name,
		float const	value,
		char const *const	unit,
		uint8_t const	fractional,
		char *	end,
		char *	title
	)

Output a float value as JSON {object} with name, value, unit and help text.

This function puts a float value as e.g. {"name": "Wimp", "value": "15.22", "unit": "kWh"}

The text by parameter end is appended. According to JSON syntax rules it must contain a comma (,) if and only if other elements follow. Besides that white space (", " " " ",\n" "\n") may enhance human readability.

The text by parameter title will be used as such, acting as hover help text (not title) by html tradition. This text must not be NULL nor empty. When wanting no help text use jsonFreading() instead.

Parameters

indent	0..36 number of spaces to put before
name	0-terminated string naming the reading (measured value e.g.)
value	the float value
unit	0-terminated string being the value's physical unit
fractional	0..9 number of fractional digits 0: value will be taken as int
end	0-terminated string to put at the end
title	0-terminated string as help text

Returns: >=0: OK; <0: error

◆ jsonSreadingT()

int jsonSreadingT	(	uint8_t const	indent,
		char const *const	name,
		char *const	value,
		char const *const	unit,
		char *	end,
		char *	title
	)

Output a physical value as JSON {object} with name, value as String and unit.

This function puts a value given as String "15.22" e.g. in the form {"name": "Wimp", "value": "15.22", "unit": "kWh"}

The text end is appended. According to JSON syntax rules it must contain a comma (,) if and only if other elements follow. Besides that white space (", " " " ",\n" "\n") may enhance human readability.

Parameters

indent	0..36 number of spaces to put before
name	0-terminated string naming the reading (measured value e.g.)
value	the float value
unit	0-terminated string being the value's physical unit
end	0-terminated string to put at the end
title	0-terminated string as help text (NULL no title)

Returns: >=0: OK; <0: error

◆ jsonFPreadingT()

int jsonFPreadingT	(	uint8_t const	indent,
		char const *const	name,
		uint16_t const	valueLo,
		uint16_t const	valueHi,
		uint8_t	dotPos,
		char const *const	unit,
		char *	end,
		char *	title
	)

Output a physical value as JSON {object} with name, 32 bit FP value and unit.

This function puts a value given as 32 bit fixed point value in two 16 bit parts in the form {"name": "Wimp", "value": "15.22", "unit": "kWh"}. Accepting the vale as two parts solves problems with 32 bit integers or fixed point values delivered as two 16 bit Modbus registers in arbitrary order. The value is specified by the parameters valueLo, valueHi and dotPos.
With valueHi == 0 valueLo is considered as 16 bit value

The text end is appended. According to JSON syntax rules it must contain a comma (,) if and only if other elements follow. Besides that white space (", " " " ",\n" "\n") may enhance human readability.

Parameters

indent	0..36 number of spaces to put before
name	0-terminated string naming the reading (measured value e.g.)
valueLo	the least significant 16 bits of the fixed point value
valueHi	the most significant 16 bits of the fixed point value
dotPos	position where the fixed point is 0..6; 0 means integer
unit	0-terminated string being the value's physical unit
end	0-terminated string to put at the end
title	0-terminated string as help text (NULL no title)

Returns: >=0: OK; <0: error

Macros

Functions

Variables

Detailed Description

Function Documentation

◆ getQueryString()

◆ getQSparam()

◆ jsonIreading()

◆ jsonBreading()

◆ jsonBinForm()

◆ jsonFreading()

◆ jsonFreadingT()

◆ jsonSreadingT()

◆ jsonFPreadingT()