[To main guide]

General Functions

flml_is_message_complete
flml_get_last_error

Functions for initialising the parsing

flml_parse_message
flml_set_tag_info_root

Functions for setting the base read location

flml_set_location
flml_restore_location

Functions for reading parameters

flml_is_present
flml_read_void
flml_read_boolean
flml_read_integer
flml_read_float
flml_read_float
flml_read_ipv4
flml_read_ipv6
flml_read_date
flml_read_time
flml_read_oid
flml_read_ascii
flml_read_ascii_dynamic
flml_read_const
flml_read_unicode
flml_read_unicode_dynamic
flml_read_bytes
flml_read_bytes_dynamic
flml_read_embedded
flml_read_embedded_dynamic
flml_read_union
flml_read_enumerated_union

Functions for cleaning up after reading

flml_release

Functions to support encoding

flml_encode_float
flml_encode_get_ascii_length
flml_encode_ascii
flml_encode_get_unicode_length
flml_encode_unicode
flml_encode_get_bytes_length
flml_encode_bytes
flml_is_well_formed

Functions to aid debugging

flml_debug_display_parse_info

int flml_is_message_complete(

const char *ap_message, int a_length );

Description

Tests whether the message is complete by using the technique of looking for an unmatched closing brace.

Depending on the protocol being used other methods may be used to tell whether a message is complete, in which case this function need not be used.

This function may be called before calling flml_parse_message.

Returns

The length of the message if complete, or -1 if incomplete.

Parameters

ap_message

Pointer to the buffer containing the message

a_length

The length of the buffer containing the message.

elml_error flml_get_last_error(

slml_parse_ctrl *ap_parse_ctrl );

Description

Returns the lastest error and resets the stored error condition to ELML_OK.

Returns

The last error code. See elml_error for more information.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

tlms_bool flml_parse_message(

slml_parse_ctrl *ap_parse_ctrl, const char *ap_message, int a_length );

Description

Parses the message. This builds internal data structures that the parameter reading functions use to read the parameters in the message.

The function also initialises the parse control block pointed to by ap_parse_ctrl.

flml_release must be called to release the memory allocated by this function once all the interaction with the message has been completed.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when this function is called.

ap_message

Pointer to the buffer containing the message

a_length

The length of the buffer containing the message.

void flml_set_tag_info_root(

slml_parse_ctrl *ap_parse_ctrl, slml_tag_info *ap_tag_info );

Description

Specifies where the tag information generated by the lumas2tags program is stored. lumas2tags is an optional extra program and its use is not required to use the library. However, it is a useful way of detecting tag specification errors that might be in your code.

See the Lumas Home Page for more information.

Returns

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ap_tag_info

tlms_bool flml_set_location(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, slml_location *ap_old_location );

Description

Sets the base read location in the tree from which subsequent parameter specifications are made. If / is the first character then the specification is addressed from the root of the message tree, otherwise it is addressed from the current location. By analogy to file directories, it is similar to the cd command.

Returns

The previously set read location.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ap_old_location

Pointer to where the current location (the location before the set_location is effected) can be stored. This parameter can be NULL if this information is not required.

slml_location flml_restore_location(

slml_parse_ctrl *ap_parse_ctrl, slml_location a_restore_location );

Description

Restores the read location to a previous location resturned from any of the other location setting functions.

Returns

The previously set read location.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

a_restore_location

The message location that is to be restored. The information in this parameter must have been populated by a previous call to flml_set_location.

tlms_bool flml_is_present(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance );

Description

Checks to see whether the named parameter is present. It is NOT necessary to test whether a parameter is present before attempting to read it using the parameter reading functions (they will return ELML_PARAMETER_NOT_FOUND or an associated error if the parameter is not found).

Returns

TRUE if the requested parameter, FALSE otherwise. Additional information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

tlms_bool flml_read_void(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance );

Description

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

tlms_bool flml_read_boolean(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, int *ap_boolean );

Description

Reads the boolean value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ap_boolean

Pointer to the variable that is to receive the read boolean.

tlms_bool flml_read_integer(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, int *ap_integer );

Description

Reads the integer value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ap_integer

Pointer to an integer variable that is to receive the read integer.

tlms_bool flml_read_float(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, tlms_float *ap_float );

Description

Reads the float value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ap_float

Pointer to a float variable that is to receive the read float.

tlms_bool flml_read_float(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, tlms_double *ap_double );

Description

Reads the float value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ap_double

Pointer to a double variable that is to receive the read double.

tlms_bool flml_read_ipv4(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, unsigned char ac_addr[4] );

Description

Reads the IPv4 address value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ac_addr

Where the bytes corresponding to the address are to be placed.

tlms_bool flml_read_ipv6(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, unsigned char ac_addr[16] );

Description

Reads the IPv6 address value associated with the named parameter.

