manual.tex

此代码为jrtplib-2.9库文件

\documentstyle[12pt,a4]{article}

\begin{document}
\title{JRTPLIB (v2.9) -  REFERENCE MANUAL}
\author{Jori Liesenborgs ([e-mail])}
\date{12th July 2004}
\maketitle


\section{General Information}

\subsection{Description}

JRTPLIB (Jori's RTP Library) is an object oriented library for the use of RTP
(Real-Time Transport Protocol). Normally, it should follow the specifications
according to RFC 1889. This textfile describes the classes and functions 
which form the interface of the library. If some of the used terms aren't
clear, you should consult RFC 1889.

\subsection{Author \& contact}

The library was written completely from scratch by Jori Liesenborgs. Any
comments, bugreports, ideas for improvements,... can be sent to the following
e-mail address:	
	[e-mail]

\subsection{Platforms}

The library uses the socket mechanism for network communications. This means
it can be compiled (perhaps with some minor modifications) and used on 
various platforms. It has been tested on a Linux platform and on a Windows
platform (using the Winsock library). It's also known to work on Solaris,
HP-UX, FreeBSD and VxWorks platforms.

\subsection{Important general information}

All of the functions with return type 'int', return 0 or more on success. 
Thus, with these functions an error is always indicated by a negative number.

\subsection{What the library doesn't do}

An important remark is that the library will not necessarily filter out 
duplicate packets. The packets from one sender which are in the received packets
queue after a call to 'Poll', won't be duplicates of other packets in the queue.
Once out of the queue, however, there is no guarantee that some accepted packet 
won't have been received already. 
There is a good reason for this: the application using the library probably has
more information about which packets are expected. Using this information it's 
possible to filter out duplicate packets using less memory than would be 
required inside the library.

\subsection{Copyright \& disclaimer}

  Permission is hereby granted, free of charge, to any person obtaining a
  copy of this software and associated documentation files (the "Software"),
  to deal in the Software without restriction, including without limitation
  the rights to use, copy, modify, merge, publish, distribute, sublicense,
  and/or sell copies of the Software, and to permit persons to whom the
  Software is furnished to do so, subject to the following conditions:\\

  The above copyright notice and this permission notice shall be included
  in all copies or substantial portions of the Software.\\

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  IN THE SOFTWARE.

\section{class RTPSession}

\subsection{Description}

This class is used to set up a RTP session.

\subsection{Member functions}

\begin{itemize}
\item {\tt int Create(int localportbase)}\\
	This function attempts to create a RTP session with a given portbase.
	It creates an initial timestamp and an initial packet sequence
	number. It also creates a local synchronization source identifier
	(SSRC). When doing this, the list of illegal SSRCs is checked. This
	list can be modified by the functions AddIllegalLocalSSRC,
	DeleteIllegalLocalSSRC and ClearInvalidLocalSSRCList. In a newly
	created session, there are no destinations to send the RTP and RTCP
	packets to. Destinations can be set by the functions AddDestination,
	DeleteDestination and ClearDestinations.

\item {\tt int GetPortBase()}\\
	Returns the portbase of this session.

\item {\tt int GetLocalSSRC(unsigned long *ssrc)}\\
	This function retrieves the local synchronization source identifier.

\item {\tt int Destroy()}\\
	Destroys the session. All info is destroyed, including destinations,
	default values for SendPacket, invalid local SSRC values,...	

\item {\tt int GetRTPSocket(RTPSOCKET *sock)}\\
	Retrieves the RTP socket (used for receiving RTP data). This way,
	the socket can be used outside the library. A practical use would be
	in the 'select' function.

\item {\tt int GetRTCPSocket(RTPSOCKET *sock)}\\
	Retrieves the RTCP socket (used for receiving RTCP data). This way,
	the socket can be used outside the library. A practical use would
	be in the 'select' function.

\item {\tt int GetSendSocket(RTPSOCKET *sock)}\\
	Retrieves the socket which is used for sending the RTP data. This
	way, the socket can be used outside the library. A practical use
	would be in the 'select' function.

\item {\tt int GetSendPort()}\\
	Retrieves the port to which the sending socket was bound.

\item {\tt int GetLocalIP(unsigned long *ip)}\\
 	Puts the local IP address which is used by the library in 'ip'.

\item {\tt int SetToS(int tos)}\\
 	Set the IP type of service (ToS) field for outgoing RTP and RTCP
	packets.
 
\item {\tt int AddDestination(unsigned long remoteIP,int remoteportbase)}\\
 	Adds a destination to send RTP and RTCP data to.

\item {\tt int DeleteDestination(unsigned long remoteIP,int remoteportbase)}\\
	Deletes a destination from the list of destinations.
	
\item {\tt void ClearDestinations()}\\
	Clears the list of destinations.

\item {\tt bool SupportsMulticasting()}\\
	Returns 'true' if the library is compiled with multicasting support,
	otherwise the function returns 'false'.

\item {\tt int JoinMulticastGroup(unsigned long mcastIP)}\\
 	This function attempts to join the multicast group specified by the
 	address in 'mcastIP'. Note that you only have to join a multicast
 	group to receive packets which are sent to it. You don't have to be
 	in a group to send packets to it.

\item {\tt int LeaveMulticastGroup(unsigned long mcastIP)}\\
 	This function attempts to leave the multicast group specified by the
 	address in 'mcastIP'

\item {\tt void LeaveAllMulticastGroups()}\\
 	Leaves all multicast groups to which the session was previously joined
 	through the use of JoinMulticastGroup
 	
\item {\tt int SetMulticastTTL(unsigned char ttl)}\\
 	Use this function to change the Time To Live (TTL) field for multicast
 	packets. The TTL field is a field in the IP header which determines
 	the lifetime for a packet (normally, this the maximum number of hops
 	for a packet).
	
\item {\tt int SendPacket(void *data,int len)}\\
	Sends a RTP packet with a payload containing of 'len' bytes of
	'data'. To be able to use this function, you must first set the
	default values for the payload type, the mark bit and the timestamp
	increment value. These default values can be set with the functions
	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement.

\item {\tt int SendPacket(void *data,int len,unsigned char pt,bool mark,unsigned long timestampinc)}\\
	Sends a RTP packet with a payload containing of 'len' bytes of
	'data'. The packet type is specified by 'pt', the mark bit by 'mark'
	and the timestamp increment by 'timestampinc'. The values set by
	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement
	are ignored.
	
\item {\tt int SendPacket(void *data,int len,unsigned short hdrextID,void *hdrextdata,int numhdrextwords)}\\
	Sends a RTP packet with a payload containing of 'len' bytes of
	'data'. To be able to use this function, you must first set the
	default values for the payload type, the mark bit and the timestamp
	increment value. These default values can be set with the functions
	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement.
	This function also causes a RTP header extension to be included in the
	packet. This extension has identifier 'hdrextID' and the length of the
	extension data is specified in 32-bit words by 'numhdrextwords'. The
	data itself is contained in 'hdrextdata'.

\item {\tt int SendPacket(void *data,int len,unsigned char pt,bool mark,unsigned long timestampinc,unsigned short hdrextID,void *hdrextdata,int numhdrextwords)}\\
	Sends a RTP packet with a payload containing of 'len' bytes of
	'data'. The packet type is specified by 'pt', the mark bit by 'mark'
	and the timestamp increment by 'timestampinc'. The values set by
	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement
	are ignored. This function also causes a RTP header extension to be
	included in the packet. This extension has identifier 'hdrextID' and
	the length of the extension data is specified in 32-bit words by
	'numhdrextwords'. The data itself is contained in 'hdrextdata'.

\item {\tt void SetDefaultPayloadType(unsigned char pt)}\\
	Sets the default packet type.

\item {\tt void SetDefaultMark(bool mark)}\\
	Sets the default value for the mark bit.

\item {\tt void SetDefaultTimeStampIncrement(unsigned long inc)}\\
	Sets the default timestamp increment value.

\item {\tt int IncrementTimeStamp(unsigned long inc)}\\
	Increments the current timestamp with value 'inc'.

\item {\tt int IncrementTimeStampDefault()}\\
	Increments the current timestamp with the default value, set by the
	function SetDefaultTimeStampIncrement.

\item {\tt int PollData()}\\
	Checks for data on RTP and RTCP ports. If any data is present, it's
	immediately processed. To retrieve RTP packets or info gathered from
	RTCP packets, you can use the functions GotoFirstSource, GotoNextSource,
	GotoFirstSourceWithData, GotoNextSourceWithData, GetNextPacket,
	GetCurrentSourceInfo and GetSourceInfo. After calling PollData, you
	should always use one of the GotoFirst functions before one of the
	GotoNext functions, as the list of participating sources may have
	changed: sources could have joined the session or may have left the
	session.
	Note that currently own RTCP packets are always discarded.

\item {\tt bool GotoFirstSource()}\\
	This function goes sets a pointer to the first participating source.
	You can use this function to start an iteration over the participating
	sources. It returns 'true' if there are any participating sources,
	otherwise the function returns 'false'.
	
\item {\tt bool GotoNextSource()}\\
	You can use this function to iterate over the participating sources.
	If there is a source that hasn't been processed yet, the function
	returns 'true'. If all sources were covered, 'false' is returned.

\item {\tt bool GotoFirstSourceWithData()}\\
	This function is similar to GotoFirstSource, but it skips sources
	that haven't got any data pending on their input queues. Returns
	'true' is a source with data on its queue exists. Returns 'false'
	otherwise.

\item {\tt bool GotoNextSourceWithData()}\\
	This function is similar to GotoNextSource, but it skips sources
	that haven't got any data pending on their input queues. If there
	aren't any sources left to process 'false' is returned. If another
	source was found, 'true' is returned.

\item {\tt RTPPacket *GetNextPacket()}\\
	When iterating over the participating sources with GotoFirst and
	GotoNext functions, you can use this function to extract a packet
	from the current source's queue. If data is available, the function
	returns an instance of the class RTPPacket containing the data.
	Otherwise, NULL is returned. If a packet is returned, it must be
	destroyed by a call to 'delete' when it is no longer needed.

\item {\tt RTPSourceData *GetCurrentSourceInfo()}\\
	When iterating over the participating sources with GotoFirst and
	GotoNext functions, you can use this function to get information
	about the current source. If the iteration has stopped NULL is
	returned, otherwise the function returns an instance of the class
	RTPSourceData containing the info about the current source.

\item {\tt RTPSourceData *GetSourceInfo(unsigned long ssrc)}\\
	Retrieves information about the participating source with
	synchronization source identifier 'ssrc'. If there is an entry for
	that source, an instance of the class RTPSourceData is returned.
	Otherwise the function returns NULL.

\item {\tt AddInvalidLocalSSRC(unsigned long ssrc)}\\
	Adds the synchronization source identifier 'ssrc' to the list of
	invalid local sychronization source identifiers. This list is checked
	when the local SSRC identifier is created.

\item {\tt int RemoveInvalidLocalSSRC(unsigned long ssrc)}\\
	Removes an entry from the list of invalid local SSRCs.

\item {\tt void ClearInvalidLocalSSRCList()}\\
	Clears the list of invalid local SSRCs.

\item {\tt int AddCSRC(unsigned long csrc)}\\
	Adds an entry to the list of contributing sources. Info about these
	sources can be set with SetCSRC functions.

\item {\tt int DeleteCSRC(unsigned long csrc)}\\
	Deletes an entry from the list of contributing sources.

\item {\tt void ClearCSRCList()}\\
	Clears the list of contributing sources.

\item {\tt int SetReceiveMode(int mode)}\\
	Sets the receive mode. The parameter 'mode' has three legal values:
	\begin{itemize}
	\item RECEIVEMODE\_ALL \\
		Accept all incoming data on RTP and RTCP ports.
	\item RECEIVEMODE\_IGNORESOME \\
		Ignore packets from the ip-port pairs in the ignore list, but
		accept all other packets.		
	\item RECEIVEMODE\_ACCEPTSOME \\
		Ignore all packets, except those whose ip-port origin is
		found in the accept list.
	\end{itemize}
	The ignore list can be modified with the function AddToIgnoreList,
	DeleteFromIgnoreList and ClearIgnoreList. The accept list can be
	modified with AddToAcceptList, DeleteFromAcceptList and