/work/dcmtk-install/include/dcmtk/dcmdata/dcistrma.h

Source
/*
 *
 *  Copyright (C) 1994-2018, 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:  Marco Eichelberg
 *
 *  Purpose: base classes for input streams
 *
 */

#ifndef DCISTRMA_H
#define DCISTRMA_H

#include "dcmtk/config/osconfig.h"
#include "dcmtk/ofstd/oftypes.h"  /* for OFBool */
#include "dcmtk/ofstd/ofcond.h"   /* for OFCondition */
#include "dcmtk/ofstd/offile.h"   /* for offile_off_t */
#include "dcmtk/dcmdata/dcxfer.h"   /* for E_StreamCompression */

class DcmInputStream;

/** pure virtual abstract base class for producers, i.e. the initial node
 *  of a filter chain in an input stream.
 */
class DCMTK_DCMDATA_EXPORT DcmProducer
{
public:

  /// destructor
  virtual ~DcmProducer()
  {
  }

  /** returns the status of the producer. Unless the status is good,
   *  the producer will not permit any operation.
   *  @return status, true if good
   */
  virtual OFBool good() const = 0;

  /** returns the status of the producer as an OFCondition object.
   *  Unless the status is good, the producer will not permit any operation.
   *  @return status, EC_Normal if good
   */
  virtual OFCondition status() const = 0;

  /** returns true if the producer is at the end of stream.
   *  @return true if end of stream, false otherwise
   */
  virtual OFBool eos() = 0;

  /** returns the minimum number of bytes that can be read with the
   *  next call to read(). The DcmObject read methods rely on avail
   *  to return a value > 0 if there is no I/O suspension since certain
   *  data such as tag and length are only read "en bloc", i.e. all
   *  or nothing.
   *  @return minimum of data available in producer
   */
  virtual offile_off_t avail() = 0;

  /** reads as many bytes as possible into the given block.
   *  @param buf pointer to memory block, must not be NULL
   *  @param buflen length of memory block
   *  @return number of bytes actually read.
   */
  virtual offile_off_t read(void *buf, offile_off_t buflen) = 0;

  /** skips over the given number of bytes (or less)
   *  @param skiplen number of bytes to skip
   *  @return number of bytes actually skipped.
   */
  virtual offile_off_t skip(offile_off_t skiplen) = 0;

  /** resets the stream to the position by the given number of bytes.
   *  @param num number of bytes to putback. If the putback operation
   *    fails, the producer status becomes bad.
   */
  virtual void putback(offile_off_t num) = 0;

};


/** pure virtual abstract base class for input filters, i.e.
 *  intermediate nodes of a filter chain in an input stream.
 */
class DCMTK_DCMDATA_EXPORT DcmInputFilter: public DcmProducer
{
public:

  /// destructor
  virtual ~DcmInputFilter()
  {
  }

  /** determines the producer from which the filter is supposed
   *  to read it's input. Once a producer for the input filter has
   *  been defined, it cannot be changed anymore during the lifetime
   *  of the object.
   *  @param producer reference to producer, must not be circular chain
   */
  virtual void append(DcmProducer& producer) = 0;
};

/** this enum identifies subclasses of class DcmInputStreamFactory.
 */
enum DcmInputStreamFactoryType
{
  /// class DcmInputFileStreamFactory
  DFT_DcmInputFileStreamFactory,

  /// class DcmInputTempFileStreamFactory
  DFT_DcmInputTempFileStreamFactory
};

/** pure virtual abstract base class for input stream factories,
 *  i.e. objects that can create a new input stream
 */
class DCMTK_DCMDATA_EXPORT DcmInputStreamFactory
{
public:

  /// destructor
  virtual ~DcmInputStreamFactory()
  {
  }

  /** create a new input stream object
   *  @return pointer to new input stream object
   */
  virtual DcmInputStream *create() const = 0;

  /** returns a pointer to a copy of this object
   *  @return pointer to a copy of this object
   */
  virtual DcmInputStreamFactory *clone() const = 0;

  /** returns an enum describing the class to which this instance belongs
   *  @return class to which this instance belongs
   */
  virtual DcmInputStreamFactoryType ident() const = 0;
};


/** abstract base class for input streams.
 */