This function is currently not implemented.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ac_addr

Where the bytes corresponding to the address are to be placed.

tlms_bool flml_read_date(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, tlms_date *ap_date );

Description

Reads the date value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ap_date

Pointer to the date structure that is to receive the read date.

tlms_bool flml_read_time(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, tlms_time *ap_time );

Description

Reads the time value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ap_time

Pointer to the time structure that is to receive the read time.

tlms_bool flml_read_oid(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, tlms_oid *ap_oid );

Description

Reads the Object Identifier value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ap_oid

Pointer to the Object Identifier structure that is to receive the read OID.

tlms_bool flml_read_ascii(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, char ac_string[], int a_max_length );

Description

Reads the unquoted or quoted ascii string value associated with the named parameter.

If the function indicates that the output array is too small, an attempt can be made to read the message using flml_read_ascii_dynamic.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ac_string

Where the read string is to be placed.

a_max_length

The maximimum length of string that the ac_string parameter can hold.

tlms_bool flml_read_ascii_dynamic(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, char **app_string );

Description

Reads the unquoted or quoted ascii string value associated with the named parameter into an array that is dynamically allocated by the library.

It is the responsibility of the calling code to free this memory when the information is no longer required.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

app_string

The function returns the address of the dynamically allocated string in the location pointed to by this parameter. It is the responsibility of the calling function to release the allocated memory when it is no longer required.

tlms_bool flml_read_const(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, char ac_string[], int a_max_length );

Description

Reads the const value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ac_string

Where the read string is to be placed.

a_max_length

The maximimum length of string that the ac_string parameter can hold.

tlms_bool flml_read_unicode(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, tlms_unicode ac_string[], int a_max_length );

Description

Reads the unicode string value associated with the named parameter.

If the function indicates that the output array is too small, an attempt can be made to read the message using flml_read_unicode_dynamic.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ac_string

Where the read string is to be placed.

a_max_length

The maximimum length of string that the ac_string parameter can hold.

tlms_bool flml_read_unicode_dynamic(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, tlms_unicode **app_string );

Description

Reads the unicode string value associated with the named parameter into an array that is dynamically allocated by the library.

It is the responsibility of the calling code to free this memory when the information is no longer required.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

app_string

The function returns the address of the dynamically allocated string in the location pointed to by this parameter. It is the responsibility of the calling function to release the allocated memory when it is no longer required.

tlms_bool flml_read_bytes(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, char ac_bytes[], int a_max_length, int *ap_result_length );

Description

Reads the bytes value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ac_bytes

Pointer to where the bytes data is to be placed.

a_max_length

The maximum number of bytes that can be stored in ac_bytes.

ap_result_length

Pointer to where the number of bytes contained in ac_bytes should be stored on return.

tlms_bool flml_read_bytes_dynamic(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, char **app_bytes, int *ap_result_length );

Description

Reads the bytes value associated with the named parameter into an array that is dynamically allocated by the library.

It is the responsibility of the calling code to free this memory when the information is no longer required.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

app_bytes

Pointer to where the pointer to the dynamically allocated bytes data buffer is to be placed.

ap_result_length

Pointer to where the number of bytes contained in the array associated with app_bytes should be stored on return.

tlms_bool flml_read_embedded(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, char ac_embedded[], int a_max_length, int *ap_result_length );

Description

Reads the embedded value associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ac_embedded

Pointer to where the embedded data is to be placed.

a_max_length

The maximimum length of string that the ac_string parameter can hold.

ap_result_length

Pointer to where the number of bytes contained in ac_embedded should be stored on return.

tlms_bool flml_read_embedded_dynamic(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, char **app_embedded, int *ap_result_length );

Description

Reads the embedded value associated with the named parameter into an array that is dynamically allocated by the library.

It is the responsibility of the calling code to free this memory when the information is no longer required.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

app_embedded

Pointer to where the pointer to the dynamically allocated embedded data buffer is to be placed.

ap_result_length

Pointer to where the number of bytes contained in the array associated with app_embedded should be stored on return.

tlms_bool flml_read_union(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, char ac_string[], int a_max_length );

Description

Reads the selected option of the union associated with the named parameter.

See the section Using the Library for hints on how the code using the read functions can be structured.

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ac_string

Where the read string is to be placed.

a_max_length

The maximimum length of string that the ac_string parameter can hold.

int flml_read_enumerated_union(

slml_parse_ctrl *ap_parse_ctrl, const char ac_tagging[], int a_instance, slml_tag_translation ac_tag_translation[] );

Description

Reads the selected option of the union associated with the named parameter and converts it to an integer value according to the contents of the array ac_tag_translation.

This is indended for use in switch statements.

Returns

The integer corresponding to the union value present. If there is not an entry in the translation table, then -1 is returned.

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

