Home | History | Annotate | Download | only in neteq 
      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.
    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