Loading...
Searching...
No Matches
WlmFileSystemInteractionManager Class Reference

This class encapsulates data structures and operations for managing data base interaction in the framework of the DICOM basic worklist management service. More...

## Public Member Functions

| WlmFileSystemInteractionManager ()
| default constructor.
| ~WlmFileSystemInteractionManager ()
| destructor
void | SetEnableRejectionOfIncompleteWlFiles (OFBool value)
| Set value in member variable.
OFCondition | ConnectToFileSystem (const OFString &dfPathv)
| Connects to the worklist file system database.
OFCondition | DisconnectFromFileSystem ()
| Disconnects from the worklist file system database.
OFBool | IsCalledApplicationEntityTitleSupported (const OFString &calledApplicationEntityTitlev)
| Checks if the given called application entity title is supported.
size_t | DetermineMatchingRecords (DcmDataset *searchMask)
| This function determines the records from the Worklist files that match the given search mask and returns the number of matching records.
void | MatchWorklistFile (DcmDataset &searchMask, const OFpath &worklistFile)
| Determine whether a Worklist file matches the search mask.
unsigned long | GetNumberOfSequenceItemsForMatchingRecord (DcmTagKey sequenceTag, WlmSuperiorSequenceInfoType *superiorSequenceArray, unsigned long numOfSuperiorSequences, unsigned long idx)
| For the matching record that is identified through idx, this function returns the number of items that are contained in the sequence element that is referred to by sequenceTag.
void | GetAttributeValueForMatchingRecord (DcmTagKey tag, WlmSuperiorSequenceInfoType *superiorSequenceArray, unsigned long numOfSuperiorSequences, unsigned long idx, char *&value)
| This function determines an attribute value of a matching record and returns this value in a newly created string to the caller.
void | ClearMatchingRecords ()
| This function frees the memory which was occupied by matchingRecords.

## Static Public Member Functions

static OFBool | IsValidAETitleForFilesystem (const OFString &aeTitle)
| Determines whether the given DICOM Application Entity Title is safe to use as a single directory or filename component below the worklist data file path.

## Protected Member Functions

OFdirectory_iterator & | FindNextWorklistFile (OFdirectory_iterator &it)
| Increment the given directory iterator until it refers to a worklist file (or past-the-end).
OFBool | DatasetIsComplete (DcmDataset *dataset)
| This function checks if the given dataset (which represents the information from a worklist file) contains all necessary return type 1 information.
OFBool | ReferencedStudyOrPatientSequenceIsAbsentOrExistentButNonEmptyAndIncomplete (DcmTagKey sequenceTagKey, DcmItem *dset)
| This function checks if the specified sequence attribute is absent or existent but non-empty and incomplete in the given dataset.
OFBool | DescriptionAndCodeSequenceAttributesAreIncomplete (DcmTagKey descriptionTagKey, DcmTagKey codeSequenceTagKey, DcmItem *dset)
| This method ensures that either code or description is set to a non-empty value, and at the same time none of the attributes is present with a zero-length value.
OFBool | AttributeIsAbsentOrEmpty (DcmTagKey elemTagKey, DcmItem *dset)
| This function checks if the specified attribute is absent or contains an empty value in the given dataset.
OFBool | MatchSequences (DcmSequenceOfItems &candidate, DcmSequenceOfItems &query, const MatchingKeys &matchingKeys)
| This function returns OFTrue, if the matching key attribute values in the one of the items of the candidate sequence match the matching key attribute values in at least one of the items of the query sequence.
OFBool | IsUniversalMatch (DcmSequenceOfItems &query, const MatchingKeys &matchingKeys, const OFBool normalize=OFTrue, const OFBool normalizeWildCards=OFTrue)
| Determine if a sequence is an universal match.
OFBool | DatasetMatchesSearchMask (DcmItem &dataset, DcmItem &searchMask, const MatchingKeys &matchingKeys)
| This function returns OFTrue, if the matching key attribute values in the dataset match the matching key attribute values in the search mask.

## Protected Attributes

OFString | dfPath
| path to database files
OFBool | enableRejectionOfIncompleteWlFiles
| indicates if wl-files which are lacking return type 1 attributes or information in such attributes shall be rejected or not
OFString | calledApplicationEntityTitle
| called AE title
OFVector< OFshared_ptr< DcmDataset > > | matchingRecords
| matching records

## Private Member Functions

| WlmFileSystemInteractionManager (const WlmFileSystemInteractionManager &old)
| Privately defined copy constructor.
WlmFileSystemInteractionManager & | operator= (const WlmFileSystemInteractionManager &obj)
| Privately defined assignment operator.

## Detailed Description

This class encapsulates data structures and operations for managing data base interaction in the framework of the DICOM basic worklist management service.

## Constructor & Destructor Documentation

## WlmFileSystemInteractionManager()

