/* * Copyright (c) 2016 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 rtixmlutils_object_h #define rtixmlutils_object_h #include "rtixmlutils/rtixmlutils_dll.h" #include "osapi/osapi_type.h" #ifdef __cplusplus extern "C" { #endif /** \ingroup RTIXMLUTILSParserModule * * @brief Definition of the available text content kind. * * An RTIXMLUTILSObject may be a text element, such as: * [MyText] * * where [MyText] could be either a value or a variable. If the element text * is a variable, its text can be expanded to a specified value. This may * cause the need to access both values depending on the operation performed * in the object. * * This enumeration defines the two the types of element text: * - value: this corresponds to the actual element text. If the text is a * variable, it could represent the variable name of the expanded value. * - variable: if the element text is a variable and it was expanded, it * represent the original text containing the variable name. */ typedef enum { RTIXMLUTILS_OBJECT_VALUE_TEXT_CONTENT, RTIXMLUTILS_OBJECT_VARIABLE_TEXT_CONTENT } RTIXMLUTILSObjectTextContentKind; /** \ingroup RTIXMLUTILSParserModule * * @brief Memory representation of a XML element. */ struct RTIXMLUTILSObject; /* * --- RTIXMLUTILSObject ------------------------------------------------------ */ #define RTIXMLUTILS_OBJECT_ANNOTATION_TAG_NAME ("annotation") #define RTIXMLUTILS_OBJECT_DOCUMENTATION_TAG_NAME ("documentation") #define RTIXMLUTILS_OBJECT_NODE_NAME_LENGTH_MAX (256) #define RTIXMLUTILS_OBJECT_NAME_SEPARATOR ("::") #define RTIXMLUTILS_OBJECT_NAME_SEPARATOR_LEN (2) #define RTIXMLUTILS_OBJECT_FILE_PATH_PI_NAME ("rti-filepath") #define RTIXMLUTILS_OBJECT_END_OF_FRAGMENT_PI_CONTENT ("END-OF-XML-FRAGMENT") #define RTIXMLUTILS_PARSER_URL_LIST_SEPARATOR (";") #define RTIXMLUTILS_PARSER_URL_GROUP_SEPARATOR ("|") #define RTIXMLUTILS_PARSER_URL_GROUP_START ("[") #define RTIXMLUTILS_PARSER_URL_GROUP_END ("]") #define RTIXMLUTILS_PARSER_URL_STRING_SCHEME ("str://") #define RTIXMLUTILS_PARSER_URL_FILE_SCHEME ("file://") #define RTIXMLUTILS_TRANSFORMER_PARAMS_LENGTH_MAX (64) extern RTIXMLUTILSDllVariable const char * RTIXMLUTILS_OBJECT_FILE_UNKNOWN_URL; /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the name of this RTIXMLUTILSObject. This usually refers to * the value of the name attribute, or an automatically generated value if the * attribute is not present. * * @return the name of this RTIXMLUTILSObject */ extern RTIXMLUTILSDllExport const char * RTIXMLUTILSObject_getName(struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns tag name of this RTIXMLUTILSObject. * * @return The tag name of the XmlObject */ extern RTIXMLUTILSDllExport const char *RTIXMLUTILSObject_getTagName(struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the value of the specified attribute. * * @param attributeName The attribute name * @return The attribute value string or NULL if the attribute does not * exist. */ extern RTIXMLUTILSDllExport const char * RTIXMLUTILSObject_getAttribute( struct RTIXMLUTILSObject *self, const char *attributeName); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the next attribute that appears next to the specified one * * @param name \inout input attribute (NULL to retrieve the first attribute) * output attribute if the function returns true. * @param vale \out output attribute value if the function returns true. * @return True if an attribute is found */ extern RTIXMLUTILSDllExport RTIBool RTIXMLUTILSObject_getNextAttribute( struct RTIXMLUTILSObject *self, const char **name, const char **value); /** \ingroup RTIXMLUTILSParserModule * * @brief returns the element text of this RTIXMLUTILSObject. * * The operation returns the text of the current selected content kind. Default * kind is RTIXMLUTILS_OBJECT_VALUE_TEXT_CONTENT. * * @return the element text of this RTIXMLUTILSObject or NULL if the XML * element is not a text element. */ extern RTIXMLUTILSDllExport const char * RTIXMLUTILSObject_getText(struct RTIXMLUTILSObject * self); /** \ingroup RTIXMLUTILSParserModule * * @brief Selects the content text in the text elements contained in the * specified tree. * * This operation will traverse the specified tree an set the text content * in each of the RTIXMLUTILSObject that represent a text element. * * This operation allows specifying the text content to be used by affected * operations such as RTIXMLUTILSObject_getText or RTIXMLUTILSObject_toString. * * @param contentKind The text content kind. * * @return True on succes. */ extern RTIXMLUTILSDllExport RTIBool RTIXMLUTILSObject_selectText( struct RTIXMLUTILSObject *self, RTIXMLUTILSObjectTextContentKind contentKind); /** \ingroup RTIXMLUTILSParserModule * * @return Returns the fully qualified name of this RTIXMLUTILSObject. * */ extern RTIXMLUTILSDllExport const char * RTIXMLUTILSObject_getFullyQualifiedName(struct RTIXMLUTILSObject * self); /** \ingroup RTIXMLUTILSParserModule * * @return The line number of the XML file where appears the element that this * RTIXMLUTILSObject represents. * * @return the line number of -1 if this information is not available. */ extern RTIXMLUTILSDllExport RTI_INT32 RTIXMLUTILSObject_getLineNumber(struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns The URL of the file where this RTIXMLUTILSObject comes from. * * @return The URL of the file where this RTIXMLUTILSObject comes from or * RTIXMLUTILS_OBJECT_FILE_UNKNOWN_URL if it is not available. */ extern RTIXMLUTILSDllExport const char * RTIXMLUTILSObject_getUrl(struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Retrieves the parent element of this RTIXMLUTILSObject. * * @return the parent RTIXMLUTILSObject o NULL if this object is the root node. */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject * RTIXMLUTILSObject_getParent( struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @return The number of children this RTIXMLUTILSObject has. * */ extern RTIXMLUTILSDllExport int RTIXMLUTILSObject_getChildCount(struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the first child of this RTIXMLUTILSObject. * * @return first child of this RTIXMLUTILSObject or NULL if this element has * not children. */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject * RTIXMLUTILSObject_getFirstChild( struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the next sibling of this RTIXMLUTILSObject. * * @return Returns the next sibling of this RTIXMLUTILSObject or NULL if there * are no more next siblings. */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject *RTIXMLUTILSObject_getNextSibling( struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the previous sibling of this RTIXMLUTILSObject. * * @return Returns the next previous of this RTIXMLUTILSObject or NULL if there * are no more previous siblings. */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject *RTIXMLUTILSObject_getPrevSibling( struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the first child sibling of this RTIXMLUTILSObject that matches * the specified tag. * * @param tagName The XML tag name. * * @returns The first child with the specified tag or NULL if there are no * children with such tag. * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject * RTIXMLUTILSObject_getFirstChildWithTag( struct RTIXMLUTILSObject *self, const char *tagName); /** \ingroup RTIXMLUTILSParserModule * * @brief * Finds the first descendant of this RTIXMLUTILSObject that matches * the specified tag. The search is performed using DFS (Depth-first search). * * @param [in] tagName The XML tag name. * * @returns * The first descendant with the specified tag or NULL if there are no * nodes in the subtree with such a tag. * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject * RTIXMLUTILSObject_getFirstDescendantWithTag( struct RTIXMLUTILSObject *self, const char *tagName); /** \ingroup RTIXMLUTILSParserModule * * @brief * Finds the next descendant of this RTIXMLUTILSObject that matches * the specified tag. The next element is retrieved relative to the * prevDescendant in DFS (Depth-first search) order. * * @param [in] tagName The XML tag name. * * @param [in] prevDescendant * This the node relative to which the next node is found in DFS ordering. * * @returns * The next descendant with the specified tag or NULL if there are * no nodes in the subtree with such a tag after the prevDescendant in DFS order. * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject * RTIXMLUTILSObject_getNextDescendantWithTag( struct RTIXMLUTILSObject *self, struct RTIXMLUTILSObject *prevDescendant, const char *tagName); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the next sibling of this RTIXMLUTILSObject that matches the * specified tag * * @param tagName The XML tag name. * @returns The next sibling with the specified tag or NULL if there are no * more children with such tag * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject * RTIXMLUTILSObject_getNextSiblingWithTag( struct RTIXMLUTILSObject *self, const char *tagName); /** \ingroup RTIXMLUTILSParserModule * * @brief Traverses the XML element subtree of this RTIXMLUTILSObject to find * the first child with the specified name. * * @param name The name of the child. It cannot be a fully qualified name. * * @return The first child in the tree with the specified name or NULL if no * element is found. * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject *RTIXMLUTILSObject_lookUpChild( struct RTIXMLUTILSObject *self, const char *name); /** \ingroup RTIXMLUTILSParserModule * * @brief Traverses the XML element subtree of this RTIXMLUTILSObject to find * the first child with the specified name. * * If the name is a fully qualified name, this operation will look up from the * root if the FQN starts with RTIXMLUTILS_OBJECT_NAME_SEPARATOR, the * operation will look up from the root element, otherwise it will look up * from this RTIXMLUTILSObject. * * @param name The name of the child. It can be a fully qualified name. * * @return The first child in the tree with the specified name or NULL if no * element is found. * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject *RTIXMLUTILSObject_lookUp( struct RTIXMLUTILSObject *self, const char *name); /** \ingroup RTIXMLUTILSParserModule * * @brier Returns the root element of the tree where this RTIXMLUTILSObject * belongs to. * * @return The root element or this RTIXMLUTILSObject. This function * never returns NULL. * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject *RTIXMLUTILSObject_getRoot( struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brier A place holder to keep data associated with the XML object. * */ extern RTIXMLUTILSDllExport void RTIXMLUTILSObject_setUserData( struct RTIXMLUTILSObject *self, void *userData); /** \ingroup RTIXMLUTILSParserModule * * @brier Returns the user data associated with the XML object. * * @returns The user data associated with the XML object. * */ extern RTIXMLUTILSDllExport void * RTIXMLUTILSObject_getUserData( struct RTIXMLUTILSObject *self); /** * \ingroup RTIXMLUTILSParserModule * * @brief Unlinks this RTIXMLUTILSObject from the XML DOM document * it belongs to. * */ extern RTIXMLUTILSDllExport void RTIXMLUTILSObject_unlink(struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Copies the specified element as child to this RTIXMLUTILSObject. * * @param element The element to be added as child. * * @return The new child element on success, NULL otherwise. * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject * RTIXMLUTILSObject_copyAsChild( struct RTIXMLUTILSObject *self, struct RTIXMLUTILSObject *element); /** \ingroup RTIXMLUTILSParserModule * * @brief Copies the specified element as child to this RTIXMLUTILSObject with * the specified processing instruction information. * * @param element The element to be added as child. * @param processingInstruction The processing information name * @param processingInstructionData The processing information data * * @return The new child element on success, NULL otherwise. * * @see RTIXMLUTILSObject_copyAsChild * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject * RTIXMLUTILSObject_copyAsChildWithProcessingInstruction( struct RTIXMLUTILSObject *self, struct RTIXMLUTILSObject *element, char *processingInstruction, char *processingInstructionData); /** \ingroup RTIXMLUTILSParserModule * * @brief Creates a new RTIXMLUTILSObject copy of this RTIXMLUTILSObject. * * @return The new copy on success, NULL otherwise. * */ extern RTIXMLUTILSDllExport struct RTIXMLUTILSObject * RTIXMLUTILSObject_copy( struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Converts this RTIXMLUTILSObject into a string representation and places * it in the specified buffer. * * The string representation is equivalent to the minimal XML code that would * have generated this RTIXMLUTILSObject, including its children. * * The string representation is placed in the specified buffer at the specified * offset within the buffer. This operation will reallocate the output buffer * if it does not have enough capacity or NULL is provided. * * If a NULL buffer is provided, this operation returns the length of the * string representation in outputBufferLength. * * @param outputBuffer The output string that contains the string * representation of this object. * @param outputBufferLength As an input, the size of the output buffer. * As an output, the actual size of the buffer, * which may be bigger if it was reallocated. * @param outputBufferOffset Position within the buffer where the string * representation is placed. * @param prettyPrint Indicates whether the output string is formatted * with proper indentation. * * @return True on success. */ extern RTIXMLUTILSDllExport RTIBool RTIXMLUTILSObject_toStringWithParams( struct RTIXMLUTILSObject * self, char **outputBuffer, unsigned int *outputBufferLength, unsigned int outputBufferOffset, RTIBool prettyPrint); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns this RTIXMLUTILSObject as a string representation. * * This operation allocates a new string to hold the string representation. * The string representation will be formatted to contain the proper * indentation. * * @return A newly allocated string containing the string representation of * this RTIXMLUTILSObject or NULL on error. * * @see RTIXMLUTILSObject_toStringWithBuffer. */ extern RTIXMLUTILSDllExport char * RTIXMLUTILSObject_toString(struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Checks that this RTIXMLUTILSObject has the same attributes and attribute * values than a specified element. * * The operation returns false if one of the element has at least an attribute * or attribute value that is different or inexistent in the other element. * * @param other The element to be compared with this RTIXMLUTILSObject. * * @return True if the specified element have the same attributes and * attribute values than this RTIXMLUTILSObject. * */ extern RTIXMLUTILSDllExport RTIBool RTIXMLUTILSObject_equalAttributes( struct RTIXMLUTILSObject *self, struct RTIXMLUTILSObject *other); /** \ingroup RTIXMLUTILSParserModule * * @brief Checks that this RTIXMLUTILSObject is equal to a specified element. * * Two elements are considered equal if they have the same tag name, the same * attributes and the same siblings and children. * * @param other The element to be compared with this RTIXMLUTILSObject. * * @return True if the specified element is equal to this RTIXMLUTILSObject. * * @see RTIXMLUTILSObject_equalAttributes */ extern RTIXMLUTILSDllExport RTIBool RTIXMLUTILSObject_equals( struct RTIXMLUTILSObject *self, struct RTIXMLUTILSObject *other); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the RTI-predefined annotation/documentation text. * * @return The annotation/documentation text if available, or empty string * otherwise. */ extern RTIXMLUTILSDllExport const char * RTIXMLUTILSObject_getAnnotationDocText( struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief checks whether the specified object is a text element */ extern RTIXMLUTILSDllExport RTIBool RTIXMLUTILSObject_isText( struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Encloses all children of this node under the RTI file path * processing instruction with the specified file name as content. * * @return True on success */ extern RTIXMLUTILSDllExport RTIBool RTIXMLUTILSObject_setFilePathFragment( struct RTIXMLUTILSObject *self, const char *fileName); /** \ingroup RTIXMLUTILSParserModule * * @brief Returns the content of the RTI file path processing instruction * where this node is enclosed. * * @return The PI node value or NULL if there is no PI. */ extern RTIXMLUTILSDllExport const char * RTIXMLUTILSObject_getFilePath( struct RTIXMLUTILSObject *self); /** \ingroup RTIXMLUTILSParserModule * * @brief Adds or replace the content of the specified attribute * * @return True on success */ extern RTIXMLUTILSDllExport RTIBool RTIXMLUTILSObject_setAttribute( struct RTIXMLUTILSObject *self, const char *name, const char *value); /** \ingroup RTIXMLUTILSParserModule * * @brief Removes the specified attribute */ extern RTIXMLUTILSDllExport void RTIXMLUTILSObject_removeAttribute( struct RTIXMLUTILSObject *self, const char *name); /** \ingroup RTIXMLUTILSParserModule * * @brief Adds a new PI to this node */ extern RTIXMLUTILSDllExport RTIBool RTIXMLUTILSObject_addProcessingInstruction( struct RTIXMLUTILSObject *self, const char *name, const char *content); /** \ingroup RTIXMLUTILSParserModule * * @brief Finds the content of the specified PI. * * @return The content or NULL if not found */ extern RTIXMLUTILSDllExport const char * RTIXMLUTILSObject_lookUpProcessingInstruction( struct RTIXMLUTILSObject *self, const char *name); /** \ingroup RTIXMLUTILSParserModule * * @brief Replaces the tag name of this object * */ extern RTIXMLUTILSDllExport void RTIXMLUTILSObject_setTagName( struct RTIXMLUTILSObject *self, const char *tagName); /** \ingroup RTIXMLUTILSParserModule * * @brief Replaces the name of this object without adding the attribute * in the dom. * */ extern RTIXMLUTILSDllExport void RTIXMLUTILSObject_setName( struct RTIXMLUTILSObject *self, const char *name); /** \ingroup RTIXMLUTILSParserModule * * @brief Sets the text content of this element. * */ extern RTIXMLUTILSDllExport void RTIXMLUTILSObject_setText( struct RTIXMLUTILSObject *self, const char *elementText); #ifdef __cplusplus } /* extern "C" */ #endif #endif /* rtixmlutils_object_h */