1 /*===========================================================================
2 *
3 *                            PUBLIC DOMAIN NOTICE
4 *               National Center for Biotechnology Information
5 *
6 *  This software/database is a "United States Government Work" under the
7 *  terms of the United States Copyright Act.  It was written as part of
8 *  the author's official duties as a United States Government employee and
9 *  thus cannot be copyrighted.  This software/database is freely available
10 *  to the public for use. The National Library of Medicine and the U.S.
11 *  Government have not placed any restriction on its use or reproduction.
12 *
13 *  Although all reasonable efforts have been taken to ensure the accuracy
14 *  and reliability of the software and data, the NLM and the U.S.
15 *  Government do not and cannot warrant the performance or results that
16 *  may be obtained by using this software or data. The NLM and the U.S.
17 *  Government disclaim all warranties, express or implied, including
18 *  warranties of performance, merchantability or fitness for any particular
19 *  purpose.
20 *
21 *  Please cite the author in any work or product based on this material.
22 *
23 * ===========================================================================
24 *
25 */
26 
27 #ifndef _h_kxml_xml_
28 #define _h_kxml_xml_
29 
30 #ifndef _h_klib_extern_
31 #include <klib/extern.h>
32 #endif
33 
34 #include <klib/defs.h>
35 
36 #include <stdarg.h>
37 
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42 
43 
44 /*--------------------------------------------------------------------------
45  * forwards
46  */
47 struct KFile;
48 struct KNamelist;
49 struct KXMLNodeset;
50 
51 
52 /*--------------------------------------------------------------------------
53  * XML node
54  */
55 typedef struct KXMLNode KXMLNode;
56 
57 /* AddRef
58  * Release
59  */
60 KLIB_EXTERN rc_t CC KXMLNodeAddRef ( const KXMLNode *self );
61 KLIB_EXTERN rc_t CC KXMLNodeRelease ( const KXMLNode *self );
62 
63 /* GetName
64  * Get node path from parent nodeset
65  */
66 KLIB_EXTERN rc_t CC KXMLNodeGetName ( const KXMLNode *self, const char **name );
67 
68 /* Get element name (tag)
69  */
70 KLIB_EXTERN rc_t CC KXMLNodeElementName ( const KXMLNode *self, const char **name );
71 
72 /* Read
73  */
74 KLIB_EXTERN rc_t CC KXMLNodeRead ( const KXMLNode *self,
75     size_t offset, void *buffer, size_t size,
76     size_t *num_read, size_t *remaining );
77 
78 /* Write
79  */
80 KLIB_EXTERN rc_t CC KXMLNodeWrite ( KXMLNode *self,
81     size_t offset, const void *buffer, size_t size );
82 
83 /* Append
84  */
85 KLIB_EXTERN rc_t CC KXMLNodeAppend ( KXMLNode *self,
86     const void *buffer, size_t bsize );
87 
88 
89 /* ReadAs ( formatted )
90  *  reads as integer or float value in native byte order
91  *  casts smaller-sized values to desired size, e.g.
92  *    uint32_t to uint64_t
93  *
94  *  "i" [ OUT ] - return parameter for signed integer
95  *  "u" [ OUT ] - return parameter for unsigned integer
96  *  "f" [ OUT ] - return parameter for double float
97  */
98 KLIB_EXTERN rc_t CC KXMLNodeReadAsI16 ( const KXMLNode *self, int16_t *i );
99 KLIB_EXTERN rc_t CC KXMLNodeReadAsU16 ( const KXMLNode *self, uint16_t *u );
100 KLIB_EXTERN rc_t CC KXMLNodeReadAsI32 ( const KXMLNode *self, int32_t *i );
101 KLIB_EXTERN rc_t CC KXMLNodeReadAsU32 ( const KXMLNode *self, uint32_t *u );
102 KLIB_EXTERN rc_t CC KXMLNodeReadAsI64 ( const KXMLNode *self, int64_t *i );
103 KLIB_EXTERN rc_t CC KXMLNodeReadAsU64 ( const KXMLNode *self, uint64_t *u );
104 KLIB_EXTERN rc_t CC KXMLNodeReadAsF64 ( const KXMLNode *self, double *f );
105 
106 
107 /* ReadCString ( formatted )
108  *  reads as C-string
109  *
110  *  "buffer" [ OUT ] and "bsize" [ IN ] - output buffer for
111  *  NUL terminated string.
112  *
113  *  "size" [ OUT ] - return parameter giving size of string
114  *  not including NUL byte. the size is set both upon success
115  *  and insufficient buffer space error.
116  */
117 KLIB_EXTERN rc_t CC KXMLNodeReadCString ( const KXMLNode *self,
118     char *buffer, size_t bsize, size_t *size );
119 
120 /* ReadCStr
121  *  reads node value as C-string
122  *
123  *  "str" [ IN ] - returned pointer to a NULL terminated string.
124  *                 Caller responsible to dealloc (free)!
125  *  "default_value" [IN] - default value used in case node value is empty, NULL - none
126  */
127 KLIB_EXTERN rc_t CC KXMLNodeReadCStr( const KXMLNode *self, char** str, const char* default_value );
128 
129 /* Write ( formatted )
130  *  writes string
131  *
132  *  "str" [ IN ] - NULL terminated string.
133  */
134 KLIB_EXTERN rc_t CC KXMLNodeWriteCString ( KXMLNode *self, const char *str );
135 
136 
137 /* OpenNodesetRead
138  *
139  * NB. OpenNodesetRead could return Nodeset with 0 elements.
140  *  To make sure the node exists you should verify that (KXMLNodesetCount > 0)
141  */
142 KLIB_EXTERN rc_t CC KXMLNodeOpenNodesetRead ( const KXMLNode *self,
143     struct KXMLNodeset const **ns, const char *path, ... );
144 KLIB_EXTERN rc_t CC KXMLNodeVOpenNodesetRead ( const KXMLNode *self,
145     struct KXMLNodeset const **ns, const char *path, va_list args );
146 
147 /* OpenNodesetUpdate
148  */
149 KLIB_EXTERN rc_t CC KXMLNodeOpenNodesetUpdate ( KXMLNode *self,
150     struct KXMLNodeset **ns, const char *path, ... );
151 KLIB_EXTERN rc_t CC KXMLNodeVOpenNodesetUpdate ( KXMLNode *self,
152     struct KXMLNodeset **ns, const char *path, va_list args );
153 
154 /* ReadAttr
155  */
156 KLIB_EXTERN rc_t CC KXMLNodeReadAttr ( const KXMLNode *self,
157      const char *attr, void *buffer, size_t bsize,
158      size_t *num_read, size_t *remaining );
159 
160 /* WriteAttr
161  */
162 KLIB_EXTERN rc_t CC KXMLNodeWriteAttr ( KXMLNode *self,
163      const char *attr, const void *buffer, size_t size );
164 
165 
166 /* ReadAttrAs ( formatted )
167  *  reads as integer or float value in native byte order
168  *  casts smaller-sized values to desired size, e.g.
169  *    uint32_t to uint64_t
170  *
171  *  "i" [ OUT ] - return parameter for signed integer
172  *  "u" [ OUT ] - return parameter for unsigned integer
173  *  "f" [ OUT ] - return parameter for double float
174  */
175 KLIB_EXTERN rc_t CC KXMLNodeReadAttrAsI16 ( const KXMLNode *self, const char *attr, int16_t *i );
176 KLIB_EXTERN rc_t CC KXMLNodeReadAttrAsU16 ( const KXMLNode *self, const char *attr, uint16_t *u );
177 KLIB_EXTERN rc_t CC KXMLNodeReadAttrAsI32 ( const KXMLNode *self, const char *attr, int32_t *i );
178 KLIB_EXTERN rc_t CC KXMLNodeReadAttrAsU32 ( const KXMLNode *self, const char *attr, uint32_t *u );
179 KLIB_EXTERN rc_t CC KXMLNodeReadAttrAsI64 ( const KXMLNode *self, const char *attr, int64_t *i );
180 KLIB_EXTERN rc_t CC KXMLNodeReadAttrAsU64 ( const KXMLNode *self, const char *attr, uint64_t *u );
181 KLIB_EXTERN rc_t CC KXMLNodeReadAttrAsF64 ( const KXMLNode *self, const char *attr, double *f );
182 
183 
184 /* ReadAttrCString ( formatted )
185  *  reads as C-string
186  *
187  *  "buffer" [ OUT ] and "bsize" [ IN ] - output buffer for
188  *  NUL terminated string.
189  *
190  *  "size" [ OUT ] - return parameter giving size of string
191  *  not including NUL byte. the size is set both upon success
192  *  and insufficient buffer space error.
193  */
194 KLIB_EXTERN rc_t CC KXMLNodeReadAttrCString ( const KXMLNode *self, const char *attr,
195     char *buffer, size_t bsize, size_t *size );
196 
197 /* ReadAttrCStr
198  *  reads attribute as C-string
199  *
200  *  "str" [ IN ] - returned pointer to a NULL terminated string.
201  *                 Caller responsible to dealloc (free)!
202  *  "default_value" [IN] - default value used in case node value is empty, NULL - none
203  */
204 KLIB_EXTERN rc_t CC KXMLNodeReadAttrCStr( const KXMLNode *self, const char *attr, char** str, const char* default_value);
205 
206 /* CountChildNodes
207  *  count child nodes
208  */
209 KLIB_EXTERN rc_t CC KXMLNodeCountChildNodes(const KXMLNode *self,
210     uint32_t *count);
211 
212 /* GetNodeRead
213  *  access indexed node
214  *  "idx" [ IN ] - a zero-based index
215  */
216 KLIB_EXTERN rc_t CC KXMLNodeGetNodeRead ( const KXMLNode *self,
217     const KXMLNode **node, uint32_t idx );
218 
219 /* ListAttr
220  *  list all named attributes
221  */
222 KLIB_EXTERN rc_t CC KXMLNodeListAttr ( const KXMLNode *self,
223     struct KNamelist const **names );
224 
225 /* ListChild
226  *  list all named children
227  */
228 KLIB_EXTERN rc_t CC KXMLNodeListChild ( const KXMLNode *self,
229     struct KNamelist const **names );
230 
231 
232 /* GetFirstChildNodeRead
233  *  Returns the first(with index 0) sub-node of self using path.
234  *  Is equivalent to:
235  *          KXMLNodeOpenNodesetRead(self, &nc, path, ...);
236  *          KXMLNodesetGetNodeRead(ns, node, 0);
237  *  It will return NotFound error if any node exists
238  */
239 KLIB_EXTERN rc_t CC KXMLNodeGetFirstChildNodeRead ( const KXMLNode *self,
240     const KXMLNode **node, const char *path, ... );
241 KLIB_EXTERN rc_t CC KXMLNodeVGetFirstChildNodeRead ( const KXMLNode *self,
242     const KXMLNode **node, const char *path, va_list args );
243 
244 
245 /*--------------------------------------------------------------------------
246  * XML node set
247  */
248 typedef struct KXMLNodeset KXMLNodeset;
249 
250 /* AddRef
251  * Release
252  */
253 KLIB_EXTERN rc_t CC KXMLNodesetAddRef ( const KXMLNodeset *self );
254 KLIB_EXTERN rc_t CC KXMLNodesetRelease ( const KXMLNodeset *self );
255 
256 /* Count
257  *  retrieve the number of nodes in set
258  */
259 KLIB_EXTERN rc_t CC KXMLNodesetCount ( const KXMLNodeset *self, uint32_t *count );
260 
261 /* GetNode
262  *  access indexed node
263  *  "idx" [ IN ] - a zero-based index
264  */
265 KLIB_EXTERN rc_t CC KXMLNodesetGetNodeRead ( const KXMLNodeset *self,
266     const KXMLNode **node, uint32_t idx );
267 
268 
269 /*--------------------------------------------------------------------------
270  * XML document
271  */
272 typedef struct KXMLDoc KXMLDoc;
273 
274 /* AddRef
275  * Release
276  *  ignores NULL references
277  */
278 KLIB_EXTERN rc_t CC KXMLDocAddRef ( const KXMLDoc *self );
279 KLIB_EXTERN rc_t CC KXMLDocRelease ( const KXMLDoc *self );
280 
281 /* OpenNodesetRead
282  *  opens a node set with given path
283  */
284 KLIB_EXTERN rc_t CC KXMLDocOpenNodesetRead ( const KXMLDoc *self,
285     const KXMLNodeset **ns, const char *path, ... );
286 KLIB_EXTERN rc_t CC KXMLDocVOpenNodesetRead ( const KXMLDoc *self,
287     const KXMLNodeset **ns, const char *path, va_list args );
288 
289 /* OpenNodesetUpdate
290  *  opens a node set with given path
291  */
292 KLIB_EXTERN rc_t CC KXMLDocOpenNodesetUpdate ( KXMLDoc *self,
293     KXMLNodeset **ns, const char *path, ... );
294 KLIB_EXTERN rc_t CC KXMLDocVOpenNodesetUpdate ( KXMLDoc *self,
295     KXMLNodeset **ns, const char *path, va_list args );
296 
297 
298 /*--------------------------------------------------------------------------
299  * XML manager
300  */
301 typedef struct KXMLMgr KXMLMgr;
302 
303 /* Make
304  *  make an XML manager object
305  */
306 KLIB_EXTERN rc_t CC KXMLMgrMakeRead ( const KXMLMgr **mgr );
307 
308 /* AddRef
309  * Release
310  *  ignores NULL references
311  */
312 KLIB_EXTERN rc_t CC KXMLMgrAddRef ( const KXMLMgr *self );
313 KLIB_EXTERN rc_t CC KXMLMgrRelease ( const KXMLMgr *self );
314 
315 /* MakeDoc
316  *  create a document object from source file
317  */
318 KLIB_EXTERN rc_t CC KXMLMgrMakeDocRead ( const KXMLMgr *self,
319     const KXMLDoc **doc, struct KFile const *src );
320 
321 /* MakeDoc
322  *  create a document object from memory
323  */
324 KLIB_EXTERN rc_t KXMLMgrMakeDocReadFromMemory ( const KXMLMgr *self,
325     const KXMLDoc **result, const char* buffer, uint64_t size );
326 
327 /*--------------------------------------------------------------------------
328  * KDirectory
329  *  this will probably be relocated later on
330  */
331 struct KDirectory;
332 struct KFile;
333 struct String;
334 struct VFSManager;
335 struct VPath;
336 
337 /* OpenXTocDirRead
338  *  open copycat XML as a chroot'd directory
339  *  XML data comes from a KFile in this case
340  *
341  *  "dir" [ OUT ] - return parameter for directory object
342  *
343  *  "base_path" [ IN ] - NUL terminated string giving the path
344  *   of the new directory relative to "self". NB - can be absolute
345  *   or relative, but is always interpreted by "self".
346  *
347  *  "xml" [ IN ] - file containing XML data produced by copycat tool
348  */
349 rc_t CC KDirectoryOpenXTocDirRead (const struct KDirectory * self,
350                                    const struct KDirectory ** pnew_dir,
351                                    bool chroot,
352                                    const struct KFile * xml,
353                                    const char * path, ... );
354 rc_t CC KDirectoryVOpenXTocDirRead (const struct KDirectory * self,
355                                     const struct KDirectory ** pnew_dir,
356                                     bool chroot,
357                                     const struct KFile * xml,
358                                     const char * _path,
359                                     va_list args );
360 rc_t CC KDirectoryOpenXTocDirRead (const struct KDirectory * self,
361                                    const struct KDirectory ** pnew_dir,
362                                    bool chroot,
363                                    const struct KFile * xml,
364                                    const char * path, ... );
365 rc_t CC KDirectoryOpenXTocDirReadDir (const struct KDirectory * self,
366                                       const struct KDirectory ** pnew_dir,
367                                       const struct KFile * xml,
368                                       const struct String * spath);
369 
370 rc_t CC VFSManagerOpenXTocDirRead (const struct VFSManager * self,
371                                    const struct KDirectory ** pnew_dir,
372                                    const struct KFile * xml,
373                                    const struct VPath * path);
374 
375 
376 
377 
378 #ifdef __cplusplus
379 }
380 #endif
381 
382 #endif /* _h_kxml_xml_ */
383