DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Static Public Member Functions | Private Member Functions | List of all members
DcmIODUtil Class Reference

Class with helper functions used within the dcmiod module (and beyond) More...

## Static Public Member Functions
static OFCondition | getAndCheckElementFromDataset (DcmItem &dataset, DcmElement &delem, const OFString &vm, const OFString &type, const char *moduleName=NULL)
| Get element from dataset and check it for correct value multiplicity and type. More...
static OFCondition | getAndCheckElementFromDataset (DcmItem &dataset, const DcmTagKey &tagKey, DcmElement *&delem, const OFString &vm, const OFString &type, const char *moduleName=NULL)
| Get element from dataset and check it for correct value multiplicity and type. More...
static OFCondition | getAndCheckElementFromDataset (DcmItem &dataset, DcmElement &delem, const IODRule *rule)
| Get element from dataset and check it for correct value multiplicity and type. More...
static OFCondition | getAndCheckElementFromDataset (DcmItem &dataset, DcmElement *&delem, const IODRule *rule)
| Get element from dataset and check it for correct value multiplicity and type. More...
static const OFString & | currentDate (OFString &dateString)
| Get current date in DICOM 'DA' format (YYYYMMDD) More...
static const OFString & | currentTime (OFString &timeString)
| Get current time in DICOM 'TM' format (HHMMSS) The optional UTC notation (e.g. +0100) is currently not supported. More...
static OFCondition | copyElementToDataset (OFCondition &result, DcmItem &dataset, const DcmElement &delem, const OFString &vm, const OFString &type, const char *moduleName=NULL)
| Copy given element to the dataset The element is only added if 'result' is EC_Normal. More...
static OFCondition | copyElementToDataset (OFCondition &result, DcmItem &dataset, const DcmElement &delem, const IODRule *rule)
| Copy given element to the dataset. More...
static OFCondition | addElementToDataset (OFCondition &result, DcmItem &dataset, DcmElement *delem, const IODRule *rule, const OFBool checkValue=OFTrue)
| Add given element to the dataset The element is only added if 'result' is EC_Normal and the 'delem' pointer is not NULL. More...
static OFCondition | checkElementValue (const DcmElement *delem, const DcmTagKey &tagKey, const OFString &vm, const OFString &type, const OFCondition &searchCond=EC_Normal, const char *moduleName=NULL, const dcmtk::log4cplus::LogLevel logLevel=dcmtk::log4cplus::WARN_LOG_LEVEL)
| Check element value for correct value multiplicity and type. More...
static OFCondition | checkElementValue (const DcmElement &delem, const OFString &vm, const OFString &type, const OFCondition &searchCond=EC_Normal, const char *moduleName=NULL, const dcmtk::log4cplus::LogLevel logLevel=dcmtk::log4cplus::WARN_LOG_LEVEL)
| Check element value for correct value multiplicity and type. More...
static OFCondition | getStringValueFromElement (const DcmElement &delem, OFString &stringValue, const signed long pos)
| Get string value from element. More...
static OFCondition | getStringValueFromItem (const DcmTagKey &key, DcmItem &item, OFString &result, const signed long &pos)
| Get string value from item. More...
static OFCondition | getFloat64ValueFromItem (const DcmTagKey &key, DcmItem &item, Float64 &result, const unsigned long &pos)
| Get Float64 value from item. More...
static OFCondition | getFloat64ValuesFromItem (const DcmTagKey &key, DcmItem &item, OFVector< Float64 > &result)
| Get Float64 values from item. More...
static OFCondition | getFloat64ValueFromElement (const DcmElement &delem, Float64 &result, const unsigned long pos)
| Get Float64 value from element. More...
static OFCondition | getFloat64ValuesFromElement (const DcmElement &delem, OFVector< Float64 > &result)
| Get Float64 values from element. More...
static OFCondition | setFloat64ValuesOnElement (DcmElement &delem, const OFVector< Float64 > &values, const OFString &vm, const OFBool check)
| Set a DcmElement's content from Float64 vector. More...
static OFCondition | getFloat32ValueFromElement (const DcmElement &delem, Float32 &result, const unsigned long pos)
| Get Float32 value from element. More...
static OFCondition | setFloat32ValuesOnElement (DcmElement &delem, const OFVector< Float32 > &values, const OFString &vm, const OFBool check)
| Set a DcmElement's content from Float32 vector. More...
static OFCondition | setUint16ValuesOnElement (DcmElement &delem, const OFVector< Uint16 > &values, const OFString &vm, const OFBool check)
| Set a DcmElement's content from Uint16 vector. More...
static OFCondition | getUint16ValuesFromElement (DcmElement &delem, OFVector< Uint16 > &values)
| Get Uint16 values from DcmElement. More...
static OFCondition | getAndCheckSingleItem (DcmSequenceOfItems &seq, DcmItem *&item, const DcmTagKey &checkKey=DCM_UndefinedTagKey)
| Returns single item from given sequence. More...
template<class Container >
static OFCondition | copyFromUint8Array (DcmElement *elem, Container &destination)
| Copies Uint8 values from given element to destination container (must support push_back() method). More...
static OFCondition | checkSOPClass (DcmItem *item, const OFString &desiredSOPClass, OFString &valueFound)
| Check whether SOP class UID matches the expected value. More...
static OFBool | isSequenceTag (const DcmTagKey &key, const OFString &privateCreator="")
| Check whether given tag is a sequence tag. More...
template<class Container >
static OFCondition | readSubSequence (DcmSequenceOfItems *source, const DcmTagKey &seqKey, Container &destination, const OFString &cardinality, const OFString &type, const OFString &module)
| Reads items from DICOM sequence into container by creating a dedicated container item for each DICOM item. More...
template<class Container >
static OFCondition | readSubSequence (DcmItem &source, const DcmTagKey &seqKey, Container &destination, const OFString &cardinality, const OFString &type, const OFString &module)
| Reads DICOM sequence into container by creating a dedicated container element for each DICOM item. More...
template<class Container >
static OFCondition | readSubSequence (DcmItem &source, const DcmTagKey &seqKey, Container &destination, IODRule *rule)
| Reads DICOM sequence into container by creating a dedicated container element for each DICOM item. More...
template<class Container >
static OFCondition | readSingleItem (DcmItem &source, const DcmTagKey &seqKey, Container &destination, const OFString &type, const OFString &module)
| Reads single DICOM item from a specific sequence into a destination class. More...
template<class Container >
static OFCondition | readSingleItem (DcmItem &source, const DcmTagKey &seqKey, Container &destination, IODRule *rule=NULL)
| Reads single DICOM item from a specific sequence into a destination class. More...
template<class Container >
static void | writeSubSequence (OFCondition &result, const DcmTagKey &seqKey, Container &source, DcmItem &destination, const OFString &cardinality, const OFString &type, const OFString &module)
| Write given container into a DICOM sequence that is created within the given item. More...
template<class Container >
static void | writeSubSequence (OFCondition &result, const DcmTagKey &seqKey, Container &source, DcmItem &destination, IODRule *rule)
| Write given container into a DICOM sequence that is created within the given item. More...
template<class Container >
static void | writeSingleItem (OFCondition &result, const DcmTagKey &seqKey, Container &source, DcmItem &destination, const OFString &type, const OFString &module)
| Writes given container into a DICOM item of a specific sequence. More...
template<class Container >
static void | writeSingleItem (OFCondition &result, const DcmTagKey &seqKey, Container &source, DcmItem &destination, IODRule *rule)
| Writes given container into a DICOM item of a specific sequence. More...
static void | checkSubSequence (OFCondition &result, DcmItem &surroundingItem, const DcmTagKey &seqKey, const OFString &cardinality, const OFString &type, const OFString &module, const dcmtk::log4cplus::LogLevel logLevel)
| Check whether a given sequence exists in a given item and whether it conforms to to its requirement type. More...
template<class Container >
static void | freeContainer (Container &container)
| Deletes all elements from given container and calls "delete" on each of them to clear memory. More...
template<class Map >
static void | freeMap (Map &container)
| Deletes all elements from given map and calls "delete" on each of them to clear memory. More...
template<class Container >
static OFCondition | copyContainer (const Container &src, Container &dst)
| Clones and copies all elements from source to destination container by copy constructing all elements. More...
template<class Container >
static int | compareContainer (const Container &src, const Container &dst)
| Compares all elements in source and destination container by using their respective compare(const Container& rhs) method. More...
template<typename ModuleType >
static OFCondition | setContentDateAndTimeNow (ModuleType &module)
| Set the current date and time on the given module by using setContentDate() and setContentTime() methods. More...
static const DcmTagKey | parseTagKey (const OFString &keyString)
| Function that takes a string representation of a tag key and converts it to a tag key instance if possible. More...
static OFCondition | decompress (DcmDataset &dset)
| Decompress given dataset if possible. More...
static OFString | createUID (const Uint8 level=0)
| Create new Unique Identifier (UID) More...
static Uint32 | limitMaxFrames (const size_t numFramesPresent, const OFString &warning)
| Print warning if more than 2147483647 frames are present. More...
static OFCondition | extractBinaryFrames (Uint8 *pixData, const size_t numFrames, const size_t bitsPerFrame, OFVector< DcmIODTypes::FrameBase * > &results)
| Extracts Frame structures from the given pixel data element. More...
static void | resetConditionIfCheckDisabled (OFCondition &result, const OFBool checkValue, DcmElement &elem)
| Resets the given condition to EC_Normal if checkValue is true and prints a related message as a warning to the debug logger. More...
static void | resetValueCheckResult (OFCondition &result, const OFBool checkValue, DcmElement &elem)
| If checkValue is true, the given OFCondition for certain errors (listed below), prints a debug message if the condition is not good, and resets the condition to EC_Normal. More...

