xml_pars_api.h

/*
 * Copyright 2016-2023, Cypress Semiconductor Corporation (an Infineon company) or
 * an affiliate of Cypress Semiconductor Corporation.  All rights reserved.
 *
 * This software, including source code, documentation and related
 * materials ("Software") is owned by Cypress Semiconductor Corporation
 * or one of its affiliates ("Cypress") and is protected by and subject to
 * worldwide patent protection (United States and foreign),
 * United States copyright laws and international treaty provisions.
 * Therefore, you may use this Software only as provided in the license
 * agreement accompanying the software package from which you
 * obtained this Software ("EULA").
 * If no EULA applies, Cypress hereby grants you a personal, non-exclusive,
 * non-transferable license to copy, modify, and compile the Software
 * source code solely for use in connection with Cypress's
 * integrated circuit products.  Any reproduction, modification, translation,
 * compilation, or representation of this Software except as specified
 * above is prohibited without the express written permission of Cypress.
 *
 * Disclaimer: THIS SOFTWARE IS PROVIDED AS-IS, WITH NO WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, NONINFRINGEMENT, IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress
 * reserves the right to make changes to the Software without notice. Cypress
 * does not assume any liability arising out of the application or use of the
 * Software or any product or circuit described in the Software. Cypress does
 * not authorize its products for use in any products where a malfunction or
 * failure of the Cypress product may reasonably be expected to result in
 * significant property damage, injury or death ("High Risk Product"). By
 * including Cypress's product in a High Risk Product, the manufacturer
 * of such system or application assumes all risk of such use and in doing
 * so agrees to indemnify Cypress against all liability.
 */

/*****************************************************************************
**
**  Name:       xml_pars_api.h
**
**  File:       XML Parser
**
**
*****************************************************************************/
#ifndef XML_PARS_API_H
#define XML_PARS_API_H

#include "data_types.h"
#include "wiced_bt_types.h"

#define XML_STACK_SIZE      7

#ifndef XML_UI_ENTRY_MAX_NAME_LEN
#define XML_UI_ENTRY_MAX_NAME_LEN 256
#endif

/*****************************************************************************
**   Type Definitions
*****************************************************************************/

/* Definition of XML events */
enum
{
    XML_XMLDECL,
    XML_TAG,         /* 1 For STag (Start Tag) and EmptyElemTag */
    XML_TAG_END,     /* 2 When STag or EmptyElemTag ends */
    XML_ATTRIBUTE,   /* 3 */
    XML_CHARDATA,    /* 4 */
    XML_ETAG,        /* 5 For End Tag */
    XML_PARTIAL,     /* 6 notify XML user that the parse does not end properly */
    XML_COPY,        /* 7 notify XML user to copy till end of a token */
    XML_QUERY,       /* 8 query if the XML object has ended */
    XML_TOP          /* 9 */
};
typedef UINT16 tXML_EVENT;
#define XML_LAST_XE     XML_ETAG

enum
{
    XML_SUCCESS,
    XML_WARNING,
    XML_OBJ_ST_EMPTY,
    XML_NO_MEM,         /* no p_last_bfr, and the tXML_MUL_STATE is not in init */
    XML_NO_PROP,        /* run out of tXML_PROP */
    XML_ERR,            /* generic error */
    XML_NO_END          /* to be continued */
};
typedef UINT16 tXML_RESULT;

/* Definitions of different event data */
typedef struct
{
    UINT8   *p_version;
    UINT8   *p_enc_name;
    BOOLEAN *p_standalone;    /* NULL if no standalone decl was found */
} tXML_DECL;



/* for parser that expand multi-sessions */
/* tag stack */
typedef struct
{
    UINT8         stack[XML_STACK_SIZE];
    UINT8         top;
    tXML_EVENT    event; /* last XML event */
} tXML_STACK;

typedef struct
{
    UINT8   *p;
    UINT16  len;
} tXML_STR;

typedef struct
{
    tXML_STACK  stack;
    tXML_STR    prefix;
    tXML_STR    name;
    UINT8       *p_last_stm;
} tXML_MTAG;

