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
 java.lang.String email
          SDES The participant's email
 java.lang.String loc
          SDES The participant's location
 java.lang.String name
          SDES The participant's real name
 java.lang.String note
          SDES A note
 java.lang.String phone
          SDES The participant's phone number
 java.lang.String priv
          SDES A priv string, loosely defined
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.
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.
 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.
 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.
 java.util.Enumeration<Participant> getParticipants()
           
 long getSsrc()
           
 java.util.Iterator<Participant> getUnicastReceivers()
           
 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.
 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
equals, 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

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

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.


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()

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