## Private Member Functions
| DcmIODUtil ()
| Undefined default constructor (only static functions)
| ~DcmIODUtil ()
| Undefined destructor.

## Detailed Description

Class with helper functions used within the dcmiod module (and beyond)

## Member Function Documentation

## ◆ addElementToDataset()

static OFCondition DcmIODUtil::addElementToDataset | ( | OFCondition & | result,
|  | DcmItem & | dataset,
|  | DcmElement * | delem,
|  | const IODRule * | rule,
|  | const OFBool | checkValue = `OFTrue`
| ) |  |
| static

Add given element to the dataset The element is only added if 'result' is EC_Normal and the 'delem' pointer is not NULL.

Parameters

  result | Reference to status variable (checked before adding and updated afterwards!)
  dataset | Reference to DICOM dataset to which the element should be added
  delem | Pointer to DICOM element which should be added. The element is always consumed by this function, i.e. insertion was successful and therefore ownership is transferred to the dataset, or the element is deleted from memory if it could not be inserted.
  rule | Rule describing parameters to be checked on element.
  checkValue | If OFTrue, the value of the element is checked for violations against VR, VM, charset and value length. If OFTrue, an error is printed and an error is returned. Otherwise, a warning is printed and EC_Normal is returned.

Returns
  Current value of 'result', EC_Normal if successful, an error code otherwise

