DCMTK: DSRXMLDocument Class Reference

DCMTK Version 3.6.9 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Static Protected Member Functions | Private Attributes | List of all members
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
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 character encoding handler for converting internally stored character strings (UTF-8) to a particular character set.
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.
DSRXMLCursor | getNamedChildNode (const DSRXMLCursor &cursor, const char *name, const OFBool required=OFTrue) const
| get a particular named child 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 | printMissingAttributeWarning (const DSRXMLCursor &cursor, const char *name) const
| print warning message for missing attribute
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
virtual | ~DSRTypes ()
| destructor.

## Static Protected Member Functions
static OFString & | getFullNodePath (const DSRXMLCursor &cursor, OFString &stringValue, const OFBool omitCurrent=OFFalse)
| get the full path (incl. all predecessors) to the current node
static const char * | documentTypeToSOPClassUID (const E_DocumentType documentType)
| convert SR document type to SOP class UID
static const char * | documentTypeToModality (const E_DocumentType documentType)
| convert SR document type to modality
static const char * | documentTypeToReadableName (const E_DocumentType documentType)
| convert SR document type to readable name.
static const char * | documentTypeToDocumentTitle (const E_DocumentType documentType, OFString &documentTitle)
| convert SR document type to document title.
static OFBool | requiresEnhancedEquipmentModule (const E_DocumentType documentType)
| check whether a given SR document type requires the Enhanced General Equipment Module
static OFBool | requiresTimezoneModule (const E_DocumentType documentType)
| check whether a given SR document type requires the Timezone Module
static OFBool | requiresSynchronizationModule (const E_DocumentType documentType)
| check whether a given SR document type requires the Synchronization Module
static OFBool | usesSRDocumentSeriesModule (const E_DocumentType documentType)
| check whether a given SR document type uses the SR Document Series Module (instead of the Key Object Document Series Module)
static OFBool | usesKeyObjectDocumentSeriesModule (const E_DocumentType documentType)
| check whether a given SR document type uses the Key Object Document Series Module (instead of the SR Document Series Module)
static OFBool | usesSRDocumentGeneralModule (const E_DocumentType documentType)
| check whether a given SR document type uses the SR Document General Module (instead of the Key Object Document Module)
static OFBool | usesKeyObjectDocumentModule (const E_DocumentType documentType)
| check whether a given SR document type uses the Key Object Document Module (instead of the SR Document General Module)
static const char * | relationshipTypeToDefinedTerm (const E_RelationshipType relationshipType)
| convert relationship type to DICOM defined term
static const char * | relationshipTypeToReadableName (const E_RelationshipType relationshipType)
| convert relationship type to readable name.
static const char * | valueTypeToDefinedTerm (const E_ValueType valueType)
| convert value type to DICOM defined term
static const char * | valueTypeToXMLTagName (const E_ValueType valueType)
| convert value type to XML tag name
static const char * | valueTypeToReadableName (const E_ValueType valueType)
| convert value type to readable name.
static const char * | presentationStateTypeToShortName (const E_PresentationStateType pstateType)
| convert presentation state type to short name.
static const char * | graphicTypeToEnumeratedValue (const E_GraphicType graphicType)
| convert graphic type to DICOM enumerated value
static const char * | graphicTypeToReadableName (const E_GraphicType graphicType)
| convert graphic type to readable name.
static const char * | graphicType3DToEnumeratedValue (const E_GraphicType3D graphicType)
| convert graphic type (3D) to DICOM enumerated value
static const char * | graphicType3DToReadableName (const E_GraphicType3D graphicType)
| convert graphic type (3D) to readable name.
static const char * | temporalRangeTypeToEnumeratedValue (const E_TemporalRangeType temporalRangeType)
| convert temporal range type to DICOM enumerated value
static const char * | temporalRangeTypeToReadableName (const E_TemporalRangeType temporalRangeType)
| convert temporal range type to readable name.
static const char * | continuityOfContentToEnumeratedValue (const E_ContinuityOfContent continuityOfContent)
| convert continuity of content flag to DICOM enumerated value
static const char * | preliminaryFlagToEnumeratedValue (const E_PreliminaryFlag preliminaryFlag)
| convert preliminary flag to DICOM enumerated value
static const char * | completionFlagToEnumeratedValue (const E_CompletionFlag completionFlag)
| convert completion flag to DICOM enumerated value
static const char * | verificationFlagToEnumeratedValue (const E_VerificationFlag verificationFlag)
| convert verification flag to DICOM enumerated value
static const char * | characterSetToDefinedTerm (const E_CharacterSet characterSet)
| convert character set to DICOM defined term
static const char * | characterSetToHTMLName (const E_CharacterSet characterSet)
| convert character set to HTML name.
static const char * | characterSetToXMLName (const E_CharacterSet characterSet)
| convert character set to XML name.
static E_DocumentType | sopClassUIDToDocumentType (const OFString &sopClassUID)
| convert SOP class UID to SR document type
static E_RelationshipType | definedTermToRelationshipType (const OFString &definedTerm)
| convert DICOM defined term to relationship type
static E_ValueType | definedTermToValueType (const OFString &definedTerm)
| convert DICOM defined term to value type
static E_PresentationStateType | sopClassUIDToPresentationStateType (const OFString &sopClassUID)
| convert SOP class UID to presentation state type
static E_ValueType | xmlTagNameToValueType (const OFString &xmlTagName)
| convert XML tag name to value type
static E_GraphicType | enumeratedValueToGraphicType (const OFString &enumeratedValue)
| convert DICOM enumerated value to graphic type
static E_GraphicType3D | enumeratedValueToGraphicType3D (const OFString &enumeratedValue)
| convert DICOM enumerated value to graphic type (3D)
static E_TemporalRangeType | enumeratedValueToTemporalRangeType (const OFString &enumeratedValue)
| convert DICOM enumerated value to temporal range type
static E_ContinuityOfContent | enumeratedValueToContinuityOfContent (const OFString &enumeratedValue)
| convert DICOM enumerated value to continuity of content flag
static E_PreliminaryFlag | enumeratedValueToPreliminaryFlag (const OFString &enumeratedValue)
| convert DICOM enumerated value to preliminary flag
static E_CompletionFlag | enumeratedValueToCompletionFlag (const OFString &enumeratedValue)
| convert DICOM enumerated value to completion flag
static E_VerificationFlag | enumeratedValueToVerificationFlag (const OFString &enumeratedValue)
| convert DICOM enumerated value to verification flag
static E_CharacterSet | definedTermToCharacterSet (const OFString &definedTerm)
| convert DICOM defined term to character set.
static OFBool | isDocumentTypeSupported (const E_DocumentType documentType)
| check whether specified SR document type is supported by this library
static const OFString & | currentDate (OFString &dateString)
| get current date in DICOM 'DA' format.
static const OFString & | currentTime (OFString &timeString)
| get current time in DICOM 'TM' format.
static const OFString & | currentDateTime (OFString &dateTimeString)
| get current date and time in DICOM 'DT' format.
static const OFString & | localTimezone (OFString &timezoneString)
| get local timezone in DICOM format.
static const OFString & | dicomToReadableDate (const OFString &dicomDate, OFString &readableDate)
| convert DICOM date string to readable format.
static const OFString & | dicomToReadableTime (const OFString &dicomTime, OFString &readableTime)
| convert DICOM time string to readable format.
static const OFString & | dicomToReadableDateTime (const OFString &dicomDateTime, OFString &readableDateTime)
| convert DICOM date time string to readable format.
static const OFString & | dicomToReadablePersonName (const OFString &dicomPersonName, OFString &readablePersonName)
| convert DICOM person name to readable format.
static const OFString & | dicomToXMLPersonName (const OFString &dicomPersonName, OFString &xmlPersonName, const OFBool writeEmptyValue=OFFalse)
| convert DICOM person name to XML format.
static const char * | numberToString (const size_t number, char *stringValue, size_t stringLength)
| convert unsigned integer number to character string
static size_t | stringToNumber (const char *stringValue)
| convert string to unsigned integer number
static const OFString & | convertToPrintString (const OFString &sourceString, OFString &printString)
| convert character string to print string.
static const OFString & | convertToHTMLString (const OFString &sourceString, OFString &markupString, const size_t flags=0, const OFBool newlineAllowed=OFFalse)
| convert character string to HTML mnenonic string.
static const OFString & | convertToXMLString (const OFString &sourceString, OFString &markupString)
| convert character string to XML mnenonic string.
static OFBool | checkForValidReference (const OFString &stringValue)
| check string for valid reference (as used for by-reference relationships).
static DSRIODConstraintChecker * | createIODConstraintChecker (const E_DocumentType documentType)
| create specified SR IOD content relationship constraint checker object.
static DSRDocumentTreeNode * | createDocumentTreeNode (const E_RelationshipType relationshipType, const E_ValueType valueType)
| create specified document tree node.
static OFCondition | addElementToDataset (OFCondition &result, DcmItem &dataset, DcmElement *delem, const OFString &vm, const OFString &type, const char *moduleName=NULL)
| add given element to the dataset.
static void | removeAttributeFromSequence (DcmSequenceOfItems &sequence, const DcmTagKey &tagKey)
| remove given attribute from the sequence.
static OFCondition | getElementFromDataset (DcmItem &dataset, DcmElement &delem)
| get element from dataset
static const char * | getStringValueFromElement (const DcmElement &delem)
| get string value from element
static const OFString & | getStringValueFromElement (const DcmElement &delem, OFString &stringValue)
| get string value from element.
static OFCondition | getStringValueFromElement (const DcmElement &delem, OFString &stringValue, const signed long pos)
| get string value from element
static const OFString & | getPrintStringFromElement (const DcmElement &delem, OFString &stringValue)
| get string value from element and convert to "print" format.
static const OFString & | getMarkupStringFromElement (const DcmElement &delem, OFString &stringValue, const OFBool convertNonASCII=OFFalse)
| get string value from element and convert to HTML/XML.
static OFCondition | getStringValueFromDataset (DcmItem &dataset, const DcmTagKey &tagKey, OFString &stringValue, const signed long pos=0)
| get string value from dataset
static OFCondition | putStringValueToDataset (DcmItem &dataset, const DcmTag &tag, const OFString &stringValue, const OFBool allowEmpty=OFTrue)
| put string value to dataset
static OFBool | checkElementValue (DcmElement *delem, const DcmTagKey &tagKey, const OFString &vm, const OFString &type, const OFCondition &searchCond=EC_Normal, const char *moduleName=NULL, const OFBool acceptViolation=OFFalse)
| check element value for correct value multiplicity and type.
static OFBool | checkElementValue (DcmElement &delem, const OFString &vm, const OFString &type, const OFCondition &searchCond=EC_Normal, const char *moduleName=NULL, const OFBool acceptViolation=OFFalse)
| check element value for correct value multiplicity and type.
static OFCondition | getAndCheckElementFromDataset (DcmItem &dataset, DcmElement &delem, const OFString &vm, const OFString &type, const char *moduleName=NULL, const OFBool acceptViolation=OFFalse)
| get element from dataset and check it for correct value multiplicity and type.
static OFCondition | getAndCheckStringValueFromDataset (DcmItem &dataset, const DcmTagKey &tagKey, OFString &stringValue, const OFString &vm, const OFString &type, const char *moduleName=NULL, const OFBool acceptViolation=OFFalse)
| get string value from dataset and check it for correct value multiplicity and type.
static void | printInvalidContentItemMessage (const char *action, const DSRDocumentTreeNode *node, const char *location=NULL)
| print the warning message that the current content item is invalid/incomplete.
static void | printContentItemErrorMessage (const char *action, const OFCondition &result, const DSRDocumentTreeNode *node, const char *location=NULL)
| print an error message for the current content item.
static void | printUnknownValueWarningMessage (const char *valueName, const char *readValue=NULL, const char *action="Reading")
| print a warning message that an unknown/unsupported value has been determined
static OFBool | writeStringValueToXML (STD_NAMESPACE ostream &stream, const OFString &stringValue, const OFString &tagName, const OFBool writeEmptyValue=OFFalse)
| write string value to XML output stream.
static OFBool | writeStringFromElementToXML (STD_NAMESPACE ostream &stream, DcmElement &delem, const OFString &tagName, const OFBool writeEmptyValue=OFFalse)
| write string value from DICOM element to XML output stream.
static size_t | createHTMLAnnexEntry (STD_NAMESPACE ostream &docStream, STD_NAMESPACE ostream &annexStream, const OFString &referenceText, size_t &annexNumber, const size_t flags=0)
| create an HTML annex entry with hyperlinks.
static size_t | createHTMLFootnote (STD_NAMESPACE ostream &docStream, STD_NAMESPACE ostream &footnoteStream, size_t &footnoteNumber, const size_t nodeID, const size_t flags=0)
| create an HTML footnote with hyperlinks
static OFCondition | appendStream (STD_NAMESPACE ostream &mainStream, OFOStringStream &tempStream, const char *heading=NULL)
| append one output stream to another.

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

