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 */