DYTSrouce/Tool/3rdParty_x64/include/dcmtk/dcmsr/dsrcitem.h
2024-11-22 23:19:31 +08:00

618 lines
26 KiB
C++

/*
*
* Copyright (C) 2000-2016, OFFIS e.V.
* All rights reserved. See COPYRIGHT file for details.
*
* This software and supporting documentation were developed by
*
* OFFIS e.V.
* R&D Division Health
* Escherweg 2
* D-26121 Oldenburg, Germany
*
*
* Module: dcmsr
*
* Author: Joerg Riesmeier
*
* Purpose:
* classes: DSRContentItem
*
*/
#ifndef DSRCITEM_H
#define DSRCITEM_H
#include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */
#include "dcmtk/dcmsr/dsrtypes.h"
#include "dcmtk/dcmsr/dsrdoctn.h"
#include "dcmtk/dcmsr/dsrcodvl.h"
#include "dcmtk/dcmsr/dsrnumvl.h"
#include "dcmtk/dcmsr/dsrscovl.h"
#include "dcmtk/dcmsr/dsrsc3vl.h"
#include "dcmtk/dcmsr/dsrtcovl.h"
#include "dcmtk/dcmsr/dsrcomvl.h"
#include "dcmtk/dcmsr/dsrimgvl.h"
#include "dcmtk/dcmsr/dsrwavvl.h"
/*---------------------*
* class declaration *
*---------------------*/
/** Interface class for content items.
* This class allows to access the document tree nodes without using any pointers.
*/
class DCMTK_DCMSR_EXPORT DSRContentItem
: protected DSRTypes
{
// allow DSRDocumentSubTree to access protected method setTreeNode()
friend class DSRDocumentSubTree;
public:
/** copy constructor.
* Internally, the copy constructor of the respective tree node class is used, so the
* corresponding comments apply. This also means that the copy describes a separate
* content item, i.e. without relationships to other content items.
** @param item content item to be copied
*/
DSRContentItem(const DSRContentItem &item);
/** destructor
*/
virtual ~DSRContentItem();
/** check for validity/completeness.
* Applicable to all content items.
** @return OFTrue if current content item is valid, OFFalse otherwise
*/
OFBool isValid() const;
/** check for mark flag.
* Applicable to all content items.
** @return OFTrue if current content item is marked, OFFalse otherwise
*/
OFBool isMarked() const;
/** mark/unmark item.
* Applicable to all content items.
** @param flag mark item if OFTrue, unmark otherwise
*/
void setMark(const OFBool flag);
/** get value type.
* Applicable to all content items.
** @return value type of current content item if valid, DSRTypes::VT_invalid otherwise
*/
E_ValueType getValueType() const;
/** get relationship type.
* Applicable to all content items.
** @return relationship type of current content item if valid, DSRTypes::RT_invalid
* otherwise
*/
E_RelationshipType getRelationshipType() const;
/** get ID of the referenced node.
* Applicable to: by-reference relationships
** @return ID of the referenced node if valid, 0 otherwise
*/
size_t getReferencedNodeID() const;
/** get string value.
* Applicable to: TEXT, DATETIME, DATE, TIME, UIDREF, PNAME
** @return string value of current content item if valid, EmptyString otherwise
*/
const OFString &getStringValue() const;
/** set string value.
* Please use the correct format for the string value depending on the corresponding
* content item (value type).
*
* Applicable to: TEXT, DATETIME, DATE, TIME, UIDREF, PNAME
** @param stringValue value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setStringValue(const OFString &stringValue,
const OFBool check = OFTrue);
/** get pointer to code value.
* Applicable to: CODE
** @return pointer to code value of current content item if valid, NULL otherwise
*/
DSRCodedEntryValue *getCodeValuePtr();
/** get code value.
* Applicable to: CODE
** @return coded entry value of current content item if valid, EmptyCodedEntry otherwise
*/
const DSRCodedEntryValue &getCodeValue() const;
/** get copy of code value.
* Applicable to: CODE
** @param codeValue variable where the copy should be stored
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getCodeValue(DSRCodedEntryValue &codeValue) const;
/** set code value.
* Applicable to: CODE
** @param codeValue value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setCodeValue(const DSRCodedEntryValue &codeValue,
const OFBool check = OFTrue);
/** get pointer to numeric value.
* Applicable to: NUM
** @return pointer to numeric value of current content item if valid, NULL otherwise
*/
DSRNumericMeasurementValue *getNumericValuePtr();
/** get numeric value.
* Applicable to: NUM
** @return numeric measurement value of current content item if valid,
* EmptyNumericMeasurement otherwise
*/
const DSRNumericMeasurementValue &getNumericValue() const;
/** get copy of numeric value.
* Applicable to: NUM
** @param numericValue variable where the copy should be stored
* (cleared if an error occurs)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getNumericValue(DSRNumericMeasurementValue &numericValue) const;
/** set numeric value.
* Applicable to: NUM
** @param numericValue value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setNumericValue(const DSRNumericMeasurementValue &numericValue,
const OFBool check = OFTrue);
/** get pointer to spatial coordinates.
* Applicable to: SCOORD
** @return pointer to spatial coordinates value of current content item if valid,
* NULL otherwise
*/
DSRSpatialCoordinatesValue *getSpatialCoordinatesPtr();
/** get spatial coordinates.
* Applicable to: SCOORD
** @return spatial coordinates value of current content item if valid,
* EmptySpatialCoordinates otherwise
*/
const DSRSpatialCoordinatesValue &getSpatialCoordinates() const;
/** get copy of spatial coordinates.
* Applicable to: SCOORD
** @param coordinatesValue variable where the copy should be stored
* (cleared if an error occurs)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getSpatialCoordinates(DSRSpatialCoordinatesValue &coordinatesValue) const;
/** set spatial coordinates.
* Applicable to: SCOORD
** @param coordinatesValue value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setSpatialCoordinates(const DSRSpatialCoordinatesValue &coordinatesValue,
const OFBool check = OFTrue);
/** get pointer to spatial coordinates 3D.
* Applicable to: SCOORD3D
** @return pointer to spatial coordinates 3D value of current content item if valid,
* NULL otherwise
*/
DSRSpatialCoordinates3DValue *getSpatialCoordinates3DPtr();
/** get spatial coordinates 3D.
* Applicable to: SCOORD3D
** @return spatial coordinates 3D value of current content item if valid,
* EmptySpatialCoordinates3D otherwise
*/
const DSRSpatialCoordinates3DValue &getSpatialCoordinates3D() const;
/** get copy of spatial coordinates 3D.
* Applicable to: SCOORD3D
** @param coordinatesValue variable where the copy should be stored
* (cleared if an error occurs)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getSpatialCoordinates3D(DSRSpatialCoordinates3DValue &coordinatesValue) const;
/** set spatial coordinates 3D.
* Applicable to: SCOORD3D
** @param coordinatesValue value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setSpatialCoordinates3D(const DSRSpatialCoordinates3DValue &coordinatesValue,
const OFBool check = OFTrue);
/** get pointer to temporal coordinates.
* Applicable to: TCOORD
** @return pointer to temporal coordinates value of current content item if valid,
* NULL otherwise
*/
DSRTemporalCoordinatesValue *getTemporalCoordinatesPtr();
/** get temporal coordinates.
* Applicable to: TCOORD
** @return temporal coordinates value of current content item if valid,
* EmptyTemporalCoordinates otherwise
*/
const DSRTemporalCoordinatesValue &getTemporalCoordinates() const;
/** get copy of temporal coordinates.
* Applicable to: TCOORD
** @param coordinatesValue variable where the copy should be stored
* (cleared if an error occurs)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getTemporalCoordinates(DSRTemporalCoordinatesValue &coordinatesValue) const;
/** set temporal coordinates.
* Applicable to: TCOORD
** @param coordinatesValue value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setTemporalCoordinates(const DSRTemporalCoordinatesValue &coordinatesValue,
const OFBool check = OFTrue);
/** get pointer to composite reference.
* Applicable to: COMPOSITE
** @return pointer to reference value of current content item if valid, NULL otherwise
*/
DSRCompositeReferenceValue *getCompositeReferencePtr();
/** get composite reference.
* Applicable to: COMPOSITE
** @return reference value of current content item if valid, EmptyReference otherwise
*/
const DSRCompositeReferenceValue &getCompositeReference() const;
/** get copy of composite reference.
* Applicable to: COMPOSITE
** @param referenceValue variable where the copy should be stored
* (cleared if an error occurs)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getCompositeReference(DSRCompositeReferenceValue &referenceValue) const;
/** set composite reference.
* Applicable to: COMPOSITE
** @param referenceValue value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setCompositeReference(const DSRCompositeReferenceValue &referenceValue,
const OFBool check = OFTrue);
/** get pointer to image reference.
* Applicable to: IMAGE
** @return pointer to image reference value of current content item if valid,
* NULL otherwise
*/
DSRImageReferenceValue *getImageReferencePtr();
/** get image reference.
* Applicable to: IMAGE
** @return image reference value of current content item if valid,
* EmptyImageReference otherwise
*/
const DSRImageReferenceValue &getImageReference() const;
/** get copy of image reference.
* Applicable to: IMAGE
** @param referenceValue variable where the copy should be stored
* (cleared if an error occurs)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getImageReference(DSRImageReferenceValue &referenceValue) const;
/** set image reference.
* Applicable to: IMAGE
** @param referenceValue value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setImageReference(const DSRImageReferenceValue &referenceValue,
const OFBool check = OFTrue);
/** get pointer to waveform reference.
* Applicable to: WAVEFORM
** @return pointer to waveform reference value of current content item if valid,
* NULL otherwise
*/
DSRWaveformReferenceValue *getWaveformReferencePtr();
/** get waveform reference.
* Applicable to: WAVEFORM
** @return waveform reference value of current content item if valid,
* EmptyWaveformReference otherwise
*/
const DSRWaveformReferenceValue &getWaveformReference() const;
/** get copy of waveform reference.
* Applicable to: WAVEFORM
** @param referenceValue variable where the copy should be stored
* (cleared if an error occurs)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getWaveformReference(DSRWaveformReferenceValue &referenceValue) const;
/** set waveform reference.
* Applicable to: WAVEFORM
** @param referenceValue value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setWaveformReference(const DSRWaveformReferenceValue &referenceValue,
const OFBool check = OFTrue);
/** get continuity of content flag.
* This flag specifies whether or not its contained content items (child nodes) are
* logically linked in a continuous textual flow, or are separate items.
*
* Applicable to: CONTAINER
** @return continuity of content flag if successful, DSRTypes::COC_invalid otherwise
*/
E_ContinuityOfContent getContinuityOfContent() const;
/** set continuity of content flag.
* This flag specifies whether or not its contained content items (child nodes) are
* logically linked in a continuous textual flow, or are separate items.
*
* Applicable to: CONTAINER
** @param continuityOfContent value to be set
* (should be different from DSRTypes::COC_invalid)
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setContinuityOfContent(const E_ContinuityOfContent continuityOfContent,
const OFBool check = OFTrue);
/** get template identifier and mapping resource.
* This value pair identifies the template that was used to create this content item
* (and its children). According to the DICOM standard this is "required if a template
* was used to define the content of this Item, and the template consists of a single
* CONTAINER with nested content, and it is the outermost invocation of a set of
* nested templates that start with the same CONTAINER."
* The identification is valid if both values are either present (non-empty) or absent
* (empty).
*
* Applicable to: CONTAINER
** @param templateIdentifier identifier of the template (might be empty)
* @param mappingResource mapping resource that defines the template
* (might be empty)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getTemplateIdentification(OFString &templateIdentifier,
OFString &mappingResource) const;
/** get template identifier and mapping resource and optional mapping resource UID.
* This value triple identifies the template that was used to create this content item
* (and its children). According to the DICOM standard, this is "required if a template
* was used to define the content of this Item, and the template consists of a single
* CONTAINER with nested content, and it is the outermost invocation of a set of
* nested templates that start with the same CONTAINER."
* The identification is valid if the first two values are either present (non-empty) or
* all three are absent (empty).
*
* Applicable to: CONTAINER
** @param templateIdentifier identifier of the template (might be empty)
* @param mappingResource mapping resource that defines the template
* (might be empty)
* @param mappingResourceUID uniquely identifies the mapping resource
* (might be empty)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getTemplateIdentification(OFString &templateIdentifier,
OFString &mappingResource,
OFString &mappingResourceUID) const;
/** set template identifier and mapping resource.
* The identification is valid if the first two values are either present (non-empty)
* or all three values are absent (empty). See getTemplateIdentification() for details.
* Please use the correct DICOM format for all values (VR=CS,CS,UI).
*
* Applicable to: CONTAINER
** @param templateIdentifier identifier of the template to be set
* @param mappingResource mapping resource that defines the template
* @param mappingResourceUID uniquely identifies the mapping resource (optional)
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setTemplateIdentification(const OFString &templateIdentifier,
const OFString &mappingResource,
const OFString &mappingResourceUID = "",
const OFBool check = OFTrue);
/** get pointer to concept name.
* Code describing the concept represented by this content item. Also conveys the value
* of document title and section headings in documents.
* Applicable to all content items (by-value only).
** @return pointer to concept name value of current content item if valid, NULL otherwise
*/
DSRCodedEntryValue *getConceptNamePtr();
/** get concept name.
* Code describing the concept represented by this content item. Also conveys the value
* of document title and section headings in documents.
*
* Applicable to all content items (by-value only).
** @return concept name value of current content item if valid, EmptyCodedEntry otherwise
*/
const DSRCodedEntryValue &getConceptName() const;
/** get copy of concept name.
* Code describing the concept represented by this content item. Also conveys the value
* of document title and section headings in documents.
*
* Applicable to all content items (by-value only).
** @param conceptName variable where the copy should be stored
* (cleared if an error occurs)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition getConceptName(DSRCodedEntryValue &conceptName) const;
/** set concept name.
* Code describing the concept represented by this content item. Also conveys the value
* of document title and section headings in documents.
*
* Applicable to all content items (by-value only, optional/conditional for some value
* types).
** @param conceptName value to be set
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setConceptName(const DSRCodedEntryValue &conceptName,
const OFBool check = OFTrue);
/** get observation date/time.
* This is the date and time on which this content item was completed. Might be empty
* if the date and time do not differ from the content date and time, see DSRDocument.
*
* Applicable to all content items (by-value only, optional attribute).
** @return observation date/time of current content item if valid, EmptyString otherwise
*/
const OFString &getObservationDateTime() const;
/** set observation date/time.
* This is the date and time on which this content item was completed. Might be empty
* if the date and time do not differ from the content date and time, see DSRDocument.
* Please use the correct DICOM format (VR=DT).
*
* Applicable to all content items (by-value only).
** @param observationDateTime value to be set (might be an empty string)
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setObservationDateTime(const OFString &observationDateTime,
const OFBool check = OFTrue);
/** get observation unique identifier.
* The UID represents the semantic content of the observation; an encoding of the same
* observation with the same context into another representation may use the same UID.
*
* Applicable to all content items (by-value only, optional attribute).
** @return observation unique identifier of current content item if valid,
* EmptyString otherwise
*/
const OFString &getObservationUID() const;
/** set observation unique identifier.
* The UID represents the semantic content of the observation; an encoding of the same
* observation with the same context into another representation may use the same UID.
* Please use the correct DICOM format (VR=UI).
*
* Applicable to all content items (by-value only).
** @param observationUID value to be set (might be an empty string)
* @param check if enabled, check value for validity before setting it
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setObservationUID(const OFString &observationUID,
const OFBool check = OFTrue);
/** get annotation text.
* The optional annotation text allows for labeling a content item with an arbitrary
* character string. This might be useful to navigate more easily within the document
* tree.
*
* Applicable to all content items (optional).
** @return annotation text of current content item if valid, EmptyString otherwise
*/
const OFString &getAnnotationText() const;
/** set annotation text.
* The optional annotation text allows for labeling a content item with an arbitrary
* character string. This might be useful to navigate more easily within the document
* tree.
*
* Applicable to all content items (optional).
** @param annotationText value to be set (might be an empty string)
** @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition setAnnotationText(const OFString &annotationText) const;
protected:
/** default constructor (protected)
*/
DSRContentItem();
/** set internal tree node pointer (protected)
** @param node pointer to the document tree node (content item)
*/
inline void setTreeNode(DSRDocumentTreeNode *node)
{
TreeNode = node;
}
/** fast, non-throwing swap function.
* The time complexity of this function is constant.
** @param item content item to swap with
*/
void swap(DSRContentItem &item);
private:
/// internal tree node pointer to current content item
DSRDocumentTreeNode *TreeNode;
/// flag indicating whether to delete the 'TreeNode' during destruction (or not)
/*const*/ OFBool DeleteTreeNode; // removed "const" to support swap() method
/// empty numeric measurement value. Used as default return value for getNumericValue().
/// A static member variable (as for the other values below) cannot be used because this
/// class contains members that again contain OFCondition instances that cannot be defined
/// before the main() function starts.
const DSRNumericMeasurementValue EmptyNumericMeasurement;
/// empty string value.
/// Used as default return value for getStringValue()
static const OFString EmptyString;
/// empty coded entry value.
/// Used as default return value for getCodeValue() and getConceptName()
static const DSRCodedEntryValue EmptyCodedEntry;
/// empty spatial coordinates value.
/// Used as default return value for getSpatialCoordinates()
static const DSRSpatialCoordinatesValue EmptySpatialCoordinates;
/// empty spatial coordinates 3D value.
/// Used as default return value for getSpatialCoordinates3D()
static const DSRSpatialCoordinates3DValue EmptySpatialCoordinates3D;
/// empty temporal coordinates value.
/// Used as default return value for getTemporalCoordinates()
static const DSRTemporalCoordinatesValue EmptyTemporalCoordinates;
/// empty composite reference value.
/// Used as default return value for getCompositeReference()
static const DSRCompositeReferenceValue EmptyCompositeReference;
/// empty image reference value.
/// Used as default return value for getImageReference()
static const DSRImageReferenceValue EmptyImageReference;
/// empty waveform reference value.
/// Used as default return value for getWaveformReference()
static const DSRWaveformReferenceValue EmptyWaveformReference;
// --- declaration of assignment operator
DSRContentItem &operator=(const DSRContentItem &);
};
#endif