manual.tex

此代码为jrtplib-2.9库文件

	from the last sender report.

\item {\tt unsigned long SR\_GetByteCount()}\\
	Gets the byte (octet) count of this source according to the
	information from the last sender report.

\item {\tt struct timeval SR\_GetReceiveTime()}\\
 	This returns the time when the last sender report was received. You
 	can use the 'getntptime' function to transform this value into NTP
 	time format, but be careful: this function returns values in network
 	byte order!

\item {\tt bool RR\_HasInfo()}\\
	Returns 'true' if the source has sent any receiver reports about
	the local source. Otherwise it returns false.

\item {\tt float RR\_GetFractionLost()}\\
	Gets the fraction of lost packets which originated from this source.
	This value is calculated from receiver reports.

\item {\tt long RR\_GetPacketsLost()}\\
	Gets the number of lost packets which originated from this source.
	This value is read from receiver reports.
	
\item {\tt unsigned long RR\_GetExtendedHighestSequenceNumber()}\\
	Gets the extended highest sequence number of the packets that this
	source received from the local source. Its value is read from
	receiver reports.

\item {\tt unsigned long RR\_GetJitter()}\\
	Returns the amount of jitter in timestamp units that this source
	noticed when receiving packets from the local source. The value is
	read from receiver reports.

\item {\tt unsigned long RR\_GetLastSRTimestamp()}\\
	Returns the time at which the current source received the last
	sender report from the local source. The high 16 bits are in fact
	the low 16 bits of the most significant 32 bit word of the NTP
	timestamp. The low 16 bits are the high 16 bits of the fractional
	part (32 bits) of the NTP timestamp. So this value is in fact the
	middle 32 bits of the whole 64 bit NTP timestamp. If no sender
	reports were received, the value is zero.

\item {\tt unsigned long RR\_GetDelaySinceLastSR()}\\
	Returns the time that has elapsed since the current source received
	a sender report from the local source. The value is given in
	1/65536 seconds. If no sender reports were received, the value is
	zero.

\item {\tt struct timeval RR\_GetReceiveTime()}\\
 	This returns the time when the last receiver report was received. You
 	can use the 'getntptime' function to transform this value into NTP
 	time format, but be careful: this function returns values in network
 	byte order!
 	
\item {\tt bool INF\_HasSentData()}\\
	Returns 'true' if the current source has sent RTP data. Otherwise
	the function returns 'false'.

\item {\tt long INF\_GetNumPacketsReceived()}\\
	Returns the number of packets received from this source.

\item {\tt unsigned long INF\_GetBaseSequenceNumber()}\\
	The sequence number of RTP packets starts at a random offset. This
	function returns this base sequence number. It is just the lowest
	extended sequence number that was present in RTP packets.

\item {\tt unsigned long INF\_GetExtendedHighestSequenceNumber()}\\
	Returns the extended highest sequence number received from this
	source.
	
\item {\tt unsigned long INF\_GetJitter()}\\
	Returns the amount of jitter in timestamp units that the local
	source noticed when receiving packets from this source.
	
\item {\tt struct timeval INF\_GetRoundTripTime()}\\
	This function gives an approximation of the round-trip-time, as
	suggested in RFC 1889.

\item {\tt char *SDES\_GetCNAME(int *len)}\\
	Returns the CNAME (canonical name) of this source. The length is
	set in 'len'.

\item {\tt char *SDES\_GetName(int *len)}\\
	Returns the name of this source. The length is set in 'len'.

\item {\tt char *SDES\_GetEMail(int *len)}\\
	Returns the email address of this source. The length is set in 'len'.

\item {\tt char *SDES\_GetLocation(int *len)}\\
	Returns the location of this source. The length is set in 'len'.

\item {\tt char *SDES\_GetPhone(int *len)}\\
	Returns the phone number for this source. The length is set in 'len'.

\item {\tt char *SDES\_GetTool(int *len)}\\
	Returns tool information for this source. The length is set in 'len'.

\item {\tt char *SDES\_GetNote(int *len)}\\
	Returns a note from this source. The length is set in 'len'.

\end{itemize}


\section{Exception handlers}

\subsection{Description}

In the class RTPSession, you can set exception handlers for various types
of events. If you look at those functions in the class description, you will
see that all of these function take a parameter of type RTPExceptionHandler
and a paramater of type void (the so called 'usrdata' parameter). The
parameter of type RTPExceptionHandler should be a function with the following
format:\\
\\
{\tt void MyHandler(int exceptiontype,void *exceptiondata,void *usrdata)}\\
\\
You may also use the value NULL for this parameter. In this case, the handler
will be disabled. The parameter 'usrdata' is the pointer that was specified
when the handler was set. The contents of 'exceptiondata' will differ
according to the type of event that has occurred. The possibilities will
be discussed below, together with the possible exception types.

\subsection{Exception types}

When the handler is called, the parameter 'exceptiontype' contains the type
of event that has occurred. These are the posible values:
\begin{itemize}
	\item RTP\_EXCEPTION\_LOCALSSRCCOLLISION\\
		There has been a collision with the local synchronization
		source identifier. The parameter 'exceptiondata' is of type
		RTPExcepSSRCCollision. For a description of the contents,
		see the part about the exception structures.		
	\item RTP\_EXCEPTION\_SSRCCOLLISION\\
		There has been a collision between synchronization source
		identifiers, other than the local identifier. The parameter
		'exceptiondata' is of type RTPExcepSSRCCollision. For a
		description of the contents, see the part about the exception
		structures.		
	\item RTP\_EXCEPTION\_NEWSOURCE\\
		A new source has joined the session. The 'exceptiondata'
		parameter is of type RTPExcepSSRC. For a description of the
		contents, see the part about the exception structures.
	\item RTP\_EXCEPTION\_INVALIDSDESTYPE\\
		A RTCP packet containing an invalid SDES type has arrived. The
		parameter 'exceptiondata' is of type RTPExcepInvalSDESType. For
		a description of the contents, see the part about the exception
		structures.
	\item RTP\_EXCEPTION\_SSRCDEPARTURE\\
		A certain source has left the session. The 'exceptiondata'
		parameter is of type RTPExcepSSRC. For a description of the
		contents, see the part about the exception structures.
	\item RTP\_EXCEPTION\_SSRCTIMEOUT\\
		A certain source has left the session due to a timeout. The
		'exceptiondata' parameter is of type RTPExcepSSRC. For a
		description of the contents, see the part about the exception
		structures.
	\item RTP\_EXCEPTION\_RECEIVERTCPAPPDATA\\
		Application specific data has arrived. The parameter
		'exceptiondata' is of type RTPExcepAppData. For a description
		of the contents, see the part about the exception structures.
	\item RTP\_EXCEPTION\_TRANSMITRTCPAPPDATA\\
		The library asks for application specific data. The parameter
		'exceptiondata' is of type RTPExcepAppData. For a description
		of the contents, see the part about the exception structures.
	\item RTP\_EXCEPTION\_RTCPPACKET\\
		If this handler is enabled, your handler will be called for
		each received RTCP packet. This way, you can examine the raw
		RTCP data yourself if necessary. The parameter 'exceptiondata'
		is of type RTPExcepRTCPPacket. For a description of the
		contents, see the part about the exception structures.
	\end{itemize}
	
\subsection{Structures}

The data that is specified in the parameter 'exceptiondata' is contained in
one of the structures that will be described here. If you want to save the
data, you must make a copy of it somehow, and not just save a pointer to it,
as the data may be altered or deleted after the handler is called. The used
structures are these:
\begin{itemize}

\item {\tt RTPExcepSSRCCollision}\\
	This structure has the following members:
		\begin{itemize}
		
		\item {\tt unsigned long ssrc}\\
			The synchronization source identifier of the colliding
			sources.
		\item {\tt unsigned long ip}\\
			The IP address of the source that caused the collision.
		\item {\tt bool rtpdata}\\
			This member is 'true' if the collision occurred when
			processing RTP data. It is false if it happened while
			processing RTCP data.
		\item {\tt int port}\\
			The port from which the RTP or RTCP data originated.
		\end{itemize}
		
