DSRDocumentTree Class Reference

Class managing the SR document tree. More...

Inheritance diagram for DSRDocumentTree:

DSRTree DSRTreeNodeCursor DSRTypes List of all members.

Public Member Functions

 DSRDocumentTree (const E_DocumentType documentType)
 constructor
virtual ~DSRDocumentTree ()
 destructor
virtual void clear ()
 clear internal member variables.
virtual OFBool isValid () const
 check whether the current internal state is valid.
void setLogStream (OFConsole *stream)
 set the log stream.
OFCondition print (ostream &stream, const size_t flags=0)
 print current SR document tree to specified output stream
OFCondition read (DcmItem &dataset, const E_DocumentType documentType, const size_t flags=0)
 read SR document tree from DICOM dataset.
OFCondition write (DcmItem &dataset, DcmStack *markedItems=NULL)
 write current SR document tree to DICOM dataset
OFCondition readXML (const DSRXMLDocument &doc, DSRXMLCursor cursor, const size_t flags)
 read XML document tree
OFCondition writeXML (ostream &stream, const size_t flags)
 write current SR document tree in XML format
OFCondition renderHTML (ostream &docStream, ostream &annexStream, const size_t flags=0)
 render current SR document tree in HTML format
E_DocumentType getDocumentType () const
 get document type return current document type (might be DT_invalid)
OFCondition changeDocumentType (const E_DocumentType documentType)
 change document type.
OFBool canAddContentItem (const E_RelationshipType relationshipType, const E_ValueType valueType, const E_AddMode addMode=AM_afterCurrent)
 check whether specified content item can be added to the current one.
OFBool canAddByReferenceRelationship (const E_RelationshipType relationshipType, const E_ValueType targetValueType)
 check whether specified by-reference relationship can be added to the current content item.
size_t addContentItem (const E_RelationshipType relationshipType, const E_ValueType valueType, const E_AddMode addMode=AM_afterCurrent)
 add specified content item to the current one.
size_t addByReferenceRelationship (const E_RelationshipType relationshipType, const size_t referencedNodeID)
 add specified by-reference relationship to the current content item.
size_t removeCurrentContentItem ()
 remove current content item from tree.
DSRContentItem & getCurrentContentItem ()
 get reference to current content item.
size_t gotoNamedNode (const DSRCodedEntryValue &conceptName, const OFBool startFromRoot=OFTrue, const OFBool searchIntoSub=OFTrue)
 set internal cursor to the named node.
size_t gotoNextNamedNode (const DSRCodedEntryValue &conceptName, const OFBool searchIntoSub=OFTrue)
 set internal cursor to the next named node.
void unmarkAllContentItems ()
 unmark all content items in the document tree.
void removeSignatures ()
 remove digital signatures from the document tree.
OFBool containsExtendedCharacters ()
 check if this object contains non-ASCII characters in one of the strings affected by SpecificCharacterSet in DICOM

Protected Member Functions

virtual size_t addNode (DSRDocumentTreeNode *node, const E_AddMode addMode=AM_afterCurrent)
 add new node to the current one.
virtual size_t removeNode ()
 remove current node from tree.
OFCondition checkByReferenceRelationships (const OFBool updateString=OFFalse, const OFBool updateNodeID=OFFalse)
 check the by-reference relationships (if any) for validity.

Private Member Functions

virtual size_t addNode (DSRTreeNode *node, const E_AddMode addMode=AM_afterCurrent)
 add new node to the current one.
 DSRDocumentTree (const DSRDocumentTree &)
DSRDocumentTree & operator= (const DSRDocumentTree &)

Private Attributes

E_DocumentType DocumentType
 document type of the associated SR document
OFConsole * LogStream
 output stream for error messages, NULL for no messages
DSRContentItem CurrentContentItem
 current content item. Introduced to avoid the external use of pointers.
DSRIODConstraintChecker * ConstraintChecker
 check relationship content constraints of the associated IOD

Detailed Description

Class managing the SR document tree.

Definition at line 60 of file dsrdoctr.h.

Constructor & Destructor Documentation

DSRDocumentTree::DSRDocumentTree (  const E_DocumentType  documentType  ) 
 

constructor

Parameters:
documentType document type of the associated document

Member Function Documentation

size_t DSRDocumentTree::addByReferenceRelationship (  const E_RelationshipType  relationshipType,
const size_t  referencedNodeID
) 
 

add specified by-reference relationship to the current content item.

If possible this method creates a new pseudo-node (relationship) and adds it to the current one. The method canAddByReferenceRelationship() is called internally to check parameters first. The internal cursor is automatically re-set to the current node.

Parameters:
relationshipType relationship type between current and referenced node
referencedNodeID node ID of the referenced content item
Returns:
ID of new pseudo-node if successful, 0 otherwise

size_t DSRDocumentTree::addContentItem (  const E_RelationshipType  relationshipType,
const E_ValueType  valueType,
const E_AddMode  addMode = AM_afterCurrent
) 
 

