jlibrtp
Class RTPSession

java.lang.Object
  extended by jlibrtp.RTPSession

public class RTPSession
extends java.lang.Object

The RTPSession object is the core of jlibrtp. One should be instantiated for every communication channel, i.e. if you send voice and video, you should create one for each. The instance holds a participant database, as well as other information about the session. When the application registers with the session, the necessary threads for receiving and processing RTP packets are spawned. RTP Packets are sent synchronously, all other operations are asynchronous.

Author:
Arne Kepp

Field Summary
protected  AppCallerThread appCallerThrd
          The thread for invoking callbacks for RTP packets
protected  RTPAppIntf appIntf
          Handle to application interface for RTP
protected  int bandwidth
          Session bandwidth in BYTES per second
protected  java.lang.String cname
          SDES CNAME
protected  boolean conflict
          We're busy resolving a SSRC conflict, please try again later
protected  int conflictCount
          Number of conflicts observed, exessive number suggests loop in network
protected  DebugAppIntf debugAppIntf
          Handle to application interface for debugging
 java.lang.String email
          SDES The participant's email
protected  boolean endSession
          Enough is enough, set to true when you want to quit.
protected  int fbEarlyThreshold
           
protected  int fbMaxDelay
           
protected  int fbRegularThreshold
           
protected  boolean frameReconstruction
          Should the library attempt frame reconstruction?
protected  long lastTimestamp
          The last timestamp when we sent something
 java.lang.String loc
          SDES The participant's location
protected  java.net.InetAddress mcGroup
          RTP multicast group
protected  boolean mcSession
          Whether this session is a multicast session or not
protected  int minInterval
           
protected  boolean naiveReception
          By default we do not return packets from strangers in unicast mode
 java.lang.String name
          SDES The participant's real name
 java.lang.String note
          SDES A note
protected  ParticipantDatabase partDb
          Participant database
protected  int payloadType
          Current payload type, can be changed by application
 java.lang.String phone
          SDES The participant's phone number
protected  int pktBufBehavior
          Maximum number of packets used for reordering
protected  java.util.concurrent.locks.Condition pktBufDataReady
          Condition variable, to tell the
protected  java.util.concurrent.locks.Lock pktBufLock
          Lock to protect the packet buffers
 java.lang.String priv
          SDES A priv string, loosely defined
protected  java.util.Random random
          The random seed
protected  RTPReceiverThread recvThrd
          The thread for receiving RTP packets
protected  boolean registered
          Only one registered application, please
protected  RTCPAppIntf rtcpAppIntf
          Handle to application interface for RTCP (optional)
protected  RTCPAVPFIntf rtcpAVPFIntf
          Handle to application interface for AVPF, RFC 4585 (optional)
protected  int rtcpBandwidth
           
static int rtcpDebugLevel
          The debug level is final to avoid compilation of if-statements.
0 provides no debugging information, 20 provides everything
Debug output is written to System.out
Debug level for RTCP related things.
protected  int rtcpMode
           
protected  RTCPSession rtcpSession
          The RTCP session associated with this RTP Session
static int rtpDebugLevel
          The debug level is final to avoid compilation of if-statements.
0 provides no debugging information, 20 provides everything
Debug output is written to System.out
Debug level for RTP related things.
protected  java.net.MulticastSocket rtpMCSock
          RTP multicast socket
protected  java.net.DatagramSocket rtpSock
          RTP unicast socket
protected  int sentOctetCount
          Number of octets sent by this session
protected  int sentPktCount
          Number of packets sent by this session
protected  int seqNum
          Current sequence number
protected  long ssrc
          SSRC of this session
 java.lang.String tool
          SDES The tool the participants is using
 
Constructor Summary
RTPSession(java.net.DatagramSocket rtpSocket, java.net.DatagramSocket rtcpSocket)
          Returns an instance of a unicast RTP session.
RTPSession(java.net.MulticastSocket rtpSock, java.net.MulticastSocket rtcpSock, java.net.InetAddress multicastGroup)
          Returns an instance of a multicast RTP session.
 
Method Summary
 int addParticipant(Participant p)
          Add a participant object to the participant database.
 java.lang.String CNAME()
          Get the current CNAME, used for outgoing SDES packets
 void CNAME(java.lang.String cname)
          Overrides CNAME, used for outgoing RTCP packets.