## Additional Inherited Members
Protected Types inherited from DSRTypes
enum | E_DocumentType { DT_invalid , DT_unknown = DT_invalid , DT_BasicTextSR , DT_EnhancedSR , DT_ComprehensiveSR , DT_KeyObjectSelectionDocument , DT_MammographyCadSR , DT_ChestCadSR , DT_ColonCadSR , DT_ProcedureLog , DT_XRayRadiationDoseSR , DT_EnhancedXRayRadiationDoseSR , DT_SpectaclePrescriptionReport , DT_MacularGridThicknessAndVolumeReport , DT_ImplantationPlanSRDocument , DT_Comprehensive3DSR , DT_RadiopharmaceuticalRadiationDoseSR , DT_ExtensibleSR , DT_AcquisitionContextSR , DT_SimplifiedAdultEchoSR , DT_PatientRadiationDoseSR , DT_PerformedImagingAgentAdministrationSR , DT_PlannedImagingAgentAdministrationSR , DT_RenditionSelectionDocument , DT_WaveformAnnotationSR , DT_last = DT_WaveformAnnotationSR }
| SR document types (DICOM IOD) More...
enum | E_RelationshipType { RT_invalid , RT_unknown , RT_isRoot , RT_contains , RT_hasObsContext , RT_hasAcqContext , RT_hasConceptMod , RT_hasProperties , RT_inferredFrom , RT_selectedFrom , RT_last = RT_selectedFrom }
| SR relationship types. More...
enum | E_ValueType { VT_invalid , VT_Text , VT_Code , VT_Num , VT_DateTime , VT_Date , VT_Time , VT_UIDRef , VT_PName , VT_SCoord , VT_SCoord3D , VT_TCoord , VT_Composite , VT_Image , VT_Waveform , VT_Container , VT_byReference , VT_includedTemplate , VT_last = VT_includedTemplate }
| SR value types. More...
enum | E_PresentationStateType { PT_invalid , PT_unknown = PT_invalid , PT_Grayscale , PT_Color , PT_PseudoColor , PT_Blending , PT_XAXRFGrayscale , PT_GrayscalePlanarMPR , PT_CompositingPlanarMPR , PT_AdvancedBlending , PT_VolumeRendering , PT_SegmentedVolumeRendering , PT_MultipleVolumeRendering , PT_VariableModalityLUT , PT_last = PT_VariableModalityLUT }
| Softcopy presentation state types. More...
enum | E_GraphicType { GT_invalid , GT_unknown = GT_invalid , GT_Point , GT_Multipoint , GT_Polyline , GT_Circle , GT_Ellipse , GT_last = GT_Ellipse }
| SR graphic types. More...
enum | E_GraphicType3D { GT3_invalid , GT3_unknown = GT3_invalid , GT3_Point , GT3_Multipoint , GT3_Polyline , GT3_Polygon , GT3_Ellipse , GT3_Ellipsoid , GT3_last = GT3_Ellipsoid }
| SR graphic types (3D). More...
enum | E_TemporalRangeType { TRT_invalid , TRT_unknown = TRT_invalid , TRT_Point , TRT_Multipoint , TRT_Segment , TRT_Multisegment , TRT_Begin , TRT_End , TRT_last = TRT_End }
| SR temporal range types. More...
enum | E_ContinuityOfContent { COC_invalid , COC_Separate , COC_Continuous , COC_last = COC_Continuous }
| SR continuity of content flag. More...
enum | E_PreliminaryFlag { PF_invalid , PF_Preliminary , PF_Final , PF_last = PF_Final }
| SR document preliminary flag. More...
enum | E_CompletionFlag { CF_invalid , CF_Partial , CF_Complete , CF_last = CF_Complete }
| SR document completion flag. More...
enum | E_VerificationFlag { VF_invalid , VF_Unverified , VF_Verified , VF_last = VF_Verified }
| SR document verification flag. More...
enum | E_CharacterSet { CS_invalid , CS_unknown = CS_invalid , CS_ASCII , CS_default = CS_ASCII , CS_Latin1 , CS_Latin2 , CS_Latin3 , CS_Latin4 , CS_Cyrillic , CS_Arabic , CS_Greek , CS_Hebrew , CS_Latin5 , CS_Latin9 , CS_Thai , CS_Japanese , CS_Korean , CS_ChineseISO , CS_ChineseGB18030 , CS_ChineseGBK , CS_UTF8 , CS_last = CS_UTF8 }
| Specific character set. More...
enum | E_CodeValueType { CVT_auto , CVT_Short , CVT_Long , CVT_URN }
| Code value type. More...
enum | E_AddMode { AM_afterCurrent , AM_beforeCurrent , AM_belowCurrent , AM_belowCurrentBeforeFirstChild }
| Add node mode. More...
Static Protected Attributes inherited from DSRTypes
static const size_t | RF_readDigitalSignatures
| read digital signatures from dataset
static const size_t | RF_acceptUnknownRelationshipType
| accept unknown/missing relationship type
static const size_t | RF_acceptInvalidContentItemValue
| accept invalid content item value (e.g. violation of VR or VM definition)
static const size_t | RF_ignoreRelationshipConstraints
| ignore relationship constraints for this document class
static const size_t | RF_ignoreContentItemErrors
| do not abort on content item errors (e.g. missing value type specific attributes)
static const size_t | RF_skipInvalidContentItems
| do not abort when detecting an invalid content item, skip invalid sub-tree instead
static const size_t | RF_showCurrentlyProcessedItem
| show the currently processed content item (e.g. "1.2.3")
static const size_t | HF_neverExpandChildrenInline
| external: never expand child nodes inline
static const size_t | HF_alwaysExpandChildrenInline
| external: always expand child nodes inline
static const size_t | HF_renderInlineCodes
| external: render codes even if they appear inline
static const size_t | HF_useCodeDetailsTooltip
| external: render code details as a tooltip (not with HTML 3.2)
static const size_t | HF_renderConceptNameCodes
| external: render concept name codes (default: code meaning only)
static const size_t | HF_renderNumericUnitCodes
| external: render the code of the numeric measurement unit
static const size_t | HF_useCodeMeaningAsUnit
| external: use code meaning for the numeric measurement unit (default: code value)
static const size_t | HF_renderPatientTitle
| external: use patient information as document title (default: document type)
static const size_t | HF_renderNoDocumentHeader
| external: render no general document information (header)
static const size_t | HF_renderDcmtkFootnote
| external: render dcmtk/dcmsr comment at the end of the document
static const size_t | HF_renderFullData
| external: render the full data of all content items
static const size_t | HF_renderSectionTitlesInline
| external: render section titles inline (default: separate paragraph)
static const size_t | HF_copyStyleSheetContent
| external: copy Cascading Style Sheet (CSS) content to HTML file
static const size_t | HF_HTML32Compatibility
| external: output compatible to HTML version 3.2 (default: 4.01)
static const size_t | HF_XHTML11Compatibility
| external: output compatible to XHTML version 1.1 (default: HTML 4.01)
static const size_t | HF_addDocumentTypeReference
| external: add explicit reference to HTML document type (DTD)
static const size_t | HF_omitGeneratorMetaElement
| external: omit generator meta element referring to the DCMTK
static const size_t | HF_renderItemsSeparately
| internal: render items separately (for container with SEPARATE flag)
static const size_t | HF_renderItemInline
| internal: expand items inline when they are short and have no child nodes
static const size_t | HF_currentlyInsideAnnex
| internal: content item is rendered fully inside the annex
static const size_t | HF_createFootnoteReferences
| internal: create footnote references
static const size_t | HF_convertNonASCIICharacters
| internal: convert non-ASCII characters (> #127) to &#nnn;
static const size_t | HF_renderAllCodes
| shortcut: render all codes
static const size_t | HF_internalUseOnly
| shortcut: filter all flags that are only used internally
static const size_t | XF_writeEmptyTags
| write: write all tags even if their value is empty
static const size_t | XF_writeTemplateIdentification
| write: write template identification information (TID and mapping resource)
static const size_t | XF_alwaysWriteItemIdentifier
| write: always write item identifier "id", not only when item is referenced
static const size_t | XF_codeComponentsAsAttribute
| write: encode code value, coding scheme designator and coding scheme version as attribute instead of element text
static const size_t | XF_relationshipTypeAsAttribute
| write: encode relationship type as attribute instead of element text
static const size_t | XF_valueTypeAsAttribute
| write: encode value type as attribute instead of element text
static const size_t | XF_templateIdentifierAsAttribute
| write: encode template identifier as attribute instead of element text
static const size_t | XF_useDcmsrNamespace
| write: add DCMSR namespace declaration to the XML output
static const size_t | XF_addSchemaReference
| write: add Schema reference to XML document
static const size_t | XF_validateSchema
| read: validate content of XML document against Schema
static const size_t | XF_templateElementEnclosesItems
| read/write: template identification element encloses content items
static const size_t | XF_addCommentsForIncludedTemplate
| write: add comments with details at beginning/end of included template (might be useful for debugging purposes)
static const size_t | XF_acceptEmptyStudySeriesInstanceUID
| read: accept empty Study/Series/SOP Instance UID attribute values (must be filled later)
static const size_t | XF_encodeEverythingAsAttribute
| shortcut: combines all XF_xxxAsAttribute write flags (see above)
static const size_t | PF_printItemPosition
| print item position ("1.2.3") instead of line indentation
static const size_t | PF_shortenLongItemValues
| shorten long item value (e.g. long texts)
static const size_t | PF_printSOPInstanceUID
| print SOP instance UID of referenced objects
static const size_t | PF_printConceptNameCodes
| print coding scheme designator/version and code value of concept names
static const size_t | PF_printNoDocumentHeader
| print no general document information (header)
static const size_t | PF_printTemplateIdentification
| print template identification (TID and mapping resource)
static const size_t | PF_useANSIEscapeCodes
| use ANSI escape codes for output
static const size_t | PF_printLongSOPClassName
| print long SOP class name of referenced objects (default: short name for images)
static const size_t | PF_printSOPClassUID
| print SOP class UID of referenced objects (instead of the name)
static const size_t | PF_printInvalidCodes
| print code triple for invalid codes (instead of the text "invalid code")
static const size_t | PF_printNodeID
| print node ID at the beginning of each line (might be useful for debugging purposes)
static const size_t | PF_indicateEnhancedEncodingMode
| indicate with a "*" that the "enhanced encoding mode" is used for codes
static const size_t | PF_printAnnotation
| print annotation of a content item (optional, e.g. user-defined information)
static const size_t | PF_hideIncludedTemplateNodes
| do not print internal "included template" nodes (position counter is still increased)
static const size_t | PF_dontCountIncludedTemplateNodes
| do not count internal "included template" nodes (only with PF_hideIncludedTemplateNodes)
static const size_t | PF_printEmptyCodes
| print text "empty code" for empty codes (instead of "invalid code")
static const size_t | PF_printAllCodes
| shortcut: print all codes (combines all PF_printXxxCodes flags, see above)
static const size_t | CM_updatePositionString
| update the position string using the node ID
static const size_t | CM_updateNodeID
| update the node ID using the position string
static const size_t | CM_resetReferenceTargetFlag
| reset the reference target flag for all nodes
static const size_t | CB_maskPrintFlags
| bit mask (filter) for valid print flags (see PF_xxx)
static const size_t | CB_maskReadFlags
| bit mask (filter) for valid read flags (see RF_xxx)

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

## ◆ checkNode()

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

## ◆ convertUtf8ToCharset()

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)