add specified content item to the current one.

If possible this method creates a new node as specified and adds it to the current one. The method canAddContentItem() is called internally to check parameters first.

Parameters:
relationshipType relationship type of node to be added with regard to the current one
valueType value type of node to be added
addMode flag specifying at which position to add the new node. (AM_afterCurrent, AM_beforeCurrent, AM_belowCurrent)
Returns:
ID of new node if successful, 0 otherwise

virtual size_t DSRDocumentTree::addNode (  DSRTreeNode *  node,
const E_AddMode  addMode = AM_afterCurrent
)  [private, virtual]
 

add new node to the current one.

This method just overwrites the method from the base class DSRTree. Use the above addNode() method instead.

Parameters:
node dummy parameter
addMode dummy parameter
Returns:
always 0 (invalid)

Reimplemented from DSRTree.

virtual size_t DSRDocumentTree::addNode (  DSRDocumentTreeNode *  node,
const E_AddMode  addMode = AM_afterCurrent
)  [protected, virtual]
 

add new node to the current one.

Please note that no copy of the given node is created. Therefore, the node should be created with new() - do not use a reference to a local variable. If the node could be added successfully the cursor is set to it automatically.

Parameters:
node pointer to the new node to be added
addMode flag specifying at which position to add the new node. (AM_afterCurrent, AM_beforeCurrent, AM_belowCurrent)
Returns:
ID of the new added node if successful, 0 otherwise

OFBool DSRDocumentTree::canAddByReferenceRelationship (  const E_RelationshipType  relationshipType,
const E_ValueType  targetValueType
) 
 

check whether specified by-reference relationship can be added to the current content item.

Always returns true if no constraint checker is available.

Parameters:
relationshipType type of relationship between current and target node
targetValueType value type of the referenced target node
Returns:
OFTrue if specified by-reference relationship can be added, OFFalse otherwise

OFBool DSRDocumentTree::canAddContentItem (  const E_RelationshipType  relationshipType,
const E_ValueType  valueType,
const E_AddMode  addMode = AM_afterCurrent
) 
 

check whether specified content item can be added to the current one.

If the tree is currently empty only a CONTAINER with the internal relationship type RT_isRoot is allowed (as the new root node). Always returns true if no constraint checker is available. This method can be used to decide which type of content items can be added prior to really do so.

Parameters:
relationshipType relationship type of node to be checked with regard to the current one
valueType value type of node to be checked
addMode flag specifying at which position the new node would be added. (AM_afterCurrent, AM_beforeCurrent, AM_belowCurrent)
Returns:
OFTrue if specified node can be added, OFFalse otherwise

OFCondition DSRDocumentTree::changeDocumentType (  const E_DocumentType  documentType  ) 
 

change document type.

Please note that the document tree is deleted if the specified 'documentType' is supported. Otherwise the current document remains in force.

Parameters:
documentType new document type to be set (should be != DT_invalid)
Returns:
status, EC_Normal if successful, an error code otherwise

OFCondition DSRDocumentTree::checkByReferenceRelationships (  const OFBool  updateString = OFFalse,
const OFBool  updateNodeID = OFFalse
)  [protected]
 

check the by-reference relationships (if any) for validity.

This function checks whether all by-reference relationships possibly contained in the document tree are valid according to the following restrictions: source and target node are not identical and the target node is not an ancestor of the source node (requirement from the DICOM standard to prevent loops -> directed acyclic graph, though this is not 100% true - see "reportlp.dcm" example). In addition, the position strings (used to encode by-reference relationships according to the DICOM standard) OR the node IDs (used internally to uniquely identify nodes) can be updated. Please note that the flags 'updateString' and 'updateNodeID' are mutually exclusive.

Parameters:
updateString update the position string using the node ID if OFTrue
updateNodeID update the node ID using the position string if OFTrue
Returns:
status, EC_Normal if successful, an error code otherwise

virtual void DSRDocumentTree::clear (   )  [virtual]
 

clear internal member variables.

The document type is not changed (e.g. set to DT_invalid).

Reimplemented from DSRTree.

OFBool DSRDocumentTree::containsExtendedCharacters (   ) 
 

check if this object contains non-ASCII characters in one of the strings affected by SpecificCharacterSet in DICOM

Returns:
true if node contains non-ASCII characters, false otherwise

DSRContentItem& DSRDocumentTree::getCurrentContentItem (   ) 
 

get reference to current content item.

This mechanism allows to access all content items without using pointers.

Returns:
reference to current content item (might be invalid)

size_t DSRDocumentTree::gotoNamedNode (  const DSRCodedEntryValue &  conceptName,
const OFBool  startFromRoot = OFTrue,
const OFBool  searchIntoSub = OFTrue
) 
 

set internal cursor to the named node.

If more than one node exists with the given concept name the first one will be selected. Use gotoNextNamedNode() in order to go to the next matching node.