WlmFileSystemInteractionManager::WlmFileSystemInteractionManager | ( | const WlmFileSystemInteractionManager & | old | ) |

private

Privately defined copy constructor.

Parameters

  old | Object which shall be copied.

References WlmFileSystemInteractionManager().

Referenced by WlmFileSystemInteractionManager(), and operator=().

## Member Function Documentation

## AttributeIsAbsentOrEmpty()

OFBool WlmFileSystemInteractionManager::AttributeIsAbsentOrEmpty | ( | DcmTagKey | elemTagKey,
|  | DcmItem * | dset )

protected

This function checks if the specified attribute is absent or contains an empty value in the given dataset.

Parameters

  elemTagKey | The attribute which shall be checked.
  dset | The dataset in which the attribute is contained.

Returns
  OFTrue in case the attribute is absent or contains an empty value, OFFalse otherwise.

## ClearMatchingRecords()

void WlmFileSystemInteractionManager::ClearMatchingRecords | ( |  | ) |

This function frees the memory which was occupied by matchingRecords.

It shall be called when the matching records are no longer needed.

## ConnectToFileSystem()

OFCondition WlmFileSystemInteractionManager::ConnectToFileSystem | ( | const OFString & | dfPathv | ) |

Connects to the worklist file system database.

Parameters

  dfPathv | Path to worklist file system database.

Returns
  Indicates if the connection could be established or not.

## DatasetIsComplete()

OFBool WlmFileSystemInteractionManager::DatasetIsComplete | ( | DcmDataset * | dataset | ) |

protected

This function checks if the given dataset (which represents the information from a worklist file) contains all necessary return type 1 information.

According to the DICOM standard part 4 annex K, the following attributes are type 1 attributes in C-Find RSP messages: Attribute Tag Return Key Type SpecificCharacterSet (0008,0005) 1C (will be checked in WlmDataSourceFileSystem::StartFindRequest(...); this attribute does not have to be checked here) ScheduledProcedureStepSequence (0040,0100) 1

> ScheduledStationAETitle (0040,0001) 1 ScheduledProcedureStepStartDate (0040,0002) 1 ScheduledProcedureStepStartTime (0040,0003) 1 Modality (0008,0060) 1 ScheduledProcedureStepDescription (0040,0007) 1C (The ScheduledProcedureStepDescription (0040,0007) or the ScheduledProtocolCodeSequence (0040,0008) or both shall be supported by the SCP; we actually support both, so we have to check if at least one of the two attributes contains valid information.) ScheduledProtocolCodeSequence (0040,0008) 1C (see abobve)

> > CodeValue (0008,0100) 1 CodingSchemeDesignator (0008,0102) 1

> ScheduledProcedureStepID (0040,0009) 1 RequestedProcedureID (0040,1001) 1 RequestedProcedureDescription (0032,1060) 1C (The RequestedProcedureDescription (0032,1060) or the RequestedProcedureCodeSequence (0032,1064) or both shall be supported by the SCP; we actually support both, so we have to check if at least one of the two attributes contains valid information.) RequestedProcedureCodeSequence (0032,1064) 1C (see abobve)

> > CodeValue (0008,0100) 1 CodingSchemeDesignator (0008,0102) 1 StudyInstanceUID (0020,000D) 1 ReferencedStudySequence (0008,1110) 2

> ReferencedSOPClassUID (0008,1150) 1C (Required if a sequence item is present) ReferencedSOPInstanceUID (0008,1155) 1C (Required if a sequence item is present) ReferencedPatientSequence (0008,1120) 2 ReferencedSOPClassUID (0008,1150) 1C (Required if a sequence item is present) ReferencedSOPInstanceUID (0008,1155) 1C (Required if a sequence item is present) PatientName (0010,0010) 1 PatientID (0010,0020) 1

> Parameters

>   dataset | - [in] The dataset of the worklist file which is currently examined.

> Returns
>   OFTrue in case the given dataset contains all necessary return type 1 information, OFFalse otherwise.

## DatasetMatchesSearchMask()

OFBool WlmFileSystemInteractionManager::DatasetMatchesSearchMask | ( | DcmItem & | dataset,
|  | DcmItem & | searchMask,
|  | const MatchingKeys & | matchingKeys )

protected

This function returns OFTrue, if the matching key attribute values in the dataset match the matching key attribute values in the search mask.

Parameters

  dataset | The dataset which shall be checked.
  searchMask | The search mask.
  matchingKeys | The matching keys to regard.

Returns
  OFTrue in case the dataset matches the search mask in the matching key attribute values, OFFalse otherwise.

## DescriptionAndCodeSequenceAttributesAreIncomplete()

OFBool WlmFileSystemInteractionManager::DescriptionAndCodeSequenceAttributesAreIncomplete | ( | DcmTagKey | descriptionTagKey,
|  | DcmTagKey | codeSequenceTagKey,
|  | DcmItem * | dset )

