// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef RTP_H

#define RTP_H

#include <es_sock.h>

class TRtpEvent;

class RRtpSession;

class RRtpSendPacket;

class RRtpReceivePacket;

class RRtpReceiveSource;

class RRtpSendSource;

class RRtpHeaderExtension;

class RRtpCSRCs;

class CRtpSession;

class CRtpReceiveSource;

class CRtpSendSource;

class TRtpPacket;

class RRtcpRRPart;

class RRtcpSRPart;

/**

@publishedAll

@released

A set of values that defines the event types that may be handled.

See all variants of the RegisterEventCallbackL() function. 

@see TRtpEvent

*/

enum TRtpEventType

	{

	/** 

	A special event type that is interpreted by all of

	the RegisterEventCallbackL() set of functions to mean that the registered

	callback function is to be called for any event except failure events.

    */

	ERtpAnyEvent = 0,

    /**

    Defines a base value for session events.

    All session event types have values that are greater than this.

    */

	ERtpSessionEventBase = 0x100,

	/**

	An event type that indicates that a session-level error has occurred.

	The event status is a standard Symbian OS error code.

	The callback parameter is used to register interest in only one 

	type of error.

	*/

	ERtpSessionFail      = 0x101, 

	/**

    An event type that indicates that a new stream has been received.

	The event status is the	SSRC of the stream.

	*/

	ERtpNewSource        = 0x102,

	/**

	An event type that indicates that an RTCP RR (Receiver Report) has been

	received.

	The event status is the SSRC of the sender.

	Note - This event type has not been implemented yet.

	*/

	ERtpNewRR            = 0x103,

	/**

	An event type that indicates that a packet bigger than the expected maximum

	has been received.

	When this event occurs, the packet is deleted.

	*/

	ERtpBufferOverflow   = 0x104,

	/**

	An event type that indicates that a packet has been recived that

	is smaller than its header.

	When this event occurs, the packet is deleted.

	*/

	ERtpUndersizedPacket = 0x105,

	/**

	Not an event type, but defines the upper limit for session event

	type values.

    */

	ERtpSessionEventEnd  = 0x1ff,

    /**

    Not an event type but defines a base value for send stream events.

    All send stream event types have values that are greater than this.

    */

	ERtpSendEventBase    = 0x200,

	/**

	An event type that indicates that an error has occurred while sending

	a packet.

	The event status is a standard Symbian OS error code. The callback parameter

	is used only to register interest in one type of error.

	*/

	ERtpSendFail         = 0x201, 

	/**

	An event type that indicates that a send packet operation has succeeded.

	*/

	ERtpSendSucceeded    = 0x202,

	/**

	Not an event type, but defines the upper limit for send stream event 

	type values.

	*/

	ERtpSendEventEnd     = 0x2ff,

    /**

    Not an event type but defines a base value for receive stream events.

    All receive stream event types have values that are greater than this.

    */

	ERtpSourceEventBase  = 0x300,

	/**

	An event type that indicates that an error has occurred.

    The event status is a standard Symbian OS error code. The callback parameter

    is used only to register interest in one type of error.

    */

	ERtpSourceFail       = 0x301,

	/**

	An event type that indicates that an in-sequence packet has been received.

	*/

	ERtpPacketReceived   = 0x302,

	/**

	An event type that indicates that the  codec has changed.

	The event status is the new payload type.

	*/

	ERtpCodecChange      = 0x303,

	/**

	An event type that indicates that a marker packet has arrived.

	*/

	ERtpMarker           = 0x304,

	/**

	An event type that indicates that a misordered packet has arrived.

	*/

	ERtpMisorder         = 0x305,

	/**

	An event type that indicates that a dropout has been detected.

	*/

	ERtpDropout          = 0x306,

	/**

	An event type that indicates that a SDES (Source Description) RTCP packet

	has been received.

	For SDES events, the callback parameter is used to specify the type of 

	SDES. Use a value from TRtpSendPacketType

	The event status is the SSRC of the sender.

	@see RRtpSession::TRtpSendPacketType

	*/

	ERtpSDES             = 0x307, 

	/**

	An event type that indicates that a APP (Application Defined) RTCP packet

	has been received.

	The event status is the SSRC of the sender.

	*/

	ERtpAPP              = 0x308,

	/**

	An event type that indicates that a SR (Sender Report) RTCP packet

	has been received.

	The event status is the SSRC of the sender.

	*/

	ERtpSR               = 0x309,

	/**

	An event type that indicates that a RR (Receiver Report) RTCP packet

	has been received.

	The event status is the SSRC of the sender.

	*/

	ERtpRR               = 0x30a,

	/**

	An event type that indicates that a BYE (Goodbye) RTCP packet

	has been received.

	The event status is the SSRC of the sender.

	*/

	ERtpBYE              = 0x30b,

	/**

	Not an event type, but defines the upper limit for receive stream event 

	type values.

	*/

	ERtpSourceEventEnd   = 0x3ff

	};

/**

@publishedAll

@released

Indicates whether a callback function can be called once, or more than once.

The appropriate enum value is passed as an argument to the

RegisterEventCallbackL() functions of RRtpSession, RRtpSendSource,

and RRtpReceiveSource, or to the equivalent static functions.

@see RRtpSession

@see RRtpSendSource

@see RRtpReceiveSource

*/

enum TRtpOneShotness 

	{

	/**

	Indicates that the call back function can be called more than once.

	*/

	ERtpNotOneShot = 0,

	/**

	Indicates that the call back function is only called once.

	*/

	ERtpOneShot = 0x40000000

	};

/**

@publishedAll

*/

typedef void (*TRtpCallbackFunction)(TAny* aPtr, const TRtpEvent& aEvent);

