dcmdata/include/dcmtk/dcmdata/dcobject.h

/*
 *
 *  Copyright (C) 1994-2010, 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:
 *  This file contains the interface to routines which provide
 *  DICOM object encoding/decoding, search and lookup facilities.
 *
 *  Last Update:      $Author: joergr $
 *  Update Date:      $Date: 2010-10-29 10:57:17 $
 *  CVS/RCS Revision: $Revision: 1.70 $
 *  Status:           $State: Exp $
 *
 *  CVS/RCS Log at end of file
 *
 */


#ifndef DCOBJECT_H
#define DCOBJECT_H

#include "dcmtk/config/osconfig.h"    /* make sure OS specific configuration is included first */

#include "dcmtk/ofstd/ofglobal.h"
#include "dcmtk/dcmdata/dcerror.h"
#include "dcmtk/dcmdata/dcxfer.h"
#include "dcmtk/dcmdata/dctag.h"
#include "dcmtk/dcmdata/dcstack.h"


// forward declarations
class DcmOutputStream;
class DcmInputStream;
class DcmWriteCache;

// Undefined Length Identifier now defined in dctypes.h

// Maxinum number of read bytes for a Value Element
const Uint32 DCM_MaxReadLength = 4096;

// Maximum length of tag and length in a DICOM element
const Uint32 DCM_TagInfoLength = 12;

// Optimum line length if not all data printed
const Uint32 DCM_OptPrintLineLength = 70;

// Optimum value length if not all data printed
const Uint32 DCM_OptPrintValueLength = 40;

// Optimum attribute name length (for tree output)
const Uint32 DCM_OptPrintAttributeNameLength = 35;

extern OFGlobal<OFBool> dcmEnableAutomaticInputDataCorrection; /* default OFTrue */

extern OFGlobal<OFBool> dcmAcceptOddAttributeLength; /* default OFTrue */

extern OFGlobal<OFBool> dcmEnableCP246Support; /* default OFTrue */

extern OFGlobal<OFBool> dcmEnableOldSignatureFormat; /* default OFFalse */

extern OFGlobal<OFBool> dcmAutoDetectDatasetXfer; /* default OFFalse */

extern OFGlobal<OFBool> dcmAcceptUnexpectedImplicitEncoding; /* default OFFalse */

extern OFGlobal<OFBool> dcmReadImplPrivAttribMaxLengthAsSQ; /* default OFFalse */

extern OFGlobal<OFBool> dcmIgnoreParsingErrors; /* default OFFalse */

extern OFGlobal<DcmTagKey> dcmStopParsingAfterElement; /* default OFTrue */

extern OFGlobal<OFBool> dcmWriteOversizedSeqsAndItemsUndefined; /* default OFTrue */

extern OFGlobal<OFBool> dcmIgnoreFileMetaInformationGroupLength; /* default OFFalse */


class DcmObject
{
  public:

    DcmObject(const DcmTag &tag, const Uint32 len = 0);

    DcmObject(const DcmObject &obj);

    virtual ~DcmObject();

    virtual DcmObject *clone() const = 0;

    DcmObject &operator=(const DcmObject &obj);

    virtual OFCondition copyFrom(const DcmObject &rhs) = 0;

    virtual DcmEVR ident() const = 0;

    inline DcmEVR getVR() const { return Tag.getEVR(); }

    inline OFBool isaString() const { return Tag.getVR().isaString(); }

    virtual OFBool isLeaf() const = 0;

    virtual void print(STD_NAMESPACE ostream &out,
                       const size_t flags = 0,
                       const int level = 0,
                       const char *pixelFileName = NULL,
                       size_t *pixelCounter = NULL) = 0;

    inline E_TransferState transferState() const { return fTransferState; }

    virtual void transferInit(void);

    virtual void transferEnd(void);

    inline Uint16 getGTag() const { return Tag.getGTag(); }

    inline Uint16 getETag() const { return Tag.getETag(); }

    inline const DcmTag &getTag() const { return Tag; }

    inline void setGTag(Uint16 gtag) { Tag.setGroup(gtag); }

    virtual OFCondition setVR(DcmEVR /*vr*/) { return EC_IllegalCall; }

    virtual unsigned long getVM() = 0;

    virtual Uint32 calcElementLength(const E_TransferSyntax xfer,
                                     const E_EncodingType enctype) = 0;

    virtual Uint32 getLength(const E_TransferSyntax xfer = EXS_LittleEndianImplicit,
                             const E_EncodingType enctype = EET_UndefinedLength) = 0;

    virtual OFBool canWriteXfer(const E_TransferSyntax newXfer,
                                const E_TransferSyntax oldXfer) = 0;

