PM/DYT
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1c07e198c9
DYT/Tool/3rdParty_x64/include/dcmtk/dcmdata/dcitem.h

1438 lines
78 KiB
C
Raw Normal View History

添加tool
2024-11-22 15:19:31 +00:00
/*
*
* Copyright (C) 1994-2016, OFFIS e.V.
* All rights reserved. See COPYRIGHT file for details.
*
* This software and supporting documentation were developed by
*
* OFFIS e.V.
* R&D Division Health
* Escherweg 2
* D-26121 Oldenburg, Germany
*
*
* Module: dcmdata
*
* Author: Gerd Ehlers
*
* Purpose: Interface of class DcmItem
*
*/
#ifndef DCITEM_H
#define DCITEM_H
#include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */
#include "dcmtk/ofstd/offile.h" /* for offile_off_t */
#include "dcmtk/dcmdata/dctypes.h"
#include "dcmtk/dcmdata/dcobject.h"
#include "dcmtk/dcmdata/dclist.h"
#include "dcmtk/dcmdata/dcpcache.h"
// forward declarations
class DcmSequenceOfItems;
class DcmElement;
class DcmSpecificCharacterSet;
/** a class representing a list of DICOM elements in which each
* element has a different tag and elements are maintained in
* increasing order of tags. In particular, a sequence item.
*/
class DCMTK_DCMDATA_EXPORT DcmItem
: public DcmObject
{
public:
// be friend with "greater than" and "less than" operators that are defined
// outside of this class
friend OFBool operator< (const DcmItem& lhs, const DcmItem& rhs);
friend OFBool operator> (const DcmItem& lhs, const DcmItem& rhs);
friend OFBool operator<=(const DcmItem& lhs, const DcmItem& rhs);
friend OFBool operator>=(const DcmItem& lhs, const DcmItem& rhs);
/** default constructor
*/
DcmItem();
/** constructor.
* Create new item from given tag and length.
* @param tag DICOM tag for the new element
* @param len value length for the new element
*/
DcmItem(const DcmTag &tag,
const Uint32 len = 0);
/** copy constructor
* @param old item to be copied
*/
DcmItem(const DcmItem &old);
/** assignment operator. Private creator cache is not copied
* as it is also the case for clone().
* @param obj the item to be copied
* @return Reference to this object after assignment
*/
DcmItem &operator=(const DcmItem &obj);
/** comparison operator that compares the normalized value of this object
* with a given object of the same type. The tag of the element is also
* considered as the first component that is compared, followed by the
* object types (VR, i.e. DCMTK'S EVR) and the comparison of all value
* components of the object, preferably in the order declared in the
* object (if applicable). For item values that means that all elements
* within the items are compared to each other in ascending tag order.
* This may be an expensive operation.
* @param rhs the right hand side of the comparison
* @return 0 if the object values are equal.
* -1 if either the value of the first component that does not match
* is lower in this object than in rhs, or all compared components match
* but this object has fewer components than rhs. Also returned if rhs
* cannot be casted to this object type.
* 1 if either the value of the first component that does not match
* is greater in this object than in rhs object, or all compared
* components match but the this component is longer.
*/
virtual int compare(const DcmItem& rhs) const;
/** destructor
*/
virtual ~DcmItem();
/** clone method
* @return deep copy of this object
*/
virtual DcmObject *clone() const
{
return new DcmItem(*this);
}
/** Virtual object copying. This method can be used for DcmObject
* and derived classes to get a deep copy of an object. Internally
* the assignment operator is called if the given DcmObject parameter
* is of the same type as "this" object instance. If not, an error
* is returned. This function permits copying an object by value
* in a virtual way which therefore is different to just calling the
* assignment operator of DcmElement which could result in slicing
* the object.
* @param rhs - [in] The instance to copy from. Has to be of the same
* class type as "this" object
* @return EC_Normal if copying was successful, error otherwise
*/
virtual OFCondition copyFrom(const DcmObject& rhs);
/** get type identifier
* @return type identifier of this class (EVR_item)
*/
virtual DcmEVR ident() const;
/** get value multiplicity
* @return always returns 1 (according to the DICOM standard)
*/
virtual unsigned long getVM();
/** get cardinality of this item
* @return number of elements in this item
*/
virtual unsigned long card() const;
/** check if this element is a leaf node in a dataset tree.
* All subclasses of DcmElement except for DcmSequenceOfItems
* are leaf nodes, while DcmSequenceOfItems, DcmItem, DcmDataset etc.
* are not.
* @return true if leaf node, false otherwise.
*/
virtual OFBool isLeaf() const { return OFFalse; }
/** check if this item is nested in a sequence of items, i.e.\ not a
* top-level or stand-alone item/dataset
* @return true if this item is nested, false otherwise
*/
virtual OFBool isNested() const;
/** print all elements of the item to a stream
* @param out output stream
* @param flags optional flag used to customize the output (see DCMTypes::PF_xxx)
* @param level current level of nested items. Used for indentation.
* @param pixelFileName not used
* @param pixelCounter not used
*/
virtual void print(STD_NAMESPACE ostream&out,
const size_t flags = 0,
const int level = 0,
const char *pixelFileName = NULL,
size_t *pixelCounter = NULL);
/** calculate the length of this DICOM element when encoded with the
* given transfer syntax and the given encoding type for sequences.
* For elements, the length includes the length of the tag, length field,
* VR field and the value itself, for items and sequences it returns
* the length of the complete item or sequence including delimitation tags
* if applicable.
* If length encoding is set to be explicit and the total item size is
* larger than the available 32-bit length field, then undefined length
* is returned. If "dcmWriteOversizedSeqsAndItemsImplicit" is disabled,
* also the internal DcmObject errorFlag is set to EC_SeqOrItemContentOverflow
* in case the item content (excluding tag header etc.) is already too
* large.
* @param xfer transfer syntax for length calculation
* @param enctype sequence encoding type for length calculation
* @return length of DICOM element
*/
virtual Uint32 calcElementLength(const E_TransferSyntax xfer,
const E_EncodingType enctype);
/** calculate the value length (without attribute tag, VR and length field)
* of this DICOM element when encoded with the given transfer syntax and
* the given encoding type for sequences.
* If length encoding is set to be explicit and the item content is larger
* than the available 32-bit length field, then undefined length is
* returned. If "dcmWriteOversizedSeqsAndItemsUndefined" is disabled,
* also the internal DcmObject errorFlag is set to
* EC_SeqOrItemContentOverflow.
* @param xfer transfer syntax for length calculation
* @param enctype sequence encoding type for length calculation
* @return value length of DICOM element
*/
virtual Uint32 getLength(const E_TransferSyntax xfer = EXS_LittleEndianImplicit,
const E_EncodingType enctype = EET_UndefinedLength);
/** initialize the transfer state of this object. This method must be called
* before this object is written to a stream or read (parsed) from a stream.
*/
virtual void transferInit();
/** finalize the transfer state of this object. This method must be called
* when reading/writing this object from/to a stream has been completed.
*/
virtual void transferEnd();
/** get parent item of this object, i.e.\ the item/dataset in which the
* surrounding sequence element is stored.
* @return pointer to the parent item of this object (might be NULL)
*/
virtual DcmItem *getParentItem();
/** check if this DICOM object can be encoded in the given transfer syntax.
* @param newXfer transfer syntax in which the DICOM object is to be encoded
* @param oldXfer transfer syntax in which the DICOM object was read or created.
* @return true if object can be encoded in desired transfer syntax, false otherwise.
*/
virtual OFBool canWriteXfer(const E_TransferSyntax newXfer,
const E_TransferSyntax oldXfer);
/** This function reads the information of all attributes which
* are captured in the input stream and captures this information
* in elementList. Each attribute is represented as an element
* in this list. If not all information for an attribute could be
* read from the stream, the function returns EC_StreamNotifyClient.
* @param inStream The stream which contains the information.
* @param ixfer The transfer syntax which was used to encode
* the information in inStream.
* @param glenc Encoding type for group length; specifies
* what will be done with group length tags.
* @param maxReadLength Maximum read length for reading an attribute value.
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition read(DcmInputStream &inStream,
const E_TransferSyntax ixfer,
const E_GrpLenEncoding glenc = EGL_noChange,
const Uint32 maxReadLength = DCM_MaxReadLength);
/** write object to a stream
* @param outStream DICOM output stream
* @param oxfer output transfer syntax
* @param enctype encoding types (undefined or explicit length)
* @param wcache pointer to write cache object, may be NULL
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition write(DcmOutputStream &outStream,
const E_TransferSyntax oxfer,
const E_EncodingType enctype,
DcmWriteCache *wcache);
/** write object in XML format
* @param out output stream to which the XML document is written
* @param flags optional flag used to customize the output (see DCMTypes::XF_xxx)
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition writeXML(STD_NAMESPACE ostream&out,
const size_t flags = 0);
/** special write method for creation of digital signatures
* @param outStream DICOM output stream
* @param oxfer output transfer syntax
* @param enctype encoding types (undefined or explicit length)
* @param wcache pointer to write cache object, may be NULL
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition writeSignatureFormat(DcmOutputStream &outStream,
const E_TransferSyntax oxfer,
const E_EncodingType enctype,
DcmWriteCache *wcache);
/** returns true if the object contains an element with Unknown VR at any nesting level
* @return true if the object contains an element with Unknown VR, false otherwise
*/
virtual OFBool containsUnknownVR() const;
/** check if this object contains non-ASCII characters at any nesting level. Please note
* that this check is pretty simple and only works for single-byte character sets that
* do include the 7-bit ASCII codes, e.g. for the ISO 8859 family. In other words: All
* character codes below 128 are considered to be ASCII codes and all others are
* considered to be non-ASCII.
* @param checkAllStrings if true, also check elements with string values not affected
* by SpecificCharacterSet (0008,0005). By default, only check PN, LO, LT, SH, ST,
* UC and UT.
* @return true if object contains non-ASCII characters, false otherwise
*/
virtual OFBool containsExtendedCharacters(const OFBool checkAllStrings = OFFalse);
/** check if this object is affected by SpecificCharacterSet at any nesting level.
* In detail, it is checked whether this object contains any data elements that
* according to their VR are affected by the SpecificCharacterSet (0008,0005)
* element. This is true for the following VRs: PN, LO, LT, SH, ST, UC and UT
* @return true if object is affected by SpecificCharacterSet, false otherwise
*/
virtual OFBool isAffectedBySpecificCharacterSet() const;
/** mode specifying whether the SpecificCharacterSet (0008,0005) element should be
* checked by convertCharacterSet() or not, i.e.\ whether this element might be
* present on this dataset-level. This method is reimplemented in derived classes.
* @return always returns OFFalse, i.e.\ SpecificCharacterSet should not be checked
*/
virtual OFBool checkForSpecificCharacterSet() const { return OFFalse; }
/** convert all element values that are contained in this item and that are affected
* by SpecificCharacterSet from the given source character set to the given
* destination character set. The defined terms for a particular character set can
* be found in the DICOM standard, e.g. "ISO_IR 100" for ISO 8859-1 (Latin 1) or
* "ISO_IR 192" for Unicode in UTF-8. An empty string denotes the default character
* repertoire, which is ASCII (7-bit). If multiple values are given for 'fromCharset'
* (separated by a backslash) code extension techniques are used and escape sequences
* may be encountered in the source string to switch between the specified character
* sets.
* @param fromCharset name of the source character set(s) used for the conversion
* @param toCharset name of the destination character set used for the conversion.
* Only a single value is permitted (i.e. no code extensions).
* @param transliterate mode specifying whether a character that cannot be
* represented in the destination character encoding is approximated through one
* or more characters that look similar to the original one
* @param updateCharset if OFTrue, the SpecificCharacterSet (0008,0005) element is
* updated, i.e.\ the current value is either replaced or a new element is inserted
* or the existing element is deleted. If OFFalse the SpecificCharacterSet element
* remains unchanged.
* @param discardIllegal mode specifying whether characters that cannot be represented
* in the destination character encoding will be silently discarded
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition convertCharacterSet(const OFString &fromCharset,
const OFString &toCharset,
const OFBool transliterate = OFFalse,
const OFBool updateCharset = OFFalse,
const OFBool discardIllegal = OFFalse);
/** convert all element values that are contained in this item and that are affected
* by SpecificCharacterSet to the given destination character set. If not disabled,
* the source character set is determined automatically from the value of the
* SpecificCharacterSet (0008,0005) element. The defined terms for the destination
* character set can be found in the DICOM standard, e.g. "ISO_IR 100" for ISO 8859-1
* (Latin 1) or "ISO_IR 192" for Unicode in UTF-8. An empty string denotes the
* default character repertoire, which is ASCII (7-bit).
* @param toCharset name of the destination character set used for the conversion.
* Only a single value is permitted (i.e. no code extensions).
* @param transliterate mode specifying whether a character that cannot be
* represented in the destination character encoding is approximated through one
* or more characters that look similar to the original one
* @param ignoreCharset if OFTrue, the value of SpecificCharacterSet is ignored.
* Also see checkForSpecificCharacterSet().
* @param discardIllegal mode specifying whether characters that cannot be represented
* in the destination character encoding will be silently discarded
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition convertCharacterSet(const OFString &toCharset,
const OFBool transliterate = OFFalse,
const OFBool ignoreCharset = OFFalse,
const OFBool discardIllegal = OFFalse);
/** convert all element values that are contained in this item and that are affected
* by SpecificCharacterSet from the currently selected source character set to the
* currently selected destination character set
* @param converter character set converter to be used to convert the element values
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition convertCharacterSet(DcmSpecificCharacterSet &converter);
/** convert all element values that are contained in this item and that are affected
* by SpecificCharacterSet to UTF-8 (Unicode). The value of the SpecificCharacterSet
* (0008,0005) element is updated, set or deleted automatically if needed. The
* transliteration mode is disabled - see convertCharacterSet().
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition convertToUTF8();
/** insert a new element into the list of elements maintained by this item.
* The list of elements is always kept in ascending tag order.
* @param elem element to be inserted, must not be contained in this or
* any other item. Will be deleted upon destruction of this item object.
* @param replaceOld if true, this element replaces any other element with
* the same tag which may already be contained in the item. If false,
* insert fails if another element with the same tag is already present.
* @param checkInsertOrder if true, a warning message is sent to the console
* if the element is not inserted at the end of the list. This is used
* in the read() method to detect datasets with out-of-order elements.
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition insert(DcmElement *elem,
OFBool replaceOld = OFFalse,
OFBool checkInsertOrder = OFFalse);
/** access an element from the item. This method returns a pointer to one
* of the elements in the item, and not a copy.
* @param num index number of element, must be < card()
* @return pointer to element if found, NULL if num >= card()
*/
virtual DcmElement *getElement(const unsigned long num);
/** this method enables a stack based, depth-first traversal of a complete
* hierarchical DICOM dataset (that is, classes derived from DcmItem or
* DcmSequenceOfItems). With each call of this method, the next object
* in the tree is located and marked on the stack.
* @param stack "cursor" for current position in the dataset. The stack
* will contain a pointer to each dataset, sequence, item and element
* from the main dataset down to the current element, and is updated
* upon each call to this method. An empty stack is equivalent to a stack
* containing a pointer to this object only.
* @param intoSub if true, the nextObject method will perform a hierarchical
* search through the dataset (depth-first), if false, only the current
* container object will be traversed (e.g., all elements of an item
* or all items of a sequence).
* @return EC_Normal if value length is correct, an error code otherwise
*/
virtual OFCondition nextObject(DcmStack &stack,
const OFBool intoSub);
/** this method is only used in container classes,
* that is, DcmItem and DcmSequenceOfItems. It returns a pointer to the
* next object in the list AFTER the given object. If the caller passes NULL,
* a pointer to the first object in the list is returned. If the given object
* is not found, the given object is the last one in the list or the list is empty,
* NULL is returned.
* @param obj pointer to one object in the container; we are looking for the
* next entry after this one. NULL if looking for the first entry.
* @return pointer to next object in container or NULL if not found
*/
virtual DcmObject *nextInContainer(const DcmObject *obj);
/** remove element from list. If found, the element is not deleted but
* returned to the caller who is responsible for further management of the
* DcmElement object.
* @param num index number of element, must be < card()
* @return pointer to DcmElement if found, NULL otherwise
*/
virtual DcmElement *remove(const unsigned long num);
/** remove element from list. If found, the element is not deleted but
* returned to the caller who is responsible for further management of the
* DcmElement object.
* @param elem pointer to element (as type DcmObject *) to be removed from list
* @return pointer to element (as type DcmElement *) if found, NULL otherwise
*/
virtual DcmElement *remove(DcmObject *elem);
/** remove element from list. If found, the element is not deleted but
* returned to the caller who is responsible for further management of the
* DcmElement object.
* @param tag attribute tag of element to be removed
* @return pointer to DcmElement if found, NULL otherwise
*/
virtual DcmElement *remove(const DcmTagKey &tag);
/** check if this item is empty
* @param normalize not used for this class
* @return true if item is empty, i.e.\ has no elements, false otherwise
*/
virtual OFBool isEmpty(const OFBool normalize = OFTrue);
/** clear (remove) all attributes from item and delete them from memory.
* @return EC_Normal if successful, an error code otherwise
*/
virtual OFCondition clear();
/** check the currently stored element value
* @param autocorrect correct value length if OFTrue
* @return status, EC_Normal if value length is correct, an error code otherwise
*/
virtual OFCondition verify(const OFBool autocorrect = OFFalse );
/** a complex, stack-based, hierarchical search method. It allows for a search
* for a DICOM object with a given attribute within a given container,
* hierarchically, from a starting position identified through a cursor stack.
* @param xtag the DICOM attribute tag we are searching for
* @param resultStack Depending on the search mode (see below), this parameter
* either serves as an input and output parameter, or as an output parameter
* only (the latter being the default). When used as an input parameter,
* the cursor stack defines the start position for the search within a
* hierarchical DICOM dataset. Upon successful return, the stack contains
* the position of the element found, in the form of a pointer to each dataset,
* sequence, item and element from the main dataset down to the found element.
* @param mode search mode, controls how the search stack is handled.
* In the default mode, ESM_fromHere, the stack is ignored on input, and
* the search starts in the object for which this method is called.
* In the other modes, the stack is used both as an input and an output
* parameter and defines the starting point for the search.
* @param searchIntoSub if true, the search will be performed hierarchically descending
* into the sequences and items of the dataset. If false, only the current container
* (sequence or item) will be traversed.
* @return EC_Normal if found, EC_TagNotFound if not found, an error code is something
* went wrong.
*/
virtual OFCondition search(const DcmTagKey &xtag, // in
DcmStack &resultStack, // inout
E_SearchMode mode = ESM_fromHere, // in
OFBool searchIntoSub = OFTrue ); // in
/** this method loads all attribute values maintained by this object and
* all sub-objects (in case of a container such as DcmDataset) into memory.
* After a call to this method, the file from which a dataset was read may safely
* be deleted or replaced. For large files, this method may obviously allocate large
* amounts of memory.
* @return EC_Normal if successful, an error code otherwise
*/
virtual OFCondition loadAllDataIntoMemory();
/** iterate over all elements and remove those element values from memory which exceed
* a given length and which can be loaded from file when needed again. For all other
* elements, nothing is done.
* @param maxLength maximum length (number of bytes) allowed without removing the value
*/
virtual void compactElements(const Uint32 maxLength);
/** This function takes care of group length and padding elements
* in the current element list according to what is specified in
* glenc and padenc. If required, this function does the following
* two things:
* a) it calculates the group length of all groups which are
* contained in this item and sets the calculated values
* in the corresponding group length elements and
* b) it inserts a corresponding padding element (or, in case
* of sequences: padding elements) with a corresponding correct
* size into the element list.
* @param glenc Encoding type for group length; specifies what shall
* be done with group length tags.
* @param padenc Encoding type for padding; specifies what shall be
* done with padding tags.
* @param xfer The transfer syntax that shall be used.
* @param enctype Encoding type for sequences; specifies how sequences
* will be handled.
* @param padlen The length up to which the dataset shall be padded,
* if padding is desired.
* @param subPadlen For sequences (ie sub elements), the length up to
* which item shall be padded, if padding is desired.
* @param instanceLength Number of extra bytes added to the item/dataset
* length used when computing the padding; this
* parameter is for instance used to pass the length
* of the file meta header from the DcmFileFormat to
* the DcmDataset object.
* @return status, EC_Normal if successful, an error code otherwise
*/
virtual OFCondition computeGroupLengthAndPadding(const E_GrpLenEncoding glenc,
const E_PaddingEncoding padenc = EPD_noChange,
const E_TransferSyntax xfer = EXS_Unknown,
const E_EncodingType enctype = EET_ExplicitLength,
const Uint32 padlen = 0,
const Uint32 subPadlen = 0,
Uint32 instanceLength = 0);
/** check if an element with the given attribute tag exists in the dataset
* @param key tag key to be searched
* @param searchIntoSub if true, do hierarchical search within sequences,
* if false only search through this dataset
* @return true if tag found, false otherwise
*/
OFBool tagExists(const DcmTagKey &key,
OFBool searchIntoSub = OFFalse);
/** check if an element with the given attribute tag exists in the dataset
* and has a non-empty value
* @param key tag key to be searched
* @param searchIntoSub if true, do hierarchical search within sequences,
* if false only search through this dataset
* @return true if tag found and element non-empty, false otherwise
*/
OFBool tagExistsWithValue(const DcmTagKey &key,
OFBool searchIntoSub = OFFalse);
/* --- findAndGet functions: find an element and get it or the value, respectively --- */
/** find element and get a pointer to it (or copy it).
* Applicable to all DICOM value representations (VR).
* The result variable 'element' is automatically set to NULL if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param element variable in which the reference to (or copy of) the element is stored
* @param searchIntoSub flag indicating whether to search into sequences or not
* @param createCopy create a copy of the element if true, return a reference otherwise
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetElement(const DcmTagKey &tagKey,
DcmElement *&element,
const OFBool searchIntoSub = OFFalse,
const OFBool createCopy = OFFalse);
/** find all elements matching a particular tag and return references to them on a stack.
* This functions always performs a deep search (i.e. searches into sequence of items).
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param resultStack stack where references to the elements are stored (added to).
* If no element is found, the stack is not modified (e.g. cleared).
* @return EC_Normal if at least one matching tag is found, an error code otherwise.
*/
OFCondition findAndGetElements(const DcmTagKey &tagKey,
DcmStack &resultStack);
/** find element and get value as a reference to a C string. NB: The string is not copied!
* Applicable to the following VRs: AE, AS, CS, DA, DS, DT, IS, LO, LT, PN, SH, ST, TM, UC, UI,
* UR, UT
* Since the getString() routine is called internally the resulting string reference represents
* the (possibly multi-valued) value as stored in the dataset, i.e. no normalization is performed.
* The result variable 'value' is automatically set to NULL if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the reference to the element value is stored (might be NULL)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetString(const DcmTagKey &tagKey,
const char *&value,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as a reference to a C string. NB: The string is not copied!
* Applicable to the following VRs: AE, AS, CS, DA, DS, DT, IS, LO, LT, PN, SH, ST, TM, UC, UI,
* UR, UT
* Since the getString() routine is called internally the resulting string reference represents
* the (possibly multi-valued) value as stored in the dataset, i.e. no normalization is performed.
* The result variable 'value' is automatically set to NULL and 'length' is set to 0 if an error
* occurs.
* Please note that since the length is returned separately, the string value can contain more
* than one NULL byte.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the reference to the element value is stored (might be NULL)
* @param length length of the string (number of characters without the trailing NULL byte)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetString(const DcmTagKey &tagKey,
const char *&value,
Uint32 &length,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as a C++ string (only one component).
* Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB, OD, OF,
* OL, OW, PN, SH, SL, SS, ST, TM, UC, UI, UL, UR, US, UT
* Since the getOFString() routine is called internally the resulting string is normalized, i.e.
* leading and/or trailing spaces are removed according to the associated value representation,
* or the element value is converted to a character string (for non-string VRs) - see documentation
* in the corresponding header file.
* In contrast to the above and below function only the specified component (see parameter 'pos')
* is returned. The result variable 'value' is automatically set to an empty string if an error
* occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param pos index of the value in case of multi-valued elements (0..vm-1)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetOFString(const DcmTagKey &tagKey,
OFString &value,
const unsigned long pos = 0,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as a C++ string (all components).
* Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB, OD, OF,
* OL, OW, PN, SH, SL, SS, ST, TM, UC, UI, UL, UR, US, UT
* Since the getOFStringArray() routine is called internally the resulting string is normalized,
* i.e. leading and/or trailing spaces are removed according to the associated value representation
* or the element values are converted to character strings (for non-string VRs) - see documentation
* in the corresponding header file.
* The result variable 'value' is automatically set to an empty string if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetOFStringArray(const DcmTagKey &tagKey,
OFString &value,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an unsigned 8-bit integer.
* Applicable to the following VRs: OB
* The result variable 'value' is automatically set to zero if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param pos index of the value in case of multi-valued elements (0..vm-1)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetUint8(const DcmTagKey &tagKey,
Uint8 &value,
const unsigned long pos = 0,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an array of unsigned 8-bit integers.
* Applicable to the following VRs: OB
* The result variable 'value' is automatically set to NULL if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the reference to the element value is stored
* @param count stores number of items in the result array (if not NULL)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetUint8Array(const DcmTagKey &tagKey,
const Uint8 *&value,
unsigned long *count = NULL,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an unsigned 16-bit integer.
* Applicable to the following VRs: OW, US
* The result variable 'value' is automatically set to zero if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param pos index of the value in case of multi-valued elements (0..vm-1)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetUint16(const DcmTagKey &tagKey,
Uint16 &value,
const unsigned long pos = 0,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an array of unsigned 16-bit integers.
* Applicable to the following VRs: AT, OW, US
* The result variable 'value' is automatically set to NULL if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the reference to the element value is stored
* @param count stores number of items in the result array (if not NULL)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetUint16Array(const DcmTagKey &tagKey,
const Uint16 *&value,
unsigned long *count = NULL,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as a signed 16-bit integer.
* Applicable to the following VRs: SS
* The result variable 'value' is automatically set to zero if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param pos index of the value in case of multi-valued elements (0..vm-1)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetSint16(const DcmTagKey &tagKey,
Sint16 &value,
const unsigned long pos = 0,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an array of signed 16-bit integers.
* Applicable to the following VRs: SS
* The result variable 'value' is automatically set to NULL if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the reference to the element value is stored
* @param count stores number of items in the result array (if not NULL)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetSint16Array(const DcmTagKey &tagKey,
const Sint16 *&value,
unsigned long *count = NULL,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an unsigned 32-bit integer.
* Applicable to the following VRs: OL, UL
* The result variable 'value' is automatically set to zero if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param pos index of the value in case of multi-valued elements (0..vm-1)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetUint32(const DcmTagKey &tagKey,
Uint32 &value,
const unsigned long pos = 0,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an array of unsigned 32-bit integers.
* Applicable to the following VRs: OL, UL
* The result variable 'value' is automatically set to NULL if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the reference to the element value is stored
* @param count stores number of items in the result array (if not NULL)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetUint32Array(const DcmTagKey &tagKey,
const Uint32 *&value,
unsigned long *count = NULL,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as a signed 32-bit integer.
* Applicable to the following VRs: IS, SL
* The result variable 'value' is automatically set to zero if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param pos index of the value in case of multi-valued elements (0..vm-1)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetSint32(const DcmTagKey &tagKey,
Sint32 &value,
const unsigned long pos = 0,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an array of signed 32-bit integers.
* Applicable to the following VRs: SL
* The result variable 'value' is automatically set to NULL if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the reference to the element value is stored
* @param count stores number of items in the result array (if not NULL)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetSint32Array(const DcmTagKey &tagKey,
const Sint32 *&value,
unsigned long *count = NULL,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as a (signed) long integer.
* Applicable to the following VRs: IS, OL, SL, SS, UL, US
* The result variable 'value' is automatically set to zero if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param pos index of the value in case of multi-valued elements (0..vm-1)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetLongInt(const DcmTagKey &tagKey,
long int &value,
const unsigned long pos = 0,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as a 32-bit floating point.
* Applicable to the following VRs: FL, OF
* The result variable 'value' is automatically set to zero if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param pos index of the value in case of multi-valued elements (0..vm-1)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetFloat32(const DcmTagKey &tagKey,
Float32 &value,
const unsigned long pos = 0,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an array of 32-bit floating point values.
* Applicable to the following VRs: FL, OF
* The result variable 'value' is automatically set to NULL if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the reference to the element value is stored
* @param count stores number of items in the result array (if not NULL)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetFloat32Array(const DcmTagKey &tagKey,
const Float32 *&value,
unsigned long *count = NULL,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as a 64-bit floating point.
* Applicable to the following VRs: DS, FD, OD
* The result variable 'value' is automatically set to zero if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the element value is stored
* @param pos index of the value in case of multi-valued elements (0..vm-1)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetFloat64(const DcmTagKey &tagKey,
Float64 &value,
const unsigned long pos = 0,
const OFBool searchIntoSub = OFFalse);
/** find element and get value as an array of 64-bit floating point values.
* Applicable to the following VRs: FD, OD
* The result variable 'value' is automatically set to NULL if an error occurs.
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param value variable in which the reference to the element value is stored
* @param count stores number of items in the result array (if not NULL)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndGetFloat64Array(const DcmTagKey &tagKey,
const Float64 *&value,
unsigned long *count = NULL,
const OFBool searchIntoSub = OFFalse);
/** looks up and returns a given sequence.
* Applicable to the following VRs: SQ, (pixelSQ)
* The result variable 'sequence' is automatically set to NULL if an error occurs
* (e.g. if 'seqTagKey' does not refer to a sequence attribute).
* @param seqTagKey DICOM tag specifying the sequence attribute to be searched for
* @param sequence variable in which the reference to (or copy of) the sequence is stored
* @param searchIntoSub flag indicating whether to search into sub-sequences or not
* @param createCopy create a copy of the sequence if true, return a reference otherwise
* @return EC_Normal upon success, an error otherwise.
*/
OFCondition findAndGetSequence(const DcmTagKey &seqTagKey,
DcmSequenceOfItems *&sequence,
const OFBool searchIntoSub = OFFalse,
const OFBool createCopy = OFFalse);
/** looks up and returns a given sequence item, if it exists. Otherwise sets 'item'
* to NULL and returns EC_TagNotFound (specified sequence does not exist) or
* EC_IllegalParameter (specified item does not exist). Only the top-most level of
* the dataset/item is examined (i.e. no deep-search is performed).
* Applicable to the following VRs: SQ, (pixelSQ)
* @param seqTagKey DICOM tag specifying the sequence attribute to be searched for
* @param item variable in which the reference to (or copy of) the item is stored
* @param itemNum number of the item to be searched for (0..n-1, -1 for last)
* @param createCopy create a copy of the item if true, return a reference otherwise
* @return EC_Normal upon success, an error otherwise.
*/
OFCondition findAndGetSequenceItem(const DcmTagKey &seqTagKey,
DcmItem *&item,
const signed long itemNum = 0,
const OFBool createCopy = OFFalse);
/* --- findOrCreate functions: find an element or create a new one --- */
/** looks up the given sequence in the current dataset and returns the given item.
* If either the sequence or the item do not exist, they are created. If necessary,
* multiple empty items are inserted. Only the top-most level of the dataset/item
* is examined (i.e. no deep-search is performed).
* Applicable to the following VRs: SQ, (pixelSQ)
* @param seqTag DICOM tag specifying the sequence attribute to be searched for
* (or to be created)
* @param item variable in which the reference to the sequence item is stored
* @param itemNum number of the item to be searched for (0..n-1, -1 for last,
* -2 for append new)
* @return EC_Normal upon success, an error otherwise.
*/
OFCondition findOrCreateSequenceItem(const DcmTag &seqTag,
DcmItem *&item,
const signed long itemNum = 0);
/* --- findAndXXX functions: find an element and do something with it --- */
/** find element, create a copy and insert it into the given destination dataset.
* This functions never performs a deep search (i.e. does not search into sequence
* of items). Empty elements are also copied. However, if the given tag is not
* found in the current dataset, EC_TagNotFound is returned and the destination
* dataset remains unchanged.
* Applicable to all DICOM value representations (VR).
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param destItem destination dataset to which the copied element is inserted
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise
*/
OFCondition findAndInsertCopyOfElement(const DcmTagKey &tagKey,
DcmItem *destItem,
const OFBool replaceOld = OFTrue);
/** find element, remove it from the dataset and free the associated memory.
* Applicable to all DICOM value representations (VR).
* @param tagKey DICOM tag specifying the attribute to be searched for
* @param allOccurrences flag indicating whether to delete all occurrences of the
* attribute tag or the first one only (implies 'searchIntoSub' to be true)
* @param searchIntoSub flag indicating whether to search into sequences or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition findAndDeleteElement(const DcmTagKey &tagKey,
const OFBool allOccurrences = OFFalse,
const OFBool searchIntoSub = OFFalse);
/** looks up the given sequence in the current dataset and deletes the given item.
* Applicable to the following VRs: SQ, (pixelSQ)
* @param seqTagKey DICOM tag specifying the sequence attribute to be searched for
* @param itemNum number of the item to be deleted (0..n-1, -1 for last)
* @return EC_Normal upon success, an error otherwise.
*/
OFCondition findAndDeleteSequenceItem(const DcmTagKey &seqTagKey,
const signed long itemNum);
/* --- putAndInsert functions: put value and insert new element --- */
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB, OD, OF,
* OL, OW, PN, SH, SL, SS, ST, TM, UC, UI, UL, UR, US, UT
* @param tag DICOM tag specifying the attribute to be created
* @param value string value to be set for the new element (might be empty or NULL)
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertString(const DcmTag &tag,
const char *value,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB, OD, OF,
* OL, OW, PN, SH, SL, SS, ST, TM, UC, UI, UL, UR, US, UT
* Please note that since the length of the string has to be specified explicitly, the string
* can contain more than one NULL byte.
* @param tag DICOM tag specifying the attribute to be created
* @param value string value to be set for the new element (might be empty or NULL)
* @param length length of the string (number of characters without the trailing NULL byte)
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertString(const DcmTag &tag,
const char *value,
const Uint32 length,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: AE, AS, CS, DA, DS, DT, IS, LO, LT, PN, SH, ST, TM, UC, UI,
* UR, UT
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element (might be empty)
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertOFStringArray(const DcmTag &tag,
const OFString &value,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: OB, ox (polymorph OB/OW or pixel data)
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element (might be NULL)
* @param count number of values (= bytes in this case) to be copied from 'value'
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertUint8Array(const DcmTag &tag,
const Uint8 *value,
const unsigned long count,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: US, xs (US or SS)
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param pos index of the value to be set (0..vm). A value can be appended to
* the end of or inserted within the existing value field.
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertUint16(const DcmTag &tag,
const Uint16 value,
const unsigned long pos = 0,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: AT, OW, US, ox (polymorph OB/OW or pixel data), xs (US or SS)
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element (might be NULL)
* @param count number of values (not bytes!) to be copied from 'value'
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertUint16Array(const DcmTag &tag,
const Uint16 *value,
const unsigned long count,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: SS, xs (US or SS)
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param pos index of the value to be set (0..vm). A value can be appended to
* the end of or inserted within the existing value field.
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertSint16(const DcmTag &tag,
const Sint16 value,
const unsigned long pos = 0,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: SS, xs (US or SS)
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param count number of values (not bytes!) to be copied from 'value'
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertSint16Array(const DcmTag &tag,
const Sint16 *value,
const unsigned long count,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: OL, UL
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param pos index of the value to be set (0..vm). A value can be appended to
* the end of or inserted within the existing value field.
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertUint32(const DcmTag &tag,
const Uint32 value,
const unsigned long pos = 0,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: OL, UL
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param count number of values (not bytes!) to be copied from 'value'
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertUint32Array(const DcmTag &tag,
const Uint32 *value,
const unsigned long count,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: SL
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param pos index of the value to be set (0..vm). A value can be appended to
* the end of or inserted within the existing value field.
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertSint32(const DcmTag &tag,
const Sint32 value,
const unsigned long pos = 0,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: FL, OF
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param pos index of the value to be set (0..vm). A value can be appended to
* the end of or inserted within the existing value field.
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertFloat32(const DcmTag &tag,
const Float32 value,
const unsigned long pos = 0,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: FL, OF
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param count number of values (not bytes!) to be copied from 'value'
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertFloat32Array(const DcmTag &tag,
const Float32 *value,
const unsigned long count,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: FD, OD
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param pos index of the value to be set (0..vm). A value can be appended to
* the end of or inserted within the existing value field.
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertFloat64(const DcmTag &tag,
const Float64 value,
const unsigned long pos = 0,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: FD, OD
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param count number of values (not bytes!) to be copied from 'value'
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertFloat64Array(const DcmTag &tag,
const Float64 *value,
const unsigned long count,
const OFBool replaceOld = OFTrue);
/** create a new element, put specified value to it and insert the element into the dataset/item.
* Applicable to the following VRs: AT
* @param tag DICOM tag specifying the attribute to be created
* @param value value to be set for the new element
* @param pos index of the value to be set (0..vm). A value can be appended to
* the end of or inserted within the existing value field.
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition putAndInsertTagKey(const DcmTag &tag,
const DcmTagKey &value,
const unsigned long pos = 0,
const OFBool replaceOld = OFTrue);
/* --- insertXXX functions: insert new element --- */
/** create a new element (with no value) and insert it into the dataset/item.
* Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB, OD, OF,
* OL, OW, PN, SH, SL, SQ, SS, ST, TM, UC, UI, UL, UR, US, UT
* @param tag DICOM tag specifying the attribute to be created
* @param replaceOld flag indicating whether to replace an existing element or not
* @return EC_Normal upon success, an error code otherwise.
*/
OFCondition insertEmptyElement(const DcmTag &tag,
const OFBool replaceOld = OFTrue);
/** looks up the given sequence in the current dataset and inserts the given item.
* If the sequence does not exist, it is created. If necessary, multiple empty items
* are inserted before the specified item position. Only the top-most level of the
* dataset/item is examined (i.e. no deep-search is performed).
* Applicable to the following VRs: SQ, (pixelSQ)
* @param seqTag DICOM tag specifying the sequence attribute to be searched for
* (or to be created)
* @param item item to be inserted into the sequence, must not be contained in this
* or any other sequence. Will be deleted upon destruction of the sequence object.
* @param itemNum position of the item (0..n-1, -1 = before last, -2 = after last)
* @return EC_Normal upon success, an error otherwise (delete 'item' manually!).
*/
OFCondition insertSequenceItem(const DcmTag &seqTag,
DcmItem *item,
const signed long itemNum = -2);
protected:
/// the list of elements maintained by this object
DcmList *elementList;
/** flag used during suspended I/O. Indicates whether the last element
* was completely or only partially read/written during the last call
* to read/write.
*/
OFBool lastElementComplete;
/** used during reading. Contains the position in the stream where
* the item started (needed for calculating the remaining number of
* bytes available for a fixed-length item).
*/
offile_off_t fStartPosition;
protected:
/** This function reads tag and length information from inStream and
* returns this information to the caller. When reading information,
* the transfer syntax which was passed is accounted for. If the
* transfer syntax shows an explicit value representation, the data
* type of this object is also read from the stream. In general, this
* function follows the rules which are specified in the DICOM standard
* (see DICOM standard (year 2000) part 5, section 7) (or the corresponding
* section in a later version of the standard) concerning the encoding
* of a dataset.
* @param inStream The stream which contains the information.
* @param xfer The transfer syntax which was used to encode the
* information in inStream.
* @param tag Contains in the end the tag that was read.
* @param length Contains in the end the length value that was read.
* @param bytesRead Contains in the end the amount of bytes which were
* read from inStream.
* @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition readTagAndLength(DcmInputStream &inStream, // inout
const E_TransferSyntax xfer, // in
DcmTag &tag, // out
Uint32 &length, // out
Uint32 &bytesRead); // out
/** This function creates a new DcmElement object on the basis of the newTag
* and newLength information which was passed, inserts this new element into
* elementList, reads the actual data value which belongs to this element
* (attribute) from the inStream and also assigns this information to the
* object which was created at the beginning.
* @param inStream The stream which contains the information.
* @param newTag The tag of the element of which the information is
* being read.
* @param newLength The length of the information which is being read.
* @param xfer The transfer syntax which was used to encode the
* information in inStream.
* @param glenc Encoding type for group length. Specifies what will
* be done with group length tags.
* @param maxReadLength Maximum read length for reading the attribute value.
* @return status, EC_Normal if successful, an error code otherwise
*/
OFCondition readSubElement(DcmInputStream &inStream, // inout
DcmTag &newTag, // inout
const Uint32 newLength, // in
const E_TransferSyntax xfer, // in
const E_GrpLenEncoding glenc, // in
const Uint32 maxReadLength = DCM_MaxReadLength);
/** This function reads the first 6 bytes from the input stream and determines
* the transfer syntax which was used to code the information in the stream.
* The decision is based on two questions: a) Did we encounter a valid tag?
* and b) Do the last 2 bytes which were read from the stream represent a valid
* VR? In certain special cases, where the transfer syntax cannot be determined
* without doubt, we want to guess the most likely transfer syntax (see code).
* @param inStream The stream which contains the coded information.
* @return The transfer syntax which was determined.
*/
E_TransferSyntax checkTransferSyntax(DcmInputStream &inStream);
/** check whether the given tag requires some special handling regarding the VR
* (i.e.\ in case it is undefined and multiple values are possible). If required,
* the VR of the given element tag is then updated according to the DICOM
* standard, e.g. the VR of PixelPaddingValue (if undefined) is set to 'SS' or
* 'US' depending on the value of PixelRepresentation.
* @param item dataset or item that can be used to lookup other element values
* @param tag tag of the element to be checked and updated (if required)
*/
void checkAndUpdateVR(DcmItem &item,
DcmTag &tag);
/** update the SpecificCharacterSet (0008,0005) element depending on the given
* parameters. The current value of this element is either replaced or a new
* element is inserted or the existing element is deleted.
* @param status error status of previous operations (might also be updated)
* @param converter character set converter used to convert element values
*/
void updateSpecificCharacterSet(OFCondition &status,
const DcmSpecificCharacterSet &converter);
private:
/** helper function for search(). May only be called if elementList is non-empty.
* Performs hierarchical search for given tag and pushes pointer of sub-element
* on result stack if found
* @param tag tag key to be searched
* @param resultStack upon successful return, pointer to element pushed onto this stack
* @param searchIntoSub flag indicating whether recursive search is desired
* @return EC_Normal if tag found and stack modified, EC_TagNotFound if tag not found
* and stack unmodified
*/
OFCondition searchSubFromHere(const DcmTagKey &tag, // in
DcmStack &resultStack, // inout
OFBool searchIntoSub ); // in
/** helper function that interprets the given pointer as a pointer to an
* array of two characters and checks whether these two characters form
* a valid standard DICOM VR.
* @param atposition pointer to array of (at least) two bytes interpreted as VR
* @return true if standard VR, false otherwise
*/
static OFBool foundVR(const Uint8* atposition);
/// cache for private creator tags and names
DcmPrivateTagCache privateCreatorCache;
};
/** Checks whether left hand side item is smaller than right hand side
* item. Uses DcmItem's compare() method in order to perform the
* comparison. See DcmItem::compare() for details.
* @param lhs left hand side of the comparison
* @param rhs right hand side of the comparison
* @return OFTrue if lhs is smaller than rhs, OFFalse otherwise
*/
inline OFBool operator< (const DcmItem& lhs, const DcmItem& rhs)
{
return ( lhs.compare(rhs) < 0 );
}
/** Checks whether left hand side item is greater than right hand side
* item. Uses DcmItem's compare() method in order to perform the
* comparison. See DcmItem::compare() for details.
* @param lhs left hand side of the comparison
* @param rhs right hand side of the comparison
* @return OFTrue if lhs is greater than rhs, OFFalse otherwise
*/
inline OFBool operator> (const DcmItem& lhs, const DcmItem& rhs)
{
return rhs < lhs;
}
/** Checks whether left hand side item is smaller than or equal to right hand
* side item. Uses DcmItem's compare() method in order to perform the
* comparison. See DcmItem::compare() for details.
* @param lhs left hand side of the comparison
* @param rhs right hand side of the comparison
* @return OFTrue if lhs is smaller than rhs or both are equal, OFFalse
* otherwise
*/
inline OFBool operator<=(const DcmItem& lhs, const DcmItem& rhs)
{
return !(lhs > rhs);
}
/** Checks whether left hand side element is greater than or equal to right hand
* side element. Uses DcmElement's compare() method in order to perform the
* comparison. See DcmElement::compare() for details.
* @param lhs left hand side of the comparison
* @param rhs right hand side of the comparison
* @return OFTrue if lhs is greater than rhs or both are equal, OFFalse
* otherwise
*/
inline OFBool operator>=(const DcmItem& lhs, const DcmItem& rhs)
{
return !(lhs < rhs);
}
//
// SUPPORT FUNCTIONS
//
/** helper function for DICOM parser. Creates new DICOM element from given attribute tag
* @param newElement pointer to newly created element returned in this parameter upon success,
* NULL pointer otherwise
* @param tag attribute tag of the element to be created
* @param length attribute value length of the element to be created
* @param privateCreatorCache cache object for private creator strings in the current dataset
* @param readAsUN flag indicating whether parser is currently handling a UN element that
* must be read in implicit VR little endian; updated upon return
* @return EC_Normal upon success, an error code otherwise
*/
DCMTK_DCMDATA_EXPORT OFCondition newDicomElement(DcmElement *&newElement,
DcmTag &tag,
const Uint32 length,
DcmPrivateTagCache *privateCreatorCache,
OFBool& readAsUN);
/** helper function for DICOM parser. Creates new DICOM element from given attribute tag
* @param newElement pointer to newly created element returned in this parameter upon success,
* NULL pointer otherwise
* @param tag attribute tag of the element to be created
* @param length attribute value length of the element to be created
* @return EC_Normal upon success, an error code otherwise
*/
DCMTK_DCMDATA_EXPORT OFCondition newDicomElement(DcmElement *&newElement,
const DcmTag &tag,
const Uint32 length = 0);
/** helper function for DICOM parser. Creates new DICOM element from given attribute tag
* @param tag attribute tag of the element to be created
* @param length attribute value length of the element to be created
* @return pointer to newly created element returned in this parameter upon success,
* NULL pointer otherwise
*/
DCMTK_DCMDATA_EXPORT DcmElement *newDicomElement(const DcmTag &tag,
const Uint32 length = 0);
/** helper function for DcmElement::nextObject.
* hierarchically traverses all datasets/items after the position indicated by the call stack
* @param st stack
* @return EC_Normal upon success, an error code otherwise
*/
DCMTK_DCMDATA_EXPORT OFCondition nextUp(DcmStack &st);
#endif // DCITEM_H
Reference in New Issue Copy Permalink