Vendor-specific diagnostic information. More...

#include <diagnosticinfo.h>

Public Member Functions
void	ua_diagnosticinfo_init (struct ua_diagnosticinfo i, struct ua_stringtable string_table)
	Initialize a diagnosticinfo. More...

void	ua_diagnosticinfo_clear (struct ua_diagnosticinfo *i)
	Clear the diagnosticinfo `i`. More...

int	ua_diagnosticinfo_compare (const struct ua_diagnosticinfo a, const struct ua_diagnosticinfo b)
	Compares the diagnosticinfos `a` and `b`. More...

int	ua_diagnosticinfo_copy (struct ua_diagnosticinfo dst, const struct ua_diagnosticinfo src)
	Copies the diagnosticinfo `src` to `dst`. More...

int	ua_diagnosticinfo_set_namespaceuri (struct ua_diagnosticinfo info, const struct ua_string namespaceuri)
	Store a namespaceuri `namespaceuri` in the diagnosticinfo `info`. More...

int	ua_diagnosticinfo_get_namespaceuri (struct ua_diagnosticinfo info, struct ua_string namespaceuri)
	Get the namespaceuri associated to the diagnosticinfo `info`. More...

int	ua_diagnosticinfo_set_symbolicid (struct ua_diagnosticinfo info, const struct ua_string symbolicid)
	Store a symbolicid `symbolicid` in the diagnosticinfo `info`. More...

int	ua_diagnosticinfo_get_symbolicid (struct ua_diagnosticinfo info, struct ua_string symbolicid)
	Get the symbolicid associated to the diagnosticinfo `info`. More...

int	ua_diagnosticinfo_set_localizedtext (struct ua_diagnosticinfo info, const struct ua_localizedtext lt)
	Store a localizedtext `localizedtext` in the diagnosticinfo `info`. More...

int	ua_diagnosticinfo_get_localizedtext (struct ua_diagnosticinfo info, struct ua_localizedtext lt)
	Get the localizedtext associated to the diagnosticinfo `info`. More...

int	ua_diagnosticinfo_set_additionalinfo (struct ua_diagnosticinfo info, const struct ua_string additionalinfo)
	Set the Additional Info field of `info` to `additonalinfo`. More...

int	ua_diagnosticinfo_get_additionalinfo (struct ua_diagnosticinfo info, struct ua_string additionalinfo)
	Get the Additonal Info field from `info`. More...

int	ua_diagnosticinfo_set_statuscode (struct ua_diagnosticinfo info, const ua_statuscode statuscode)
	Set the Statuscode field of `info` to `statuscode`. More...

int	ua_diagnosticinfo_get_statuscode (struct ua_diagnosticinfo info, ua_statuscode statuscode)
	Get the Statuscode field from `info`. More...

int	ua_diagnosticinfo_set_innerdiagnosticinfo (struct ua_diagnosticinfo info, const struct ua_diagnosticinfo inner_info)
	Set the Inner DiagnosticInfo `info` to `inner_info`. More...

int	ua_diagnosticinfo_get_innerdiagnosticinfo (struct ua_diagnosticinfo info, struct ua_diagnosticinfo inner_info)
	Get the Inner DiagnosticInfo field from `info`. More...

Data Fields
uint8_t	encoding

int32_t	symbolic_id
	The symbolic_id shall be used to identify a vendor-specific error or condition; typically the result of some server internal operation. More...

int32_t	namespace_uri
	The symbolic_id is defined within the context of a namespace. More...

int32_t	localized_text
	A vendor-specific localized text string that describes the symbolic id. More...

int32_t	locale
	The locale part of the vendor-specific localized text describing the symbolic id. More...

struct ua_string	additional_info
	Vendor-specific diagnostic information.

ua_statuscode	statuscode
	A status code provided by an underlying system. More...

struct ua_diagnosticinfo *	inner_diag_info
	The diagnostic info associated with the inner statuscode.

struct ua_stringtable *	string_table

Detailed Description

Vendor-specific diagnostic information.

The symbolic_id, namespace_uri, localized_text and locale fields are indexes in a string table which is returned in the response header. Only the index of the corresponding string in the string table is encoded. An index of −1 indicates that there is no value for the string.

DiagnosticInfo allows unlimited nesting which could result in stack overflow errors even if the message size is less than the maximum allowed. Decoders shall support at least 100 nesting levels. Decoders shall report an error if the number of nesting levels exceeds what it supports.

Member Function Documentation

void ua_diagnosticinfo_clear ( struct ua_diagnosticinfo * i )

Clear the diagnosticinfo i.