    virtual OFCondition read(DcmInputStream &inStream,
                             const E_TransferSyntax ixfer,
                             const E_GrpLenEncoding glenc = EGL_noChange,
                             const Uint32 maxReadLength = DCM_MaxReadLength) = 0;

    virtual OFCondition write(DcmOutputStream &outStream,
                              const E_TransferSyntax oxfer,
                              const E_EncodingType enctype,
                              DcmWriteCache *wcache) = 0;

    virtual OFCondition writeXML(STD_NAMESPACE ostream&out,
                                 const size_t flags = 0);

    virtual OFCondition writeSignatureFormat(DcmOutputStream &outStream,
                                             const E_TransferSyntax oxfer,
                                             const E_EncodingType enctype,
                                             DcmWriteCache *wcache) = 0;

    virtual OFBool isSignable() const;

    virtual OFBool containsUnknownVR() const;

    virtual OFBool containsExtendedCharacters(const OFBool checkAllStrings = OFFalse);

    virtual OFBool isAffectedBySpecificCharacterSet() const;

    virtual OFBool isEmpty(const OFBool normalize = OFTrue);

    virtual OFCondition clear() = 0;

    virtual OFCondition verify(const OFBool autocorrect = OFFalse) = 0;

    virtual DcmObject *nextInContainer(const DcmObject *obj);

    virtual OFCondition nextObject(DcmStack &stack,
                                   const OFBool intoSub);

    virtual OFCondition search(const DcmTagKey &xtag,
                               DcmStack &resultStack,
                               E_SearchMode mode = ESM_fromHere,
                               OFBool searchIntoSub = OFTrue);

    virtual OFCondition loadAllDataIntoMemory() = 0;

    Uint32 getLengthField() const { return Length; }

 protected:

    void printNestingLevel(STD_NAMESPACE ostream &out,
                           const size_t flags,
                           const int level);

    void printInfoLineStart(STD_NAMESPACE ostream &out,
                            const size_t flags,
                            const int level,
                            DcmTag *tag = NULL);

    void printInfoLineEnd(STD_NAMESPACE ostream &out,
                          const size_t flags,
                          const unsigned long printedLength = 0xffffffff /*no padding*/,
                          DcmTag *tag = NULL);

    virtual void printInfoLine(STD_NAMESPACE ostream &out,
                               const size_t flags,
                               const int level = 0,
                               const char *info = NULL,
                               DcmTag *tag = NULL,
                               const OFBool isInfo = OFTrue);

    static OFCondition writeTag(DcmOutputStream &outStream,
                                const DcmTag &tag,
                                const E_TransferSyntax oxfer);

    virtual OFCondition writeTagAndLength(DcmOutputStream &outStream,
                                          const E_TransferSyntax oxfer, // in
                                          Uint32 &writtenBytes) const;  // out

    virtual Uint32 getTagAndLengthSize(const E_TransferSyntax oxfer) const;

    const char *getTagName() { return Tag.getTagName(); }

    void setTagVR(DcmEVR vr) { Tag.setVR(vr); }

    E_TransferState getTransferState() const { return fTransferState; }

    void setTransferState(E_TransferState newState) { fTransferState = newState; }

    Uint32 getTransferredBytes() const { return fTransferredBytes; }

    void setTransferredBytes(Uint32 val) { fTransferredBytes = val; }

    void incTransferredBytes(Uint32 val) { fTransferredBytes += val; }

    void setLengthField(Uint32 val) { Length = val; }

public:
    class PrintHelper
    {
      private:
        PrintHelper& operator=(PrintHelper &);

      public:
        explicit PrintHelper(DcmObject &dcmobj, size_t flags = 0, int level = 0)
          : dcmobj_(dcmobj), flags_(flags), level_(level)
        {}

        DcmObject &dcmobj_;
        const size_t flags_;
        const int level_;
    };

    /* member variables */

protected:

    OFCondition errorFlag;

private:

    DcmTag Tag;

    Uint32 Length;

    E_TransferState fTransferState;

    Uint32 fTransferredBytes;

 }; // class DcmObject

static inline STD_NAMESPACE ostream& operator<<(STD_NAMESPACE ostream &stream, DcmObject::PrintHelper obj)
{
    obj.dcmobj_.print(stream, obj.flags_, obj.level_);
    return stream;
}

#endif // DCOBJECT_H


