/**
 * @file   FLMDEF.h
 * @brief  FLMDEF - External FLAM definitions
 * @author limes datentechnik gmbh
 * @date   11.01.2016
 * @copyright limes datentechnik gmbh
 *
 * This header contains different global defines for FLAM application
 * programming interfaces.
 *
 **/
/*! @cond PRIVATE */
#ifdef __cplusplus
   extern "C" {
#endif

#ifndef INC_FLMDEF_H
#define INC_FLMDEF_H
/*! @endcond */

/**********************************************************************/

/**
 * @defgroup OUTFMT Output format
 * @brief Constants for setting the output format for some functions
 *
 * Pass one of the constants below to all functions requiring output format (e.g. fcbclose2()),
 * for formatting of the output in different ways. This is mainly required for statistics and
 * other lists.
 * @{
 */
#define FLMOUT_FORMAT_NON        0 /**< @brief Default format (#FLMOUT_FORMAT_LST)*/
#define FLMOUT_FORMAT_LST        1 /**< @brief Simple list of lines with each line separated by '\\n' and the whole string terminated by 0x00*/
#define FLMOUT_FORMAT_XML        2 /**< @brief As XML-formatted, null-terminated string (in local charset) with each line separated by '\\n'*/
/** @} */

/**
 * @defgroup SYNHLP Syntax and help
 * @brief Syntax and help constants for FLUC byte and record interface
 *
 * Pass this to fcbhelp()/FCRHLP() or fcbsyntax()/FCRSYN() as parameter
 * 'what' to get help or syntax information about the different parameter
 * strings used to read, write or format data or about the state string.
 * @{
 */
#define FLC_READ_FILE               1/**< @brief File definition strings in read mode*/
#define FLC_READ_FORMAT             2/**< @brief Format data strings in read mode*/
#define FLC_WRITE_FILE              3/**< @brief File definition strings in write mode*/
#define FLC_WRITE_FORMAT            4/**< @brief Format data strings in write mode*/
#define FLC_CONV_READ               5/**< @brief Data conversion strings in read mode*/
#define FLC_CONV_WRITE              6/**< @brief Data conversion strings in write mode*/
#define FLC_CONV_FROM_TO            7/**< @brief Data conversion string in from-to mode*/
#define FLC_INPUT_FILE              8/**< @brief File definition strings in input mode*/
#define FLC_OUTPUT_FILE             9/**< @brief File definition strings in output mode*/
#define FLC_INFO                   10/**< @brief Definition of the info string*/
#define FLC_STATE                  11/**< @brief Definition of the state string*/
#define FLC_LOG                    12/**< @brief Definition of the memory log string*/
/** @} */

/**
 * @defgroup HSHMTD Hash methods
 * @brief Defines integer values for the different hash methods
 *
 * Pass this to the hash functions to choose the hash procedure.
 * @{
 */
#define FLCHSH_ALGO_NON            0U/**< @brief No valid hash method*/
#define FLCHSH_ALGO_MD5            1U/**< @brief MD5 method*/
#define FLCHSH_ALGO_RMD128         2U/**< @brief RipeMd-128 method*/
#define FLCHSH_ALGO_RMD160         3U/**< @brief RipeMd-160 method*/
#define FLCHSH_ALGO_SHA1          10U/**< @brief SHA1 method*/
#define FLCHSH_ALGO_SHA160        10U/**< @brief SHA1 method*/
#define FLCHSH_ALGO_SHA224        20U/**< @brief SHA224 (SHA2 variant) method*/
#define FLCHSH_ALGO_SHA256        21U/**< @brief SHA256 (SHA2 variant) method*/
#define FLCHSH_ALGO_SHA384        22U/**< @brief SHA384 (SHA2 variant) method*/
#define FLCHSH_ALGO_SHA512        23U/**< @brief SHA512 (SHA2 variant) method*/
#define FLCHSH_ALGO_SHA3_224      30U/**< @brief SHA3-224 method*/
#define FLCHSH_ALGO_SHA3_256      31U/**< @brief SHA3-256 method*/
#define FLCHSH_ALGO_SHA3_384      32U/**< @brief SHA3-384 method*/
#define FLCHSH_ALGO_SHA3_512      33U/**< @brief SHA3-512 method*/
#define FLCHSH_ALGO_CRC08        100U/**< @brief 8 Bit CRC checksum (no crypto quality)*/
#define FLCHSH_ALGO_CRC16        101U/**< @brief 16 Bit CRC checksum (no crypto quality)*/
#define FLCHSH_ALGO_CRC24        102U/**< @brief 24 Bit CRC checksum (no crypto quality)*/
#define FLCHSH_ALGO_CRC32        103U/**< @brief 32 Bit CRC checksum (no crypto quality)*/
#define FLCHSH_ALGO_CRC32C       104U/**< @brief 32 Bit CRC checksum (no crypto quality)*/
#define FLCHSH_ALGO_CRC40        105U/**< @brief 40 Bit CRC checksum (no crypto quality)*/
#define FLCHSH_ALGO_CRC64        106U/**< @brief 64 Bit CRC checksum (no crypto quality)*/
/** @} */

/**
 * @defgroup MACMTD MAC methods
 * @brief Defines integer values for the different methods for
 * calculation a message authentication code
 *
 * Pass this to the hash functions to choose the key related procedure.
 * @{
 */
#define FLCMAC_ALGO_NON          0U/**< @brief No valid hash method*/
#define FLCMAC_ALGO_HMAC         1U/**< @brief HMAC conform to RFC 2104*/
/** @} */

/**
 * @defgroup CNTVAL Counting values
 * @brief Defines integer values to define which statistical accounting
 * value is requested by function fcbcount() or FCRCNT().
 * @{
 */
#define FLC_INBOUND_COUNT        1/**< @brief Use input values*/
#define FLC_OUTBOUND_COUNT       2/**< @brief Use output values*/
#define FLC_FIO_COUNT            1/**< @brief Use values from File I/O*/
#define FLC_FMT_COUNT            2/**< @brief Use values from formatting*/
#define FLC_BYTE_COUNT           1/**< @brief Determine byte counts*/
#define FLC_UNIT_COUNT           2/**< @brief Determine unit (block or record) counts*/
/** @} */

/**
 * @defgroup MATTYP Matrix types
 * @anchor MATTYP
 * @brief All available matrix type definitions (data formats)
 *
 * A matrix is a complex data structure used to manage a list of neutral
 * FLAM5 elements. All element lists of a member/file must be built based
 * on the same matrix type.
 *
 * The matrix type defines a neutral data format which is used to manage
 * the data elements inside of FLAM.
 * @{
 */
#define FLMMAT_TYP_NON           0x00 /**< @brief Unknown/undefined matrix type*/
#define FLMMAT_TYP_DATBLK        0x80 /**< @brief Data blocks, 1 element type, no attributes*/
#define FLMMAT_TYP_STDREC        0x81 /**< @brief Standard record, 1 element type, no attributes*/
#define FLMMAT_TYP_STDASAREC     0x82 /**< @brief Standard record, 1 element type, with 1 byte ASA control character as attribute*/
#define FLMMAT_TYP_STDMCCREC     0x83 /**< @brief Standard record, 1 element type, with 1 byte machine control character as attribute*/
#define FLMMAT_TYP_RELREC        0x84 /**< @brief Relative record, 1 element type, with 8 byte integer (slot number) as attribute*/
#define FLMMAT_TYP_RELASAREC     0x85 /**< @brief Relative record, 1 element type, with 8 byte slot number and 1 byte ASA as attribute*/
#define FLMMAT_TYP_RELMCCREC     0x86 /**< @brief Relative record, 1 element type, with 8 byte slot number and 1 byte MCC as attribute*/
#define FLMMAT_TYP_TXTREC        0x87 /**< @brief Text record, 1 element type, no attributes (like standard record, but text is known)*/
#define FLMMAT_TYP_TXTDLM        0x88 /**< @brief Text record with delimiter at the end, 1 element type, no attributes*/
#define FLMMAT_TYP_TXTRST        0x90 /**< @brief Text record and rest element (suppressed trailing whitespace and original delimiter), 2 elements, no attributes*/
#define FLMMAT_TYP_XMLELM        0x91 /**< @brief XML elements, no attributes*/
#define FLMMAT_TYP_TABELM        0x92 /**< @brief Table elements, no attributes*/
/** @} */

/*! @cond PRIVATE */
#define FLMELM_VALID(m,t) ( (((m)>=0x80 && (m)<=0x88) && ((t)==0         )) || \
                            (((m)==0x90             ) && ((t)>=0 && t<= 1)) || \
                            (((m)==0x91             ) && ((t)>=0 && t<=23)) )
