weCGIajax.c File Reference

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

#include "weCGIajax.h"

Functions
int	getQSparam (char const *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 [QS_MAX_VAL_LEN]
	to be used for actual parameter
char	queryString [QS_MAX_STRING_LEN]
	holding the query string
char const *	requestMethod
	to hold (environment's) REQUEST_METHOD

Detailed Description

Functions and values for Web interfaces with AJAX, CGI etc.

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

Revision history

Rev. 257 14.07.2024
Rev.  82  14.12.2017 : new
Rev. 187  14.10.2018 : minor typos

cross-compile by:

arm-linux-gnueabihf-gcc -DMCU=BCM2837 -I./include -c -o weRasp/weCGIajax.o weRasp/weCGIajax.c

This is a (basic) library to support CGI programs written in C to be used under a web sever – as e.g. an Apache 2.4 on a Pi for hometersControl.

For documentation see the include file weCGIajax.h

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