ac_tagging

Tagging information for the parameter that is to be read. See the section Tagging Information for more information on how to specify tags.

a_instance

The instance of the tag that is being looked for. See the section Tagging Information for more information on how to specify tags.

ac_tag_translation

Contains an array of slml_tag_translation elements used to translate the union values in a message into an enumerated value suitable for use in a switch statement.

The first member of each slml_tag_translation structure is the tag name or value that might appear in the message. The second member of the structure is the integer value that should be used to represent that tag value.

An empty tag name string is used to represent an untagged integer, if present.

The end of the list if slml_tag_translation structures is marked by the first member containing NULL.

An example of suitably formatted array is:

     slml_tag_translation tag_list[] = {
            "", 0,          // For the untagged integer
            "*", 1,
            "factor", 2,
            NULL, 0 };
	

void flml_release(

slml_parse_ctrl *ap_parse_ctrl );

Description

Releases all the resources associated with parsing the message.

This function must be called when the code has finished with a parsed message to avoid memory leaks.

Returns

void

Parameters

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

tlms_bool flml_encode_float(

char ac_encoded_float[], tlms_double a_value );

Description

This function supports encoding Lumas messages.

Converts a single precision float or double precision float (double) in to an ascii string taking into account possible conversion to NaN, INF and -INF.

(The main argument for this function is actually a 'double'. The compiler will convert the float to a double if it is called in this way).

Returns

TRUE if successful, FALSE otherwise. Information on why the function failed can be obtained by calling flml_get_last_error.

Parameters

ac_encoded_float

Array where the ASCII representation of the float/double value is to be placed.

a_value

The value to be encoded.

int flml_encode_get_ascii_length(

const char ac_ascii[] );

Description

This function supports encoding Lumas messages.

Returns the number of bytes needed to store an encoded ascii string. This includes the leading and trailing ' characters, space for any escaping that needs to be done, and a terminating \0.

Returns

The length of the item when encoded in Lumas format plus space for a terminating \0.

Parameters

ac_ascii

The ASCII string to be encoded.

tlms_bool flml_encode_ascii(

char ac_encoded_ascii[], int a_encoded_ascii_max_length, const char ac_ascii[] );

Description

This function supports encoding Lumas messages.

Converts an ascii string into an encoded ascii string. This includes the leading and trailing ' characters, space for any escaping that needs to be done, and a terminating \0.

Returns

TRUE if successful, FALSE otherwise.

The most likely cause of failure is that the ac_encoded_ascii array is too small to contain the encoded data. Use flml_encode_get_ascii_length to find out the required size.

Parameters

ac_encoded_ascii

Array where the Lumas formatted ASCII string is to be placed.

a_encoded_ascii_max_length

Specifies the maximum number of bytes that can be stored in the ac_encoded_ascii array.

ac_ascii

The ASCII string to be encoded.

int flml_encode_get_unicode_length(

const tlms_unicode ac_unicode[] );

Description

This function supports encoding Lumas messages.

Returns the number of bytes needed to store an encoded Unicode string. This includes the leading and trailing " characters, space for any UTF-8 encoding that needs to be done, and a terminating \0.

Returns

The length of the item in bytes when encoded in Lumas format plus space for a terminating \0.

Parameters

ac_unicode

The Unicode string to be encoded.

tlms_bool flml_encode_unicode(

char ac_encoded_unicode[], int a_encoded_unicode_max_length, const tlms_unicode ac_unicode[] );

Description

This function supports encoding Lumas messages.

Converts a Unicode string into the encoded UTF-8 format for outputting on the wire. This includes the leading and trailing " characters, any escaping that needs to be done, and a terminating \0.

Returns

TRUE if successful, FALSE otherwise.

The most likely cause of failure is that the ac_encoded_unicode array is too small to contain the encoded data. Use flml_encode_get_unicode_length to find out the required size.

Parameters

ac_encoded_unicode

Where the encoded byte Unicode string is to be placed.

a_encoded_unicode_max_length

Specifies the maximum number of bytes that can be stored in the ac_encoded_unicode array.

ac_unicode

The Unicode string to be encoded.

int flml_encode_get_bytes_length(

int a_data_length );

Description

This function supports encoding Lumas messages.

Returns the number of bytes needed to store a base64 encoded array of a_data_length bytes. This includes space for the leading and terminating [ ] characters, space for line breaks every 76 output characters, plus space for a terminating \0 character.

Returns

The number of bytes needed to represent the item when encoded in Lumas format plus space for a terminating \0.

Parameters

a_data_length

The length of the unencoded binary data.

tlms_bool flml_encode_bytes(

char ac_base64[], int a_max_length, const char *ap_data, int a_length );

Description

This function supports encoding Lumas messages.