## ◆ checkElementValue() [1/2]

static OFCondition DcmIODUtil::checkElementValue | ( | const DcmElement & | delem,
|  | const OFString & | vm,
|  | const OFString & | type,
|  | const OFCondition & | searchCond = `EC_Normal`,
|  | const char * | moduleName = `NULL`,
|  | const dcmtk::log4cplus::LogLevel | logLevel = `dcmtk::log4cplus::WARN_LOG_LEVEL`
| ) |  |
| static

Check element value for correct value multiplicity and type.

Parameters

  delem | DICOM element to be checked
  vm | Value multiplicity (according to the data dictionary) to be checked for. (See DcmElement::checkVM() for a list of valid values.) Interpreted as cardinality (number of items) for sequence attributes.
  type | Value type (valid value: "1", "1C", "2", something else)
  searchCond | Optional flag indicating the status of a previous 'search' function call
  moduleName | Optional module name to be printed (default: "IOD" if NULL)
  logLevel | The log level to log errors to

Returns
  EC_Normal if element value is correct, error otherwise

## ◆ checkElementValue() [2/2]

static OFCondition DcmIODUtil::checkElementValue | ( | const DcmElement * | delem,
|  | const DcmTagKey & | tagKey,
|  | const OFString & | vm,
|  | const OFString & | type,
|  | const OFCondition & | searchCond = `EC_Normal`,
|  | const char * | moduleName = `NULL`,
|  | const dcmtk::log4cplus::LogLevel | logLevel = `dcmtk::log4cplus::WARN_LOG_LEVEL`
| ) |  |
| static

Check element value for correct value multiplicity and type.

Parameters

  delem | Pointer to DICOM element to be checked (might be NULL)
  tagKey | DICOM tag of the DICOM element the parameter 'delem' points to
  vm | Value multiplicity (according to the data dictionary) to be checked for. (See DcmElement::checkVM() for a list of valid values.) Interpreted as cardinality (number of items) for sequence attributes.
  type | Value type (valid value: "1", "1C", "2", something else)
  searchCond | Optional flag indicating the status of a previous 'search' function call
  moduleName | Optional module name to be printed (default: "IOD" if NULL)
  logLevel | The log level to log errors to

Returns
  EC_Normal if element value is correct, error otherwise

## ◆ checkSOPClass()

static OFCondition DcmIODUtil::checkSOPClass | ( | DcmItem * | item,
|  | const OFString & | desiredSOPClass,
|  | OFString & | valueFound
| ) |  |
| static

Check whether SOP class UID matches the expected value.

Parameters

  item | Item to read from. NULL value causes error return value.
  desiredSOPClass | The value that is expected
  valueFound | The value actually found (empty if no value could be retrieved)

Returns
  EC_Normal if value could be found and equals expected value, EC_TagNotFound if SOP Class UID is not found in dataset, EC_InvalidValue if SOP class differs from expected value.

## ◆ checkSubSequence()

static void DcmIODUtil::checkSubSequence | ( | OFCondition & | result,
|  | DcmItem & | surroundingItem,
|  | const DcmTagKey & | seqKey,
|  | const OFString & | cardinality,
|  | const OFString & | type,
|  | const OFString & | module,
|  | const dcmtk::log4cplus::LogLevel | logLevel
| ) |  |
| static

Check whether a given sequence exists in a given item and whether it conforms to to its requirement type.

Parameters

  result | If sequence is valid, result is set to EC_Normal, otherwise to an error.
  surroundingItem | The item that should contain the given sequence.
  seqKey | The sequence to look for
  cardinality | Expected number of items (i.e. expected number of elements in source container). See DcmElement::checkVM() for a list of valid values.
  type | The sequence type as noted in part 3 of the DICOM standard, i.e. "1,1C,2,2C or 3".
  module | Name of the module/macro this sequence is contained in. Used for error messages and can also be left empty.
  logLevel | The log level to write errors to

## ◆ compareContainer()

template<class Container >

static int DcmIODUtil::compareContainer | ( | const Container & | src,
|  | const Container & | dst
| ) |  |
| inline static

Compares all elements in source and destination container by using their respective compare(const Container& rhs) method.

If the number or elements in the Containers are different, the containers are not considered equal.

Parameters

  src | The first container
  dst | The second container

Returns
  Zero if containers are equal, other number otherwise

## ◆ copyContainer()

template<class Container >

static OFCondition DcmIODUtil::copyContainer | ( | const Container & | src,
|  | Container & | dst
| ) |  |
| inline static

Clones and copies all elements from source to destination container by copy constructing all elements.

If copying fails (because memory is exhausted), EC_MemoryExhausted is returned and the destination container is returned empty, i.e. all temporary copies of its elements are freed and removed from the container.

Parameters

  src | The container that should be copied. Must contain pointers to objects that are allocated on the heap, and that are copy-constructible
  dst | The container to copy the cloned elements to.

Returns
  EC_Normal if successful, error otherwise

References EC_MemoryExhausted, and EC_Normal.

## ◆ copyElementToDataset() [1/2]

static OFCondition DcmIODUtil::copyElementToDataset | ( | OFCondition & | result,
|  | DcmItem & | dataset,
|  | const DcmElement & | delem,
|  | const IODRule * | rule
| ) |  |
| static

Copy given element to the dataset.

The element is only added if 'result' is EC_Normal.