private  void createRandom()
          Initializes a random variable
 void endSession()
          End the RTP Session.
 int fbAppLayerFeedback(long ssrcMediaSource, byte[] bitString)
          Adds a Picture Loss Indication to the feedback queue
 int fbPictureLossIndication(long ssrcMediaSource)
          Adds a Picture Loss Indication to the feedback queue
 int fbPictureLossIndication(long ssrcMediaSource, int FMT, int[] PID, int[] BLP)
          Adds a RTP Feedback packet to the feedback queue.
 int fbRefPictureSelIndic(long ssrcMediaSource, int bitPadding, int payloadType, byte[] bitString)
          Adds a Reference Picture Selection Indication to the feedback queue
 int fbSlicLossIndication(long ssrcMediaSource, int[] sliFirst, int[] sliNumber, int[] sliPictureId)
          Adds a Slice Loss Indication to the feedback queue
 boolean frameReconstruction()
          Whether the packet buffer will attempt to reconstruct packet automatically.
 void frameReconstruction(boolean toggle)
          Enable / disable frame reconstruction in the packet buffers.
private  void generateCNAME()
           
private  void generateSeqNum()
          Generates a random sequence number
private  void generateSsrc()
          Generates a random SSRC
private  int getNextSeqNum()
          Fetches the next sequence number for RTP packets.
 java.util.Enumeration<Participant> getParticipants()
           
 long getSsrc()
           
 java.util.Iterator<Participant> getUnicastReceivers()
           
(package private)  boolean isEnding()
          Check whether this session is ending.
 boolean naivePktReception()
          Are packets from unknown participants returned to the application?
 void naivePktReception(boolean doAccept)
          Should packets from unknown participants be returned to the application? This can be dangerous.
 int packetBufferBehavior()
          The number of RTP packets that should be buffered when a packet is missing or received out of order.
 int packetBufferBehavior(int behavior)
          Set the number of RTP packets that should be buffered when a packet is missing or received out of order.
 int payloadType()
          Get the payload type that is currently used for outgoing RTP packets.
 int payloadType(int payloadT)
          Update the payload type used for the session.
 int registerAVPFIntf(RTCPAVPFIntf rtcpAVPFIntf, int maxDelay, int earlyThreshold, int regularThreshold)
          Set whether the stack should operate in RFC 4585 mode.
 void removeParticipant(Participant p)
          Remove a participant from the database.
protected  void resolveSsrcConflict()
          Resolve an SSRC conflict.
 int rtcpBandwidth()
          RFC 3550 dictates that 5% of the total bandwidth, as set by sessionBandwidth, should be dedicated to RTCP traffic.
 int rtcpBandwidth(int bandwidth)
          Set the RTCP bandwidth, see rtcpBandwidth(void) for details.
 int RTPSessionRegister(RTPAppIntf rtpApp, RTCPAppIntf rtcpApp, DebugAppIntf debugApp)
          Registers an application (RTPAppIntf) with the RTP session.
 long[] sendData(byte[] buf)
          Send data to all participants registered as receivers, using the current timeStamp, dynamic sequence number and the current payload type specified for the session.
 long[][] sendData(byte[][] buffers, long[] csrcArray, boolean[] markers, long rtpTimestamp, long[] seqNumbers)
          Send data to all participants registered as receivers, using the current timeStamp and payload type.
 long[] sendData(byte[] buf, long rtpTimestamp, long seqNum)
          Send data to all participants registered as receivers, using the specified timeStamp, sequence number and the current payload type specified for the session.
 int sendRTCPAppPacket(long ssrc, int type, byte[] name, byte[] data)
          Send RTCP App packet to receiver specified by ssrc Return values: 0 okay -1 no RTCP session established -2 name is not byte[4]; -3 data is not byte[x], where x = 4*y for syme y -4 type is not a 5 bit unsigned integer Note that a return value of 0 does not guarantee delivery.
 int sessionBandwidth()
          The bandwidth currently allocated to the session, in bytes per second.
 int sessionBandwidth(int bandwidth)
          Set the bandwidth of the session.
 void unregisterAVPFIntf()
          Unregisters the RTCP AVPF interface, thereby going from RFC 4585 mode to RFC 3550 You still have to adjust packetBufferBehavior() and frameReconstruction.
 int updateRTCPSock(java.net.DatagramSocket newSock)
          Change the RTCP socket of the session.
 int updateRTCPSock(java.net.MulticastSocket newSock)
          Change the RTCP multicast socket of the session.
 int updateRTPSock(java.net.DatagramSocket newSock)
          Change the RTP socket of the session.
 int updateRTPSock(java.net.MulticastSocket newSock)
          Change the RTP multicast socket of the session.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