#define FLMELM_INVALID(m,t) (!FLMELM_VALID((m),(t)))
#define FLMATRLEN_VALID(m,t,l) ( (((m)==0x80 || (m)==0x81 || (m)==0x87 || (m)==0x88 || (m)==0x90 || (m)==0x91) && (l)==0) || \
                                 (((m)==0x82 || (m)==0x83                                                    ) && (l)==1) || \
                                 (((m)==0x84                                                                 ) && (l)==8) || \
                                 (((m)==0x85 || (m)==0x86                                                    ) && (l)==9) )
#define FLMATRLEN_INVALID(m,t,l) (!FLMATRLEN_VALID((m),(t),(l)))
/*! @endcond */

/**
 * @defgroup ELMTYP Element types
 * @anchor ELMTYP
 * @brief Element type definitions by matrix type
 *
 * Each FLAM 5 matrix can consist of different element types. The interpretation
 * of the different element types or which element types are valid depends on
 * the matrix type.
 * The element type 0 is mainly used for the net data of a matrix type.
 * @{
 *   @defgroup ELMBLK Block
 *   @brief Block element types (see: #FLMMAT_TYP_DATBLK)
 *
 *   A matrix of blocks is a list of chunks containing an arbitrary type
 *   of data (probably binary). This matrix type only has the element
 *   type zero.
 *
 *   @defgroup ELMREC Record
 *   @brief Record element types (see: #FLMMAT_TYP_STDREC etc.)
 *
 *   The different kinds of records are separated by different matrix types.
 *   Each of these matrix types only have the element type zero.
 *
 *   @defgroup ELMTXT Text
 *   @brief Text element types (see: #FLMMAT_TYP_TXTREC etc.)
 *
 *   A text matrix  has two element types. The element type zero is the
 *   net text record and the element type one is the rest element. The
 *   rest element holds the text delimiter and (depending on the text
 *   parsing parameters) it could contain trailing whitespace.
 *
 *   @defgroup ELMXML XML
 *   @brief XML element types (see: #FLMMAT_TYP_XMLELM)
 *
 *   A XML matrix consists of a number of different element types of which
 *   each reflects one part of the XML specification. Some contain single
 *   strings, others contain multiple strings separated by.
 *
 *   @defgroup ELMTAB TAB
 *   @brief Table element types (see: #FLMMAT_TYP_TABELM)
 *
 *   A table matrix consists of a number of different element types of
 *   which each reflects the data type of the column. Additional bits in
 *   the second byte are used for different kind of attributes (e.g. tag
 *   of an TLV). The attribute length are encoded in the high oder 2 bytes\\0.
 * @} */