Parameters

  result | reference to status variable (checked before adding and updated afterwards!)
  dataset | reference to DICOM dataset to which the element should be added
  delem | reference to DICOM element which should be added; the value is copied from the original dataset's element
  rule | Rule describing parameters to be checked on element.

Returns
  Current value of 'result', EC_Normal if successful, an error code otherwise

## ◆ copyElementToDataset() [2/2]

static OFCondition DcmIODUtil::copyElementToDataset | ( | OFCondition & | result,
|  | DcmItem & | dataset,
|  | const DcmElement & | delem,
|  | const OFString & | vm,
|  | const OFString & | type,
|  | const char * | moduleName = `NULL`
| ) |  |
| static

Copy given element to the dataset The element is only added if 'result' is EC_Normal.

A copy of the given element is created, i.e. the caller is responsible for deleting the original element handed to this function (if desired).

Parameters

  result | Reference to status variable (checked before adding and updated afterwards!)
  dataset | Reference to DICOM dataset to which the element should be added
  delem | Reference to DICOM element which should be added; a copy is created so caller is responsible for deleting delem (if desired).
  vm | Value multiplicity (according to the data dictionary) to be checked for. (See DcmElement::checkVM() for a list of valid values.). Interpreted as cardinality (number of items) for sequence attributes.
  type | Value type (valid value: "1", "2" or something else which is not checked)
  moduleName | Optional module name to be printed (NULL: no module printed at all)

Returns
  Current value of 'result', EC_Normal if successful, an error code otherwise

## ◆ copyFromUint8Array()

template<class Container >

static OFCondition DcmIODUtil::copyFromUint8Array | ( | DcmElement * | elem,
|  | Container & | destination
| ) |  |
| inline static

Copies Uint8 values from given element to destination container (must support push_back() method).

Parameters

  elem | the element to read from. If NULL, an error is returned.
  destination | the container to store the Uint8 values to

Returns
  EC_Normal if successful, an error code otherwise

References EC_IllegalParameter, DcmObject::getNumberOfValues(), DcmElement::getUint8(), and OFCondition::good().

## ◆ createUID()

static OFString DcmIODUtil::createUID | ( | const Uint8 | level = `0` | ) |
| static

Create new Unique Identifier (UID)

Parameters

  level | 0: instance level, 1: Series level, >=2: Study level. Calling always with level=0 is not an error but will result in unique values, too.

Returns
  The UID created.

## ◆ currentDate()

static const OFString& DcmIODUtil::currentDate | ( | OFString & | dateString | ) |
| static

Get current date in DICOM 'DA' format (YYYYMMDD)

Parameters

  dateString | String used to store the current date. (empty string if current date could not be retrieved)

Returns
  Resulting character string

## ◆ currentTime()

static const OFString& DcmIODUtil::currentTime | ( | OFString & | timeString | ) |
| static

Get current time in DICOM 'TM' format (HHMMSS) The optional UTC notation (e.g. +0100) is currently not supported.

Parameters

  timeString | String used to store the current time (empty string if current time could not be retrieved)

Returns
  Resulting character string, empty if time could not be retrieved

## ◆ decompress()

static OFCondition DcmIODUtil::decompress | ( | DcmDataset & | dset | ) |
| static

Decompress given dataset if possible.

Decompression codecs have to be registered beforehand.

Parameters

  dset | The dataset to decompress

Returns
  EC_Normal if decompression works, error otherwise

## ◆ extractBinaryFrames()

static OFCondition DcmIODUtil::extractBinaryFrames | ( | Uint8 * | pixData,
|  | const size_t | numFrames,
|  | const size_t | bitsPerFrame,
|  | OFVector< DcmIODTypes::FrameBase * > & | results
| ) |  |
| static

Extracts Frame structures from the given pixel data element.

Only applicable for pixel data with Bits Allocated = 1. Within the pixel data element, all frames are packed next to each other, with the end of one frame and the beginning of the next frame packed bit by bit next to each other (right to left!). The resulting Frames are a bit-by-bit copy of their original counterpart. However, their first bit is aligned to the first bit/byte in the Frame, and the unused bits in the last byte (if any) are zeroed out.

Parameters

  pixData | The pixel data to read from
  numFrames | The number of frames to read
  bitsPerFrame | The number of bits per frame (usually rows * columns)
  results | The resulting frames. Memory for the frames is allocated by the method, so the Vector can/should be empty before calling.

Returns
  Return EC_Normal on success, error otherwise

## ◆ freeContainer()

template<class Container >

static void DcmIODUtil::freeContainer | ( | Container & | container | ) |
| inline static

Deletes all elements from given container and calls "delete" on each of them to clear memory.

Parameters

  container | The container that should be cleared. Must contain pointers to objects that are allocated on the heap.

## ◆ freeMap()

template<class Map >

static void DcmIODUtil::freeMap | ( | Map & | container | ) |
| inline static

Deletes all elements from given map and calls "delete" on each of them to clear memory.

Parameters

  container | The map that should be cleared. Must contain pointers to objects that are allocated on the heap.

## ◆ getAndCheckElementFromDataset() [1/4]

static OFCondition DcmIODUtil::getAndCheckElementFromDataset | ( | DcmItem & | dataset,
|  | const DcmTagKey & | tagKey,
|  | DcmElement *& | delem,
|  | const OFString & | vm,
|  | const OFString & | type,
|  | const char * | moduleName = `NULL`
| ) |  |
| static

Get element from dataset and check it for correct value multiplicity and type.

