dcmdata/include/dcmtk/dcmdata/dcelem.h

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 */


Generated on 6 Jan 2011 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.5.1