protected

This method ensures that either code or description is set to a non-empty value, and at the same time none of the attributes is present with a zero-length value.

If one of these requirements are not met, then OFTrue is returned, otherwise OFFalse.

Parameters

  descriptionTagKey | The description attribute which shall be checked.
  codeSequenceTagKey | The codeSequence attribute which shall be checked.
  dset | The dataset in which the attributes are contained.

Returns
  OFFalse (i.e. no error regarding the standard) in case at least one of both attributes has a non-empty, valid value, and none is set to an empty value. OFTrue otherwise.

## DetermineMatchingRecords()

size_t WlmFileSystemInteractionManager::DetermineMatchingRecords | ( | DcmDataset * | searchMask | ) |

This function determines the records from the Worklist files that match the given search mask and returns the number of matching records.

Also, this function will store the matching records inside the member variable matchingRecords.

Parameters

  searchMask | A pointer to the search mask.

Returns
  The number of matching records.

## DisconnectFromFileSystem()

OFCondition WlmFileSystemInteractionManager::DisconnectFromFileSystem | ( |  | ) |

Disconnects from the worklist file system database.

Returns
  Indicates if the connection was disconnected successfully.

## FindNextWorklistFile()

OFdirectory_iterator & WlmFileSystemInteractionManager::FindNextWorklistFile | ( | OFdirectory_iterator & | it | ) |

protected

Increment the given directory iterator until it refers to a worklist file (or past-the-end).

Parameters

  it | A reference to an OFdirectory_iterator.

## GetAttributeValueForMatchingRecord()

void WlmFileSystemInteractionManager::GetAttributeValueForMatchingRecord | ( | DcmTagKey | tag,
|  | WlmSuperiorSequenceInfoType * | superiorSequenceArray,
|  | unsigned long | numOfSuperiorSequences,
|  | unsigned long | idx,
|  | char *& | value )

This function determines an attribute value of a matching record and returns this value in a newly created string to the caller.

Parameters

  tag | Attribute tag. Specifies which attribute's value shall be returned.
  superiorSequenceArray | Array which contains information about superior sequence elements the given element is contained in.
  numOfSuperiorSequences | The number of elements in the above array.
  idx | Identifies the record from which the attribute value shall be retrieved.
  value | Pointer to a newly created string that contains the requested value. If value was not found an empty string will be returned.

## GetNumberOfSequenceItemsForMatchingRecord()

unsigned long WlmFileSystemInteractionManager::GetNumberOfSequenceItemsForMatchingRecord | ( | DcmTagKey | sequenceTag,
|  | WlmSuperiorSequenceInfoType * | superiorSequenceArray,
|  | unsigned long | numOfSuperiorSequences,
|  | unsigned long | idx )

For the matching record that is identified through idx, this function returns the number of items that are contained in the sequence element that is referred to by sequenceTag.

In case this sequence element is itself contained in a certain item of another superior sequence, superiorSequenceArray contains information about where to find the correct sequence element.

Parameters

  sequenceTag | The tag of the sequence element for which the number of items shall be determined.
  superiorSequenceArray | Array which contains information about superior sequence elements the given sequence element is contained in.
  numOfSuperiorSequences | The number of elements in the above array.
  idx | Identifies the record from which the number of sequence items shall be determined.

Returns
  The number of items that are contained in the sequence element that is referred to by sequenceTag and that can be found in sequence items which are specified in superiorSequenceArray.

## IsCalledApplicationEntityTitleSupported()

OFBool WlmFileSystemInteractionManager::IsCalledApplicationEntityTitleSupported | ( | const OFString & | calledApplicationEntityTitlev | ) |

Checks if the given called application entity title is supported.

If this is the case, OFTrue will be returned, else OFFalse.

The check is performed in two stages. First, the AE title is validated against the rules of IsValidAETitleForFilesystem(): titles that contain path separators, embedded NUL or other control characters, or any dot character are rejected outright (returning OFFalse). This prevents the wire-side AE title from escaping the worklist data file path through path traversal. Second, the AE title is appended to the configured worklist root path and the resulting directory must exist.

Parameters

  calledApplicationEntityTitlev | The application entity title which shall be checked for support.

Returns
  OFTrue, if the called application entity title is supported, OFFalse, if the called application entity title is not supported, not given, or rejected because it would not be safe to use as a filesystem path component.

## IsUniversalMatch()

OFBool WlmFileSystemInteractionManager::IsUniversalMatch | ( | DcmSequenceOfItems & | query,
|  | const MatchingKeys & | matchingKeys,
|  | const OFBool | normalize = OFTrue,
|  | const OFBool | normalizeWildCards = OFTrue )

protected

Determine if a sequence is an universal match.