Parameters:
conceptName concept name of the node to be searched for
startFromRoot flag indicating whether to start from the root node or the current one
searchIntoSub flag indicating whether to search into sub-trees ("deep search") or on the current level only
Returns:
ID of the new current node if successful, 0 otherwise

size_t DSRDocumentTree::gotoNextNamedNode (  const DSRCodedEntryValue &  conceptName,
const OFBool  searchIntoSub = OFTrue
) 
 

set internal cursor to the next named node.

Starts from "next" node, i.e. either the first children of the current node or the first sibling following the current node.

Parameters:
conceptName concept name of the node to be searched for
searchIntoSub flag indicating whether to search into sub-trees ("deep search") or on the current level only
Returns:
ID of the new current node if successful, 0 otherwise

virtual OFBool DSRDocumentTree::isValid (   )  const [virtual]
 

check whether the current internal state is valid.

The SR document is valid if the document type is supported, the tree is not empty the root item is a container and has the internal relationship type RT_isRoot.

Returns:
OFTrue if valid, OFFalse otherwise

Reimplemented from DSRTreeNodeCursor.

OFCondition DSRDocumentTree::print (  ostream &  stream,
const size_t  flags = 0
) 
 

print current SR document tree to specified output stream

Parameters:
stream output stream
flags flag used to customize the output (see DSRTypes::PF_xxx)
Returns:
status, EC_Normal if successful, an error code otherwise

OFCondition DSRDocumentTree::read (  DcmItem &  dataset,
const E_DocumentType  documentType,
const size_t  flags = 0
) 
 

read SR document tree from DICOM dataset.

Please note that the current document tree is also deleted if the reading fails. If the log stream is set and valid the reason for any error might be obtained from the error/warning output.

Parameters:
dataset reference to DICOM dataset where the tree should be read from
documentType document type of the SR document from which the tree is read
flags flag used to customize the reading process (see DSRTypes::RF_xxx)
Returns:
status, EC_Normal if successful, an error code otherwise

OFCondition DSRDocumentTree::readXML (  const DSRXMLDocument &  doc,
DSRXMLCursor  cursor,
const size_t  flags
) 
 

read XML document tree

Parameters:
doc document containing the XML file content
cursor cursor pointing to the starting node
flags optional flag used to customize the reading process (see DSRTypes::XF_xxx)
Returns:
status, EC_Normal if successful, an error code otherwise

size_t DSRDocumentTree::removeCurrentContentItem (   ) 
 

remove current content item from tree.

Please note that not only the specified node but also all of its child nodes are removed from the tree and then deleted. The internal cursor is set automatically to a new valid position.

Returns:
ID of the node which became the current one after deletion, 0 if an error occured or the tree is now empty.

virtual size_t DSRDocumentTree::removeNode (   )  [protected, virtual]
 

remove current node from tree.

Please note that not only the specified node but also all of his child nodes are removed from the tree and deleted afterwards. The cursor is set automatically to a new valid position.

Returns:
ID of the node which became the current one after deletion, 0 if an error occured or the tree is now empty.

Reimplemented from DSRTree.

void DSRDocumentTree::removeSignatures (   ) 
 

remove digital signatures from the document tree.

This method clears the MACParametersSequence and the DigitalSignaturesSequence for all content items which have been filled during reading.

OFCondition DSRDocumentTree::renderHTML (  ostream &  docStream,
ostream &  annexStream,
const size_t  flags = 0
) 
 

render current SR document tree in HTML format

Parameters:
docStream output stream to which the main HTML document is written
annexStream output stream to which the HTML document annex is written
flags flag used to customize the output (see DSRTypes::HF_xxx)
Returns:
status, EC_Normal if successful, an error code otherwise

void DSRDocumentTree::setLogStream (  OFConsole *  stream  ) 
 

set the log stream.

The log stream is used to report any warnings and error messages.

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

void DSRDocumentTree::unmarkAllContentItems (   ) 
 

unmark all content items in the document tree.

Use method 'setMark' on node-level to mark and unmark a single content item. Pointers to the DICOM dataset/item of marked content items are added to the optional stack when calling the 'write' method. This mechanism can e.g. be used to digitally sign particular content items.

OFCondition DSRDocumentTree::write (  DcmItem &  dataset,
DcmStack *  markedItems = NULL
) 
 

write current SR document tree to DICOM dataset

Parameters:
dataset reference to DICOM dataset where the current tree should be written to
markedItems optional stack where pointers to all 'marked' content items (DICOM datasets/items) are added to during the write process. Can be used to digitally sign parts of the document tree.
Returns:
status, EC_Normal if successful, an error code otherwise

OFCondition DSRDocumentTree::writeXML (  ostream &  stream,
const size_t  flags
) 
 

write current SR document tree in XML format

Parameters:
stream output stream to which the XML document is written
flags flag used to customize the output (see DSRTypes::XF_xxx)
Returns:
status, EC_Normal if successful, an error code otherwise

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

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