1 /**********************************************************************
2  *
3  * Project:  CPL - Common Portability Library
4  * Purpose:  Declarations for MiniXML Handler.
5  * Author:   Frank Warmerdam, warmerdam@pobox.com
6  *
7  **********************************************************************
8  * Copyright (c) 2001, Frank Warmerdam
9  *
10  * Permission is hereby granted, free of charge, to any person obtaining a
11  * copy of this software and associated documentation files (the "Software"),
12  * to deal in the Software without restriction, including without limitation
13  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
14  * and/or sell copies of the Software, and to permit persons to whom the
15  * Software is furnished to do so, subject to the following conditions:
16  *
17  * The above copyright notice and this permission notice shall be included
18  * in all copies or substantial portions of the Software.
19  *
20  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
23  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
25  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
26  * DEALINGS IN THE SOFTWARE.
27  **********************************************************************
28  *
29  * $Log: cpl_minixml.h,v $
30  * Revision 1.1.1.1  2006/08/21 05:52:19  dsr
31  * Initial import as opencpn, GNU Automake compliant.
32  *
33  * Revision 1.1.1.1  2006/04/19 03:23:28  dsr
34  * Rename/Import to OpenCPN
35  *
36  * Revision 1.11  2004/01/29 15:29:28  warmerda
37  * Added CPLCleanXMLElementName
38  *
39  * Revision 1.10  2003/12/04 15:46:51  warmerda
40  * Added CPLAddXMLSibling()
41  *
42  * Revision 1.9  2003/11/05 20:14:21  warmerda
43  * added lots of documentation
44  *
45  * Revision 1.8  2003/03/27 18:12:41  warmerda
46  * Added NULL pszNameSpace support in namespace stripper (all namespaces).
47  * Added XML file read/write functions.
48  *
49  * Revision 1.7  2003/03/24 16:46:48  warmerda
50  * added CPLStripXMLNamespace
51  *
52  * Revision 1.6  2002/11/16 20:38:34  warmerda
53  * added support for literals like DOCTYPE
54  *
55  * Revision 1.5  2002/05/24 04:09:10  warmerda
56  * added clone and SetXMLValue functions
57  *
58  * Revision 1.4  2002/03/05 14:26:57  warmerda
59  * expanded tabs
60  *
61  * Revision 1.3  2002/01/23 20:45:06  warmerda
62  * handle <?...?> and comment elements
63  *
64  * Revision 1.2  2001/12/06 18:13:49  warmerda
65  * added CPLAddXMLChild and CPLCreateElmentAndValue
66  *
67  * Revision 1.1  2001/11/16 15:39:48  warmerda
68  * New
69  *
70  **********************************************************************/
71 
72 #ifndef _CPL_MINIXML_H_INCLUDED
73 #define _CPL_MINIXML_H_INCLUDED
74 
75 #include "cpl_port.h"
76 
77 /**
78  * \file cpl_minixml.h
79  *
80  * Definitions for CPL mini XML Parser/Serializer.
81  */
82 
83 CPL_C_START
84 
85 typedef enum
86 {
87     /*! Node is an element */           CXT_Element = 0,
88     /*! Node is a raw text value */     CXT_Text = 1,
89     /*! Node is attribute */            CXT_Attribute = 2,
90     /*! Node is an XML comment. */      CXT_Comment = 3,
91     /*! Node is a special literal */    CXT_Literal = 4
92 } CPLXMLNodeType;
93 
94 /**
95  * Document node structure.
96  *
97  * This C structure is used to hold a single text fragment representing a
98  * component of the document when parsed.   It should be allocated with the
99  * appropriate CPL function, and freed with CPLDestroyXMLNode().  The structure
100  * contents should not normally be altered by application code, but may be
101  * freely examined by application code.
102  *
103  * Using the psChild and psNext pointers, a heirarchical tree structure
104  * for a document can be represented as a tree of CPLXMLNode structures.
105  */
106 
107 typedef struct _CPLXMLNode
108 {
109     /**
110      * Node type
111      *
112      * One of CXT_Element, CXT_Text, CXT_Attribute, CXT_Comment,
113      * or CXT_Literal.
114      */
115     CPLXMLNodeType      eType;
116 
117     /**
118      * Node value
119      *
120      * For CXT_Element this is the name of the element, without the angle
121      * brackets.  Note there is a single CXT_Element even when the document
122      * contains a start and end element tag.  The node represents the pair.
123      * All text or other elements between the start and end tag will appear
124      * as children nodes of this CXT_Element node.
125      *
126      * For CXT_Attribute the pszValue is the attribute name.  The value of
127      * the attribute will be a CXT_Text child.
128      *
129      * For CXT_Text this is the text itself (value of an attribute, or a
130      * text fragment between an element start and end tags.
131      *
132      * For CXT_Literal it is all the literal text.  Currently this is just
133      * used for !DOCTYPE lines, and the value would be the entire line.
134      *
135      * For CXT_Comment the value is all the literal text within the comment,
136      * but not including the comment start/end indicators ("<--" and "-->").
137      */
138     char                *pszValue;
139 
140     /**
141      * Next sibling.
142      *
143      * Pointer to next sibling, that is the next node appearing after this
144      * one that has the same parent as this node.  NULL if this node is the
145      * last child of the parent element.
146      */
147     struct _CPLXMLNode  *psNext;
148 
149     /**
150      * Child node.
151      *
152      * Pointer to first child node, if any.  Only CXT_Element and CXT_Attribute
153      * nodes should have children.  For CXT_Attribute it should be a single
154      * CXT_Text value node, while CXT_Attribute can have any kind of child.
155      * The full list of children for a node are identified by walking the
156      * psNext's starting with the psChild node.
157      */
158 
159     struct _CPLXMLNode  *psChild;
160 } CPLXMLNode;
161 
162 
163 CPLXMLNode CPL_DLL *CPLParseXMLString( const char * );
164 void       CPL_DLL  CPLDestroyXMLNode( CPLXMLNode * );
165 CPLXMLNode CPL_DLL *CPLGetXMLNode( CPLXMLNode *poRoot,
166                                    const char *pszPath );
167 const char CPL_DLL *CPLGetXMLValue( CPLXMLNode *poRoot,
168                                     const char *pszPath,
169                                     const char *pszDefault );
170 CPLXMLNode CPL_DLL *CPLCreateXMLNode( CPLXMLNode *poParent,
171                                       CPLXMLNodeType eType,
172                                       const char *pszText );
173 char       CPL_DLL *CPLSerializeXMLTree( CPLXMLNode *psNode );
174 void       CPL_DLL  CPLAddXMLChild( CPLXMLNode *psParent,
175                                     CPLXMLNode *psChild );
176 void       CPL_DLL  CPLAddXMLSibling( CPLXMLNode *psOlderSibling,
177                                       CPLXMLNode *psNewSibling );
178 CPLXMLNode CPL_DLL *CPLCreateXMLElementAndValue( CPLXMLNode *psParent,
179                                                  const char *pszName,
180                                                  const char *pszValue );
181 CPLXMLNode CPL_DLL *CPLCloneXMLTree( CPLXMLNode *psTree );
182 int        CPL_DLL CPLSetXMLValue( CPLXMLNode *psRoot,  const char *pszPath,
183                                    const char *pszValue );
184 void       CPL_DLL CPLStripXMLNamespace( CPLXMLNode *psRoot,
185                                          const char *pszNameSpace,
186                                          int bRecurse );
187 void       CPL_DLL CPLCleanXMLElementName( char * );
188 
189 CPLXMLNode CPL_DLL *CPLParseXMLFile( const char *pszFilename );
190 int        CPL_DLL CPLSerializeXMLTreeToFile( CPLXMLNode *psTree,
191                                               const char *pszFilename );
192 
193 CPL_C_END
194 
195 #endif /* _CPL_MINIXML_H_INCLUDED */
196