## ◆ encodingHandlerValid()

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

## ◆ getElementFromAttribute()

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

## ◆ getElementFromNodeContent()

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

## ◆ getFullNodePath()

static OFString & DSRXMLDocument::getFullNodePath | ( | const DSRXMLCursor & | cursor,
|  | OFString & | stringValue,
|  | const OFBool | omitCurrent = OFFalse )
| staticprotected

get the full path (incl. all predecessors) to the current node

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

Returns
  resulting character string, set to "<invalid>" in case of an invalid 'cursor'

## ◆ getNamedChildNode()

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

get a particular named child node of the document.

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

Parameters

  cursor | cursor pointing to the parent of 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 if necessary.

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

## ◆ getNamedNode()

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 if necessary.

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

## ◆ getRelationshipTypeFromNode()

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, DSRTypes::RT_invalid or DSRTypes::RT_unknown otherwise

## ◆ getRootNode()

DSRXMLCursor DSRXMLDocument::getRootNode | ( |  | ) | const

get root node of the document

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

## ◆ getStringFromAttribute()

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)

## ◆ getStringFromNodeContent()

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)

## ◆ getValueTypeFromNode()

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, DSRTypes::VT_invalid otherwise

## ◆ hasAttribute()

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

## ◆ matchNode()

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

## ◆ printGeneralNodeError()

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)

## ◆ printMissingAttributeError()

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

## ◆ printMissingAttributeWarning()

void DSRXMLDocument::printMissingAttributeWarning | ( | const DSRXMLCursor & | cursor,
|  | const char * | name ) const

print warning message for missing attribute

Parameters

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

## ◆ printUnexpectedNodeWarning()

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

print warning message for unexpected node

Parameters

  cursor | cursor pointing to the unexpected node

## ◆ read()

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

## ◆ setEncodingHandler()

OFCondition DSRXMLDocument::setEncodingHandler | ( | const char * | charset | ) |

set character encoding handler for converting internally stored character strings (UTF-8) to a particular character set.

This conversion is only done when requested, e.g. when calling getStringFromAttribute() with the 'encoding' parameter being OFTrue. 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

## ◆ valid()

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 Sat Mar 1 2025 for DCMTK Version 3.6.9 by Doxygen 1.13.2