All fields direcly included are cleared. The index fields (symbolicid, namespaceuri and localizedtext) are not cleared as they are cleared when their stringtable is cleared. Still the indices themselves and the reference to the stringtable is reset, so it will not be possible to set or get index fields.

int ua_diagnosticinfo_compare	(	const struct ua_diagnosticinfo *	a,
		const struct ua_diagnosticinfo *	b
	)

Compares the diagnosticinfos a and b.

Ignores all index fields, so only additionalinfo, inner statuscode and inner diagnosticinfo are considered. Returns an integer less than, equal to, or greater than zero if a is less than, matches, or is greater than b.

int ua_diagnosticinfo_copy	(	struct ua_diagnosticinfo *	dst,
		const struct ua_diagnosticinfo *	src
	)

Copies the diagnosticinfo src to dst.

Ignores all index fields, so only additionalinfo, inner statuscode and inner diagnosticinfo are considered. Returns 0 on success or an errorcode on failure.

int ua_diagnosticinfo_get_additionalinfo	(	struct ua_diagnosticinfo *	info,
		struct ua_string *	additionalinfo
	)

Get the Additonal Info field from info.

The caller has to provide an ua_string struct where this function copies the field into. The caller is responsible to clear the additonalinfo on success. Returns 0 on success or errorcode on failure.

int ua_diagnosticinfo_get_innerdiagnosticinfo	(	struct ua_diagnosticinfo *	info,
		struct ua_diagnosticinfo *	inner_info
	)

Get the Inner DiagnosticInfo field from info.

The caller has to provide an ua_diagnosticinfo struct where this function copies the field into. The caller is responsible to clear the inner_info on success. Returns 0 on success or errorcode on failure.

int ua_diagnosticinfo_get_localizedtext	(	struct ua_diagnosticinfo *	info,
		struct ua_localizedtext *	lt
	)

Get the localizedtext associated to the diagnosticinfo info.

The localizedtext is actually stored in a stringtable inside the responseheader. So this function must not be called if the corresponding responseheader has alreaday been cleared. This will result in an address violation and may cause a crash!

Parameters

info	to get localizedtext from.
lt	the caller must provide a ua_localizedtext struct, where the localizedtext will be filled into. On success the caller is responsible to clear this localizedtext.

Returns: 0 on succuess or errorcode on failure.

int ua_diagnosticinfo_get_namespaceuri	(	struct ua_diagnosticinfo *	info,
		struct ua_string *	namespaceuri
	)

Get the namespaceuri associated to the diagnosticinfo info.

The namespaceuri is actually stored in a stringtable inside the responseheader. So this function must not be called if the corresponding responseheader has alreaday been cleared. This will result in an address violation and may cause a crash!

Parameters

info	to get namespaceuri from.
namespaceuri	the caller must provide a ua_string struct, where the namespaceuri will be filled into. On success the caller is responsible to clear this string.

Returns: 0 on succuess or errorcode on failure.

int ua_diagnosticinfo_get_statuscode	(	struct ua_diagnosticinfo *	info,
		ua_statuscode *	statuscode
	)

Get the Statuscode field from info.

The caller has to provide a pointer to an ua_statuscode this function can fill the field into. The caller is responsible to clear the statuscode on success. Returns 0 on success or errorcode on failure.

int ua_diagnosticinfo_get_symbolicid	(	struct ua_diagnosticinfo *	info,
		struct ua_string *	symbolicid
	)

Get the symbolicid associated to the diagnosticinfo info.

The symbolicid is actually stored in a stringtable inside the responseheader. So this function must not be called if the corresponding responseheader has alreaday been cleared. This will result in an address violation and may cause a crash!

Parameters

info	to get symbolicid from.
symbolicid	the caller must provide a ua_string struct, where the symbolicid will be filled into. On success the caller is responsible to clear this string.

Returns: 0 on succuess or errorcode on failure.

void ua_diagnosticinfo_init	(	struct ua_diagnosticinfo *	i,
		struct ua_stringtable *	string_table
	)

Initialize a diagnosticinfo.

Parameters

i	diagnosticinfo to initialze.
string_table	if the index fields (symbolicid, namespaceuri and localizedtext) should be useable, the initialized stringtable from the corresponding responseheader must be passed, otherwise NULL can be given here.

int ua_diagnosticinfo_set_additionalinfo	(	struct ua_diagnosticinfo *	info,
		const struct ua_string *	additionalinfo
	)

Set the Additional Info field of info to additonalinfo.

This function creates a copy of the provided string that will be cleared when info is cleared. Returns 0 on success or errorcode on failure.

