/*
* @(#)SessionManager.java 1.20 02/08/21
*
* Copyright (c) 1996-2002 Sun Microsystems, Inc. All rights reserved.
*/
package javax.media.rtp;
import java.lang.String;
import javax.media.protocol.*;
import javax.media.format.*;
import java.net.*;
import java.util.*;
import java.io.*;
import javax.media.rtp.event.*;
import javax.media.rtp.rtcp.*;
import javax.media.Controls;
import javax.media.Format;
/**
* The interface implemented by the SessionManager. This is the
* starting point for creating, maintaining and closing an RTP
* session.
* @deprecated This inferface has been replaced with the
* RTPManager interface.
*/
public abstract interface SessionManager extends Controls
{
/** Used to specify an unspecified SSRC for methods which retrieve an
* SSRC
*/
public static final long SSRC_UNSPEC = 0;
/**
* Initializes the session. Once this method has been called, the
* session is "initialized" and this method cannot be called again. <P>
*
* @param localAddress Encapsulates the *local* control and data
* addresses to be used for the session. If either InetAddress
* contained in this parameter is null, a default local address
* will be chosen; this should be adequate except for multi-homed
* systems with more than one IP
* interface. The ports do not necessarily need to be specified
* (i.e. they may be the ANY_PORT constant); RTPSM will pick
* appropriate ports in that case. In any case, the fully specified
* local addresses to be used are returned in this object. <P>
* Note: The localAddress is the interface and port used by the
* sending/transmitting threads of the SessionManager. The
* receiving threads will use the address and port of the RTP
* session that is supplied in startSession().
*
* @param defaultSSRC Identifies an SSRC value to use for this
* participant. This SSRC value will go out in RTCP listener
* reports from this participant.
* .If the user wishes that RTPSM generate the SSRC, it must use the
* initSession() call mentioned below.<P>
*
* @param defaultSourceDesc An array of SourceDescription
* objects containing information to send in RTCP SDES packets
* for the local participant. This information can be changed by
* calling setSourceDescription() on the local Participant
* object.
* @param rtcp_bw_fraction The fraction of the session bandwidth
* that the RTPSM must use when sending out RTCP reports.
* @param rtcp_sender_bw_fraction The fraction of the
* rtcp_bw_fraction that the RTPSM must use to send out RTCP Sender
* reports from the local participant. The remaining fraction of the
* rtcp_bw is used for sending out RTCP Receiver reports. <P>
*
* Note : The rtcp_bw_fraction is set to zero for a
* non-participating observer of this Session. In this case
* the application will receive both RTP and RTCP messages, but will
* not send out any RTCP feedback reports.
* This is equivalent to setting the outgoing RTP/RTCP
* bandwidth of this application to zero, implying that this
* application may NOT send out any data or control streams and can
* thus not make a call to createSendStream(). If it does, it will
* receive an exception. Further, this application is NOT considered
* an Participant since it does not send out any RTCP
* information. Consequently, this client will NOT appear in the
* list of Participants for this session.<P>
*
* InitSession called a second time or thereafter will return
* without doing anything, since the session had already been
* initialized. If parameters to initSession() are different from
* before, the user must note that the new parameters will ignored
* as a result of no action being performed. In this case,
* the return value is -1
* indicating no action was taken since initSession had previously
* been called <P>
*
* @return Returns 0 if initSession was executed succesfully and
* -1 initSession was previously executed.
* @exception InvalidSessionAddressException This exception is
* thrown if the local control and data addresses given in
* parameter localAddress do not belong to one of the localhost
* interfaces.
*
* @classname SessionAddress
* @classname SourceDescription
* <p>
*/
public int
initSession( SessionAddress localAddress,
long defaultSSRC,
SourceDescription defaultUserDesc[],
double rtcp_bw_fraction,
double rtcp_sender_bw_fraction)
throws InvalidSessionAddressException;
/**
* This form of initSession is to be used when the SSRC is to be
* generated by the RTPSM. In this case, the client allows the
* underlying implementation to choose an appropriate SSRC, and
* the SSRC chosen can be retrieved with getDefaultSSRC(). <P>
*
* InitSession called a second time or thereafter will return
* without doing anything, since the session had already been
* initialized. If parameters to initSession() are different from
* before, the user must note that the new parameters will ignored
* as a result of no action being performed. In this case,
* The return value is -1
* indicating no action was taken since initSession had previously
* been called <P>
*
* @return Returns 0 if initSession was executed succesfully and
* -1 initSession was previously executed.
*
* @classname InitSession
* @exception InvalidSessionAddressException This exception is
* thrown if the local control and data addresses given in
* parameter localAddress do not belong to one of the localhost
* interfaces.
*
* @classname SessionAddress
* @classname SourceDescription
* <p>
*/
public int
initSession( SessionAddress localAddress,
SourceDescription defaultUserDesc[],
double rtcp_bw_fraction,
double rtcp_sender_bw_fraction)
throws InvalidSessionAddressException;
/**
* This method starts the session, causing RTCP reports to
* generated and callbacks to be made through the
* SessionListener interface. This method must be called after
* session initialization and prior to the creation of any streams
* on a session. A valid destination address is required
* even for sessions that will have no sending streams so that RTCP
* control messages can be sent.
* <P>
*
* @param destAddress The RTP session address which is defined as
* the address,port combination pair to which data and
* control packets will be sent. As opposed to the localAddress
* parameter specified in initSession,some portions of this
* SessionAddress *must* be specified.This is the Session
* Address and is defined in the RFC as one network address and a
* port pair for RTP/RTCP. The RTP ports is even and one lower than
* the RTCP port.Either of the RTP or RTCP address, port pair must
* be supplied in destAddress parameter.
* Note: For multicast sessions, this address will be the
* multicast address to which data will be sent. In case of a
* UNICAST session, you can enter either the IP address of the
* receiver of data i.e. address to which data is destined OR the IP
* address of the sender i.e. address to which control packets are
* to be sent. For broadcast session, this
* address will be the subnet broadcast address.
*
* @return Returns 0 if startSession was executed succesfully and
* -1 startSession was previously executed.
*
* @param mcastScope If the destination address specified is an IP
* multicast address, this value
* specifies the ttl of outgoing packets on that address. <P>
*
* @param encryptionInfo Encryption information for this
* session. <P>
* @exception IOException This exception is thrown if the local
* control and data sockets cannot be opened or if the mulitcast
* group cannot be joined.
*
* @exception InvalidSessionAddressException This exception is
* thrown if the Session Address is incomplete in that it
* cannot be completely deciphered.
* @classname SessionAddress
* @classname EncryptionInfo
* <p>
*/
public int
startSession(SessionAddress destAddress,
int mcastScope,
EncryptionInfo encryptionInfo)
throws IOException, InvalidSessionAddressException;
/**
* This method may be used instead of startSession() above, but only
* in case of UNICAST sessions. It allows a user to specify
* distinct port pairs for the two end points of a unicast session
* only.
* Note: This feature is not in RFC 1889, but has been added in a later
* RTP draft.
* @param localReceiverAddress specifies the RTP session address of the
* local end point of this unicast session. i.e. the IP
* address, data/ control port of the local host
* @param localSenderAddress specifies the local RTP session address that
* is used for sending out RTP and RTCP packets.
* @param remoteReceiverAddress The RTP session address of the remote end
* point of this unicast session. i.e. the IP address,port of the
* remote host
*
* @exception IOException This exception is thrown if the local
* control and data sockets cannot be opened.
*
* @exception InvalidSessionAddressException This exception is
* thrown if the Session Address is incomplete in that it
* cannot be completely deciphered or the addresses supplied are
* NOT unicast IP addresses.
*
* @return Returns 0 if startSession was executed succesfully and
* -1 startSession was previously executed.
*
* @classname SessionAddress
* @classname EncryptionInfo
* <p>
*/
public int
startSession(SessionAddress localReceiverAddress,
SessionAddress localSenderAddress,
SessionAddress remoteReceiverAddress,
EncryptionInfo encryptionInfo)
throws IOException, InvalidSessionAddressException;
/**
* Adds a SessionListener. A SessionListener will receive
* events that pertain to the Session as a whole. Currently,
* these include the NewParticipantEvent and
* LocalCollisionEvent. Events are notified in the
* update(SessionEvent) method which must be implemented by all
* SessionListeners.
* @classname SessionListener
*/
public void
addSessionListener(SessionListener listener);
/**
* Adds a RemoteListener to the session. This listener listens
* to all remote RTP events. Currently, these include
* ReceiverReportEvent, ReceiveSenderReportEvent and
* RemoteCollisionEvent. This interface would be usefuly for an RTCP
* monitor that does not wish to receive any particular stream
* transitionEvents but just wants to monitor the session quality
* and statistics.
*/
public void
addRemoteListener( RemoteListener listener);
/**
* Adds a ReceiveStreamListener. This listener listens to all the
* events that notify state transitions for a particular
* ReceiveStream.
*/
public void
addReceiveStreamListener( ReceiveStreamListener listener);
/**
* Adds a SendStreamListener. This listener listens to all the
* events that notify state transitions for a particular
* SendStream.
*/
public void
addSendStreamListener(SendStreamListener listener);
/**
* removes a SessionListener
* @classname SessionListener
*/
public void
removeSessionListener(SessionListener listener);
/**
* removes a RTPRemoteListener
* @classname RTPRemoteListener
*/
public void
removeRemoteListener( RemoteListener listener);
/**
* removes a ReceiveStreamListener
* @classname ReceiveStreamListener
*/
public void
removeReceiveStreamListener( ReceiveStreamListener listener);
/**
* removes a SendStreamListener
* @classname SendStreamListener
*/
public void
removeSendStreamListener(SendStreamListener listener);
/**
* Returns the default SSRC for this session. Returns SSRC_UNSPEC
* if the session has not yet been initialized. <P>
*/
public long
getDefaultSSRC();
/**
* Returns a Vector of all the remote participants in the
* session.This vector is simply a snapshot of the current state in
* the SessionManager.The SessionListener interface can be
* used to get notified of additional participants for the
* Session. <P>
*/
public Vector
getRemoteParticipants();
/**
* Returns a vector of all the active (data sending)
* participants. These participants may be remote and/or the local participant.
*/
public Vector
getActiveParticipants();
/**
* Returns all the passive participants. These participants will
* include the local participant and some remote participants that
* do not send any data.
*/
public Vector
getPassiveParticipants();
/**
* Retrieves the local participant
*/
public LocalParticipant
getLocalParticipant();
/**
* Returns all the participants of this session.
*/
public Vector
getAllParticipants();
/** Returns the ReceiveStreams created by the
* SessionManager. These are streams formed when the RTPSM
* detects a new source of RTP data.
* ReceiveStreams returned are a snapshot of the current state in the
* RTPSesionManager and the ReceiveStreamListener interface may be used
* to get notified of additional streams.
*/
public Vector
getReceiveStreams();
/** Returns the SendStreams created by the
* SessionManager.
* SendStreams returned are a snapshot of the current state in the
* RTPSesionManager and the SendStreamListener interface may be used
* to get notified of additional streams.
*/
public Vector
getSendStreams();
/** Returns the RTPStream created by the SessionManager that
* has the same SSRC as the filterssrc. If no stream with the
* filterssrc exits, null is returned. <p>
*
* Note: the return type for this method has been changed from long
* to int.
*/
public RTPStream
getStream(long filterssrc);
/**
* Allows the user to retrieve the multicast TTL set for this
session.
*/
public int
getMulticastScope();
/**
* Sets the IP Multicast TTL for this session. <P>
*
* @param multicastScope Specifies the new multicast scope for the
* session. A multicastScope less than 1 defaults to a scope of 1
* set for the session. <P>
*/
public void
setMulticastScope(int multicastScope);
/**
* Informs RTP that the application is ready to terminate the
* session. All open streams will be closed after this call
* completes, and the object implementing this interface is no longer
* useful as an SessionManager. <P>
*
* @param reason A string that RTCP will send out to other
* participants as the reason the local participant has quit the
* session.This RTCP packet will go out with the default SSRC of the
* session. If supplied as null, a default reason will be supplied by RTP. <P>
*/
public void
closeSession(String reason);
/**
* This function can be used to generate a CNAME using the scheme
* described in RFC1889. This function is provided in order to facilitate CNAME
* generation prior to actual stream creation. <P>
*
* @return The generated CNAME. <P>
*/
public String
generateCNAME();
/**
* This function can be used to generate a SSRC using the scheme
* described in RFC1889. This function is provided in order to facilitate SSRC
* generation prior to actual stream creation, which may be useful for call
* control functions which need to exchange SSRCs before stream transmission
* commences. <P>
* Note: the return type has been changed from long to int. <P>
*
* @return The generated SSRC. <P>
*/
public long
generateSSRC();
/**
* Method to get the Destination SessionAddress of this SessionManager
* This will return the data address/port and control address/port
* that the RTP manager is receiving data/control packets on and
* sending RTCP packets to. <p>
*/
public SessionAddress
getSessionAddress();
/**
* Method to get the local SessionAddress of this
* SessionManager. This will return the local address and port
* bound to of the socket which is sending out RTP/RTCP packets. Since the
* RTPSM does not send out any RTP packets, the destaddress/port
* field of SessionAddress will not be filled in.
* Note: current implementations of JDK will return
* 0.0.0.0/0.0.0.0 for a socket.getLocalAddress() call.
*
*/
public SessionAddress
getLocalSessionAddress();
/**
* This method will provide access to overall data and control
* messsage reception statistics for this Session. Statistics on
* data from individual sources is available from method
* getSourceReceptionStats() of interface ReceiveStream
* @return The GlobalReceptionStats for this session
* @classname ReceiveStream
*/
public GlobalReceptionStats
getGlobalReceptionStats();
/**
* This method will provide access to overall data and control
* messsage transmission statistics for this Session. Statistics on
* data from individual sources is available from method
* getSourceTransmissionStats() of interface SendStream
* @return The GlobalTransmissionStats for this session
* @classname SendStream
*/
public GlobalTransmissionStats
getGlobalTransmissionStats();
/**
* This method is used to create a sending stream within the RTP
* session. For each time the call is made, a new sending stream
* will be created. This stream will use the SDES items as entered
* in the initSession() call for all its RTCP messages. Each stream
* is sent out with a new SSRC (Synchronisation SouRCe
* identifier), but from the same participant i.e. local
* participant. <BR>
*
* @param ssrc The Synchronisation source identifier to be used when
* sending out this data stream. Note: Since the ssrc to be used by
* the local member is supplied in the initSession() call as well,
* the first SendStream created will use that ssrc and hence
* IGNORE the ssrc supplied in createSendStream. Subsequent calls to
* createSendStream() will use the ssrc supplied as this argument.
* Use createSendStream (DataSource, int, int) to start a send
* stream without supplying an SSRC. <BR>
*
* @param ds This is the PushOutputDataSource or
* PullOutputDataSource which is the output datasource of the
* Processor. This datasource may contain more than one
* stream. The stream which is used in creating this RTP
* stream is specified in the next parameter of stream.<BR>
*
* @param streamindex The index of the sourcestream from which
* data is sent out on this RTP stream. An index of 1 would indicate the first
* sourcestream of this datasource should be used to create the RTP
* stream. If the index is set to zero, it would indicate a RTP
* mixer operation is desired. i.e. all the streams of this
* datasource must be mixed into one single stream from one single
* SSRC. <BR>
*
* @param packet_interval This is the packetization interval in
* millisecs that must constitute each RTP packet when it is
* transmitted over the network. The packetization interval
* determines the minimum end-to-end delay; longer packets
* introduce less header overhead but higher delay and make packet loss more
* noticeable. For non interactive applications such as lectures or
* links with severe bandwidth constraints, a higher packetization delay may be
* appropriate. <BR>
*
* If this parameter is supplied as zero, the
* packetizer's default packetization interval will be used.<BR>
*
* Note: The RTP payload that is used to send this stream is found
* from the format set on the SourceStream of the datasource
* supplied. <BR>
* If the sourcestream has no format set or has a
* format for which a packetizer plugin cannot be found in the session
* manager's database, an UnsupportedFormatException will be thrown
* by the SessionManager. <BR>
*
* Note on PullDataSources supplied to the RTP session manager :
* In most cases, it is expected that the datasource supplied to the
* RTP session manager for stream creation would be a
* PushDataSource. In cases that the datasource is a pulldatasource,
* it MUST have a format set on its SourceStreams. This is the only
* way for SessionManger to determine the RTP payload to use in
* the header of the stream as well as the bitrate to pulldata from
* this datasource. <BR>
*
* @return The SendStream created by the RTP session manager.<BR>
*
* @exception UnsupportedFormatException
* (javax.media.format.UnsupportedFormatException ). This
* exception is thrown if the format is not set on the sourcestream
* or a RTP payload cannot be located for the format set on the
* sourcestream.
* @exception SSRCInUseException <BR>
* This is thrown if the ssrc supplied as the first argument is
* already in use by another sendstream of this local
* participant. RTP requires that each sending stream of the same
* participant in the same session use a different unique SSRC. <BR>
*
* @exception IOException
* Thrown for two possible reasons which will be specified in the
* message part of the exception
* 1) If the session was initiated with zero rtcp_bw_fraction which
* implied that this participant could not send out any RTP/RTCP
* data or control messages. i.e. it could not also create any send
* streams and was just a passive listener for this session.
* 2) If there was any problem opening the sending sockets
* @classname SendStream
*
*/
public SendStream
createSendStream(int ssrc,
DataSource ds,
int streamindex) throws
UnsupportedFormatException, SSRCInUseException, IOException;
/**
* This method is the same as the createSendStream(int ssrc,
* DataSource ds, in t streamindex, int packet_interval) except
* that the user need not supply the SSRC of the stream. The SSRC
* will be chosen by the SessionManager itself.<BR>
*
* This method is used to create a sending stream within the RTP
* session. For each time the call is made, a new sending stream
* will be created. This stream will use the SDES items as entered
* in the initSession() call for all its RTCP messages. Each stream
* is sent out with a new SSRC (Synchronisation SouRCe
* identifier), but from the same participant i.e. local
* participant. <BR>
*
* @param ds This is the PushOutputDataSource or
* PullOutputDataSource which is the output datasource of the
* Processor. This datasource may contain more than one
* stream. The stream which is used in creating this RTP
* stream is specified in the next parameter of stream.<BR>
*
* @param streamindex The index of the sourcestream from which
* data is sent out on this RTP stream. An index of 1 would indicate the first
* sourcestream of this datasource should be used to create the RTP
* stream. If the index is set to zero, it would indicate a RTP
* mixer operation is desired. i.e. all the streams of this
* datasource must be mixed into one single stream from one single
* SSRC. <BR>
*
* @param packet_interval This is the packetization interval in
* millisecs that must constitute each RTP packet when it is
* transmitted over the network. The packetization interval
* determines the minimum end-to-end delay; longer packets
* introduce less header overhead but higher delay and make packet loss more
* noticeable. For non interactive applications such as lectures or
* links with severe bandwidth constraints, a higher packetization delay may be
* appropriate. <BR>
*
* If this parameter is supplied as zero, the
* packetizer's default packetization interval will be used.<BR>
*
* Note: The RTP payload that is used to send this stream is found
* from the format set on the SourceStream of the datasource
* supplied. <BR>
* If the sourcestream has no format set or has a
* format for which a packetizer plugin cannot be found in the session
* manager's database, an UnsupportedFormatException will be thrown
* by the SessionManager. <BR>
*
* Note on PullDataSources supplied to the RTP session manager :
* In most cases, it is expected that the datasource supplied to the
* RTP session manager for stream creation would be a
* PushDataSource. In cases that the datasource is a pulldatasource,
* it MUST have a format set on its SourceStreams. This is the only
* way for SessionManger to determine the RTP payload to use in
* the header of the stream as well as the bitrate to pulldata from
* this datasource. <BR>
*
* @return The SendStream created by the RTP session manager.<BR>
*
* @exception UnsupportedFormatException
* (javax.media.format.UnsupportedFormatException ). This
* exception is thrown if the format is not set on the sourcestream
* or a RTP payload cannot be located for the format set on the
* sourcestream.
* @exception IOException
* Thrown for two possible reasons which will be specified in the
* message part of the exception
* 1) If the session was initiated with zero rtcp_bw_fraction which
* implied that this participant could not send out any RTP/RTCP
* data or control messages. i.e. it could not also create any send
* streams and was just a passive listener for this session.
* 2) If there was any problem opening the sending sockets
* @classname SendStream
*
*/
public SendStream
createSendStream(DataSource ds,
int streamindex) throws
UnsupportedFormatException, IOException;
/**
* This method is used to add a dynamic payload ---> Format
* mapping in the SessionManager. The SessionManager maintains
* all static payload numbers and their correspnding Formats as
* mentioned in the Audio/Video profile document. Using the plugin
* packethandler interface, a user may plugin his own packetizer or
* depacketizer to handle RTP streams of a proprietary format using
* dynamic payload numbers as specified in the AV profile. Before
* streaming payload of a dynamic nature, a Format object needs to
* be created for the dynamic payload and associated with a dynamic
* payload number.
* @param fmt The Format to be associated with this dynamic
* payload number.
* @param payload The RTP payload number
* @see Format
*/
public void
addFormat(Format fmt,
int payload);
/**
* This variant of the startSession() method is for starting
* a session with an empty list of peers. This method is meant to be
* used to start a multi-unicast session. For more details, please see
* documentation on multi-unicast sessions.
* @param mcastScope if the address in the addPeer() method is a
* multicast address, the packets are sent out with this ttl.
* @param encryptionInfo the encryption information to be used in
* this session.
* @returns same as other forms of startSession <p>
*/
public int
startSession(int mcastScope, EncryptionInfo encryptionInfo) throws IOException;
/**
* Adds a peer to the list of peers.
* This method can be used when an RTP Session is to be built based on a
* full mesh of unicast streams between participants (this is called
* multi-unicast).
* If there is more than one peer in the list the SessionManager
* duplicates outbound RTP or RTCP packets.
* The duplicates are addressed to each peer in the list of peers.
* <p>If the peer is already in the list the method call is ignored.
* <p>[Note: The notion of a list of peers can be readily extended
* to contain multicast addresses as well.
* This would enable hybrid multicast and multi-unicast RTP Sessions.]
*
* @param peerAddress The unicast address pair (RTP transport address,
RTCP transport address) of the peer.
*
* @exception IOException This exception is thrown if the multicast group
* cannot be joined. <p>
*/
public void
addPeer(SessionAddress peerAddress) throws IOException,
InvalidSessionAddressException;
/**
* Removes a peer from the list of peers.
* <p>If the peer is not in the list the method call is ignored.
* @param peerAddress The unicast address pair (RTP transport address,
* RTCP transport address) of the peer. <p>
*/
public void
removePeer(SessionAddress peerAddress);
/**
* Removes all peers from the list of peers. <p>
*/
public void
removeAllPeers();
/**
* Gets the list of peers.
*
* @return The list of current peers in the form of a Vector of
SessionAddress objects.
*/
public Vector
getPeers();
}