jrtplib  3.7.1
Public Member Functions | Protected Member Functions | List of all members
RTPSession Class Reference

High level class for using RTP. More...

#include <rtpsession.h>

Inherits RTPMemoryObject.

Public Member Functions

 RTPSession (RTPMemoryManager *mgr=0)
 Constructs an RTPSession instance, optionally installing a memory manager. More...
 
int Create (const RTPSessionParams &sessparams, const RTPTransmissionParams *transparams=0, RTPTransmitter::TransmissionProtocol proto=RTPTransmitter::IPv4UDPProto)
 Creates an RTP session. More...
 
int Create (const RTPSessionParams &sessparams, RTPTransmitter *transmitter)
 Creates an RTP session using transmitter as transmission component. More...
 
void Destroy ()
 Leaves the session without sending a BYE packet. More...
 
void BYEDestroy (const RTPTime &maxwaittime, const void *reason, size_t reasonlength)
 Sends a BYE packet and leaves the session. More...
 
bool IsActive ()
 Returns whether the session has been created or not. More...
 
uint32_t GetLocalSSRC ()
 Returns our own SSRC. More...
 
int AddDestination (const RTPAddress &addr)
 Adds addr to the list of destinations. More...
 
int DeleteDestination (const RTPAddress &addr)
 Deletes addr from the list of destinations. More...
 
void ClearDestinations ()
 Clears the list of destinations. More...
 
bool SupportsMulticasting ()
 Returns true if multicasting is supported. More...
 
int JoinMulticastGroup (const RTPAddress &addr)
 Joins the multicast group specified by addr. More...
 
int LeaveMulticastGroup (const RTPAddress &addr)
 Leaves the multicast group specified by addr. More...
 
void LeaveAllMulticastGroups ()
 Leaves all multicast groups. More...
 
int SendPacket (const void *data, size_t len)
 Sends the RTP packet with payload data which has length len. More...
 
int SendPacket (const void *data, size_t len, uint8_t pt, bool mark, uint32_t timestampinc)
 Sends the RTP packet with payload data which has length len. More...
 
int SendPacketEx (const void *data, size_t len, uint16_t hdrextID, const void *hdrextdata, size_t numhdrextwords)
 Sends the RTP packet with payload data which has length len. More...
 
int SendPacketEx (const void *data, size_t len, uint8_t pt, bool mark, uint32_t timestampinc, uint16_t hdrextID, const void *hdrextdata, size_t numhdrextwords)
 Sends the RTP packet with payload data which has length len. More...
 
int SendRTCPAPPPacket (uint8_t subtype, const uint8_t name[4], const void *appdata, size_t appdatalen)
 If sending of RTCP APP packets was enabled at compile time, this function creates a compound packet containing an RTCP APP packet and sends it immediately. More...
 
int SetDefaultPayloadType (uint8_t pt)
 Sets the default payload type for RTP packets to pt. More...
 
int SetDefaultMark (bool m)
 Sets the default marker for RTP packets to m. More...
 
int SetDefaultTimestampIncrement (uint32_t timestampinc)
 Sets the default value to increment the timestamp with to timestampinc. More...
 
int IncrementTimestamp (uint32_t inc)
 This function increments the timestamp with the amount given by inc. More...
 
int IncrementTimestampDefault ()
 This function increments the timestamp with the amount given set by the SetDefaultTimestampIncrement member function. More...
 
int SetPreTransmissionDelay (const RTPTime &delay)
 This function allows you to inform the library about the delay between sampling the first sample of a packet and sending the packet. More...
 
RTPTransmissionInfoGetTransmissionInfo ()
 This function returns an instance of a subclass of RTPTransmissionInfo which will give some additional information about the transmitter (a list of local IP addresses for example). More...
 
void DeleteTransmissionInfo (RTPTransmissionInfo *inf)
 Frees the memory used by the transmission information inf. More...
 
int Poll ()
 If you're not using the poll thread, this function must be called regularly to process incoming data and to send RTCP data when necessary.
 
int WaitForIncomingData (const RTPTime &delay, bool *dataavailable=0)
 Waits at most a time delay until incoming data has been detected. More...
 
