Structured data callback API

The structured data interface is a callback-based interface used to access parameters passed to a module. More...

Files
file	swdataapi.h
	Header file defining the Structured data callback API.
file	swdevdata.h
	Header file defining the Structured data callback API.

Data Structures
struct	sw_datum
	Structured data instance type. More...
struct	sw_data_api
	A structure containing callback functions for structured data access. More...
struct	sw_data_match
	A structure used for extracting multiple values from an array or dictionary in one go. More...

Macros
#define	SW_DATUM_INVALID   {SW_DATUM_TYPE_INVALID}
	Auto/static initializer for sw_datum invalid values. More...
#define	SW_DATUM_NOTHING   {SW_DATUM_TYPE_NOTHING}
	Auto/static initializer for sw_datum nothing values. More...
#define	SW_DATUM_NULL   {SW_DATUM_TYPE_NULL}
	Auto/static initializer for sw_datum null values. More...
#define	SW_DATUM_INTEGER(_int)    {SW_DATUM_TYPE_INTEGER, 0,0,0, NULL, 0, { (void *)((intptr_t)(_int)) }}
	Auto/static initializer for sw_datum integer values. More...
#define	SW_DATUM_BOOLEAN(_bool)    {SW_DATUM_TYPE_BOOLEAN, 0,0,0, NULL, 0, { (void *)((intptr_t)(_bool)) }}
	Auto/static initializer for sw_datum boolean values. More...
#define	SW_DATUM_STRING(_str)    {SW_DATUM_TYPE_STRING, 0,0,0, NULL, sizeof("" _str "") - 1, {(const void *)("" _str "")}}
	Auto/static initializer for sw_datum string values. More...
#define	SW_DATUM_NAME(_str)    {SW_DATUM_TYPE_STRING, SW_DATUM_SUBTYPE_NAME_STRING,0,0, NULL, sizeof("" _str "") - 1, {(const void *)("" _str "")}}
	Auto/static initializer for sw_datum name values. More...
#define	SW_DATUM_ARRAY(_array, _len)    {SW_DATUM_TYPE_ARRAY, 0,0,0, NULL, (_len), { (void *)(_array) }}
	Auto/static initializer for sw_datum array values. More...
#define	SW_DATUM_STACK(_stack, _len)    {SW_DATUM_TYPE_ARRAY, SW_DATUM_SUBTYPE_STACK_ARRAY,0,0, NULL, (_len), { (void *)(_stack) }}
	Auto/static initializer for sw_datum stack values. More...
#define	SW_DATUM_DICT(_dict, _len)    {SW_DATUM_TYPE_DICT, 0,0,0, NULL, (_len), { (void *)(_dict) }}
	Auto/static initializer for sw_datum dictionary values. More...
#define	SW_DATA_ARRAY_LENGTH(_array)   (sizeof(_array) / sizeof((_array)[0]))
	Count the members of a local data array. Useful for statically initialising arrays.
#define	SW_DATA_DICT_LENGTH(_dict)   (SW_DATA_ARRAY_LENGTH(_dict) >> 1)
	Count the members of a local data dictionary. Useful for statically initialising dictionaries.
#define	SW_DATUM_0_0F   0
	A constant of real value 0.0 for use with the SW_DATUM_FLOAT() static initializer.
#define	SW_DATUM_1_0F   1065353216
	A constant of real value 1.0 for use with the SW_DATUM_FLOAT() static initializer.
#define	SW_DATUM_0_5F   1056964608
	A constant of real value 0.5 for use with the SW_DATUM_FLOAT() static initializer.
#define	SW_DATUM_FLOAT(_real)    {SW_DATUM_TYPE_FLOAT, 0,0,0, NULL, 0, { (void *)((intptr_t)(_real)) }}
	Auto/static initializer for sw_datum float values, for use with the defined constants that can be used with this initializer. More...
