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