Class for managing sets of DICOM attributes (e.g. macros and modules). More...

Inheritance diagram for IODComponent:

Public Member Functions
	IODComponent (OFshared_ptr< DcmItem > item, OFshared_ptr< IODRules > rules, IODComponent *parent=NULL)
	Constructor.
	IODComponent (IODComponent *parent=NULL)
	Constructor, creates rules and item from scratch.
IODComponent &	operator= (const IODComponent &rhs)
	Assignment operator, copies contained item and rule set from rhs to "this" attribute set.
	IODComponent (const IODComponent &rhs)
	Copy constructor, copies reference to contained item and rule set to "this" attribute set.
virtual	~IODComponent ()
	Virtual Destructor.
virtual void	clearData ()
	Clear all attributes from the data that are handled by this module.
virtual void	inventMissing ()
	Set missing values by inventing "default values".
virtual void	resetRules ()=0
	Resets rules to their original values.
OFshared_ptr< IODRules >	getRules ()
	Get rules handled by this module.
virtual void	makeOptional ()
	Make component optional by turning all attributes requirement types of it to type 3.
virtual OFString	getName () const =0
	Get name of component.
DcmItem &	getData ()
	Get the data handled by this module.
virtual OFCondition	read (DcmItem &source, const OFBool clearOldData=OFTrue)
	Read attributes from given item into this class.
virtual OFCondition	write (DcmItem &destination)
	Write attributes from this class into given item.
virtual OFCondition	check (const OFBool quiet=OFFalse)
	Check whether this component's data satisfies the underlying rules.
virtual int	compare (const IODComponent &rhs) const
	Comparison operator for IOD Components.
virtual bool	getValueCheckOnWrite () const
	Get whether attribute value errors will be handled as errors on writing.
virtual void	setValueCheckOnWrite (const OFBool checkValue)
	Set whether attribute values should be checked on writing, i.e.

Static Public Member Functions
static OFCondition	read (DcmItem &source, IODRules &rules, DcmItem &destination, const OFString &componentName)
	Static helper function that reads attributes from given item into destination item, as determined by the provided rules and component name.
static OFCondition	write (DcmItem &source, IODRules &rules, DcmItem &destination, const OFString &componentName, const OFBool checkValue)
	Static helper function that writes attributes from given item into destination item, as determined by the provided rules and component name.

Protected Member Functions
void	ensureOwnRules ()
	Ensure this instance has its own private, writable copy of m_Rules.

Protected Attributes
OFshared_ptr< DcmItem >	m_Item
	Shared pointer to the data handled by this class.
OFshared_ptr< IODRules >	m_Rules
	Rules describing the attributes governed by this class.
IODComponent *	m_Parent
	The parent component (may be NULL) of this class.
OFBool	m_HasOwnRules
	OFTrue if m_Rules is a private copy owned solely by this instance and safe to mutate in place.