#define	SW_DATUM_REQUIREDKEY(type, name)    {SW_DATUM_BIT_##type,SW_DATUM_STRING(""name""),SW_DATUM_NOTHING}
	A key initializer macro to help build the sw_data_match structure. More...
#define	SW_DATUM_OPTIONALKEY(type, name)    {SW_DATUM_BIT_##type|SW_DATUM_BIT_NOTHING,SW_DATUM_STRING(""name""),SW_DATUM_NOTHING}
	A key initializer macro to help build the sw_data_match structure. More...

Typedefs
typedef HqnResult	sw_data_result
	Type of return values from sw_data_api functions. More...
typedef struct sw_data_api	sw_data_api
	Type definition for the structured data interface implementation.
typedef struct sw_datum	sw_datum
	Structured data instance type. More...
typedef struct sw_data_match	sw_data_match
	A structure used for matching multiple datum entries in one go.
typedef struct sw_data_iterator	sw_data_iterator
	An opaque type used by the data provider to iterate data structures.

Enumerations
enum	{   SW_DATA_API_VERSION_20070525 = 2 , SW_DATA_API_VERSION_20070620 , SW_DATA_API_VERSION_20071111 , SW_DATA_API_VERSION_20090415 ,   SW_DATA_API_VERSION_20130321 , SW_DATA_API_VERSION_20181206 }
	Version numbers defined for the structured data API. More...
enum	SW_DATA_RESULT {   SW_DATA_OK = HQN_RESULT_SUCCESS , SW_DATA_FINISHED = -1 , SW_DATA_ERROR = 1 , SW_DATA_ERROR_TYPECHECK ,   SW_DATA_ERROR_RANGECHECK , SW_DATA_ERROR_INVALIDACCESS , SW_DATA_ERROR_UNDEFINED , SW_DATA_ERROR_MEMORY ,   SW_DATA_ERROR_SYNTAX }
	Return values from sw_data_api functions. More...
enum	SW_DATUM_TYPES {   SW_DATUM_TYPE_NOTHING = 0 , SW_DATUM_TYPE_NULL , SW_DATUM_TYPE_BOOLEAN , SW_DATUM_TYPE_INTEGER ,   SW_DATUM_TYPE_FLOAT , SW_DATUM_TYPE_STRING , SW_DATUM_TYPE_ARRAY , SW_DATUM_TYPE_DICT ,   SW_DATUM_TYPE_BLOB , SW_DATUM_TYPE_INVALID = 31 }
	Data types for structured data. More...
enum	SW_DATUM_BITS {   SW_DATUM_BIT_NOTHING = 1u << SW_DATUM_TYPE_NOTHING , SW_DATUM_BIT_NULL = 1u << SW_DATUM_TYPE_NULL , SW_DATUM_BIT_BOOLEAN = 1u << SW_DATUM_TYPE_BOOLEAN , SW_DATUM_BIT_INTEGER = 1u << SW_DATUM_TYPE_INTEGER ,   SW_DATUM_BIT_FLOAT = 1u << SW_DATUM_TYPE_FLOAT , SW_DATUM_BIT_STRING = 1u << SW_DATUM_TYPE_STRING , SW_DATUM_BIT_ARRAY = 1u << SW_DATUM_TYPE_ARRAY , SW_DATUM_BIT_DICT = 1u << SW_DATUM_TYPE_DICT ,   SW_DATUM_BIT_BLOB = 1u << SW_DATUM_TYPE_BLOB , SW_DATUM_BIT_INVALID = 1u << SW_DATUM_TYPE_INVALID }
	Data type bits. More...
enum	SW_DATUM_SUBTYPES { SW_DATUM_SUBTYPE_NONE = 0 , SW_DATUM_SUBTYPE_NAME_STRING = 1 , SW_DATUM_SUBTYPE_STACK_ARRAY = 1 }
	Data subtypes for structured data. More...

Functions
HqnResult	swdata_result_translate (sw_data_result result)
	Translate a data API-specific error code to a generic HqnResult error code. More...
