--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ipappprotocols_plat/rtprtcp_api/inc/rtpapi.h Tue Feb 02 01:03:15 2010 +0200
@@ -0,0 +1,565 @@
+/*
+* Copyright (c) 2004-2005 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: API (Application Programming Interface) header file
+* : for RTP (Real-time Transport Protocol) library.
+*
+*/
+
+
+
+
+#ifndef __RTPAPI_H
+#define __RTPAPI_H
+
+// INCLUDES
+#include <rtpdef.h>
+#include "srtpsession.h"
+
+// CONSTANTS
+
+// MACROS
+
+// DATA TYPES
+
+// FUNCTION PROTOTYPES
+
+// FORWARD DECLARATIONS
+class CRtpManager;
+
+// CLASS DECLARATION
+
+/**
+* API (Application Programming Interface) class for RTP (Real-time Transport
+* Protocol) library.
+*
+* @lib RtpService.dll
+*/
+class CRtpAPI : public CBase
+ {
+ public: // Constructors and destructor
+
+ /**
+ * Two-phased constructor.
+ */
+ IMPORT_C static CRtpAPI* NewL( MRtpErrNotify& aErrNotify );
+
+ /**
+ * Destructor.
+ */
+ virtual ~CRtpAPI();
+
+ public:
+
+ /**
+ * Open and initialize the CRtpAPI object.
+ * @param aSdesInfo - [input] SDES (Source Description)
+ * of the local participant (CName, Username, etc.)
+ * @param aRtpPacketDll - [input] Path+file name of RTP packet
+ * formatting DLL to use; NULL to use standard RTP packet format
+ * Ownership is transfered.
+ * @param aRConnPtr - [input] Network connection to use;
+ * NULL to use default network connection. Ownership is transfered.
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt OpenL( const TRtpSdesParams& aSdesInfo,
+ const TDesC* aRtpPacketDll,
+ const RSocketServ* aSocketServPtr,
+ const RConnection* aConnPtr );
+
+ /**
+ * Open and initialize the CRtpAPI object.
+ * @param aIapId - [input] IAP ID. If -1, no IAP selection dialog
+ * will pop up. Instead, the default IAP will be used.
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt StartConnection( TInt aIapId = -1 );
+
+ /**
+ * Open and initialize the CRtpAPI object in asynchronous mode
+ * @param aStatus - [output] On completion, will contain a status code:
+ * KErrNone if successful; system wide error code otherwise.
+ * @param aIapId - [input] IAP ID. If -1, no IAP selection dialog
+ * will pop up. Instead, the default IAP will be used.
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt StartConnection( TRequestStatus& aStatus,
+ TInt aIapId = -1 );
+
+ /**
+ * Cancels asynchoronous start of connection.
+ * Any open requests will be completed with KErrCancel.
+ * @return None
+ */
+ IMPORT_C void CancelStart();
+
+ /**
+ * Close the CRtpAPI object.
+ * @param None
+ * @return None
+ */
+ IMPORT_C void Close();
+
+ /**
+ * Set SDES (Source Description) information of the local participant.
+ * Participant is defined as an application program and
+ * only one local participant is allowed.
+ * @param aSdesInfo - [input] SDES of the local participant
+ * (CName, Username, etc.).
+ * @return None
+ */
+ IMPORT_C void SetLocalSdes( const TRtpSdesParams& aSdesInfo );
+
+ /**
+ * Get the local IP address
+ * @param None
+ * @return local ip address.
+ */
+ IMPORT_C TInetAddr& GetLocalIPAddressL();
+
+ /**
+ * Create a new RTP Session and return the Session ID as well as the
+ * local port number assigned for RTP. RTP uses an even port number and
+ * RTCP, if enabled, uses the next higher (odd) port number.
+ * @param aSessionParams - [input] Session parameters
+ * @param aPort - [input] Local port number to use for RTP;
+ * 0 to use default port number
+ * - [output] port number assigned for RTP
+ * @param aEnableRtcp - [input] ETrue to enable RTCP; EFalse to disable
+ * @param aRtcpParams - [input] RTCP parameters to use;
+ * NULL to use default RTCP parameters
+ * @return Identifier (ID) of RTP Session created if successful;
+ * KNullId otherwise
+ */
+ IMPORT_C TRtpId CreateSessionL(
+ const TCreateSessionParams& aSessionParams,
+ TUint& aPort,
+ TBool aEnableRtcp,
+ const TRtcpParams* aRtcpParams );
+ /**
+ * Create a new, secure RTP Session and return the Session ID as well as the
+ * local port number assigned for RTP. RTP uses an even port number and
+ * RTCP, if enabled, uses the next higher (odd) port number.
+ * User is expected to create corresponding SRTP session prior to calling this
+ * function.
+ * @param aSessionParams - [input] Session parameters
+ * @param aPort - [input] Local port number to use for RTP;
+ * 0 to use default port number
+ * - [output] port number assigned for RTP
+ * @param aEnableRtcp - [input] ETrue to enable RTCP; EFalse to disable
+ * @param aRtcpParams - [input] RTCP parameters to use;
+ * NULL to use default RTCP parameters
+ * @param aSession - [input] SRTP session to be used by this RTP session.
+ * @return Identifier (ID) of RTP Session created if successful;
+ * KNullId otherwise
+ */
+
+ IMPORT_C TRtpId CreateSessionL(
+ const TCreateSessionParams& aSessionParams,
+ TUint& aPort,
+ TBool aEnableRtcp,
+ const TRtcpParams* aRtcpParams,
+ CSRTPSession& aSession);
+
+
+ /**
+ * Start an RTP Session. If enabled, RTCP associated with the given
+ * session is also started.
+ * @param aSessionId - [input] Session ID
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt StartSession( TRtpId aSessionId );
+
+ /**
+ * Close an RTP Session.
+ * @param aSessionId - [input] Session ID
+ * @return None
+ */
+ IMPORT_C void CloseSession( TRtpId aSessionId );
+
+ /**
+ * Set remote IP address and port number to RTP Session.
+ * Port number for RTP must be an even number and the corresponding
+ * RTCP, if enabled, will be set to use the next higher (odd) port.
+ * @param aSessionId - [input] RTP Session ID
+ * @param aRemoteAddr - [input] Remote IP address & port number for RTP
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SetRemoteAddress( TRtpId aSessionId,
+ const TInetAddr& aRemoteAddr );
+
+ /**
+ * Set remote RTCP IP address and port number to RTP Session accoring to RFC 3605
+ * i.e. this should be used if RTCP port is different than RTP port + 1
+ * @param TRtpId aSessionId - [input] RTP Session ID
+ * @param TInetAddr& aRemoteAddr - [input] Remote IP address & port
+ * number for RTP
+ * @return TInt - KErrNone if successful; KErrNotFound if invalid session id;
+ * KErrNotSupported if RTCP disabled; system wide error code otherwise
+ */
+ IMPORT_C TInt SetRemoteRtcpAddress( TRtpId aSessionId, const TInetAddr& aRemoteRtcpAddr );
+
+ /**
+ * Create a Receive stream for an RTP Session and return the stream
+ * ID which is unique for all RTP Sessions.
+ * @param aSessionId - [input] RTP Session ID
+ * @param aParams - [input] Receive stream parameters
+ * @return Stream ID if successful; KNullId otherwise
+ */
+ IMPORT_C TRtpId CreateReceiveStreamL( TRtpId aSessionId,
+ const TRcvStreamParams& aParams );
+
+ /**
+ * Create a Transmit stream for an RTP Session and return the stream
+ * ID which is unique for all RTP Sessions. SSRC value assigned for the
+ * very first Transmit stream will be the same as the default SSRC
+ * value reserved internally by CreateSession function. This function
+ * is normally used to create a transmit stream where SSRC value is
+ * randomly generated.
+ * @param aSessionId - [input] RTP Session ID
+ * @param aParams - [input] Transmit stream parameters
+ * @param aSSRC - [output] SSRC value assigned
+ * @return Stream ID if successful; KNullId otherwise
+ */
+ IMPORT_C TRtpId CreateTransmitStreamL( TRtpId aSessionId,
+ const TTranStreamParams& aParams,
+ TRtpSSRC& aSSRC );
+
+ /**
+ * Create a Transmit stream, with a given SSRC value, for an RTP Session
+ * and return the stream ID which is unique for all RTP Sessions. This
+ * extended function is used for a special case where a specific SSRC
+ * value needs to be associated with the transmit stream being created,
+ * e.g. for retransmission purpose.
+ * @param aSessionId - [input] RTP Session ID
+ * @param aParams - [input] Transmit stream parameters
+ * @param aSsrc - [input] SSRC value to use
+ * @return Stream ID if successful; KNullId otherwise
+ */
+ IMPORT_C TRtpId CreateTransmitStreamExtL( TRtpId aSessionId,
+ const TTranStreamParams& aParams,
+ const TRtpSSRC aSSRC );
+
+ /**
+ * Close a Transmit or Receive stream.
+ * @param TRtpId aStreamId - [input] ID of stream to close
+ * @return None
+ */
+ IMPORT_C void CloseStream( TRtpId aStreamId );
+
+ /**
+ * Register a callback object for receiving RTP data packets from an RTP
+ * Session. Only one receiver callback object is allowed to be
+ * registered for one Session.
+ * MRtpObserver::RtpPacketReceived function from aRtpObserver object is
+ * called when an RTP data packet is received.
+ * @param aSessionId - [input] RTP Session ID
+ * @param aRtpObserver - [input] Callback object to receive RTP packets
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt RegisterRtpObserver( TRtpId aSessionId,
+ MRtpObserver& aRtpObserver );
+
+ /**
+ * Unregister RTP observer callback object associated with an RTP
+ * session.
+ * @param aSessionId - [input] RTP Session ID
+ * @return None
+ */
+ IMPORT_C void UnregisterRtpObserver( TRtpId aSessionId );
+
+ /**
+ * Sets/resets the observer for the non-RTP data.
+ * Only one receiver callback object is allowed to be
+ * registered for one Session.
+ * MNonRTPDataObserver::NonRTPDataReceived or
+ * MNonRTPDataObserver::NonRTCPDataReceived from
+ * aNonRTPDataObserver object is
+ * called when a non-RTP data packet is received.
+ * @param aNonRTPDataObserver an observer, 0-pointer resets the observer
+ * @return KErrNotFound if non-existing session-ID provided, system-wide error code otherwise. KErrNone if successfull.
+ */
+ IMPORT_C TInt SetNonRTPDataObserver( TRtpId aSessionId,
+ MNonRTPDataObserver* aNonRTPDataObserver );
+
+ /**
+ * Send an RTP data packet in a Transmit stream synchronously.
+ * @param aTranStreamId - [input] ID of Transmit stream
+ * @param aHeaderInfo - [input] Header information of RTP data packet
+ * @param aPayloadData - [input] Payload data of RTP data packet
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SendRtpPacket( TRtpId aTranStreamId,
+ const TRtpSendHeader& aHeaderInfo,
+ const TDesC8& aPayloadData );
+
+ /**
+ * Send an RTP data packet in a Transmit stream asynchronously.
+ * @param TRtpId aTranStreamId - [input] ID of Transmit stream
+ * @param aHeaderInfo - [input] Header information
+ * of RTP data packet to send
+ * @param aPayloadData - [input] Payload data of RTP data packet to send
+ * @param aStatus - [output] On completion, will contain a status code:
+ * KErrNone if successful; system wide error code otherwise
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SendRtpPacket( TRtpId aTranStreamId,
+ const TRtpSendHeader& aHeaderInfo,
+ const TDesC8& aPayloadData,
+ TRequestStatus& aStatus );
+
+ /**
+ * Send an RTP data packet asynchronously, with a given sequence number,
+ * in a Transmit stream mainly for retransmission purpose.
+ * @param aTranStreamId - [input] ID of Transmit stream
+ * @param aSequenceNum - [input] Sequence number to use
+ * @param aHeaderInfo - [input] Header information of RTP data packet
+ * @param aPayloadData - [input] Payload data of RTP data packet to send
+ * @param aStatus - [output] On completion, will contain a status code:
+ * KErrNone if successful; system wide error code otherwise
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SendRtpPacket( TRtpId aTranStreamId,
+ TRtpSequence aSequenceNum,
+ const TRtpSendHeader& aHeaderInfo,
+ const TDesC8& aPayloadData,
+ TRequestStatus& aStatus );
+
+
+ /**
+ * Send a non-RTP (control) data packet asynchronously
+ * @param aSessionId - [input] RTP Session ID
+ * @param aUseRTPSocket - [input] use RTP/RTCP socket
+ * @param aData - [input] non-RTP data packet to send
+ * @param aStatus - [output] On completion, will contain a status code:
+ * KErrNone if successful; system wide error code otherwise
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C void SendDataL( TRtpId aSessionId,
+ TBool aUseRTPSocket,
+ const TDesC8& aData,
+ TRequestStatus& aStatus );
+
+ /**
+ * Cancel an outstanding SendRtpPacket() operation.
+ * @param TRtpId aSessionId - [input] RTP Session ID
+ * @return None
+ */
+ IMPORT_C void CancelSend( TRtpId aSessionId );
+
+ /**
+ * Register a callback object for receiving RTCP packets associated with
+ * a given RTP Session. Only one observer callback object is allowed to
+ * be registered. One of aRtcpObserver object's callback functions is
+ * called when an RTCP packet of that type is received.
+ * @param aSessionId - [input] RTP Session ID
+ * @param aObserver - [input] Callback object to receive RTCP packets
+ * @return KErrNone if successful; system wide error code otherwise.
+ */
+ IMPORT_C TInt RegisterRtcpObserver( TRtpId aSessionId,
+ MRtcpObserver& aRtcpObserver );
+
+ /**
+ * Unregister RTCP observer callback object associated with an RTP
+ * session.
+ * @param aSessionId - [input] RTP Session ID
+ * @return None
+ */
+ IMPORT_C void UnregisterRtcpObserver( TRtpId aSessionId );
+
+ /**
+ * Send an RTCP BYE packet for a Transmit stream.
+ * @param aTranStreamId - [input] Transmit stream ID
+ * @param aReason - [input] Reason for leaving
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SendRtcpByePacket( TRtpId aTranStreamId,
+ const TDesC8& aReason );
+
+ /**
+ * Send an RTCP APP packet for a Transmit stream.
+ * @param TRtpId aTranStreamId - [input] Transmit stream ID
+ * @param TRtcpApp aApp - [input] APP packet to send
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SendRtcpAppPacket( TRtpId aTranStreamId,
+ const TRtcpApp& aApp );
+
+ /**
+ * Send an RTCP RR packet for a Reception stream.
+ * @param TRtpId aRcvStreamId - [input] Reception stream ID
+ * @return TInt - KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SendRtcpRrPacket( TRtpId aRcvStreamId );
+
+ /**
+ * Send an RTCP SR packet for a Transmit stream.
+ * @param TRtpId aTranStreamId - [input] Transmit stream ID
+ * @return TInt - KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SendRtcpSrPacket( TRtpId aTranStreamId );
+
+ /**
+ * Suspend RTCP sending on/off, calculations will continue.
+ * @param TRtpId aSessionId - [input] RTP Session ID
+ * @param TBool aAutoSending - [input] Auto sending flag.
+ * ETrue: RTCP sending will be scheduled normally
+ * EFalse: RTCP sending will be suspended
+ * @return TInt - KErrNone if successful; KErrNotFound if invalid session id;
+ * KErrNotSupported if RTCP disabled; system wide error code otherwise
+ */
+ IMPORT_C TInt SuspendRtcpSending( TRtpId aSessionId, TBool aAutoSending );
+
+ /**
+ * Gets the status of automatic RTCP sending.
+ * @param TRtpId aSessionId - [input] RTP Session ID
+ * @param TBool aAutoSending - [output] ETrue: RTCP auto sending is on
+ * EFalse: RTCP auto sending is off
+ * @return TInt - KErrNone if successful; KErrNotFound if invalid session id;
+ * KErrNotSupported if RTCP disabled; system wide error code otherwise
+ */
+ IMPORT_C TInt IsRtcpSendingSuspended( TRtpId aSessionId, TBool& aAutoSending );
+
+ /**
+ * Get the session ID of a stream, which belongs to that session.
+ * @param aStreamId - [input] ID of a stream
+ * @return Identifier (ID) of RTP Session if found; KNullId otherwise
+ */
+ IMPORT_C TRtpId GetSessionId( TRtpId aStreamId );
+
+ /**
+ * Get address of Socket object used by a given RTP Session
+ * to send/receive RTP data packets.
+ * @param aSessionId - [input] RTP Session ID
+ * @return Address of Socket object used if successful; NULL otherwise
+ */
+ IMPORT_C RSocket* GetRtpSocket( TRtpId aSessionId );
+
+ /**
+ * Get address of Socket object used by a given RTP Session
+ * to send/receive RTCP control packets.
+ * @param aSessionId - [input] RTP Session ID
+ * @return Address of Socket object used if successful; NULL otherwise
+ */
+ IMPORT_C RSocket* GetRtcpSocket( TRtpId aSessionId );
+
+ /**
+ * Retrieve statistical information for a stream
+ * based on the reports from RTCP SR & RR packets.
+ * @param aStreamId - [input] ID of stream
+ * @param aStat - [output] Statistical information
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt GetStreamStatistics( TRtpId aStreamId,
+ TRtpPeerStat& aStat );
+
+ /**
+ * Get sampling rate setting for a payload type.
+ * @param aPayloadType - [input] Payload type
+ * @return Sampling rate in Hz; 0 if payload type setting not found
+ */
+ IMPORT_C TUint32 GetSamplingRate( TUint8 aPayloadType );
+
+ /**
+ * Set sampling rate for a payload type.
+ * @param aPayloadType - [input] Payload type
+ * @param aSamplingRate - [input] Sampling rate in Hz
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SetSamplingRate( TUint8 aPayloadType,
+ TUint32 aSamplingRate );
+
+ /**
+ * Set RTCP parameters for a given RTP Session.
+ * This function does nothing if RTCP was not enabled previously.
+ * @param aSessionId - [input] RTP Session ID
+ * @param aRtcpParams - [input] RTCP parameters to use
+ * @return KErrNone if successful; system wide error code otherwise
+ */
+ IMPORT_C TInt SetRtcpParameters( TRtpId aSessionId,
+ const TRtcpParams& aRtcpParams );
+
+ /**
+ * Synchronous custom command interface for future extensions.
+ * Input/output data and return value are defined by each custom command
+ * @param aFunction - [input] Function ID
+ * @param aInputData1 - [input] Input data #1; NULL if not used
+ * @param aInputData2 - [input] Input data #2; NULL if not used
+ * @param aOutputData - [output] Output data; NULL if not used
+ * @return Defined by the function
+ */
+ IMPORT_C TInt CustomCommandSync( TInt aFunction,
+ const TDesC8& aInputData1,
+ const TDesC8& aInputData2,
+ TDes8& aOutputData );
+
+ /**
+ * ASynchronous custom command interface for future extensions.
+ * Input/output data and return value are defined by each custom command
+ * @param aFunction - [input] Function ID
+ * @param aInputData1 - [input] Input data #1; NULL if not used
+ * @param aInputData2 - [input] Input data #2; NULL if not used
+ * @param aOutputData - [output] Output data; NULL if not used
+ * @param aStatus - [output] On completion, will contain a status code:
+ * KErrNone if successful; system wide error code otherwise
+ * @return Defined by the function
+ */
+ IMPORT_C TInt CustomCommandAsync( TInt aFunction,
+ const TDesC8& aInputData1,
+ const TDesC8& aInputData2,
+ TDes8& aOutputData,
+ TRequestStatus& aStatus );
+
+ /**
+ * Version of RtpService.dll
+ * @return Version of current RtpService.dll
+ */
+ IMPORT_C TVersion Version() const;
+
+
+ //Internal use only
+ /**
+ * Dummy function to fix Raptor error
+ * @return KErrNone.
+ */
+ IMPORT_C TInt NotInUseSetNonRTPDataObserver( );
+
+
+ private:
+ /**
+ * C++ default constructor.
+ */
+ CRtpAPI();
+
+ /**
+ * By default Symbian 2nd phase constructor is private.
+ */
+ void ConstructL( MRtpErrNotify& aErrNotify );
+
+
+ private: // Data
+ // RTP Manager
+ CRtpManager* iManager;
+
+ // Reserved for future extensions
+ TAny* iReserved1;
+ TAny* iReserved2;
+ TInt iReserved3;
+ TInt iReserved4;
+ private:
+ #ifdef EUNIT_TESTING
+ friend class UT_CRtpAPI;
+ #endif
+ };
+
+#endif //__RTPAPI_H