00001 /* 00002 * 00003 * Copyright (C) 1994-2010, OFFIS e.V. 00004 * All rights reserved. See COPYRIGHT file for details. 00005 * 00006 * This software and supporting documentation were developed by 00007 * 00008 * OFFIS e.V. 00009 * R&D Division Health 00010 * Escherweg 2 00011 * D-26121 Oldenburg, Germany 00012 * 00013 * 00014 * Module: dcmdata 00015 * 00016 * Author: Gerd Ehlers, Andreas Barth 00017 * 00018 * Purpose: Interface of class DcmElement 00019 * 00020 * Last Update: $Author: joergr $ 00021 * Update Date: $Date: 2010-11-05 09:34:11 $ 00022 * CVS/RCS Revision: $Revision: 1.49 $ 00023 * Status: $State: Exp $ 00024 * 00025 * CVS/RCS Log at end of file 00026 * 00027 */ 00028 00029 00030 #ifndef DCELEM_H 00031 #define DCELEM_H 00032 00033 #include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */ 00034 00035 #include "dcmtk/dcmdata/dcobject.h" 00036 #include "dcmtk/ofstd/ofstring.h" 00037 00038 // forward declarations 00039 class DcmInputStreamFactory; 00040 class DcmFileCache; 00041 class DcmItem; 00042 00045 class DcmElement 00046 : public DcmObject 00047 { 00048 00049 public: 00050 00056 DcmElement(const DcmTag &tag, 00057 const Uint32 len = 0); 00058 00062 DcmElement(const DcmElement &old); 00063 00066 virtual ~DcmElement(); 00067 00072 DcmElement &operator=(const DcmElement &obj); 00073 00086 virtual OFCondition copyFrom(const DcmObject& rhs); 00087 00098 virtual Uint32 calcElementLength(const E_TransferSyntax xfer, 00099 const E_EncodingType enctype); 00100 00108 virtual Uint32 getLength(const E_TransferSyntax /*xfer*/ = EXS_LittleEndianImplicit, 00109 const E_EncodingType /*enctype*/ = EET_UndefinedLength) 00110 { 00111 return getLengthField(); 00112 } 00113 00120 virtual OFBool isLeaf() const { return OFTrue; } 00121 00125 inline OFBool valueLoaded() const { return fValue != NULL || getLengthField() == 0; } 00126 00130 virtual void transferInit(); 00131 00137 virtual OFBool canWriteXfer(const E_TransferSyntax newXfer, 00138 const E_TransferSyntax oldXfer); 00139 00155 virtual OFCondition read(DcmInputStream &inStream, 00156 const E_TransferSyntax ixfer, 00157 const E_GrpLenEncoding glenc = EGL_noChange, 00158 const Uint32 maxReadLength = DCM_MaxReadLength); 00159 00182 virtual OFCondition write(DcmOutputStream &outStream, 00183 const E_TransferSyntax oxfer, 00184 const E_EncodingType enctype, 00185 DcmWriteCache *wcache); 00186 00192 virtual OFCondition writeXML(STD_NAMESPACE ostream &out, 00193 const size_t flags = 0); 00194 00202 virtual OFCondition writeSignatureFormat(DcmOutputStream &outStream, 00203 const E_TransferSyntax oxfer, 00204 const E_EncodingType enctype, 00205 DcmWriteCache *wcache); 00206 00210 virtual OFCondition clear(); 00211 00220 virtual OFCondition checkValue(const OFString &vm = "1-n", 00221 const OFBool oldFormat = OFFalse); 00222 00230 virtual OFCondition loadAllDataIntoMemory(); 00231 00232 // GET operations 00233 00240 virtual OFCondition getUint8(Uint8 &val, const unsigned long pos = 0); 00241 00248 virtual OFCondition getSint16(Sint16 &val, const unsigned long pos = 0); 00249 00256 virtual OFCondition getUint16(Uint16 &val, const unsigned long pos = 0); 00257 00264 virtual OFCondition getSint32(Sint32 &val, const unsigned long pos = 0); 00265 00272 virtual OFCondition getUint32(Uint32 &val, const unsigned long pos = 0); 00273 00280 virtual OFCondition getFloat32(Float32 &val, const unsigned long pos = 0); 00281 00288 virtual OFCondition getFloat64(Float64 &val, const unsigned long pos = 0); 00289 00296 virtual OFCondition getTagVal(DcmTagKey &val, const unsigned long pos = 0); 00297 00305 virtual OFCondition getOFString(OFString &str, 00306 const unsigned long pos, 00307 OFBool normalize = OFTrue); 00308 00318 virtual OFCondition getOFStringArray(OFString &value, 00319 OFBool normalize = OFTrue); 00320 00329 virtual OFCondition getString(char *&val); // for strings 00330 00339 virtual OFCondition getUint8Array(Uint8 *&val); // for bytes 00340 00349 virtual OFCondition getSint16Array(Sint16 *&val); 00350 00359 virtual OFCondition getUint16Array(Uint16 *&val); 00360 00369 virtual OFCondition getSint32Array(Sint32 *&val); 00370 00379 virtual OFCondition getUint32Array(Uint32 *&val); 00380 00389 virtual OFCondition getFloat32Array(Float32 *&val); 00390 00399 virtual OFCondition getFloat64Array(Float64 *&val); 00400 00409 OFCondition detachValueField(OFBool copy = OFFalse); 00410 00411 // PUT operations 00412 00418 virtual OFCondition putOFStringArray(const OFString &stringValue); 00419 00425 virtual OFCondition putString(const char *val); 00426 00436 virtual OFCondition putSint16(const Sint16 val, const unsigned long pos = 0); 00437 00447 virtual OFCondition putUint16(const Uint16 val, const unsigned long pos = 0); 00448 00458 virtual OFCondition putSint32(const Sint32 val, const unsigned long pos = 0); 00459 00469 virtual OFCondition putUint32(const Uint32 val, const unsigned long pos = 0); 00470 00480 virtual OFCondition putFloat32(const Float32 val, const unsigned long pos = 0); 00481 00491 virtual OFCondition putFloat64(const Float64 val, const unsigned long pos = 0); 00492 00502 virtual OFCondition putTagVal(const DcmTagKey &attrTag, const unsigned long pos = 0); 00503 00510 virtual OFCondition putUint8Array(const Uint8 *vals, const unsigned long num); 00511 00518 virtual OFCondition putSint16Array(const Sint16 *vals, const unsigned long num); 00519 00526 virtual OFCondition putUint16Array(const Uint16 *vals, const unsigned long num); 00527 00534 virtual OFCondition putSint32Array(const Sint32 *vals, const unsigned long num); 00535 00542 virtual OFCondition putUint32Array(const Uint32 *vals, const unsigned long num); 00543 00550 virtual OFCondition putFloat32Array(const Float32 *vals, const unsigned long num); 00551 00558 virtual OFCondition putFloat64Array(const Float64 *vals, const unsigned long num); 00559 00577 virtual OFCondition getPartialValue(void *targetBuffer, 00578 const Uint32 offset, 00579 Uint32 numBytes, 00580 DcmFileCache *cache = NULL, 00581 E_ByteOrder byteOrder = gLocalByteOrder); 00582 00590 virtual OFCondition createUint8Array(const Uint32 numBytes, Uint8 *&bytes); 00591 00599 virtual OFCondition createUint16Array(const Uint32 numWords, Uint16 *&words); 00600 00612 virtual OFCondition createValueFromTempFile(DcmInputStreamFactory *factory, 00613 const Uint32 length, 00614 const E_ByteOrder byteOrder); 00615 00619 virtual void compact(); 00620 00628 virtual OFCondition getUncompressedFrameSize(DcmItem *dataset, 00629 Uint32 &frameSize) const; 00630 00658 virtual OFCondition getUncompressedFrame(DcmItem *dataset, 00659 Uint32 frameNo, 00660 Uint32 &startFragment, 00661 void *buffer, 00662 Uint32 bufSize, 00663 OFString &decompressedColorModel, 00664 DcmFileCache *cache = NULL); 00665 00674 virtual OFCondition getDecompressedColorModel(DcmItem *dataset, 00675 OFString &decompressedColorModel); 00676 00677 /* --- static helper functions --- */ 00678 00686 static int scanValue(const OFString &value, 00687 const OFString &vr, 00688 const size_t pos = 0, 00689 const size_t num = OFString_npos); 00690 00691 protected: 00692 00699 void *getValue(const E_ByteOrder newByteOrder = gLocalByteOrder); 00700 00711 OFCondition changeValue(const void *value, // new Value 00712 const Uint32 position, // position in value array 00713 const Uint32 num); // number of new value bytes 00714 00720 OFCondition putValue(const void *value, // new value 00721 const Uint32 length); // number of new value bytes 00722 00727 OFCondition createEmptyValue(const Uint32 length); // number of new value bytes 00728 00738 OFCondition loadValue(DcmInputStream *inStream = NULL); 00739 00744 virtual void postLoadValue(); 00745 00750 virtual Uint8 *newValueField(); 00751 00756 void swapValueField(size_t valueWidth); 00757 00763 virtual void writeXMLStartTag(STD_NAMESPACE ostream &out, 00764 const size_t flags, 00765 const char *attrText = NULL); 00766 00771 virtual void writeXMLEndTag(STD_NAMESPACE ostream &out, 00772 const size_t flags); 00773 00777 E_ByteOrder getByteOrder() const { return fByteOrder; } 00778 00782 void setByteOrder(E_ByteOrder val) { fByteOrder = val; } 00783 00784 /* --- static helper functions --- */ 00785 00794 static OFCondition checkVM(const unsigned long vmNum, 00795 const OFString &vmStr); 00796 00797 private: 00798 00800 E_ByteOrder fByteOrder; 00801 00803 DcmInputStreamFactory *fLoadValue; 00804 00806 Uint8 *fValue; 00807 }; 00808 00809 00810 #endif // DCELEM_H 00811 00812 00813 /* 00814 ** CVS/RCS Log: 00815 ** $Log: dcelem.h,v $ 00816 ** Revision 1.49 2010-11-05 09:34:11 joergr 00817 ** Added support for checking the value multiplicity "9" (see Supplement 131). 00818 ** 00819 ** Revision 1.48 2010-10-14 13:15:40 joergr 00820 ** Updated copyright header. Added reference to COPYRIGHT file. 00821 ** 00822 ** Revision 1.47 2010-04-23 15:28:17 joergr 00823 ** Specify an appropriate default value for the "vm" parameter of checkValue(). 00824 ** 00825 ** Revision 1.46 2010-04-23 14:28:00 joergr 00826 ** Added new method to all VR classes which checks whether the stored value 00827 ** conforms to the VR definition and to the specified VM. 00828 ** 00829 ** Revision 1.45 2010-04-22 09:01:18 joergr 00830 ** Added support for further VM values ("1-8", "1-99", "16", "32") to be checked. 00831 ** 00832 ** Revision 1.44 2010-03-01 09:08:44 uli 00833 ** Removed some unnecessary include directives in the headers. 00834 ** 00835 ** Revision 1.43 2009-11-17 16:36:51 joergr 00836 ** Added new method that allows for determining the color model of the 00837 ** decompressed image. 00838 ** 00839 ** Revision 1.42 2009-08-03 09:05:29 joergr 00840 ** Added methods that check whether a given string value conforms to the VR and 00841 ** VM definitions of the DICOM standards. 00842 ** 00843 ** Revision 1.41 2009-05-11 16:05:45 meichel 00844 ** Minor fix in DcmElement::getUncompressedFrameSize for the rare case that 00845 ** BitsAllocated is not 8 or 16. Also the method now returns the true frame 00846 ** size without any pad byte. 00847 ** 00848 ** Revision 1.40 2009-02-04 17:52:17 joergr 00849 ** Fixes various type mismatches reported by MSVC introduced with OFFile class. 00850 ** 00851 ** Revision 1.39 2008-07-17 11:19:48 onken 00852 ** Updated copyFrom() documentation. 00853 ** 00854 ** Revision 1.38 2008-07-17 10:30:23 onken 00855 ** Implemented copyFrom() method for complete DcmObject class hierarchy, which 00856 ** permits setting an instance's value from an existing object. Implemented 00857 ** assignment operator where necessary. 00858 ** 00859 ** Revision 1.37 2008-06-23 12:09:13 joergr 00860 ** Fixed inconsistencies in Doxygen API documentation. 00861 ** 00862 ** Revision 1.36 2008-05-29 10:43:21 meichel 00863 ** Implemented new method createValueFromTempFile that allows the content of 00864 ** a temporary file to be set as the new value of a DICOM element. 00865 ** Also added a new method compact() that removes the value field if the 00866 ** value field can still be reconstructed from file. For large attribute 00867 ** value the file reference is now kept in memory even when the value has 00868 ** been loaded once. Finally, added new helper method getUncompressedFrameSize 00869 ** that computes the size of an uncompressed frame for a given dataset. 00870 ** 00871 ** Revision 1.35 2007/11/29 14:30:19 meichel 00872 ** Write methods now handle large raw data elements (such as pixel data) 00873 ** without loading everything into memory. This allows very large images to 00874 ** be sent over a network connection, or to be copied without ever being 00875 ** fully in memory. 00876 ** 00877 ** Revision 1.34 2007/07/11 08:50:23 meichel 00878 ** Initial release of new method DcmElement::getPartialValue which gives access 00879 ** to partial attribute values without loading the complete attribute value 00880 ** into memory, if kept in file. 00881 ** 00882 ** Revision 1.33 2007/06/29 14:17:49 meichel 00883 ** Code clean-up: Most member variables in module dcmdata are now private, 00884 ** not protected anymore. 00885 ** 00886 ** Revision 1.32 2007/06/07 09:01:15 joergr 00887 ** Added createUint8Array() and createUint16Array() methods. 00888 ** 00889 ** Revision 1.31 2006/10/13 10:12:02 joergr 00890 ** Fixed wrong formatting. 00891 ** 00892 ** Revision 1.30 2006/08/15 15:49:56 meichel 00893 ** Updated all code in module dcmdata to correctly compile when 00894 ** all standard C++ classes remain in namespace std. 00895 ** 00896 ** Revision 1.29 2005/12/08 16:28:11 meichel 00897 ** Changed include path schema for all DCMTK header files 00898 ** 00899 ** Revision 1.28 2004/07/01 12:28:25 meichel 00900 ** Introduced virtual clone method for DcmObject and derived classes. 00901 ** 00902 ** Revision 1.27 2003/07/04 13:25:35 meichel 00903 ** Replaced forward declarations for OFString with explicit includes, 00904 ** needed when compiling with HAVE_STD_STRING 00905 ** 00906 ** Revision 1.26 2002/12/09 09:31:14 wilkens 00907 ** Modified/Added doc++ documentation. 00908 ** 00909 ** Revision 1.25 2002/12/06 12:49:09 joergr 00910 ** Enhanced "print()" function by re-working the implementation and replacing 00911 ** the boolean "showFullData" parameter by a more general integer flag. 00912 ** Added doc++ documentation. 00913 ** Made source code formatting more consistent with other modules/files. 00914 ** 00915 ** Revision 1.24 2002/08/27 16:55:31 meichel 00916 ** Initial release of new DICOM I/O stream classes that add support for stream 00917 ** compression (deflated little endian explicit VR transfer syntax) 00918 ** 00919 ** Revision 1.23 2002/04/25 10:06:09 joergr 00920 ** Added/modified getOFStringArray() implementation. 00921 ** Added support for XML output of DICOM objects. 00922 ** 00923 ** Revision 1.22 2001/09/25 17:19:25 meichel 00924 ** Adapted dcmdata to class OFCondition 00925 ** 00926 ** Revision 1.21 2001/06/01 15:48:39 meichel 00927 ** Updated copyright header 00928 ** 00929 ** Revision 1.20 2001/05/10 12:50:21 meichel 00930 ** Added protected createEmptyValue() method in class DcmElement. 00931 ** 00932 ** Revision 1.19 2000/11/07 16:56:06 meichel 00933 ** Initial release of dcmsign module for DICOM Digital Signatures 00934 ** 00935 ** Revision 1.18 2000/03/08 16:26:14 meichel 00936 ** Updated copyright header. 00937 ** 00938 ** Revision 1.17 2000/02/02 14:31:16 joergr 00939 ** Replaced 'delete' statements by 'delete[]' for objects created with 'new[]'. 00940 ** 00941 ** Revision 1.16 1999/03/31 09:24:37 meichel 00942 ** Updated copyright header in module dcmdata 00943 ** 00944 ** Revision 1.15 1998/11/12 16:47:38 meichel 00945 ** Implemented operator= for all classes derived from DcmObject. 00946 ** 00947 ** Revision 1.14 1998/07/15 15:48:47 joergr 00948 ** Removed several compiler warnings reported by gcc 2.8.1 with 00949 ** additional options, e.g. missing copy constructors and assignment 00950 ** operators, initialization of member variables in the body of a 00951 ** constructor instead of the member initialization list, hiding of 00952 ** methods by use of identical names, uninitialized member variables, 00953 ** missing const declaration of char pointers. Replaced tabs by spaces. 00954 ** 00955 ** Revision 1.13 1997/09/11 15:13:10 hewett 00956 ** Modified getOFString method arguments by removing a default value 00957 ** for the pos argument. By requiring the pos argument to be provided 00958 ** ensures that callers realise getOFString only gets one component of 00959 ** a multi-valued string. 00960 ** 00961 ** Revision 1.12 1997/08/29 08:32:38 andreas 00962 ** - Added methods getOFString and getOFStringArray for all 00963 ** string VRs. These methods are able to normalise the value, i. e. 00964 ** to remove leading and trailing spaces. This will be done only if 00965 ** it is described in the standard that these spaces are not relevant. 00966 ** These methods do not test the strings for conformance, this means 00967 ** especially that they do not delete spaces where they are not allowed! 00968 ** getOFStringArray returns the string with all its parts separated by \ 00969 ** and getOFString returns only one value of the string. 00970 ** CAUTION: Currently getString returns a string with trailing 00971 ** spaces removed (if dcmEnableAutomaticInputDataCorrection == OFTrue) and 00972 ** truncates the original string (since it is not copied!). If you rely on this 00973 ** behaviour please change your application now. 00974 ** Future changes will ensure that getString returns the original 00975 ** string from the DICOM object (NULL terminated) inclusive padding. 00976 ** Currently, if you call getOF... before calling getString without 00977 ** normalisation, you can get the original string read from the DICOM object. 00978 ** 00979 ** Revision 1.11 1997/07/31 06:57:59 andreas 00980 ** new protected method swapValueField for DcmElement 00981 ** 00982 ** Revision 1.10 1997/07/21 07:57:53 andreas 00983 ** - New method DcmElement::detachValueField to give control over the 00984 ** value field to the calling part (see dcelem.h) 00985 ** - Replace all boolean types (BOOLEAN, CTNBOOLEAN, DICOM_BOOL, BOOL) 00986 ** with one unique boolean type OFBool. 00987 ** 00988 ** Revision 1.9 1997/05/27 13:48:26 andreas 00989 ** - Add method canWriteXfer to class DcmObject and all derived classes. 00990 ** This method checks whether it is possible to convert the original 00991 ** transfer syntax to an new transfer syntax. The check is used in the 00992 ** dcmconv utility to prohibit the change of a compressed transfer 00993 ** syntax to a uncompressed. 00994 ** 00995 ** Revision 1.8 1997/05/16 08:23:46 andreas 00996 ** - Revised handling of GroupLength elements and support of 00997 ** DataSetTrailingPadding elements. The enumeratio E_GrpLenEncoding 00998 ** got additional enumeration values (for a description see dctypes.h). 00999 ** addGroupLength and removeGroupLength methods are replaced by 01000 ** computeGroupLengthAndPadding. To support Padding, the parameters of 01001 ** element and sequence write functions changed. 01002 ** - Added a new method calcElementLength to calculate the length of an 01003 ** element, item or sequence. For elements it returns the length of 01004 ** tag, length field, vr field, and value length, for item and 01005 ** sequences it returns the length of the whole item. sequence including 01006 ** the Delimitation tag (if appropriate). It can never return 01007 ** UndefinedLength. 01008 ** 01009 ** Revision 1.7 1997/04/18 08:13:28 andreas 01010 ** - The put/get-methods for all VRs did not conform to the C++-Standard 01011 ** draft. Some Compilers (e.g. SUN-C++ Compiler, Metroworks 01012 ** CodeWarrier, etc.) create many warnings concerning the hiding of 01013 ** overloaded get methods in all derived classes of DcmElement. 01014 ** So the interface of all value representation classes in the 01015 ** library are changed rapidly, e.g. 01016 ** OFCondition get(Uint16 & value, const unsigned long pos); 01017 ** becomes 01018 ** OFCondition getUint16(Uint16 & value, const unsigned long pos); 01019 ** All (retired) "returntype get(...)" methods are deleted. 01020 ** For more information see dcmdata/include/dcelem.h 01021 ** 01022 ** Revision 1.6 1996/07/17 12:38:58 andreas 01023 ** new nextObject to iterate a DicomDataset, DicomFileFormat, Item, ... 01024 ** 01025 ** Revision 1.5 1996/04/16 16:01:36 andreas 01026 ** - put methods for AttributeTag with DcmTagKey Parameter 01027 ** - better support for NULL values 01028 ** 01029 ** Revision 1.4 1996/03/12 15:31:56 hewett 01030 ** The base virtual get & put functions now support char*. 01031 ** 01032 ** Revision 1.3 1996/01/05 13:22:55 andreas 01033 ** - changed to support new streaming facilities 01034 ** - more cleanups 01035 ** - merged read / write methods for block and file transfer 01036 ** 01037 */