class DCMTK_DCMDATA_EXPORT DcmInputStream
{
public:

  /// destructor
  virtual ~DcmInputStream();

  /** returns the status of the stream. Unless the status is good,
   *  the stream will not permit any operation.
   *  @return status, true if good
   */
  virtual OFBool good() const;

  /** returns the status of the stream as an OFCondition object.
   *  Unless the status is good, the stream will not permit any operation.
   *  @return status, EC_Normal if good
   */
  virtual OFCondition status() const;

  /** returns true if the producer is at the end of stream.
   *  @return true if end of stream, false otherwise
   */
  virtual OFBool eos();

  /** returns the minimum number of bytes that can be read with the
   *  next call to read(). The DcmObject read methods rely on avail
   *  to return a value > 0 if there is no I/O suspension since certain
   *  data such as tag and length are only read "en bloc", i.e. all
   *  or nothing.
   *  @return minimum of data available in producer
   */
  virtual offile_off_t avail();

  /** reads as many bytes as possible into the given block.
   *  @param buf pointer to memory block, must not be NULL
   *  @param buflen length of memory block
   *  @return number of bytes actually read.
   */
  virtual offile_off_t read(void *buf, offile_off_t buflen);

  /** skips over the given number of bytes (or less)
   *  @param skiplen number of bytes to skip
   *  @return number of bytes actually skipped.
   */
  virtual offile_off_t skip(offile_off_t skiplen);

  /** returns the total number of bytes read from the stream so far
   *  @return total number of bytes read from the stream
   */
  virtual offile_off_t tell() const;

  /** installs a compression filter for the given stream compression type,
   *  which should be neither ESC_none nor ESC_unsupported. Once a compression
   *  filter is active, it cannot be deactivated or replaced during the
   *  lifetime of the stream.
   *  @param filterType type of compression filter
   *  @return EC_Normal if successful, an error code otherwise
   */
  virtual OFCondition installCompressionFilter(E_StreamCompression filterType);

  /** creates a new factory object for the current stream
   *  and stream position.  When activated, the factory will be
   *  able to create new DcmInputStream delivering the same
   *  data as the current stream.  Used to defer loading of
   *  value fields until accessed.
   *  If no factory object can be created (e.g. because the
   *  stream is not seekable), returns NULL.
   *  @return pointer to new factory object if successful, NULL otherwise.
   */
  virtual DcmInputStreamFactory *newFactory() const = 0;

  /** marks the current stream position for a later putback operation,
   *  overwriting a possibly existing prior putback mark.
   *  The DcmObject read methods rely on the possibility to putback
   *  up to 132 bytes for transfer syntax detection, parse error recovery etc.
   *  Implementations of this class should guarantee a putback capability
   *  of at least 1 kbyte.
   */
  virtual void mark();

  /** resets the stream to the position previously marked with
   *  setPutbackMark(). If the putback operation fails (no putback mark
   *  set or putback buffer exceeded), status of the producer switches to bad.
   */
  virtual void putback();

protected:

  /** protected constructor, to be called from derived class constructor
   *  @param initial initial pointer to first node in filter chain
   *     The pointer is not dereferenced in the constructor, so the
   *     object pointed to may be initialized later in the subclass
   *     constructor.
   */
  DcmInputStream(DcmProducer *initial);

  /** returns pointer to current producer object
   */
  const DcmProducer *currentProducer() const;

private:

  /// private unimplemented copy constructor
  DcmInputStream(const DcmInputStream&);

  /// private unimplemented copy assignment operator
  DcmInputStream& operator=(const DcmInputStream&);

  /// pointer to first node in filter chain
  DcmProducer *current_;

  /// pointer to compression filter, NULL if no compression
  DcmInputFilter *compressionFilter_;

  /// counter for number of bytes read so far
  offile_off_t tell_;

  /// putback marker
  offile_off_t mark_;
};



#endif

Coverage Report

Created: 2026-03-31 06:23