void	sw_datum_get_integer (const sw_datum *datum, int value, sw_data_result result)
	A utility macro to extract an integer value from a sw_datum object of integer or float type. More...
void	sw_datum_get_real (const sw_datum *datum, float_or_double_specifier type, float_or_double value, sw_data_result result)
	A utility macro to extract a real value from a sw_datum object of integer or float type. More...

Detailed Description

The structured data interface is a callback-based interface used to access parameters passed to a module.

Some APIs and callback functions are provided with a sw_datum or sw_datum pointer represent structured data, usually for parameters that the function or API may read. A sw_datum can represent a boolean, integer, float, string, name, array, stack, dictionary, BLOB (i.e., a file), a null object or nothing at all. It can represent a PostScript object and act as a proxy for it to allow manipulation of PostScript state; it can represent and act as a proxy for a DEVICEPARAM or a JSON object or another structured data object; or it can be an independent module-created 'raw' value. A uniform set of functions allow navigation, matching, comparison, manipulation and retention of structured data objects, regardless of the object source that they proxy or represent.

Structured object sw_datum values are examined, matched and manipulated through the sw_data_api interface. When a sw_datum is presented to a callback or API, it should be accompanied by a sw_data_api pointer, which is the API that should be used to access this structured data object. Do not mix and match sw_datum objects from one source with sw_data_api pointers from another source: they may not work, and may crash the application. Always use the sw_data_api pointer supplied with a sw_datum object to manipulate and examine it. You may use 'raw' sw_datum objects with any sw_data_api pointer, however.

A sw_datum object contains a type, a sub-type, flags, an owner (the data proxy that created it), a length (used for strings, arrays, and dictionaries), and a variant member with the value of the data object. The type, sub-type, flags, length, and variant member may be read directly by the client. For composite objects (arrays, dictionaries, BLOBs and their sub-types), the variant member is opaque, and must be accessed through data API functions.

The data API provides functions to:

• Read values from an array or stack datum (sw_data_api::get_indexed()).
• Write values to an array or stack datum (sw_data_api::set_indexed()).
• Read values from a dictionary datum (sw_data_api::get_keyed()).
• Write values to a dictionary datum (sw_data_api::set_keyed()).
• Match a set of expected keys against a dictionary datum, extracting the values (sw_data_api::match()).
• Iterate over the values in an array or dictionary datum (sw_data_api::iterate_begin() to start iterating, sw_data_api::iterate_next() to get values from an iteration, sw_data_api::iterate_end() to finish an iteration).
• Compare datums (sw_data_api::equal()).
• Open a BLOB datum for reading or writing (sw_data_api::open_blob()).
• Push and pop an array datum as if it were stack (sw_data_api::push() and sw_data_api::pop()).
• Retain and release datum references to control their accessibility lifetimes (sw_data_api::retain() and sw_data_api::release()).

A number of auto and static initializer macros exist to construct raw datum objects from scratch. These are useful as values to set in datum parameters, and as values for matches.

A utility function, swdata_result_translate(), is provided to translate data API-specific result values to generic HqnResult result codes that can be passed to the RIP or as return values for other APIs.

A data API pointer must be discovered using RDR using class RDR_CLASS_API and type RDR_API_DATA before the API methods are used. The data API is automatically registered when the Harlequin RIP is started. It is deregistered when the Harlequin RIP is shutdown.

Macro Definition Documentation

SW_DATUM_ARRAY

#define SW_DATUM_ARRAY	(		_array,
			_len
	)		{SW_DATUM_TYPE_ARRAY, 0,0,0, NULL, (_len), { (void *)(_array) }}

Auto/static initializer for sw_datum array values.

For example:

sw_datum elements[] = {SW_DATUM_INTEGER(5), SW_DATUM_NAME("Five")} ;
sw_datum array = SW_DATUM_ARRAY(&elements[0], SW_DATA_ARRAY_LENGTH(elements)) ; 