/**
 * @ingroup ELMTYP
 * @brief Use this value for an element type if no skip of an element
 * type required at read.
 */
#define FLMELM_NOSKIP            -1

/**
 * @ingroup ELMBLK
 * @brief Simple data block element type (may contain binary data)
 */
#define FLMELM_TYPBLK_STANDARD    0

/**
 * @ingroup ELMREC
 * @brief Record element type for record matrix types
 */
#define FLMELM_TYPREC_STANDARD    0

/**
 * @ingroup ELMTXT
 * @brief Text element type of a TXTRST matrix
 */
#define FLMELM_TYPTXT_RECORD      0
/**
 * @ingroup ELMTXT
 * @brief Rest element type of a TXTRST matrix
 */
#define FLMELM_TYPTXT_REST        1

/**
 * @ingroup ELMXML
 * @brief XML data element type
 *
 * Contains the character data of an XML node. More specifically, it holds
 * the character sequence found between an opening and closing tag or within
 * a CDATA section. There may be multiple consecutive XML data elements,
 * possibly interrupted by other elements like children XML nodes, comments
 * and other entities. Data elements returned by FLAM through one of the APIs'
 * read functions are at least 1024 bytes long if the XML node contains that
 * many bytes. For XML nodes containing less than 1024 bytes of character data,
 * the data is guaranteed to be returned in one element (i.e. is not split to
 * multiple elements).
 *
 */
#define FLMELM_TYPXML_DATA        0
/**
 * @ingroup ELMXML
 * @brief Start of opening XML tag element type
 *
 * Indicates the start of an opening XML tag. It contains the tag name as
 * payload. If namespace processing is enabled, the tag is prefixed with the
 * namespace URI and optionally postfixed with the namespace prefix.
 * This element type is immediately followed by pairs of elements
 * of types #FLMELM_TYPXML_ATTNAME and #FLMELM_TYPXML_ATTRVAL for each of
 * the tag's attributes (if any). The end of an opening XML tag is indicated
 * by an element of type #FLMELM_TYPXML_ENDSTRTELM (mandatory).
 */
#define FLMELM_TYPXML_STARTELM    1
/**
 * @ingroup ELMXML
 * @brief End of opening XML tag element type
 *
 * Indicates the end of an opening XML tag. It must be preceded by a
 * #FLMELM_TYPXML_DATA element. This element carries no payload, i.e. its
 * data length is zero.
 */
#define FLMELM_TYPXML_ENDSTRTELM  2
/**
 * @ingroup ELMXML
 * @brief Closing XML tag element type
 *
 * Indicates a closing XML tag. It contains the tag name as payload.
 * If namespace processing is enabled, the tag is prefixed with the
 * namespace URI and optionally postfixed with the namespace prefix.
 * In a valid XML document, there must be a matching #FLMELM_TYPXML_STARTELM
 * element prior to a closing XML tag element.
 */
#define FLMELM_TYPXML_ENDELM      3
/**
 * @ingroup ELMXML
 * @brief Attribute name element type
 *
 * The name of an attribute within an opening XML tag.
 * If namespace processing is enabled, the attribute name is prefixed with
 * the namespace URI and optionally postfixed with the namespace prefix.
 * Must be immediately followed by an element of type #FLMELM_TYPXML_ATTRVAL.
 *
 * This element type may only occur between pairs of elements of types
 * #FLMELM_TYPXML_STARTELM and #FLMELM_TYPXML_ENDELM.
 */
#define FLMELM_TYPXML_ATTNAME     4
/**
 * @ingroup ELMXML
 * @brief Attribute value element type
 *
 * The value of an attribute within an opening XML tag. Must be immediately
 * preceded by an element of type #FLMELM_TYPXML_ATTNAME.
 *
 * This element type may only occur between pairs of elements of types
 * #FLMELM_TYPXML_STARTELM and #FLMELM_TYPXML_ENDELM.
 */
#define FLMELM_TYPXML_ATTRVAL     5
/**
 * @ingroup ELMXML
 * @brief XML prolog element type
 *
 * Element for the prolog of an XML document, e.g. <code>\<?xml version="1.0" encoding="UTF-8" standalone="yes"?\></code>.
 * The XML prolog is always the first element and must not be preceded by any other element.
 * The prolog is optional, but recommended by the standard.
 * The element's payload are the three attributes separated by a NUL character, each:
 *
 * <pre>\<version\>\\0\<encoding\>\\0\<standalone\></pre>
 *
 * * The <code>version</code> is mandatory according to the XML standard.
 * * The <code>encoding</code> string is optional and may be empty. It contains the character encoding of the document.
 * * The <code>standalone</code> field is a one byte field with one of three possible values:
 *  * - (no standalone field present)
 *  * Y (standalone="yes")
 *  * N (standalone="no")
 */
#define FLMELM_TYPXML_XML         6

