AXParameter and its associated functions. Contains functions for adding, removing, setting and getting parameters. The interface supports registering callback functions when a parameter value is updated. More...

Typedefs
typedef struct _AXParameter	AXParameter
	Opaque structure for the AXParameter.

typedef void()	AXParameterCallback(const gchar name, const gchar value, gpointer data)
	The typedef for a callback function registered by ax_parameter_register_callback() More...

Functions
AXParameter *	ax_parameter_new (const gchar app_name, GError *error)
	Creates a new AXParameter. More...

void	ax_parameter_free (AXParameter *parameter)
	Frees an AXParameter. More...

gboolean	ax_parameter_add (AXParameter parameter, const gchar name, const gchar initial_value, const gchar type, GError **error)
	Adds a new parameter. Returns failure if the parameter already exists. More...

gboolean	ax_parameter_remove (AXParameter parameter, const gchar name, GError **error)
	Removes a parameter. Returns FALSE if the parameter doesn't exist. More...

gboolean	ax_parameter_set (AXParameter parameter, const gchar name, const gchar value, gboolean do_sync, GError *error)
	Sets the value of a parameter. More...

gboolean	ax_parameter_get (AXParameter parameter, const gchar name, gchar value, GError error)
	Retrieves the value of a parameter. More...

GList *	ax_parameter_list (AXParameter parameter, GError *error)
	Lists all parameters for the application. The returned list and its members must be freed by the caller. Use g_free for the members and g_list_free for the list. More...

gboolean	ax_parameter_register_callback (AXParameter parameter, const gchar name, AXParameterCallback callback, gpointer userdata, GError *error)
	Registers a callback function to be run whenever a parameter value is updated. More...

void	ax_parameter_unregister_callback (AXParameter parameter, const gchar name)
	Unregisters the parameter callback function. More...

Detailed Description

AXParameter and its associated functions. Contains functions for adding, removing, setting and getting parameters. The interface supports registering callback functions when a parameter value is updated.

Parameters

For an application only one AXParameter instance should be created and shared globally.

Callback functions should avoid blocking calls, i.e. never call any axparameter method as this will very likely lead to a deadlock. In other words, there may only be one axparameter call at the time. A better way to handle updates of other parameters from a callback is to use a global data object that gets updated.

Parameter Types

These are all the parameter types possible to set with ax_parameter_add

Name	Type Format	Example	Description
Enum	`type = "enum:option 1[\|nice name 1][,option 2[\|nice name 2][,...]]"`	`type = "enum:TCPIP,HTTP,OFF"` `type = "enum:TCPIP\|Generic TCP/IP,HTTP\|Generic HTTP,OFF\|OFF"` `type = "enum:1\|Low,10\|Medium,30\|High"`	Rendered as drop-down lists in the ACAP settings interface. Options are separated by commas, and if desired, a nice value can be provided after the '\|' symbol. The nice value is displayed as the option in the ACAP settings interface.
Bool	`type = "bool:no,yes"`	`type = "bool:no,yes"`	Rendered as Checkbox in the ACAP settings interface. The first value is the unchecked value.
String	`type = "string[:maxlen=X]"`	`type = "string:maxlen=64"`	Rendered as a plain text input field for string in the ACAP settings interface. Optional maximum length parameter (maxlen) can be added. All Unicode characters are supported.
Int	`type = "int[:[maxlen=X;][min=Y;][max=Z]]"` `type = "int[:[maxlen=X;][range=[Y,][A-Z]]]"`	`type = "int"` `type = "int:min=0"` `type = "int:maxlen=3;min=0;max=100"` `type = "int:maxlen=5;range=0,1024-65535"`	Rendered as a plain text input field for integers in the ACAP settings interface. Optional specifications for maximum length (maxlen), minimum (min), and maximum (max) values. Optional range parameter can be provided with values separated by commas, or in the format min-max. Both methods include the specified minimum and maximum values in the range.
Password	`type = "password[:maxlen=X]"`	`type = "password:maxlen=64"`	Rendered as an input field for string in the ACAP settings interface. The value of the parameter is masked by '*'. Optional maximum length parameter (maxlen) can be added. The content of the parameter is readable from axparameter but not via param.cgi. Despite the masking, it is not secure as other ACAP applications can read the content.

