1 /*
2  *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
3  *
4  *  Use of this source code is governed by a BSD-style license
5  *  that can be found in the LICENSE file in the root of the source
6  *  tree. An additional intellectual property rights grant can be found
7  *  in the file PATENTS.  All contributing project authors may
8  *  be found in the AUTHORS file in the root of the source tree.
9  */
10 
11 #ifndef WEBRTC_MODULES_AUDIO_CODING_NETEQ_PACKET_BUFFER_H_
12 #define WEBRTC_MODULES_AUDIO_CODING_NETEQ_PACKET_BUFFER_H_
13 
14 #include "webrtc/base/constructormagic.h"
15 #include "webrtc/modules/audio_coding/neteq/packet.h"
16 #include "webrtc/typedefs.h"
17 
18 namespace webrtc {
19 
20 // Forward declaration.
21 class DecoderDatabase;
22 
23 // This is the actual buffer holding the packets before decoding.
24 class PacketBuffer {
25  public:
26   enum BufferReturnCodes {
27     kOK = 0,
28     kFlushed,
29     kNotFound,
30     kBufferEmpty,
31     kInvalidPacket,
32     kInvalidPointer
33   };
34 
35   // Constructor creates a buffer which can hold a maximum of
36   // |max_number_of_packets| packets.
37   PacketBuffer(size_t max_number_of_packets);
38 
39   // Deletes all packets in the buffer before destroying the buffer.
40   virtual ~PacketBuffer();
41 
42   // Flushes the buffer and deletes all packets in it.
43   virtual void Flush();
44 
45   // Returns true for an empty buffer.
46   virtual bool Empty() const;
47 
48   // Inserts |packet| into the buffer. The buffer will take over ownership of
49   // the packet object.
50   // Returns PacketBuffer::kOK on success, PacketBuffer::kFlushed if the buffer
51   // was flushed due to overfilling.
52   virtual int InsertPacket(Packet* packet);
53 
54   // Inserts a list of packets into the buffer. The buffer will take over
55   // ownership of the packet objects.
56   // Returns PacketBuffer::kOK if all packets were inserted successfully.
57   // If the buffer was flushed due to overfilling, only a subset of the list is
58   // inserted, and PacketBuffer::kFlushed is returned.
59   // The last three parameters are included for legacy compatibility.
60   // TODO(hlundin): Redesign to not use current_*_payload_type and
61   // decoder_database.
62   virtual int InsertPacketList(PacketList* packet_list,
63                                const DecoderDatabase& decoder_database,
64                                uint8_t* current_rtp_payload_type,
65                                uint8_t* current_cng_rtp_payload_type);
66 
67   // Gets the timestamp for the first packet in the buffer and writes it to the
68   // output variable |next_timestamp|.
69   // Returns PacketBuffer::kBufferEmpty if the buffer is empty,
70   // PacketBuffer::kOK otherwise.
71   virtual int NextTimestamp(uint32_t* next_timestamp) const;
72 
73   // Gets the timestamp for the first packet in the buffer with a timestamp no
74   // lower than the input limit |timestamp|. The result is written to the output
75   // variable |next_timestamp|.
76   // Returns PacketBuffer::kBufferEmpty if the buffer is empty,
77   // PacketBuffer::kOK otherwise.
78   virtual int NextHigherTimestamp(uint32_t timestamp,
79                                   uint32_t* next_timestamp) const;
80 
81   // Returns a (constant) pointer the RTP header of the first packet in the
82   // buffer. Returns NULL if the buffer is empty.
83   virtual const RTPHeader* NextRtpHeader() const;
84 
85   // Extracts the first packet in the buffer and returns a pointer to it.
86   // Returns NULL if the buffer is empty. The caller is responsible for deleting
87   // the packet.
88   // Subsequent packets with the same timestamp as the one extracted will be
89   // discarded and properly deleted. The number of discarded packets will be
90   // written to the output variable |discard_count|.
91   virtual Packet* GetNextPacket(size_t* discard_count);
92 
93   // Discards the first packet in the buffer. The packet is deleted.
94   // Returns PacketBuffer::kBufferEmpty if the buffer is empty,
95   // PacketBuffer::kOK otherwise.
96   virtual int DiscardNextPacket();
97 
98   // Discards all packets that are (strictly) older than timestamp_limit,
99   // but newer than timestamp_limit - horizon_samples. Setting horizon_samples
100   // to zero implies that the horizon is set to half the timestamp range. That
101   // is, if a packet is more than 2^31 timestamps into the future compared with
102   // timestamp_limit (including wrap-around), it is considered old.
103   // Returns number of packets discarded.
104   virtual int DiscardOldPackets(uint32_t timestamp_limit,
105                                 uint32_t horizon_samples);
106 
107   // Discards all packets that are (strictly) older than timestamp_limit.
108   virtual int DiscardAllOldPackets(uint32_t timestamp_limit);
109 
110   // Returns the number of packets in the buffer, including duplicates and
111   // redundant packets.
112   virtual size_t NumPacketsInBuffer() const;
113 
114   // Returns the number of samples in the buffer, including samples carried in
115   // duplicate and redundant packets.
116   virtual size_t NumSamplesInBuffer(DecoderDatabase* decoder_database,
117                                     size_t last_decoded_length) const;
118 
119   // Increase the waiting time counter for every packet in the buffer by |inc|.
120   // The default value for |inc| is 1.
121   virtual void IncrementWaitingTimes(int inc = 1);
122 
123   virtual void BufferStat(int* num_packets, int* max_num_packets) const;
124 
125   // Static method that properly deletes the first packet, and its payload
126   // array, in |packet_list|. Returns false if |packet_list| already was empty,
127   // otherwise true.
128   static bool DeleteFirstPacket(PacketList* packet_list);
129 
130   // Static method that properly deletes all packets, and their payload arrays,
131   // in |packet_list|.
132   static void DeleteAllPackets(PacketList* packet_list);
133 
134   // Static method returning true if |timestamp| is older than |timestamp_limit|
135   // but less than |horizon_samples| behind |timestamp_limit|. For instance,
136   // with timestamp_limit = 100 and horizon_samples = 10, a timestamp in the
137   // range (90, 100) is considered obsolete, and will yield true.
138   // Setting |horizon_samples| to 0 is the same as setting it to 2^31, i.e.,
139   // half the 32-bit timestamp range.
IsObsoleteTimestamp(uint32_t timestamp,uint32_t timestamp_limit,uint32_t horizon_samples)140   static bool IsObsoleteTimestamp(uint32_t timestamp,
141                                   uint32_t timestamp_limit,
142                                   uint32_t horizon_samples) {
143     return IsNewerTimestamp(timestamp_limit, timestamp) &&
144            (horizon_samples == 0 ||
145             IsNewerTimestamp(timestamp, timestamp_limit - horizon_samples));
146   }
147 
148  private:
149   size_t max_number_of_packets_;
150   PacketList buffer_;
151   RTC_DISALLOW_COPY_AND_ASSIGN(PacketBuffer);
152 };
153 
154 }  // namespace webrtc
155 #endif  // WEBRTC_MODULES_AUDIO_CODING_NETEQ_PACKET_BUFFER_H_
156