DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Private Member Functions | Private Attributes | List of all members
DcmPathProcessor Class Reference

Class that operates on DICOM datasets using a (string) path syntax. More...

## Public Member Functions
| DcmPathProcessor ()
| Constructor, creates an empty search object.
void | setItemWildcardSupport (const OFBool supported)
| Sets whether searching/creating paths will support wildcard for items. More...
void | checkPrivateReservations (const OFBool doChecking)
| Enables (class default: enabled) or disables checking of private reservations when inserting private tags. More...
OFCondition | findOrCreatePath (DcmObject *obj, const OFString &path, OFBool createIfNecessary=OFFalse)
| Function that allows for finding and/or inserting a hierarchy of items and attributes as defined by a path string; also returns a list of pointers for each successfully found or inserted paths. More...
OFCondition | findOrDeletePath (DcmObject *obj, const OFString &path, Uint32 &numDeleted)
| Function that allows for deleting elements and items from a DICOM object tree. More...
Uint32 | getResults (OFList< DcmPath * > &searchResults)
| Returns the results from the search / creation call. More...
OFCondition | applyPathWithValue (DcmDataset *dataset, const OFString &overrideKey)
| Helper function that applies a specified "override key" in path syntax to the given dataset. More...
| ~DcmPathProcessor ()
| Destructor, cleans up memory that was allocated for any search results.

## Static Public Member Functions
static OFCondition | getPrivateCreator (DcmItem *item, const DcmTagKey &tagKey, OFString &privateCreator)
| Returns private creator identifier for given tag. More...
static OFCondition | checkPrivateTagReservation (DcmItem *item, const DcmTagKey &tagKey, const OFString &privateCreator="")
| Checks in item, whether a private reservation for a given tag key exists. More...
static OFCondition | checkPrivateTagReservation (DcmItem *item, DcmTag &tag, const OFString &privateCreator="")
| Checks in item, whether a private reservation for a given tag key. More...

## Protected Member Functions
OFCondition | findOrCreateItemPath (DcmItem *item, OFString &path)
| Function that allows for finding and/or inserting a hierarchy of items and attributes as defined by a path string; also returns a list of pointers for each successfully found or inserted paths. More...
OFCondition | findOrCreateSequencePath (DcmSequenceOfItems *seq, OFString &path)
| Function that allows for finding and/or inserting a hierarchy of items and attributes as defined by a path string; also returns a list of pointers for each successfully found or inserted paths. More...
void | clear ()
| Cleans up memory that was allocated for any search results. More...

## Static Protected Member Functions
static OFCondition | deleteLastElemFromPath (DcmObject *objSearchedIn, DcmPath *path, DcmPathNode *toDelete)
| Helper function that looks at the last node in a given path and deletes the corresponding DICOM object. More...
static OFCondition | deleteLastItemFromPath (DcmObject *objSearchedIn, DcmPath *path, DcmPathNode *toDelete)
| Helper function that looks at the last node in a given path and deletes the corresponding DICOM object. More...
static DcmTagKey | calcPrivateReservationTag (const DcmTagKey &privateKey)
| Returns the private reservation tag key for a given private tag. More...

## Private Member Functions
| DcmPathProcessor (const DcmPathProcessor &rhs)
| Private undefined copy constructor. More...
DcmPathProcessor & | operator= (const DcmPathProcessor &arg)
| Private undefined assignment operator. More...

## Private Attributes
OFList< DcmPathNode * > | m_currentPath
| Internal list that is during search for keeping track of current path.
OFList< DcmPath * > | m_results
| Internal list that represents the search results found.
OFBool | m_createIfNecessary
| Denotes whether missing items/sequences/attributes should be automatically inserted when using findAndCreate routines.
OFBool | m_checkPrivateReservations
| If enabled (default), any insertions of private tags will fail, if no corresponding reservation exists in the underlying item.
OFBool | m_itemWildcardsEnabled
| Denotes, whether a path is accepted that contains wildcards. More...

## Detailed Description

Class that operates on DICOM datasets using a (string) path syntax.

## Constructor & Destructor Documentation

## ◆ DcmPathProcessor()

DcmPathProcessor::DcmPathProcessor | ( | const DcmPathProcessor & | rhs | ) |
| private

Private undefined copy constructor.

Parameters

  rhs | Object to copy from

## Member Function Documentation

## ◆ applyPathWithValue()

OFCondition DcmPathProcessor::applyPathWithValue | ( | DcmDataset * | dataset,
|  | const OFString & | overrideKey
| ) |  |