/**
 * @ingroup ELMXML
 * @brief General skipped entity element type
 *
 * A general entity is a reference to a replacement text that is associated
 * with a name. It is encoded in the XML document body as <code>\&name;</code>
 * with <code>name</code> being the name of the entity. Its value is defined
 * by an entity declaration in the DTD for the XML document. We do not
 * interpret DTDs. Therefore, these entities are not replaced with the actual
 * text, but reported as skipped entities. The payload of a general skipped
 * entity element is the name of the entity.
 *
 * @see #FLMELM_TYPXML_INTENTDECL, #FLMELM_TYPXML_SYSENTDECL, #FLMELM_TYPXML_PUBENTDECL
 */
#define FLMELM_TYPXML_SKIPENT     7
/**
 * @ingroup ELMXML
 * @brief Skipped parameter entity element type
 *
 * A parameter entity is a reference to a replacement text that is associated
 * with a name. Unlike general entities, parameter entities are only replaced
 * if used inside the DTD and are encoded as <code>%name;</code> with
 * <code>name</code> being the name of the entity. Its value is defined by a
 * parameter entity declaration in the DTD of the XML document. We do not
 * interpret DTDs. Therefore, these entities are not replaced with the actual
 * text, but reported as skipped parameter entities. The payload of a skipped
 * parameter entity element is the name of the entity.
 *
 * @see #FLMELM_TYPXML_INTENTDECL, #FLMELM_TYPXML_SYSENTDECL, #FLMELM_TYPXML_PUBENTDECL
 */
#define FLMELM_TYPXML_SKIPPARMENT 8
/**
 * @ingroup ELMXML
 * @brief Start of a DTD (Document Type Definition) element type
 *
 * A document type definition (DTD) defines the structure of an XML document.
 * It can be specified inline within the XML document itself or as a reference
 * to some external resource. An #FLMELM_TYPXML_ENDDTD element must follow before
 * the first XML tag occurs to terminate the DTD. The start of a DTD has one
 * of these following forms:
 *
 * 1. <code>\<!DOCTYPE name SYSTEM "sysid"</code>
 * 2. <code>\<!DOCTYPE name SYSTEM "sysid" [</code>
 * 3. <code>\<!DOCTYPE name PUBLIC "pubid" "sysid"</code>
 * 4. <code>\<!DOCTYPE name PUBLIC "pubid" "sysid" [</code>
 * 5. <code>\<!DOCTYPE name [</code>
 *
 * The element's payload consists of five attributes separated by a NUL character:
 *
 * <pre>\<type\>\\0\<name\>\\0\<public_id\>\\0\<system_id\>\\0\<has_internal_subset\></pre>
 *
 * * The <code>type</code> flag is one byte that indicates the DTD reference type and has one of three values
 * ** - (case 5, no external reference, DTD is inline, requires <code>has_internal_subset</code> set to 1)
 * ** S (case 1+2, the SYSTEM identifier is present)
 * ** P (case 3+4, the PUBLIC identifier is present)
 * * <code>name</code> must be same as the root element in the document
 * * <code>public_id</code> contains the public identifier if type=P
 * * <code>system_id</code> contains the system identifier if type=S or P
 * * <code>has_internal_subset</code> is a single byte field set to the character 1 (not the byte value!) if there is an internal subset (inline DTD) portion. Otherwise, it's set to the character 0.
 */
#define FLMELM_TYPXML_STARTDTD    9
/**
 * @ingroup ELMXML
 * @brief End of a DTD element type
 *
 * Marks the end of a document type definition previously started by a
 * #FLMELM_TYPXML_STARTDTD element. It must occur before the first XML
 * tag.
 */
#define FLMELM_TYPXML_ENDDTD     10
/**
 * @ingroup ELMXML
 * @brief DTD element type declaration element type
 *
 * Element type declarations put constraints on XML nodes. For example,
 * this declaration requires an XML node named "html" to have to children
 * "head" and "body":
 * <pre>\<!ELEMENT html (head, body)\></pre>
 *
 * The element's payload consists of two attributes separated by a NUL character:
 *
 * <pre>\<name\>\\0\<model\></pre>
 *
 * * <code>name</code> is the XML node name
 * * <code>model</code> is a model string complying to the content specification syntax described in the XML standard
 *
 * This element type may only occur within a DTD, i.e. between pairs of
 * elements of types #FLMELM_TYPXML_STARTDTD and #FLMELM_TYPXML_ENDDTD.
 */
#define FLMELM_TYPXML_ELMDECL    11
/**
 * @ingroup ELMXML
 * @brief DTD attribute list declaration element type
 *
 * Attribute lists describe constraints on attributes of XML nodes. This
 * example defines a required attribute "src" for XML nodes named "img".
 * The attribute value must contain character data:
 * <pre>\<!ATTLIST img src CDATA \#REQUIRED\></pre>
 *
 * Each attribute list declaration element describes one attribute.
 * The element's payload consists of five attributes separated by a NUL character:
 *
 * <pre>\<node_name\>\\0\<attribute_name\>\\0\<attribute_type\>\\0\<default\>\\0\<flag\></pre>
 *
 * * <code>node_name</code> is the name of the XML node the attribute belongs to
 * * <code>attribute_name</code> is the name of the constrained attribute
 * * <code>attribute_type</code> contains a string with the type of the attribute (see XML spec for valid values)
 * * <code>default</code> specifies a default value if <code>flag</code> is set to D or F
 * * <code>flag</code> is one byte describing an attribute mode with one of four values:
 *  * R (attribute is required, i.e. must be specified)
 *  * I (attribute is implied, i.e it is optional and without default value)
 *  * F (attribute must always have the default value)
 *  * D (attribute has a specified default value)
 *
 * This element type may only occur within a DTD, i.e. between pairs of
 * elements of types #FLMELM_TYPXML_STARTDTD and #FLMELM_TYPXML_ENDDTD.
 */
