formats/extractor.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_EXTRACTOR_H_
#define THIRD_PARTY_CREDENTIO_FORMATS_EXTRACTOR_H_

#include <cstdint>
#include <optional>
#include <string>
#include <vector>

#include "absl/status/statusor.h"
#include "absl/strings/string_view.h"
#include "formats/asset_box.h"
#include "formats/byte_range.h"
#include "riegeli/bytes/reader.h"

namespace credentio {

// FormatExtractor for finding the C2PA Manifest Store in an asset, without
// parsing or verifying the manifest store.
class FormatExtractor {
 public:
  virtual ~FormatExtractor() = default;

  struct ExtractOptions {
    bool requires_c2pa = true;
    int64_t end_offset = -1;
  };

  // Returns the extracted C2PA payload from the supplied asset if there is only
  // one found. Returns a NotFoundError for 0 or 2+ C2PA payloads. Returns an
  // error if there was a problem extracting the payload.
  virtual absl::StatusOr<std::string> ExtractManifestStore(
      riegeli::Reader& input) const = 0;

  // Returns the location of the structure in the supplied asset that contains
  // the C2PA Manifest Store. This includes format-specific wrapping, so for
  // example in a JPEG it would cover the sequence of contiguous segments that
  // contain the fragments of the manifest store.
  //
  // If requires_c2pa is true, then an error will be returned if the C2PA
  // Manifest Store is not found.
  virtual absl::StatusOr<std::optional<ByteRange>> ExtractManifestStoreLocation(
      riegeli::Reader& input, ExtractOptions options) const = 0;

  // Returns the extracted boxes from the supplied asset. If requires_c2pa is
  // true, then an error will be returned if the C2PA Manifest Store is not
  // found.
  virtual absl::StatusOr<std::vector<AssetBox>> ExtractBoxes(
      riegeli::Reader& input, ExtractOptions options) const = 0;

  // Lightweight check to determine if the payload may contain a C2PA
  // Manifest Store. This payload is the data contained within defined sequence
  // of bytes within an asset.
  // Example:
  // - For JPEG, this is the data contained within a JPEG segment minus the
  // marker and segment size.
  // - For BMFF, this is the data contained within a BMFF box minus the box
  // header.
  // - For PNG, this is the data contained within a PNG chunk minus the chunk
  // length, type and CRC.
  // - For RIFF, this is the data contained within a RIFF chunk minus the chunk
  // length and type.
  virtual bool MightBeC2paManifestStore(absl::string_view payload) const = 0;
};

}  // namespace credentio

#endif  // THIRD_PARTY_CREDENTIO_FORMATS_EXTRACTOR_H_