Control Words

When creating a new parameter with ax_parameter_add, it is also possible to prepend an extra control word, that will impact how the parameter is handled. Here is a list of the possible control words.

Name	Example	Description
Hidden	`type = "hidden:string"`	Hide the parameter in the list of parameters in the ACAP settings interface.
NoSync	`type = "nosync:string"`	The changes on the parameters last until the ACAP is restarted or the parameter is reloaded.
ReadOnly	`type = "readonly:string"`	The parameter cannot be modified by axparameter nor param.cgi, and the parameter is grayed out in the ACAP settings interface.

Deprecated Parameter Types

These parameter types are deprecated and should not be used.

Name	Type Format	Example	Description
Radio	`type = "radio:option 1[\|nice name 1][,option 2[\|nice name 2][,...]]"`	`type = "radio:TCPIP,HTTP,OFF"` `type = "radio:TCPIP\|Generic TCP/IP,HTTP\|Generic HTTP,OFF\|OFF"` `type = "radio:1\|Low,10\|Medium,30\|High"`	This type works like an enum but is not supported by the ACAP Setting interface. If used, it will present as a free text box, returning an error if the entered value is not among the options.
Checkbox	`type = "checkbox:NO,YES"`	`type = "checkbox:NO,YES"`	The first value is the unchecked value, unless the first value is "YES", "ON", "TRUE", "ENABLE" or "1". It can be expressed with the short form "yes_no" or "on_off". Equivalent to type "bool:no,yes."
Text area	`type = "textarea"`	`type = "textarea"`	Plain text input field. Equivalent to type "string".
MACADDR	`type = "MACADDR"`	`type = "MACADDR"`	Plain text input field for MAC addresses with a maximum length of 17 characters. No input validation is performed. Equivalent to type "string:maxlen=17".
IP	`type = "IP" or type = "ip"`	`type = "IP" or type = "ip"`	Plain text input field for IP addresses with a maximum length of 15 characters. No input validation is performed. Equivalent to type "string:maxlen=15".
IP long	`type = "IPNAME"`	`type = "IPNAME"`	Plain text input field for IP addresses or host names with a maximum length of 64 characters. No input validation is performed. Equivalent to type "string:maxlen=64".

Deprecated Control Words

These control words are deprecated and should not be used.

Name	Example	Description
Internal	`type = "internal:string"`	Equivalent to hidden, but only for Axis internal use
Const	`type = "const:string"`	The parameter can be modified via axparameter and param.cgi, but it is grayed out in the ACAP settings interface.
WriteOnly	`type = "writeonly:string"`	The parameter can be updated can neither be read by axparameter nor by param.cgi.

Typedef Documentation

◆ AXParameterCallback

typedef void() AXParameterCallback(const gchar *name, const gchar *value, gpointer data)

The typedef for a callback function registered by ax_parameter_register_callback()

Parameters

name	Name of the updated parameter.
value	Value of the updated parameter.
data	User data to be passed to the callback.

Function Documentation

◆ ax_parameter_new()

AXParameter* ax_parameter_new	(	const gchar *	app_name,
		GError **	error
	)

Creates a new AXParameter.

Parameters

app_name	The name of the application. Must match APPNAME in package.conf. Make sure to only create one AXParameter, see more info in Parameters
error	Return location for a GError or NULL.

Returns: A new AXParameter.

Examples:: axparameterexample.c.

◆ ax_parameter_free()

void ax_parameter_free ( AXParameter * parameter )

Frees an AXParameter.

Parameters

parameter An AXParameter.

Examples:: axparameterexample.c.

◆ ax_parameter_add()

gboolean ax_parameter_add	(	AXParameter *	parameter,
		const gchar *	name,
		const gchar *	initial_value,
		const gchar *	type,
		GError **	error
	)

Adds a new parameter. Returns failure if the parameter already exists.

Parameters

parameter	An AXParameter.
name	Name of the parameter to be added.
initial_value	Initial value of the parameter. Passing NULL will set the parameter to an empty string.
type	Parameter type. Passing NULL will set the type to "string". The parameters are for plain config generation and are not validated. For other allowed types, see Parameter Types
error	Return the location for a GError or NULL.