Helper function that applies a specified "override key" in path syntax to the given dataset.

The name "override" indicates that these keys have higher precedence than identical keys in a request dataset that might possibly read from a DICOM query file.

Parameters

  dataset | [in/out] the dataset (e.g. query keys) the override key is applied to. Must be non-NULL.
  overrideKey | [in] the override key in path syntax (see class DcmPath). Also the path can end with a value assignment, e.g. "PatientName=Doe^John". An empty (or missing value) will not be ignored but will be written as empty to the attribute (if not a sequence or item).

Returns
  EC_Normal if adding was successful, error code otherwise

## ◆ calcPrivateReservationTag()

static DcmTagKey DcmPathProcessor::calcPrivateReservationTag | ( | const DcmTagKey & | privateKey | ) |
| static protected

Returns the private reservation tag key for a given private tag.

Parameters

  privateKey | [in] The private key to calculate reservation tag for

Returns
  The reservation key. If given key is not private or an error, return DCM_UndefinedTagKey. If the given key is a reservation itself, it is directly returned.

## ◆ checkPrivateReservations()

void DcmPathProcessor::checkPrivateReservations | ( | const OFBool | doChecking | ) |

Enables (class default: enabled) or disables checking of private reservations when inserting private tags.

If enabled and a private tag is created that has no private reservation, an error is returned. If disabled, it is possible to insert private tags that do not have a reservation in the corresponding item/dataset.

Parameters

  doChecking | [in] OFTrue enables reservation checking, OFFalse disables it.

## ◆ checkPrivateTagReservation() [1/2]

static OFCondition DcmPathProcessor::checkPrivateTagReservation | ( | DcmItem * | item,
|  | const DcmTagKey & | tagKey,
|  | const OFString & | privateCreator = `""`
| ) |  |
| static

Checks in item, whether a private reservation for a given tag key exists.

Parameters

  item | [in] The item to search in
  tagKey | [in/out] The tag to be checked.
  privateCreator | [in] The private creator identifier to check for (if known, can be left empty)

Returns
  Return EC_Normal if reservation checking was successful. Otherwise an error code is returned.

## ◆ checkPrivateTagReservation() [2/2]

static OFCondition DcmPathProcessor::checkPrivateTagReservation | ( | DcmItem * | item,
|  | DcmTag & | tag,
|  | const OFString & | privateCreator = `""`
| ) |  |
| static

Checks in item, whether a private reservation for a given tag key.

If so, a dictionary lookup is performed and the VR and private creator of the tag is updated correspondingly.

Parameters

  item | [in] The item to search in
  tag | [in/out] The tag to be checked. Will be updated with VR and private creator.
  privateCreator | [in] The private creator identifier to check for (if known, can be left empty)

Returns
  Return EC_Normal if reservation checking and updating the tag was successful. Otherwise an error code is returned.

## ◆ clear()

void DcmPathProcessor::clear | ( |  | ) |
| protected

Cleans up memory that was allocated for any search results.

Called when a new search is started or during object destruction. The DICOM data all freed paths and path nodes point to, is not touched, i.e. all memory to the DICOM objects pointed to must be freed from outside. Processing options like checking for private reservations and so on are not reset to default values but keep valid.

## ◆ deleteLastElemFromPath()

static OFCondition DcmPathProcessor::deleteLastElemFromPath | ( | DcmObject * | objSearchedIn,
|  | DcmPath * | path,
|  | DcmPathNode * | toDelete
| ) |  |
| static protected

Helper function that looks at the last node in a given path and deletes the corresponding DICOM object.

Does not delete the path node itself: That is done by the calling function, findOrCreateItemPath().

Parameters

  objSearchedIn | [in/out] The object the given path starts in.
  path | [in/out] The complete path to the DICOM object to delete
  toDelete | [in/out] The path node to delete. This node must be identical to the last node in the path parameter. Also the node must represent a DICOM sequence or leaf element, not an item. However, because it is isolated already by the calling function, it is provided here for convenience.

Returns
  EC_Normal if successful, error otherwise

## ◆ deleteLastItemFromPath()

static OFCondition DcmPathProcessor::deleteLastItemFromPath | ( | DcmObject * | objSearchedIn,
|  | DcmPath * | path,
|  | DcmPathNode * | toDelete
| ) |  |
| static protected

Helper function that looks at the last node in a given path and deletes the corresponding DICOM object.

