OFFIS DCMTK  Version 3.6.0
dcobject.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
17  *
18  * Purpose:
19  * This file contains the interface to routines which provide
20  * DICOM object encoding/decoding, search and lookup facilities.
21  *
22  * Last Update: $Author: joergr $
23  * Update Date: $Date: 2010-10-29 10:57:17 $
24  * CVS/RCS Revision: $Revision: 1.70 $
25  * Status: $State: Exp $
26  *
27  * CVS/RCS Log at end of file
28  *
29  */
30 
31 
32 #ifndef DCOBJECT_H
33 #define DCOBJECT_H
34 
35 #include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */
36 
37 #include "dcmtk/ofstd/ofglobal.h"
38 #include "dcmtk/dcmdata/dcerror.h"
39 #include "dcmtk/dcmdata/dcxfer.h"
40 #include "dcmtk/dcmdata/dctag.h"
41 #include "dcmtk/dcmdata/dcstack.h"
42 
43 
44 // forward declarations
45 class DcmOutputStream;
46 class DcmInputStream;
47 class DcmWriteCache;
48 
49 // Undefined Length Identifier now defined in dctypes.h
50 
51 // Maxinum number of read bytes for a Value Element
52 const Uint32 DCM_MaxReadLength = 4096;
53 
54 // Maximum length of tag and length in a DICOM element
55 const Uint32 DCM_TagInfoLength = 12;
56 
57 // Optimum line length if not all data printed
58 const Uint32 DCM_OptPrintLineLength = 70;
59 
60 // Optimum value length if not all data printed
61 const Uint32 DCM_OptPrintValueLength = 40;
62 
63 // Optimum attribute name length (for tree output)
64 const Uint32 DCM_OptPrintAttributeNameLength = 35;
65 
70 extern OFGlobal<OFBool> dcmEnableAutomaticInputDataCorrection; /* default OFTrue */
71 
81 extern OFGlobal<OFBool> dcmAcceptOddAttributeLength; /* default OFTrue */
82 
95 extern OFGlobal<OFBool> dcmEnableCP246Support; /* default OFTrue */
96 
105 extern OFGlobal<OFBool> dcmEnableOldSignatureFormat; /* default OFFalse */
106 
112 extern OFGlobal<OFBool> dcmAutoDetectDatasetXfer; /* default OFFalse */
113 
119 extern OFGlobal<OFBool> dcmAcceptUnexpectedImplicitEncoding; /* default OFFalse */
120 
130 extern OFGlobal<OFBool> dcmReadImplPrivAttribMaxLengthAsSQ; /* default OFFalse */
131 
138 extern OFGlobal<OFBool> dcmIgnoreParsingErrors; /* default OFFalse */
139 
153 extern OFGlobal<DcmTagKey> dcmStopParsingAfterElement; /* default OFTrue */
154 
165 extern OFGlobal<OFBool> dcmWriteOversizedSeqsAndItemsUndefined; /* default OFTrue */
166 
172 extern OFGlobal<OFBool> dcmIgnoreFileMetaInformationGroupLength; /* default OFFalse */
173 
174 
180 {
181  public:
182 
188  DcmObject(const DcmTag &tag, const Uint32 len = 0);
189 
193  DcmObject(const DcmObject &obj);
194 
196  virtual ~DcmObject();
197 
201  virtual DcmObject *clone() const = 0;
202 
207  DcmObject &operator=(const DcmObject &obj);
208 
221  virtual OFCondition copyFrom(const DcmObject &rhs) = 0;
222 
229  virtual DcmEVR ident() const = 0;
230 
238  inline DcmEVR getVR() const { return Tag.getEVR(); }
239 
246  inline OFBool isaString() const { return Tag.getVR().isaString(); }
247 
254  virtual OFBool isLeaf() const = 0;
255 
263  virtual void print(STD_NAMESPACE ostream &out,
264  const size_t flags = 0,
265  const int level = 0,
266  const char *pixelFileName = NULL,
267  size_t *pixelCounter = NULL) = 0;
268 
272  inline E_TransferState transferState() const { return fTransferState; }
273 
277  virtual void transferInit(void);
278 
282  virtual void transferEnd(void);
283 
287  inline Uint16 getGTag() const { return Tag.getGTag(); }
288 
292  inline Uint16 getETag() const { return Tag.getETag(); }
293 
297  inline const DcmTag &getTag() const { return Tag; }
298 
303  inline void setGTag(Uint16 gtag) { Tag.setGroup(gtag); }
304 
312  virtual OFCondition setVR(DcmEVR /*vr*/) { return EC_IllegalCall; }
313 
317  virtual unsigned long getVM() = 0;
318 
329  virtual Uint32 calcElementLength(const E_TransferSyntax xfer,
330  const E_EncodingType enctype) = 0;
331 
339  virtual Uint32 getLength(const E_TransferSyntax xfer = EXS_LittleEndianImplicit,
340  const E_EncodingType enctype = EET_UndefinedLength) = 0;
341 
347  virtual OFBool canWriteXfer(const E_TransferSyntax newXfer,
348  const E_TransferSyntax oldXfer) = 0;
349 
359  virtual OFCondition read(DcmInputStream &inStream,
360  const E_TransferSyntax ixfer,
361  const E_GrpLenEncoding glenc = EGL_noChange,
362  const Uint32 maxReadLength = DCM_MaxReadLength) = 0;
363 
371  virtual OFCondition write(DcmOutputStream &outStream,
372  const E_TransferSyntax oxfer,
373  const E_EncodingType enctype,
374  DcmWriteCache *wcache) = 0;
375 
381  virtual OFCondition writeXML(STD_NAMESPACE ostream&out,
382  const size_t flags = 0);
383 
392  const E_TransferSyntax oxfer,
393  const E_EncodingType enctype,
394  DcmWriteCache *wcache) = 0;
395 
399  virtual OFBool isSignable() const;
400 
404  virtual OFBool containsUnknownVR() const;
405 
410  virtual OFBool containsExtendedCharacters(const OFBool checkAllStrings = OFFalse);
411 
415  virtual OFBool isAffectedBySpecificCharacterSet() const;
416 
421  virtual OFBool isEmpty(const OFBool normalize = OFTrue);
422 
426  virtual OFCondition clear() = 0;
427 
432  virtual OFCondition verify(const OFBool autocorrect = OFFalse) = 0;
433 
444  virtual DcmObject *nextInContainer(const DcmObject *obj);
445 
461  virtual OFCondition nextObject(DcmStack &stack,
462  const OFBool intoSub);
463 
485  virtual OFCondition search(const DcmTagKey &xtag,
486  DcmStack &resultStack,
487  E_SearchMode mode = ESM_fromHere,
488  OFBool searchIntoSub = OFTrue);
489 
497  virtual OFCondition loadAllDataIntoMemory() = 0;
498 
504  Uint32 getLengthField() const { return Length; }
505 
506  protected:
507 
514  void printNestingLevel(STD_NAMESPACE ostream &out,
515  const size_t flags,
516  const int level);
517 
526  void printInfoLineStart(STD_NAMESPACE ostream &out,
527  const size_t flags,
528  const int level,
529  DcmTag *tag = NULL);
530 
540  void printInfoLineEnd(STD_NAMESPACE ostream &out,
541  const size_t flags,
542  const unsigned long printedLength = 0xffffffff /*no padding*/,
543  DcmTag *tag = NULL);
544 
556  virtual void printInfoLine(STD_NAMESPACE ostream &out,
557  const size_t flags,
558  const int level = 0,
559  const char *info = NULL,
560  DcmTag *tag = NULL,
561  const OFBool isInfo = OFTrue);
562 
570  static OFCondition writeTag(DcmOutputStream &outStream,
571  const DcmTag &tag,
572  const E_TransferSyntax oxfer);
573 
580  virtual OFCondition writeTagAndLength(DcmOutputStream &outStream,
581  const E_TransferSyntax oxfer, // in
582  Uint32 &writtenBytes) const; // out
583 
590  virtual Uint32 getTagAndLengthSize(const E_TransferSyntax oxfer) const;
591 
596  const char *getTagName() { return Tag.getTagName(); }
597 
601  void setTagVR(DcmEVR vr) { Tag.setVR(vr); }
602 
606  E_TransferState getTransferState() const { return fTransferState; }
607 
611  void setTransferState(E_TransferState newState) { fTransferState = newState; }
612 
616  Uint32 getTransferredBytes() const { return fTransferredBytes; }
617 
621  void setTransferredBytes(Uint32 val) { fTransferredBytes = val; }
622 
626  void incTransferredBytes(Uint32 val) { fTransferredBytes += val; }
627 
631  void setLengthField(Uint32 val) { Length = val; }
632 
633 public:
637  {
638  private:
643 
644  public:
650  explicit PrintHelper(DcmObject &dcmobj, size_t flags = 0, int level = 0)
651  : dcmobj_(dcmobj), flags_(flags), level_(level)
652  {}
653 
654  DcmObject &dcmobj_;
655  const size_t flags_;
656  const int level_;
657  };
658 
659  /* member variables */
660 
661 protected:
662 
665 
666 private:
667 
670 
672  Uint32 Length;
673 
675  E_TransferState fTransferState;
676 
679 
680  }; // class DcmObject
681 
687 static inline STD_NAMESPACE ostream& operator<<(STD_NAMESPACE ostream &stream, DcmObject::PrintHelper obj)
688 {
689  obj.dcmobj_.print(stream, obj.flags_, obj.level_);
690  return stream;
691 }
692 
693 #endif // DCOBJECT_H
694 
695 
696 /*
697  * CVS/RCS Log:
698  * $Log: dcobject.h,v $
699  * Revision 1.70 2010-10-29 10:57:17 joergr
700  * Added support for colored output to the print() method.
701  *
702  * Revision 1.69 2010-10-14 13:15:41 joergr
703  * Updated copyright header. Added reference to COPYRIGHT file.
704  *
705  * Revision 1.68 2010-06-18 08:17:57 uli
706  * Added undefined assignment operator to PrintHelper to work around
707  * a warning with VC2008.
708  *
709  * Revision 1.67 2010-03-01 09:08:44 uli
710  * Removed some unnecessary include directives in the headers.
711  *
712  * Revision 1.66 2010-02-22 11:39:54 uli
713  * Remove some unneeded includes.
714  *
715  * Revision 1.65 2009-11-04 09:58:07 uli
716  * Switched to logging mechanism provided by the "new" oflog module
717  *
718  * Revision 1.64 2009-10-13 14:26:09 uli
719  * Added the DcmObject::PrintHelper helper class. This class can be used to
720  * print DcmObject instances with oflog's logging macros.
721  *
722  * Revision 1.63 2009-08-07 14:40:38 joergr
723  * Enhanced isEmpty() method by checking whether the data element value consists
724  * of non-significant characters only.
725  *
726  * Revision 1.62 2009-06-04 16:52:14 joergr
727  * Added new parsing flag that allows for ignoring the value of File Meta
728  * Information Group Length (0002,0000).
729  *
730  * Revision 1.61 2009-03-25 10:22:09 joergr
731  * Added new method isEmpty() to DICOM object, item and sequence class.
732  *
733  * Revision 1.60 2009-03-05 14:07:56 onken
734  * Fixed typo.
735  *
736  * Revision 1.59 2009-03-05 13:35:47 onken
737  * Added checks for sequence and item lengths which prevents overflow in length
738  * field, if total length of contained items (or sequences) exceeds
739  * 32-bit length field. Also introduced new flag (default: enabled)
740  * for writing in explicit length mode, which allows for automatically
741  * switching encoding of only that very sequence/item to undefined
742  * length coding (thus permitting to actually write the file).
743  *
744  * Revision 1.58 2009-02-11 13:16:32 onken
745  * Added global parser flag permitting to stop parsing after a specific
746  * element was parsed on dataset level (useful for removing garbage at
747  * end of file).
748  *
749  * Revision 1.57 2009-02-04 17:54:30 joergr
750  * Fixed various layout and formatting issues.
751  *
752  * Revision 1.56 2009-02-04 14:05:01 onken
753  * Introduced global flag that, if enabled, tells the parser to continue
754  * parsing if possible.
755  *
756  * Revision 1.55 2009-01-29 15:36:16 onken
757  * Added global parsing option that allows for reading private attributes in
758  * implicit encoding having a maximum length to be read as sequences instead
759  * of relying on the dictionary.
760  *
761  * Revision 1.54 2009-01-06 16:28:11 joergr
762  * Reworked print() output format for option PF_showTreeStructure.
763  *
764  * Revision 1.53 2009-01-05 15:32:23 joergr
765  * Added global flag that allows for reading incorrectly encoded DICOM datasets
766  * where particular data elements are encoded with a differing transfer syntax
767  * (Implicit VR Little endian instead of Explicit VR encoding as declared).
768  *
769  * Revision 1.52 2008-09-24 13:33:53 joergr
770  * Fixed typo in comment.
771  *
772  * Revision 1.51 2008-07-17 11:19:49 onken
773  * Updated copyFrom() documentation.
774  *
775  * Revision 1.50 2008-07-17 10:30:23 onken
776  * Implemented copyFrom() method for complete DcmObject class hierarchy, which
777  * permits setting an instance's value from an existing object. Implemented
778  * assignment operator where necessary.
779  *
780  * Revision 1.49 2008-04-17 14:48:39 meichel
781  * Method DcmObject::getLengthField now public, needed by dcmcheck
782  *
783  * Revision 1.48 2007/11/29 14:30:19 meichel
784  * Write methods now handle large raw data elements (such as pixel data)
785  * without loading everything into memory. This allows very large images to
786  * be sent over a network connection, or to be copied without ever being
787  * fully in memory.
788  *
789  * Revision 1.47 2007/06/29 14:17:49 meichel
790  * Code clean-up: Most member variables in module dcmdata are now private,
791  * not protected anymore.
792  *
793  * Revision 1.46 2007/02/19 15:04:34 meichel
794  * Removed searchErrors() methods that are not used anywhere and added
795  * error() methods only in the DcmObject subclasses where really used.
796  *
797  * Revision 1.45 2006/12/15 14:18:07 joergr
798  * Added new method that checks whether a DICOM object or element is affected
799  * by SpecificCharacterSet (0008,0005).
800  *
801  * Revision 1.44 2006/12/13 13:58:15 joergr
802  * Added new optional parameter "checkAllStrings" to method containsExtended
803  * Characters().
804  *
805  * Revision 1.43 2006/08/15 15:49:56 meichel
806  * Updated all code in module dcmdata to correctly compile when
807  * all standard C++ classes remain in namespace std.
808  *
809  * Revision 1.42 2006/05/11 08:54:23 joergr
810  * Moved checkForNonASCIICharacters() from application to library.
811  *
812  * Revision 1.41 2005/12/08 16:28:22 meichel
813  * Changed include path schema for all DCMTK header files
814  *
815  * Revision 1.40 2005/12/02 08:49:17 joergr
816  * Changed macro NO_XFER_DETECTION_FOR_DATASETS into a global option that can
817  * be enabled and disabled at runtime.
818  *
819  * Revision 1.39 2005/11/24 12:50:57 meichel
820  * Fixed bug in code that prepares a byte stream that is fed into the MAC
821  * algorithm when creating or verifying a digital signature. The previous
822  * implementation was non-conformant when signatures included compressed
823  * (encapsulated) pixel data because the item length was included in the byte
824  * stream, while it should not. The global variable dcmEnableOldSignatureFormat
825  * and a corresponding command line option in dcmsign allow to re-enable the old
826  * implementation.
827  *
828  * Revision 1.38 2005/05/10 15:27:14 meichel
829  * Added support for reading UN elements with undefined length according
830  * to CP 246. The global flag dcmEnableCP246Support allows to revert to the
831  * prior behaviour in which UN elements with undefined length were parsed
832  * like a normal explicit VR SQ element.
833  *
834  * Revision 1.37 2004/07/01 12:28:25 meichel
835  * Introduced virtual clone method for DcmObject and derived classes.
836  *
837  * Revision 1.36 2004/04/27 09:21:01 wilkens
838  * Fixed a bug in dcelem.cc which occurs when one is serializing a dataset
839  * (that contains an attribute whose length value is coded with 2 bytes) into
840  * a given buffer. Although the number of available bytes in the buffer was
841  * sufficient, the dataset->write(...) method would always return
842  * EC_StreamNotifyClient to indicate that there are not sufficient bytes
843  * available in the buffer. This code modification fixes the problem.
844  *
845  * Revision 1.35 2003/06/12 13:33:21 joergr
846  * Fixed inconsistent API documentation reported by Doxygen.
847  *
848  * Revision 1.34 2002/12/06 12:49:11 joergr
849  * Enhanced "print()" function by re-working the implementation and replacing
850  * the boolean "showFullData" parameter by a more general integer flag.
851  * Added doc++ documentation.
852  * Made source code formatting more consistent with other modules/files.
853  *
854  * Revision 1.33 2002/08/27 16:55:35 meichel
855  * Initial release of new DICOM I/O stream classes that add support for stream
856  * compression (deflated little endian explicit VR transfer syntax)
857  *
858  * Revision 1.32 2002/08/20 12:18:35 meichel
859  * Changed parameter list of loadFile and saveFile methods in class
860  * DcmFileFormat. Removed loadFile and saveFile from class DcmObject.
861  *
862  * Revision 1.31 2002/07/08 14:45:20 meichel
863  * Improved dcmdata behaviour when reading odd tag length. Depending on the
864  * global boolean flag dcmAcceptOddAttributeLength, the parser now either accepts
865  * odd length attributes or implements the old behaviour, i.e. assumes a real
866  * length larger by one.
867  *
868  * Revision 1.30 2002/04/25 09:38:47 joergr
869  * Added support for XML output of DICOM objects.
870  *
871  * Revision 1.29 2002/04/11 12:23:46 joergr
872  * Added new methods for loading and saving DICOM files.
873  *
874  * Revision 1.28 2001/11/16 15:54:39 meichel
875  * Adapted digital signature code to final text of supplement 41.
876  *
877  * Revision 1.27 2001/09/25 17:19:27 meichel
878  * Adapted dcmdata to class OFCondition
879  *
880  * Revision 1.26 2001/06/01 15:48:41 meichel
881  * Updated copyright header
882  *
883  * Revision 1.25 2000/11/07 16:56:07 meichel
884  * Initial release of dcmsign module for DICOM Digital Signatures
885  *
886  * Revision 1.24 2000/04/14 16:02:39 meichel
887  * Global flag dcmEnableAutomaticInputDataCorrection now derived from OFGlobal
888  * and, thus, safe for use in multi-thread applications.
889  *
890  * Revision 1.23 2000/03/08 16:26:16 meichel
891  * Updated copyright header.
892  *
893  * Revision 1.22 2000/03/03 14:05:24 meichel
894  * Implemented library support for redirecting error messages into memory
895  * instead of printing them to stdout/stderr for GUI applications.
896  *
897  * Revision 1.21 2000/02/10 10:50:52 joergr
898  * Added new feature to dcmdump (enhanced print method of dcmdata): write
899  * pixel data/item value fields to raw files.
900  *
901  * Revision 1.20 2000/02/01 10:12:02 meichel
902  * Avoiding to include <stdlib.h> as extern "C" on Borland C++ Builder 4,
903  * workaround for bug in compiler header files.
904  *
905  * Revision 1.19 1999/03/31 09:24:42 meichel
906  * Updated copyright header in module dcmdata
907  *
908  *
909  */


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