/**

@internalComponent

*/

const TInt KRtpNoParameter = KRequestPending;

//Needed for recv-only option for RTP or RTCP

//This must map to TRtpType

enum TPacketType

	{	

	EPacketRtp,	

	EPacketRtcp

	};

/**

@publishedAll

@released

A value that can be passed as the second parameter in a call to either

RRtpSendSource::NewSendPacketL() or RRtpSendSource::NewSendPacketLC()

to indicate that no exension is required for the RTP send packet.

*/

const TInt KRtpNoExtension = -1;

/**

@publishedAll

@released

A handle to an RTP session.

This is the interface to the socket-level RTP service, and provides additional

facilities such as header parsing, re-ordering out-of-order packets,

demultiplexing multiple sources etc.

The class abstracts all RTP information going to/from a RTP socket, and its

corresponding RTCP data.

Each RTP endpoint on a device needs its own RTP session.

Multiple hosts streaming to a port on this device correspond

to different RRtpReceiveSource objects associated with the session.

The class behaviour assumes that an active scheduler has already been created

and started; the class does not function correctly if not.

*/

class RRtpSession

	{

 public:

    /**

    A set of bit values passed as a parameter to RRtpSession::SendRTCPPacketL()

    to specify the SDES (Source Description) items that are to be sent with

    the packet. One or more of these may be set.

    @see RRtpSession::SendRTCPPacketL()

	*/

	enum TRtpSendPacketType

		{

        /**

        Canonical End-Point Identifier SDES Item.

        */

		ERtcpPacketCNAME = 1, 

		/**

        User Name SDES Item.

	    */

		ERtcpPacketNAME  = 2, 

	    /**

        Electronic Mail Address SDES Item.

	    */

		ERtcpPacketEMAIL = 4, 

        /**

	    Phone Number SDES Item.

	    */		

		ERtcpPacketPHONE = 8, 

		/**

	    Geographic User Location SDES Item.

	    */

		ERtcpPacketLOC   = 16,

		/**

        Application or Tool Name SDES Item 

	    */

		ERtcpPacketTOOL  = 32,

		/**

	    Notice/Status SDES Item 

	    */

		ERtcpPacketNOTE  = 64,

		/**

	    Private Extensions SDES Item 

	    */

		ERtcpPacketPRIV  = 128

		};

	inline RRtpSession();

	inline TBool IsOpen() const;

	IMPORT_C void OpenL(RSocketServ& aServer, TSockAddr& aLocalAddr,

						TSockAddr& aRemoteAddr,

						TInt aMaxRXSize, RConnection& aConnection, TInt aPriority = EPriorityNormal, 

						const TDesC8& aCNAME = KNullDesC8);

	IMPORT_C void OpenL(RSocketServ& aServer, TSockAddr& aLocalAddr,

						TSockAddr& aRemoteAddr,

						TInt aMaxRXSize, TInt aPriority = EPriorityNormal, 

						const TDesC8& aCNAME = KNullDesC8);

    /**

	@publishedPartner

	@released

    Opens the session and initialises it.

    No events will be generated until after control returns to the

    active scheduler. The client has this time to initialise the

    object by adding event callbacks.

    @param aSocket     The connected socket.

    @param aMaxRXSize  The maximum size of a received packet.

    @param aRtcpSocket The RTCP socket.

    @param aPriority   The priority to be used for internal active objects

    @param aCNAME      The CNAME. A sensible default is supplied if none is

                       provided.

    */

	IMPORT_C void OpenL(RSocket& aSocket, TInt aMaxRXSize, 

						RSocket& aRtcpSocket,

						TInt aPriority = EPriorityNormal, 

						const TDesC8& aCNAME = KNullDesC8);

	IMPORT_C void OpenL(RSocket& aSocket, TInt aMaxRXSize,

						TInt aPriority = EPriorityNormal);

	IMPORT_C void Close();

	IMPORT_C void SetMaxRXSize(TInt aMaxRXSize);

	IMPORT_C TInt MaxRXSize();

    /** 

	@publishedPartner

	@released

    Sets the estimated bandwidth used by the session.

    This is used to decide when to send RTCP status packets.

    The default	value is read from a resource file and should be a reasonably

	sensible default based on the maximum bandwidth of the handset.

	@param aBandwidth The bandwidth in bps.

    */

	IMPORT_C void SetBandwidth(TUint aBandwidth);

    /**

	@publishedPartner

	@released

   	Supplies information about the profile-specific RTP

    timestamps. 

    This is used to generate the RTP timestamps in RTCP packets.

    It is not used to generate timestamps in RTP packets as they must

    accurately relate to the time of the sample.

   	@param aNow        The time now in RTP format

	@param aConversion The number of nanoseconds per RTP timer tick.

    */

	IMPORT_C void SetRTPTimeConversion(TUint aNow, TUint aConversion);

	IMPORT_C RRtpReceiveSource NewReceiveSourceL();

	IMPORT_C RRtpReceiveSource NewReceiveSourceLC();

    /**

    Registers a callback for the specified event.

	Some compilers may not support templated member functions. A static version

	of this function is available that offers the same behaviour:

    RegisterEventCallbackL(RRtpSession,TRtpEventType,void (*aCallback)(T*, const TRtpEvent&),T*,TRtpOneShotness,TInt)

    @param aType      The type of event.

    @param aCallback  The callback function. The function is templated, and is

                      prototyped to take a pointer to an object of the template

                      type and a const reference to a TRtpEvent. The function

                      returns void.

	@param aPtr       A pointer that is passed to the callback function when

	                  that function is called.

	@param aOneShot   Indicates whether the callback function is only

	                  called once, or can be called more than once.

	@param aParameter A parameter to be passed to the registration function.