It is also possible to initialise the array and contents simultaneously, if you are careful about the array length:

sw_datum array[3] = {
  SW_DATUM_ARRAY(array+1, 2),   // The array datum
  SW_DATUM_INTEGER(5),          // The first element of the array
  SW_DATUM_NAME("Five")} ;

Dynamically allocated datums are most easily initialised using a static datum as a template, e.g.:

sw_datum * datum_from_intarray(int * intarray, int length)
{
  static sw_datum num = SW_DATUM_INTEGER(0) ;     // integer template
  static sw_datum arr = SW_DATUM_ARRAY(NULL, 0) ; // array template
  sw_datum * datums = malloc((length+1) * sizeof(sw_datum)) ;
  int i ;
  datums[0] = arr ;     // initialise using template
  datums[0].length = length ;
  datums[0].value.opaque = &datums[1] ;
  for (i = 0 ; i < length ; ++i) {
    datums[i+1] = num ; // initialise using template
    datums[i+1].value.integer = intarray[i] ;
  }
  return datums ;
}

SW_DATUM_BOOLEAN

#define SW_DATUM_BOOLEAN

(

_bool

)

{SW_DATUM_TYPE_BOOLEAN, 0,0,0, NULL, 0, { (void *)((intptr_t)(_bool)) }}

Auto/static initializer for sw_datum boolean values.

For example:

sw_datum bool = SW_DATUM_BOOLEAN(TRUE) ; 

SW_DATUM_DICT

#define SW_DATUM_DICT	(		_dict,
			_len
	)		{SW_DATUM_TYPE_DICT, 0,0,0, NULL, (_len), { (void *)(_dict) }}

Auto/static initializer for sw_datum dictionary values.

For example:

sw_datum entries[] = {SW_DATUM_NAME("Key1"), SW_DATUM_STRING("Value 1"),
                      SW_DATUM_NAME("Key2"), SW_DATUM_INTEGER(2)} ;
sw_datum dict = SW_DATUM_DICT(&entries[0], SW_DATA_DICT_LENGTH(entries)) ;

SW_DATUM_FLOAT

#define SW_DATUM_FLOAT

(

_real

)

{SW_DATUM_TYPE_FLOAT, 0,0,0, NULL, 0, { (void *)((intptr_t)(_real)) }}

Auto/static initializer for sw_datum float values, for use with the defined constants that can be used with this initializer.

For example:

sw_datum half = SW_DATUM_FLOAT(SW_DATUM_0_5F) ; 

SW_DATUM_INTEGER

#define SW_DATUM_INTEGER

(

_int

)

{SW_DATUM_TYPE_INTEGER, 0,0,0, NULL, 0, { (void *)((intptr_t)(_int)) }}

Auto/static initializer for sw_datum integer values.

For example:

sw_datum count = SW_DATUM_INTEGER(4) ; 

SW_DATUM_INVALID

#define SW_DATUM_INVALID   {SW_DATUM_TYPE_INVALID}

Auto/static initializer for sw_datum invalid values.

For example:

sw_datum invalid = SW_DATUM_INVALID ; 

This type is more likely to be returned by a match call than created by module code.

SW_DATUM_NAME

#define SW_DATUM_NAME

(

_str

)

{SW_DATUM_TYPE_STRING, SW_DATUM_SUBTYPE_NAME_STRING,0,0, NULL, sizeof("" _str "") - 1, {(const void *)("" _str "")}}

Auto/static initializer for sw_datum name values.

Names are a subtype of strings, and use the same value and length fields.

For example:

sw_datum key = SW_DATUM_NAME("Encoding") ; 

SW_DATUM_NOTHING

#define SW_DATUM_NOTHING   {SW_DATUM_TYPE_NOTHING}

Auto/static initializer for sw_datum nothing values.

For example:

sw_datum nothing = SW_DATUM_NOTHING ; 