Line	Count	Source
1		/*
2		*
3		* Copyright (C) 1994-2018, 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: Marco Eichelberg
17		*
18		* Purpose: base classes for input streams
19		*
20		*/
21
22		#ifndef DCISTRMA_H
23		#define DCISTRMA_H
24
25		#include "dcmtk/config/osconfig.h"
26		#include "dcmtk/ofstd/oftypes.h" /* for OFBool */
27		#include "dcmtk/ofstd/ofcond.h" /* for OFCondition */
28		#include "dcmtk/ofstd/offile.h" /* for offile_off_t */
29		#include "dcmtk/dcmdata/dcxfer.h" /* for E_StreamCompression */
30
31		class DcmInputStream;
32
33		/** pure virtual abstract base class for producers, i.e. the initial node
34		* of a filter chain in an input stream.
35		*/
36		class DCMTK_DCMDATA_EXPORT DcmProducer
37		{
38		public:
39
40		/// destructor
41		virtual ~DcmProducer()
42		{
43		}
44
45		/** returns the status of the producer. Unless the status is good,
46		* the producer will not permit any operation.
47		* @return status, true if good
48		*/
49		virtual OFBool good() const = 0;
50
51		/** returns the status of the producer as an OFCondition object.
52		* Unless the status is good, the producer will not permit any operation.
53		* @return status, EC_Normal if good
54		*/
55		virtual OFCondition status() const = 0;
56
57		/** returns true if the producer is at the end of stream.
58		* @return true if end of stream, false otherwise
59		*/
60		virtual OFBool eos() = 0;
61
62		/** returns the minimum number of bytes that can be read with the
63		* next call to read(). The DcmObject read methods rely on avail
64		* to return a value > 0 if there is no I/O suspension since certain
65		* data such as tag and length are only read "en bloc", i.e. all
66		* or nothing.
67		* @return minimum of data available in producer
68		*/
69		virtual offile_off_t avail() = 0;
70
71		/** reads as many bytes as possible into the given block.
72		* @param buf pointer to memory block, must not be NULL
73		* @param buflen length of memory block
74		* @return number of bytes actually read.
75		*/
76		virtual offile_off_t read(void *buf, offile_off_t buflen) = 0;
77
78		/** skips over the given number of bytes (or less)
79		* @param skiplen number of bytes to skip
80		* @return number of bytes actually skipped.
81		*/
82		virtual offile_off_t skip(offile_off_t skiplen) = 0;
83
84		/** resets the stream to the position by the given number of bytes.
85		* @param num number of bytes to putback. If the putback operation
86		* fails, the producer status becomes bad.
87		*/
88		virtual void putback(offile_off_t num) = 0;
89
90		};
91
92
93		/** pure virtual abstract base class for input filters, i.e.
94		* intermediate nodes of a filter chain in an input stream.
95		*/
96		class DCMTK_DCMDATA_EXPORT DcmInputFilter: public DcmProducer
97		{
98		public:
99
100		/// destructor
101		virtual ~DcmInputFilter()
102	0	{
103	0	}
104
105		/** determines the producer from which the filter is supposed
106		* to read it's input. Once a producer for the input filter has
107		* been defined, it cannot be changed anymore during the lifetime
108		* of the object.
109		* @param producer reference to producer, must not be circular chain
110		*/
111		virtual void append(DcmProducer& producer) = 0;
112		};
113
114		/** this enum identifies subclasses of class DcmInputStreamFactory.
115		*/
116		enum DcmInputStreamFactoryType
117		{
118		/// class DcmInputFileStreamFactory
119		DFT_DcmInputFileStreamFactory,
120
121		/// class DcmInputTempFileStreamFactory
122		DFT_DcmInputTempFileStreamFactory
123		};
124
125		/** pure virtual abstract base class for input stream factories,
126		* i.e. objects that can create a new input stream
127		*/
128		class DCMTK_DCMDATA_EXPORT DcmInputStreamFactory
129		{
130		public:
131
132		/// destructor
133		virtual ~DcmInputStreamFactory()
134		{
135		}
136
137		/** create a new input stream object
138		* @return pointer to new input stream object
139		*/
140		virtual DcmInputStream *create() const = 0;
141
142		/** returns a pointer to a copy of this object
143		* @return pointer to a copy of this object
144		*/
145		virtual DcmInputStreamFactory *clone() const = 0;
146
147		/** returns an enum describing the class to which this instance belongs
148		* @return class to which this instance belongs
149		*/
150		virtual DcmInputStreamFactoryType ident() const = 0;
151		};
152
153
154		/** abstract base class for input streams.
155		*/
156		class DCMTK_DCMDATA_EXPORT DcmInputStream
157		{
158		public:
159
160		/// destructor
161		virtual ~DcmInputStream();
162
163		/** returns the status of the stream. Unless the status is good,
164		* the stream will not permit any operation.
165		* @return status, true if good
166		*/
167		virtual OFBool good() const;
168
169		/** returns the status of the stream as an OFCondition object.
170		* Unless the status is good, the stream will not permit any operation.
171		* @return status, EC_Normal if good
172		*/
173		virtual OFCondition status() const;
174
175		/** returns true if the producer is at the end of stream.
176		* @return true if end of stream, false otherwise
177		*/
178		virtual OFBool eos();
179
180		/** returns the minimum number of bytes that can be read with the
181		* next call to read(). The DcmObject read methods rely on avail
182		* to return a value > 0 if there is no I/O suspension since certain
183		* data such as tag and length are only read "en bloc", i.e. all
184		* or nothing.
185		* @return minimum of data available in producer
186		*/
187		virtual offile_off_t avail();
188
189		/** reads as many bytes as possible into the given block.
190		* @param buf pointer to memory block, must not be NULL
191		* @param buflen length of memory block
192		* @return number of bytes actually read.
193		*/
194		virtual offile_off_t read(void *buf, offile_off_t buflen);
195
196		/** skips over the given number of bytes (or less)
197		* @param skiplen number of bytes to skip
198		* @return number of bytes actually skipped.
199		*/
200		virtual offile_off_t skip(offile_off_t skiplen);
201
202		/** returns the total number of bytes read from the stream so far
203		* @return total number of bytes read from the stream
204		*/
205		virtual offile_off_t tell() const;
206
207		/** installs a compression filter for the given stream compression type,
208		* which should be neither ESC_none nor ESC_unsupported. Once a compression
209		* filter is active, it cannot be deactivated or replaced during the
210		* lifetime of the stream.
211		* @param filterType type of compression filter
212		* @return EC_Normal if successful, an error code otherwise
213		*/
214		virtual OFCondition installCompressionFilter(E_StreamCompression filterType);
215
216		/** creates a new factory object for the current stream
217		* and stream position. When activated, the factory will be
218		* able to create new DcmInputStream delivering the same
219		* data as the current stream. Used to defer loading of
220		* value fields until accessed.
221		* If no factory object can be created (e.g. because the
222		* stream is not seekable), returns NULL.
223		* @return pointer to new factory object if successful, NULL otherwise.
224		*/
225		virtual DcmInputStreamFactory *newFactory() const = 0;
226
227		/** marks the current stream position for a later putback operation,
228		* overwriting a possibly existing prior putback mark.
229		* The DcmObject read methods rely on the possibility to putback
230		* up to 132 bytes for transfer syntax detection, parse error recovery etc.
231		* Implementations of this class should guarantee a putback capability
232		* of at least 1 kbyte.
233		*/
234		virtual void mark();
235
236		/** resets the stream to the position previously marked with
237		* setPutbackMark(). If the putback operation fails (no putback mark
238		* set or putback buffer exceeded), status of the producer switches to bad.
239		*/
240		virtual void putback();
241
242		protected:
243
244		/** protected constructor, to be called from derived class constructor
245		* @param initial initial pointer to first node in filter chain
246		* The pointer is not dereferenced in the constructor, so the
247		* object pointed to may be initialized later in the subclass
248		* constructor.
249		*/
250		DcmInputStream(DcmProducer *initial);
251
252		/** returns pointer to current producer object
253		*/
254		const DcmProducer *currentProducer() const;
255
256		private:
257
258		/// private unimplemented copy constructor
259		DcmInputStream(const DcmInputStream&);
260
261		/// private unimplemented copy assignment operator
262		DcmInputStream& operator=(const DcmInputStream&);
263
264		/// pointer to first node in filter chain
265		DcmProducer *current_;
266
267		/// pointer to compression filter, NULL if no compression
268		DcmInputFilter *compressionFilter_;
269
270		/// counter for number of bytes read so far
271		offile_off_t tell_;
272
273		/// putback marker
274		offile_off_t mark_;
275		};
276
277
278
279		#endif