int ua_diagnosticinfo_set_innerdiagnosticinfo	(	struct ua_diagnosticinfo *	info,
		const struct ua_diagnosticinfo *	inner_info
	)

Set the Inner DiagnosticInfo info to inner_info.

This function creates a copy of the provided diagnosticinfo that will be cleared when info is cleared. Returns 0 on success or errorcode on failure.

int ua_diagnosticinfo_set_localizedtext	(	struct ua_diagnosticinfo *	info,
		const struct ua_localizedtext *	lt
	)

Store a localizedtext localizedtext in the diagnosticinfo info.

The localizedtext will actually be stored in the stringtable, so the info must have been initialized with a stringtable, otherwise this function will return an error. The localizedtext can only be set once in each info.

Parameters

info	to store `localizedtext` in.
lt	a copy of this this localizedtext will be set, so it can be cleared after calling this function. This function sets both the locale and localizedtext fields in one call.

Returns: 0 on success or errorcode on failure.

int ua_diagnosticinfo_set_namespaceuri	(	struct ua_diagnosticinfo *	info,
		const struct ua_string *	namespaceuri
	)

Store a namespaceuri namespaceuri in the diagnosticinfo info.

The namespaceuri will actually be stored in the stringtable, so the info must have been initialized with a stringtable, otherwise this function will return an error. The namespaceuri can only be set once in each info.

Parameters

info	to store `namespaceuri` in.
namespaceuri	a copy of this this namespaceuri will be set, so it can be cleared after calling this function.

Returns: 0 on success or errorcode on failure.

int ua_diagnosticinfo_set_statuscode	(	struct ua_diagnosticinfo *	info,
		const ua_statuscode *	statuscode
	)

Set the Statuscode field of info to statuscode.

This function creates a copy of the provided statuscode that will be cleared when info is cleared. Returns 0 on success or errorcode on failure.

int ua_diagnosticinfo_set_symbolicid	(	struct ua_diagnosticinfo *	info,
		const struct ua_string *	symbolicid
	)

Store a symbolicid symbolicid in the diagnosticinfo info.

The symbolicid will actually be stored in the stringtable, so the info must have been initialized with a stringtable, otherwise this function will return an error. The symbolicid can only be set once in each info.

Parameters

info	to store `symbolicid` in.
symbolicid	a copy of this this symbolicid will be set, so it can be cleared after calling this function.

Returns: 0 on success or errorcode on failure.

Field Documentation

locale

The locale part of the vendor-specific localized text describing the symbolic id.

This localized text string is conveyed to the Client in the string_table parameter of the ua_responseheader parameter. The locale parameter contains the index into the string_table for this string. -1 indicates that no string is specified.

localized_text

A vendor-specific localized text string that describes the symbolic id.

The maximum length of this text string is 256 characters. This localized text string is conveyed to the Client in the string_table parameter of the ua_responseheader parameter. The localized_text parameter contains the index into the string_table for this string. -1 indicates that no string is specified.

The localized_text refers to the symbolic_id if present or the string that describes the standard StatusCode if the server provides translations. If the index is -1, the server has no translation to return and the client should use the invariant StatusCode description from the specification.

namespace_uri

The symbolic_id is defined within the context of a namespace.

This namespace is represented as a string and is conveyed to the Client in the string_table parameter of the ua_responseheader parameter. The namespaceIndex parameter contains the index into the string_table for this string. -1 indicates that no string is specified.

The namespace_uri shall not be the standard OPC UA namespace. There are no symbolic_ids provided for standard StatusCodes.

statuscode

A status code provided by an underlying system.

Many applications will make calls into underlying systems during OPC UA request processing. An OPC UA Server has the option of reporting the status from the underlying system in the diagnostic info.

symbolic_id

The symbolic_id shall be used to identify a vendor-specific error or condition; typically the result of some server internal operation.

The maximum length of this string is 32 characters. Servers wishing to return a numeric return code should convert the return code into a string and use this string as symbolic_id (e.g., "0xC0040007" or "-4").

This symbolic identifier string is conveyed to the Client in the string_table parameter of the ua_responseheader parameter. The symbolic_id parameter contains the index into the string_table for this string. -1 indicates that no string is specified.

The symbolic_id shall not contain StatusCodes. If the localized_text contains a translation for the description of a StatusCode, the symbolic_id is -1.

The documentation for this struct was generated from the following files:

C:/work/embeddedstack/src/uabase/diagnosticinfo.h
C:/work/embeddedstack/src/uabase/diagnosticinfo.c

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

Field Documentation