OFFIS DCMTK  Version 3.6.0
dcelem.h
1 /*
2  *
3  * Copyright (C) 1994-2010, OFFIS e.V.
4  * All rights reserved. See COPYRIGHT file for details.
5  *
6  * This software and supporting documentation were developed by
7  *
8  * OFFIS e.V.
9  * R&D Division Health
10  * Escherweg 2
11  * D-26121 Oldenburg, Germany
12  *
13  *
14  * Module: dcmdata
15  *
16  * Author: Gerd Ehlers, Andreas Barth
17  *
18  * Purpose: Interface of class DcmElement
19  *
20  * Last Update: $Author: joergr $
21  * Update Date: $Date: 2010-11-05 09:34:11 $
22  * CVS/RCS Revision: $Revision: 1.49 $
23  * Status: $State: Exp $
24  *
25  * CVS/RCS Log at end of file
26  *
27  */
28 
29 
30 #ifndef DCELEM_H
31 #define DCELEM_H
32 
33 #include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */
34 
35 #include "dcmtk/dcmdata/dcobject.h"
36 #include "dcmtk/ofstd/ofstring.h"
37 
38 // forward declarations
40 class DcmFileCache;
41 class DcmItem;
42 
46  : public DcmObject
47 {
48 
49  public:
50 
56  DcmElement(const DcmTag &tag,
57  const Uint32 len = 0);
58 
62  DcmElement(const DcmElement &old);
63 
66  virtual ~DcmElement();
67 
72  DcmElement &operator=(const DcmElement &obj);
73 
86  virtual OFCondition copyFrom(const DcmObject& rhs);
87 
98  virtual Uint32 calcElementLength(const E_TransferSyntax xfer,
99  const E_EncodingType enctype);
100 
108  virtual Uint32 getLength(const E_TransferSyntax /*xfer*/ = EXS_LittleEndianImplicit,
109  const E_EncodingType /*enctype*/ = EET_UndefinedLength)
110  {
111  return getLengthField();
112  }
113 
120  virtual OFBool isLeaf() const { return OFTrue; }
121 
125  inline OFBool valueLoaded() const { return fValue != NULL || getLengthField() == 0; }
126 
130  virtual void transferInit();
131 
137  virtual OFBool canWriteXfer(const E_TransferSyntax newXfer,
138  const E_TransferSyntax oldXfer);
139 
155  virtual OFCondition read(DcmInputStream &inStream,
156  const E_TransferSyntax ixfer,
157  const E_GrpLenEncoding glenc = EGL_noChange,
158  const Uint32 maxReadLength = DCM_MaxReadLength);
159 
182  virtual OFCondition write(DcmOutputStream &outStream,
183  const E_TransferSyntax oxfer,
184  const E_EncodingType enctype,
185  DcmWriteCache *wcache);
186 
192  virtual OFCondition writeXML(STD_NAMESPACE ostream &out,
193  const size_t flags = 0);
194 
203  const E_TransferSyntax oxfer,
204  const E_EncodingType enctype,
205  DcmWriteCache *wcache);
206 
210  virtual OFCondition clear();
211 
220  virtual OFCondition checkValue(const OFString &vm = "1-n",
221  const OFBool oldFormat = OFFalse);
222 
231 
232  // GET operations
233 
240  virtual OFCondition getUint8(Uint8 &val, const unsigned long pos = 0);
241 
248  virtual OFCondition getSint16(Sint16 &val, const unsigned long pos = 0);
249 
256  virtual OFCondition getUint16(Uint16 &val, const unsigned long pos = 0);
257 
264  virtual OFCondition getSint32(Sint32 &val, const unsigned long pos = 0);
265 
272  virtual OFCondition getUint32(Uint32 &val, const unsigned long pos = 0);
273 
280  virtual OFCondition getFloat32(Float32 &val, const unsigned long pos = 0);
281 
288  virtual OFCondition getFloat64(Float64 &val, const unsigned long pos = 0);
289 
296  virtual OFCondition getTagVal(DcmTagKey &val, const unsigned long pos = 0);
297 
305  virtual OFCondition getOFString(OFString &str,
306  const unsigned long pos,
307  OFBool normalize = OFTrue);
308 
318  virtual OFCondition getOFStringArray(OFString &value,
319  OFBool normalize = OFTrue);
320 
329  virtual OFCondition getString(char *&val); // for strings
330 
339  virtual OFCondition getUint8Array(Uint8 *&val); // for bytes
340 
349  virtual OFCondition getSint16Array(Sint16 *&val);
350 
359  virtual OFCondition getUint16Array(Uint16 *&val);
360 
369  virtual OFCondition getSint32Array(Sint32 *&val);
370 
379  virtual OFCondition getUint32Array(Uint32 *&val);
380 
389  virtual OFCondition getFloat32Array(Float32 *&val);
390 
399  virtual OFCondition getFloat64Array(Float64 *&val);
400 
409  OFCondition detachValueField(OFBool copy = OFFalse);
410 
411  // PUT operations
412 
418  virtual OFCondition putOFStringArray(const OFString &stringValue);
419 
425  virtual OFCondition putString(const char *val);
426 
436  virtual OFCondition putSint16(const Sint16 val, const unsigned long pos = 0);
437 
447  virtual OFCondition putUint16(const Uint16 val, const unsigned long pos = 0);
448 
458  virtual OFCondition putSint32(const Sint32 val, const unsigned long pos = 0);
459 
469  virtual OFCondition putUint32(const Uint32 val, const unsigned long pos = 0);
470 
480  virtual OFCondition putFloat32(const Float32 val, const unsigned long pos = 0);
481 
491  virtual OFCondition putFloat64(const Float64 val, const unsigned long pos = 0);
492 
502  virtual OFCondition putTagVal(const DcmTagKey &attrTag, const unsigned long pos = 0);
503 
510  virtual OFCondition putUint8Array(const Uint8 *vals, const unsigned long num);
511 
518  virtual OFCondition putSint16Array(const Sint16 *vals, const unsigned long num);
519 
526  virtual OFCondition putUint16Array(const Uint16 *vals, const unsigned long num);
527 
534  virtual OFCondition putSint32Array(const Sint32 *vals, const unsigned long num);
535 
542  virtual OFCondition putUint32Array(const Uint32 *vals, const unsigned long num);
543 
550  virtual OFCondition putFloat32Array(const Float32 *vals, const unsigned long num);
551 
558  virtual OFCondition putFloat64Array(const Float64 *vals, const unsigned long num);
559 
577  virtual OFCondition getPartialValue(void *targetBuffer,
578  const Uint32 offset,
579  Uint32 numBytes,
580  DcmFileCache *cache = NULL,
581  E_ByteOrder byteOrder = gLocalByteOrder);
582 
590  virtual OFCondition createUint8Array(const Uint32 numBytes, Uint8 *&bytes);
591 
599  virtual OFCondition createUint16Array(const Uint32 numWords, Uint16 *&words);
600 
613  const Uint32 length,
614  const E_ByteOrder byteOrder);
615 
619  virtual void compact();
620 
629  Uint32 &frameSize) const;
630 
658  virtual OFCondition getUncompressedFrame(DcmItem *dataset,
659  Uint32 frameNo,
660  Uint32 &startFragment,
661  void *buffer,
662  Uint32 bufSize,
663  OFString &decompressedColorModel,
664  DcmFileCache *cache = NULL);
665 
675  OFString &decompressedColorModel);
676 
677  /* --- static helper functions --- */
678 
686  static int scanValue(const OFString &value,
687  const OFString &vr,
688  const size_t pos = 0,
689  const size_t num = OFString_npos);
690 
691  protected:
692 
699  void *getValue(const E_ByteOrder newByteOrder = gLocalByteOrder);
700 
711  OFCondition changeValue(const void *value, // new Value
712  const Uint32 position, // position in value array
713  const Uint32 num); // number of new value bytes
714 
720  OFCondition putValue(const void *value, // new value
721  const Uint32 length); // number of new value bytes
722 
727  OFCondition createEmptyValue(const Uint32 length); // number of new value bytes
728 
738  OFCondition loadValue(DcmInputStream *inStream = NULL);
739 
744  virtual void postLoadValue();
745 
750  virtual Uint8 *newValueField();
751 
756  void swapValueField(size_t valueWidth);
757 
763  virtual void writeXMLStartTag(STD_NAMESPACE ostream &out,
764  const size_t flags,
765  const char *attrText = NULL);
766 
771  virtual void writeXMLEndTag(STD_NAMESPACE ostream &out,
772  const size_t flags);
773 
777  E_ByteOrder getByteOrder() const { return fByteOrder; }
778 
782  void setByteOrder(E_ByteOrder val) { fByteOrder = val; }
783 
784  /* --- static helper functions --- */
785 
794  static OFCondition checkVM(const unsigned long vmNum,
795  const OFString &vmStr);
796 
797  private:
798 
800  E_ByteOrder fByteOrder;
801 
804 
806  Uint8 *fValue;
807 };
808 
809 
810 #endif // DCELEM_H
811 
812 
813 /*
814 ** CVS/RCS Log:
815 ** $Log: dcelem.h,v $
816 ** Revision 1.49 2010-11-05 09:34:11 joergr
817 ** Added support for checking the value multiplicity "9" (see Supplement 131).
818 **
819 ** Revision 1.48 2010-10-14 13:15:40 joergr
820 ** Updated copyright header. Added reference to COPYRIGHT file.
821 **
822 ** Revision 1.47 2010-04-23 15:28:17 joergr
823 ** Specify an appropriate default value for the "vm" parameter of checkValue().
824 **
825 ** Revision 1.46 2010-04-23 14:28:00 joergr
826 ** Added new method to all VR classes which checks whether the stored value
827 ** conforms to the VR definition and to the specified VM.
828 **
829 ** Revision 1.45 2010-04-22 09:01:18 joergr
830 ** Added support for further VM values ("1-8", "1-99", "16", "32") to be checked.
831 **
832 ** Revision 1.44 2010-03-01 09:08:44 uli
833 ** Removed some unnecessary include directives in the headers.
834 **
835 ** Revision 1.43 2009-11-17 16:36:51 joergr
836 ** Added new method that allows for determining the color model of the
837 ** decompressed image.
838 **
839 ** Revision 1.42 2009-08-03 09:05:29 joergr
840 ** Added methods that check whether a given string value conforms to the VR and
841 ** VM definitions of the DICOM standards.
842 **
843 ** Revision 1.41 2009-05-11 16:05:45 meichel
844 ** Minor fix in DcmElement::getUncompressedFrameSize for the rare case that
845 ** BitsAllocated is not 8 or 16. Also the method now returns the true frame
846 ** size without any pad byte.
847 **
848 ** Revision 1.40 2009-02-04 17:52:17 joergr
849 ** Fixes various type mismatches reported by MSVC introduced with OFFile class.
850 **
851 ** Revision 1.39 2008-07-17 11:19:48 onken
852 ** Updated copyFrom() documentation.
853 **
854 ** Revision 1.38 2008-07-17 10:30:23 onken
855 ** Implemented copyFrom() method for complete DcmObject class hierarchy, which
856 ** permits setting an instance's value from an existing object. Implemented
857 ** assignment operator where necessary.
858 **
859 ** Revision 1.37 2008-06-23 12:09:13 joergr
860 ** Fixed inconsistencies in Doxygen API documentation.
861 **
862 ** Revision 1.36 2008-05-29 10:43:21 meichel
863 ** Implemented new method createValueFromTempFile that allows the content of
864 ** a temporary file to be set as the new value of a DICOM element.
865 ** Also added a new method compact() that removes the value field if the
866 ** value field can still be reconstructed from file. For large attribute
867 ** value the file reference is now kept in memory even when the value has
868 ** been loaded once. Finally, added new helper method getUncompressedFrameSize
869 ** that computes the size of an uncompressed frame for a given dataset.
870 **
871 ** Revision 1.35 2007/11/29 14:30:19 meichel
872 ** Write methods now handle large raw data elements (such as pixel data)
873 ** without loading everything into memory. This allows very large images to
874 ** be sent over a network connection, or to be copied without ever being
875 ** fully in memory.
876 **
877 ** Revision 1.34 2007/07/11 08:50:23 meichel
878 ** Initial release of new method DcmElement::getPartialValue which gives access
879 ** to partial attribute values without loading the complete attribute value
880 ** into memory, if kept in file.
881 **
882 ** Revision 1.33 2007/06/29 14:17:49 meichel
883 ** Code clean-up: Most member variables in module dcmdata are now private,
884 ** not protected anymore.
885 **
886 ** Revision 1.32 2007/06/07 09:01:15 joergr
887 ** Added createUint8Array() and createUint16Array() methods.
888 **
889 ** Revision 1.31 2006/10/13 10:12:02 joergr
890 ** Fixed wrong formatting.
891 **
892 ** Revision 1.30 2006/08/15 15:49:56 meichel
893 ** Updated all code in module dcmdata to correctly compile when
894 ** all standard C++ classes remain in namespace std.
895 **
896 ** Revision 1.29 2005/12/08 16:28:11 meichel
897 ** Changed include path schema for all DCMTK header files
898 **
899 ** Revision 1.28 2004/07/01 12:28:25 meichel
900 ** Introduced virtual clone method for DcmObject and derived classes.
901 **
902 ** Revision 1.27 2003/07/04 13:25:35 meichel
903 ** Replaced forward declarations for OFString with explicit includes,
904 ** needed when compiling with HAVE_STD_STRING
905 **
906 ** Revision 1.26 2002/12/09 09:31:14 wilkens
907 ** Modified/Added doc++ documentation.
908 **
909 ** Revision 1.25 2002/12/06 12:49:09 joergr
910 ** Enhanced "print()" function by re-working the implementation and replacing
911 ** the boolean "showFullData" parameter by a more general integer flag.
912 ** Added doc++ documentation.
913 ** Made source code formatting more consistent with other modules/files.
914 **
915 ** Revision 1.24 2002/08/27 16:55:31 meichel
916 ** Initial release of new DICOM I/O stream classes that add support for stream
917 ** compression (deflated little endian explicit VR transfer syntax)
918 **
919 ** Revision 1.23 2002/04/25 10:06:09 joergr
920 ** Added/modified getOFStringArray() implementation.
921 ** Added support for XML output of DICOM objects.
922 **
923 ** Revision 1.22 2001/09/25 17:19:25 meichel
924 ** Adapted dcmdata to class OFCondition
925 **
926 ** Revision 1.21 2001/06/01 15:48:39 meichel
927 ** Updated copyright header
928 **
929 ** Revision 1.20 2001/05/10 12:50:21 meichel
930 ** Added protected createEmptyValue() method in class DcmElement.
931 **
932 ** Revision 1.19 2000/11/07 16:56:06 meichel
933 ** Initial release of dcmsign module for DICOM Digital Signatures
934 **
935 ** Revision 1.18 2000/03/08 16:26:14 meichel
936 ** Updated copyright header.
937 **
938 ** Revision 1.17 2000/02/02 14:31:16 joergr
939 ** Replaced 'delete' statements by 'delete[]' for objects created with 'new[]'.
940 **
941 ** Revision 1.16 1999/03/31 09:24:37 meichel
942 ** Updated copyright header in module dcmdata
943 **
944 ** Revision 1.15 1998/11/12 16:47:38 meichel
945 ** Implemented operator= for all classes derived from DcmObject.
946 **
947 ** Revision 1.14 1998/07/15 15:48:47 joergr
948 ** Removed several compiler warnings reported by gcc 2.8.1 with
949 ** additional options, e.g. missing copy constructors and assignment
950 ** operators, initialization of member variables in the body of a
951 ** constructor instead of the member initialization list, hiding of
952 ** methods by use of identical names, uninitialized member variables,
953 ** missing const declaration of char pointers. Replaced tabs by spaces.
954 **
955 ** Revision 1.13 1997/09/11 15:13:10 hewett
956 ** Modified getOFString method arguments by removing a default value
957 ** for the pos argument. By requiring the pos argument to be provided
958 ** ensures that callers realise getOFString only gets one component of
959 ** a multi-valued string.
960 **
961 ** Revision 1.12 1997/08/29 08:32:38 andreas
962 ** - Added methods getOFString and getOFStringArray for all
963 ** string VRs. These methods are able to normalise the value, i. e.
964 ** to remove leading and trailing spaces. This will be done only if
965 ** it is described in the standard that these spaces are not relevant.
966 ** These methods do not test the strings for conformance, this means
967 ** especially that they do not delete spaces where they are not allowed!
968 ** getOFStringArray returns the string with all its parts separated by \
969 ** and getOFString returns only one value of the string.
970 ** CAUTION: Currently getString returns a string with trailing
971 ** spaces removed (if dcmEnableAutomaticInputDataCorrection == OFTrue) and
972 ** truncates the original string (since it is not copied!). If you rely on this
973 ** behaviour please change your application now.
974 ** Future changes will ensure that getString returns the original
975 ** string from the DICOM object (NULL terminated) inclusive padding.
976 ** Currently, if you call getOF... before calling getString without
977 ** normalisation, you can get the original string read from the DICOM object.
978 **
979 ** Revision 1.11 1997/07/31 06:57:59 andreas
980 ** new protected method swapValueField for DcmElement
981 **
982 ** Revision 1.10 1997/07/21 07:57:53 andreas
983 ** - New method DcmElement::detachValueField to give control over the
984 ** value field to the calling part (see dcelem.h)
985 ** - Replace all boolean types (BOOLEAN, CTNBOOLEAN, DICOM_BOOL, BOOL)
986 ** with one unique boolean type OFBool.
987 **
988 ** Revision 1.9 1997/05/27 13:48:26 andreas
989 ** - Add method canWriteXfer to class DcmObject and all derived classes.
990 ** This method checks whether it is possible to convert the original
991 ** transfer syntax to an new transfer syntax. The check is used in the
992 ** dcmconv utility to prohibit the change of a compressed transfer
993 ** syntax to a uncompressed.
994 **
995 ** Revision 1.8 1997/05/16 08:23:46 andreas
996 ** - Revised handling of GroupLength elements and support of
997 ** DataSetTrailingPadding elements. The enumeratio E_GrpLenEncoding
998 ** got additional enumeration values (for a description see dctypes.h).
999 ** addGroupLength and removeGroupLength methods are replaced by
1000 ** computeGroupLengthAndPadding. To support Padding, the parameters of
1001 ** element and sequence write functions changed.
1002 ** - Added a new method calcElementLength to calculate the length of an
1003 ** element, item or sequence. For elements it returns the length of
1004 ** tag, length field, vr field, and value length, for item and
1005 ** sequences it returns the length of the whole item. sequence including
1006 ** the Delimitation tag (if appropriate). It can never return
1007 ** UndefinedLength.
1008 **
1009 ** Revision 1.7 1997/04/18 08:13:28 andreas
1010 ** - The put/get-methods for all VRs did not conform to the C++-Standard
1011 ** draft. Some Compilers (e.g. SUN-C++ Compiler, Metroworks
1012 ** CodeWarrier, etc.) create many warnings concerning the hiding of
1013 ** overloaded get methods in all derived classes of DcmElement.
1014 ** So the interface of all value representation classes in the
1015 ** library are changed rapidly, e.g.
1016 ** OFCondition get(Uint16 & value, const unsigned long pos);
1017 ** becomes
1018 ** OFCondition getUint16(Uint16 & value, const unsigned long pos);
1019 ** All (retired) "returntype get(...)" methods are deleted.
1020 ** For more information see dcmdata/include/dcelem.h
1021 **
1022 ** Revision 1.6 1996/07/17 12:38:58 andreas
1023 ** new nextObject to iterate a DicomDataset, DicomFileFormat, Item, ...
1024 **
1025 ** Revision 1.5 1996/04/16 16:01:36 andreas
1026 ** - put methods for AttributeTag with DcmTagKey Parameter
1027 ** - better support for NULL values
1028 **
1029 ** Revision 1.4 1996/03/12 15:31:56 hewett
1030 ** The base virtual get & put functions now support char*.
1031 **
1032 ** Revision 1.3 1996/01/05 13:22:55 andreas
1033 ** - changed to support new streaming facilities
1034 ** - more cleanups
1035 ** - merged read / write methods for block and file transfer
1036 **
1037 */


Generated on Thu Dec 20 2012 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.8.2