RtpPacket class introduced.

webrtc/modules/rtp_rtcp/source/rtp_packet.h

+/*
+ *  Copyright (c) 2016 The WebRTC project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+#ifndef WEBRTC_MODULES_RTP_RTCP_SOURCE_RTP_PACKET_H_
+#define WEBRTC_MODULES_RTP_RTCP_SOURCE_RTP_PACKET_H_
+
+#include <vector>
+
+#include "webrtc/base/basictypes.h"
+#include "webrtc/base/buffer.h"
+#include "webrtc/modules/rtp_rtcp/include/rtp_rtcp_defines.h"
+
+namespace webrtc {
+struct RTPHeader;
+class RtpHeaderExtensionMap;
+class Random;
+
+namespace rtp {
+class Packet {
+ public:
+  using ExtensionType = RTPExtensionType;
+  using ExtensionManager = RtpHeaderExtensionMap;
+  static const size_t kMaxExtensionHeaders = 14;
+
+  bool Parse(const uint8_t* buffer, size_t size);
+  bool Parse(rtc::Buffer packet);
+  void SetExtensionManager(const ExtensionManager* extensions);

[terelius, 2016/04/14 11:36:41]

Please document what this functions does or how it will be used.
If I have called
Packet packet(extension_manager);
packet.Parse(buffer)
packet.SetExtensionManager(new_extension_manager);
can I start using the new extensions immediately, or do I have to
call some other function to re-parse them from the buffer first?

[sprang_webrtc, 2016/04/14 13:41:50]

When do we want to dynamically change extension manager? Feels like it would
make things easier if we could only set it at construction?

[terelius, 2016/04/14 14:05:21]

Though afaik you need the SSRC of the incoming packet to know what extensions
are used, and to get the SSRC you have to parse the header.

[danilchap, 2016/04/14 14:13:19]

After parsing in case of bundling: first need to parse rtp packet to find out
ssrc,
then decide which extension mapping should be used: audio or video.

[terelius, 2016/04/14 14:36:03]

Could you add a comment that clarifies that changing the ExtensionManager does
not modify what's written to the buffer, but allows you to access the new
extensions through GetExtension(). Perhaps also document why this function was
deemed useful.

[danilchap, 2016/04/19 13:54:14]

Added, both in text and as a test.

+
+  // Header.
+  bool Marker() const;
+  uint8_t PayloadType() const;
+  uint16_t SequenceNumber() const;
+  uint32_t Timestamp() const;
+  uint32_t Ssrc() const;
+  std::vector<uint32_t> Csrcs() const;
+  // TODO(danilchap): Remove this function when all code update to use RtpPacket
+  // directly. Function is there just for easier backward compatibilty.
+  void GetHeader(RTPHeader* header) const;
+  // Header extensions.
+  template <typename Extension, typename... Values>
+  bool GetExtension(Values...) const;
+  size_t headers_size() const;
+  // Payload.
+  size_t payload_size() const;
+  size_t padding_size() const;
+  const uint8_t* payload() const;
+  // Buffer.
+  size_t capacity() const;
+  size_t size() const;
+  const uint8_t* data() const;
+  size_t FreeCapacity() const;
+  size_t MaxPayloadSize() const;
+
+  // Reset fields and buffer.
+  void Clear();
+  // Header setters.
+  void CopyHeader(const Packet& packet);
+  void SetMarker(bool marker_bit);
+  void SetPayloadType(uint8_t payload_type);
+  void SetSequenceNumber(uint16_t seq_no);
+  void SetTimestamp(uint32_t timestamp);
+  void SetSsrc(uint32_t ssrc);
+  // Writes csrc list. Assumes:
+  // a) There is enough room left in buffer.
+  // b) Extension headers, payload or padding data has not already been added.
+  void SetCsrcs(const std::vector<uint32_t>& csrcs);
+  // Header extensions.
+  template <typename Extension, typename... Values>
+  bool SetExtension(Values...);
+  template <typename Extension>
+  bool ReserveExtension();
+  // Reserve size_bytes for payload. Returns nullptr on failure.
+  uint8_t* AllocatePayload(size_t size_bytes);
+  void SetPayloadSize(size_t size_bytes);
+  bool SetPadding(uint8_t size_bytes, Random* random);
+
+ protected:
+  explicit Packet(const ExtensionManager* extensions);

[terelius, 2016/04/14 11:36:41]

Am I allowed to call the constructors with a nullptr
as argument? Is there a default constructor?

[sprang_webrtc, 2016/04/14 13:41:50]

Looks like no (there's a dcheck) and no.
You'll probably not use this directly but rely on the send/receive subclasses,
right?

[terelius, 2016/04/14 14:05:21]

I can't see any DCHECK in the constructor, so I assume it is allowed. Also, it
appears to me that we *need* to be able to parse just the standard header
without any extensions, so I think there should be a way to construct a packet
without an ExtensionManager.

[danilchap, 2016/04/14 14:13:19]

There is no default constructor, but it is allowed to create packet without
extensions (either if code do not plan to use any in create mode (or during
testing), or do not know which to use in case of parsing.

RtpPacketReceived has a default constructor that create RtpPacket without
extensions.

And yes, currently rtp::Packet is not expected to be used directly, but through
derived classes.

[terelius, 2016/04/14 14:36:03]

Acknowledged. Could you add a short comment about this, e.g. "If the packet is
constructed with |extensions|==nullptr, then it will only read/write the fixed
header."?

[danilchap, 2016/04/19 13:54:14]

Done.

+  Packet(const ExtensionManager* extensions, size_t capacity);
+  virtual ~Packet();
+
+ private:
+  struct ExtensionInfo {
+    ExtensionType type;
+    uint16_t offset;
+    uint8_t length;
+  };
+  // Helper function for Parse. Fill header fields using data in given buffer,
+  // but does not touch packet own buffer, leaving packet in invalid state.
+  bool ParseBuffer(const uint8_t* buffer, size_t size);
+  // Find an extension based on the type field of the parameter.
+  // If found, length field would be validated, the offset field will be set
+  // and true returned,
+  // otherwise the parameter will be unchanged and false is returned.
+  bool FindExtension(ExtensionType type,
+                     uint8_t length,
+                     uint16_t* offset) const;
+  // Find or allocate an extension, based on the type field of the parameter.
+  // If found, the length field be checked against what is already registered
+  // and the offset field will be set, then true is returned. If allocated, the
+  // length field will be used for allocation and the offset update to indicate
+  // position, the true is returned.
+  // If not found and allocations fails, false is returned and parameter remains
+  // unchanged.
+  bool AllocateExtension(ExtensionType type, uint8_t length, uint16_t* offset);
+
+  uint8_t* WriteAt(size_t offset);
+  void WriteAt(size_t offset, uint8_t byte);
+
+  const ExtensionManager* extensions_;
+  // Header.
+  bool marker_;
+  uint8_t payload_type_;
+  uint8_t padding_size_;
+  uint16_t sequence_number_;
+  uint32_t timestamp_;
+  uint32_t ssrc_;
+  size_t payload_offset_;  // Match header size with csrcs and extensions.
+  size_t payload_size_;
+
+  uint8_t num_extensions_ = 0;
+  ExtensionInfo extension_entries_[kMaxExtensionHeaders];
+  uint16_t extensions_size_ = 0;  // Unaligned.
+  rtc::Buffer buffer_;
+
+  RTC_DISALLOW_COPY_AND_ASSIGN(Packet);
+};
+
+template <typename Extension, typename... Values>
+bool Packet::GetExtension(Values... values) const {
+  uint16_t offset = 0;
+  if (!FindExtension(Extension::kId, Extension::kValueSizeBytes, &offset))
+    return false;
+  return Extension::Parse(data() + offset, values...);
+}
+
+template <typename Extension, typename... Values>
+bool Packet::SetExtension(Values... values) {
+  uint16_t offset = 0;
+  if (!AllocateExtension(Extension::kId, Extension::kValueSizeBytes, &offset))
+    return false;
+  return Extension::Write(WriteAt(offset), values...);
+}
+
+template <typename Extension>
+bool Packet::ReserveExtension() {
+  uint16_t offset = 0;
+  if (!AllocateExtension(Extension::kId, Extension::kValueSizeBytes, &offset))
+    return false;
+  memset(WriteAt(offset), 0, Extension::kValueSizeBytes);
+  return true;
+}
+}  // namespace rtp
+}  // namespace webrtc
+
+#endif  // WEBRTC_MODULES_RTP_RTCP_SOURCE_RTP_PACKET_H_