torsten
77c67c12ca
Entire-Metadata: .entire/metadata/fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Session: fb87247f-2a75-407e-b336-cbc8c20ba5a6 Entire-Strategy: manual-commit
394 lines
11 KiB
C
394 lines
11 KiB
C
/*
|
|
* Copyright (c) 2007-2024 Real-Time Innovations, Inc. All rights reserved.
|
|
* No duplications, whole or partial, manual or electronic, may be made
|
|
* without express written permission. Any such copies, or revisions thereof,
|
|
* must display this notice unaltered.
|
|
* This code contains trade secrets of Real-Time Innovations, Inc.
|
|
*/
|
|
|
|
#ifndef rtixml_parser_h
|
|
#define rtixml_parser_h
|
|
|
|
|
|
/* ---------------------------------------------------------------------- */
|
|
/* PARSER CLASS --------------------------------------------------------- */
|
|
/* ---------------------------------------------------------------------- */
|
|
|
|
/*e \file
|
|
\brief XML Parser API
|
|
*/
|
|
|
|
/*e \mainpage
|
|
RTI XML utilities
|
|
*/
|
|
|
|
/*e \defgroup RTIXMLModule RTIXMLModule
|
|
\brief RTI XML utilities
|
|
*/
|
|
|
|
/*e \defgroup RTIXMLParserClass RTIXMLParser
|
|
\ingroup RTIXMLModule
|
|
|
|
@brief RTI XML Parser
|
|
|
|
The XML parser will parse the input XML returning the root RTIXMLObject.
|
|
|
|
The XML parser can parse files, urls, and strings.
|
|
|
|
Following there is a code snippet that shows how to use the Parser.
|
|
|
|
\b Example:
|
|
\code
|
|
void example( char * inputXML )
|
|
{
|
|
struct RTIXMLParser * parser = NULL;
|
|
struct RTIXMLObject * root = NULL;
|
|
|
|
parser = RTIXMLParser_new();
|
|
|
|
// Here register parser extensions ...
|
|
|
|
root = RTIXMLParser_parseFromFile(parser, NULL, 0, inputXML);
|
|
if (root == NULL) {
|
|
RTIXMLLog_exception( METHOD_NAME,
|
|
&RTI_LOG_ANY_FAILURE_s,
|
|
"parsing" );
|
|
RTIXMLParser_delete(parser);
|
|
return 0;
|
|
}
|
|
|
|
// Use the returned DOM ...
|
|
|
|
RTIXMLParser_delete(parser);
|
|
}
|
|
\endcode
|
|
*/
|
|
|
|
/* ---------------------------------------------------------------------- */
|
|
/* INCLUDES, DEFINES ---------------------------------------------------- */
|
|
/* ---------------------------------------------------------------------- */
|
|
|
|
#include "rtixml/rtixml_dll.h"
|
|
#include "rtixml/rtixml_extension.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* ---------------------------------------------------------------------- */
|
|
/* STRUCTURES ----------------------------------------------------------- */
|
|
/* ---------------------------------------------------------------------- */
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
@brief RTIXMLParser class
|
|
*/
|
|
struct RTIXMLParser;
|
|
|
|
/* ---------------------------------------------------------------------- */
|
|
/* METHODS -------------------------------------------------------------- */
|
|
/* ---------------------------------------------------------------------- */
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Creates a new RTIXMLParser.
|
|
|
|
This method creates a new RTIXMLParser.
|
|
The same parser can be used to parse multiple XML files.
|
|
|
|
@return The new RTIXMLParser if success. Otherwise, NULL.
|
|
|
|
@see RTIXMLParser_delete
|
|
*/
|
|
extern RTIXMLDllExport struct RTIXMLParser * RTIXMLParser_new(void);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Deletes a RTIXMLParser
|
|
|
|
This method deletes a RTIXMLParser that was created with RTIXMLParser_new.
|
|
|
|
@pre self is not NULL
|
|
|
|
@param self \b In. Pointer to the parser.
|
|
|
|
@see RTIXMLParser_new
|
|
*/
|
|
extern RTIXMLDllExport void RTIXMLParser_delete(struct RTIXMLParser *self);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Initializes a RTIXMLParser
|
|
|
|
@pre self is not NULL
|
|
|
|
@param self \b In. Pointer to the parser.
|
|
|
|
@return RTI_TRUE if success. Otherwise, RTI_FALSE.
|
|
|
|
@see RTIXMLParser_finalize
|
|
*/
|
|
extern RTIXMLDllExport
|
|
RTIBool RTIXMLParser_initialize(struct RTIXMLParser *self);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Finalizes a RTIXMLParser
|
|
|
|
This method releases the resources associated to the input RTIXMLParser.
|
|
|
|
@pre self is not NULL
|
|
|
|
@param self \b In. Pointer to the parser.
|
|
|
|
@see RTIXMLParser_initialize
|
|
*/
|
|
extern RTIXMLDllExport void RTIXMLParser_finalize(struct RTIXMLParser *self);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Parses a XML file and returns a pointer to the root XML object,
|
|
optionally relaxing DTD validation to allow unexpected tags.
|
|
|
|
It is responsability of the user to release the returned DOM using the
|
|
function RTIXMLParser_freeDOM.
|
|
|
|
@pre self is not NULL.
|
|
@param dtdStr \b In. Pointer to an array of string pointers containing the DTD
|
|
document
|
|
|
|
The DTD document referenced from the DOCTYPE tag in the XML file takes
|
|
precedence over dtdStr.
|
|
|
|
@param dtdStrLength \b In. Number of elements in dtdStr
|
|
@param dtdIgnoreUnexpectedElements \b In. Whether tags not specified in the
|
|
DTD should be ignored.
|
|
@pre filename is not NULL.
|
|
|
|
@param self \b In. Pointer to the parser.
|
|
@param fileName \b In. The name of the XML file.
|
|
|
|
@return The root element of the DOM if success. Otherwise, NULL.
|
|
|
|
@see RTIXMLParser_parseFromString_ex
|
|
*/
|
|
extern RTIXMLDllExport struct RTIXMLObject * RTIXMLParser_parseFromFile_ex(
|
|
struct RTIXMLParser *self,
|
|
const char *dtdStr[],
|
|
unsigned int dtdStrLength,
|
|
RTIBool dtdIgnoreUnexpectedElements,
|
|
const char *fileName,
|
|
struct RTIXMLObject *root,
|
|
void *contextUserData);
|
|
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Parses a XML file and returns a pointer to the root XML object.
|
|
|
|
It is responsability of the user to release the returned DOM using the
|
|
function RTIXMLParser_freeDOM.
|
|
|
|
@pre self is not NULL.
|
|
@param dtdStr \b In. Pointer to an array of string pointers containing the DTD
|
|
document
|
|
|
|
The DTD document referenced from the DOCTYPE tag in the XML file takes
|
|
precedence over dtdStr.
|
|
|
|
@param dtdStrLength \b In. Number of elements in dtdStr
|
|
@pre filename is not NULL.
|
|
|
|
@param self \b In. Pointer to the parser.
|
|
@param fileName \b In. The name of the XML file.
|
|
|
|
@return The root element of the DOM if success. Otherwise, NULL.
|
|
|
|
@see RTIXMLParser_parseFromString
|
|
*/
|
|
extern RTIXMLDllExport struct RTIXMLObject * RTIXMLParser_parseFromFile(
|
|
struct RTIXMLParser *self,
|
|
const char *dtdStr[],
|
|
unsigned int dtdStrLength,
|
|
const char *fileName,
|
|
struct RTIXMLObject *root,
|
|
void *contextUserData);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Parses XML data from the input string vector and
|
|
returns a pointer to the root XML object, optionally relaxing DTD
|
|
validation to allow unexpected tags.
|
|
|
|
It is responsability of the user to release the returned DOM using the
|
|
function RTIXMLParser_freeDOM.
|
|
|
|
The DTD document referenced from the DOCTYPE tag in the XML file takes
|
|
precedence over dtdStr.
|
|
|
|
@pre self is not NULL.
|
|
@pre xmlStr is not NULL
|
|
@pre xmlStrLength is not '0'.
|
|
@pre if dtdStrLength > 0 then dtdStr != NULL
|
|
|
|
@param self \b In. Pointer to the parser.
|
|
@param dtdStr \b In. Pointer to an array of string pointers containing the DTD
|
|
document
|
|
@param dtdStrLength \b In. Number of elements in dtdStr
|
|
@param dtdIgnoreUnexpectedElements \b In. Whether tags not specified in the
|
|
DTD should be ignored.
|
|
@param xmlStr \b In. String array to be parsed.
|
|
@param xmlStrLength \b In. Size of the string array.
|
|
|
|
@return The root element of the DOM if success. Otherwise, NULL.
|
|
|
|
@see RTIXMLParser_parseFromFile
|
|
*/
|
|
extern RTIXMLDllExport struct RTIXMLObject * RTIXMLParser_parseFromString_ex(
|
|
struct RTIXMLParser *self,
|
|
const char *dtdStr[],
|
|
unsigned int dtdStrLength,
|
|
RTIBool dtdIgnoreUnexpectedTags,
|
|
const char *xmlStr[],
|
|
unsigned int xmlStrLength,
|
|
struct RTIXMLObject *root,
|
|
void *contextUserData);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Parses XML data from the input string vector and
|
|
returns a pointer to the root XML object.
|
|
|
|
It is responsability of the user to release the returned DOM using the
|
|
function RTIXMLParser_freeDOM.
|
|
|
|
The DTD document referenced from the DOCTYPE tag in the XML file takes
|
|
precedence over dtdStr.
|
|
|
|
@pre self is not NULL.
|
|
@pre xmlStr is not NULL
|
|
@pre xmlStrLength is not '0'.
|
|
@pre if dtdStrLength > 0 then dtdStr != NULL
|
|
|
|
@param self \b In. Pointer to the parser.
|
|
@param dtdStr \b In. Pointer to an array of string pointers containing the DTD
|
|
document
|
|
@param dtdStrLength \b In. Number of elements in dtdStr
|
|
@param xmlStr \b In. String array to be parsed.
|
|
@param xmlStrLength \b In. Size of the string array.
|
|
|
|
@return The root element of the DOM if success. Otherwise, NULL.
|
|
|
|
@see RTIXMLParser_parseFromFile
|
|
*/
|
|
extern RTIXMLDllExport struct RTIXMLObject * RTIXMLParser_parseFromString(
|
|
struct RTIXMLParser *self,
|
|
const char *dtdStr[],
|
|
unsigned int dtdStrLength,
|
|
const char *xmlStr[],
|
|
unsigned int xmlStrLength,
|
|
struct RTIXMLObject *root,
|
|
void *contextUserData);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Registers a RTIXMLExtensionClass with the parser.
|
|
|
|
@pre self is not NULL
|
|
@pre extension is not NULL
|
|
|
|
@param self \b In. A pointer to the parser.
|
|
@param extension \b In. The pointer to the extension to be register.
|
|
|
|
@return RTI_TRUE if success. Otherwise, RTI_FALSE.
|
|
|
|
If the extension already exists, the function returns
|
|
RTI_TRUE and prints a warning
|
|
*/
|
|
extern RTIXMLDllExport RTIBool RTIXMLParser_registerExtensionClass(
|
|
struct RTIXMLParser *self,
|
|
struct RTIXMLExtensionClass *extension);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Unregisters a RTIXMLExtensionClass.
|
|
|
|
@pre self is not NULL
|
|
@pre tagName is not NULL
|
|
|
|
@param self \b In. A pointer to the parser.
|
|
@param tagName \b In. Tagname associated to the extension class.
|
|
|
|
@return Unregistered extension class. NULL if the extension class does not
|
|
exist
|
|
*/
|
|
extern RTIXMLDllExport
|
|
struct RTIXMLExtensionClass * RTIXMLParser_unregisterExtensionClass(
|
|
struct RTIXMLParser *self,
|
|
const char *tagName);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Finds a RTIXMLExtensionClass.
|
|
|
|
@pre self is not NULL
|
|
@pre tagName is not NULL
|
|
|
|
@param self \b In. A pointer to the parser.
|
|
@param tagName \b In. Tagname associated to the extension class.
|
|
|
|
@return Extension class. NULL if the extension class is not found
|
|
*/
|
|
extern RTIXMLDllExport
|
|
struct RTIXMLExtensionClass * RTIXMLParser_findExtensionClass(
|
|
struct RTIXMLParser *self,
|
|
const char *tagName);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Releases all the resources associated to the input DOM object
|
|
|
|
@pre self is not NULL
|
|
@pre dom is not NULL
|
|
|
|
@param self \b In. A pointer to the parser.
|
|
@param dom \b In. A pointer to the DOM object.
|
|
*/
|
|
extern RTIXMLDllExport void RTIXMLParser_freeDOM(
|
|
struct RTIXMLParser *self,
|
|
struct RTIXMLObject *dom);
|
|
|
|
/*e \ingroup RTIXMLParserClass
|
|
|
|
@brief Gets the version of the last XML file parsed by the parser.
|
|
|
|
If the version does not exist the function returns NULL.
|
|
|
|
@pre self is not NULL
|
|
|
|
@param self \b In. A pointer to the parser.
|
|
|
|
@return The XML version if it exists. Otherwise, NULL.
|
|
*/
|
|
extern RTIXMLDllExport const char * RTIXMLParser_getLastXmlVersion(
|
|
struct RTIXMLParser *self);
|
|
|
|
/** \ingroup RTIXMLParserClass
|
|
* @brief Adds a new entry in the user_environment list of this parser
|
|
*
|
|
* The variable is asserted at the end of the list, overriding the value if the
|
|
* variable already exists.
|
|
*/
|
|
extern RTIXMLDllExport
|
|
RTIBool RTIXMLParser_addUserEnvironmentVariable(
|
|
struct RTIXMLParser *self,
|
|
const char *name,
|
|
const char *value);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
#endif
|
|
#include "rtixml/rtixml_parser_impl.h"
|
|
|
|
#endif /* rtixml_parser_h */
|