typedef struct
{
    tXML_STACK  stack;
    BOOLEAN     end;        /* true if end of EmptyElemTag */
                            /* false if end of STag        */
} tXML_MTAG_END;



typedef struct
{
    tXML_STACK  stack;
    tXML_STR    prefix;
    tXML_STR    name;
    tXML_STR    value;
} tXML_MATTR;


/* There may be several XML_CHARDATA events dispatched for one CHARDATA
** string in the XML document. In each XML_CHARDATA only a segment of the
** total string is provided. For the last segement the field last is true.
*/
typedef struct
{
    tXML_STACK  stack;
    tXML_STR    value;
    BOOLEAN     last;
} tXML_MCH_DATA;


typedef struct
{
    tXML_STACK  stack;
    tXML_STR    prefix;
    tXML_STR    name;
} tXML_METAG;

typedef struct
{
    tXML_STACK  stack;
    UINT8       *p_begin;
    tXML_STR    last;
} tXML_MCOPY;

typedef struct
{
    tXML_STACK  stack;
    tXML_RESULT parse;
    UINT8       *p_keep;
} tXML_MPART;

typedef union
{
    tXML_STACK      stack;
    tXML_DECL       decl;
    tXML_MTAG       tag;
    tXML_MTAG_END   empty_elem;
    tXML_MATTR      attr;
    tXML_MCH_DATA   ch_data;
    tXML_METAG      etag;
    tXML_MCOPY      copy;
    tXML_MPART      part;
} tXML_MEVT_DATA;

typedef struct
{
    UINT8       *p_data;            /* Pointer to property data. */
    UINT16      len;                /* Length of data. */
    UINT8       prefix;             /* Property prefix. */
    UINT8       name;               /* Property name. */
    UINT8       level;              /* 0 as top level */
} tXML_PROP;

/* Definitions of different error actions.
** At present there is only one.
*/
enum
{
    XML_NEXT_TAG /* tries to find beginning of next tag */
};
typedef UINT16 tXML_ERR_ACTION;



enum
{
    XML_STS_INIT,
    XML_STS_1STM,   /* got the first < */
    XML_STS_1TAG,   /* got the first tag element */
    XML_STS_DONE
};
typedef UINT8   tXML_STATUS;

typedef struct
{
    UINT8       *p_begin;/* the beginning of XML data */
    UINT8       *p_end;  /* the end of XML data */
} tXML_OS;


/*****************************************************************************
**
** Callback         tXML_CBACK
**
** Description
**     Called repeatedly from the XML parser for each XML construct parsed.
**     The parsed XML construct is reported as an XML event in the event
**     in-parameter. The parser provides event data specific for each event
**     in the callback through the p_event_data param which should be casted
**     to the proper type by the user implemented tXML_CBACK function.
**     The p_event_data should be casted to a pointer of a type with the same
**     name as the  event but prefixed with t. For example when the event is
**     XML_TAG, p_event_data should be casted to tXML_TAG*. Alternatively,
**     p_event_data can be casted to a tEVENT_DATA* (pointer to union) type
**     for all events. The memory behind the p_event_data is provided by the
**     parser and is only valid during the callback, i.e. the memory is not
**     valid after the callback. No pointer inside the event structures may
**     be NULL unless explicitly stated so above for some specific event.
**     The p_usr_data parameter is the same p_usr_data pointer the
**     API user passed in the XML_Parse. It is only declared as a mean for
**     the API user to pass any user data to its callback function.
**
**
** Parameters
**     event (in) :        the XML event or XML contruct just parsed,
**     p_event_data (in) : data, i.e. names values etc, found in the XML
**                         construct. The data is specific for the XML
**                         construct and should be casted to the
**                         proper type as described above. May not be NULL.
**     p_usr_data (in) :   Same p_usr_data as passed in XML_Parse.
**
** Returns
**     TRUE :  if parsing should continue
**     FALSE : if parsing should stop
**
*****************************************************************************/