Returns: TRUE if a parameter could be added, FALSE otherwise.

Examples:: axparameterexample.c.

◆ ax_parameter_remove()

gboolean ax_parameter_remove	(	AXParameter *	parameter,
		const gchar *	name,
		GError **	error
	)

Removes a parameter. Returns FALSE if the parameter doesn't exist.

Parameters

parameter	An AXParameter.
name	Name of the parameter to be removed.
error	Return the location for a GError or NULL.

Returns: TRUE if a parameter could be removed, FALSE otherwise.

Examples:: axparameterexample.c.

◆ ax_parameter_set()

gboolean ax_parameter_set	(	AXParameter *	parameter,
		const gchar *	name,
		const gchar *	value,
		gboolean	do_sync,
		GError **	error
	)

Sets the value of a parameter.

Parameters

parameter	An AXParameter.
name	Name of the parameter. Using only the parameter name will set a parameter in the group that belongs to the application. Using the complete path (root.Group.Name) will set any parameter in the Axis product provided that the application has proper access rights to the parameter.
value	Value to set the parameter to. Passing NULL will set the value to an empty string.
do_sync	If set to FALSE, the change won't be written to file and callbacks won't be run until a new ax_parameter_set() with do_sync set to TRUE is sent. This is recommended when updating several parameters at the same time.
error	Return the location for a GError or NULL.

Returns: TRUE if the parameter could be set, FALSE otherwise.

Examples:: axparameterexample.c.

◆ ax_parameter_get()

gboolean ax_parameter_get	(	AXParameter *	parameter,
		const gchar *	name,
		gchar **	value,
		GError **	error
	)

Retrieves the value of a parameter.

Parameters

parameter	An AXParameter.
name	Name of the parameter. Using only the parameter name will retrieve a parameter from the group that belongs to the application. Using the complete path (root.Group.Name) will retrieve any parameter in the Axis product provided that the application has proper access rights to the parameter.
value	Address of a character pointer. The function will allocate memory for the new value and set the provided pointer to the address of this location. This pointer should be freed by the caller. Use g_free to release the allocated storage when it is no longer needed.
error	Return the location for a GError or NULL.

Returns: TRUE if a parameter could be retrieved, FALSE otherwise.

Examples:: axparameterexample.c.

◆ ax_parameter_list()

GList* ax_parameter_list	(	AXParameter *	parameter,
		GError **	error
	)

Lists all parameters for the application. The returned list and its members must be freed by the caller. Use g_free for the members and g_list_free for the list.

Parameters

parameter	An AXParameter.
error	Return the location for a GError or NULL.

Returns: A GList of allocated strings or NULL if empty.

Examples:: axparameterexample.c.

◆ ax_parameter_register_callback()

gboolean ax_parameter_register_callback	(	AXParameter *	parameter,
		const gchar *	name,
		AXParameterCallback *	callback,
		gpointer	userdata,
		GError **	error
	)

Registers a callback function to be run whenever a parameter value is updated.

Parameters

parameter	An AXParameter.
name	Name of the parameter.
callback	The callback function to be run when the parameter is updated.
userdata	Userdata to be passed to the callback or NULL.
error	Return the location for a GError or NULL.

Returns: TRUE if a callback could be registered, FALSE otherwise.

Examples:: axparameterexample.c.

◆ ax_parameter_unregister_callback()

void ax_parameter_unregister_callback	(	AXParameter *	parameter,
		const gchar *	name
	)

Unregisters the parameter callback function.

Parameters

parameter	An AXParameter.
name	Name of the parameter.

Typedefs

Functions

Detailed Description

Parameters

Parameter Types

Control Words

Deprecated Parameter Types

Deprecated Control Words

Typedef Documentation

◆ AXParameterCallback

Function Documentation

◆ ax_parameter_new()

◆ ax_parameter_free()

◆ ax_parameter_add()

◆ ax_parameter_remove()

◆ ax_parameter_set()

◆ ax_parameter_get()

◆ ax_parameter_list()

◆ ax_parameter_register_callback()

◆ ax_parameter_unregister_callback()