File	Doc	Category	Size	Date	Package
SessionManager.java	API Doc	JMF 2.1.1e	30043	Mon May 12 12:20:40 BST 2003	javax.media.rtp

SessionManager

Fields Summary
public static final long	SSRC_UNSPEC Used to specify an unspecified SSRC for methods which retrieve an SSRC

Constructors Summary

Methods Summary
public void	addFormat(javax.media.Format fmt, int payload) 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	addPeer(javax.media.rtp.SessionAddress peerAddress) 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. If the peer is already in the list the method call is ignored. [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.
public void	addReceiveStreamListener(javax.media.rtp.ReceiveStreamListener listener) Adds a ReceiveStreamListener. This listener listens to all the events that notify state transitions for a particular ReceiveStream.
public void	addRemoteListener(javax.media.rtp.RemoteListener 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	addSendStreamListener(javax.media.rtp.SendStreamListener listener) Adds a SendStreamListener. This listener listens to all the events that notify state transitions for a particular SendStream.
public void	addSessionListener(javax.media.rtp.SessionListener listener) 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	closeSession(java.lang.String reason) 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. 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.
public javax.media.rtp.SendStream	createSendStream(int ssrc, javax.media.protocol.DataSource ds, int streamindex) 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. 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. 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. 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. 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. If this parameter is supplied as zero, the packetizer's default packetization interval will be used. Note: The RTP payload that is used to send this stream is found from the format set on the SourceStream of the datasource supplied. 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. 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. return The SendStream created by the RTP session manager. 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 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. 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 javax.media.rtp.SendStream	createSendStream(javax.media.protocol.DataSource ds, int streamindex) 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. 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. 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. 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. 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. If this parameter is supplied as zero, the packetizer's default packetization interval will be used. Note: The RTP payload that is used to send this stream is found from the format set on the SourceStream of the datasource supplied. 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. 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. return The SendStream created by the RTP session manager. 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 java.lang.String	generateCNAME() 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. return The generated CNAME.
public long	generateSSRC() 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. Note: the return type has been changed from long to int. return The generated SSRC.
public java.util.Vector	getActiveParticipants() Returns a vector of all the active (data sending) participants. These participants may be remote and/or the local participant.
public java.util.Vector	getAllParticipants() Returns all the participants of this session.
public long	getDefaultSSRC() Returns the default SSRC for this session. Returns SSRC_UNSPEC if the session has not yet been initialized.
public javax.media.rtp.GlobalReceptionStats	getGlobalReceptionStats() 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 javax.media.rtp.GlobalTransmissionStats	getGlobalTransmissionStats() 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 javax.media.rtp.LocalParticipant	getLocalParticipant() Retrieves the local participant
public javax.media.rtp.SessionAddress	getLocalSessionAddress() 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 int	getMulticastScope() Allows the user to retrieve the multicast TTL set for this session.
public java.util.Vector	getPassiveParticipants() Returns all the passive participants. These participants will include the local participant and some remote participants that do not send any data.
public java.util.Vector	getPeers() Gets the list of peers. return The list of current peers in the form of a Vector of SessionAddress objects.
public java.util.Vector	getReceiveStreams() 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 java.util.Vector	getRemoteParticipants() 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.
public java.util.Vector	getSendStreams() 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 javax.media.rtp.SessionAddress	getSessionAddress() 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.
public javax.media.rtp.RTPStream	getStream(long filterssrc) 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. Note: the return type for this method has been changed from long to int.
public int	initSession(javax.media.rtp.SessionAddress localAddress, long defaultSSRC, javax.media.rtp.rtcp.SourceDescription[] defaultUserDesc, double rtcp_bw_fraction, double rtcp_sender_bw_fraction) Initializes the session. Once this method has been called, the session is "initialized" and this method cannot be called again. 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. 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. 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. 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. 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 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
public int	initSession(javax.media.rtp.SessionAddress localAddress, javax.media.rtp.rtcp.SourceDescription[] defaultUserDesc, double rtcp_bw_fraction, double rtcp_sender_bw_fraction) 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(). 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 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
public void	removeAllPeers() Removes all peers from the list of peers.
public void	removePeer(javax.media.rtp.SessionAddress peerAddress) Removes a peer from the list of peers. 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.
public void	removeReceiveStreamListener(javax.media.rtp.ReceiveStreamListener listener) removes a ReceiveStreamListener classname ReceiveStreamListener
public void	removeRemoteListener(javax.media.rtp.RemoteListener listener) removes a RTPRemoteListener classname RTPRemoteListener
public void	removeSendStreamListener(javax.media.rtp.SendStreamListener listener) removes a SendStreamListener classname SendStreamListener
public void	removeSessionListener(javax.media.rtp.SessionListener listener) removes a SessionListener classname SessionListener
public void	setMulticastScope(int multicastScope) Sets the IP Multicast TTL for this session. 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.
public int	startSession(javax.media.rtp.SessionAddress destAddress, int mcastScope, javax.media.rtp.EncryptionInfo encryptionInfo) 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. 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. param encryptionInfo Encryption information for this session. 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
public int	startSession(int mcastScope, javax.media.rtp.EncryptionInfo encryptionInfo) 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
public int	startSession(javax.media.rtp.SessionAddress localReceiverAddress, javax.media.rtp.SessionAddress localSenderAddress, javax.media.rtp.SessionAddress remoteReceiverAddress, javax.media.rtp.EncryptionInfo encryptionInfo) 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