# mediasession.h

Go to the documentation of this file.

    00001 /*
    00002  * mediasession.h
    00003  *
    00004  * Media session abstraction
    00005  *
    00006  * Open Phone Abstraction Library (OPAL)
    00007  *
    00008  * Copyright (C) 2010 Vox Lucida Pty. Ltd.
    00009  *
    00010  * The contents of this file are subject to the Mozilla Public License
    00011  * Version 1.0 (the "License"); you may not use this file except in
    00012  * compliance with the License. You may obtain a copy of the License at
    00013  * http://www.mozilla.org/MPL/
    00014  *
    00015  * Software distributed under the License is distributed on an "AS IS"
    00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
    00017  * the License for the specific language governing rights and limitations
    00018  * under the License.
    00019  *
    00020  * The Original Code is Open Phone Abstraction Library.
    00021  *
    00022  * The Initial Developer of the Original Code is Vox Lucida Pty. Ltd.
    00023  *
    00024  * Contributor(s): ______________________________________.
    00025  *
    00026  * $Revision: 29564 $
    00027  * $Author: rjongbloed $
    00028  * $Date: 2013-04-24 22:17:56 -0500 (Wed, 24 Apr 2013) $
    00029  */
    00030
    00031 #ifndef OPAL_OPAL_MEDIASESSION_H
    00032 #define OPAL_OPAL_MEDIASESSION_H
    00033
    00034 #ifdef P_USE_PRAGMA
    00035 #pragma interface
    00036 #endif
    00037
    00038 #include <opal/buildopts.h>
    00039
    00040 #include <opal/transports.h>
    00041 #include <opal/mediatype.h>
    00042
    00043
    00044 class OpalConnection;
    00045 class OpalMediaStream;
    00046 class OpalMediaFormat;
    00047 class OpalMediaFormatList;
    00048 class OpalMediaCryptoSuite;
    00049
    00050
    00051 #if OPAL_STATISTICS
    00052
    00055 class OpalMediaStatistics : public PObject
    00056 {
    00057     PCLASSINFO(OpalMediaStatistics, PObject);
    00058   public:
    00059     OpalMediaStatistics();
    00060
    00061     // General info (typicallly from RTP)
    00062     PTime    m_startTime;
    00063     PUInt64  m_totalBytes;
    00064     unsigned m_totalPackets;
    00065     unsigned m_packetsLost;
    00066     unsigned m_packetsOutOfOrder;
    00067     unsigned m_packetsTooLate;
    00068     unsigned m_packetOverruns;
    00069     unsigned m_minimumPacketTime;
    00070     unsigned m_averagePacketTime;
    00071     unsigned m_maximumPacketTime;
    00072
    00073     // Audio
    00074     unsigned m_averageJitter;
    00075     unsigned m_maximumJitter;
    00076     unsigned m_jitterBufferDelay;
    00077
    00078 #if OPAL_VIDEO
    00079     // Video
    00080     unsigned m_totalFrames;
    00081     unsigned m_keyFrames;
    00082     int      m_quality; // -1 is none, 0 is very good > 0 is progressively worse
    00083 #endif
    00084
    00085     // Fax
    00086 #if OPAL_FAX
    00087     enum {
    00088       FaxNotStarted = -2,
    00089       FaxInProgress = -1,
    00090       FaxSuccessful = 0,
    00091       FaxErrorBase  = 1
    00092     };
    00093     enum FaxCompression {
    00094       FaxCompressionUnknown,
    00095       FaxCompressionT4_1d,
    00096       FaxCompressionT4_2d,
    00097       FaxCompressionT6,
    00098     };
    00099     friend ostream & operator<<(ostream & strm, FaxCompression compression);
    00100     struct Fax {
    00101       Fax();
    00102
    00103       int  m_result;      // -2=not started, -1=progress, 0=success, >0=ended with error
    00104       char m_phase;       // 'A', 'B', 'D'
    00105       int  m_bitRate;     // e.g. 14400, 9600
    00106       FaxCompression m_compression; // 0=N/A, 1=T.4 1d, 2=T.4 2d, 3=T.6
    00107       bool m_errorCorrection;
    00108       int  m_txPages;
    00109       int  m_rxPages;
    00110       int  m_totalPages;
    00111       int  m_imageSize;   // In bytes
    00112       int  m_resolutionX; // Pixels per inch
    00113       int  m_resolutionY; // Pixels per inch
    00114       int  m_pageWidth;
    00115       int  m_pageHeight;
    00116       int  m_badRows;     // Total number of bad rows
    00117       int  m_mostBadRows; // Longest run of bad rows
    00118       int  m_errorCorrectionRetries;
    00119
    00120       PString m_stationId; // Remote station identifier
    00121       PString m_errorText;
    00122     } m_fax;
    00123 #endif // OPAL_FAX
    00124 };
    00125
    00126 #endif
    00127
    00128
    00131 class OpalMediaCryptoKeyInfo : public PObject {
    00132   protected:
    00133     OpalMediaCryptoKeyInfo(const OpalMediaCryptoSuite & cryptoSuite) : m_cryptoSuite(cryptoSuite) { }
    00134
    00135   public:
    00136     virtual ~OpalMediaCryptoKeyInfo() { }
    00137
    00138     virtual bool IsValid() const = 0;
    00139     virtual void Randomise() = 0;
    00140     virtual bool FromString(const PString & str) = 0;
    00141     virtual PString ToString() const = 0;
    00142
    00143     const OpalMediaCryptoSuite & GetCryptoSuite() const { return m_cryptoSuite; }
    00144
    00145     void SetTag(const PString & tag) { m_tag = tag; }
    00146     const PString & GetTag() const { return m_tag; }
    00147
    00148   protected:
    00149     const OpalMediaCryptoSuite & m_cryptoSuite;
    00150     PString m_tag;
    00151 };
    00152
    00153 typedef PList<OpalMediaCryptoKeyInfo> OpalMediaCryptoKeyList;
    00154
    00155
    00159 class OpalMediaCryptoSuite : public PObject
    00160 {
    00161     PCLASSINFO(OpalMediaCryptoSuite, PObject);
    00162   protected:
    00163     OpalMediaCryptoSuite() { }
    00164
    00165   public:
    00166     static const PCaselessString & ClearText();
    00167
    00168     virtual const PCaselessString & GetFactoryName() const = 0;
    00169     virtual bool Supports(const PCaselessString & proto) const = 0;
    00170     virtual bool ChangeSessionType(PCaselessString & mediaSession) const = 0;
    00171
    00172     virtual const char * GetDescription() const = 0;
    00173
    00174     virtual OpalMediaCryptoKeyInfo * CreateKeyInfo() const = 0;
    00175 };
    00176
    00177 typedef PFactory<OpalMediaCryptoSuite, PCaselessString> OpalMediaCryptoSuiteFactory;
    00178
    00179
    00182 class OpalMediaSession : public PSafeObject
    00183 {
    00184     PCLASSINFO(OpalMediaSession, PSafeObject);
    00185   public:
    00187     struct Init {
    00188       Init(
    00189         OpalConnection & connection,
    00190         unsigned sessionId,
    00191         const OpalMediaType & mediaType,
    00192         bool remoteBehindNAT
    00193       ) : m_connection(connection)
    00194         , m_sessionId(sessionId)
    00195         , m_mediaType(mediaType)
    00196         , m_remoteBehindNAT(remoteBehindNAT)
    00197       { }
    00198
    00199
    00200       OpalConnection & m_connection;
    00201       unsigned         m_sessionId;
    00202       OpalMediaType    m_mediaType;
    00203       bool             m_remoteBehindNAT;
    00204     };
    00205
    00206   protected:
    00207     OpalMediaSession(const Init & init);
    00208
    00209   public:
    00210     virtual const PCaselessString & GetSessionType() const = 0;
    00211     virtual bool Open(const PString & localInterface, const OpalTransportAddress & remoteAddress, bool isMediaAddress);
    00212     virtual bool IsOpen() const;
    00213     virtual bool Close();
    00214     virtual OpalTransportAddress GetLocalAddress(bool isMediaAddress = true) const;
    00215     virtual OpalTransportAddress GetRemoteAddress(bool isMediaAddress = true) const;
    00216     virtual bool SetRemoteAddress(const OpalTransportAddress & remoteAddress, bool isMediaAddress = true);
    00217
    00218     typedef PList<PChannel> Transport;
    00219     virtual void AttachTransport(Transport & transport);
    00220     virtual Transport DetachTransport();
    00221
    00222     bool IsExternalTransport() const { return m_isExternalTransport; }
    00223     virtual void SetExternalTransport(const OpalTransportAddressArray & transports);
    00224
    00225 #if OPAL_SIP
    00226     virtual SDPMediaDescription * CreateSDPMediaDescription();
    00227 #endif
    00228
    00229     virtual OpalMediaStream * CreateMediaStream(
    00230       const OpalMediaFormat & mediaFormat,
    00231       unsigned sessionID,
    00232       bool isSource
    00233     ) = 0;
    00234
    00235 #if OPAL_STATISTICS
    00236     virtual void GetStatistics(OpalMediaStatistics & statistics, bool receiver) const;
    00237 #endif
    00238
    00239     void OfferCryptoSuite(const PString & cryptoSuite);
    00240     virtual OpalMediaCryptoKeyList & GetOfferedCryptoKeys();
    00241
    00242     virtual bool ApplyCryptoKey(
    00243       OpalMediaCryptoKeyList & keys,
    00244       bool rx
    00245     );
    00246
    00247
    00248     unsigned GetSessionID() const { return m_sessionId; }
    00249     const OpalMediaType & GetMediaType() const { return m_mediaType; }
    00250
    00251   protected:
    00252     OpalConnection & m_connection;
    00253     unsigned         m_sessionId;  // unique session ID
    00254     OpalMediaType    m_mediaType;  // media type for session
    00255     bool             m_isExternalTransport;
    00256
    00257     OpalMediaCryptoKeyList m_offeredCryptokeys;
    00258
    00259   private:
    00260     OpalMediaSession(const OpalMediaSession & other) : PSafeObject(other), m_connection(other.m_connection) { }
    00261     void operator=(const OpalMediaSession &) { }
    00262
    00263     P_REMOVE_VIRTUAL(bool, Open(const PString &), false);
    00264     P_REMOVE_VIRTUAL(OpalTransportAddress, GetLocalMediaAddress() const, 0);
    00265     P_REMOVE_VIRTUAL(OpalTransportAddress, GetRemoteMediaAddress() const, 0);
    00266     P_REMOVE_VIRTUAL(bool, SetRemoteMediaAddress(const OpalTransportAddress &), false);
    00267     P_REMOVE_VIRTUAL(OpalTransportAddress, GetRemoteControlAddress() const, 0);
    00268     P_REMOVE_VIRTUAL(bool, SetRemoteControlAddress(const OpalTransportAddress &), false);
    00269 };
    00270
    00271
    00272 typedef PParamFactory<OpalMediaSession, const OpalMediaSession::Init &, PCaselessString> OpalMediaSessionFactory;
    00273
    00274 #ifdef OPAL_SRTP
    00275 PFACTORY_LOAD(OpalSRTPSession);
    00276 #endif
    00277
    00278
    00279 #endif // OPAL_OPAL_MEDIASESSION_H