Parameters

  dataset | DICOM dataset from which the element should be retrieved. (Would be 'const' if the methods from 'dcmdata' would also be 'const')
  tagKey | Tag key of the element to get
  delem | DICOM element that is set to a copy of the dataset's orinal element
  vm | Value multiplicity (according to the data dictionary) to be checked for. (See DcmElement::checkVM() for a list of valid values.) Interpreted as cardinality (number of items) for sequence attributes.
  type | Value type (valid value: "1", "1C", "2", something else which is not checked)
  moduleName | Optional module name to be printed (NULL: no module printed at all)

Returns
  EC_Normal if element could be retrieved and value is correct, an error code otherwise

## ◆ getAndCheckElementFromDataset() [2/4]

static OFCondition DcmIODUtil::getAndCheckElementFromDataset | ( | DcmItem & | dataset,
|  | DcmElement & | delem,
|  | const IODRule * | rule
| ) |  |
| static

Get element from dataset and check it for correct value multiplicity and type.

Parameters

  dataset | DICOM dataset from which the element should be retrieved. (Would be 'const' if the methods from 'dcmdata' would also be 'const'.)
  delem | DICOM element used to store the value (always creates a copy of the value from the original element)
  rule | Rule describing parameters to be checked on element

Returns
  EC_Normal if element could be retrieved and value is correct, an error code otherwise

## ◆ getAndCheckElementFromDataset() [3/4]

static OFCondition DcmIODUtil::getAndCheckElementFromDataset | ( | DcmItem & | dataset,
|  | DcmElement & | delem,
|  | const OFString & | vm,
|  | const OFString & | type,
|  | const char * | moduleName = `NULL`
| ) |  |
| static

Get element from dataset and check it for correct value multiplicity and type.