Parameters

  query | The query sequence.
  matchingKeys | The matching keys to regard.
  normalize | Normalize each attribute value before the check. Defaults to OFTrue, which means the value will be normalized as appropriate for the given VR, e.g. ignoring spaces used as padding.
  normalizeWildCards | Whether to interpret a query only consisting of wild cards as an universal match. Defaults to OFTrue, which means wild cards will be normalized if an attribute's VR supports it and it is allowed for the attribute (as defined by the matchingKeys argument). Set to OFFalse to force strict interpretation instead.

Returns
  OFTrue if the sequence has no items or if all attributes in its item can be considered an universal match. Returns OFFalse otherwise.

## IsValidAETitleForFilesystem()

OFBool WlmFileSystemInteractionManager::IsValidAETitleForFilesystem | ( | const OFString & | aeTitle | ) |

static

Determines whether the given DICOM Application Entity Title is safe to use as a single directory or filename component below the worklist data file path.

An AE title is considered safe if and only if all of the following hold:

- it is not empty and not longer than 16 bytes (the DICOM AE VR length limit),
- it contains no dot ('.') at all,
- OFStandard::sanitizeAETitle() would not change any byte of it.

The third rule delegates the character-set check to OFStandard::sanitizeAETitle(), which is the same allow list used by storescp for filename and shell-substitution contexts: letters, digits, space and the characters '-', '.', ':', '@', '_' are kept, every other byte (path separators '/' and '\', NUL, control characters, bytes outside the printable ASCII range and shell metacharacters) is replaced. If the sanitized string differs from the input, the AE title contains at least one such unsafe byte and is rejected.

Dots are rejected by the explicit second rule even though sanitizeAETitle() keeps them. Real-world AE titles never contain dots, and rejecting the entire character avoids any need to reason about path normalization corner cases (".", "..", trailing dots on Windows etc.).

Note that this delegation couples the rule applied here to the allow list inside OFStandard::sanitizeAETitle(). If that allow list is widened in the future, the set of AE titles accepted as safe filesystem path components widens too, so any change to it must consider downstream effects on wlmscpfs.

Parameters

  aeTitle | Application Entity Title to validate.

Returns
  OFTrue if the AE title is safe to use as a path component, OFFalse otherwise.

## MatchSequences()

OFBool WlmFileSystemInteractionManager::MatchSequences | ( | DcmSequenceOfItems & | candidate,
|  | DcmSequenceOfItems & | query,
|  | const MatchingKeys & | matchingKeys )

protected

This function returns OFTrue, if the matching key attribute values in the one of the items of the candidate sequence match the matching key attribute values in at least one of the items of the query sequence.

Parameters

  candidate | The candidate sequence.
  query | The query sequence.
  matchingKeys | The matching keys to regard.

Returns
  OFTrue in case at least one item matches, OFFalse otherwise.

## MatchWorklistFile()

void WlmFileSystemInteractionManager::MatchWorklistFile | ( | DcmDataset & | searchMask,
|  | const OFpath & | worklistFile )

Determine whether a Worklist file matches the search mask.

Parameters

  searchMask | A reference to the search mask.
  worklistFile | An OFpath (hopefully) referring to a Worklist file.

This method will attempt to load the Worklist file referenced by the argument worklistFile and, on success, compare it against searchMask. If the file matches the search mask, its dataset part will be added to the matching records member variable.

## operator=()

WlmFileSystemInteractionManager & WlmFileSystemInteractionManager::operator= | ( | const WlmFileSystemInteractionManager & | obj | ) |

private

Privately defined assignment operator.

Parameters

  obj | Object which shall be copied.

References WlmFileSystemInteractionManager().

## ReferencedStudyOrPatientSequenceIsAbsentOrExistentButNonEmptyAndIncomplete()

OFBool WlmFileSystemInteractionManager::ReferencedStudyOrPatientSequenceIsAbsentOrExistentButNonEmptyAndIncomplete | ( | DcmTagKey | sequenceTagKey,
|  | DcmItem * | dset )

protected

This function checks if the specified sequence attribute is absent or existent but non-empty and incomplete in the given dataset.

Parameters

  sequenceTagKey | The sequence attribute which shall be checked.
  dset | The dataset in which the attribute is contained.

Returns
  OFTrue in case the sequence attribute is absent (and cannot be added to the dataset) or existent but non-empty and incomplete, OFFalse otherwise.

## SetEnableRejectionOfIncompleteWlFiles()

void WlmFileSystemInteractionManager::SetEnableRejectionOfIncompleteWlFiles | ( | OFBool | value | ) |

Set value in member variable.

Parameters

  value | The value to set.

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

- dcmwlm/include/dcmtk/dcmwlm/wlfsim.h

Generated on for DCMTK Version 3.7.0 by Doxygen 1.15.0