OPAL  Version 3.14.3
mediasession.h
Go to the documentation of this file.
1 /*
2  * mediasession.h
3  *
4  * Media session abstraction
5  *
6  * Open Phone Abstraction Library (OPAL)
7  *
8  * Copyright (C) 2010 Vox Lucida Pty. Ltd.
9  *
10  * The contents of this file are subject to the Mozilla Public License
11  * Version 1.0 (the "License"); you may not use this file except in
12  * compliance with the License. You may obtain a copy of the License at
13  * http://www.mozilla.org/MPL/
14  *
15  * Software distributed under the License is distributed on an "AS IS"
16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17  * the License for the specific language governing rights and limitations
18  * under the License.
19  *
20  * The Original Code is Open Phone Abstraction Library.
21  *
22  * The Initial Developer of the Original Code is Vox Lucida Pty. Ltd.
23  *
24  * Contributor(s): ______________________________________.
25  *
26  * $Revision: 32280 $
27  * $Author: rjongbloed $
28  * $Date: 2014-07-02 14:32:53 +1000 (Wed, 02 Jul 2014) $
29  */
30 
31 #ifndef OPAL_OPAL_MEDIASESSION_H
32 #define OPAL_OPAL_MEDIASESSION_H
33 
34 #ifdef P_USE_PRAGMA
35 #pragma interface
36 #endif
37 
38 #include <opal_config.h>
39 
40 #include <opal/transports.h>
41 #include <opal/mediatype.h>
42 
43 
44 class OpalConnection;
45 class OpalMediaStream;
46 class OpalMediaFormat;
47 class OpalMediaFormatList;
48 class OpalMediaCryptoSuite;
49 class H235SecurityCapability;
50 class H323Capability;
51 
52 
53 #if OPAL_STATISTICS
54 
57 class OpalMediaStatistics : public PObject
58 {
59  PCLASSINFO(OpalMediaStatistics, PObject);
60  public:
61  OpalMediaStatistics();
62 
63  OpalMediaStatistics & Update(const OpalMediaStream & stream);
64  virtual void PrintOn(ostream & strm) const;
65 
66  OpalMediaType m_mediaType;
67  PString m_mediaFormat;
68 
69  PTimeInterval m_updateInterval;
70  PTimeInterval m_lastUpdateTime;
71 
72  // General info (typicallly from RTP)
73  PTime m_startTime;
74  PUInt64 m_totalBytes;
75  PUInt64 m_deltaBytes;
76  unsigned m_totalPackets;
77  unsigned m_deltaPackets;
78  unsigned m_packetsLost;
79  unsigned m_packetsOutOfOrder;
80  unsigned m_packetsTooLate;
81  unsigned m_packetOverruns;
82  unsigned m_minimumPacketTime; // Milliseconds
83  unsigned m_averagePacketTime; // Milliseconds
84  unsigned m_maximumPacketTime; // Milliseconds
85  unsigned m_roundTripTime; // Milliseconds
86 
87  // Audio
88  unsigned m_averageJitter; // Milliseconds
89  unsigned m_maximumJitter; // Milliseconds
90  unsigned m_jitterBufferDelay; // Milliseconds
91 
92 #if OPAL_VIDEO
93  // Video
94  unsigned m_totalFrames;
95  unsigned m_deltaFrames;
96  unsigned m_keyFrames;
97  unsigned m_updateRequests;
98  int m_quality; // -1 is none, 0 is very good > 0 is progressively worse
99 #endif
100 
101  // Fax
102 #if OPAL_FAX
103  enum {
104  FaxNotStarted = -2,
105  FaxInProgress = -1,
106  FaxSuccessful = 0,
107  FaxErrorBase = 1
108  };
109  enum FaxCompression {
110  FaxCompressionUnknown,
111  FaxCompressionT4_1d,
112  FaxCompressionT4_2d,
113  FaxCompressionT6,
114  };
115  friend ostream & operator<<(ostream & strm, FaxCompression compression);
116  struct Fax {
117  Fax();
118 
119  int m_result; // -2=not started, -1=progress, 0=success, >0=ended with error
120  char m_phase; // 'A', 'B', 'D'
121  int m_bitRate; // e.g. 14400, 9600
122  FaxCompression m_compression; // 0=N/A, 1=T.4 1d, 2=T.4 2d, 3=T.6
123  bool m_errorCorrection;
124  int m_txPages;
125  int m_rxPages;
126  int m_totalPages;
127  int m_imageSize; // In bytes
128  int m_resolutionX; // Pixels per inch
129  int m_resolutionY; // Pixels per inch
130  int m_pageWidth;
131  int m_pageHeight;
132  int m_badRows; // Total number of bad rows
133  int m_mostBadRows; // Longest run of bad rows
134  int m_errorCorrectionRetries;
135 
136  PString m_stationId; // Remote station identifier
137  PString m_errorText;
138  } m_fax;
139 #endif // OPAL_FAX
140 };
141 
142 #endif
143 
144 
147 class OpalMediaCryptoKeyInfo : public PObject {
148  protected:
149  OpalMediaCryptoKeyInfo(const OpalMediaCryptoSuite & cryptoSuite) : m_cryptoSuite(cryptoSuite) { }
150 
151  public:
152  virtual ~OpalMediaCryptoKeyInfo() { }
153 
154  virtual bool IsValid() const = 0;
155  virtual void Randomise() = 0;
156  virtual bool FromString(const PString & str) = 0;
157  virtual PString ToString() const = 0;
158 
159  virtual bool SetCipherKey(const PBYTEArray & key) = 0;
160  virtual bool SetAuthSalt(const PBYTEArray & key) = 0;
161 
162  virtual PBYTEArray GetCipherKey() const = 0;
163  virtual PBYTEArray GetAuthSalt() const = 0;
164 
165  const OpalMediaCryptoSuite & GetCryptoSuite() const { return m_cryptoSuite; }
166 
167  void SetTag(const PString & tag) { m_tag = tag; }
168  const PString & GetTag() const { return m_tag; }
169 
170  protected:
171  const OpalMediaCryptoSuite & m_cryptoSuite;
172  PString m_tag;
173 };
174 
175 struct OpalMediaCryptoKeyList : PList<OpalMediaCryptoKeyInfo>
176 {
177  void Select(iterator & it);
178 };
179 
180 
184 class OpalMediaCryptoSuite : public PObject
185 {
186  PCLASSINFO(OpalMediaCryptoSuite, PObject);
187  protected:
188  OpalMediaCryptoSuite() { }
189 
190  public:
191  static const PCaselessString & ClearText();
192 
193  virtual const PCaselessString & GetFactoryName() const = 0;
194  virtual bool Supports(const PCaselessString & proto) const = 0;
195  virtual bool ChangeSessionType(PCaselessString & mediaSession) const = 0;
196 
197  virtual const char * GetDescription() const = 0;
198 #if OPAL_H235_6 || OPAL_H235_8
199  virtual H235SecurityCapability * CreateCapability(const H323Capability & mediaCapability) const;
200  virtual const char * GetOID() const = 0;
201  static OpalMediaCryptoSuite * FindByOID(const PString & oid);
202 #endif
203 
204  PINDEX GetCipherKeyBytes() const { return (GetCipherKeyBits()+7)/8; }
205  virtual PINDEX GetCipherKeyBits() const = 0;
206  virtual PINDEX GetAuthSaltBits() const = 0;
207 
208  virtual OpalMediaCryptoKeyInfo * CreateKeyInfo() const = 0;
209 
210  struct List : PList<OpalMediaCryptoSuite>
211  {
212  List() { DisallowDeleteObjects(); }
213  };
214  static List FindAll(
215  const PStringArray & cryptoSuiteNames,
216  const char * prefix = NULL
217  );
218 
219  private:
220  P_REMOVE_VIRTUAL(H235SecurityCapability *,CreateCapability(const OpalMediaFormat &, unsigned) const,0);
221 };
222 
223 typedef PFactory<OpalMediaCryptoSuite, PCaselessString> OpalMediaCryptoSuiteFactory;
224 
225 
228 class OpalMediaSession : public PSafeObject
229 {
230  PCLASSINFO(OpalMediaSession, PSafeObject);
231  public:
233  struct Init {
234  Init(
235  OpalConnection & connection,
236  unsigned sessionId,
237  const OpalMediaType & mediaType,
238  bool remoteBehindNAT
239  ) : m_connection(connection)
240  , m_sessionId(sessionId)
241  , m_mediaType(mediaType)
242  , m_remoteBehindNAT(remoteBehindNAT)
243  { }
244 
245 
246  OpalConnection & m_connection;
247  unsigned m_sessionId;
248  OpalMediaType m_mediaType;
249  bool m_remoteBehindNAT;
250  };
251 
252  protected:
253  OpalMediaSession(const Init & init);
254 
255  public:
256  virtual const PCaselessString & GetSessionType() const = 0;
257  virtual bool Open(const PString & localInterface, const OpalTransportAddress & remoteAddress, bool isMediaAddress);
258  virtual bool IsOpen() const;
259  virtual bool Close();
260  virtual OpalTransportAddress GetLocalAddress(bool isMediaAddress = true) const;
261  virtual OpalTransportAddress GetRemoteAddress(bool isMediaAddress = true) const;
262  virtual bool SetRemoteAddress(const OpalTransportAddress & remoteAddress, bool isMediaAddress = true);
263 
264  typedef PList<PChannel> Transport;
265  virtual void AttachTransport(Transport & transport);
266  virtual Transport DetachTransport();
267 
268 #if OPAL_SDP
269  virtual SDPMediaDescription * CreateSDPMediaDescription();
270 #endif
271 
272  virtual OpalMediaStream * CreateMediaStream(
273  const OpalMediaFormat & mediaFormat,
274  unsigned sessionID,
275  bool isSource
276  ) = 0;
277 
278 #if OPAL_STATISTICS
279  virtual void GetStatistics(OpalMediaStatistics & statistics, bool receiver) const;
280 #endif
281 
282  void OfferCryptoSuite(const PString & cryptoSuite);
283  virtual OpalMediaCryptoKeyList & GetOfferedCryptoKeys();
284 
285  virtual bool ApplyCryptoKey(
286  OpalMediaCryptoKeyList & keys,
287  bool rx
288  );
289 
290  virtual bool IsCryptoSecured(bool rx) const;
291 
292  OpalConnection & GetConnection() const { return m_connection; }
293 
294  unsigned GetSessionID() const { return m_sessionId; }
295  const OpalMediaType & GetMediaType() const { return m_mediaType; }
296 
297  const PString & GetLocalUsername() const { return m_localUsername; }
298  const PString & GetLocalPassword() const { return m_localPassword; }
299 
300  virtual void SetRemoteUserPass(
301  const PString & user,
302  const PString & pass
303  );
304 
305  protected:
306  OpalConnection & m_connection;
307  unsigned m_sessionId; // unique session ID
308  OpalMediaType m_mediaType; // media type for session
309  PString m_localUsername; // ICE username sent to remote
310  PString m_localPassword; // ICE password sent to remote
311  PString m_remoteUsername; // ICE username expected from remote
312  PString m_remotePassword; // ICE password expected from remote
313 
314  OpalMediaCryptoKeyList m_offeredCryptokeys;
315 
316  private:
317  OpalMediaSession(const OpalMediaSession & other) : PSafeObject(other), m_connection(other.m_connection) { }
318  void operator=(const OpalMediaSession &) { }
319 
320  P_REMOVE_VIRTUAL(bool, Open(const PString &), false);
321  P_REMOVE_VIRTUAL(OpalTransportAddress, GetLocalMediaAddress() const, 0);
322  P_REMOVE_VIRTUAL(OpalTransportAddress, GetRemoteMediaAddress() const, 0);
323  P_REMOVE_VIRTUAL(bool, SetRemoteMediaAddress(const OpalTransportAddress &), false);
324  P_REMOVE_VIRTUAL(OpalTransportAddress, GetRemoteControlAddress() const, 0);
325  P_REMOVE_VIRTUAL(bool, SetRemoteControlAddress(const OpalTransportAddress &), false);
326 };
327 
328 
336 class OpalDummySession : public OpalMediaSession
337 {
338  PCLASSINFO(OpalDummySession, OpalMediaSession)
339  public:
340  OpalDummySession(const Init & init, const OpalTransportAddressArray & transports = OpalTransportAddressArray());
341  static const PCaselessString & SessionType();
342  virtual const PCaselessString & GetSessionType() const;
343  virtual bool Open(const PString & localInterface, const OpalTransportAddress & remoteAddress, bool isMediaAddress);
344  virtual bool IsOpen() const;
345  virtual OpalTransportAddress GetLocalAddress(bool isMediaAddress = true) const;
346  virtual OpalTransportAddress GetRemoteAddress(bool isMediaAddress = true) const;
347  virtual bool SetRemoteAddress(const OpalTransportAddress & remoteAddress, bool isMediaAddress = true);
348 #if OPAL_SDP
349  virtual SDPMediaDescription * CreateSDPMediaDescription();
350 #endif
351  virtual OpalMediaStream * CreateMediaStream(const OpalMediaFormat & mediaFormat, unsigned sessionID, bool isSource);
352 
353  private:
354  OpalTransportAddress m_localTransportAddress[2];
355  OpalTransportAddress m_remoteTransportAddress[2];
356 };
357 
358 
359 typedef PParamFactory<OpalMediaSession, const OpalMediaSession::Init &, PCaselessString> OpalMediaSessionFactory;
360 
361 #if OPAL_SRTP
362  PFACTORY_LOAD(OpalSRTPSession);
363 #endif
364 
365 #if OPAL_H235_6
366  PFACTORY_LOAD(H2356_Session);
367 #endif
368 
369 #endif // OPAL_OPAL_MEDIASESSION_H