int AbortWait ()
 If the previous function has been called, this one aborts the waiting (only works when you're not using the poll thread).
 
RTPTime GetRTCPDelay ()
 Returns the time interval after which an RTCP compound packet may have to be sent (only works when you're not using the poll thread.
 
int BeginDataAccess ()
 The following member functions (till EndDataAccess}) need to be accessed between a call to BeginDataAccess and EndDataAccess. More...
 
bool GotoFirstSource ()
 Starts the iteration over the participants by going to the first member in the table. More...
 
bool GotoNextSource ()
 Sets the current source to be the next source in the table. More...
 
bool GotoPreviousSource ()
 Sets the current source to be the previous source in the table. More...
 
bool GotoFirstSourceWithData ()
 Sets the current source to be the first source in the table which has RTPPacket instances that we haven't extracted yet. More...
 
bool GotoNextSourceWithData ()
 Sets the current source to be the next source in the table which has RTPPacket instances that we haven't extracted yet. More...
 
bool GotoPreviousSourceWithData ()
 Sets the current source to be the previous source in the table which has RTPPacket instances that we haven't extracted yet. More...
 
RTPSourceDataGetCurrentSourceInfo ()
 Returns the RTPSourceData instance for the currently selected participant. More...
 
RTPSourceDataGetSourceInfo (uint32_t ssrc)
 Returns the RTPSourceData instance for the participant identified by ssrc, or NULL if no such entry exists.
 
RTPPacketGetNextPacket ()
 Extracts the next packet from the received packets queue of the current participant, or NULL if no more packets are available. More...
 
void DeletePacket (RTPPacket *p)
 Frees the memory used by p. More...
 
int EndDataAccess ()
 See BeginDataAccess. More...
 
int SetReceiveMode (RTPTransmitter::ReceiveMode m)
 Sets the receive mode to m. More...
 
int AddToIgnoreList (const RTPAddress &addr)
 Adds addr to the list of addresses to ignore. More...
 
int DeleteFromIgnoreList (const RTPAddress &addr)
 Deletes addr from the list of addresses to ignore. More...
 
void ClearIgnoreList ()
 Clears the list of addresses to ignore. More...
 
int AddToAcceptList (const RTPAddress &addr)
 Adds addr to the list of addresses to accept. More...
 
int DeleteFromAcceptList (const RTPAddress &addr)
 Deletes addr from the list of addresses to accept. More...
 
void ClearAcceptList ()
 Clears the list of addresses to accept. More...
 
int SetMaximumPacketSize (size_t s)
 Sets the maximum allowed packet size to s. More...
 
int SetSessionBandwidth (double bw)
 Sets the session bandwidth to bw, which is specified in bytes per second. More...
 
int SetTimestampUnit (double u)
 Sets the timestamp unit for our own data. More...
 
void SetNameInterval (int count)
 Sets the RTCP interval for the SDES name item. More...
 
void SetEMailInterval (int count)
 Sets the RTCP interval for the SDES e-mail item. More...
 
void SetLocationInterval (int count)
 Sets the RTCP interval for the SDES location item. More...
 
void SetPhoneInterval (int count)
 Sets the RTCP interval for the SDES phone item. More...
 
void SetToolInterval (int count)
 Sets the RTCP interval for the SDES tool item. More...
 
void SetNoteInterval (int count)
 Sets the RTCP interval for the SDES note item. More...
 
int SetLocalName (const void *s, size_t len)
 Sets the SDES name item for the local participant to the value s with length len. More...
 
int SetLocalEMail (const void *s, size_t len)
 Sets the SDES e-mail item for the local participant to the value s with length len. More...
 
int SetLocalLocation (const void *s, size_t len)
 Sets the SDES location item for the local participant to the value s with length len. More...
 
int SetLocalPhone (const void *s, size_t len)
 Sets the SDES phone item for the local participant to the value s with length len. More...
 
int SetLocalTool (const void *s, size_t len)
 Sets the SDES tool item for the local participant to the value s with length len. More...
 
int SetLocalNote (const void *s, size_t len)
 Sets the SDES note item for the local participant to the value s with length len. More...
 

Protected Member Functions

virtual RTPTransmitterNewUserDefinedTransmitter ()
 Allocate a user defined transmitter. More...
 
virtual void OnRTPPacket (RTPPacket *pack, const RTPTime &receivetime, const RTPAddress *senderaddress)
 Is called when an incoming RTCP packet is about to be processed. More...
 
virtual void OnRTCPCompoundPacket (RTCPCompoundPacket *pack, const RTPTime &receivetime, const RTPAddress *senderaddress)
 Is called when an incoming RTCP packet is about to be processed. More...
 
virtual void OnSSRCCollision (RTPSourceData *srcdat, const RTPAddress *senderaddress, bool isrtp)
 Is called when an SSRC collision was detected. More...
 
virtual void OnCNAMECollision (RTPSourceData *srcdat, const RTPAddress *senderaddress, const uint8_t *cname, size_t cnamelength)
 Is called when another CNAME was received than the one already present for source srcdat. More...
 
virtual void OnNewSource (RTPSourceData *srcdat)
 Is called when a new entry srcdat is added to the source table. More...
 
virtual void OnRemoveSource (RTPSourceData *srcdat)
 Is called when the entry srcdat is about to be deleted from the source table. More...
 
virtual void OnTimeout (RTPSourceData *srcdat)
 Is called when participant srcdat is timed out. More...
 
virtual void OnBYETimeout (RTPSourceData *srcdat)
 Is called when participant srcdat is timed after having sent a BYE packet. More...
 
virtual void OnAPPPacket (RTCPAPPPacket *apppacket, const RTPTime &receivetime, const RTPAddress *senderaddress)
 Is called when an RTCP APP packet apppacket has been received at time receivetime from address senderaddress.
 
virtual void OnUnknownPacketType (RTCPPacket *rtcppack, const RTPTime &receivetime, const RTPAddress *senderaddress)
 Is called when an unknown RTCP packet type was detected. More...
 
virtual void OnUnknownPacketFormat (RTCPPacket *rtcppack, const RTPTime &receivetime, const RTPAddress *senderaddress)
 Is called when an unknown packet format for a known packet type was detected. More...
 
virtual void OnNoteTimeout (RTPSourceData *srcdat)
 Is called when the SDES NOTE item for source srcdat has been timed out. More...
 
virtual void OnBYEPacket (RTPSourceData *srcdat)
 Is called when a BYE packet has been processed for source srcdat. More...
 
virtual void OnSendRTCPCompoundPacket (RTCPCompoundPacket *pack)
 Is called when an RTCP compound packet has just been sent (useful to inspect outgoing RTCP data). More...
 
virtual void OnPollThreadError (int errcode)
 Is called when error errcode was detected in the poll thread. More...
 
virtual void OnPollThreadStep ()
 Is called each time the poll thread loops. More...
 

Detailed Description

For most RTP based applications, the RTPSession class will probably be the one to use. It handles the RTCP part completely internally, so the user can focus on sending and receiving the actual data.

Note
The RTPSession class is not meant to be thread safe. The user should use some kind of locking mechanism to prevent different threads from using the same RTPSession instance.

Constructor & Destructor Documentation

RTPSession::RTPSession ( RTPMemoryManager mgr = 0)

Member Function Documentation

int RTPSession::AddDestination ( const RTPAddress addr)
int RTPSession::AddToAcceptList ( const RTPAddress addr)
int RTPSession::AddToIgnoreList ( const RTPAddress addr)
int RTPSession::BeginDataAccess ( )

The BeginDataAccess function makes sure that the poll thread won't access the source table at the same time that you're using it. When the EndDataAccess is called, the lock on the source table is freed again.

void RTPSession::BYEDestroy ( const RTPTime maxwaittime,
const void *  reason,
size_t  reasonlength 
)

Sends a BYE packet and leaves the session. At most a time maxwaittime will be waited to send the BYE packet. If this time expires, the session will be left without sending a BYE packet. The BYE packet will contain as reason for leaving reason with length reasonlength.

void RTPSession::ClearAcceptList ( )
void RTPSession::ClearDestinations ( )
void RTPSession::ClearIgnoreList ( )
int RTPSession::Create ( const RTPSessionParams sessparams,
const RTPTransmissionParams transparams = 0,
RTPTransmitter::TransmissionProtocol  proto = RTPTransmitter::IPv4UDPProto 
)

This function creates an RTP session with parameters sessparams, which will use a transmitter corresponding to proto. Parameters for this transmitter can be specified as well. If proto is of type RTPTransmitter::UserDefinedProto, the NewUserDefinedTransmitter function must be implemented.

int RTPSession::Create ( const RTPSessionParams sessparams,
RTPTransmitter transmitter 
)

This function creates an RTP session with parameters sessparams, which will use the transmission component transmitter. Initialization and destruction of the transmitter will not be done by the RTPSession class if this Create function is used. This function can be useful if you which to reuse the transmission component in another RTPSession instance, once the original RTPSession isn't using the transmitter anymore.

int RTPSession::DeleteDestination ( const RTPAddress addr)
int RTPSession::DeleteFromAcceptList ( const RTPAddress addr)
int RTPSession::DeleteFromIgnoreList ( const RTPAddress addr)
void RTPSession::DeletePacket ( RTPPacket p)
void RTPSession::DeleteTransmissionInfo ( RTPTransmissionInfo inf)
void RTPSession::Destroy ( )
int RTPSession::EndDataAccess ( )
RTPSourceData* RTPSession::GetCurrentSourceInfo ( )
uint32_t RTPSession::GetLocalSSRC ( )
RTPPacket* RTPSession::GetNextPacket ( )

Extracts the next packet from the received packets queue of the current participant, or NULL if no more packets are available. When the packet is no longer needed, its memory should be freed using the DeletePacket member function.

RTPTransmissionInfo* RTPSession::GetTransmissionInfo ( )

This function returns an instance of a subclass of RTPTransmissionInfo which will give some additional information about the transmitter (a list of local IP addresses for example). The user has to free the returned instance when it is no longer needed, preferably using the DeleteTransmissionInfo function.

bool RTPSession::GotoFirstSource ( )

Starts the iteration over the participants by going to the first member in the table. If a member was found, the function returns true, otherwise it returns false.

bool RTPSession::GotoFirstSourceWithData ( )

Sets the current source to be the first source in the table which has RTPPacket instances that we haven't extracted yet. If no such member was found, the function returns false, otherwise it returns true.

bool RTPSession::GotoNextSource ( )

Sets the current source to be the next source in the table. If we're already at the last source, the function returns false, otherwise it returns true.

bool RTPSession::GotoNextSourceWithData ( )

Sets the current source to be the next source in the table which has RTPPacket instances that we haven't extracted yet. If no such member was found, the function returns false, otherwise it returns true.

bool RTPSession::GotoPreviousSource ( )

Sets the current source to be the previous source in the table. If we're at the first source, the function returns false, otherwise it returns true.

bool RTPSession::GotoPreviousSourceWithData ( )

Sets the current source to be the previous source in the table which has RTPPacket instances that we haven't extracted yet. If no such member was found, the function returns false, otherwise it returns true.

int RTPSession::IncrementTimestamp ( uint32_t  inc)

This function increments the timestamp with the amount given by inc. This can be useful if, for example, a packet was not sent because it contained only silence. Then, this function should be called to increment the timestamp with the appropriate amount so that the next packets will still be played at the correct time at other hosts.

int RTPSession::IncrementTimestampDefault ( )

This function increments the timestamp with the amount given set by the SetDefaultTimestampIncrement member function. This can be useful if, for example, a packet was not sent because it contained only silence. Then, this function should be called to increment the timestamp with the appropriate amount so that the next packets will still be played at the correct time at other hosts.

bool RTPSession::IsActive ( )
int RTPSession::JoinMulticastGroup ( const RTPAddress addr)
void RTPSession::LeaveAllMulticastGroups ( )
int RTPSession::LeaveMulticastGroup ( const RTPAddress addr)
virtual RTPTransmitter* RTPSession::NewUserDefinedTransmitter ( )
inlineprotectedvirtual

In case you specified in the Create function that you want to use a user defined transmitter, you should override this function. The RTPTransmitter instance returned by this function will then be used to send and receive RTP and RTCP packets. Note that when the session is destroyed, this RTPTransmitter instance will be destroyed as well.

virtual void RTPSession::OnBYEPacket ( RTPSourceData srcdat)
inlineprotectedvirtual
virtual void RTPSession::OnBYETimeout ( RTPSourceData srcdat)
inlineprotectedvirtual
virtual void RTPSession::OnCNAMECollision ( RTPSourceData srcdat,
const RTPAddress senderaddress,
const uint8_t *  cname,
size_t  cnamelength 
)
inlineprotectedvirtual
virtual void RTPSession::OnNewSource ( RTPSourceData srcdat)
inlineprotectedvirtual
virtual void RTPSession::OnNoteTimeout ( RTPSourceData srcdat)
inlineprotectedvirtual
virtual void RTPSession::OnPollThreadError ( int  errcode)
inlineprotectedvirtual
virtual void RTPSession::OnPollThreadStep ( )
inlineprotectedvirtual

Is called each time the poll thread loops. This happens when incoming data was detected or when it's time to send an RTCP compound packet.

virtual void RTPSession::OnRemoveSource ( RTPSourceData srcdat)
inlineprotectedvirtual
virtual void RTPSession::OnRTCPCompoundPacket ( RTCPCompoundPacket pack,
const RTPTime receivetime,
const RTPAddress senderaddress 
)
inlineprotectedvirtual
virtual void RTPSession::OnRTPPacket ( RTPPacket pack,
const RTPTime receivetime,
const RTPAddress senderaddress 
)
inlineprotectedvirtual
virtual void RTPSession::OnSendRTCPCompoundPacket ( RTCPCompoundPacket pack)
inlineprotectedvirtual
virtual void RTPSession::OnSSRCCollision ( RTPSourceData srcdat,
const RTPAddress senderaddress,
bool  isrtp 
)
inlineprotectedvirtual

Is called when an SSRC collision was detected. The instance srcdat is the one present in the table, the address senderaddress is the one that collided with one of the addresses and isrtp indicates against which address of srcdat the check failed.

virtual void RTPSession::OnTimeout ( RTPSourceData srcdat)
inlineprotectedvirtual
virtual void RTPSession::OnUnknownPacketFormat ( RTCPPacket rtcppack,
const RTPTime receivetime,
const RTPAddress senderaddress 
)
inlineprotectedvirtual
virtual void RTPSession::OnUnknownPacketType ( RTCPPacket rtcppack,
const RTPTime receivetime,
const RTPAddress senderaddress 
)
inlineprotectedvirtual
int RTPSession::SendPacket ( const void *  data,
size_t  len 
)

Sends the RTP packet with payload data which has length len. The used payload type, marker and timestamp increment will be those that have been set using the SetDefault member functions.

int RTPSession::SendPacket ( const void *  data,
size_t  len,
uint8_t  pt,
bool  mark,
uint32_t  timestampinc 
)

It will use payload type pt, marker mark and after the packet has been built, the timestamp will be incremented by timestampinc.

int RTPSession::SendPacketEx ( const void *  data,
size_t  len,
uint16_t  hdrextID,
const void *  hdrextdata,
size_t  numhdrextwords 
)

The packet will contain a header extension with identifier hdrextID and containing data hdrextdata. The length of this data is given by numhdrextwords and is specified in a number of 32-bit words. The used payload type, marker and timestamp increment will be those that have been set using the SetDefault member functions.

int RTPSession::SendPacketEx ( const void *  data,
size_t  len,
uint8_t  pt,
bool  mark,
uint32_t  timestampinc,
uint16_t  hdrextID,
const void *  hdrextdata,
size_t  numhdrextwords 
)

It will use payload type pt, marker mark and after the packet has been built, the timestamp will be incremented by timestampinc. The packet will contain a header extension with identifier hdrextID and containing data hdrextdata. The length of this data is given by numhdrextwords and is specified in a number of 32-bit words.

int RTPSession::SendRTCPAPPPacket ( uint8_t  subtype,
const uint8_t  name[4],
const void *  appdata,
size_t  appdatalen 
)

If sending of RTCP APP packets was enabled at compile time, this function creates a compound packet containing an RTCP APP packet and sends it immediately. If successful, the function returns the number of bytes in the RTCP compound packet. Note that this immediate sending is not compliant with the RTP specification, so use with care.

int RTPSession::SetDefaultMark ( bool  m)
int RTPSession::SetDefaultPayloadType ( uint8_t  pt)
int RTPSession::SetDefaultTimestampIncrement ( uint32_t  timestampinc)
void RTPSession::SetEMailInterval ( int  count)

After all possible sources in the source table have been processed, the class will check if other SDES items need to be sent. If count is zero or negative, nothing will happen. If count is positive, an SDES e-mail item will be added after the sources in the source table have been processed count times.

int RTPSession::SetLocalEMail ( const void *  s,
size_t  len 
)
int RTPSession::SetLocalLocation ( const void *  s,
size_t  len 
)
int RTPSession::SetLocalName ( const void *  s,
size_t  len 
)
int RTPSession::SetLocalNote ( const void *  s,
size_t  len 
)
int RTPSession::SetLocalPhone ( const void *  s,
size_t  len 
)
int RTPSession::SetLocalTool ( const void *  s,
size_t  len 
)
void RTPSession::SetLocationInterval ( int  count)

After all possible sources in the source table have been processed, the class will check if other SDES items need to be sent. If count is zero or negative, nothing will happen. If count is positive, an SDES location item will be added after the sources in the source table have been processed count times.

int RTPSession::SetMaximumPacketSize ( size_t  s)
void RTPSession::SetNameInterval ( int  count)

After all possible sources in the source table have been processed, the class will check if other SDES items need to be sent. If count is zero or negative, nothing will happen. If count is positive, an SDES name item will be added after the sources in the source table have been processed count times.

void RTPSession::SetNoteInterval ( int  count)

After all possible sources in the source table have been processed, the class will check if other SDES items need to be sent. If count is zero or negative, nothing will happen. If count is positive, an SDES note item will be added after the sources in the source table have been processed count times.

void RTPSession::SetPhoneInterval ( int  count)

After all possible sources in the source table have been processed, the class will check if other SDES items need to be sent. If count is zero or negative, nothing will happen. If count is positive, an SDES phone item will be added after the sources in the source table have been processed count times.

int RTPSession::SetPreTransmissionDelay ( const RTPTime delay)

This function allows you to inform the library about the delay between sampling the first sample of a packet and sending the packet. This delay is taken into account when calculating the relation between RTP timestamp and wallclock time, used for inter-media synchronization.

int RTPSession::SetReceiveMode ( RTPTransmitter::ReceiveMode  m)

Sets the receive mode to m. Note that when the receive mode is changed, the list of addresses to be ignored ot accepted will be cleared.

int RTPSession::SetSessionBandwidth ( double  bw)
int RTPSession::SetTimestampUnit ( double  u)

Sets the timestamp unit for our own data. The timestamp unit is defined as a time interval in seconds divided by the corresponding timestamp interval. For example, for 8000 Hz audio, the timestamp unit would typically be 1/8000. Since this value is initially set to an illegal value, the user must set this to an allowed value to be able to create a session.

void RTPSession::SetToolInterval ( int  count)

After all possible sources in the source table have been processed, the class will check if other SDES items need to be sent. If count is zero or negative, nothing will happen. If count is positive, an SDES tool item will be added after the sources in the source table have been processed count times.

bool RTPSession::SupportsMulticasting ( )
int RTPSession::WaitForIncomingData ( const RTPTime delay,
bool *  dataavailable = 0 
)

Waits at most a time delay until incoming data has been detected. Only works when you're not using the poll thread. If dataavailable is not NULL, it should be set to true if data was actually read and to false otherwise.


The documentation for this class was generated from the following file: