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 ()
	Deconstructor, cleans up memory that was allocated for any search results.

Static Public Member Functions
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.

DcmPathProcessor &	operator= (const DcmPathProcessor &arg)
	Private undefined assignment operator.

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

Member Function Documentation

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

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

staticprotected

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.

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.

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 to check for (if known, can be left empty)

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

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

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.

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

staticprotected

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.

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

staticprotected

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.

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 a leaf attribute) as a dicitionary name or tag. The parsed attribute is removed from the path string.

Returns: EC_Normal if successful, error code otherwise.

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 a leaf attribute as a dicitionary 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.

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.

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 a leaf attribute as a dicitionary 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.

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

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Member Function Documentation

Member Data Documentation