rtpDebugLevel

public static final int rtpDebugLevel
The debug level is final to avoid compilation of if-statements.
0 provides no debugging information, 20 provides everything
Debug output is written to System.out
Debug level for RTP related things.

See Also:
Constant Field Values

rtcpDebugLevel

public static final int rtcpDebugLevel
The debug level is final to avoid compilation of if-statements.
0 provides no debugging information, 20 provides everything
Debug output is written to System.out
Debug level for RTCP related things.

See Also:
Constant Field Values

rtpSock

protected java.net.DatagramSocket rtpSock
RTP unicast socket


rtpMCSock

protected java.net.MulticastSocket rtpMCSock
RTP multicast socket


mcGroup

protected java.net.InetAddress mcGroup
RTP multicast group


mcSession

protected boolean mcSession
Whether this session is a multicast session or not


payloadType

protected int payloadType
Current payload type, can be changed by application


ssrc

protected long ssrc
SSRC of this session


lastTimestamp

protected long lastTimestamp
The last timestamp when we sent something


seqNum

protected int seqNum
Current sequence number


sentPktCount

protected int sentPktCount
Number of packets sent by this session


sentOctetCount

protected int sentOctetCount
Number of octets sent by this session


random

protected java.util.Random random
The random seed


bandwidth

protected int bandwidth
Session bandwidth in BYTES per second


naiveReception

protected boolean naiveReception
By default we do not return packets from strangers in unicast mode


frameReconstruction

protected boolean frameReconstruction
Should the library attempt frame reconstruction?


pktBufBehavior

protected int pktBufBehavior
Maximum number of packets used for reordering


partDb

protected ParticipantDatabase partDb
Participant database


appIntf

protected RTPAppIntf appIntf
Handle to application interface for RTP


rtcpAppIntf

protected RTCPAppIntf rtcpAppIntf
Handle to application interface for RTCP (optional)


rtcpAVPFIntf

protected RTCPAVPFIntf rtcpAVPFIntf
Handle to application interface for AVPF, RFC 4585 (optional)


debugAppIntf

protected DebugAppIntf debugAppIntf
Handle to application interface for debugging


rtcpSession

protected RTCPSession rtcpSession
The RTCP session associated with this RTP Session


recvThrd

protected RTPReceiverThread recvThrd
The thread for receiving RTP packets


appCallerThrd

protected AppCallerThread appCallerThrd
The thread for invoking callbacks for RTP packets


pktBufLock

protected final java.util.concurrent.locks.Lock pktBufLock
Lock to protect the packet buffers


pktBufDataReady

protected final java.util.concurrent.locks.Condition pktBufDataReady
Condition variable, to tell the


endSession

protected boolean endSession
Enough is enough, set to true when you want to quit.


registered

protected boolean registered
Only one registered application, please


conflict

protected boolean conflict
We're busy resolving a SSRC conflict, please try again later


conflictCount

protected int conflictCount
Number of conflicts observed, exessive number suggests loop in network


cname

protected java.lang.String cname
SDES CNAME


name

public java.lang.String name
SDES The participant's real name


email

public java.lang.String email
SDES The participant's email


phone

public java.lang.String phone
SDES The participant's phone number


loc

public java.lang.String loc
SDES The participant's location


tool

public java.lang.String tool
SDES The tool the participants is using


note

public java.lang.String note
SDES A note


priv

public java.lang.String priv
SDES A priv string, loosely defined


rtcpMode

protected int rtcpMode

fbEarlyThreshold

protected int fbEarlyThreshold

fbRegularThreshold

protected int fbRegularThreshold

minInterval

protected int minInterval

fbMaxDelay

protected int fbMaxDelay

rtcpBandwidth

protected int rtcpBandwidth
Constructor Detail

RTPSession