Parameters

  dataset | DICOM dataset from which the element should be retrieved. (Would be 'const' if the methods from 'dcmdata' would also (be 'const'.)
  delem | DICOM element used to store the value (always creates a copy of the dataset element's value)
  vm | Value multiplicity (according to the data dictionary) to be checked for. (See DcmElement::checkVM() for a list of valid values.) Interpreted as cardinality (number of items) for sequence attributes.
  type | Value type (valid value: "1", "1C", "2", something else which is not checked)
  moduleName | Optional module name to be printed (NULL: no module printed at all)

Returns
  EC_Normal if element could be retrieved and value is correct, an error code otherwise

## ◆ getAndCheckElementFromDataset() [4/4]

static OFCondition DcmIODUtil::getAndCheckElementFromDataset | ( | DcmItem & | dataset,
|  | DcmElement *& | delem,
|  | const IODRule * | rule
| ) |  |
| static

Get element from dataset and check it for correct value multiplicity and type.

Parameters

  dataset | DICOM dataset from which the element should be retrieved. (Would be 'const' if the methods from 'dcmdata' would also be 'const')
  delem | DICOM element that is set to a copy of the dataset's original element
  rule | Rule describing parameters to be checked on element.

Returns
  EC_Normal if element could be retrieved and value is correct, an error code otherwise

## ◆ getAndCheckSingleItem()

static OFCondition DcmIODUtil::getAndCheckSingleItem | ( | DcmSequenceOfItems & | seq,
|  | DcmItem *& | item,
|  | const DcmTagKey & | checkKey = `DCM_UndefinedTagKey`
| ) |  |
| static

Returns single item from given sequence.

Returns error number of items is 0 or more than 1.

Parameters

  seq | Sequence to read from.
  item | The resulting item, NULL in case of error
  checkKey | If given it is checked whether the given seq parameter matches the tag key provided in the checkKey parameter. If not, an error is returned.

Returns
  Status EC_Normal if successful, an error code otherwise

## ◆ getFloat32ValueFromElement()

static OFCondition DcmIODUtil::getFloat32ValueFromElement | ( | const DcmElement & | delem,
|  | Float32 & | result,
|  | const unsigned long | pos
| ) |  |
| static

Get Float32 value from element.

Parameters

  delem | The element whose value should be retrieved
  result | Reference to variable in which the result should be stored.
  pos | Index of the value to get (0..vm-1)

Returns
  EC_Normal if successful, an error code otherwise

## ◆ getFloat64ValueFromElement()

static OFCondition DcmIODUtil::getFloat64ValueFromElement | ( | const DcmElement & | delem,
|  | Float64 & | result,
|  | const unsigned long | pos
| ) |  |
| static

Get Float64 value from element.

Parameters

  delem | The element whose value should be retrieved
  result | Reference to variable in which the result should be stored.
  pos | Index of the value to get (0..vm-1)

Returns
  EC_Normal if successful, an error code otherwise

## ◆ getFloat64ValueFromItem()

static OFCondition DcmIODUtil::getFloat64ValueFromItem | ( | const DcmTagKey & | key,
|  | DcmItem & | item,
|  | Float64 & | result,
|  | const unsigned long & | pos
| ) |  |
| static

Get Float64 value from item.

Parameters

  key | The tag key of the attribute whose value should be retrieved
  item | The item to search the attribute in
  result | Reference to variable in which the result should be stored.
  pos | Index of the value to get (0..vm-1)

Returns
  EC_Normal if successful, an error code otherwise

## ◆ getFloat64ValuesFromElement()

static OFCondition DcmIODUtil::getFloat64ValuesFromElement | ( | const DcmElement & | delem,
|  | OFVector< Float64 > & | result
| ) |  |
| static

Get Float64 values from element.

Parameters

  delem | The element to get the value from
  result | Reference to variable in which the result should be stored.

Returns
  EC_Normal if successful, an error code otherwise

## ◆ getFloat64ValuesFromItem()

static OFCondition DcmIODUtil::getFloat64ValuesFromItem | ( | const DcmTagKey & | key,
|  | DcmItem & | item,
|  | OFVector< Float64 > & | result
| ) |  |
| static

Get Float64 values from item.

Parameters

  key | The tag key of the attribute whose value should be retrieved
  item | The item to search the attribute in
  result | Reference to variable in which the result should be stored.

Returns
  EC_Normal if successful, an error code otherwise

## ◆ getStringValueFromElement()

static OFCondition DcmIODUtil::getStringValueFromElement | ( | const DcmElement & | delem,
|  | OFString & | stringValue,
|  | const signed long | pos
| ) |  |
| static

Get string value from element.

Parameters

  delem | DICOM element from which the string value should be retrieved
  stringValue | Reference to variable in which the result should be stored. (This parameter is automatically cleared if an error occurs.)
  pos | Index of the value to get (0..vm-1), -1 for all components

Returns
  EC_Normal if successful, an error code otherwise

## ◆ getStringValueFromItem()

static OFCondition DcmIODUtil::getStringValueFromItem | ( | const DcmTagKey & | key,
|  | DcmItem & | item,
|  | OFString & | result,
|  | const signed long & | pos
| ) |  |
| static

Get string value from item.

Parameters

  key | The tag key of the attribute whose value should be retrieved
  item | The item to search the attribute in
  result | Reference to variable in which the result should be stored. (This parameter is automatically cleared if an error occurs.)
  pos | Index of the value to get (0..vm-1), -1 for all components

Returns
  EC_Normal if successful, an error code otherwise

## ◆ getUint16ValuesFromElement()

static OFCondition DcmIODUtil::getUint16ValuesFromElement | ( | DcmElement & | delem,
|  | OFVector< Uint16 > & | values
| ) |  |
| static

Get Uint16 values from DcmElement.

Parameters

  delem | DICOM element to read from
  values | Vector used as destination for the values

Returns
  Status EC_Normal if successful, an error code otherwise

## ◆ isSequenceTag()

static OFBool DcmIODUtil::isSequenceTag | ( | const DcmTagKey & | key,
|  | const OFString & | privateCreator = `""`
| ) |  |
| static

Check whether given tag is a sequence tag.

Parameters

  key | the tag key to be checked
  privateCreator | The private creator to check for if tag is private

Returns
  OFTrue if given tag is a sequence tag, OFFalse otherwise

## ◆ limitMaxFrames()

static Uint32 DcmIODUtil::limitMaxFrames | ( | const size_t | numFramesPresent,
|  | const OFString & | warning
| ) |  |
| static

Print warning if more than 2147483647 frames are present.

This is the maximum number since the Number of Frames attribute has a VR of IS which allows a maximum of 2^31-1. The method returns the number of frames that can be used, i.e. either 2147483647 if the maximum is exceeded, otherwise the actual number of frames.

Parameters

  numFramesPresent | The number of frames actually present
  warning | The message to be printed if Number of Frames is larger than 2147483647.

Returns
  Number of frames that can be safely used.

## ◆ parseTagKey()

static const DcmTagKey DcmIODUtil::parseTagKey | ( | const OFString & | keyString | ) |
| static

Function that takes a string representation of a tag key and converts it to a tag key instance if possible.

Parameters

  keyString | String of the format "(gggg,eeee)"

Returns
  The tag key if it could be parsed, DCM_UndefinedTagKey is returned instead (0xffff,0xffff)

## ◆ readSingleItem() [1/2]

template<class Container >

static OFCondition DcmIODUtil::readSingleItem | ( | DcmItem & | source,
|  | const DcmTagKey & | seqKey,
|  | Container & | destination,
|  | const OFString & | type,
|  | const OFString & | module
| ) |  |
| inline static

Reads single DICOM item from a specific sequence into a destination class.

The container must support the read(DcmItem) function. If a single item (i.e. the first item of the specified sequence) cannot be read, an error is returned.

Parameters

  source | The source DICOM item read the sequence from
  seqKey | The tag key of the sequence to be read
  destination | The destination container to read into
  type | The sequence type as noted in part 3 of the DICOM standard, i.e. "1,1C,2,2C or 3".
  module | Name of the module/macro this sequence is contained in. Used for error messages and can also be left empty.

Returns
  EC_Normal if successful, an error code otherwise

References DcmItem::findAndGetSequenceItem().

## ◆ readSingleItem() [2/2]

template<class Container >

static OFCondition DcmIODUtil::readSingleItem | ( | DcmItem & | source,
|  | const DcmTagKey & | seqKey,
|  | Container & | destination,
|  | IODRule * | rule = `NULL`
| ) |  |
| inline static

Reads single DICOM item from a specific sequence into a destination class.

The container must support the read(DcmItem) function. If a single item (i.e. the first item of the specified sequence) cannot be read, an error is returned.

Parameters

  source | The source DICOM item read the sequence from
  seqKey | The tag key of the sequence to be read
  destination | The destination container to read into
  rule | The rule (for the sequence) used for reading.

Returns
  EC_Normal if successful, an error code otherwise. If the rule equlas NULL, then nothing is read at all and an error is returned (IOD_EC_NoSuchRule), but no error is reported to the logger.

## ◆ readSubSequence() [1/3]

template<class Container >

static OFCondition DcmIODUtil::readSubSequence | ( | DcmItem & | source,
|  | const DcmTagKey & | seqKey,
|  | Container & | destination,
|  | const OFString & | cardinality,
|  | const OFString & | type,
|  | const OFString & | module
| ) |  |
| inline static

Reads DICOM sequence into container by creating a dedicated container element for each DICOM item.

The container must support push_back(T) function and the container's element type T must support the read(DcmItem*) function.

Parameters

  source | The source DICOM item read the sequence from
  seqKey | The tag key of the sequence to be read
  destination | The destination container to read into
  cardinality | Expected number of items. See DcmElement::checkVM() for a list of valid values.
  type | The sequence type as noted in part 3 of the DICOM standard, i.e. "1,1C,2,2C or 3".
  module | Name of the module/macro this sequence is contained in. Used for error messages and can also be left empty.

Returns
  status EC_Normal if successful, an error code otherwise

References DcmItem::findAndGetSequence().

## ◆ readSubSequence() [2/3]

template<class Container >

static OFCondition DcmIODUtil::readSubSequence | ( | DcmItem & | source,
|  | const DcmTagKey & | seqKey,
|  | Container & | destination,
|  | IODRule * | rule
| ) |  |
| inline static

Reads DICOM sequence into container by creating a dedicated container element for each DICOM item.

The container must support the push_back(T) function and the container's element type T must support the read(DcmItem*) function.

Parameters

  source | The source DICOM item read the sequence from
  seqKey | The tag key of the sequence to be read
  destination | The destination container to read into
  rule | The rule for reading this sequence. If NULL, an error is returned.

Returns
  EC_Normal if successful, an error code otherwise

References IODRule::getModule(), IODRule::getType(), and IODRule::getVM().

## ◆ readSubSequence() [3/3]

template<class Container >

static OFCondition DcmIODUtil::readSubSequence | ( | DcmSequenceOfItems * | source,
|  | const DcmTagKey & | seqKey,
|  | Container & | destination,
|  | const OFString & | cardinality,
|  | const OFString & | type,
|  | const OFString & | module
| ) |  |
| inline static

Reads items from DICOM sequence into container by creating a dedicated container item for each DICOM item.

The container must support push_back(T) function and the container's element type T must support the read(DcmItem*) function.

Parameters

  source | The source sequence to read items from
  seqKey | The sequence's tag key that is expected
  destination | The destination container to read into
  cardinality | Expected number of items. See DcmElement::checkVM() for a list of valid values.
  type | The sequence type as noted in part 3 of the DICOM standard, i.e. "1,1C,2,2C or 3".
  module | Name of the module/macro this sequence is contained in. Used for error messages and can also be left empty.

Returns
  EC_Normal if successful, an error code otherwise

References OFString::c_str(), EC_Normal, and EC_TagNotFound.

## ◆ resetConditionIfCheckDisabled()

static void DcmIODUtil::resetConditionIfCheckDisabled | ( | OFCondition & | result,
|  | const OFBool | checkValue,
|  | DcmElement & | elem
| ) |  |
| static

Resets the given condition to EC_Normal if checkValue is true and prints a related message as a warning to the debug logger.

Parameters

  result | The condition to check. Only EC_ValueRepresentationViolated, EC_MaximumLengthViolated, EC_InvalidCharacter and EC_ValueMultiplicityViolated are handled. Those codes are reset to EC_Normal if the checkValue is OFFalse.
  checkValue | If this value is false, the condition is reset to EC_Normal
  elem | Used if the condition is reset to EC_Normal to print a warning

## ◆ resetValueCheckResult()

static void DcmIODUtil::resetValueCheckResult | ( | OFCondition & | result,
|  | const OFBool | checkValue,
|  | DcmElement & | elem
| ) |  |
| static

If checkValue is true, the given OFCondition for certain errors (listed below), prints a debug message if the condition is not good, and resets the condition to EC_Normal.

If checkValue is false, the method does nothing. The following error codes are handled, i.e. reset: EC_ValueRepresentationViolated EC_MaximumLengthViolated EC_InvalidCharacter EC_ValueMultiplicityViolated

Parameters

  result | The condition to check. Only EC_ValueRepresentationViolated, EC_MaximumLengthViolated, EC_InvalidCharacter and EC_ValueMultiplicityViolated are handled.
  checkValue | If this value is true, the listed condition are reset to EC_Normal; otherwise the condition is not changed and no message is printed.
  elem | Used if the condition is reset to EC_Normal to print a message in case of a "reset"

## ◆ setContentDateAndTimeNow()

template<typename ModuleType >

static OFCondition DcmIODUtil::setContentDateAndTimeNow | ( | ModuleType & | module | ) |
| inline static

Set the current date and time on the given module by using setContentDate() and setContentTime() methods.

The current date and time is retrieved from the system clock.

Parameters

  module | The module to set the date and time on

Returns
  EC_Normal if successful, an error code otherwise

References OFDate::getISOFormattedDate(), and OFDate::setCurrentDate().

## ◆ setFloat32ValuesOnElement()

static OFCondition DcmIODUtil::setFloat32ValuesOnElement | ( | DcmElement & | delem,
|  | const OFVector< Float32 > & | values,
|  | const OFString & | vm,
|  | const OFBool | check
| ) |  |
| static

Set a DcmElement's content from Float32 vector.

Parameters

  delem | DICOM element to be filled
  values | Vector use as a source for the values
  vm | Value multiplicity (according to the data dictionary) to be checked for. (See DcmElement::checkVM() for a list of valid values.)
  check | If OFTrue, then it is checked whether number of values conforms to the value provided by the vm parameter.

Returns
  Dtatus, EC_Normal if successful, an error code otherwise

## ◆ setFloat64ValuesOnElement()

static OFCondition DcmIODUtil::setFloat64ValuesOnElement | ( | DcmElement & | delem,
|  | const OFVector< Float64 > & | values,
|  | const OFString & | vm,
|  | const OFBool | check
| ) |  |
| static

Set a DcmElement's content from Float64 vector.

Parameters

  delem | DICOM element to be filled
  values | Vector use as a source for the values
  vm | Value multiplicity (according to the data dictionary) to be checked for. (See DcmElement::checkVM() for a list of valid values.)
  check | If OFTrue, then it is checked whether number of values conforms to the value provided by the vm parameter.

Returns
  Dtatus, EC_Normal if successful, an error code otherwise

## ◆ setUint16ValuesOnElement()

static OFCondition DcmIODUtil::setUint16ValuesOnElement | ( | DcmElement & | delem,
|  | const OFVector< Uint16 > & | values,
|  | const OFString & | vm,
|  | const OFBool | check
| ) |  |
| static

Set a DcmElement's content from Uint16 vector.

Parameters

  delem | DICOM element to be filled
  values | Vector use as a source for the values
  vm | Value multiplicity (according to the data dictionary) to be checked for. (See DcmElement::checkVM() for a list of valid values.)
  check | If OFTrue, then it is checked whether number of values conforms to the value provided by the vm parameter.

Returns
  Dtatus, EC_Normal if successful, an error code otherwise

## ◆ writeSingleItem() [1/2]

template<class Container >

static void DcmIODUtil::writeSingleItem | ( | OFCondition & | result,
|  | const DcmTagKey & | seqKey,
|  | Container & | source,
|  | DcmItem & | destination,
|  | const OFString & | type,
|  | const OFString & | module
| ) |  |
| inline static

Writes given container into a DICOM item of a specific sequence.

The sequence is created from scratch so that any old information will be lost.

Parameters

  result | If writing is successful, result will contain EC_Normal. Otherwise an error code is set.
  seqKey | The tag key of the sequence to be written
  source | The source container to read from. Must support the write(DcmItem*) function.
  destination | The DICOM item that should hold the sequence (with a single item) in the end.
  type | The sequence type as noted in part 3 of the DICOM standard, i.e. "1,1C,2,2C or 3".
  module | Name of the module/macro this sequence is contained in. Used for error messages and can also be left empty.

References DcmItem::findAndDeleteElement(), and OFCondition::good().

## ◆ writeSingleItem() [2/2]

template<class Container >

static void DcmIODUtil::writeSingleItem | ( | OFCondition & | result,
|  | const DcmTagKey & | seqKey,
|  | Container & | source,
|  | DcmItem & | destination,
|  | IODRule * | rule
| ) |  |
| inline static

Writes given container into a DICOM item of a specific sequence.

The sequence is created from scratch so that any old information will be lost.

Parameters

  result | If writing is successful, result will contain EC_Normal. Otherwise an error code is set.
  seqKey | The tag key of the sequence to be written
  source | The source container to read from. Must support the write(DcmItem*) function.
  destination | The DICOM item that should hold the sequence (with a single item) in the end.
  rule | The rule for writing the given sequence

References EC_CannotCheck, IODRule::getModule(), IODRule::getType(), and OFCondition::good().

## ◆ writeSubSequence() [1/2]

template<class Container >

static void DcmIODUtil::writeSubSequence | ( | OFCondition & | result,
|  | const DcmTagKey & | seqKey,
|  | Container & | source,
|  | DcmItem & | destination,
|  | const OFString & | cardinality,
|  | const OFString & | type,
|  | const OFString & | module
| ) |  |
| inline static

Write given container into a DICOM sequence that is created within the given item.

The sequence is created from scratch, i.e. any old sequence (and its items) will be overwritten.

Parameters

  result | If writing is successful, result will contain EC_Normal. Otherwise an error code is set.
  seqKey | The tag key of the sequence to be write
  source | The source container to read from. Must support the write(DcmItem*) function.
  destination | The DICOM destination item to write the sequence to
  cardinality | Expected number of items (i.e. expected number of elements in source container). See DcmElement::checkVM() for a list of valid values.
  type | The sequence type as noted in part 3 of the DICOM standard, i.e. "1,1C,2,2C or 3".
  module | Name of the module/macro this sequence is contained in. Used for error messages and can also be left empty.

References OFCondition::bad(), DcmItem::findAndDeleteElement(), DcmItem::findAndDeleteSequenceItem(), DcmItem::findOrCreateSequenceItem(), OFCondition::good(), DcmItem::insertEmptyElement(), and OFCondition::text().

## ◆ writeSubSequence() [2/2]

template<class Container >

static void DcmIODUtil::writeSubSequence | ( | OFCondition & | result,
|  | const DcmTagKey & | seqKey,
|  | Container & | source,
|  | DcmItem & | destination,
|  | IODRule * | rule
| ) |  |
| inline static

Write given container into a DICOM sequence that is created within the given item.

The container. The sequence is created from scratch, i.e. any old sequence (and its items) will be overwritten.

Parameters

  result | If writing is successful, result will contain EC_Normal. Otherwise an error code is set.
  seqKey | The tag key of the sequence to be write
  source | The source container to read from. Must support the write(DcmItem*) function.
  destination | The DICOM destination item to write the sequence to
  rule | Rule describing the requirements for this sequence. If NULL an error is returned (IOD_EC_NoSuchRule), but no error error is reported to the logger.

References IODRule::getModule(), IODRule::getTagKey(), IODRule::getType(), IODRule::getVM(), and OFCondition::good().

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

- dcmiod/include/dcmtk/dcmiod/iodutil.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1