This type is more likely to be returned by a match call than created by module code.

SW_DATUM_NULL

#define SW_DATUM_NULL   {SW_DATUM_TYPE_NULL}

Auto/static initializer for sw_datum null values.

For example:

sw_datum null = SW_DATUM_NULL ; 

SW_DATUM_OPTIONALKEY

#define SW_DATUM_OPTIONALKEY	(		type,
			name
	)		{SW_DATUM_BIT_##type|SW_DATUM_BIT_NOTHING,SW_DATUM_STRING(""name""),SW_DATUM_NOTHING}

A key initializer macro to help build the sw_data_match structure.

For example:

static sw_data_match match[] = {
  SW_DATUM_OPTIONALKEY(BOOLEAN,"Verbose"),
  SW_DATUM_REQUIREDKEY(STRING, "Name"),
} ;

Note the shortening of the type field for simplicity in the usual case - the macro prepends SW_DATUM_BIT_ to this. Consequently, if more than one type is acceptable then others must be ORed in full, e.g.:

SW_DATUM_OPTIONALKEY(FLOAT|SW_DATUM_BIT_INTEGER, "Number"),

SW_DATUM_REQUIREDKEY

#define SW_DATUM_REQUIREDKEY	(		type,
			name
	)		{SW_DATUM_BIT_##type,SW_DATUM_STRING(""name""),SW_DATUM_NOTHING}

A key initializer macro to help build the sw_data_match structure.

For example:

static sw_data_match match[] = {
  SW_DATUM_REQUIREDKEY(STRING, "Name"),
} ;

Note the shortening of the type field for simplicity in the usual case - the macro prepends SW_DATUM_BIT_ to this. Consequently, if more than one type is acceptable then others must be ORed in full, e.g.:

SW_DATUM_REQUIREDKEY(FLOAT|SW_DATUM_BIT_INTEGER, "Number"),

SW_DATUM_STACK

#define SW_DATUM_STACK	(		_stack,
			_len
	)		{SW_DATUM_TYPE_ARRAY, SW_DATUM_SUBTYPE_STACK_ARRAY,0,0, NULL, (_len), { (void *)(_stack) }}

Auto/static initializer for sw_datum stack values.

This is unlikely to be useful.

sw_datum elements[] = {SW_DATUM_STRING("Just one")} ;
sw_datum stack = SW_DATUM_STACK(&elements, SW_DATA_ARRAY_LENGTH(elements)) ;

SW_DATUM_STRING

#define SW_DATUM_STRING

(

_str

)

{SW_DATUM_TYPE_STRING, 0,0,0, NULL, sizeof("" _str "") - 1, {(const void *)("" _str "")}}

Auto/static initializer for sw_datum string values.

For example:

sw_datum text = SW_DATUM_STRING("Some text") ; 

Typedef Documentation

sw_data_result

typedef HqnResult sw_data_result

Type of return values from sw_data_api functions.

This is a subclass of HqnResult that also supports some specific extra error codes generated by sw_data_api functions (declared as the SW_DATA_RESULT enumeration). Before assigning to values of HqnResult type or any of its other subclasses, sw_data_result values must be converted to change the data API specific values to HQN_RESULT_SUCCESS or a monitor UID error code greater than MON_CLASS_ERROR. This can be done by calling the function swdata_result_translate().

sw_datum

typedef struct sw_datum sw_datum

Structured data instance type.

Modules may create raw sw_datum values, including arrays and dictionaries (associative arrays), but must ensure that all fields are initialised properly. Static initializers are provided which can be used to initialise local datums, which can then be used directly or copied to initialise dynamically allocated datums.

For a raw sw_datum array of n elements, value.opaque points to a contiguous array of n sw_datum items. For a dictionary of n key/value pairs it points to a contiguous array of n * 2 sw_datum items. (Raw stacks are not useful because their size cannot be safely changed, so push and pop are not supported.) The owner field must be set to NULL for raw datums created by a module, and should never be modified for data provided to the module. Note however it is possible for a module to implement the sw_data_api itself and hence build 'owned' datums.

