media/formats/mp4/box_reader.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_FORMATS_MP4_BOX_READER_H_
   6 #define MEDIA_FORMATS_MP4_BOX_READER_H_
   7
   8 #include <map>
   9 #include <vector>
  10
  11 #include "base/compiler_specific.h"
  12 #include "base/logging.h"
  13 #include "media/base/media_export.h"
  14 #include "media/base/media_log.h"
  15 #include "media/formats/mp4/fourccs.h"
  16 #include "media/formats/mp4/rcheck.h"
  17
  18 namespace media {
  19 namespace mp4 {
  20
  21 class BoxReader;
  22
  23 struct MEDIA_EXPORT Box {
  24   virtual ~Box();
  25
  26   // Parse errors may be logged using the BoxReader's log callback.
  27   virtual bool Parse(BoxReader* reader) = 0;
  28
  29   virtual FourCC BoxType() const = 0;
  30 };
  31
  32 class MEDIA_EXPORT BufferReader {
  33  public:
  34   BufferReader(const uint8* buf, const int size)
  35       : buf_(buf), size_(size), pos_(0) {
  36     CHECK(buf);
  37     CHECK_GE(size, 0);
  38   }
  39
  40   bool HasBytes(int count) { return (pos() + count <= size()); }
  41
  42   // Read a value from the stream, perfoming endian correction, and advance the
  43   // stream pointer.
  44   bool Read1(uint8* v)  WARN_UNUSED_RESULT;
  45   bool Read2(uint16* v) WARN_UNUSED_RESULT;
  46   bool Read2s(int16* v) WARN_UNUSED_RESULT;
  47   bool Read4(uint32* v) WARN_UNUSED_RESULT;
  48   bool Read4s(int32* v) WARN_UNUSED_RESULT;
  49   bool Read8(uint64* v) WARN_UNUSED_RESULT;
  50   bool Read8s(int64* v) WARN_UNUSED_RESULT;
  51
  52   bool ReadFourCC(FourCC* v) WARN_UNUSED_RESULT;
  53
  54   bool ReadVec(std::vector<uint8>* t, int count) WARN_UNUSED_RESULT;
  55
  56   // These variants read a 4-byte integer of the corresponding signedness and
  57   // store it in the 8-byte return type.
  58   bool Read4Into8(uint64* v) WARN_UNUSED_RESULT;
  59   bool Read4sInto8s(int64* v) WARN_UNUSED_RESULT;
  60
  61   // Advance the stream by this many bytes.
  62   bool SkipBytes(int nbytes) WARN_UNUSED_RESULT;
  63
  64   const uint8* data() const { return buf_; }
  65   int size() const { return size_; }
  66   int pos() const { return pos_; }
  67
  68  protected:
  69   const uint8* buf_;
  70   int size_;
  71   int pos_;
  72
  73   template<typename T> bool Read(T* t) WARN_UNUSED_RESULT;
  74 };
  75
  76 class MEDIA_EXPORT BoxReader : public BufferReader {
  77  public:
  78   ~BoxReader();
  79
  80   // Create a BoxReader from a buffer. Note that this function may return NULL
  81   // if an intact, complete box was not available in the buffer. If |*err| is
  82   // set, there was a stream-level error when creating the box; otherwise, NULL
  83   // values are only expected when insufficient data is available.
  84   //
  85   // |buf| is retained but not owned, and must outlive the BoxReader instance.
  86   static BoxReader* ReadTopLevelBox(const uint8* buf,
  87                                     const int buf_size,
  88                                     const LogCB& log_cb,
  89                                     bool* err);
  90
  91   // Read the box header from the current buffer. This function returns true if
  92   // there is enough data to read the header and the header is sane; that is, it
  93   // does not check to ensure the entire box is in the buffer before returning
  94   // true. The semantics of |*err| are the same as above.
  95   //
  96   // |buf| is not retained.
  97   static bool StartTopLevelBox(const uint8* buf,
  98                                const int buf_size,
  99                                const LogCB& log_cb,
 100                                FourCC* type,
 101                                int* box_size,
 102                                bool* err) WARN_UNUSED_RESULT;
 103
 104   // Create a BoxReader from a buffer. |buf| must be the complete buffer, as
 105   // errors are returned when sufficient data is not available. |buf| can start
 106   // with any type of box -- it does not have to be IsValidTopLevelBox().
 107   //
 108   // |buf| is retained but not owned, and must outlive the BoxReader instance.
 109   static BoxReader* ReadConcatentatedBoxes(const uint8* buf,
 110                                            const int buf_size);
 111
 112   // Returns true if |type| is recognized to be a top-level box, false
 113   // otherwise. This returns true for some boxes which we do not parse.
 114   // Helpful in debugging misaligned appends.
 115   static bool IsValidTopLevelBox(const FourCC& type,
 116                                  const LogCB& log_cb);
 117
 118   // Scan through all boxes within the current box, starting at the current
 119   // buffer position. Must be called before any of the *Child functions work.
 120   bool ScanChildren() WARN_UNUSED_RESULT;
 121
 122   // Return true if child with type |child.BoxType()| exists.
 123   bool HasChild(Box* child) WARN_UNUSED_RESULT;
 124
 125   // Read exactly one child box from the set of children. The type of the child
 126   // will be determined by the BoxType() method of |child|.
 127   bool ReadChild(Box* child) WARN_UNUSED_RESULT;
 128
 129   // Read one child if available. Returns false on error, true on successful
 130   // read or on child absent.
 131   bool MaybeReadChild(Box* child) WARN_UNUSED_RESULT;
 132
 133   // Read at least one child. False means error or no such child present.
 134   template<typename T> bool ReadChildren(
 135       std::vector<T>* children) WARN_UNUSED_RESULT;
 136
 137   // Read any number of children. False means error.
 138   template<typename T> bool MaybeReadChildren(
 139       std::vector<T>* children) WARN_UNUSED_RESULT;
 140
 141   // Read all children, regardless of FourCC. This is used from exactly one box,
 142   // corresponding to a rather significant inconsistency in the BMFF spec.
 143   // Note that this method is mutually exclusive with ScanChildren().
 144   template<typename T> bool ReadAllChildren(
 145       std::vector<T>* children) WARN_UNUSED_RESULT;
 146
 147   // Populate the values of 'version()' and 'flags()' from a full box header.
 148   // Many boxes, but not all, use these values. This call should happen after
 149   // the box has been initialized, and does not re-read the main box header.
 150   bool ReadFullBoxHeader() WARN_UNUSED_RESULT;
 151
 152   FourCC type() const   { return type_; }
 153   uint8 version() const { return version_; }
 154   uint32 flags() const  { return flags_; }
 155
 156   const LogCB& log_cb() const { return log_cb_; }
 157
 158  private:
 159   // Create a BoxReader from |buf|. |is_EOS| should be true if |buf| is
 160   // complete stream (i.e. no additional data is expected to be appended).
 161   BoxReader(const uint8* buf, const int size, const LogCB& log_cb, bool is_EOS);
 162
 163   // Must be called immediately after init. If the return is false, this
 164   // indicates that the box header and its contents were not available in the
 165   // stream or were nonsensical, and that the box must not be used further. In
 166   // this case, if |*err| is false, the problem was simply a lack of data, and
 167   // should only be an error condition if some higher-level component knows that
 168   // no more data is coming (i.e. EOS or end of containing box). If |*err| is
 169   // true, the error is unrecoverable and the stream should be aborted.
 170   bool ReadHeader(bool* err);
 171
 172   LogCB log_cb_;
 173   FourCC type_;
 174   uint8 version_;
 175   uint32 flags_;
 176
 177   typedef std::multimap<FourCC, BoxReader> ChildMap;
 178
 179   // The set of child box FourCCs and their corresponding buffer readers. Only
 180   // valid if scanned_ is true.
 181   ChildMap children_;
 182   bool scanned_;
 183
 184   // True if the buffer provided to the reader is the complete stream.
 185   const bool is_EOS_;
 186 };
 187
 188 // Template definitions
 189 template<typename T> bool BoxReader::ReadChildren(std::vector<T>* children) {
 190   RCHECK(MaybeReadChildren(children) && !children->empty());
 191   return true;
 192 }
 193
 194 template<typename T>
 195 bool BoxReader::MaybeReadChildren(std::vector<T>* children) {
 196   DCHECK(scanned_);
 197   DCHECK(children->empty());
 198
 199   children->resize(1);
 200   FourCC child_type = (*children)[0].BoxType();
 201
 202   ChildMap::iterator start_itr = children_.lower_bound(child_type);
 203   ChildMap::iterator end_itr = children_.upper_bound(child_type);
 204   children->resize(std::distance(start_itr, end_itr));
 205   typename std::vector<T>::iterator child_itr = children->begin();
 206   for (ChildMap::iterator itr = start_itr; itr != end_itr; ++itr) {
 207     RCHECK(child_itr->Parse(&itr->second));
 208     ++child_itr;
 209   }
 210   children_.erase(start_itr, end_itr);
 211
 212   DVLOG(2) << "Found " << children->size() << " "
 213            << FourCCToString(child_type) << " boxes.";
 214   return true;
 215 }
 216
 217 template<typename T>
 218 bool BoxReader::ReadAllChildren(std::vector<T>* children) {
 219   DCHECK(!scanned_);
 220   scanned_ = true;
 221
 222   bool err = false;
 223   while (pos_ < size_) {
 224     BoxReader child_reader(&buf_[pos_], size_ - pos_, log_cb_, is_EOS_);
 225     if (!child_reader.ReadHeader(&err)) break;
 226     T child;
 227     RCHECK(child.Parse(&child_reader));
 228     children->push_back(child);
 229     pos_ += child_reader.size();
 230   }
 231
 232   return !err;
 233 }
 234
 235 }  // namespace mp4
 236 }  // namespace media
 237
 238 #endif  // MEDIA_FORMATS_MP4_BOX_READER_H_