OFBool	m_ExternalRules
	OFTrue if the rules container was supplied externally via the IODComponent(item, rules, parent) constructor (shared-container pattern used e.g.
OFBool	m_CheckValueOnWrite
	Denotes whether attribute values should be checked on writing, i.e.

Detailed Description

Class for managing sets of DICOM attributes (e.g. macros and modules).

The data is hold in a container (DcmItem) that can be shared with other components, i.e. different modules that hold their data in a common container. In order to know which attributes in the container should be actually handled by a component, the component also has a set of rules, which can also be shared between different components (e.g. all modules of an IOD can share the same set of rules). For each attribute there is one rule in the rule set, denoting the requirement type (1,2,3,1C,2C), the VM, and besides others also the name of the component that the attribute belongs to (e.g. "PatientModule"). Since the component knows its own name, it can decide which attributes in the data container it is responsible for. This class is meant to support nested substructures but so far only writes attributes on a single level (including sequences). Also, in this context the class carries a parent relationship which is not used at the moment.

Static per-class default rules (performance optimization)

Creating many instances of an IODComponent subclass (e.g. CodeSequenceMacro inside per-frame functional groups of an Enhanced CT with 100,000 frames) used to allocate a fresh IODRules container and N individual IODRule objects per instance. Since the rules are usually identical for every instance of the same concrete class, this overhead is avoidable.

The optimization works as follows:

Each concrete subclass maintains a static OFshared_ptr<IODRules> (typically in an anonymous namespace in its .cc file), lazily initialized on the first instantiation of that class using a per-class OFMutex.
When resetRules() is called and no external rules container was provided (m_ExternalRules == OFFalse), the instance simply points its m_Rules shared_ptr at the class-level static. No heap allocation takes place after the very first instance of that class is created.
m_HasOwnRules is OFFalse in this state, meaning the rules are considered immutable for this instance. Any operation that needs to mutate the rule set (makeOptional(), getRules() for modification) calls ensureOwnRules() first, which performs a copy-on-write: the shared static is cloned into a new private IODRules, and m_HasOwnRules is set to OFTrue.
Calling resetRules() after makeOptional() re-points m_Rules at the static and drops the private copy (resetting to class defaults), which is the documented contract of resetRules().
When rules are provided externally via the IODComponent(item, rules, parent) constructor (m_ExternalRules == OFTrue, the pattern used by DcmIODCommon to build a single shared IODRules for all modules of an IOD), resetRules() falls back to the original behaviour and populates the shared container in place. Static defaults are still initialised on that first call so they are available for subsequent standalone instantiations.

How to implement resetRules() in a new subclass

The typical (optimized) pattern:

Declare a static OFshared_ptr<IODRules> and a static OFMutex in an anonymous namespace in the .cc file.
Lock the mutex, and if the static pointer is still null, allocate a new IODRules and add all rules to it, then unlock.
If m_ExternalRules is OFFalse, point m_Rules at the static and set m_HasOwnRules = OFFalse (sharing path). If m_ExternalRules is OFTrue, iterate the static and clone each rule into m_Rules (in-place population path used by DcmIODCommon). See any existing resetRules() implementation for a concrete example.

Exception - rules that depend on constructor arguments: If the rule set varies between instances of the same class (e.g. because a constructor argument determines which rules are added, as in CodeWithModifiers), a shared static cannot be used. In that case allocate a fresh IODRules directly into m_Rules, set m_HasOwnRules = OFTrue, and populate it normally. The rest of the copy-on-write machinery is unaffected; the instance simply starts life already owning its rules.

Constructor & Destructor Documentation

◆ IODComponent() [1/3]

IODComponent::IODComponent	(	OFshared_ptr< DcmItem >	item,
		OFshared_ptr< IODRules >	rules,
		IODComponent *	parent = NULL )

Constructor.

Parameters

item	The item to be used for data storage. If NULL, the class creates an empty data container.
rules	The rule set for this class. If NULL, the class creates an empty rule set.
parent	The parent of the IOD component (NULL if none or unknown)

References IODComponent().

Referenced by CodeSequenceMacro::CodeSequenceMacro(), CodeSequenceMacro::CodeSequenceMacro(), CodeSequenceMacro::CodeSequenceMacro(), CodeSequenceMacro::CodeSequenceMacro(), IODMultiFrameFGModule::ConcatenationInfo::ConcatenationInfo(), IODMultiframeDimensionModule::DimensionIndexItem::DimensionIndexItem(), IODMultiframeDimensionModule::DimensionIndexItem::DimensionIndexItem(), IODMultiframeDimensionModule::DimensionOrganizationItem::DimensionOrganizationItem(), IODMultiframeDimensionModule::DimensionOrganizationItem::DimensionOrganizationItem(), HL7HierarchicDesignatorMacro::HL7HierarchicDesignatorMacro(), HL7HierarchicDesignatorMacro::HL7HierarchicDesignatorMacro(), IODComponent(), IODComponent(), IODComponent(), IODSeriesAndInstanceReferenceMacro::IODSeriesAndInstanceReferenceMacro(), IODSeriesAndInstanceReferenceMacro::IODSeriesAndInstanceReferenceMacro(), MandatoryViewAndSliceProgressionDirectionMacro::MandatoryViewAndSliceProgressionDirectionMacro(), MandatoryViewAndSliceProgressionDirectionMacro::MandatoryViewAndSliceProgressionDirectionMacro(), IODSeriesAndInstanceReferenceMacro::ReferencedSeriesItem::ReferencedSeriesItem(), IODSeriesAndInstanceReferenceMacro::ReferencedSeriesItem::ReferencedSeriesItem(), ContentItemMacro::ReferencedSOPSequenceItem::ReferencedSOPSequenceItem(), ContentItemMacro::ReferencedSOPSequenceItem::ReferencedSOPSequenceItem(), FGRealWorldValueMapping::RWVMItem::RWVMItem(), FGRealWorldValueMapping::RWVMItem::RWVMItem(), SOPInstanceReferenceMacro::SOPInstanceReferenceMacro(), SOPInstanceReferenceMacro::SOPInstanceReferenceMacro(), IODCommonInstanceReferenceModule::StudiesOtherInstancesItem::StudiesOtherInstancesItem(), IODCommonInstanceReferenceModule::StudiesOtherInstancesItem::StudiesOtherInstancesItem(), CodeWithModifiers::compare(), FGRealWorldValueMapping::RWVMItem::compare(), ImageSOPInstanceReferenceMacro::compare(), compare(), and operator=().

◆ IODComponent() [2/3]

IODComponent::IODComponent ( IODComponent * parent = NULL )

Constructor, creates rules and item from scratch.

Parameters

parent The parent of the IOD component (NULL if none or unknown)

References IODComponent().

◆ IODComponent() [3/3]

IODComponent::IODComponent ( const IODComponent & rhs )

Copy constructor, copies reference to contained item and rule set to "this" attribute set.

Parameters

rhs	The component to be assigned

References IODComponent().

Member Function Documentation

◆ check()

virtual OFCondition IODComponent::check ( const OFBool quiet = OFFalse )

virtual

Check whether this component's data satisfies the underlying rules.

Parameters

quiet If OFTrue, not error / warning messages will be produced. Only the returned error code will indicate error or OK. Per default, logging output is produced (OFFalse).

Returns: EC_Normal if rules are satisfied, error otherwise

Reimplemented in CodeSequenceMacro, CodeWithModifiers, TrcTrack, and TrcTractographyResultsModule.

◆ clearData()

virtual void IODComponent::clearData ( )

virtual

Clear all attributes from the data that are handled by this module.

An attribute is considered belonging to the module if there are rules marked as belonging to this module via the rule's module name.

Reimplemented in CodeWithModifiers, IODCommonInstanceReferenceModule, IODCommonInstanceReferenceModule::StudiesOtherInstancesItem, IODGeneralStudyModule, IODICCProfileModule, IODMultiframeDimensionModule, IODPaletteColorLUTModule, IODSeriesAndInstanceReferenceMacro, IODSeriesAndInstanceReferenceMacro::ReferencedSeriesItem, MandatoryViewAndSliceProgressionDirectionMacro, TrcMeasurement, TrcStatistic, TrcTrack, TrcTrackSet, and TrcTractographyResultsModule.

Referenced by DcmIODImage<>::clearData().

◆ compare()

virtual int IODComponent::compare ( const IODComponent & rhs ) const

virtual

Comparison operator for IOD Components.

Parameters

rhs	The right hand side of the comparison

Returns: 0, if the given object is equal to this object, other value otherwise

Reimplemented in CodeWithModifiers, FGRealWorldValueMapping::RWVMItem, and ImageSOPInstanceReferenceMacro.

References IODComponent().

◆ ensureOwnRules()

void IODComponent::ensureOwnRules ( )

protected

Ensure this instance has its own private, writable copy of m_Rules.

If m_HasOwnRules is already OFTrue, this is a no-op. Otherwise (the instance is sharing the class-level static default rules) the shared IODRules object is cloned into a new heap-allocated copy owned solely by this instance, and m_HasOwnRules is set to OFTrue. Must be called before any in-place mutation of m_Rules (e.g. changing requirement types, adding ad-hoc rules).

◆ getData()

DcmItem & IODComponent::getData ( )

inline

Get the data handled by this module.

Returns: The item containing the data of this module

References m_Item.

◆ getName()

virtual OFString IODComponent::getName ( ) const

pure virtual

Get name of component.

Returns: Name of the module

Implemented in CodeSequenceMacro, CodeWithModifiers, ContentItemMacro, ContentItemMacro::ReferencedSOPSequenceItem, DPMParametricMapImageModule, DPMParametricMapSeriesModule, FGRealWorldValueMapping::RWVMItem, HL7HierarchicDesignatorMacro, IODAcquisitionContextModule, IODCommonInstanceReferenceModule, IODCommonInstanceReferenceModule::StudiesOtherInstancesItem, IODDoubleFloatingPointImagePixelModule, IODEnhancedUSSeriesModule, IODEnhGeneralEquipmentModule, IODEnhUSImageModule, IODFloatingPointImagePixelModule, IODFoRModule, IODGeneralEquipmentModule, IODGeneralImageModule, IODGeneralSeriesModule, IODGeneralStudyModule, IODICCProfileModule, IODImagePixelBase, IODImagePixelModule< T >, IODMultiframeDimensionModule::DimensionIndexItem, IODMultiframeDimensionModule::DimensionOrganizationItem, IODMultiframeDimensionModule, IODMultiFrameFGModule::ConcatenationInfo, IODMultiFrameFGModule, IODPaletteColorLUTModule, IODPatientModule, IODPatientStudyModule, IODSegmentationSeriesModule, IODSeriesAndInstanceReferenceMacro, IODSeriesAndInstanceReferenceMacro::ReferencedSeriesItem, IODSOPCommonModule, IODSynchronizationModule, IODUSFoRModule, MandatoryViewAndSliceProgressionDirectionMacro, SOPInstanceReferenceMacro, TrcMeasurement, TrcMeasurement::Values, TrcTrack, TrcTrackSet, TrcTrackSetStatistic, TrcTracksStatistic, and TrcTractographyResultsModule.

◆ getRules()

OFshared_ptr< IODRules > IODComponent::getRules ( )

Get rules handled by this module.

Triggers copy-on-write if this instance currently shares the class-level static default rules, since the caller may intend to modify them. For read-only inspection of rules, iterate m_Rules directly from a subclass or use the const read/write helpers.

Returns: The rules (private copy if copy-on-write was triggered)

◆ getValueCheckOnWrite()

virtual bool IODComponent::getValueCheckOnWrite ( ) const

virtual

Get whether attribute value errors will be handled as errors on writing.

Returns: OFTrue if attribute value errors are handled as errors on writing, OFFalse otherwise.

◆ inventMissing()

virtual void IODComponent::inventMissing ( )

virtual

Set missing values by inventing "default values".

Automatically called during write() in IODComponent. In this bas class implementation, this method checks for every rule of this component whether it has a default value, and if, invents the attribute if it is not present in the data, i.e. creating it with the default value or setting it to the default value if no value is present. This happens independently of the requirement type.

Reimplemented in IODGeneralSeriesModule, IODGeneralStudyModule, IODSOPCommonModule, and TrcTrackSet.

◆ makeOptional()

virtual void IODComponent::makeOptional ( )

virtual

Make component optional by turning all attributes requirement types of it to type 3.

In order to reset to the attribute's original types, resetRules() can be used.

◆ operator=()

IODComponent & IODComponent::operator= ( const IODComponent & rhs )

Assignment operator, copies contained item and rule set from rhs to "this" attribute set.

Performs deep copy, i.e. the contained item and the rule set are copied. The parent component is set to NULL.

Parameters

rhs	The IODComponent to be assigned

Returns: Reference to this module

References IODComponent().

◆ read() [1/2]

virtual OFCondition IODComponent::read	(	DcmItem &	source,
		const OFBool	clearOldData = OFTrue )

virtual

Read attributes from given item into this class.

Parameters

source	The source to read from
clearOldData	If OFTrue, old data is cleared before reading. Otherwise old data is overwritten (or amended)

Returns: EC_Normal if reading was successful, error otherwise

Reimplemented in CodeWithModifiers, ContentItemMacro, ContentItemMacro::ReferencedSOPSequenceItem, DPMParametricMapImageModule, DPMParametricMapSeriesModule, FGRealWorldValueMapping::RWVMItem, ImageSOPInstanceReferenceMacro, IODCommonInstanceReferenceModule, IODCommonInstanceReferenceModule::StudiesOtherInstancesItem, IODDoubleFloatingPointImagePixelModule, IODEnhancedUSSeriesModule, IODEnhUSImageModule, IODFloatingPointImagePixelModule, IODGeneralSeriesModule, IODGeneralStudyModule, IODICCProfileModule, IODImagePixelModule< T >, IODMultiframeDimensionModule, IODMultiFrameFGModule, IODPaletteColorLUTModule, IODSeriesAndInstanceReferenceMacro, IODSeriesAndInstanceReferenceMacro::ReferencedSeriesItem, MandatoryViewAndSliceProgressionDirectionMacro, TrcMeasurement, TrcStatistic, TrcTrack, TrcTrackSet, TrcTrackSetStatistic, TrcTracksStatistic, and TrcTractographyResultsModule.

Referenced by DcmIODImage<>::read().

◆ read() [2/2]

OFCondition IODComponent::read	(	DcmItem &	source,
		IODRules &	rules,
		DcmItem &	destination,
		const OFString &	componentName )

static

Static helper function that reads attributes from given item into destination item, as determined by the provided rules and component name.

The rules are only applied when reading from the source (which may result in warning messages on the logger), but if they could be found they are taken over into the destination item no matter whether the element validates against the rule.

Parameters

source	The item to read from
rules	The rules that provide the attributes and requirements for these attributes
destination	The destination to write to
componentName	The name of the module/component to write

Returns: EC_Normal if reading was successful, error otherwise

◆ setValueCheckOnWrite()

virtual void IODComponent::setValueCheckOnWrite ( const OFBool checkValue )

virtual

Set whether attribute values should be checked on writing, i.e.

if writing should fail if attribute values violate their VR, VM, character set or value length. A missing but required value is always considered an error, independent of this setting. If set to OFFalse, writing will always succeed, even if attribute value constraints are violated. A warning instead of an error will be printed to the logger.

Parameters

checkValue If OFTrue, attribute value errors are handled as errors on writing, if OFFalse any errors are ignored.

Referenced by DcmIODImage<>::setValueCheckOnWrite().

◆ write() [1/2]

virtual OFCondition IODComponent::write ( DcmItem & destination )

virtual

Write attributes from this class into given item.

Parameters

destination The item to write to

Returns: EC_Normal if writing was successful, error otherwise

Reimplemented in CodeWithModifiers, ContentItemMacro::ReferencedSOPSequenceItem, ContentItemMacro, DPMParametricMapImageModule, DPMParametricMapSeriesModule, FGRealWorldValueMapping::RWVMItem, ImageSOPInstanceReferenceMacro, IODCommonInstanceReferenceModule::StudiesOtherInstancesItem, IODCommonInstanceReferenceModule, IODDoubleFloatingPointImagePixelModule, IODEnhancedUSSeriesModule, IODEnhUSImageModule, IODFloatingPointImagePixelModule, IODGeneralSeriesModule, IODGeneralStudyModule, IODICCProfileModule, IODImagePixelModule< T >, IODMultiframeDimensionModule, IODMultiFrameFGModule, IODPaletteColorLUTModule, IODSeriesAndInstanceReferenceMacro::ReferencedSeriesItem, IODSeriesAndInstanceReferenceMacro, MandatoryViewAndSliceProgressionDirectionMacro, TrcMeasurement, TrcStatistic, TrcTrack, TrcTrackSet, TrcTrackSetStatistic, TrcTracksStatistic, and TrcTractographyResultsModule.

Referenced by DcmIODImage<>::write().

◆ write() [2/2]

OFCondition IODComponent::write	(	DcmItem &	source,
		IODRules &	rules,
		DcmItem &	destination,
		const OFString &	componentName,
		const OFBool	checkValue )

static

Static helper function that writes attributes from given item into destination item, as determined by the provided rules and component name.

The rules are only applied when writing to the destination (which may result in warning messages on the logger, and the whole call returning with an error). During reading from the source item the elements read are not validated against the rules.

Parameters

source	The item to read from
rules	The rules that provide the attributes and requirements for these attributes
destination	The destination to write to
componentName	The name of the module/component to write
checkValue	If OFTrue, attribute value errors are handled as errors on writing, if OFFalse any errors are ignored.

Returns: EC_Normal if reading was successful, error otherwise

Member Data Documentation

◆ m_CheckValueOnWrite

OFBool IODComponent::m_CheckValueOnWrite

protected

Denotes whether attribute values should be checked on writing, i.e.

if writing should fail if attribute values violate their VR, VM, character set or value length. A missing but required value is always considered an error, independent of this setting. If set to OFFalse, writing will always succeed, even if attribute values constraints are violated. A warning instead of an error will be printed to the logger. OFTrue if attribute value errors are handled as errors on writing, OFFalse otherwise.

◆ m_ExternalRules

OFBool IODComponent::m_ExternalRules

protected

OFTrue if the rules container was supplied externally via the IODComponent(item, rules, parent) constructor (shared-container pattern used e.g.

by DcmIODCommon). When OFTrue, resetRules() populates the shared container in place instead of pointing at the per-class static.

◆ m_HasOwnRules

OFBool IODComponent::m_HasOwnRules

protected

OFTrue if m_Rules is a private copy owned solely by this instance and safe to mutate in place.

OFFalse if m_Rules is the shared class-level static and must not be modified without triggering copy-on-write first.

◆ m_Item

OFshared_ptr<DcmItem> IODComponent::m_Item

protected

Shared pointer to the data handled by this class.

The item may contain more attributes than this class is actually responsible for

Referenced by getData().

◆ m_Rules

OFshared_ptr<IODRules> IODComponent::m_Rules

protected

Rules describing the attributes governed by this class.

Normally points to the class-level static default rules shared by all instances (m_HasOwnRules == OFFalse). After ensureOwnRules() is called it points to a private copy (m_HasOwnRules == OFTrue).

Referenced by CodeWithModifiers::getRules().

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

dcmiod/include/dcmtk/dcmiod/modbase.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

How to implement resetRules() in a new subclass

Constructor & Destructor Documentation

◆ IODComponent() [1/3]

◆ IODComponent() [2/3]

◆ IODComponent() [3/3]

Member Function Documentation

◆ check()

◆ clearData()

◆ compare()

◆ ensureOwnRules()

◆ getData()

◆ getName()

◆ getRules()

◆ getValueCheckOnWrite()

◆ inventMissing()

◆ makeOptional()

◆ operator=()

◆ read() [1/2]

◆ read() [2/2]

◆ setValueCheckOnWrite()

◆ write() [1/2]

◆ write() [2/2]

Member Data Documentation

◆ m_CheckValueOnWrite

◆ m_ExternalRules

◆ m_HasOwnRules

◆ m_Item

◆ m_Rules