Modules may treat all arrays and dictionaries as opaque and use the api access methods even for values it has created itself. However, arrays and dictionaries with a non-NULL owner are always opaque and their contents can only be accessed using the API.

Enumeration Type Documentation

anonymous enum

anonymous enum

Version numbers defined for the structured data API.

Enumerator
SW_DATA_API_VERSION_20070525	Obsolete as of 20070620.
SW_DATA_API_VERSION_20070620	Obsolete as of 20071111.
SW_DATA_API_VERSION_20071111	Obsolete as of 20090415.
SW_DATA_API_VERSION_20090415	Obsolete as of 20130321.
SW_DATA_API_VERSION_20130321	Deprecated as of 20181206.
SW_DATA_API_VERSION_20181206	Current version.

SW_DATA_RESULT

enum SW_DATA_RESULT

Return values from sw_data_api functions.

All error values are guaranteed to be greater than or equal to SW_DATA_ERROR. Errors may be implementation dependent so all return values greater than or equal to SW_DATA_ERROR must be treated as errors, even if not explicitly listed as a method return value.

Enumerator
SW_DATA_OK	Return value for successful operations.
SW_DATA_FINISHED	An iterator has finished. This is not an error.
SW_DATA_ERROR	Non-specific error, also minimum error value. Please avoid using this if possible.
SW_DATA_ERROR_TYPECHECK	Type of value or key was incorrect.
SW_DATA_ERROR_RANGECHECK	Range of value or index was incorrect.
SW_DATA_ERROR_INVALIDACCESS	Return value for disallowed set or get.
SW_DATA_ERROR_UNDEFINED	A key was not found in an association.
SW_DATA_ERROR_MEMORY	Memory was exhausted.
SW_DATA_ERROR_SYNTAX	Programming error (e.g. invalid parameters).

SW_DATUM_BITS

enum SW_DATUM_BITS

Data type bits.

These are used to select allowable types in the sw_data_match structure's type_mask field.

Enumerator
SW_DATUM_BIT_NOTHING	Match mask bit for SW_DATUM_TYPE_NOTHING
SW_DATUM_BIT_NULL	Match mask bit for SW_DATUM_TYPE_NULL
SW_DATUM_BIT_BOOLEAN	Match mask bit for SW_DATUM_TYPE_BOOLEAN
SW_DATUM_BIT_INTEGER	Match mask bit for SW_DATUM_TYPE_INTEGER
SW_DATUM_BIT_FLOAT	Match mask bit for SW_DATUM_TYPE_FLOAT
SW_DATUM_BIT_STRING	Match mask bit for SW_DATUM_TYPE_STRING
SW_DATUM_BIT_ARRAY	Match mask bit for SW_DATUM_TYPE_ARRAY
SW_DATUM_BIT_DICT	Match mask bit for SW_DATUM_TYPE_DICT
SW_DATUM_BIT_BLOB	Match mask bit for SW_DATUM_TYPE_BLOB
SW_DATUM_BIT_INVALID	Match mask bit indicating no match

SW_DATUM_SUBTYPES

enum SW_DATUM_SUBTYPES

Data subtypes for structured data.

These values allow data types to be subtyped. Strings and arrays are subtyped, to indicate names and stacks respectively.

Enumerator
SW_DATUM_SUBTYPE_NONE	Types usually have no subtype.
SW_DATUM_SUBTYPE_NAME_STRING	String subtype that represents Postscript NAMEs or similar atomic tokens
SW_DATUM_SUBTYPE_STACK_ARRAY	Array subtype that represents a Postscript stack or similar list

SW_DATUM_TYPES

enum SW_DATUM_TYPES

Data types for structured data.

These definitions closely follow Postscript use, but also support other data hierarchy forms.

Data types are divided into three categories.