public RTPSession(java.net.DatagramSocket rtpSocket,
                  java.net.DatagramSocket rtcpSocket)
Returns an instance of a unicast RTP session. Following this you should adjust any settings and then register your application. The sockets should have external ip addresses, else your CNAME automatically generated CNAMe will be bad.

Parameters:
rtpSocket - UDP socket to receive RTP communication on
rtcpSocket - UDP socket to receive RTCP communication on, null if none.

RTPSession

public RTPSession(java.net.MulticastSocket rtpSock,
                  java.net.MulticastSocket rtcpSock,
                  java.net.InetAddress multicastGroup)
           throws java.lang.Exception
Returns an instance of a multicast RTP session. Following this you should register your application. The sockets should have external ip addresses, else your CNAME automatically generated CNAMe will be bad.

Parameters:
rtpSock - a multicast socket to receive RTP communication on
rtcpSock - a multicast socket to receive RTP communication on
multicastGroup - the multicast group that we want to communicate with.
Throws:
java.lang.Exception
Method Detail

RTPSessionRegister

public int RTPSessionRegister(RTPAppIntf rtpApp,
                              RTCPAppIntf rtcpApp,
                              DebugAppIntf debugApp)
Registers an application (RTPAppIntf) with the RTP session. The session will call receiveData() on the supplied instance whenever data has been received. Following this you should set the payload type and add participants to the session.

Parameters:
rtpApp - an object that implements the RTPAppIntf-interface
rtcpApp - an object that implements the RTCPAppIntf-interface (optional)
Returns:
-1 if this RTPSession-instance already has an application registered.

sendData

public long[] sendData(byte[] buf)
Send data to all participants registered as receivers, using the current timeStamp, dynamic sequence number and the current payload type specified for the session.

Parameters:
buf - A buffer of bytes, less than 1496 bytes
Returns:
null if there was a problem, {RTP Timestamp, Sequence number} otherwise

sendData

public long[] sendData(byte[] buf,
                       long rtpTimestamp,
                       long seqNum)
Send data to all participants registered as receivers, using the specified timeStamp, sequence number and the current payload type specified for the session.

Parameters:
buf - A buffer of bytes, less than 1496 bytes
rtpTimestamp - the RTP timestamp to be used in the packet
seqNum - the sequence number to be used in the packet
Returns:
null if there was a problem, {RTP Timestamp, Sequence number} otherwise

sendData

public long[][] sendData(byte[][] buffers,
                         long[] csrcArray,
                         boolean[] markers,
                         long rtpTimestamp,
                         long[] seqNumbers)
Send data to all participants registered as receivers, using the current timeStamp and payload type. The RTP timestamp will be the same for all the packets.

Parameters:
buffers - A buffer of bytes, should not bed padded and less than 1500 bytes on most networks.
csrcArray - an array with the SSRCs of contributing sources
markers - An array indicating what packets should be marked. Rarely anything but the first one
rtpTimestamp - The RTP timestamp to be applied to all packets
seqNumbers - An array with the sequence number associated with each byte[]
Returns:
null if there was a problem sending the packets, 2-dim array with {RTP Timestamp, Sequence number}

sendRTCPAppPacket

public int sendRTCPAppPacket(long ssrc,
                             int type,
                             byte[] name,
                             byte[] data)
Send RTCP App packet to receiver specified by ssrc Return values: 0 okay -1 no RTCP session established -2 name is not byte[4]; -3 data is not byte[x], where x = 4*y for syme y -4 type is not a 5 bit unsigned integer Note that a return value of 0 does not guarantee delivery. The participant must also exist in the participant database, otherwise the message will eventually be deleted.

Parameters:
ssrc - of the participant you want to reach
type - the RTCP App packet subtype, default 0
name - the ASCII (in byte[4]) representation
data - the data itself
Returns:
0 if okay, negative value otherwise (see above)

addParticipant

public int addParticipant(Participant p)
Add a participant object to the participant database. If packets have already been received from this user, we will try to update the automatically inserted participant with the information provided here.

Parameters:
p - A participant.

removeParticipant

public void removeParticipant(Participant p)
Remove a participant from the database. All buffered packets will be destroyed.

Parameters:
p - A participant.

getUnicastReceivers

public java.util.Iterator<Participant> getUnicastReceivers()

getParticipants

