jumbf/internal/intermediate.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.
//

// Intermediate types to represent partially-parsed JUMBF structures. Most
// contain references back to the underlying serialized array to minimize
// copies. This behavior is more thoroughly documented at the functions that
// return these structs.
#ifndef THIRD_PARTY_CREDENTIO_JUMBF_INTERNAL_INTERMEDIATE_H_
#define THIRD_PARTY_CREDENTIO_JUMBF_INTERNAL_INTERMEDIATE_H_

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

#include "absl/strings/string_view.h"
#include "uuid/uuid.h"

namespace jumbf_internal {

// A generic box structure, may be of any type (see section 4.3 of standard)
struct IntermediateBox {
  absl::string_view payload;
  // The original serialized representation of this box.
  absl::string_view serialized;
  uint32_t type;
  // Whether this box has an LBox of 0, indicating that it extends to the end
  // of the file.
  bool implicit_length;

  bool operator==(const IntermediateBox&) const = default;
};

// A description box (see section A.3 of standard)
struct IntermediateDescriptionBox {
  // The type UUID, referred to simply as "type" in section A.3, not to be
  // confused with the 32 bit box type described in section 4.3 (all description
  // boxes must have box type "jumd").
  credentio::Uuid type_uuid;

  bool requestable;
  std::optional<absl::string_view> label;
  std::optional<uint32_t> id;
  // The SHA-256 hash of the associated content boxes. In identical byte order
  // to the serialized form as defined in the standard. Note that this value is
  // not verified during the initial parse stage that produces this intermediate
  // struct.
  std::optional<absl::string_view> hash;
  std::optional<IntermediateBox> private_box;

  bool operator==(const IntermediateDescriptionBox&) const = default;
};

// A Super Box, according to the naming convention used in this library. In the
// standard it's referred to as a "JUMBF Box" with the term "superbox" simply
// meaning a box that contains other boxes (see section A.2 of the standard).
struct IntermediateSuperBox {
  IntermediateDescriptionBox description;
  std::vector<IntermediateBox> content;
  // The original serialized representation of this box.
  absl::string_view serialized;

  bool operator==(const IntermediateSuperBox&) const = default;
};

}  // namespace jumbf_internal

#endif  // THIRD_PARTY_CREDENTIO_JUMBF_INTERNAL_INTERMEDIATE_H_