The data types SW_DATUM_TYPE_NOTHING and SW_DATUM_TYPE_INVALID are pseudo-types which are used by the RIP to indicate certain conditions have occurred, such as missing or invalid data in data matches. They will not be retrieved through the sw_data_api getter functions and cannot be stored through the sw_data_api setter functions.

Transparent data types are SW_DATUM_TYPE_NULL, SW_DATUM_TYPE_BOOLEAN, SW_DATUM_TYPE_INTEGER, SW_DATUM_TYPE_FLOAT, and SW_DATUM_TYPE_STRING. Values of these types can be examined directly, by looking at the appropriate field of the sw_datum::value union. The null type has no union branch, it is a type with a singleton value. Strings are not zero-terminated, so the sw_datum::length field must be used to delimit their size.

Opaque data types are SW_DATUM_TYPE_ARRAY, SW_DATUM_TYPE_DICT, and SW_DATUM_TYPE_BLOB. Datum of these types must only be accessed through the sw_data_api method functions. In the case of arrays and dictionaries (associative arrays), the length can be examined to determine the array length or the maximum storage space in the dictionary respectively.

Enumerator
SW_DATUM_TYPE_NOTHING	No datum present.
SW_DATUM_TYPE_NULL	The distinguished null value.
SW_DATUM_TYPE_BOOLEAN	TRUE or FALSE values.
SW_DATUM_TYPE_INTEGER	A type for integer values.
SW_DATUM_TYPE_FLOAT	Single-precision floating point numbers.
SW_DATUM_TYPE_STRING	A contiguous byte array.
SW_DATUM_TYPE_ARRAY	An opaque type for indexed arrays.
SW_DATUM_TYPE_DICT	An opaque type for associative arrays.
SW_DATUM_TYPE_BLOB	An opaque type for streamed or mapped data.
SW_DATUM_TYPE_INVALID	A match value's type was incorrect. This should have a higher value than any other type number.

Function Documentation

sw_datum_get_integer()

void sw_datum_get_integer	(	const sw_datum *	datum,
		int	value,
		sw_data_result	result
	)

A utility macro to extract an integer value from a sw_datum object of integer or float type.

This prototype exists for Splint and Doxygen. There is no actual function of this name.

Parameters

[in]	datum	The object from which to extract an integer.
[out]	value	The returned integer value.
[out]	result	The return value of the macro.

Return values

SW_DATA_OK	Success. The value entry is filled with the integer value of the datum.
SW_DATA_ERROR_RANGECHECK	Returned if the datum value is not exactly representable as an integer.
SW_DATA_ERROR_TYPECHECK	Returned if the datum value is not an integer or a real.
SW_DATA_ERROR_INVALIDACCESS	Returned if the datum is invalid.

sw_datum_get_real()

void sw_datum_get_real	(	const sw_datum *	datum,
		float_or_double_specifier	type,
		float_or_double	value,
		sw_data_result	result
	)

A utility macro to extract a real value from a sw_datum object of integer or float type.

This prototype exists for Splint and Doxygen. There is no actual function of this name.

Parameters

[in]	datum	The object from which to extract a value.
[in]	type	The required type of value - this MUST be float or double.
[out]	value	The real value extracted from the sw_datum. This must be a float or double.
[out]	result	The return value of the extraction.

Return values

SW_DATA_OK	Success. The value entry is filled with the real value of the datum.
SW_DATA_ERROR_TYPECHECK	Returned if the datum value is not an integer or a real.
SW_DATA_ERROR_INVALIDACCESS	Returned if the datum is invalid.

swdata_result_translate()

HqnResult swdata_result_translate

(

sw_data_result

result

)

Translate a data API-specific error code to a generic HqnResult error code.

Parameters

[in]

result

One of the SW_DATA_RESULT values, or an error value greater than MON_CLASS_ERROR.

Returns

Either HQN_RESULT_SUCCESS, or an error value greater than MON_CLASS_ERROR.