1/*
2 * Python bindings.
3 *
4 * Open Phone Abstraction Library (OPAL)
5 *
6 * Copyright (c) 2011 Demetrius Cassidy
7 *
8 * The contents of this file are subject to the Mozilla Public License
9 * Version 1.0 (the "License"); you may not use this file except in
10 * compliance with the License. You may obtain a copy of the License at
11 * http://www.mozilla.org/MPL/
12 *
13 * Software distributed under the License is distributed on an "AS IS"
14 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
15 * the License for the specific language governing rights and limitations
16 * under the License.
17 *
18 * The Original Code is Open Phone Abstraction Library (OPAL)
19 *
20 * The Initial Developer of the Original Code is Demetrius Cassidy
21 *
22 * Contributor(s): ______________________________________.
23 *
24 * $Revision: 26117 $
25 * $Author: rjongbloed $
26 * $Date: 2011-07-04 22:45:05 -0500 (Mon, 04 Jul 2011) $
27 */
28
29%ModuleHeaderCode
30#include <ptlib.h>
31#include <rtp/jitter.h>
32%End
33
34
35///////////////////////////////////////////////////////////////////////////////
36/**This is an Abstract jitter buffer, which can be used simply in any
37   application. The user is required to use a descendant of this class, and
38   provide a "OnReadPacket" method, so that network packets can be placed in
39   this class instance */
40class OpalJitterBuffer : PSafeObject
41{
42
43  public:
44  /**@name Construction */
45  //@{
46    /**Constructor for this jitter buffer. The size of this buffer can be
47       altered later with the SetDelay method
48      */
49    OpalJitterBuffer(
50      unsigned minJitterDelay, ///<  Minimum delay in RTP timestamp units
51      unsigned maxJitterDelay, ///<  Maximum delay in RTP timestamp units
52      unsigned timeUnits = 8,  ///<  Time units, usually 8 or 16
53      PINDEX packetSize = 2048 ///<  Max RTP packet size
54    );
55
56    /** Destructor, which closes this down and deletes the internal list of frames
57      */
58    virtual ~OpalJitterBuffer();
59  //@}
60
61  /**@name Operations */
62  //@{
63    /**Set the maximum delay the jitter buffer will operate to.
64      */
65    void SetDelay(
66      unsigned minJitterDelay, ///<  Minimum delay in RTP timestamp units
67      unsigned maxJitterDelay, ///<  Maximum delay in RTP timestamp units
68      PINDEX packetSize = 2048 ///<  Max RTP packet size
69    );
70
71    /**Reset jitter buffer.
72      */
73    void Reset();
74
75    /**Write data frame from the RTP channel.
76      */
77    virtual PBoolean WriteData(
78      const RTP_DataFrame & frame,   ///< Frame to feed into jitter buffer
79      const PTimeInterval & tick = 0 ///< Real time tick for packet arrival
80    );
81
82    /**Read a data frame from the jitter buffer.
83       This function never blocks. If no data is available, an RTP packet
84       with zero payload size is returned.
85      */
86    virtual PBoolean ReadData(
87      RTP_DataFrame & frame,  ///<  Frame to extract from jitter buffer
88      const PTimeInterval & tick = 0 ///< Real time tick for packet removal
89    );
90
91    /**Get current delay for jitter buffer.
92      */
93    DWORD GetCurrentJitterDelay() const;
94
95    /**Get minimum delay for jitter buffer.
96      */
97    DWORD GetMinJitterDelay() const;
98
99    /**Get maximum delay for jitter buffer.
100      */
101    DWORD GetMaxJitterDelay() const;
102
103    /**Get time units.
104      */
105    unsigned GetTimeUnits() const;
106
107    /**Get total number received packets too late to go into jitter buffer.
108      */
109    DWORD GetPacketsTooLate() const;
110
111    /**Get total number received packets that overran the jitter buffer.
112      */
113    DWORD GetBufferOverruns() const;
114
115    /**Get maximum consecutive marker bits before buffer starts to ignore them.
116      */
117    DWORD GetMaxConsecutiveMarkerBits() const;
118
119    /**Set maximum consecutive marker bits before buffer starts to ignore them.
120      */
121    void SetMaxConsecutiveMarkerBits(DWORD max);
122  //@}
123
124  protected:
125    DWORD CalculateRequiredTimestamp(DWORD playOutTimestamp) const;
126};
127
128
129/**A descendant of the OpalJitterBuffer that starts a thread to read
130   from something continuously and feed it into the jitter buffer.
131  */
132class OpalJitterBufferThread : OpalJitterBuffer /Abstract/
133{
134 public:
135    OpalJitterBufferThread(
136      unsigned minJitterDelay, ///<  Minimum delay in RTP timestamp units
137      unsigned maxJitterDelay, ///<  Maximum delay in RTP timestamp units
138      unsigned timeUnits = 8,  ///<  Time units, usually 8 or 16
139      PINDEX packetSize = 2048 ///<  Max RTP packet size
140    );
141    ~OpalJitterBufferThread();
142
143    /**Read a data frame from the jitter buffer.
144       This function never blocks. If no data is available, an RTP packet
145       with zero payload size is returned.
146
147       Override of base class so can terminate caller when shutting down.
148      */
149    virtual PBoolean ReadData(
150      RTP_DataFrame & frame   ///<  Frame to extract from jitter buffer
151    );
152
153    /**This class instance collects data from the outside world in this
154       method.
155
156       @return true on successful read, false on faulty read. */
157    virtual PBoolean OnReadPacket(
158      RTP_DataFrame & frame  ///<  Frame read from the RTP session
159    ) = 0;
160
161 protected:
162    //PDECLARE_NOTIFIER(PThread, OpalJitterBufferThread, JitterThreadMain);
163
164    /// Internal function to be called from derived class constructor
165    void StartThread() /ReleaseGIL/;
166
167    /// Internal function to be called from derived class destructor
168    void WaitForThreadTermination() /ReleaseGIL/;
169
170	/// SIP Function to access m_running method.
171    /*bool running();
172%MethodCode
173	return m_running;
174%End*/
175};
176
177
178/////////////////////////////////////////////////////////////////////////////
179/**A descendant of the OpalJitterBuffer that reads RTP_DataFrame instances
180   from the RTP_Sessions
181  */
182class RTP_JitterBuffer : OpalJitterBufferThread
183{
184 public:
185    RTP_JitterBuffer(
186      RTP_Session & session,   ///<  Associated RTP session tor ead data from
187      unsigned minJitterDelay, ///<  Minimum delay in RTP timestamp units
188      unsigned maxJitterDelay, ///<  Maximum delay in RTP timestamp units
189      unsigned timeUnits = 8,  ///<  Time units, usually 8 or 16
190      PINDEX packetSize = 2048 ///<  Max RTP packet size
191    );
192    ~RTP_JitterBuffer();
193
194    /**This class instance collects data from the outside world in this
195       method.
196
197       @return true on successful read, false on faulty read. */
198    virtual PBoolean OnReadPacket(
199      RTP_DataFrame & frame  ///<  Frame read from the RTP session
200    );
201
202};
203
204
205
206/////////////////////////////////////////////////////////////////////////////
207