Don't use PCRE if we have GRegex.
[obnox/wireshark/wip.git] / idl / tango.idl
1
2
3 /**
4  * This is the new TACO interface defined in IDL. New TACO (or TANGO)
5  * is a total rethink of (old) TACO which was based on remote procedure
6  * calls. 
7  * TANGO is an extension of old TACO.
8  * The fundamental idea of a device as a network object which
9  * has methods and data has been retained. However 
10  * in TANGO objects will be real C++/Java objects which can be instantiated
11  * and accessed via their methods and data by the client as if they were local
12  * objects. 
13  * Certain aspects of the old DSAPI application programmer's 
14  * interface have been suppressed in order to simplify the client (e.g. import,
15  * free, data collector api). 
16  * Features which have been considered missing in old TACO have been added 
17  * e.g. signals, events and groups. 
18  * Asynchronism and groups have been foreseen right from the beginning 
19  * this time. 
20  * This interface is defined in CORBA IDL.
21  * The fundamental interface is Device. 
22  * All TANGO control objects will be of this type i.e. they will implement and
23  * offer the Device interface. 
24  * New classes of control objects e.g. PowerSupply, will be created by 
25  * wrapping the Device class appropriately. 
26  * The wrapper class will hide the calls to the Device interface from
27  * the client so that the client will only see the wrapper class.
28  * All CORBA details will be hidden from the client as far as possible.
29  * Generic clients will use the Device interface directly.
30  * In addition to Device TANGO offers the interfaces Monitor,
31  * GroupDevice and GroupSignal.
32  * These interfaces implement TANGO services for monitoring and 
33  * executing grouped accesses to device/signals.<BR><BR>
34  * Version history: <BR>
35  * 20/08/98 : 1.1 : First official release<BR>
36  * 18/08/99 : 2.0 : Separe idl and pseudo-idl<BR>
37  * 08/09/99 : 2.1 : Remove the applet attribute and the initiliase and serialise operation from the device interface<BR>
38  * 15/09/99 : 2.2 : Adapted to the ICALEPS show<BR>
39  * 06/12/99 : 2.3 : Less possible state and add strings in the DevCmdInfo struct<BR>
40  * 31/01/00 : 2.4 : Update DevVarCharArray to array of octet<BR>
41  * 10/02/00 : 2.5 : Updated all attribute related stuff<BR>
42  * 21/03/00 : 2.6 : Change arguments for the write_attributes device operation<BR>
43  * 15/09/00 : 2.7 : Change arguments for the read_attributes operation. Remove the
44  *                  CORBA field of the ErrFacility enumeration.
45  *                  Replace the WARMUP state by INIT.
46  *                  Change name of the dim_x and dim_y fields of the 
47  *                  AttributeConfig structure to max_dim_x and max_dim_y<BR>
48  * 27/09/00 : 2.8 : Change the writable field type of the AttributeConfig structure<BR>
49  * 26/10/00 : 2.9 : Change the DevError structure fields<BR>
50  * 12/02/01 : 2.10 : Change in the ErrSeverity enum. Windows does not like enum member like ERROR<BR>
51  * 14/02/01 : 2.11 : Another change in the ErrSeverity enum. WARNING is now WARN<BR>
52  * 23/03/01 : 2.12 : Add a new attribute in the Device interface called adm_name<BR>
53  * 26/10/01 : 3.0 : Add a new Device interface version using inheritance<BR>
54  * Add a new parameter to command_inout operation<BR>
55  * Add the command and attribute display level in command and attribute config structure<BR>
56  * Add a new call to get command or attribute cache history<BR>
57  * 06/04/02 : 2.0 : Update release number to be coherent with the real Tango software release number<BR>
58
59 @author JM.Chaize,<BR>A.Gotz,<BR>W-D.Klotz,<BR>J.Meyer,<BR>E.Taurel
60 @version 2.0
61 **/ 
62
63 module Tango
64 {
65
66 //-------------------------------------------------------------------------
67 //
68 //              Include all types, struct.... definition file
69 //
70 //-------------------------------------------------------------------------
71
72
73
74 //-------------------------------------------------------------------------
75 //
76 //              Basic types to transport command data
77 //
78 //-------------------------------------------------------------------------
79
80 typedef boolean                         DevBoolean;
81 typedef double                          DevDouble;
82 typedef float                           DevFloat;
83 typedef long                            DevLong;
84 typedef short                           DevShort;
85 typedef string                          DevString;
86 typedef octet                           DevUChar;
87 typedef unsigned long                   DevULong;
88 typedef unsigned short                  DevUShort;
89 typedef sequence<float>                 DevVarFloatArray;
90 typedef sequence<double>                DevVarDoubleArray;
91 typedef sequence<short>                 DevVarShortArray;
92 typedef sequence<long>                  DevVarLongArray;
93 typedef sequence<octet>                 DevVarCharArray;
94 typedef sequence<string>                DevVarStringArray;
95 typedef sequence<unsigned short>        DevVarUShortArray;
96 typedef sequence<unsigned long>         DevVarULongArray;
97 typedef sequence<boolean>               DevVarBooleanArray;
98
99 struct DevVarLongStringArray
100 {
101         DevVarLongArray         lvalue;
102         DevVarStringArray       svalue;
103 };
104
105 struct DevVarDoubleStringArray
106 {
107         DevVarDoubleArray       dvalue;
108         DevVarStringArray       svalue;
109 };
110
111
112 //-------------------------------------------------------------------------
113 //
114 //              Some enumerations
115 //
116 //-------------------------------------------------------------------------
117
118
119 enum AttrQuality
120 {
121         ATTR_VALID,
122         ATTR_INVALID,
123         ATTR_ALARM,
124         ATTR_CHANGING,
125         ATTR_WARNING
126 };
127
128 enum AttrWriteType
129 {
130         READ,
131         READ_WITH_WRITE,
132         WRITE,
133         READ_WRITE
134 };
135                 
136 enum AttrDataFormat
137 {
138         SCALAR,
139         SPECTRUM,
140         IMAGE
141 };
142
143 enum DevSource
144 {
145         DEV,
146         CACHE,
147         CACHE_DEV
148 };
149
150 enum ErrSeverity
151 {
152         WARN,
153         ERR,
154         PANIC
155 };
156
157 enum DevState
158 {
159         ON,
160         OFF,
161         CLOSE,
162         OPEN,
163         INSERT,
164         EXTRACT,
165         MOVING,
166         STANDBY,
167         FAULT,
168         INIT,
169         RUNNING,
170         ALARM,
171         DISABLE,
172         UNKNOWN
173 };      
174
175 enum DispLevel
176 {
177         OPERATOR,
178         EXPERT
179 };
180
181
182 //-------------------------------------------------------------------------
183 //      
184 //               Some  miscellaneous structures definitions
185 //
186 //-------------------------------------------------------------------------     
187         
188 struct TimeVal 
189 {
190         long    tv_sec;
191         long    tv_usec;
192         long    tv_nsec;
193 };
194
195
196 //-------------------------------------------------------------------------
197 //      
198 //              For the command query device operation 
199 //
200 //-------------------------------------------------------------------------
201
202
203 struct DevCmdInfo
204 {
205         string  cmd_name;
206         long    cmd_tag;
207         long    in_type;
208         long    out_type;
209         string  in_type_desc;
210         string  out_type_desc;
211 };
212
213 struct DevCmdInfo_2
214 {
215         string          cmd_name;
216         DispLevel       level;
217         long            cmd_tag;
218         long            in_type;
219         long            out_type;
220         string          in_type_desc;
221         string          out_type_desc;
222 };
223
224 typedef sequence<DevCmdInfo> DevCmdInfoList;
225 typedef sequence<DevCmdInfo_2> DevCmdInfoList_2;
226
227
228 //-------------------------------------------------------------------------
229 //
230 //              For the DevFailed exceptions
231 //
232 //-------------------------------------------------------------------------
233
234 struct DevError
235 {
236         string          reason;
237         ErrSeverity     severity;
238         string          desc;
239         string          origin;
240 };                      
241
242 typedef sequence<DevError> DevErrorList;
243
244 struct NamedDevError
245 {
246         string          name;
247         long            index_in_call;
248         DevErrorList    err_list;
249 };
250
251 typedef sequence<NamedDevError> NamedDevErrorList;
252
253
254 exception DevFailed
255 {
256         DevErrorList errors;
257 };
258
259 exception MultiDevFailed
260 {
261         NamedDevErrorList errors;
262 };
263
264
265 //-------------------------------------------------------------------------
266 //      
267 //              For attribute management
268 //
269 //-------------------------------------------------------------------------
270
271
272 struct AttributeConfig
273 {
274         string                  name;
275         AttrWriteType           writable;
276         AttrDataFormat          data_format;
277         long                    data_type;
278         long                    max_dim_x;
279         long                    max_dim_y;
280         string                  description;
281         string                  label;
282         string                  unit;
283         string                  standard_unit;
284         string                  display_unit;
285         string                  format;
286         string                  min_value;
287         string                  max_value;
288         string                  min_alarm;
289         string                  max_alarm;
290         string                  writable_attr_name;
291         DevVarStringArray       extensions;     
292 };
293
294 struct AttributeConfig_2
295 {
296         string                  name;
297         AttrWriteType           writable;
298         AttrDataFormat          data_format;
299         long                    data_type;
300         long                    max_dim_x;
301         long                    max_dim_y;
302         string                  description;
303         string                  label;
304         string                  unit;
305         string                  standard_unit;
306         string                  display_unit;
307         string                  format;
308         string                  min_value;
309         string                  max_value;
310         string                  min_alarm;
311         string                  max_alarm;
312         string                  writable_attr_name;
313         DispLevel               level;
314         DevVarStringArray       extensions;     
315 };
316
317 struct AttributeValue
318 {
319         any             value;
320         AttrQuality     quality;
321         TimeVal         time;
322         string          name;
323         long            dim_x;
324         long            dim_y;
325 };
326
327 struct AttributeDim
328 {
329         long dim_x;
330         long dim_y;
331 };
332
333 struct AttributeValue_3
334 {
335         any             value;
336         AttrQuality     quality;
337         TimeVal         time;
338         string          name;
339         AttributeDim    r_dim;
340         AttributeDim    w_dim;
341         DevErrorList    err_list;
342 };
343
344 struct ChangeEventProp
345 {
346         string                  rel_change;
347         string                  abs_change;
348         DevVarStringArray       extensions;     
349 };
350
351 struct PeriodicEventProp
352 {
353         string                  period;
354         DevVarStringArray       extensions;     
355 };
356
357 struct ArchiveEventProp
358 {
359         string                  rel_change;
360         string                  abs_change;
361         string                  period;
362         DevVarStringArray       extensions;     
363 };
364
365 struct EventProperties
366 {
367         ChangeEventProp         ch_event;
368         PeriodicEventProp       per_event;
369         ArchiveEventProp        arch_event;
370 };
371
372 struct AttributeAlarm
373 {
374         string                  min_alarm;
375         string                  max_alarm;
376         string                  min_warning;
377         string                  max_warning;
378         string                  delta_t;
379         string                  delta_val;
380         DevVarStringArray       extensions;     
381 };
382
383 struct AttributeConfig_3
384 {
385         string                  name;
386         AttrWriteType           writable;
387         AttrDataFormat          data_format;
388         long                    data_type;
389         long                    max_dim_x;
390         long                    max_dim_y;
391         string                  description;
392         string                  label;
393         string                  unit;
394         string                  standard_unit;
395         string                  display_unit;
396         string                  format;
397         string                  min_value;
398         string                  max_value;
399         string                  writable_attr_name;
400         DispLevel               level;
401         AttributeAlarm          att_alarm;
402         EventProperties         event_prop;     
403         DevVarStringArray       extensions;
404         DevVarStringArray       sys_extensions;
405 };
406
407 typedef sequence<AttributeConfig> AttributeConfigList;
408 typedef sequence<AttributeConfig_2> AttributeConfigList_2;
409 typedef sequence<AttributeConfig_3> AttributeConfigList_3;
410 typedef sequence<AttributeValue> AttributeValueList;
411 typedef sequence<AttributeValue_3> AttributeValueList_3;
412
413
414 //-------------------------------------------------------------------------
415 //
416 //              For device interface info operation
417 //
418 //-------------------------------------------------------------------------
419
420 struct DevInfo
421 {
422         string  dev_class;
423         string  server_id;
424         string  server_host;
425         long    server_version;
426         string  doc_url;
427 };
428
429 struct DevInfo_3
430 {
431         string  dev_class;
432         string  server_id;
433         string  server_host;
434         long    server_version;
435         string  doc_url;
436         string  dev_type;
437 };
438
439 //-------------------------------------------------------------------------
440 //
441 //              For command and attribute history
442 //
443 //-------------------------------------------------------------------------
444
445 struct DevCmdHistory
446 {
447         TimeVal         time;
448         boolean         cmd_failed;
449         any             value;
450         DevErrorList    errors;
451 };
452
453 typedef sequence<DevCmdHistory> DevCmdHistoryList;
454
455 struct DevAttrHistory
456 {
457         boolean         attr_failed;
458         AttributeValue  value;
459         DevErrorList    errors;
460 };
461
462 struct DevAttrHistory_3
463 {
464         boolean                 attr_failed;
465         AttributeValue_3        value;
466 };
467
468 typedef sequence<DevAttrHistory>        DevAttrHistoryList;
469 typedef sequence<DevAttrHistory_3>      DevAttrHistoryList_3;
470
471 //-------------------------------------------------------------------------
472 //
473 //              Include the device interface
474 //
475 //-------------------------------------------------------------------------
476
477
478
479
480
481 /**
482  * The fundamental interface for all TANGO objects.
483  * Each Device is a network object which can be accessed locally or via
484  * network.
485  * The network protocol on the wire will be IIOP.
486  * The Device interface implements all the basic functions needed for doing
487  * generic synchronous and asynchronous I/O on a device.
488  * A Device object has data and actions. 
489  * Data are represented in the form of Attributes.
490  * Actions are represented in the form of Commands.
491  * The CORBA Device interface offers attributes and methods to access
492  * the attributes and commands.
493  * A client will either use these methods directly from C++ or Java or access
494  * them via a wrapper class.
495  * The Device interface describes only the remote network interface.
496  * Implementation features like threads, command security, priority
497  * etc. are dealt with in server side of the device server model.
498  **/
499
500 interface Device
501 {
502
503 /**
504  * name (readonly) - unique ascii identifier
505  **/
506         readonly attribute string name;
507 /**
508  * description (readonly) - general description of device
509  **/
510         readonly attribute string description;
511 /**
512  * state (readonly) - device state 
513  **/
514         readonly attribute DevState state;
515 /**
516  * status (readonly) - device state as ascii string
517  **/
518         readonly attribute string status;
519 /**
520  * adm_name (readonly) - administrator device unique ascii identifier
521  **/
522         readonly attribute string adm_name;
523
524 /**
525  * execute a command on a device synchronously with
526  * one input parameter and one output parameter
527 @param command ascii string e.g. "On"
528 @param argin command input parameter e.g. float
529 @return command result.
530  **/
531         any command_inout(in string command, in any argin) raises(DevFailed);
532         
533         
534 /**
535  * read the configuration for a variable list of attributes from a device
536 @param name list of attribute names to read
537 @return list of attribute configurations read
538  **/
539         AttributeConfigList get_attribute_config(in DevVarStringArray names) raises(DevFailed);
540
541
542 /**
543  * set the configuration for a variable list of attributes from the device
544 @param new_conf list of attribute configuration to be set
545 @return nothing
546  **/
547         void set_attribute_config(in AttributeConfigList new_conf) raises(DevFailed);
548         
549         
550 /**
551  * read a variable list of attributes from a device
552 @param name list of attribute names to read
553 @return list of attribute values read
554  **/
555         AttributeValueList read_attributes(in DevVarStringArray names) raises(DevFailed);
556
557
558
559 /**
560  * write a variable list of attributes to a device
561 @param values list of attribute values to write
562 @return nothing
563  **/
564         void write_attributes(in AttributeValueList values) raises(DevFailed);
565
566 /**
567  * ping a device to see if it alive
568  **/
569         void ping() raises(DevFailed);
570
571 /**
572  * read list of last N commands executed by clients
573 @param number of commands to return
574 @return list of command and clients
575  **/
576         DevVarStringArray black_box(in long n) raises(DevFailed);
577         
578
579 /**
580  * return general information about object e.g. class, type, ... 
581 @return device info
582  **/
583         DevInfo info() raises(DevFailed);
584         
585         
586 /**
587  * query device to see what commands it supports
588 @return list of commands and their types
589  **/
590         DevCmdInfoList command_list_query() raises(DevFailed);
591         
592         
593 /**
594  * query device to see command argument
595 @return command and its types
596 @param command name
597  **/
598         DevCmdInfo command_query(in string command) raises(DevFailed);
599
600 };
601         
602 /**
603  * A new release of the basic Device interface.
604  * This new release has been introduced mainly to support Tango device server
605  * internal polling. Inheritance is used between this new release and the
606  * old one. This release mainly defines a new release of the command_inout and 
607  * read_attributes calls with a new parameter. It also add a new call to read
608  * command or attributes result history.
609  **/
610  
611 interface Device_2: Device
612 {
613 /**
614  * Execute a command on a device synchronously with
615  * one input parameter and one output parameter
616 @param command ascii string e.g. "On"
617 @param argin command input parameter e.g. float
618 @param source The data source. Used to specify if the command result must be 
619 read from the polling cache buffer or from the device itself
620 @return command result.
621  **/
622         any command_inout_2(in string command,
623                             in any argin,
624                             in DevSource source) raises(DevFailed);
625
626 /**
627  * Read a variable list of attributes from a device
628 @param name list of attribute names to read
629 @param source The data source. Used to specify if the command result must be 
630 read from the polling cache buffer or from the device itself
631 @return list of attribute values read
632  **/
633         AttributeValueList read_attributes_2(in DevVarStringArray names,
634                                              in DevSource source) raises(DevFailed);
635
636 /**
637  * Read the configuration for a variable list of attributes from a device.
638  * Compared to the Device interface, the attribute configuration has one more
639  * field (The display level)
640 @param name list of attribute names to read
641 @return list of attribute configurations read
642  **/                                                               
643         AttributeConfigList_2 get_attribute_config_2(in DevVarStringArray names) raises(DevFailed);
644
645 /**
646  * Query device to see what commands it supports.
647  * Compared to the Device interface, the command configuration has one more
648  * field (The display level)
649 @return list of commands and their types
650  **/
651         DevCmdInfoList_2 command_list_query_2() raises(DevFailed);
652
653 /**
654  * Query device to see command argument.
655  * Compared to the Device interface, the command configuration has one more
656  * field (The display level)
657 @return command and its types
658 @param command name
659  **/    
660         DevCmdInfo_2 command_query_2(in string command) raises(DevFailed);
661
662 /**
663  * Get command history buffer.
664  * Return command result history for polled command
665 @param command ascii string e.g. "On"
666 @param n The history depth
667 @return command history.
668  **/    
669         DevCmdHistoryList command_inout_history_2(in string command,
670                                                   in long n) raises (DevFailed);
671
672 /**
673  * Get attribute value history buffer.
674  * Return attribute value history for polled attribute
675 @param name ascii string
676 @param n The history depth
677 @return attribute value history.
678  **/                                              
679         DevAttrHistoryList read_attribute_history_2(in string name,
680                                                     in long n) raises (DevFailed);
681 };
682
683
684 interface Device_3: Device_2
685 {
686
687 /**
688  * Read a variable list of attributes from a device
689 @param name list of attribute names to read
690 @param source The data source. Used to specify if the command result must be 
691 read from the polling cache buffer or from the device itself
692 @return list of attribute values read
693  **/
694         AttributeValueList_3 read_attributes_3(in DevVarStringArray names,
695                                                in DevSource source) raises(DevFailed);
696
697 /**
698  * write a variable list of attributes to a device
699 @param values list of attribute values to write
700 @return nothing
701  **/
702         void write_attributes_3(in AttributeValueList values) raises(DevFailed,MultiDevFailed);
703 /**
704  * Get attribute value history buffer.
705  * Return attribute value history for polled attribute
706 @param name ascii string
707 @param n The history depth
708 @return attribute value history.
709  **/                                              
710         DevAttrHistoryList_3 read_attribute_history_3(in string name,
711                                                       in long n) raises (DevFailed);
712
713 /**
714  * return general information about object e.g. class, type, ... 
715 @return device info
716  **/
717         DevInfo_3 info_3() raises(DevFailed);
718
719 /**
720  * Read the configuration for a variable list of attributes from a device.
721  * Compared to the Device interface, the attribute configuration has one more
722  * field (The display level)
723 @param name list of attribute names to read
724 @return list of attribute configurations read
725  **/                                                               
726         AttributeConfigList_3 get_attribute_config_3(in DevVarStringArray names) raises(DevFailed);
727
728 /**
729  * set the configuration for a variable list of attributes from the device
730 @param new_conf list of attribute configuration to be set
731 @return nothing
732  **/
733         void set_attribute_config_3(in AttributeConfigList_3 new_conf) raises(DevFailed);
734 };
735
736 };  /* module tango */