public java.util.Enumeration<Participant> getParticipants()

endSession

public void endSession()
End the RTP Session. This will halt all threads and send bye-messages to other participants. RTCP related threads may require several seconds to wake up and terminate.


isEnding

boolean isEnding()
Check whether this session is ending.

Returns:
true if session and associated threads are terminating.

CNAME

public void CNAME(java.lang.String cname)
Overrides CNAME, used for outgoing RTCP packets.

Parameters:
cname - a string, e.g. username@hostname. Must be unique for session.

CNAME

public java.lang.String CNAME()
Get the current CNAME, used for outgoing SDES packets


getSsrc

public long getSsrc()

generateCNAME

private void generateCNAME()

updateRTPSock

public int updateRTPSock(java.net.DatagramSocket newSock)
Change the RTP socket of the session. Peers must be notified through SIP or other signalling protocol. Only valid if this is a unicast session to begin with.

Parameters:
newSock - integer for new port number, check it is free first.

updateRTCPSock

public int updateRTCPSock(java.net.DatagramSocket newSock)
Change the RTCP socket of the session. Peers must be notified through SIP or other signalling protocol. Only valid if this is a unicast session to begin with.

Parameters:
newSock - the new unicast socket for RTP communication.

updateRTPSock

public int updateRTPSock(java.net.MulticastSocket newSock)
Change the RTP multicast socket of the session. Peers must be notified through SIP or other signalling protocol. Only valid if this is a multicast session to begin with.

Parameters:
newSock - the new multicast socket for RTP communication.

updateRTCPSock

public int updateRTCPSock(java.net.MulticastSocket newSock)
Change the RTCP multicast socket of the session. Peers must be notified through SIP or other signalling protocol. Only valid if this is a multicast session to begin with.

Parameters:
newSock - the new multicast socket for RTCP communication.

payloadType

public int payloadType(int payloadT)
Update the payload type used for the session. It is represented as a 7 bit integer, whose meaning must be negotiated elsewhere (see IETF RFCs 3550 and 3551)

Parameters:
payloadT - an integer representing the payload type of any subsequent packets that are sent.

payloadType

public int payloadType()
Get the payload type that is currently used for outgoing RTP packets.

Returns:
payload type as integer

naivePktReception

public void naivePktReception(boolean doAccept)
Should packets from unknown participants be returned to the application? This can be dangerous.

Parameters:
doAccept - packets from participants not added by the application.

naivePktReception

public boolean naivePktReception()
Are packets from unknown participants returned to the application?

Returns:
whether we accept packets from participants not added by the application.

packetBufferBehavior

public int packetBufferBehavior(int behavior)
Set the number of RTP packets that should be buffered when a packet is missing or received out of order. Setting this number high increases the chance of correctly reordering packets, but increases latency when a packet is dropped by the network. Packets that arrive in order are not affected, they are passed straight to the application. The maximum delay is numberofPackets * packet rate , where the packet rate depends on the codec and profile used by the sender. Valid values: >0 - The maximum number of packets (based on RTP Timestamp) that may accumulate 0 - All valid packets received in order will be given to the application -1 - All valid packets will be given to the application

Parameters:
behavior - the be
Returns:
the behavior set, unchanged in the case of a erroneous value

packetBufferBehavior

public int packetBufferBehavior()
The number of RTP packets that should be buffered when a packet is missing or received out of order. A high number increases the chance of correctly reordering packets, but increases latency when a packet is dropped by the network. A negative value disables the buffering, out of order packets will simply be dropped.

Returns:
the maximum number of packets that can accumulate before the first is returned

registerAVPFIntf

public int registerAVPFIntf(RTCPAVPFIntf rtcpAVPFIntf,
                            int maxDelay,
                            int earlyThreshold,
                            int regularThreshold)
Set whether the stack should operate in RFC 4585 mode. This will automatically call adjustPacketBufferBehavior(-1), i.e. disable all RTP packet buffering in jlibrtp, and disable frame reconstruction

Parameters:
rtcpAVPFIntf - the in

unregisterAVPFIntf

public void unregisterAVPFIntf()
Unregisters the RTCP AVPF interface, thereby going from RFC 4585 mode to RFC 3550 You still have to adjust packetBufferBehavior() and frameReconstruction.