Convert binary data stored in a bytes item into base64 encoded data suitable for outputing to an encoded message. The result includes the leading and terminating [ ] characters, line breaks every 76 output characters, plus a terminating \0 character.

Returns

TRUE if successful, FALSE otherwise.

The most likely cause of failure is that the ac_base64 array is too small to contain the encoded data. Use flml_encode_get_bytes_length to find out the required size.

Parameters

ac_base64

Array where the encoded byte string is to be placed.

a_max_length

The maximimum length of string that the ac_string parameter can hold.

ap_data

Pointer to the bytes data to be encoded.

a_length

The length of the buffer containing the message.

tlms_bool flml_is_well_formed(

const char *ap_message, int a_length );

Description

This function supports encoding Lumas messages.

Tests whether the message is well formed from a syntactic point of view. (Note that even if the message passes this test, it may still be semantically ill-formed, and may not conform to the intended message definition.)

This function is useful to test that locally generated messages have a valid Lumas format before putting them on the wire. It can also be used to test whether received messages have a valid format.

Returns

TRUE if the message is well formed, FALSE otherwise.

Parameters

ap_message

Pointer to the buffer containing the message

a_length

The length of the buffer containing the message.

void flml_debug_display_parse_info(

FILE *ah_fout, slml_parse_ctrl *ap_parse_ctrl );

Description

Returns

Parameters

ah_fout

The handle of the file to which the debug information should be printed. If the parameter is NULL, the debug information is output to stdout.

ap_parse_ctrl

Pointer to the parse control block. This is allocated by the calling code (typically as a local variable) and initialised when flml_parse_message is called.

slml_tag_translation
slml_message_element
slml_tag_info
slml_location
slml_parse_ctrl
tlml_input_location

typedef struct slml_tag_translation
{
        char *text_tag;
        int enumerated_value;
} slml_tag_translation;

typedef struct slml_message_element
{
        char *p_tag;
        tlml_input_location tag_location;
        int tag_number;
        tlml_input_location value_location;
        struct slml_message_element *p_compound;
        struct slml_message_element *p_next;
} slml_message_element;

typedef struct slml_tag_info
{
        const char *p_name;
        struct slml_tag_info *p_definition;
} slml_tag_info;

typedef struct slml_location
{
        slml_message_element *p_element;
        slml_tag_info *p_tag_info;
} slml_location;

typedef struct slml_parse_ctrl
{
        const char *p_message;
        int length;
        const char *p_next;
        const char *p_message_end;
        elml_error error;
        int allocation_failed;
        slml_location root_location;
        slml_location base_location;
        int unget_char;
        int recursion;
} slml_parse_ctrl;

typedef int tlml_input_location;

typedef         unsigned char tlms_bool; // Boolean value
typedef         unsigned long tlms_uns32; // Unsigned 32 bit integer
typedef         unsigned short tlms_uns16; // Unsigned 16 bit integer
typedef         unsigned char tlms_uns8; // Unsigned 8 bit integer
typedef         signed long tlms_int32; // Signed 32 bit integer
typedef         signed short tlms_int16; // Signed 16 bit integer
typedef         signed char tlms_int8; // Signed 8 bit integer
typedef         float tlms_float; // Single precision floating point
typedef         double tlms_double; // Double precision floating point
typedef         char tlms_ascii; // Ascii character
typedef         unsigned short tlms_unicode; // 16 bit wide Unicode character
typedef         unsigned char tlms_bytes; // Bytes type
typedef         char tlms_embedded; // Single byte of an embedded type
typedef         tlms_uns8 tlms_ipv4[4];
typedef         tlms_uns8 tlms_ipv6[16];

typedef struct tlms_date
{
        unsigned int year; /* years since 0 */
        unsigned int month; /* months since January - [1,12] */
        unsigned int day; /* day of the month - [1,31] */
} tlms_date;

typedef struct tlms_time
{
        unsigned int hour; /* hours since midnight - [0,23] */
        unsigned int min; /* minutes after the hour - [0,59] */
        unsigned int sec; /* seconds after the minute - [0,59] */
} tlms_time;

typedef struct tlms_oid
{
        unsigned int size;
        unsigned int value[20];
} tlms_oid;

typedef enum elml_error
{
        ELML_OK = 0,
        ELML_PARSE_FAILED = 1000,
        ELML_NO_DATA_IN_MESSAGE,
        ELML_ALLOCATION_FAILED,
        ELML_TOO_MANY_RECURSIONS,
        ELML_MESSAGE_TOO_SHORT,
        ELML_PARAMETER_TOO_LONG,
        ELML_PARAMETER_WRONG_TYPE,
        ELML_PARAMETER_NOT_FOUND,
        ELML_PARAMETER_DOES_NOT_EXIST, // Only used when tagging info is present
        ELML_OUTPUT_TOO_SMALL
} elml_error;

[To main guide]