2
* VirtualBox XML helper APIs.
6
* Copyright (C) 2007-2009 Sun Microsystems, Inc.
8
* This file is part of VirtualBox Open Source Edition (OSE), as
9
* available from http://www.virtualbox.org. This file is free software;
10
* you can redistribute it and/or modify it under the terms of the GNU
11
* General Public License (GPL) as published by the Free Software
12
* Foundation, in version 2 as it comes in the "COPYING" file of the
13
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16
* The contents of this file may alternatively be used under the terms
17
* of the Common Development and Distribution License Version 1.0
18
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19
* VirtualBox OSE distribution, in which case the provisions of the
20
* CDDL are applicable instead of those of the GPL.
22
* You may elect to license modified versions of this file under the
23
* terms and conditions of either the GPL or the CDDL or both.
25
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26
* Clara, CA 95054 USA or visit http://www.sun.com if you need
27
* additional information or have any questions.
30
#ifndef ___VBox_vboxxml_h
31
#define ___VBox_vboxxml_h
34
# error "There are no XML APIs available in Ring-0 Context!"
40
#include <iprt/ministring_cpp.h>
43
typedef struct _xmlParserInput xmlParserInput;
44
typedef xmlParserInput *xmlParserInputPtr;
45
typedef struct _xmlParserCtxt xmlParserCtxt;
46
typedef xmlParserCtxt *xmlParserCtxtPtr;
47
typedef struct _xmlError xmlError;
48
typedef xmlError *xmlErrorPtr;
54
//////////////////////////////////////////////////////////////////////////////
57
* Base exception class.
59
class RT_DECL_CLASS Error : public std::exception
63
Error(const char *pcszMessage)
74
virtual ~Error() throw()
78
void operator=(const Error &s)
83
void setWhat(const char *pcszMessage)
88
virtual const char* what() const throw()
94
// hide the default constructor to make sure the extended one above is always used
100
class RT_DECL_CLASS LogicError : public Error
104
LogicError(const char *aMsg = NULL)
108
LogicError(RT_SRC_POS_DECL);
111
class RT_DECL_CLASS RuntimeError : public Error
115
RuntimeError(const char *aMsg = NULL)
120
class RT_DECL_CLASS XmlError : public RuntimeError
123
XmlError(xmlErrorPtr aErr);
125
static char* Format(xmlErrorPtr aErr);
129
//////////////////////////////////////////////////////////////////////////////
131
class RT_DECL_CLASS ENotImplemented : public LogicError
134
ENotImplemented(const char *aMsg = NULL) : LogicError(aMsg) {}
135
ENotImplemented(RT_SRC_POS_DECL) : LogicError(RT_SRC_POS_ARGS) {}
138
class RT_DECL_CLASS EInvalidArg : public LogicError
141
EInvalidArg(const char *aMsg = NULL) : LogicError(aMsg) {}
142
EInvalidArg(RT_SRC_POS_DECL) : LogicError(RT_SRC_POS_ARGS) {}
145
class RT_DECL_CLASS EDocumentNotEmpty : public LogicError
148
EDocumentNotEmpty(const char *aMsg = NULL) : LogicError(aMsg) {}
149
EDocumentNotEmpty(RT_SRC_POS_DECL) : LogicError(RT_SRC_POS_ARGS) {}
152
class RT_DECL_CLASS ENodeIsNotElement : public LogicError
155
ENodeIsNotElement(const char *aMsg = NULL) : LogicError(aMsg) {}
156
ENodeIsNotElement(RT_SRC_POS_DECL) : LogicError(RT_SRC_POS_ARGS) {}
160
//////////////////////////////////////////////////////////////////////////////
162
class RT_DECL_CLASS EIPRTFailure : public RuntimeError
166
EIPRTFailure (int aRC);
168
int rc() const { return mRC; }
176
* The Stream class is a base class for I/O streams.
178
class RT_DECL_CLASS Stream
184
virtual const char *uri() const = 0;
187
* Returns the current read/write position in the stream. The returned
188
* position is a zero-based byte offset from the beginning of the file.
190
* Throws ENotImplemented if this operation is not implemented for the
193
virtual uint64_t pos() const = 0;
196
* Sets the current read/write position in the stream.
198
* @param aPos Zero-based byte offset from the beginning of the stream.
200
* Throws ENotImplemented if this operation is not implemented for the
203
virtual void setPos (uint64_t aPos) = 0;
207
* The Input class represents an input stream.
209
* This input stream is used to read the settings tree from.
210
* This is an abstract class that must be subclassed in order to fill it with
211
* useful functionality.
213
class RT_DECL_CLASS Input : virtual public Stream
218
* Reads from the stream to the supplied buffer.
220
* @param aBuf Buffer to store read data to.
221
* @param aLen Buffer length.
223
* @return Number of bytes read.
225
virtual int read (char *aBuf, int aLen) = 0;
231
class RT_DECL_CLASS Output : virtual public Stream
236
* Writes to the stream from the supplied buffer.
238
* @param aBuf Buffer to write data from.
239
* @param aLen Buffer length.
241
* @return Number of bytes written.
243
virtual int write (const char *aBuf, int aLen) = 0;
246
* Truncates the stream from the current position and upto the end.
247
* The new file size will become exactly #pos() bytes.
249
* Throws ENotImplemented if this operation is not implemented for the
252
virtual void truncate() = 0;
256
//////////////////////////////////////////////////////////////////////////////
259
* The File class is a stream implementation that reads from and writes to
262
* The File class uses IPRT File API for file operations. Note that IPRT File
263
* API is not thread-safe. This means that if you pass the same RTFILE handle to
264
* different File instances that may be simultaneously used on different
265
* threads, you should care about serialization; otherwise you will get garbage
266
* when reading from or writing to such File instances.
268
class RT_DECL_CLASS File : public Input, public Output
273
* Possible file access modes.
275
enum Mode { Mode_Read, Mode_WriteCreate, Mode_Overwrite, Mode_ReadWrite };
278
* Opens a file with the given name in the given mode. If @a aMode is Read
279
* or ReadWrite, the file must exist. If @a aMode is Write, the file must
280
* not exist. Otherwise, an EIPRTFailure excetion will be thrown.
282
* @param aMode File mode.
283
* @param aFileName File name.
285
File(Mode aMode, const char *aFileName);
288
* Uses the given file handle to perform file operations. This file
289
* handle must be already open in necessary mode (read, or write, or mixed).
291
* The read/write position of the given handle will be reset to the
292
* beginning of the file on success.
294
* Note that the given file handle will not be automatically closed upon
295
* this object destruction.
297
* @note It you pass the same RTFILE handle to more than one File instance,
298
* please make sure you have provided serialization in case if these
299
* instasnces are to be simultaneously used by different threads.
300
* Otherwise you may get garbage when reading or writing.
302
* @param aHandle Open file handle.
303
* @param aFileName File name (for reference).
305
File(RTFILE aHandle, const char *aFileName = NULL);
308
* Destroys the File object. If the object was created from a file name
309
* the corresponding file will be automatically closed. If the object was
310
* created from a file handle, it will remain open.
314
const char *uri() const;
316
uint64_t pos() const;
317
void setPos(uint64_t aPos);
320
* See Input::read(). If this method is called in wrong file mode,
321
* LogicError will be thrown.
323
int read(char *aBuf, int aLen);
326
* See Output::write(). If this method is called in wrong file mode,
327
* LogicError will be thrown.
329
int write(const char *aBuf, int aLen);
332
* See Output::truncate(). If this method is called in wrong file mode,
333
* LogicError will be thrown.
339
/* Obscure class data */
343
/* auto_ptr data doesn't have proper copy semantics */
344
DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP (File)
348
* The MemoryBuf class represents a stream implementation that reads from the
351
class RT_DECL_CLASS MemoryBuf : public Input
355
MemoryBuf (const char *aBuf, size_t aLen, const char *aURI = NULL);
357
virtual ~MemoryBuf();
359
const char *uri() const;
361
int read(char *aBuf, int aLen);
362
uint64_t pos() const;
363
void setPos(uint64_t aPos);
366
/* Obscure class data */
370
/* auto_ptr data doesn't have proper copy semantics */
371
DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(MemoryBuf)
381
typedef xmlParserInput* FNEXTERNALENTITYLOADER(const char *aURI,
383
xmlParserCtxt *aCtxt);
384
typedef FNEXTERNALENTITYLOADER *PFNEXTERNALENTITYLOADER;
386
class RT_DECL_CLASS GlobalLock
392
void setExternalEntityLoader(PFNEXTERNALENTITYLOADER pFunc);
394
static xmlParserInput* callDefaultLoader(const char *aURI,
396
xmlParserCtxt *aCtxt);
399
/* Obscure class data. */
406
* an XML node, which represents either an element or text content
409
* For elements, getName() returns the element name, and getValue()
410
* returns the text contents, if any.
412
* For attributes, getName() returns the attribute name, and getValue()
413
* returns the attribute value, if any.
415
* Since the default constructor is private, one can create new nodes
416
* only through factory methods provided by the XML classes. These are:
418
* -- xml::Document::createRootElement()
419
* -- xml::Node::createChild()
420
* -- xml::Node::addContent()
421
* -- xml::Node::setAttribute()
425
typedef std::list<const ElementNode*> ElementNodesList;
431
class RT_DECL_CLASS Node
436
const char* getName() const;
437
bool nameEquals(const char *pcsz) const;
439
const char* getValue() const;
440
bool copyValue(int32_t &i) const;
441
bool copyValue(uint32_t &i) const;
442
bool copyValue(int64_t &i) const;
443
bool copyValue(uint64_t &i) const;
445
int getLineNumber() const;
449
return mType == IsElement;
453
typedef enum {IsElement, IsAttribute, IsContent} EnumType;
456
// hide the default constructor so people use only our factory methods
458
Node(const Node &x); // no copying
460
void buildChildren();
462
/* Obscure class data */
467
class RT_DECL_CLASS ElementNode : public Node
470
int getChildElements(ElementNodesList &children,
471
const char *pcszMatch = NULL) const;
473
const ElementNode* findChildElement(const char *pcszMatch) const;
474
const ElementNode* findChildElementFromId(const char *pcszId) const;
476
const AttributeNode* findAttribute(const char *pcszMatch) const;
477
bool getAttributeValue(const char *pcszMatch, const char *&ppcsz) const;
478
bool getAttributeValue(const char *pcszMatch, iprt::MiniString &str) const;
479
bool getAttributeValue(const char *pcszMatch, int32_t &i) const;
480
bool getAttributeValue(const char *pcszMatch, uint32_t &i) const;
481
bool getAttributeValue(const char *pcszMatch, int64_t &i) const;
482
bool getAttributeValue(const char *pcszMatch, uint64_t &i) const;
483
bool getAttributeValue(const char *pcszMatch, bool &f) const;
485
ElementNode* createChild(const char *pcszElementName);
487
ContentNode* addContent(const char *pcszContent);
488
ContentNode* addContent(const iprt::MiniString &strContent)
490
return addContent(strContent.c_str());
493
AttributeNode* setAttribute(const char *pcszName, const char *pcszValue);
494
AttributeNode* setAttribute(const char *pcszName, const iprt::MiniString &strValue)
496
return setAttribute(pcszName, strValue.c_str());
498
AttributeNode* setAttribute(const char *pcszName, int32_t i);
499
AttributeNode* setAttribute(const char *pcszName, uint32_t i);
500
AttributeNode* setAttribute(const char *pcszName, int64_t i);
501
AttributeNode* setAttribute(const char *pcszName, uint64_t i);
502
AttributeNode* setAttributeHex(const char *pcszName, uint32_t i);
503
AttributeNode* setAttribute(const char *pcszName, bool f);
506
// hide the default constructor so people use only our factory methods
508
ElementNode(const ElementNode &x); // no copying
511
friend class Document;
512
friend class XmlFileParser;
515
class RT_DECL_CLASS ContentNode : public Node
520
// hide the default constructor so people use only our factory methods
522
ContentNode(const ContentNode &x); // no copying
525
friend class ElementNode;
528
class RT_DECL_CLASS AttributeNode : public Node
533
// hide the default constructor so people use only our factory methods
535
AttributeNode(const AttributeNode &x); // no copying
538
friend class ElementNode;
546
class RT_DECL_CLASS NodesLoop
549
NodesLoop(const ElementNode &node, const char *pcszMatch = NULL);
551
const ElementNode* forAllNodes() const;
554
/* Obscure class data */
564
class RT_DECL_CLASS Document
570
Document(const Document &x);
571
Document& operator=(const Document &x);
573
const ElementNode* getRootElement() const;
574
ElementNode* getRootElement();
576
ElementNode* createRootElement(const char *pcszRootElementName);
579
friend class XmlFileParser;
580
friend class XmlFileWriter;
582
void refreshInternals();
584
/* Obscure class data */
594
class RT_DECL_CLASS XmlParserBase
600
xmlParserCtxtPtr m_ctxt;
608
class RT_DECL_CLASS XmlFileParser : public XmlParserBase
614
void read(const iprt::MiniString &strFilename, Document &doc);
617
/* Obscure class data */
621
static int ReadCallback(void *aCtxt, char *aBuf, int aLen);
622
static int CloseCallback (void *aCtxt);
630
class RT_DECL_CLASS XmlFileWriter
633
XmlFileWriter(Document &doc);
636
void write(const char *pcszFilename);
638
static int WriteCallback(void *aCtxt, const char *aBuf, int aLen);
639
static int CloseCallback (void *aCtxt);
642
/* Obscure class data */
647
#if defined(_MSC_VER)
648
#pragma warning (default:4251)
653
} // end namespace xml
655
#endif /* ___VBox_vboxxml_h */
added
removed
include/iprt/xml_cpp.h
