DSRXMLDocument Class Reference

Class for XML documents. More...

Inheritance diagram for DSRXMLDocument:

List of all members.

Public Member Functions
	DSRXMLDocument ()
	default constructor
virtual	~DSRXMLDocument ()
	destructor
void	clear ()
	clear all internal member variables
OFBool	valid () const
	check whether the current internal state is valid
OFCondition	read (const OFString &filename, const size_t flags=0)
	read XML document from file.
OFBool	encodingHandlerValid () const
	check whether the currently set character encoding handler is valid.
OFCondition	setEncodingHandler (const char *charset)
	set the specified character encoding handler.
DSRXMLCursor	getRootNode () const
	get root node of the document
DSRXMLCursor	getNamedNode (const DSRXMLCursor &cursor, const char *name, const OFBool required=OFTrue) const
	get a particular named node of the document.
OFBool	matchNode (const DSRXMLCursor &cursor, const char *name) const
	check whether particular node matches a given name
OFCondition	checkNode (const DSRXMLCursor &cursor, const char *name) const
	check whether particular node matches a given name and report an error if not
OFBool	hasAttribute (const DSRXMLCursor &cursor, const char *name) const
	check whether particular node has a specific attribute
OFString &	getStringFromAttribute (const DSRXMLCursor &cursor, OFString &stringValue, const char *name, const OFBool encoding=OFFalse, const OFBool required=OFTrue) const
	get string value from particular XML attribute.
OFCondition	getElementFromAttribute (const DSRXMLCursor &cursor, DcmElement &delem, const char *name, const OFBool encoding=OFFalse, const OFBool required=OFTrue) const
	get element value from particular XML attribute
OFString &	getStringFromNodeContent (const DSRXMLCursor &cursor, OFString &stringValue, const char *name=NULL, const OFBool encoding=OFFalse, const OFBool clearString=OFTrue) const
	get string value from particular XML element
OFCondition	getElementFromNodeContent (const DSRXMLCursor &cursor, DcmElement &delem, const char *name=NULL, const OFBool encoding=OFFalse) const
	get element value from particular XML element
E_ValueType	getValueTypeFromNode (const DSRXMLCursor &cursor) const
	get value type from particular node.
E_RelationshipType	getRelationshipTypeFromNode (const DSRXMLCursor &cursor) const
	get relationship type from particular node.
void	printUnexpectedNodeWarning (const DSRXMLCursor &cursor) const
	print warning message for unexpected node
void	printGeneralNodeError (const DSRXMLCursor &cursor, const OFCondition &result) const
	print general node error message
Protected Member Functions
OFBool	convertUtf8ToCharset (const xmlChar *fromString, OFString &toString) const
	convert given string from 'libxml' format (UTF8) to current character set
void	printMissingAttributeError (const DSRXMLCursor &cursor, const char *name) const
	print error message for missing attribute
