/* -*- C++ -*- */ // $Id$ // ============================================================================ // // = LIBRARY // cos // // = FILENAME // AVStreams.idl // // = AUTHOR // Sumedh Mungee and Nagarajan Surendran // // // ============================================================================ #ifndef TAO_AV_STREAMS_IDL #define TAO_AV_STREAMS_IDL #include "CosPropertyService.idl" #pragma prefix "omg.org" 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" CosPropertyService::Properties QoSParams; // Sequence of name value pairs, see e.g. above. }; typedef sequence streamQoS; // The QoS of a stream is a sequence of QoS structs (defined above) typedef sequence flowSpec; // flowSpec is used to keep transport protocol information Each // string is one endpoint. typedef sequence protocolSpec; // List of protocols supported protocol names registered by OMG. // e.g., TCP, UDP, AAL5, IPX, RTP typedef sequence key; // Used as a key for public-key encryption struct SFPStatus { // = TITLE // This structure is defined for SFP1.0 Subsequent versions of // the protocol may specify new structures // // = DESCRIPTION // 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 { // = TITLE // Used to store the status of a flow. string flowName; dirType directionality; flowState status; SFPStatus theFormat; QoS theQoS; }; typedef CosPropertyService::Property 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 { // An flow protocol related error. string flow_name; }; 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 { // = 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_dev(in MMDevice dev, in flowSpec the_spec) raises (streamOpFailed, noSuchFlow); 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 () VDev get_related_vdev(in MMDevice adev, out StreamEndPoint sep) raises (streamOpFailed); }; interface MCastConfigIf : CosPropertyService::PropertySet{ // = DESCRIPTION // Interface for multicasting operations. boolean set_peer (in Object peer, inout streamQoS the_qos, in flowSpec the_spec) raises (QoSRequestFailed, streamOpFailed); // Set a peer in the multicast tree. void configure (in CosPropertyService::Property a_configuration); // Configure the multicast stream. void set_initial_configuration (in CosPropertyService::Properties initial); // Sets the initial configuration to be used for all added peers. // Uses 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); raises (PropertyException, streamOpFailed); // Multicasting operations are not supported yet. }; interface StreamEndPoint : CosPropertyService::PropertySet{ // = 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 with. 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 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, notSupported); // 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 { // = 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 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, streamOpFailed); // Not supported in the light profile, raises notsupported. }; // Define the exceptions. exception protocolNotSupported{}; exception formatNotSupported{}; exception formatMismatch{}; exception FEPMismatch{}; exception alreadyConnected{}; exception invalidSettings{string settings;}; exception notConnected{}; exception deviceQosMismatch{}; exception failedToConnect{string reason;}; exception failedToListen{string reason;}; // Forward declarations of the interfaces. interface FlowProducer; interface FlowConsumer; interface FlowEndPoint; interface FDev; interface FlowConnection : CosPropertyService::PropertySet{ void stop(); void start(); void destroy(); boolean modify_QoS(inout AVStreams::QoS new_qos) raises (AVStreams::QoSRequestFailed); boolean use_flow_protocol(in string fp_name, in any fp_settings) raises (AVStreams::FPError, AVStreams::notSupported); oneway void push_event(in AVStreams::streamEvent the_event); boolean connect_devs(in FDev a_party, in FDev b_party, inout AVStreams::QoS the_qos) raises (AVStreams::streamOpFailed, AVStreams::streamOpDenied, AVStreams::QoSRequestFailed); boolean connect(in FlowProducer flow_producer, in FlowConsumer flow_consumer, inout AVStreams::QoS the_qos) raises (formatMismatch, FEPMismatch, alreadyConnected); boolean disconnect(); // The notSupported exception is raised where // flow cannot have multiple producers boolean add_producer(in FlowProducer flow_producer, inout AVStreams::QoS the_qos) raises (alreadyConnected, AVStreams::notSupported); boolean add_consumer(in FlowConsumer flow_consumer, inout AVStreams::QoS the_qos) raises (alreadyConnected); boolean drop(in FlowEndPoint target) raises (notConnected); }; interface FlowEndPoint : CosPropertyService::PropertySet { boolean lock(); void unlock(); void stop(); void start(); void destroy(); // Default is a nil object reference attribute AVStreams::StreamEndPoint related_sep; attribute FlowConnection related_flow_connection; FlowEndPoint get_connected_fep() raises (notConnected,AVStreams::notSupported); // syntax of fp_name is boolean use_flow_protocol(in string fp_name, in any fp_settings) raises (AVStreams::FPError, AVStreams::notSupported); // set_format() initializes ëformatí // as current media format e.g. MPEG. void set_format(in string format) raises (AVStreams::notSupported); void set_dev_params(in CosPropertyService::Properties new_settings) // raises (CosPropertyService::PropertyException, AVStreams::streamOpFailed); raises (PropertyException, AVStreams::streamOpFailed); void set_protocol_restriction(in AVStreams::protocolSpec the_spec) raises (AVStreams::notSupported); boolean is_fep_compatible(in FlowEndPoint fep) raises (formatMismatch, deviceQosMismatch); boolean set_peer(in FlowConnection the_fc, in FlowEndPoint the_peer_fep, inout AVStreams::QoS the_qos) raises (AVStreams::QoSRequestFailed, AVStreams::streamOpFailed); boolean set_Mcast_peer(in FlowConnection the_fc, in AVStreams::MCastConfigIf a_mcastconfigif, inout AVStreams::QoS the_qos) raises (AVStreams::QoSRequestFailed); boolean connect_to_peer(inout AVStreams::QoS the_qos, in string address, in string use_flow_protocol) // syntax raises(failedToConnect,AVStreams::FPError, AVStreams::QoSRequestFailed); // Needs to know its peer to choose its protocol correctly // Also to ask for a reverse channel for credit-based flow // control, if one is required string go_to_listen(inout AVStreams::QoS the_qos, in boolean is_mcast, in FlowEndPoint peer, inout string flowProtocol)// syntax // The out value of flowProtocol contains SFP version // supported and all options including "Credit". raises(failedToListen, AVStreams::FPError, AVStreams::QoSRequestFailed); }; interface FlowProducer : FlowEndPoint { string connect_mcast(inout AVStreams::QoS the_qos, out boolean is_met, in string address, in string use_flow_protocol) raises (failedToConnect, AVStreams::notSupported, AVStreams::FPError, AVStreams::QoSRequestFailed); string get_rev_channel(in string pcol_name); void set_key(in AVStreams::key the_key); void set_source_id(in long source_id); }; interface FlowConsumer : FlowEndPoint { }; interface FDev : CosPropertyService::PropertySet { FlowProducer create_producer(in FlowConnection the_requester, inout AVStreams::QoS the_qos, out boolean met_qos, inout string named_fdev) raises(AVStreams::streamOpFailed, AVStreams::streamOpDenied, AVStreams::notSupported, AVStreams::QoSRequestFailed); FlowConsumer create_consumer(in FlowConnection the_requester, inout AVStreams::QoS the_qos, out boolean met_qos, inout string named_fdev) raises(AVStreams::streamOpFailed, AVStreams::streamOpDenied, AVStreams::notSupported, AVStreams::QoSRequestFailed); FlowConnection bind(in FDev peer_device, inout AVStreams::QoS the_qos, out boolean is_met) raises (AVStreams::streamOpFailed, AVStreams::QoSRequestFailed); FlowConnection bind_mcast(in FDev first_peer, inout AVStreams::QoS the_qos, out boolean is_met) raises (AVStreams::streamOpFailed, AVStreams::QoSRequestFailed); void destroy(in FlowEndPoint the_ep, in string fdev_name) // ie FDev not found raises (AVStreams::notSupported); }; enum PositionOrigin { AbsolutePosition, RelativePosition, ModuloPosition }; enum PositionKey { ByteCount, SampleCount, MediaTime }; struct Position { PositionOrigin origin; PositionKey key; long value; }; exception PostionKeyNotSupported { PositionKey key;}; exception InvalidPosition { PositionKey key;}; // MediaControl interface is similar to // ControlledStream interface in MSS. // It can be inherited by flow endpoints or // FlowConnection interfaces. interface MediaControl{ exception PostionKeyNotSupported { PositionKey key;}; Position get_media_position(in PositionOrigin an_origin, in PositionKey a_key) raises (PostionKeyNotSupported); void set_media_position(in Position a_position) raises (PostionKeyNotSupported, InvalidPosition); void start(in Position a_position) raises(InvalidPosition); void pause(in Position a_position) raises(InvalidPosition); void resume(in Position a_position) raises(InvalidPosition); void stop(in Position a_position) raises(InvalidPosition); }; // Additional sequences needed for the properties. typedef sequence FlowConnection_seq; typedef sequence StreamEndPoint_A_seq; typedef sequence StreamEndPoint_B_seq; typedef sequence FlowEndPoint_seq; typedef sequence Object_seq; }; #endif /* TAO_AV_STREAMS_IDL */