frameReconstruction

public void frameReconstruction(boolean toggle)
Enable / disable frame reconstruction in the packet buffers. This is only relevant if getPacketBufferBehavior > 0; Default is true.


frameReconstruction

public boolean frameReconstruction()
Whether the packet buffer will attempt to reconstruct packet automatically.

Returns:
the status

sessionBandwidth

public int sessionBandwidth()
The bandwidth currently allocated to the session, in bytes per second. The default is 8000. This value is not enforced and currently only used to calculate the RTCP interval to ensure the control messages do not exceed 5% of the total bandwidth described here. Since the actual value may change a conservative estimate should be used to avoid RTCP flooding. see rtcpBandwidth(void)

Returns:
current bandwidth setting

sessionBandwidth

public int sessionBandwidth(int bandwidth)
Set the bandwidth of the session. See sessionBandwidth(void) for details.

Parameters:
bandwidth - the new value requested, in bytes per second
Returns:
the actual value set

rtcpBandwidth

public int rtcpBandwidth()
RFC 3550 dictates that 5% of the total bandwidth, as set by sessionBandwidth, should be dedicated to RTCP traffic. This This should normally not be done, but is permissible in conjunction with feedback (RFC 4585) and possibly other profiles. Also see sessionBandwidth(void)

Returns:
current RTCP bandwidth setting, -1 means not in use

rtcpBandwidth

public int rtcpBandwidth(int bandwidth)
Set the RTCP bandwidth, see rtcpBandwidth(void) for details. This function must be

Parameters:
bandwidth - the new value requested, in bytes per second or -1 to disable
Returns:
the actual value set

fbPictureLossIndication

public int fbPictureLossIndication(long ssrcMediaSource)
Adds a Picture Loss Indication to the feedback queue

Parameters:
ssrcMediaSource -
Returns:
0 if packet was queued, -1 if no feedback support, 1 if redundant

fbSlicLossIndication

public int fbSlicLossIndication(long ssrcMediaSource,
                                int[] sliFirst,
                                int[] sliNumber,
                                int[] sliPictureId)
Adds a Slice Loss Indication to the feedback queue

Parameters:
ssrcMediaSource -
sliFirst - macroblock (MB) address of the first lost macroblock
sliNumber - number of lost macroblocks
sliPictureId - six least significant bits of the codec-specific identif
Returns:
0 if packet was queued, -1 if no feedback support, 1 if redundant

fbRefPictureSelIndic

public int fbRefPictureSelIndic(long ssrcMediaSource,
                                int bitPadding,
                                int payloadType,
                                byte[] bitString)
Adds a Reference Picture Selection Indication to the feedback queue

Parameters:
ssrcMediaSource -
bitPadding - number of padded bits at end of bitString
payloadType - RTP payload type for codec
bitString - RPSI information as natively defined by the video codec
Returns:
0 if packet was queued, -1 if no feedback support, 1 if redundant

fbAppLayerFeedback

public int fbAppLayerFeedback(long ssrcMediaSource,
                              byte[] bitString)
Adds a Picture Loss Indication to the feedback queue

Parameters:
ssrcMediaSource -
bitString - the original application message
Returns:
0 if packet was queued, -1 if no feedback support, 1 if redundant

fbPictureLossIndication

public int fbPictureLossIndication(long ssrcMediaSource,
                                   int FMT,
                                   int[] PID,
                                   int[] BLP)
Adds a RTP Feedback packet to the feedback queue. These are mostly used for NACKs.

Parameters:
ssrcMediaSource -
FMT - the Feedback Message Subtype
PID - RTP sequence numbers of lost packets
BLP - bitmask of following lost packets, shared index with PID
Returns:
0 if packet was queued, -1 if no feedback support, 1 if redundant

getNextSeqNum

private int getNextSeqNum()
Fetches the next sequence number for RTP packets.

Returns:
the next sequence number

createRandom

private void createRandom()
Initializes a random variable


generateSeqNum

private void generateSeqNum()
Generates a random sequence number


generateSsrc

private void generateSsrc()
Generates a random SSRC


resolveSsrcConflict

protected void resolveSsrcConflict()
Resolve an SSRC conflict. Also increments the SSRC conflict counter, after 5 conflicts it is assumed there is a loop somewhere and the session will terminate.