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 DRTScheduledProtocolCodeSequence
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 DRTSPCS_H
16 #define DRTSPCS_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 #include "dcmtk/dcmrt/seq/drtecs.h"    // for EquivalentCodeSequence
23 #include "dcmtk/dcmrt/seq/drtpcxs.h"   // for ProtocolContextSequence
24 
25 
26 /** Interface class for ScheduledProtocolCodeSequence (0040,0008)
27  */
28 class DCMTK_DCMRT_EXPORT DRTScheduledProtocolCodeSequence
29   : protected DRTTypes
30 {
31 
32   public:
33 
34     /** Item class
35      */
36     class DCMTK_DCMRT_EXPORT Item
37       : protected DRTTypes
38     {
39 
40       public:
41 
42       // --- constructors, destructor and operators ---
43 
44         /** (default) constructor
45          *  @param emptyDefaultItem flag used to mark the empty default item
46          */
47         Item(const OFBool emptyDefaultItem = OFFalse);
48 
49         /** copy constructor
50          *  @param copy item object to be copied
51          */
52         Item(const Item &copy);
53 
54         /** destructor
55          */
56         virtual ~Item();
57 
58         /** assigment operator
59          *  @param copy item object to be copied
60          *  @return reference to this object
61          */
62         Item &operator=(const Item &copy);
63 
64       // --- general methods ---
65 
66         /** clear all internal member variables
67          */
68         void clear();
69 
70         /** check if item is empty
71          *  @return OFTrue if item is empty, OFFalse otherwise
72          */
73         OFBool isEmpty();
74 
75         /** check if item is valid, i.e.\ not the empty default item
76          *  @return OFTrue if item is valid, OFFalse otherwise
77          */
78         OFBool isValid() const;
79 
80       // --- input/output methods ---
81 
82         /** read elements from sequence item
83          *  @param  item    reference to DICOM sequence item from which the elements should be read
84          *  @return status, EC_Normal if successful, an error code otherwise
85          */
86         OFCondition read(DcmItem &item);
87 
88         /** write elements to sequence item
89          *  @param  item    reference to DICOM sequence item to which the elements should be written
90          *  @return status, EC_Normal if successful, an error code otherwise
91          */
92         OFCondition write(DcmItem &item);
93 
94       // --- get DICOM attribute values ---
95 
96         /** get CodeMeaning (0008,0104)
97          *  @param  value  reference to variable in which the value should be stored
98          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
99          *  @return status, EC_Normal if successful, an error code otherwise
100          */
101         OFCondition getCodeMeaning(OFString &value, const signed long pos = 0) const;
102 
103         /** get CodeValue (0008,0100)
104          *  @param  value  reference to variable in which the value should be stored
105          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
106          *  @return status, EC_Normal if successful, an error code otherwise
107          */
108         OFCondition getCodeValue(OFString &value, const signed long pos = 0) const;
109 
110         /** get CodingSchemeDesignator (0008,0102)
111          *  @param  value  reference to variable in which the value should be stored
112          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
113          *  @return status, EC_Normal if successful, an error code otherwise
114          */
115         OFCondition getCodingSchemeDesignator(OFString &value, const signed long pos = 0) const;
116 
117         /** get CodingSchemeVersion (0008,0103)
118          *  @param  value  reference to variable in which the value should be stored
119          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
120          *  @return status, EC_Normal if successful, an error code otherwise
121          */
122         OFCondition getCodingSchemeVersion(OFString &value, const signed long pos = 0) const;
123 
124         /** get ContextGroupExtensionCreatorUID (0008,010d)
125          *  @param  value  reference to variable in which the value should be stored
126          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
127          *  @return status, EC_Normal if successful, an error code otherwise
128          */
129         OFCondition getContextGroupExtensionCreatorUID(OFString &value, const signed long pos = 0) const;
130 
131         /** get ContextGroupExtensionFlag (0008,010b)
132          *  @param  value  reference to variable in which the value should be stored
133          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
134          *  @return status, EC_Normal if successful, an error code otherwise
135          */
136         OFCondition getContextGroupExtensionFlag(OFString &value, const signed long pos = 0) const;
137 
138         /** get ContextGroupLocalVersion (0008,0107)
139          *  @param  value  reference to variable in which the value should be stored
140          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
141          *  @return status, EC_Normal if successful, an error code otherwise
142          */
143         OFCondition getContextGroupLocalVersion(OFString &value, const signed long pos = 0) const;
144 
145         /** get ContextGroupVersion (0008,0106)
146          *  @param  value  reference to variable in which the value should be stored
147          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
148          *  @return status, EC_Normal if successful, an error code otherwise
149          */
150         OFCondition getContextGroupVersion(OFString &value, const signed long pos = 0) const;
151 
152         /** get ContextIdentifier (0008,010f)
153          *  @param  value  reference to variable in which the value should be stored
154          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
155          *  @return status, EC_Normal if successful, an error code otherwise
156          */
157         OFCondition getContextIdentifier(OFString &value, const signed long pos = 0) const;
158 
159         /** get ContextUID (0008,0117)
160          *  @param  value  reference to variable in which the value should be stored
161          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
162          *  @return status, EC_Normal if successful, an error code otherwise
163          */
164         OFCondition getContextUID(OFString &value, const signed long pos = 0) const;
165 
166         /** get LongCodeValue (0008,0119)
167          *  @param  value  reference to variable in which the value should be stored
168          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
169          *  @return status, EC_Normal if successful, an error code otherwise
170          */
171         OFCondition getLongCodeValue(OFString &value, const signed long pos = 0) const;
172 
173         /** get MappingResource (0008,0105)
174          *  @param  value  reference to variable in which the value should be stored
175          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
176          *  @return status, EC_Normal if successful, an error code otherwise
177          */
178         OFCondition getMappingResource(OFString &value, const signed long pos = 0) const;
179 
180         /** get MappingResourceName (0008,0122)
181          *  @param  value  reference to variable in which the value should be stored
182          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
183          *  @return status, EC_Normal if successful, an error code otherwise
184          */
185         OFCondition getMappingResourceName(OFString &value, const signed long pos = 0) const;
186 
187         /** get MappingResourceUID (0008,0118)
188          *  @param  value  reference to variable in which the value should be stored
189          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
190          *  @return status, EC_Normal if successful, an error code otherwise
191          */
192         OFCondition getMappingResourceUID(OFString &value, const signed long pos = 0) const;
193 
194         /** get URNCodeValue (0008,0120)
195          *  @param  value  reference to variable in which the value should be stored
196          *  @param  pos    index of the value to get (0..vm-1), -1 for all components
197          *  @return status, EC_Normal if successful, an error code otherwise
198          */
199         OFCondition getURNCodeValue(OFString &value, const signed long pos = 0) const;
200 
201       // --- get DICOM sequence attributes ---
202 
203         /** get EquivalentCodeSequence (0008,0121)
204          *  @return reference to sequence element
205          */
getEquivalentCodeSequence()206         DRTEquivalentCodeSequence &getEquivalentCodeSequence()
207             { return EquivalentCodeSequence; }
208 
209         /** get EquivalentCodeSequence (0008,0121)
210          *  @return const reference to sequence element
211          */
getEquivalentCodeSequence()212         const DRTEquivalentCodeSequence &getEquivalentCodeSequence() const
213             { return EquivalentCodeSequence; }
214 
215         /** get ProtocolContextSequence (0040,0440)
216          *  @return reference to sequence element
217          */
getProtocolContextSequence()218         DRTProtocolContextSequence &getProtocolContextSequence()
219             { return ProtocolContextSequence; }
220 
221         /** get ProtocolContextSequence (0040,0440)
222          *  @return const reference to sequence element
223          */
getProtocolContextSequence()224         const DRTProtocolContextSequence &getProtocolContextSequence() const
225             { return ProtocolContextSequence; }
226 
227       // --- set DICOM attribute values ---
228 
229         /** set CodeMeaning (0008,0104)
230          *  @param  value  value to be set (single value only) or "" for no value
231          *  @param  check  check 'value' for conformance with VR (LO) and VM (1) if enabled
232          *  @return status, EC_Normal if successful, an error code otherwise
233          */
234         OFCondition setCodeMeaning(const OFString &value, const OFBool check = OFTrue);
235 
236         /** set CodeValue (0008,0100)
237          *  @param  value  value to be set (single value only) or "" for no value
238          *  @param  check  check 'value' for conformance with VR (SH) and VM (1) if enabled
239          *  @return status, EC_Normal if successful, an error code otherwise
240          */
241         OFCondition setCodeValue(const OFString &value, const OFBool check = OFTrue);
242 
243         /** set CodingSchemeDesignator (0008,0102)
244          *  @param  value  value to be set (single value only) or "" for no value
245          *  @param  check  check 'value' for conformance with VR (SH) and VM (1) if enabled
246          *  @return status, EC_Normal if successful, an error code otherwise
247          */
248         OFCondition setCodingSchemeDesignator(const OFString &value, const OFBool check = OFTrue);
249 
250         /** set CodingSchemeVersion (0008,0103)
251          *  @param  value  value to be set (single value only) or "" for no value
252          *  @param  check  check 'value' for conformance with VR (SH) and VM (1) if enabled
253          *  @return status, EC_Normal if successful, an error code otherwise
254          */
255         OFCondition setCodingSchemeVersion(const OFString &value, const OFBool check = OFTrue);
256 
257         /** set ContextGroupExtensionCreatorUID (0008,010d)
258          *  @param  value  value to be set (single value only) or "" for no value
259          *  @param  check  check 'value' for conformance with VR (UI) and VM (1) if enabled
260          *  @return status, EC_Normal if successful, an error code otherwise
261          */
262         OFCondition setContextGroupExtensionCreatorUID(const OFString &value, const OFBool check = OFTrue);
263 
264         /** set ContextGroupExtensionFlag (0008,010b)
265          *  @param  value  value to be set (single value only) or "" for no value
266          *  @param  check  check 'value' for conformance with VR (CS) and VM (1) if enabled
267          *  @return status, EC_Normal if successful, an error code otherwise
268          */
269         OFCondition setContextGroupExtensionFlag(const OFString &value, const OFBool check = OFTrue);
270 
271         /** set ContextGroupLocalVersion (0008,0107)
272          *  @param  value  value to be set (single value only) or "" for no value
273          *  @param  check  check 'value' for conformance with VR (DT) and VM (1) if enabled
274          *  @return status, EC_Normal if successful, an error code otherwise
275          */
276         OFCondition setContextGroupLocalVersion(const OFString &value, const OFBool check = OFTrue);
277 
278         /** set ContextGroupVersion (0008,0106)
279          *  @param  value  value to be set (single value only) or "" for no value
280          *  @param  check  check 'value' for conformance with VR (DT) and VM (1) if enabled
281          *  @return status, EC_Normal if successful, an error code otherwise
282          */
283         OFCondition setContextGroupVersion(const OFString &value, const OFBool check = OFTrue);
284 
285         /** set ContextIdentifier (0008,010f)
286          *  @param  value  value to be set (single value only) or "" for no value
287          *  @param  check  check 'value' for conformance with VR (CS) and VM (1) if enabled
288          *  @return status, EC_Normal if successful, an error code otherwise
289          */
290         OFCondition setContextIdentifier(const OFString &value, const OFBool check = OFTrue);
291 
292         /** set ContextUID (0008,0117)
293          *  @param  value  value to be set (single value only) or "" for no value
294          *  @param  check  check 'value' for conformance with VR (UI) and VM (1) if enabled
295          *  @return status, EC_Normal if successful, an error code otherwise
296          */
297         OFCondition setContextUID(const OFString &value, const OFBool check = OFTrue);
298 
299         /** set LongCodeValue (0008,0119)
300          *  @param  value  value to be set (single value only) or "" for no value
301          *  @param  check  check 'value' for conformance with VR (UC) and VM (1) if enabled
302          *  @return status, EC_Normal if successful, an error code otherwise
303          */
304         OFCondition setLongCodeValue(const OFString &value, const OFBool check = OFTrue);
305 
306         /** set MappingResource (0008,0105)
307          *  @param  value  value to be set (single value only) or "" for no value
308          *  @param  check  check 'value' for conformance with VR (CS) and VM (1) if enabled
309          *  @return status, EC_Normal if successful, an error code otherwise
310          */
311         OFCondition setMappingResource(const OFString &value, const OFBool check = OFTrue);
312 
313         /** set MappingResourceName (0008,0122)
314          *  @param  value  value to be set (single value only) or "" for no value
315          *  @param  check  check 'value' for conformance with VR (LO) and VM (1) if enabled
316          *  @return status, EC_Normal if successful, an error code otherwise
317          */
318         OFCondition setMappingResourceName(const OFString &value, const OFBool check = OFTrue);
319 
320         /** set MappingResourceUID (0008,0118)
321          *  @param  value  value to be set (single value only) or "" for no value
322          *  @param  check  check 'value' for conformance with VR (UI) and VM (1) if enabled
323          *  @return status, EC_Normal if successful, an error code otherwise
324          */
325         OFCondition setMappingResourceUID(const OFString &value, const OFBool check = OFTrue);
326 
327         /** set URNCodeValue (0008,0120)
328          *  @param  value  value to be set (single value only) or "" for no value
329          *  @param  check  check 'value' for conformance with VR (UR) and VM (1) if enabled
330          *  @return status, EC_Normal if successful, an error code otherwise
331          */
332         OFCondition setURNCodeValue(const OFString &value, const OFBool check = OFTrue);
333 
334       private:
335 
336         /// internal flag used to mark the empty default item
337         /*const*/ OFBool EmptyDefaultItem;
338 
339         /// CodeMeaning (0008,0104) vr=LO, vm=1, type=1
340         DcmLongString CodeMeaning;
341         /// CodeValue (0008,0100) vr=SH, vm=1, type=1C
342         DcmShortString CodeValue;
343         /// CodingSchemeDesignator (0008,0102) vr=SH, vm=1, type=1C
344         DcmShortString CodingSchemeDesignator;
345         /// CodingSchemeVersion (0008,0103) vr=SH, vm=1, type=1C
346         DcmShortString CodingSchemeVersion;
347         /// ContextGroupExtensionCreatorUID (0008,010d) vr=UI, vm=1, type=1C
348         DcmUniqueIdentifier ContextGroupExtensionCreatorUID;
349         /// ContextGroupExtensionFlag (0008,010b) vr=CS, vm=1, type=3
350         DcmCodeString ContextGroupExtensionFlag;
351         /// ContextGroupLocalVersion (0008,0107) vr=DT, vm=1, type=1C
352         DcmDateTime ContextGroupLocalVersion;
353         /// ContextGroupVersion (0008,0106) vr=DT, vm=1, type=1C
354         DcmDateTime ContextGroupVersion;
355         /// ContextIdentifier (0008,010f) vr=CS, vm=1, type=3
356         DcmCodeString ContextIdentifier;
357         /// ContextUID (0008,0117) vr=UI, vm=1, type=3
358         DcmUniqueIdentifier ContextUID;
359         /// EquivalentCodeSequence (0008,0121) vr=SQ, vm=1, type=3
360         DRTEquivalentCodeSequence EquivalentCodeSequence;
361         /// LongCodeValue (0008,0119) vr=UC, vm=1, type=1C
362         DcmUnlimitedCharacters LongCodeValue;
363         /// MappingResource (0008,0105) vr=CS, vm=1, type=1C
364         DcmCodeString MappingResource;
365         /// MappingResourceName (0008,0122) vr=LO, vm=1, type=3
366         DcmLongString MappingResourceName;
367         /// MappingResourceUID (0008,0118) vr=UI, vm=1, type=3
368         DcmUniqueIdentifier MappingResourceUID;
369         /// ProtocolContextSequence (0040,0440) vr=SQ, vm=1, type=3
370         DRTProtocolContextSequence ProtocolContextSequence;
371         /// URNCodeValue (0008,0120) vr=UR, vm=1, type=1C
372         DcmUniversalResourceIdentifierOrLocator URNCodeValue;
373 
374     };
375 
376   // --- constructors, destructor and operators ---
377 
378     /** (default) constructor
379      *  @param emptyDefaultSequence internal flag used to mark the empty default sequence
380      */
381     DRTScheduledProtocolCodeSequence(const OFBool emptyDefaultSequence = OFFalse);
382 
383     /** copy constructor
384      *  @param copy sequence object to be copied
385      */
386     DRTScheduledProtocolCodeSequence(const DRTScheduledProtocolCodeSequence &copy);
387 
388     /** destructor
389      */
390     virtual ~DRTScheduledProtocolCodeSequence();
391 
392     /** assigment operator
393      *  @param copy sequence object to be copied
394      *  @return reference to this object
395      */
396     DRTScheduledProtocolCodeSequence &operator=(const DRTScheduledProtocolCodeSequence &copy);
397 
398   // --- general methods ---
399 
400     /** clear all internal member variables
401      */
402     void clear();
403 
404     /** check if sequence is empty
405      *  @return OFTrue if sequence is empty, OFFalse otherwise
406      */
407     OFBool isEmpty();
408 
409     /** check if sequence is valid, i.e.\ not the empty default sequence
410      *  @return OFTrue if sequence is valid, OFFalse otherwise
411      */
412     OFBool isValid() const;
413 
414     /** get number of items in the sequence
415      *  @return number of items
416      */
417     size_t getNumberOfItems() const;
418 
419     /** goto first item in the sequence
420      *  @return status, EC_Normal if successful, an error code otherwise
421      */
422     OFCondition gotoFirstItem();
423 
424     /** goto next item in the sequence
425      *  @return status, EC_Normal if successful, an error code otherwise
426      */
427     OFCondition gotoNextItem();
428 
429     /** goto particular item in the sequence
430      *  @param  num  number of the item to be selected (0..num-1)
431      *  @return status, EC_Normal if successful, an error code otherwise
432      */
433     OFCondition gotoItem(const size_t num);
434 
435     /** get current item in the sequence
436      *  @param  item  reference to item pointer (result variable)
437      *  @return status, EC_Normal if successful, an error code otherwise
438      */
439     OFCondition getCurrentItem(Item *&item) const;
440 
441     /** get current item in the sequence
442      *  @return reference to specified item if successful, empty default item otherwise
443      */
444     Item &getCurrentItem();
445 
446     /** get current item in the sequence
447      *  @return const reference to specified item if successful, empty default item otherwise
448      */
449     const Item &getCurrentItem() const;
450 
451     /** get particular item in the sequence
452      *  @param  num   number of the item to be retrieved (0..num-1)
453      *  @param  item  reference to item pointer (result variable)
454      *  @return status, EC_Normal if successful, an error code otherwise
455      */
456     OFCondition getItem(const size_t num, Item *&item);
457 
458     /** get particular item in the sequence
459      *  @param  num  number of the item to be retrieved (0..num-1)
460      *  @return reference to specified item if successful, empty default item otherwise
461      */
462     Item &getItem(const size_t num);
463 
464     /** get particular item in the sequence
465      *  @param  num  number of the item to be retrieved (0..num-1)
466      *  @return const reference to specified item if successful, empty default item otherwise
467      */
468     const Item &getItem(const size_t num) const;
469 
470     /** get particular item in the sequence
471      *  @param  num  number of the item to be retrieved (0..num-1)
472      *  @return reference to specified item if successful, empty default item otherwise
473      */
474     Item &operator[](const size_t num);
475 
476     /** get particular item in the sequence
477      *  @param  num  number of the item to be retrieved (0..num-1)
478      *  @return const reference to specified item if successful, empty default item otherwise
479      */
480     const Item &operator[](const size_t num) const;
481 
482     /** add new item to the end of this sequence
483      *  @param  item  reference to new item pointer (result variable)
484      *  @return status, EC_Normal if successful, an error code otherwise
485      */
486     OFCondition addItem(Item *&item);
487 
488     /** insert new item into the sequence
489      *  @param  pos   position where the new item is to be inserted (0..num)
490      *  @param  item  reference to new item pointer (result variable)
491      *  @return status, EC_Normal if successful, an error code otherwise
492      */
493     OFCondition insertItem(const size_t pos, Item *&item);
494 
495     /** remove particular item from the sequence
496      *  @param  pos  position of the item to be removed (0..num-1)
497      *  @return status, EC_Normal if successful, an error code otherwise
498      */
499     OFCondition removeItem(const size_t pos);
500 
501   // --- input/output methods ---
502 
503     /** read sequence of items from dataset
504      *  @param  dataset     reference to DICOM dataset from which the sequence should be read
505      *  @param  card        cardinality (valid range for number of items)
506      *  @param  type        value type (valid value: "1", "1C", "2" or something else which is not checked)
507      *  @param  moduleName  optional module/sequence name to be printed (default: "RT object" if NULL)
508      *  @return status, EC_Normal if successful, an error code otherwise
509      */
510     OFCondition read(DcmItem &dataset,
511                      const OFString &card,
512                      const OFString &type,
513                      const char *moduleName = NULL);
514 
515     /** write sequence of items to dataset
516      *  @param  dataset     reference to DICOM dataset to which the sequence should be written
517      *  @param  card        cardinality (valid range for number of items)
518      *  @param  type        value type (valid value: "1", "2" or something else which is not checked)
519      *  @param  moduleName  optional module/sequence name to be printed (default: "RT object" if NULL)
520      *  @return status, EC_Normal if successful, an error code otherwise
521      */
522     OFCondition write(DcmItem &dataset,
523                       const OFString &card,
524                       const OFString &type,
525                       const char *moduleName = NULL);
526 
527   protected:
528 
529     /** goto particular item in the sequence
530      *  @param  num       number of the item to be selected (0..num-1)
531      *  @param  iterator  list iterator storing the position of the item
532      *  @return status, EC_Normal if successful, an error code otherwise
533      */
534     OFCondition gotoItem(const size_t num,
535                          OFListIterator(Item *) &iterator);
536 
537     /** goto particular item in the sequence
538      *  @param  num       number of the item to be selected (0..num-1)
539      *  @param  iterator  list iterator storing the position of the item
540      *  @return status, EC_Normal if successful, an error code otherwise
541      */
542     OFCondition gotoItem(const size_t num,
543                          OFListConstIterator(Item *) &iterator) const;
544 
545   private:
546 
547     /// internal flag used to mark the empty default sequence
548     /*const*/ OFBool EmptyDefaultSequence;
549 
550     /// list of items in this sequence
551     OFList<Item *>         SequenceOfItems;
552     /// currently selected item
553     OFListIterator(Item *) CurrentItem;
554     /// empty default item
555     Item                   EmptyItem;
556 
557 };
558 
559 
560 #endif
561