DSRXMLDocument Class Reference

Class for XML documents. More...

Inheritance diagram for DSRXMLDocument:


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
OFConsole *	getLogStream () const
	get the current log stream.
void	setLogStream (OFConsole *stream)
	set the log stream.
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)
OFConsole *	LogStream
	output stream for error messages, NULL for no messages

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).

Definition at line 67 of file dsrxmld.h.

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 to the log stream 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

OFConsole* DSRXMLDocument::getLogStream ( ) const

get the current log stream.
See setLogStream() for details.
Returns:
pointer to the log stream (might be NULL = no messages)

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 to the log stream in case it is not found.

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 to the log stream 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. XF_enableLibxmlErrorOutput enables the debug output from 'libxml'.
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

void DSRXMLDocument::setLogStream ( OFConsole * stream )

set the log stream.
The log stream is used to report warning and error messages. Unfortunately, the stream cannot be used for 'libxml' messages. Therefore, the error output of 'libxml' is disabled by default (see read() for details).
Parameters:

stream pointer to the log stream (might be NULL = no messages)

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

Generated on 20 Dec 2005 for OFFIS DCMTK Version 3.5.4 by Doxygen 1.4.5

DSRXMLDocument Class Reference

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation