manual.txt

此代码为jrtplib-2.9库文件

 - void SR_GetNTPTimestamp(unsigned long *msw,unsigned long *lsw)
	Gets the NTP timestamp that was specified in the last received
	sender report.

 - unsigned long SR_GetRTPTimestamp()
	Gets the timestamp that was last mentioned in a sender report.

 - unsigned long SR_GetPacketCount()
	Gets the packet count of this source according to the information
	from the last sender report.

 - unsigned long SR_GetByteCount()
	Gets the byte (octet) count of this source according to the 
	information from the last sender report.

 - 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!

 - bool RR_HasInfo()
	Returns 'true' if the source has sent any receiver reports about
	the local source. Otherwise it returns false.

 - float RR_GetFractionLost()
	Gets the fraction of lost packets which originated from this source.
	This value is calculated from receiver reports.

 - long RR_GetPacketsLost()
	Gets the number of lost packets which originated from this source.
	This value is read from receiver reports.
	
 - 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.

 - 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.

 - 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.

 - 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.

 - 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!
 	
 - bool INF_HasSentData()
	Returns 'true' if the current source has sent RTP data. Otherwise
	the function returns 'false'.

 - long INF_GetNumPacketsReceived()
	Returns the number of packets received from this source.

 - 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.

 - unsigned long INF_GetExtendedHighestSequenceNumber()
	Returns the extended highest sequence number received from this
	source.
	
 - unsigned long INF_GetJitter()
	Returns the amount of jitter in timestamp units that the local
	source noticed when receiving packets from this source.
	
 - struct timeval INF_GetRoundTripTime()
	This function gives an approximation of the round-trip-time, as
	suggested in RFC 1889.

 - char *SDES_GetCNAME(int *len)
	Returns the CNAME (canonical name) of this source. The length is
	set in 'len'.
 
 - char *SDES_GetName(int *len)
	Returns the name of this source. The length is set in 'len'.
 
 - char *SDES_GetEMail(int *len)
	Returns the email address of this source. The length is set in 'len'.

 - char *SDES_GetLocation(int *len)
	Returns the location of this source. The length is set in 'len'.

 - char *SDES_GetPhone(int *len)
	Returns the phone number for this source. The length is set in 'len'.

 - char *SDES_GetTool(int *len)
	Returns tool information for this source. The length is set in 'len'.

 - char *SDES_GetNote(int *len)
	Returns a note from this source. The length is set in 'len'.



5.    Exception handlers

5.1   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:

	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.

5.2   Exception types

When the handler is called, the parameter 'exceptiontype' contains the type
of event that has occurred. These are the posible values:
	* 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.		
	* 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.		
	* 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.
	* 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.
	* 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.
	* 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.
	* 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.
	* 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.
	* 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.

5.3   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:

 - RTPExcepSSRCCollision
	This structure has the following members:
		* unsigned long ssrc
			The synchronization source identifier of the colliding
			sources.
		* unsigned long ip
			The IP address of the source that caused the collision.
		* bool rtpdata
			This member is 'true' if the collision occurred when
			processing RTP data. It is false if it happened while
			processing RTCP data.
		* int port
			The port from which the RTP or RTCP data originated.

 - RTPExcepSSRC
	The structure has only one member:
		* unsigned long ssrc
			The sychronization source identifier of a certain source.

 - RTPExcepInvalSDESType
	The structure has the following members:
		* unsigned long ssrc
			The syncronization source identifier of the source to 
			which the source description data belongs.
		* int sdestype
			The number of the type that was specified.
		* unsigned char *sdesdata
			A pointer to the source description data. The data does
			not include the SDES header.
		* int datalen
			The length of the data, in bytes.

 - RTPExcepAppData
	The structure has the following members:
		* unsigned char subtype
			Contains the subtype of the application specific data.
		* unsigned long src
			Contains the SSRC or CSRC identifier to which this
			data is relevant.
		* unsigned char name[4]
			Specifies a user defined name for this data.
		* unsigned char *data
			The data itself.
		* int numwords
			The length of the data, specified in 32-bit words.
		* bool validdata
			Specifies if the data is valid; only used when the
			library asks for application specific data to send.
		* 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.
	
	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).
		
	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:
			subtype 	-> 0
			src             -> own SSRC
			name		-> four spaces
			data		-> NULL
			numwords	-> 0
			validdata	-> false
		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.

 - RTPExcepRTCPPacket
 	The structure has four members:
		* 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.
		* int packetlen
			The length of the RTCP packet.
		* unsigned long sourceip
			The IP address of the sender of the packet.
		* int sourceport
			The port from which this packet was sent.
 		
----------------------------------------------------------------------------------