/*
 * CVS/RCS Log:
 * $Log: dcobject.h,v $
 * Revision 1.70  2010-10-29 10:57:17  joergr
 * Added support for colored output to the print() method.
 *
 * Revision 1.69  2010-10-14 13:15:41  joergr
 * Updated copyright header. Added reference to COPYRIGHT file.
 *
 * Revision 1.68  2010-06-18 08:17:57  uli
 * Added undefined assignment operator to PrintHelper to work around
 * a warning with VC2008.
 *
 * Revision 1.67  2010-03-01 09:08:44  uli
 * Removed some unnecessary include directives in the headers.
 *
 * Revision 1.66  2010-02-22 11:39:54  uli
 * Remove some unneeded includes.
 *
 * Revision 1.65  2009-11-04 09:58:07  uli
 * Switched to logging mechanism provided by the "new" oflog module
 *
 * Revision 1.64  2009-10-13 14:26:09  uli
 * Added the DcmObject::PrintHelper helper class. This class can be used to
 * print DcmObject instances with oflog's logging macros.
 *
 * Revision 1.63  2009-08-07 14:40:38  joergr
 * Enhanced isEmpty() method by checking whether the data element value consists
 * of non-significant characters only.
 *
 * Revision 1.62  2009-06-04 16:52:14  joergr
 * Added new parsing flag that allows for ignoring the value of File Meta
 * Information Group Length (0002,0000).
 *
 * Revision 1.61  2009-03-25 10:22:09  joergr
 * Added new method isEmpty() to DICOM object, item and sequence class.
 *
 * Revision 1.60  2009-03-05 14:07:56  onken
 * Fixed typo.
 *
 * Revision 1.59  2009-03-05 13:35:47  onken
 * Added checks for sequence and item lengths which prevents overflow in length
 * field, if total length of contained items (or sequences) exceeds
 * 32-bit length field. Also introduced new flag (default: enabled)
 * for writing in explicit length mode, which allows for automatically
 * switching encoding of only that very sequence/item to undefined
 * length coding (thus permitting to actually write the file).
 *
 * Revision 1.58  2009-02-11 13:16:32  onken
 * Added global parser flag permitting to stop parsing after a specific
 * element was parsed on dataset level (useful for removing garbage at
 * end of file).
 *
 * Revision 1.57  2009-02-04 17:54:30  joergr
 * Fixed various layout and formatting issues.
 *
 * Revision 1.56  2009-02-04 14:05:01  onken
 * Introduced global flag that, if enabled, tells the parser to continue
 * parsing if possible.
 *
 * Revision 1.55  2009-01-29 15:36:16  onken
 * Added global parsing option that allows for reading private attributes in
 * implicit encoding having a maximum length to be read as sequences instead
 * of relying on the dictionary.
 *
 * Revision 1.54  2009-01-06 16:28:11  joergr
 * Reworked print() output format for option PF_showTreeStructure.
 *
 * Revision 1.53  2009-01-05 15:32:23  joergr
 * Added global flag that allows for reading incorrectly encoded DICOM datasets
 * where particular data elements are encoded with a differing transfer syntax
 * (Implicit VR Little endian instead of Explicit VR encoding as declared).
 *
 * Revision 1.52  2008-09-24 13:33:53  joergr
 * Fixed typo in comment.
 *
 * Revision 1.51  2008-07-17 11:19:49  onken
 * Updated copyFrom() documentation.
 *
 * Revision 1.50  2008-07-17 10:30:23  onken
 * Implemented copyFrom() method for complete DcmObject class hierarchy, which
 * permits setting an instance's value from an existing object. Implemented
 * assignment operator where necessary.
 *
 * Revision 1.49  2008-04-17 14:48:39  meichel
 * Method DcmObject::getLengthField now public, needed by dcmcheck
 *
 * Revision 1.48  2007/11/29 14:30:19  meichel
 * Write methods now handle large raw data elements (such as pixel data)
 *   without loading everything into memory. This allows very large images to
 *   be sent over a network connection, or to be copied without ever being
 *   fully in memory.
 *
 * Revision 1.47  2007/06/29 14:17:49  meichel
 * Code clean-up: Most member variables in module dcmdata are now private,
 *   not protected anymore.
 *
 * Revision 1.46  2007/02/19 15:04:34  meichel
 * Removed searchErrors() methods that are not used anywhere and added
 *   error() methods only in the DcmObject subclasses where really used.
 *
 * Revision 1.45  2006/12/15 14:18:07  joergr
 * Added new method that checks whether a DICOM object or element is affected
 * by SpecificCharacterSet (0008,0005).
 *
 * Revision 1.44  2006/12/13 13:58:15  joergr
 * Added new optional parameter "checkAllStrings" to method containsExtended
 * Characters().
 *
 * Revision 1.43  2006/08/15 15:49:56  meichel
 * Updated all code in module dcmdata to correctly compile when
 *   all standard C++ classes remain in namespace std.
 *
 * Revision 1.42  2006/05/11 08:54:23  joergr
 * Moved checkForNonASCIICharacters() from application to library.
 *
 * Revision 1.41  2005/12/08 16:28:22  meichel
 * Changed include path schema for all DCMTK header files
 *
 * Revision 1.40  2005/12/02 08:49:17  joergr
 * Changed macro NO_XFER_DETECTION_FOR_DATASETS into a global option that can
 * be enabled and disabled at runtime.
 *
 * Revision 1.39  2005/11/24 12:50:57  meichel
 * Fixed bug in code that prepares a byte stream that is fed into the MAC
 *   algorithm when creating or verifying a digital signature. The previous
 *   implementation was non-conformant when signatures included compressed
 *   (encapsulated) pixel data because the item length was included in the byte
 *   stream, while it should not. The global variable dcmEnableOldSignatureFormat
 *   and a corresponding command line option in dcmsign allow to re-enable the old
 *   implementation.
 *
 * Revision 1.38  2005/05/10 15:27:14  meichel
 * Added support for reading UN elements with undefined length according
 *   to CP 246. The global flag dcmEnableCP246Support allows to revert to the
 *   prior behaviour in which UN elements with undefined length were parsed
 *   like a normal explicit VR SQ element.
 *
 * Revision 1.37  2004/07/01 12:28:25  meichel
 * Introduced virtual clone method for DcmObject and derived classes.
 *
 * Revision 1.36  2004/04/27 09:21:01  wilkens
 * Fixed a bug in dcelem.cc which occurs when one is serializing a dataset
 * (that contains an attribute whose length value is coded with 2 bytes) into
 * a given buffer. Although the number of available bytes in the buffer was
 * sufficient, the dataset->write(...) method would always return
 * EC_StreamNotifyClient to indicate that there are not sufficient bytes
 * available in the buffer. This code modification fixes the problem.
 *
 * Revision 1.35  2003/06/12 13:33:21  joergr
 * Fixed inconsistent API documentation reported by Doxygen.
 *
 * Revision 1.34  2002/12/06 12:49:11  joergr
 * Enhanced "print()" function by re-working the implementation and replacing
 * the boolean "showFullData" parameter by a more general integer flag.
 * Added doc++ documentation.
 * Made source code formatting more consistent with other modules/files.
 *
 * Revision 1.33  2002/08/27 16:55:35  meichel
 * Initial release of new DICOM I/O stream classes that add support for stream
 *   compression (deflated little endian explicit VR transfer syntax)
 *
 * Revision 1.32  2002/08/20 12:18:35  meichel
 * Changed parameter list of loadFile and saveFile methods in class
 *   DcmFileFormat. Removed loadFile and saveFile from class DcmObject.
 *
 * Revision 1.31  2002/07/08 14:45:20  meichel
 * Improved dcmdata behaviour when reading odd tag length. Depending on the
 *   global boolean flag dcmAcceptOddAttributeLength, the parser now either accepts
 *   odd length attributes or implements the old behaviour, i.e. assumes a real
 *   length larger by one.
 *
 * Revision 1.30  2002/04/25 09:38:47  joergr
 * Added support for XML output of DICOM objects.
 *
 * Revision 1.29  2002/04/11 12:23:46  joergr
 * Added new methods for loading and saving DICOM files.
 *
 * Revision 1.28  2001/11/16 15:54:39  meichel
 * Adapted digital signature code to final text of supplement 41.
 *
 * Revision 1.27  2001/09/25 17:19:27  meichel
 * Adapted dcmdata to class OFCondition
 *
 * Revision 1.26  2001/06/01 15:48:41  meichel
 * Updated copyright header
 *
 * Revision 1.25  2000/11/07 16:56:07  meichel
 * Initial release of dcmsign module for DICOM Digital Signatures
 *
 * Revision 1.24  2000/04/14 16:02:39  meichel
 * Global flag dcmEnableAutomaticInputDataCorrection now derived from OFGlobal
 *   and, thus, safe for use in multi-thread applications.
 *
 * Revision 1.23  2000/03/08 16:26:16  meichel
 * Updated copyright header.
 *
 * Revision 1.22  2000/03/03 14:05:24  meichel
 * Implemented library support for redirecting error messages into memory
 *   instead of printing them to stdout/stderr for GUI applications.
 *
 * Revision 1.21  2000/02/10 10:50:52  joergr
 * Added new feature to dcmdump (enhanced print method of dcmdata): write
 * pixel data/item value fields to raw files.
 *
 * Revision 1.20  2000/02/01 10:12:02  meichel
 * Avoiding to include <stdlib.h> as extern "C" on Borland C++ Builder 4,
 *   workaround for bug in compiler header files.
 *
 * Revision 1.19  1999/03/31 09:24:42  meichel
 * Updated copyright header in module dcmdata
 *
 *
 */

---

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