\item {\tt RTPExcepSSRC}\\
	The structure has only one member:
		\begin{itemize}
		\item {\tt unsigned long ssrc}\\
			The sychronization source identifier of a certain source.
		\end{itemize}

\item {\tt RTPExcepInvalSDESType}\\
	The structure has the following members:
		\begin{itemize}
		\item {\tt unsigned long ssrc}\\
			The syncronization source identifier of the source to
			which the source description data belongs.
		\item {\tt int sdestype}\\
			The number of the type that was specified.
		\item {\tt unsigned char *sdesdata}\\
			A pointer to the source description data. The data does
			not include the SDES header.
		\item {\tt int datalen}\\
			The length of the data, in bytes.
		\end{itemize}
		
\item {\tt RTPExcepAppData}\\
	The structure has the following members:
		\begin{itemize}
		\item {\tt unsigned char subtype}\\
			Contains the subtype of the application specific data.
		\item {\tt unsigned long src}\\
			Contains the SSRC or CSRC identifier to which this
			data is relevant.
		\item {\tt unsigned char name[4]}\\
			Specifies a user defined name for this data.
		\item {\tt unsigned char *data}\\
			The data itself.
		\item {\tt int numwords}\\
			The length of the data, specified in 32-bit words.
		\item {\tt bool validdata}\\
			Specifies if the data is valid; only used when the
			library asks for application specific data to send.
		\item {\tt int prevreturnval}\\
			When passing application specific data to the library,
			the library uses this member to tell the handler if
			the previous data was handled correctly. A negative
			value indicates an error.
		\end{itemize}
	Here are some notes about sending and receiving application specific data.
	\begin{itemize}
	\item {\it Receiving application specific data:}\\
		For each RTCP application specific data block, the library
		will call the appropriate handler and will pass an instance
		of the RTPExcepAppData structure. Members 'validdata' and
		'prevreturnval' are not used. The members are in host byte
		order. The data, however, is passed in the exact way as it
		arrived, without doing any conversions (which would be
		impossible anyway, since the library does not know about
		the meaning of that data).
		
	\item {\it Sending application specific data:}\\
		When the handler for sending application specific RTCP data
		has been set, this handler will be called by the library when
		RTCP packets are generated. The library will pass an instance
		of the RTPExcepAppData structure, which the application can
		fill in to specify the data to send. Each time RTCP packets
		are generated, the library will keep calling this handler
		until the RTPExcepAppData member 'validdata' is set to
		'false'. When this is the case, the rest of the structure is
		ignored, so only set it to 'false' when all the application
		specific data has already been sent. The 'prevreturnval'
		indicates if there was an error with the previous data.
		The library sets default values for several members:
		\begin{tabbing}
		0123456701234567\=0123456701234567\kill
			subtype \> 0\\
			src \> own SSRC\\
			name \> four spaces\\
			data \> NULL\\
			numwords \> 0\\
			validdata \> false\\
		\end{tabbing}
		The members should be supplied in host byte order, the library
		will do the necessary conversions. However, the data is passed
		exactly as it was received, since the library can't possibly
		know how to interpret that data.
	\end{itemize}
\item {\tt RTPExcepRTCPPacket}\\
 	The structure has four members:
		\begin{itemize}
		\item {\tt unsigned char *packet}\\
			The raw RTCP packet data. No conversions were done, so
			you'll have to take the endianness into account if you
			want to process the data.
		\item {\tt int packetlen}\\
			The length of the RTCP packet.
		\item {\tt unsigned long sourceip}\\
			The IP address of the sender of the packet.
		\item {\tt int sourceport}\\
			The port from which this packet was sent.
		\end{itemize}

\end{itemize}

\end{document}