Does not delete the path node itself: That is done by the calling function, findOrCreateItemPath().

Parameters

  objSearchedIn | [in/out] The object the given path starts in.
  path | [in/out] The complete path to the DICOM object to delete
  toDelete | [in/out] The path node to delete. This node must be identical to the last node in the path parameter. Also the node must represent a DICOM item, not a sequence However, because it is isolated already by the calling function, it is provided here for convenience.

Returns
  EC_Normal if successful, error otherwise

## ◆ findOrCreateItemPath()

OFCondition DcmPathProcessor::findOrCreateItemPath | ( | DcmItem * | item,
|  | OFString & | path
| ) |  |
| protected

Function that allows for finding and/or inserting a hierarchy of items and attributes as defined by a path string; also returns a list of pointers for each successfully found or inserted paths.

Every list contains pointers pointing to all the objects along the path starting from the object given as parameter. The pointer to the starting object will not be part of the result.

In principle, the path string must have the following format (in arbitrary depth). SEQUENCE[ITEMNO].SEQUENCE[ITEMNO].ATTRIBUTE . ITEMNO must be a positive integer starting with 0. SEQUENCE and ATTRIBUTE must be a tag, written e.g. "(0010,0010)" or as a dictionary name, e.g. "PatientName". If the path cannot be fully created (see option createIfNecessary), any possibly object changes are reverted. So a path is either fully created or no path component is created at all. The result can be obtained by calling the getResults() function.

Example: The path "ContentSequence[4].(0040,a043)[0].CodeValue" selects the Content Sequence in the given item, therein the 5th item, therein the "Concept Name Code Sequence" denoted by (0040,a043), therein the first item and finally therein the tag "Code Value". The resulting object list should (if success is returned) contain 1 result, consisting of a list with 5 pointers to 5 objects in the order in their logical order as they occur in the path string (in total 2 sequences, 2 items, and one leaf attribute).

Parameters

  item | [in] The object to search (or create) a path in
  path | [in] The path starting with an attribute (either a sequence or a leaf attribute) as a dictionary name or tag. The parsed attribute is removed from the path string.

Returns
  EC_Normal if successful, error code otherwise.

## ◆ findOrCreatePath()

OFCondition DcmPathProcessor::findOrCreatePath | ( | DcmObject * | obj,
|  | const OFString & | path,
|  | OFBool | createIfNecessary = `OFFalse`
| ) |  |

Function that allows for finding and/or inserting a hierarchy of items and attributes as defined by a path string; also returns a list of pointers for each successfully found or inserted paths.

Every list contains pointers pointing to all the objects along the path starting from the object given as parameter. The pointer to the starting object will not be part of the result.

In principle, the path string must have the following format (in arbitrary depth). Note that for searching a sequence, the example below would start with [ITEMNO] instead: SEQUENCE[ITEMNO].SEQUENCE[ITEMNO].ATTRIBUTE . ITEMNO must be a positive integer starting with 0. SEQUENCE and ATTRIBUTE must be a tag, written e.g. "(0010,0010)" or as a dictionary name, e.g. "PatientName". If the path cannot be fully created (see option createIfNecessary), any possibly object changes are reverted. So a path is either fully created or no path component is created at all. The result can be obtained by calling the getResults() function.

Example: The path "ContentSequence[4].(0040,a043)[0].CodeValue" selects the Content Sequence in the given object, therein the 5th item, therein the "Concept Name Code Sequence" denoted by (0040,a043), therein the first item and finally therein the tag "Code Value". The resulting object list should (if success is returned) contain 1 result, consisting of a list with 5 pointers to 5 objects in the order in their logical order as they occur in the path string (in total 2 sequences, 2 items, and one leaf attribute).

Parameters

  obj | [in] The object to search (or create) a path in
  path | [in] The path either starting with an attribute (either a sequence or a leaf attribute as a dictionary name or tag) or starting with an item
  createIfNecessary | [in] If set, all missing objects found in the path string are created. If not set, only existing paths can be accessed and no new attribute or item is created.

Returns
  EC_Normal if successful, error code otherwise.

## ◆ findOrCreateSequencePath()

OFCondition DcmPathProcessor::findOrCreateSequencePath | ( | DcmSequenceOfItems * | seq,
|  | OFString & | path
| ) |  |
| protected

Function that allows for finding and/or inserting a hierarchy of items and attributes as defined by a path string; also returns a list of pointers for each successfully found or inserted paths.

Every list contains pointers pointing to all the objects along the path starting from the object given as parameter. The pointer to the starting object will not be part of the result.

In principle, the path string must have the following format (in arbitrary depth). [ITEMNO].SEQUENCE[ITEMNO].ATTRIBUTE . ITEMNO must be a positive integer starting with 0. SEQUENCE and ATTRIBUTE must be a tag, written e.g. "(0010,0010)" or as a dictionary name, e.g. "PatientName". If the path cannot be fully created (see option createIfNecessary), any possibly object changes are reverted. So a path is either fully created or no path component is created at all. The result can be obtained by calling the getResults() function.

Example: The path "[4].(0040,a043)[0].CodeValue" selects the 5th item in the given sequence, therein the "Concept Name Code Sequence" denoted by (0040,a043), therein the first item and finally therein the tag "Code Value". The resulting object list should (if success is returned) contain 1 result, consisting of a list with 4 pointers to 4 objects in the order in their logical order as they occur in the path string (in total 1 sequence, 2 items, and one leaf element).

Parameters

  seq | [in] The object to search (or create) a path in
  path | [in] The path starting with an item. The parsed item number (e.g. "[0]") is removed from the path string.

Returns
  EC_Normal if successful, error code otherwise.

## ◆ findOrDeletePath()

OFCondition DcmPathProcessor::findOrDeletePath | ( | DcmObject * | obj,
|  | const OFString & | path,
|  | Uint32 & | numDeleted
| ) |  |

Function that allows for deleting elements and items from a DICOM object tree.

In principle, the path string must have the following format (in arbitrary depth). Note that for searching in a sequence, the example below would start with [ITEMNO] instead: SEQUENCE[ITEMNO].SEQUENCE[ITEMNO].ATTRIBUTE . ITEMNO must be a positive integer starting with 0. SEQUENCE and ATTRIBUTE must be a tag, written e.g. "(0010,0010)" or as a dictionary name, e.g. "PatientName".

Example: The path "ContentSequence[4].(0040,a043)[0].CodeValue" selects the Content Sequence in the given object, therein the 5th item, therein the "Concept Name Code Sequence" denoted by (0040,a043), therein the first item and finally therein the tag "Code Value". Only "Code Value" will be deleted by the function.

Parameters

  obj | [in] The object to delete attribute or item from
  path | [in] The path either starting with an attribute (either a sequence or a leaf attribute as a dictionary name or tag) or starting with an item
  numDeleted | [out] Number of deleted attributes/items

Returns
  EC_Normal if successful, error code otherwise. If the desired attribute/item was not found, EC_TagNotFound is returned.

## ◆ getPrivateCreator()

static OFCondition DcmPathProcessor::getPrivateCreator | ( | DcmItem * | item,
|  | const DcmTagKey & | tagKey,
|  | OFString & | privateCreator
| ) |  |
| static

Returns private creator identifier for given tag.

Parameters

  item | [in] The item to search in
  tagKey | [in] The tag key for which a reservation should be looked up
  privateCreator | [out] The private creator identifier

Returns
  Return EC_Normal if reservation was found (can be empty, though), EC_TagNotFound if no private creator tag exists, error otherwise

## ◆ getResults()

Uint32 DcmPathProcessor::getResults | ( | OFList< DcmPath * > & | searchResults | ) |

Returns the results from the search / creation call.

Parameters

  searchResults | [out] The resulting paths that were created/searched Note that the memory of the search results is freed automatically by the destructor and must not be freed by the caller.

Returns
  Number of results returned

## ◆ operator=()

DcmPathProcessor& DcmPathProcessor::operator= | ( | const DcmPathProcessor & | arg | ) |
| private

Private undefined assignment operator.

Parameters

  arg | Object to copy from

Returns
  Reference to this object

## ◆ setItemWildcardSupport()

void DcmPathProcessor::setItemWildcardSupport | ( | const OFBool | supported | ) |

Sets whether searching/creating paths will support wildcard for items.

If set to false, any path operation with item wildcard characters will return an error.

Parameters

  supported | [in] If true, wildcard are enabled (default) If false, item wildcard support is disabled.

## Member Data Documentation

## ◆ m_itemWildcardsEnabled

OFBool DcmPathProcessor::m_itemWildcardsEnabled
| private

Denotes, whether a path is accepted that contains wildcards.

If false, then any search containing wildcards will return an error.

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

- dcmdata/include/dcmtk/dcmdata/dcpath.h

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