#define FLMELM_TYPXML_ATTLDECL   12
/**
 * @ingroup ELMXML
 * @brief Internal entity declaration element type
 *
 * Entity declarations define general or parameter entities. Entities names
 * are assigned replacement texts that are substitutes for any occurrence of
 * the entity. Parameter entities are only valid within the DTD. General
 * entities are valid in the XML document body. This element only describes
 * internal entities, i.e. entities with values directly defined within the
 * DTD. Here is an example for an internal general and a internal parameter
 * entity declaration:
 *
 * 1. <code>\<!ENTITY name "value"\></code>
 * 2. <code>\<!ENTITY % name "value"\></code>
 *
 * The element's payload consists of three attributes separated by a NUL character:
 *
 * <pre>\<name\>\\0\<value\>\\0\<is_parameter_entity\></pre>
 *
 * * <code>name</code> of the entity
 * * <code>value</code> that is substituted for entities with above name
 * * <code>is_parameter_entity</code> is the character 1 (not the byte value!) if a parameter entity is declared, 0 for a general entity
 *
 * This element type may only occur within a DTD, i.e. between pairs of
 * elements of types #FLMELM_TYPXML_STARTDTD and #FLMELM_TYPXML_ENDDTD.
 *
 * @see #FLMELM_TYPXML_SYSENTDECL, #FLMELM_TYPXML_PUBENTDECL, #FLMELM_TYPXML_SKIPENT, #FLMELM_TYPXML_SKIPPARMENT
 */
#define FLMELM_TYPXML_INTENTDECL 13
/**
 * @ingroup ELMXML
 * @brief External entity declaration element type with system identifier
 *
 * Entity declarations define general or parameter entities. Entities names
 * are assigned replacement texts that are substitutes for any occurrence of
 * the entity. Parameter entities are only valid within the DTD. General
 * entities are valid in the XML document body. This element only describes
 * external entities with a system identifier, i.e. entities with values
 * defined in another file. The file's content maybe parsed or unparsed (NDATA)
 * data. Here is an example for external general and internal parameter
 * entity declarations with system identifier:
 *
 * 1. <code>\<!ENTITY name SYSTEM "file.txt"\></code>
 * 2. <code>\<!ENTITY name SYSTEM "file.txt" NDATA notation\></code>
 * 3. <code>\<!ENTITY % name SYSTEM "file.txt"\></code>
 * 4. <code>\<!ENTITY % name SYSTEM "file.txt" NDATA notation\></code>
 *
 * The element's payload consists of four attributes separated by a NUL character:
 *
 * <pre>\<name\>\\0\<system_id\>\\0\<notation_name\>\\0\<is_parameter_entity\></pre>
 *
 * * <code>name</code> of the entity
 * * <code>system_id</code> contains the system identifier, typically a file URI
 * * <code>notation_name</code> is a non-empty string if the external resource is unparsed (NDATA) and must match the name of a notation declaration
 * * <code>is_parameter_entity</code> is the character 1 (not the byte value!) if a parameter entity is declared, 0 for a general entity
 *
 * This element type may only occur within a DTD, i.e. between pairs of
 * elements of types #FLMELM_TYPXML_STARTDTD and #FLMELM_TYPXML_ENDDTD.
 *
 * @see #FLMELM_TYPXML_INTENTDECL, #FLMELM_TYPXML_PUBENTDECL, #FLMELM_TYPXML_SKIPENT, #FLMELM_TYPXML_SKIPPARMENT, #FLMELM_TYPXML_NOTDECLS, #FLMELM_TYPXML_NOTDECLP, #FLMELM_TYPXML_NOTDECLPS
 */
#define FLMELM_TYPXML_SYSENTDECL 14
/**
 * @ingroup ELMXML
 * @brief External entity declaration element type with public identifier
 *
 * Entity declarations define general or parameter entities. Entities names
 * are assigned replacement texts that are substitutes for any occurrence of
 * the entity. Parameter entities are only valid within the DTD. General
 * entities are valid in the XML document body. This element only describes
 * external entities with a public identifier, i.e. entities with values
 * defined in another file and a public id. The file's content maybe parsed
 * or unparsed (NDATA) data. Here is an example for external general and
 * internal parameter entity declarations with public identifier:
 *
 * 1. <code>\<!ENTITY name PUBLIC "-//private//file//" "file.txt"\></code>
 * 2. <code>\<!ENTITY name PUBLIC "-//private//file//" "file.txt" NDATA notation\></code>
 * 3. <code>\<!ENTITY % name PUBLIC "-//private//file//" "file.txt"\></code>
 * 4. <code>\<!ENTITY % name PUBLIC "-//private//file//" "file.txt" NDATA notation\></code>
 *
 * The element's payload consists of five attributes separated by a NUL character:
 *
 * <pre>\<name\>\\0\<public_id\>\\0\<system_id\>\\0\<notation_name\>\\\<is_parameter_entity\></pre>
 *
 * * <code>name</code> of the entity
 * * <code>public_id</code> contains the public identifier
 * * <code>system_id</code> contains the system identifier, typically a file URI
 * * <code>notation_name</code> is a non-empty string if the external resource is unparsed (NDATA) and must match the name of a notation declaration
 * * <code>is_parameter_entity</code> is the character 1 (not the byte value!) if a parameter entity is declared, 0 for a general entity
 *
 * This element type may only occur within a DTD, i.e. between pairs of
 * elements of types #FLMELM_TYPXML_STARTDTD and #FLMELM_TYPXML_ENDDTD.
 *
 * @see #FLMELM_TYPXML_INTENTDECL, #FLMELM_TYPXML_SKIPENT, #FLMELM_TYPXML_SKIPPARMENT, #FLMELM_TYPXML_NOTDECLS, #FLMELM_TYPXML_NOTDECLP, #FLMELM_TYPXML_NOTDECLPS
 */
