formats/bmff/box_matcher.h

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

#ifndef THIRD_PARTY_CREDENTIO_FORMATS_BMFF_BOX_MATCHER_H_
#define THIRD_PARTY_CREDENTIO_FORMATS_BMFF_BOX_MATCHER_H_

#include <cstdint>
#include <utility>
#include <vector>

#include "absl/base/nullability.h"
#include "absl/log/die_if_null.h"
#include "formats/bmff/box_header.h"
#include "proto/bmff_based_hash_assertion.pb.h"
#include "riegeli/bytes/reader.h"

namespace credentio {

// A matcher to match BMFF boxes against an exclusion in the
// BmffBasedHashAssertion.
class BMFFBoxMatcher {
 public:
  struct Range {
    uint64_t offset;  // The offset within the file.
    int64_t length;

    bool operator==(const Range& other) const = default;
  };
  BMFFBoxMatcher(BmffRange bmff_range, riegeli::Reader* absl_nonnull input)
      : bmff_range_(std::move(bmff_range)), input_(*ABSL_DIE_IF_NULL(input)) {}
  // Returns true if the given Box matches the exclusion BmffRange in a
  // BmffBasedHashAssertion.
  bool Matches(BmffBoxHeader header) const;
  // Returns a list of data ranges that should be excluded in the hash, which is
  // empty if the box does not match the BmffRange. The caller is responsible
  // for checking any out order or any overlap of the returned ranges.
  // NOTE: callers must check `Matches` first.
  std::vector<Range> MatchedRanges(BmffBoxHeader header) const;
  // Returns true if this is for matching the entirety of the box, rather than
  // some subsets of the box.
  bool IsMatchingEntireBox() const { return bmff_range_.subsets_size() == 0; }

 private:
  BmffRange bmff_range_;
  riegeli::Reader& input_;
};
}  // namespace credentio

#endif  // THIRD_PARTY_CREDENTIO_FORMATS_BMFF_BOX_MATCHER_H_