DSRXMLDocument Class Reference

Class for XML documents. More...

Inheritance diagram for DSRXMLDocument:

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

Definition at line 63 of file dsrxmld.h.

Member Function Documentation

OFBool DSRXMLDocument::valid (  )  const

check whether the current internal state is valid

Returns:
OFTrue if valid, OFFalse otherwise

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

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::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

DSRXMLCursor DSRXMLDocument::getRootNode (  )  const

get root node of the document

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

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

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

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::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

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)

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

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)

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

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

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

void DSRXMLDocument::printUnexpectedNodeWarning ( const DSRXMLCursor &  cursor  )  const

print warning message for unexpected node

Parameters:
cursor cursor pointing to the unexpected node

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)

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)

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

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

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

Generated on 6 Jan 2011 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.5.1