#define FLMELM_TYPXML_PUBENTDECL 15
/**
 * @ingroup ELMXML
 * @brief Notation declaration element type with a system identifier
 *
 * Notation declarations define the format of unparsed external entities
 * (referred to by the optional NDATA portion of an entity declaration),
 * the format of elements which bear a notation attribute and more. This
 * element only describes notation declarations with a system identifier
 * of the form:
 *
 * <pre><!NOTATION name SYSTEM "systemId"></pre>
 *
 * The element's payload consists of two attributes separated by a NUL character:
 *
 * <pre>\<name\>\\0\<system_id\></pre>
 *
 * * <code>name</code> of the entity
 * * <code>system_id</code> contains the system identifier
 *
 * This element type may only occur within a DTD, i.e. between pairs of
 * elements of types #FLMELM_TYPXML_STARTDTD and #FLMELM_TYPXML_ENDDTD.
 *
 * @see #FLMELM_TYPXML_NOTDECLP, #FLMELM_TYPXML_NOTDECLPS, #FLMELM_TYPXML_INTENTDECL, #FLMELM_TYPXML_SYSENTDECL, #FLMELM_TYPXML_PUBENTDECL
 */
#define FLMELM_TYPXML_NOTDECLS   16
/**
 * @ingroup ELMXML
 * @brief Notation declaration element type with a public identifier
 *
 * Notation declarations define the format of unparsed external entities
 * (referred to by the optional NDATA portion of an entity declaration),
 * the format of elements which bear a notation attribute and more. This
 * element only describes notation declarations with a public identifier
 * of the form:
 *
 * <pre><!NOTATION name PUBLIC "publicId"></pre>
 *
 * The element's payload consists of two attributes separated by a NUL character:
 *
 * <pre>\<name\>\\0\<public_id\></pre>
 *
 * * <code>name</code> of the entity
 * * <code>public_id</code> contains the public identifier
 *
 * This element type may only occur within a DTD, i.e. between pairs of
 * elements of types #FLMELM_TYPXML_STARTDTD and #FLMELM_TYPXML_ENDDTD.
 *
 * @see #FLMELM_TYPXML_NOTDECLS, #FLMELM_TYPXML_NOTDECLPS, #FLMELM_TYPXML_INTENTDECL, #FLMELM_TYPXML_SYSENTDECL, #FLMELM_TYPXML_PUBENTDECL
 */
#define FLMELM_TYPXML_NOTDECLP   17
/**
 * @ingroup ELMXML
 * @brief Notation declaration element type with a public and system identifier
 *
 * Notation declarations define the format of unparsed external entities
 * (referred to by the optional NDATA portion of an entity declaration),
 * the format of elements which bear a notation attribute and more. This
 * element only describes notation declarations with a public and system
 * identifier of the form:
 *
 * <pre><!NOTATION name PUBLIC "publicId" "systemId"></pre>
 *
 * The element's payload consists of three attributes separated by a NUL character:
 *
 * <pre>\<name\>\\0\<public_id\>\\0\<system_id\></pre>
 *
 * * <code>name</code> of the entity
 * * <code>public_id</code> contains the public identifier
 * * <code>system_id</code> contains the system identifier
 *
 * This element type may only occur within a DTD, i.e. between pairs of
 * elements of types #FLMELM_TYPXML_STARTDTD and #FLMELM_TYPXML_ENDDTD.
 *
 * @see #FLMELM_TYPXML_NOTDECLS, #FLMELM_TYPXML_NOTDECLP, #FLMELM_TYPXML_INTENTDECL, #FLMELM_TYPXML_SYSENTDECL, #FLMELM_TYPXML_PUBENTDECL
 */
#define FLMELM_TYPXML_NOTDECLPS  18
/**
 * @ingroup ELMXML
 * @brief Processing instruction element type
 *
 * Processing instructions carry instructions to the application.
 * They have a target name and application-specific string. A common
 * example is rendering XML documents using an XSLT stylesheet:
 *
 * <pre>\<?xml-stylesheet type="text/xsl" href="style.xsl"?\></pre>
 *
 * The element's payload consists of two attributes separated by a NUL character:
 *
 * <pre>\<target\>\\0\<instruction\></pre>
 *
 * * <code>target</code> names the intended recipient of an instruction
 * * <code>instruction</code> is an application-specific string
 */
#define FLMELM_TYPXML_PROCINST   19
/**
 * @ingroup ELMXML
 * @brief Start of CDATA section element type
 *
 * A CDATA section contains arbitrary character data which is not parsed
 * by an XML data. So, CDATA sections can contain whole XML documents,
 * which are treated like any other character data. The data in a CDATA
 * section may not contain the character sequence ]]\> as this marks the
 * end of a CDATA section.
 *
 * This element carries no payload, i.e. its data length is zero.
 *
 * Any number of elements of type #FLMELM_TYPXML_DATA may follow, followed
 * by a #FLMELM_TYPXML_ENDCD element.
 *
 * @see #FLMELM_TYPXML_ENDCD
 */
#define FLMELM_TYPXML_STARTCD    20
/**
 * @ingroup ELMXML
 * @brief Start of CDATA section element type
 *
 * Marks the end of a CDATA section that has previously been started by a
 * #FLMELM_TYPXML_STARTCD element.
 *
 * This element carries no payload, i.e. its data length is zero.
 *
 * @see #FLMELM_TYPXML_STARTCD
 */
#define FLMELM_TYPXML_ENDCD      21
/**
 * @ingroup ELMXML
 * @brief Comment element type
 *
 * XML comment is arbitrary text data enclosed by \<!-- and --\>.
 * This element type contains the comment's data as payload. The comment
 * data may not contain the character sequence --\> as this marks the end
 * of a comment.
 */
#define FLMELM_TYPXML_COMMENT    22
/**
 * @ingroup ELMXML
 * @brief Element type for all other data in a document
 *
 * This element type contains the data not covered by one of the other
 * elements. This includes whitespace, tabulators and line breaks that
 * are not part of a nodes content, in other words: ignorable whitespace.
 */
#define FLMELM_TYPXML_DEFAULT    23

/**
 * @ingroup ELMXML
 * @brief Start declaration name space handler
 *
 * Indicates the start of a name space declaration. It contains the
 * namespace prefix, the separation character and the URI as payload.
 * The prefix can be empty for a default name space definition.
 */
#define FLMELM_TYPXML_STARTNS    24

/**
 * @ingroup ELMXML
 * @brief End declaration name space handler
 *
 * Indicates the end of a name space declaration.
 * It contains the namespace prefix as payload.
 */
#define FLMELM_TYPXML_ENDNS      25

/*! @cond PRIVATE */
#define FLMELM_XMLMAX_TYPCNT     26 // to define type and pot tables big enough (must be one more than last element typ)
#define FLMELM_FLAG_LITCACHE     0x00000001U // marks element that literal cache are used (pcDat points into literal cache)
#define setFLMELM_LITCACHE(f)    ((f)|FLMELM_FLAG_LITCACHE)
#define isFLMELM_LITCACHE(f)     ((f)&FLMELM_FLAG_LITCACHE)

/*! @endcond */

/**
 * @ingroup ELMTAB
 * @brief No element type
 *
 * This element type contains elements which are only parsed from a row.
 * There is no data type defined, it is simply a part (blob) from a row.
 * This element type is handled like a binary element at write.
 *
 * Attention: The net data of table element list are only consists of
 * such elements.
 */
#define FLMELM_TYPTAB_NONE          0

/**
 * @ingroup ELMTAB
 * @brief Flag for null indication
 *
 * This flag are add to each data type to indicate a default value for
 * an optional item that was not part of the data.
 *
 */
#define FLMELM_TYPTAB_FLAG_NULLID   0x00010000

/**
 * @ingroup ELMTAB
 * @brief Flag for empty indication
 *
 * This flag are add to each data type to indicate a default value for
 * an empty data item (e.g. a integer string of length 0 replaced by a
 * default value (e.g. 0)).
 *
 */
#define FLMELM_TYPTAB_FLAG_EMPTID   0x00020000

/**
 * @ingroup ELMTAB
 * @brief Binary element type
 *
 * A binary data type is a black box for each kind of data in a
 * certain length. The external representation can be different
 * encodings. Internally representation if always the binary form.
 */
#define FLMELM_TYPTAB_BINARY        0x00000001
#define FLMELM_TYPTAB_BINARY_NI     (FLMELM_TYPTAB_BINARY | FLMELM_TYPTAB_FLAG_NULLID)
#define FLMELM_TYPTAB_BINARY_EI     (FLMELM_TYPTAB_BINARY | FLMELM_TYPTAB_FLAG_EMPTID)
#define FLMELM_TYPTAB_BINARY_EINI   (FLMELM_TYPTAB_BINARY | FLMELM_TYPTAB_FLAG_EMPTID | FLMELM_TYPTAB_FLAG_NULLID)

/**
 * @ingroup ELMTAB
 * @brief String element type
 *
 * A string data type is a character array in a certain length. The
 * external representation can be in different encodings (character sets).
 * The internal representation if always Unicode in UTF-8.
 */
#define FLMELM_TYPTAB_STRING        0x00000002
#define FLMELM_TYPTAB_STRING_NI     (FLMELM_TYPTAB_STRING | FLMELM_TYPTAB_FLAG_NULLID)
#define FLMELM_TYPTAB_STRING_EI     (FLMELM_TYPTAB_STRING | FLMELM_TYPTAB_FLAG_EMPTID)
#define FLMELM_TYPTAB_STRING_EINI   (FLMELM_TYPTAB_STRING | FLMELM_TYPTAB_FLAG_EMPTID | FLMELM_TYPTAB_FLAG_NULLID)

/**
 * @ingroup ELMTAB
 * @brief Integer element type
 *
 * A integer data type is a byte array in a certain length. The external
 * representation can be in different encodings (two's complement, BCD,
 * string). The internal representation is a hidden complex data structure
 * (black box).
 */
#define FLMELM_TYPTAB_INTEGER       0x00000003
#define FLMELM_TYPTAB_INTEGER_NI    (FLMELM_TYPTAB_INTEGER | FLMELM_TYPTAB_FLAG_NULLID)
#define FLMELM_TYPTAB_INTEGER_EI    (FLMELM_TYPTAB_INTEGER | FLMELM_TYPTAB_FLAG_EMPTID)
#define FLMELM_TYPTAB_INTEGER_EINI  (FLMELM_TYPTAB_INTEGER | FLMELM_TYPTAB_FLAG_EMPTID | FLMELM_TYPTAB_FLAG_NULLID)

