path: root/TAO/orbsvcs/orbsvcs/AVStreams.idl

/* -*- C++ -*- */

// $Id$

// ============================================================================
//
// = LIBRARY
//    cos
// 
// = FILENAME
//   AVStreams.idl
//
// = AUTHOR
//    OMG
//    
// 
// ============================================================================

#include "CosPropertyService.idl"

module AVStreams
// = DESCRIPTION
//    IDL for Control and Management of Audio/Video Streams
//    Revised Submission
{
  struct QoS
    // This structure represents QoS for a given type.
    // E.g. {"video_qos", <"video_framerate", 26>,
    //                    <"video_depth", 9>}
  {
    string QoSType;
    // Name of the Qos type, e.g. "video_qos"
    string QoSParams;
    // @@
    //    CosPropertyService::Properties QoSParams;
    // Sequence of name value pairs, see e.g. above.
  };
  
  typedef sequence<QoS> streamQoS;
  // The QoS of a stream is a sequence of QoS structs (defined above)
  
  typedef sequence<string> flowSpec;
  // flowSpec is used to keep transport protocol information
  // Each string is one endpoint. 
  
  typedef sequence<string> protocolSpec;
  // List of protocols supported
  // protocol names registered by OMG.
  // e.g., TCP, UDP, AAL5, IPX, RTP

  typedef sequence<octet> encryption_key;
  // Used as a key for public-key encryption

  struct SFPStatus
    // This structure is defined for SFP1.0
    // Subsequent versions of the protocol may
    // specify new structures
  {
    // = TITLE
    //   This structure is defined for SFP1.0 Subsequent versions of
    //   the protocol may specify new structures
    boolean isFormatted;
    boolean isSpecialFormat;
    boolean seqNums;
    boolean timestamps;
    boolean sourceIndicators;
  };

  enum flowState {stopped, started, dead};
  // represents the state of a flow

  enum dirType {dir_in, dir_out};
  // the direction of a flow

  struct flowStatus
    // Used to store the status of a flow
  {
    string flowName;
    dirType directionality;
    flowState status;
    SFPStatus theFormat;
    QoS theQoS;
  };

  // @@
  //  typedef CosPropertyService::Property streamEvent;
  typedef string streamEvent;
  // Used to convey events, in Basic_StreamCtrl::push_event
  
  exception notSupported {};
  // Used to indicate that an operation is not supported

  exception PropertyException {};
  // Property exception: raised by VDev::configure ()

  exception FPError { string flow_name; };
  // An flow protocol related error
  
  exception streamOpFailed
    // Raised by operations on streams
    {
      string reason;
    };

  exception streamOpDenied
    // Raised by operations on streams
    {
      string reason;
    };

  exception noSuchFlow {};
  // Used to indicate that an invalid flow name was used for the operation

  exception QoSRequestFailed
    //  Used to indicate failure in changing QoS
    {
      string reason;
    };

  // @@
  //  interface Basic_StreamCtrl : CosPropertyService::PropertySet {
  interface Basic_StreamCtrl 
    // = DESCRIPTION
    //    Base class for StreamCtrl, implements basic stream start
    //    and stop functionality
    {
      // Empty flowSpec => apply operation to all flows
      void stop (in flowSpec the_spec) raises (noSuchFlow);
      // Stop the transfer of data of the stream
      // Empty the_spec means apply operation to all flows
      
      void start (in flowSpec the_spec) raises (noSuchFlow);
      // Start the transfer of data in the stream.
      // Empty the_spec means apply operation to all flows
      
      void destroy (in flowSpec the_spec) raises (noSuchFlow);
      // Tears down the stream. This will close the connection, and delete
      // the streamendpoint and vdev associated with this stream
      // Empty the_spec means apply operation to all flows
      
      boolean modify_QoS (inout streamQoS new_qos,
                          in flowSpec the_spec)
        raises (noSuchFlow, 
                QoSRequestFailed);
      // Changes the QoS associated with the stream
      // Empty the_spec means apply operation to all flows
      
      oneway void push_event (in streamEvent the_event);
      // Called by StreamEndPoint when something goes wrong
      // with a flow
      
      void set_FPStatus (in flowSpec the_spec,
                         in string fp_name,		
                         in any fp_settings)		
        raises (noSuchFlow, 
                FPError);
      // Used to control the flow protocol parameters.
      
      
      Object get_flow_connection (in string flow_name) 
        raises (noSuchFlow, 
                notSupported);
      // Not implemented in the light profile, will raise the notsupported
      // exception
      
      
      void set_flow_connection (in string flow_name,
                                in Object flow_connection)
        raises (noSuchFlow, 
                notSupported);
    };
  // Not implemented in the light profile, will raise the notsupported
  // exception

  interface Negotiator
    // = DESCRIPTION
    //    This class is used to negotiate QoS between two stream endpoints
    {
      boolean negotiate (in Negotiator remote_negotiator,
                         in streamQoS qos_spec);
      // initiates the process of negotiating the qos_spec
    };

  // forward declarations
  interface VDev;
  interface MMDevice;
  interface StreamEndPoint;
  interface StreamEndPoint_A;
  interface StreamEndPoint_B;
  
  interface StreamCtrl : Basic_StreamCtrl 
    // = DESCRIPTION
    //    Implementation the A/V StreamCtrl class. this class
    //    is used to control the stream. It should be subclassed
    //    by applications that want to provide more control features.
    {
      
      boolean bind_devs (in MMDevice a_party, in MMDevice b_party,
                         inout streamQoS the_qos,
                         in flowSpec the_flows)
        raises (streamOpFailed, 
                noSuchFlow, 
                QoSRequestFailed);
      // Establish a stream between a_party and b_party,
      // with qos the_qos, and for the flows in the_flows
      // if the_flows is empty, bind all the flows
      // Causes a connection to be established between the StreamEndpoints.
      // Returns success/failure
      
      boolean bind (in StreamEndPoint_A a_party,
                    in StreamEndPoint_B b_party,
                    inout streamQoS the_qos,
                    in flowSpec the_flows)
        raises (streamOpFailed, 
                noSuchFlow, 
                QoSRequestFailed);
      // Establish a connection between two streamendpoints. This can
      // be used if the streamendpoints have been created independent of
      // a MMDevice
      
      void unbind_party (in StreamEndPoint the_ep,
                         in flowSpec the_spec)
        raises (streamOpFailed, noSuchFlow);
      // Unbind the_ep from the stream. Empty the_spec means apply to all flows.
      
      void unbind ()
        raises (streamOpFailed);
      // unbind the stream. Same effect as Basic_StreamCtrl::destroy ()
    };
  
  // @@
  //  interface MCastConfigIf : CosPropertyService::PropertySet{
  interface MCastConfigIf 
    // multicasting operations are not supported yet  
    {
      boolean set_peer (in Object peer,
                        inout streamQoS the_qos,
                        in flowSpec the_spec)
        raises (QoSRequestFailed, 
                streamOpFailed);
      // multicasting operations are not supported yet  
      
      void configure (in CosPropertyService::Property a_configuration);
      // multicasting operations are not supported yet  
      
      void set_initial_configuration (in CosPropertyService::Properties initial);
      // multicasting operations are not supported yet  
      
      // Uses <format_name> standardised by OMG and IETF
      void set_format (in string flowName, 
                       in string format_name)
        raises (notSupported);
      // multicasting operations are not supported yet  
      
      // Note, some of these device params are standardised by OMG
      void set_dev_params (in string flowName,
                           in CosPropertyService::Properties new_params)
        raises (CosPropertyService::PropertyException,
                streamOpFailed);
      // multicasting operations are not supported yet  
      
    };

  // @@
  //  interface StreamEndPoint : CosPropertyService::PropertySet{
  interface StreamEndPoint 
    // = DESCRIPTION
    //    The Stream EndPoint. Used to implement one endpoint of a stream
    //    that implements the transport layer.
    {
      void stop (in flowSpec the_spec) 
        raises (noSuchFlow);
      // Stop the stream. Empty the_spec means, for all the flows
      
      void start (in flowSpec the_spec) 
        raises (noSuchFlow);
      // Start the stream, Empty the_spec means, for all the flows
      
      void destroy (in flowSpec the_spec) 
        raises (noSuchFlow);
      // Destroy the stream, Empty the_spec means, for all the flows
      
      boolean connect (in StreamEndPoint responder,
                       inout streamQoS qos_spec,
                       in flowSpec the_spec)
        raises (noSuchFlow, 
                QoSRequestFailed, 
                streamOpFailed);
      // Called by StreamCtrl. responder is the peer to connect to
      
      boolean request_connection (in StreamEndPoint initiator,
                                  in boolean is_mcast,
                                  inout streamQoS qos,
                                  inout flowSpec the_spec)
        raises (streamOpDenied, noSuchFlow,
                QoSRequestFailed, FPError);
      // Called by the peer StreamEndPoint. The flow_spec indicates the
      // flows (which contain transport addresses etc.)
      
      boolean modify_QoS (inout streamQoS new_qos,
                          in flowSpec the_flows)
        raises (noSuchFlow, 
                QoSRequestFailed);
      // Change the transport qos on a stream
      
      boolean set_protocol_restriction (in protocolSpec the_pspec);
      // Used to restrict the set of protocols
      
      void disconnect(in flowSpec the_spec)
        raises (noSuchFlow, 
                streamOpFailed);
      // disconnect the flows
      
      void set_FPStatus (in flowSpec the_spec,
                         in string fp_name,
                         in any fp_settings)
        raises (noSuchFlow, 
                FPError);
      // Used to control the SFP parameters

      Object get_fep (in string flow_name)
        raises (notSupported, 
                noSuchFlow);
      // Not implemented in the light profile, throws notsupported
      
      string add_fep (in Object the_fep)
        // Can fail for reasons {duplicateFepName, duplicateRef}
        raises (notSupported, 
                streamOpFailed);
      // Not implemented in the light profile, throws notsupported
      
      void remove_fep (in string fep_name)
        raises (notSupported, 
                streamOpFailed);
      // Not implemented in the light profile, throws notsupported
      
      void set_negotiator (in Negotiator new_negotiator);
      // Used to "attach" a negotiator to the endpoint

      void set_key (in string flow_name, 
                    in encryption_key the_key);
      // Used for public key encryption.
    
      void set_source_id (in long source_id);
      // Used to set a unique id for packets sent by this streamendpoint
    };

  interface StreamEndPoint_A : StreamEndPoint
    // = DESCRIPTION
    //     The "A" side of a streamendpoint
    {

      boolean multiconnect (inout streamQoS the_qos,
                            inout flowSpec the_spec)
        raises (noSuchFlow, QoSRequestFailed, streamOpFailed);
      // Used for ATM-style multicast

      boolean connect_leaf (in StreamEndPoint_B the_ep,
                            inout streamQoS the_qos,
                            in flowSpec the_flows)
        raises (streamOpFailed, noSuchFlow,
                QoSRequestFailed, notSupported);
      // Used for ATM-style multicast

      void disconnect_leaf (in StreamEndPoint_B the_ep,
                            in flowSpec theSpec)
        raises(streamOpFailed, noSuchFlow);
      // Used for ATM-style multicast
    };

  interface StreamEndPoint_B : StreamEndPoint 
    {

      boolean multiconnect (inout streamQoS the_qos,
                            inout flowSpec the_spec)
        raises (streamOpFailed, noSuchFlow,
                QoSRequestFailed, FPError);
      // Used for ATM-style multicast
    };

  // @@
  //  interface VDev : CosPropertyService::PropertySet{
  interface VDev 
    // = DESCRIPTION
    //    Implements the VDev interface. One of these is created per connection,
    //    and represents device-specific parameters
    {
      boolean set_peer (in StreamCtrl the_ctrl,
                        in VDev the_peer_dev,
                        inout streamQoS the_qos,
                        in flowSpec the_spec)
        raises (noSuchFlow, 
                QoSRequestFailed, 
                streamOpFailed);
      // Called to tell the vdev who the streamctrl, peer vdev is

      boolean set_Mcast_peer (in StreamCtrl the_ctrl,
                              in MCastConfigIf a_mcastconfigif,
                              inout streamQoS the_qos,
                              in flowSpec the_spec)
        raises (noSuchFlow, 
                QoSRequestFailed, 
                streamOpFailed);
      // Used to set the streamctrl and multicast device

      void configure (in CosPropertyService::Property the_config_mesg)
        raises (PropertyException, 
                streamOpFailed);
      // Called by the peer VDev to configure the device (catch all)

      // Uses <formatName> standardised by OMG and IETF
      void set_format (in string flowName, 
                       in string format_name)
        raises (notSupported);
      // Used to set a format on a flowname

      // Note, some of these device params are standardised by OMG
      void set_dev_params (in string flowName,
                           in CosPropertyService::Properties new_params)
        raises (PropertyException, 
                streamOpFailed);
      // Used to set device parameters

      boolean modify_QoS (inout streamQoS the_qos,
                          in flowSpec the_spec)
        raises (noSuchFlow, 
                QoSRequestFailed);
      // Called to change QoS of the device

    };

  interface MMDevice : CosPropertyService::PropertySet 
    // = DESCRIPTION
    //     Implements a factory to create Endpoints and VDevs
    {
      StreamEndPoint_A create_A (in StreamCtrl the_requester,
                                 out VDev the_vdev,
                                 inout streamQoS the_qos,
                                 out boolean met_qos,
                                 inout string named_vdev,
                                 in flowSpec the_spec)
        raises (streamOpFailed, 
                streamOpDenied, 
                notSupported,
                QoSRequestFailed, 
                noSuchFlow);
      // Called by StreamCtrl to create a "A" type streamendpoint and vdev

      StreamEndPoint_B create_B(in StreamCtrl the_requester,
                                out VDev the_vdev,
                                inout streamQoS the_qos,
                                out boolean met_qos,
                                inout string named_vdev,
                                in flowSpec the_spec)
        raises (streamOpFailed, 
                streamOpDenied, 
                notSupported,
                QoSRequestFailed, 
                noSuchFlow);
      // Called by StreamCtrl to create a "B" type streamendpoint and vdev
    
      StreamCtrl bind (in MMDevice peer_device,
                       inout streamQoS the_qos,
                       out boolean is_met,
                       in flowSpec the_spec)
        raises (streamOpFailed, 
                noSuchFlow, 
                QoSRequestFailed);
      // Can be used to request the MMDevice to create a new StreamCtrl,
      // and call bind_devs on it
    
      StreamCtrl bind_mcast (in MMDevice first_peer,
                             inout streamQoS the_qos,
                             out boolean is_met,
                             in flowSpec the_spec)
        raises (streamOpFailed, 
                noSuchFlow, 
                QoSRequestFailed);
      // Multicast bind

      void destroy (in StreamEndPoint the_ep, 
                    in string vdev_name)
        // ie VDev not found
        raises (notSupported);
      // Remove the StreamEndPoint and the related vdev
     
      string add_fdev (in Object the_fdev)
        raises (notSupported, 
                streamOpFailed);
      // Not supported in the light profile, raises notsupported

      Object get_fdev (in string flow_name)
        raises (notSupported, 
                noSuchFlow);
      // Not supported in the light profile, raises notsupported

      void remove_fdev (in string flow_name)
        raises (notSupported, 
                noSuchFlow);
      // Not supported in the light profile, raises notsupported
    };
};