Static Protected Member Functions
static OFString &	getFullNodePath (const DSRXMLCursor &cursor, OFString &stringValue, const OFBool omitCurrent=OFFalse)
	get the full path (incl.
Private Member Functions
	DSRXMLDocument (const DSRXMLDocument &)
DSRXMLDocument &	operator= (const DSRXMLDocument &)
Private Attributes
xmlDocPtr	Document
	pointer to the internal representation of the XML document (libxml)
xmlCharEncodingHandlerPtr	EncodingHandler
	pointer to the currently selected character encoding handler (libxml)

---

Detailed Description

Class for XML documents.

This class encapsulates the access to the 'libxml' routines. Since the public interface of this class does not use any 'libxml' specific data structures it should be possible to replace the XML library with little effort (if required).

---

Member Function Documentation

OFCondition DSRXMLDocument::checkNode	(	const DSRXMLCursor &	cursor,
		const char *	name
	)		const

check whether particular node matches a given name and report an error if not

Parameters:

cursor	cursor pointing to the particular node
name	name of the node (XML element) to be checked

Returns:

OFTrue if name matches, OFFalse otherwise

OFBool DSRXMLDocument::convertUtf8ToCharset	(	const xmlChar *	fromString,
		OFString &	toString
	)		const [protected]

convert given string from 'libxml' format (UTF8) to current character set

Parameters:

fromString	character string to be converted
toString	reference to string object in which the result should be stored

Returns:

OFTrue if successful, OFFalse otherwise (e.g. no handler selected)

OFBool DSRXMLDocument::encodingHandlerValid

(

)

const

check whether the currently set character encoding handler is valid.

If no encoding handler is set this is equivalent to an invalid handler.

Returns:

OFTrue if handler is valid, OFFalse otherwise

OFCondition DSRXMLDocument::getElementFromAttribute	(	const DSRXMLCursor &	cursor,
		DcmElement &	delem,
		const char *	name,
		const OFBool	encoding = OFFalse,
		const OFBool	required = OFTrue
	)		const

get element value from particular XML attribute

Parameters:

cursor	cursor pointing to the particular node
delem	DICOM element in which the attribute value is stored
name	name of the XML attribute to be retrieved
encoding	use encoding handler if OFTrue, ignore character set otherwise
required	flag specifying whether the attribute is required or not. If the attribute is required to be present an error message is reported in case it is not found.

Returns:

status, EC_Normal if successful, an error code otherwise

OFCondition DSRXMLDocument::getElementFromNodeContent	(	const DSRXMLCursor &	cursor,
		DcmElement &	delem,
		const char *	name = NULL,
		const OFBool	encoding = OFFalse
	)		const

get element value from particular XML element

Parameters:

cursor	cursor pointing to the particular node
delem	DICOM element in which the element value is stored
name	name of the XML element to be retrieved
encoding	use encoding handler if OFTrue, ignore character set otherwise

Returns:

status, EC_Normal if successful, an error code otherwise

static OFString& DSRXMLDocument::getFullNodePath	(	const DSRXMLCursor &	cursor,
		OFString &	stringValue,
		const OFBool	omitCurrent = OFFalse
	)		[static, protected]

get the full path (incl.

all predecessors) to the current node. Returns "<invalid>" in case of an invalid 'cursor'.

Parameters:

cursor	cursor pointing to the relevant node
stringValue	reference to string object in which the result should be stored
omitCurrent	flag indicating whether to omit the current node or not

DSRXMLCursor DSRXMLDocument::getNamedNode	(	const DSRXMLCursor &	cursor,
		const char *	name,
		const OFBool	required = OFTrue
	)		const

get a particular named node of the document.

Please note that the search process is limited to the current node level, i.e. no deep search is performed.

Parameters:

cursor	cursor pointing to the node where to start from
name	name of the node (XML element) to be searched for
required	flag specifying whether the node is required or not. If the node is required to be present an error message is reported.

Returns:

cursor pointing to the named node if successful, invalid cursor otherwise

E_RelationshipType DSRXMLDocument::getRelationshipTypeFromNode

(

const DSRXMLCursor &

cursor

)

const

get relationship type from particular node.

The relationship type is either stored in the element "relationship" or in the attribute "relType".

Parameters:

cursor

cursor pointing to the particular node

Returns:

relationship type if successful, RT_invalid/unknown otherwise

DSRXMLCursor DSRXMLDocument::getRootNode

(

)

const

get root node of the document

Returns:

cursor pointing to the root node if successful, invalid cursor otherwise

OFString& DSRXMLDocument::getStringFromAttribute	(	const DSRXMLCursor &	cursor,
		OFString &	stringValue,
		const char *	name,
		const OFBool	encoding = OFFalse,
		const OFBool	required = OFTrue
	)		const

get string value from particular XML attribute.

The result variable 'stringValue' is automatically cleared at the beginning.

Parameters:

cursor	cursor pointing to the particular node
stringValue	reference to string object in which the value should be stored
name	name of the XML attribute to be retrieved
encoding	use encoding handler if OFTrue, ignore character set otherwise
required	flag specifying whether the attribute is required or not. If the attribute is required to be present an error message is reported in case it is not found.

Returns:

reference to string object (might be empty)

OFString& DSRXMLDocument::getStringFromNodeContent	(	const DSRXMLCursor &	cursor,
		OFString &	stringValue,
		const char *	name = NULL,
		const OFBool	encoding = OFFalse,
		const OFBool	clearString = OFTrue
	)		const

get string value from particular XML element

Parameters:

cursor	cursor pointing to the particular node
stringValue	reference to string object in which the value should be stored
name	name of the XML element to be retrieved
encoding	use encoding handler if OFTrue, ignore character set otherwise
clearString	flag specifying whether to clear the 'stringValue' at first or not

Returns:

reference to string object (might be empty)

E_ValueType DSRXMLDocument::getValueTypeFromNode

(

const DSRXMLCursor &

cursor

)

const

get value type from particular node.

The value type is either stored as the element name or in the attribute "valType". Additionally, by-reference relationships are also supported (either by attribute "ref" being present or element named "reference").

Parameters:

cursor

cursor pointing to the particular node

Returns:

value type (incl. by-reference) if successful, VT_invalid/unknown otherwise

OFBool DSRXMLDocument::hasAttribute	(	const DSRXMLCursor &	cursor,
		const char *	name
	)		const

check whether particular node has a specific attribute

Parameters:

cursor	cursor pointing to the particular node
name	name of the XML attribute to be checked

Returns:

OFTrue if attribute is present, OFFalse otherwise

OFBool DSRXMLDocument::matchNode	(	const DSRXMLCursor &	cursor,
		const char *	name
	)		const

check whether particular node matches a given name

Parameters:

cursor	cursor pointing to the particular node
name	name of the node (XML element) to be checked

Returns:

OFTrue if name matches, OFFalse otherwise

void DSRXMLDocument::printGeneralNodeError	(	const DSRXMLCursor &	cursor,
		const OFCondition &	result
	)		const

print general node error message

Parameters:

cursor	cursor pointing to the unexpected node
result	status used to print details on the error (no message if EC_Normal)

void DSRXMLDocument::printMissingAttributeError	(	const DSRXMLCursor &	cursor,
		const char *	name
	)		const [protected]

print error message for missing attribute

Parameters:

cursor	cursor pointing to the relevant node
name	name of the XML attribute

void DSRXMLDocument::printUnexpectedNodeWarning

(

const DSRXMLCursor &

cursor

)

const

print warning message for unexpected node

Parameters:

cursor

cursor pointing to the unexpected node

OFCondition DSRXMLDocument::read	(	const OFString &	filename,
		const size_t	flags = 0
	)

read XML document from file.

In order to enable the optional Schema validation the flag XF_validateSchema has to be set.

Parameters:

filename	name of the file from which the XML document is read ("-" for stdin)
flags	optional flag used to customize the reading process (see DSRTypes::XF_xxx)

Returns:

status, EC_Normal if successful, an error code otherwise

OFCondition DSRXMLDocument::setEncodingHandler

(

const char *

charset

)

set the specified character encoding handler.

NB: 'libxml' relies on GNU 'libiconv' for most character sets.

Parameters:

charset

XML name of the character set (e.g. "ISO-8859-1" for ISO Latin-1)

Returns:

status, EC_Normal if successful, an error code otherwise

OFBool DSRXMLDocument::valid

(

)

const

check whether the current internal state is valid

Returns:

OFTrue if valid, OFFalse otherwise

---

The documentation for this class was generated from the following file:

• dcmsr/include/dcmtk/dcmsr/dsrxmld.h