/**
 * @ingroup ELMTAB
 * @brief Float element type
 *
 * A float data type is a byte array in a certain length. The external
 * representation can be in different encodings (IEEE, BCD, string). The
 * internal representation is a hidden complex data structure (black box).
 */
#define FLMELM_TYPTAB_FLOAT         0x00000004
#define FLMELM_TYPTAB_FLOAT_NI      (FLMELM_TYPTAB_FLOAT | FLMELM_TYPTAB_FLAG_NULLID)
#define FLMELM_TYPTAB_FLOAT_EI      (FLMELM_TYPTAB_FLOAT | FLMELM_TYPTAB_FLAG_EMPTID)
#define FLMELM_TYPTAB_FLOAT_EINI    (FLMELM_TYPTAB_FLOAT | FLMELM_TYPTAB_FLAG_EMPTID | FLMELM_TYPTAB_FLAG_NULLID)

/**
 * @ingroup ELMTAB
 * @brief Column name element type
 *
 * This is a special element type to detect a table header in a element
 * list of tables. Each table starts with a CLP string containing the
 * table name and a list of column names. The names can have optional
 * different kind of path variants preceded to support XML and other
 * hierarchical data formats. And the name can be appended optional the
 * DTL for this column in parenthesis.
 */
#define FLMELM_TYPTAB_HEADER        0x0000000A

/**********************************************************************/
/**
 * @defgroup STRUCTS Structures
 * @brief Definition of structures for FLAM's APIs.
 * @{
 */
/**
 * @brief FLAM 5 serialized element structure (version 0)
 *
 * This structure defines a FLAM 5 element in a serialized form. It may be
 * used to cast a buffer that contains data written by
 * <code>format.element()</code>. A serialized element basically consists
 * of a set of 32 bit integers followed by element attributes, data and
 * a data hash (is applicable).
 *
 * Users MUST check that the #version field matches the version of the used
 * struct definition. In future versions, further structures with different
 * fields may be added which will be assigned a new version. The first 32
 * bits can always be used to identify the correct structure.
 *
 * Each FLAM 5 matrix can consist of different element types. The interpretation
 * of the different element types depends on the matrix type.
 *
 * @see MATTYP, ELMTYP
 */
typedef struct {
   /** @brief Element structure version (must be 0)*/
    int     version;
   /** @brief Matrix type (type of data format)
    *
    * The matrix type indicates the type of data and defines the set of
    * valid element types that each FLAM 5 matrix can consist of. The
    * list of available matrix types can be found @ref MATTYP "here".
    */
    int     matTyp;
   /** @brief Element type
    *
    * The interpretation of the different element types depends on the matrix type.
    * The available element types can be found @ref ELMTYP "here".
    */
   int      elmTyp;
   /** @brief Attribute data length (at offset 32)*/
   int      atrLen;
   /** @brief Element data length (at offset 32 + #atrLen)*/
   int      datLen;
   /** @brief Hash data length (at offset 32 + #atrLen + #datLen)*/
   int      hshLen;
   /** Reserved for future use (should be 0)*/
   int      reserved1;
   /** Reserved for future use (should be 0)*/
   int      reserved2;
   /** @brief Unsigned data buffer (variable length) */
   char     buffer[4];
   /**<
    * Contains <code>atrLen</code> bytes of attribute data, followed by
    * <code>datLen</code> bytes of element data, followed by
    * <code>hshLen</code> bytes of hash data.
    *
    * The presence of attribute and hash data when reading depends on the
    * parameter given to format.element(). When writing, attributes and hash
    * data is only passed to FLAM if this is requested in the format.element()
    * clause.
    *
    * Hash values are only relevant with the FLAM element interface in order
    * to find data elements in compressed and encrypted data. The FLUC
    * element interface (used for data formats like PGP, GZIP, ...) does not
    * support hash values.
    */
} FlmElmRec0;

/**
 * @brief Macro that calculates the length of an element of type #FlmElmRec0
 * @hideinitializer
 *
 * This macro calculates the correct length in bytes of a serialized
 * element structure of type #FlmElmRec0 by passing a pointer the
 * element.
 *
 * The macro may be used to conveniently calculate the correct buffer size
 * e.g. to pass to fcbwrite() or FCRPUT() when writing elements.
 */
#define FLMELMREC0_LENGTH(element) ((size_t)32+(size_t)((element)->atrLen)+(size_t)((element)->datLen)+(size_t)((element)->hshLen))

/**
 * @brief Convenience macro that calculates the correct starting address of the attribute data within FlmElmRec0::buffer
 * @hideinitializer
 */
#define FLMELMREC0_ATTRPTR(element) ((element)->buffer)

/**
 * @brief Convenience macro that calculates the correct starting address of the element's data payload within FlmElmRec0::buffer
 * @hideinitializer
 */
#define FLMELMREC0_DATAPTR(element) (FLMELMREC0_ATTRPTR(element)+(element)->atrLen)

/**
 * @brief Convenience macro that calculates the correct starting address of the hash data within FlmElmRec0::buffer
 * @hideinitializer
 */
#define FLMELMREC0_HASHPTR(element) (FLMELMREC0_DATAPTR(element)+(element)->datLen)

/** @} */
/**********************************************************************/

/*! @cond PRIVATE */
#endif /* INC_FLMDEF_H */

#ifdef __cplusplus
   }
#endif
/*! @endcond */

