1 /*
2  *
3  *  Copyright (C) 2008-2012, OFFIS e.V. and ICSMED AG, Oldenburg, Germany
4  *  Copyright (C) 2013-2017, J. Riesmeier, Oldenburg, Germany
5  *  All rights reserved.  See COPYRIGHT file for details.
6  *
7  *  Header file for class DRTMACParametersSequence
8  *
9  *  Generated automatically from DICOM PS 3.3-2017e
10  *  File created on 2017-12-05 09:30:54
11  *
12  */
13 
14 
15 #ifndef DRTMPS_H
16 #define DRTMPS_H
17 
18 #include "dcmtk/config/osconfig.h"     // make sure OS specific configuration is included first
19 
20 #include "dcmtk/ofstd/oflist.h"        // for standard list class
21 #include "dcmtk/dcmrt/drttypes.h"      // module-specific helper class
22 
23 
24 /** Interface class for MACParametersSequence (4ffe,0001)
25  */
26 class DCMTK_DCMRT_EXPORT DRTMACParametersSequence
27   : protected DRTTypes
28 {
29 
30   public:
31 
32     /** Item class
33      */
34     class DCMTK_DCMRT_EXPORT Item
35       : protected DRTTypes
36     {
37 
38       public:
39 
40       // --- constructors, destructor and operators ---
41 
42         /** (default) constructor
43          *  @param emptyDefaultItem flag used to mark the empty default item
44          */
45         Item(const OFBool emptyDefaultItem = OFFalse);
46 
47         /** copy constructor
48          *  @param copy item object to be copied
49          */
50         Item(const Item &copy);
51 
52         /** destructor
53          */
54         virtual ~Item();
55 
56         /** assigment operator
57          *  @param copy item object to be copied
58          *  @return reference to this object
59          */
60         Item &operator=(const Item &copy);
61 
62       // --- general methods ---
63 
64         /** clear all internal member variables
65          */
66         void clear();
67 
68         /** check if item is empty
69          *  @return OFTrue if item is empty, OFFalse otherwise
70          */
71         OFBool isEmpty();
72 
73         /** check if item is valid, i.e.\ not the empty default item
74          *  @return OFTrue if item is valid, OFFalse otherwise
75          */
76         OFBool isValid() const;
77 
78       // --- input/output methods ---
79 
80         /** read elements from sequence item
81          *  @param  item    reference to DICOM sequence item from which the elements should be read
82          *  @return status, EC_Normal if successful, an error code otherwise
83          */
84         OFCondition read(DcmItem &item);
85 
86         /** write elements to sequence item
87          *  @param  item    reference to DICOM sequence item to which the elements should be written
88          *  @return status, EC_Normal if successful, an error code otherwise
89          */
90         OFCondition write(DcmItem &item);
91 
92       // --- get DICOM attribute values ---
93 
94         /** get DataElementsSigned (0400,0020)
95          *  @param  value  reference to variable in which the value should be stored
96          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
97          *  @return status, EC_Normal if successful, an error code otherwise
98          */
99         OFCondition getDataElementsSigned(OFString &value, const signed long pos = 0) const;
100 
101         /** get MACAlgorithm (0400,0015)
102          *  @param  value  reference to variable in which the value should be stored
103          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
104          *  @return status, EC_Normal if successful, an error code otherwise
105          */
106         OFCondition getMACAlgorithm(OFString &value, const signed long pos = 0) const;
107 
108         /** get MACCalculationTransferSyntaxUID (0400,0010)
109          *  @param  value  reference to variable in which the value should be stored
110          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
111          *  @return status, EC_Normal if successful, an error code otherwise
112          */
113         OFCondition getMACCalculationTransferSyntaxUID(OFString &value, const signed long pos = 0) const;
114 
115         /** get MACIDNumber (0400,0005)
116          *  @param  value  reference to variable in which the value should be stored
117          *  @param  pos    index of the value to get (0..vm-1)
118          *  @return status, EC_Normal if successful, an error code otherwise
119          */
120         OFCondition getMACIDNumber(Uint16 &value, const unsigned long pos = 0) const;
121 
122       // --- set DICOM attribute values ---
123 
124         /** set DataElementsSigned (0400,0020)
125          *  @param  value  value to be set (possibly multi-valued) or "" for no value
126          *  @param  check  check 'value' for conformance with VR (AT) and VM (1-n) if enabled
127          *  @return status, EC_Normal if successful, an error code otherwise
128          */
129         OFCondition setDataElementsSigned(const OFString &value, const OFBool check = OFTrue);
130 
131         /** set MACAlgorithm (0400,0015)
132          *  @param  value  value to be set (single value only) or "" for no value
133          *  @param  check  check 'value' for conformance with VR (CS) and VM (1) if enabled
134          *  @return status, EC_Normal if successful, an error code otherwise
135          */
136         OFCondition setMACAlgorithm(const OFString &value, const OFBool check = OFTrue);
137 
138         /** set MACCalculationTransferSyntaxUID (0400,0010)
139          *  @param  value  value to be set (single value only) or "" for no value
140          *  @param  check  check 'value' for conformance with VR (UI) and VM (1) if enabled
141          *  @return status, EC_Normal if successful, an error code otherwise
142          */
143         OFCondition setMACCalculationTransferSyntaxUID(const OFString &value, const OFBool check = OFTrue);
144 
145         /** set MACIDNumber (0400,0005)
146          *  @param  value  value to be set (should be valid for this VR)
147          *  @param  pos    index of the value to be set (0..vm-1), vm=1
148          *  @return status, EC_Normal if successful, an error code otherwise
149          */
150         OFCondition setMACIDNumber(const Uint16 value, const unsigned long pos = 0);
151 
152       private:
153 
154         /// internal flag used to mark the empty default item
155         /*const*/ OFBool EmptyDefaultItem;
156 
157         /// DataElementsSigned (0400,0020) vr=AT, vm=1-n, type=1
158         DcmAttributeTag DataElementsSigned;
159         /// MACAlgorithm (0400,0015) vr=CS, vm=1, type=1
160         DcmCodeString MACAlgorithm;
161         /// MACCalculationTransferSyntaxUID (0400,0010) vr=UI, vm=1, type=1
162         DcmUniqueIdentifier MACCalculationTransferSyntaxUID;
163         /// MACIDNumber (0400,0005) vr=US, vm=1, type=1
164         DcmUnsignedShort MACIDNumber;
165 
166     };
167 
168   // --- constructors, destructor and operators ---
169 
170     /** (default) constructor
171      *  @param emptyDefaultSequence internal flag used to mark the empty default sequence
172      */
173     DRTMACParametersSequence(const OFBool emptyDefaultSequence = OFFalse);
174 
175     /** copy constructor
176      *  @param copy sequence object to be copied
177      */
178     DRTMACParametersSequence(const DRTMACParametersSequence &copy);
179 
180     /** destructor
181      */
182     virtual ~DRTMACParametersSequence();
183 
184     /** assigment operator
185      *  @param copy sequence object to be copied
186      *  @return reference to this object
187      */
188     DRTMACParametersSequence &operator=(const DRTMACParametersSequence &copy);
189 
190   // --- general methods ---
191 
192     /** clear all internal member variables
193      */
194     void clear();
195 
196     /** check if sequence is empty
197      *  @return OFTrue if sequence is empty, OFFalse otherwise
198      */
199     OFBool isEmpty();
200 
201     /** check if sequence is valid, i.e.\ not the empty default sequence
202      *  @return OFTrue if sequence is valid, OFFalse otherwise
203      */
204     OFBool isValid() const;
205 
206     /** get number of items in the sequence
207      *  @return number of items
208      */
209     size_t getNumberOfItems() const;
210 
211     /** goto first item in the sequence
212      *  @return status, EC_Normal if successful, an error code otherwise
213      */
214     OFCondition gotoFirstItem();
215 
216     /** goto next item in the sequence
217      *  @return status, EC_Normal if successful, an error code otherwise
218      */
219     OFCondition gotoNextItem();
220 
221     /** goto particular item in the sequence
222      *  @param  num  number of the item to be selected (0..num-1)
223      *  @return status, EC_Normal if successful, an error code otherwise
224      */
225     OFCondition gotoItem(const size_t num);
226 
227     /** get current item in the sequence
228      *  @param  item  reference to item pointer (result variable)
229      *  @return status, EC_Normal if successful, an error code otherwise
230      */
231     OFCondition getCurrentItem(Item *&item) const;
232 
233     /** get current item in the sequence
234      *  @return reference to specified item if successful, empty default item otherwise
235      */
236     Item &getCurrentItem();
237 
238     /** get current item in the sequence
239      *  @return const reference to specified item if successful, empty default item otherwise
240      */
241     const Item &getCurrentItem() const;
242 
243     /** get particular item in the sequence
244      *  @param  num   number of the item to be retrieved (0..num-1)
245      *  @param  item  reference to item pointer (result variable)
246      *  @return status, EC_Normal if successful, an error code otherwise
247      */
248     OFCondition getItem(const size_t num, Item *&item);
249 
250     /** get particular item in the sequence
251      *  @param  num  number of the item to be retrieved (0..num-1)
252      *  @return reference to specified item if successful, empty default item otherwise
253      */
254     Item &getItem(const size_t num);
255 
256     /** get particular item in the sequence
257      *  @param  num  number of the item to be retrieved (0..num-1)
258      *  @return const reference to specified item if successful, empty default item otherwise
259      */
260     const Item &getItem(const size_t num) const;
261 
262     /** get particular item in the sequence
263      *  @param  num  number of the item to be retrieved (0..num-1)
264      *  @return reference to specified item if successful, empty default item otherwise
265      */
266     Item &operator[](const size_t num);
267 
268     /** get particular item in the sequence
269      *  @param  num  number of the item to be retrieved (0..num-1)
270      *  @return const reference to specified item if successful, empty default item otherwise
271      */
272     const Item &operator[](const size_t num) const;
273 
274     /** add new item to the end of this sequence
275      *  @param  item  reference to new item pointer (result variable)
276      *  @return status, EC_Normal if successful, an error code otherwise
277      */
278     OFCondition addItem(Item *&item);
279 
280     /** insert new item into the sequence
281      *  @param  pos   position where the new item is to be inserted (0..num)
282      *  @param  item  reference to new item pointer (result variable)
283      *  @return status, EC_Normal if successful, an error code otherwise
284      */
285     OFCondition insertItem(const size_t pos, Item *&item);
286 
287     /** remove particular item from the sequence
288      *  @param  pos  position of the item to be removed (0..num-1)
289      *  @return status, EC_Normal if successful, an error code otherwise
290      */
291     OFCondition removeItem(const size_t pos);
292 
293   // --- input/output methods ---
294 
295     /** read sequence of items from dataset
296      *  @param  dataset     reference to DICOM dataset from which the sequence should be read
297      *  @param  card        cardinality (valid range for number of items)
298      *  @param  type        value type (valid value: "1", "1C", "2" or something else which is not checked)
299      *  @param  moduleName  optional module/sequence name to be printed (default: "RT object" if NULL)
300      *  @return status, EC_Normal if successful, an error code otherwise
301      */
302     OFCondition read(DcmItem &dataset,
303                      const OFString &card,
304                      const OFString &type,
305                      const char *moduleName = NULL);
306 
307     /** write sequence of items to dataset
308      *  @param  dataset     reference to DICOM dataset to which the sequence should be written
309      *  @param  card        cardinality (valid range for number of items)
310      *  @param  type        value type (valid value: "1", "2" or something else which is not checked)
311      *  @param  moduleName  optional module/sequence name to be printed (default: "RT object" if NULL)
312      *  @return status, EC_Normal if successful, an error code otherwise
313      */
314     OFCondition write(DcmItem &dataset,
315                       const OFString &card,
316                       const OFString &type,
317                       const char *moduleName = NULL);
318 
319   protected:
320 
321     /** goto particular item in the sequence
322      *  @param  num       number of the item to be selected (0..num-1)
323      *  @param  iterator  list iterator storing the position of the item
324      *  @return status, EC_Normal if successful, an error code otherwise
325      */
326     OFCondition gotoItem(const size_t num,
327                          OFListIterator(Item *) &iterator);
328 
329     /** goto particular item in the sequence
330      *  @param  num       number of the item to be selected (0..num-1)
331      *  @param  iterator  list iterator storing the position of the item
332      *  @return status, EC_Normal if successful, an error code otherwise
333      */
334     OFCondition gotoItem(const size_t num,
335                          OFListConstIterator(Item *) &iterator) const;
336 
337   private:
338 
339     /// internal flag used to mark the empty default sequence
340     /*const*/ OFBool EmptyDefaultSequence;
341 
342     /// list of items in this sequence
343     OFList<Item *>         SequenceOfItems;
344     /// currently selected item
345     OFListIterator(Item *) CurrentItem;
346     /// empty default item
347     Item                   EmptyItem;
348 
349 };
350 
351 
352 #endif
353