typedef BOOLEAN (*tXML_CBACK)(tXML_EVENT event, void *p_event_data,
                              void *p_usr_data);

typedef struct
{

    UINT8       p[512];
    UINT16     len;
} tXML_STR_PARTIAL;

typedef struct
{
    tXML_STR_PARTIAL       last_bfr;
    UINT16          used_last_bfr;
    tXML_MEVT_DATA event_data;
}
tXML_PARTIAL;

/* tXML_STATE stores state during the XML_Parse call not between
** XML_Parse calls. It is used in most static functions in this file
** and passed in as first parameter to these.
*/
typedef struct
{
    /* input from XML_Parse caller */
    tXML_OS        xml_os;
    UINT8          *p_cur;
    tXML_CBACK     cback;
    void           *p_usr_data;
    tXML_MEVT_DATA event_data;

    /* handling of data buffers for prefix, name and value */
    UINT8          *p_data_bfr;
    UINT8          *p_last_stm; /* last '<' */
    UINT8          *p_copy;
    tXML_STR       last_bfr;
    tXML_STR       value;
    tXML_STR       prefix;
    tXML_STR       name;

    /* token and result handling */
    INT16          curr_res;
    tXML_RESULT    pars_res;
    UINT8          next_token;
    BOOLEAN        skip_next_nl;

    UINT16          used_last_bfr;   /* the actual data size in p_last_bfr */
    tXML_STATUS    status;

    /* structure used to store partial data */
    tXML_PARTIAL  partial_st;
} tXML_MUL_STATE;

/*****************************************************************************
**  External Function Declarations
*****************************************************************************/
#ifdef __cplusplus
extern "C"
{
#endif

/*****************************************************************************
**
** Function         XML_Parse
**
** Description
**     Parses an XML message/document in utf8. The message is read from
**     an object store which must have been initialised and an object
**     (file) must have been opened so the parser can start directly with
**     reading the first byte using the GOEP_Read function and passing
**     the h_obj_store in-param.
**     The parser will call the xml_cback callback for each basic
**     XML-construct parsed. If the parser encounters an error it will
**     try to act according to the err_action in-param and report any
**     errors through the err_handle. The parser is non-validating.
**
** Parameters
**     h_obj_store (in) : a handle to an opened object (file) in
**                        the Object Store. The object must be
**                        ready for reading.
**     xml_cback (in) :   the user provided function to call back
**                        for each XML-construct (XML event) parsed.
**     err_action (in) :  the action the parser will try if it finds
**                        an error.
**     err_handle (in) :  a handle to some error recording object to
**                        which the parser may report errors. This is
**                        a place holder to connect any type of error
**                        recording object.
**     p_usr_data (in) :  any user data that will be passed on
**                        unchanged to the callback function.
**
** Returns
**     0 if the parsing was successfull without errors
**     non-zero error or warning code otherwise
**
*****************************************************************************/

tXML_RESULT XML_Parse(tXML_OS *p_os, tXML_CBACK xml_cback,
                      tXML_ERR_ACTION err_action, UINT32 err_handle,
                      void *p_usr_data);

/*****************************************************************************
**
** Function         XML_MulParse
**
** Description      Initialize XML parser state machine.
**
** Parameters
**      p_st (in)        :   xml state machine.
**      p_os (in)        :   xml data storage
**
*****************************************************************************/
tXML_RESULT XML_MulParse(tXML_MUL_STATE *p_st, tXML_OS *p_os);

/*****************************************************************************
**
** Function         XML_InitPars
**
** Description      Initialize XML parser state machine.
**
** Parameters
**      p_st (in)        :   xml state machine.
**      xml_cback (in)   :   the user provided function to call back
**      p_usr_data       :   user defined data.
**
*****************************************************************************/
void XML_InitPars(tXML_MUL_STATE *p_st, tXML_CBACK xml_cback, void *p_usr_data);

#ifdef __cplusplus
}
#endif

#endif /* ifndef XML_PARS_API_H */