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

// Internal encoding primitives: Functions for writing individual JUMBF
// constructs.
//
// These functions each write a single JUMBF construct. Care is needed to use
// them properly, as callers must track the number of bytes written to properly
// close out Superboxes.
//
// For example, to create a superbox containing a single CBOR content box:
//
// size_t superbox_size = 0;
// CHECK_OK(EncodeContentBox(kCborBoxType, cbor_data, &writer, &superbox_size));
// CHECK_OK(EncodeDescriptionBox(kCborBoxTypeUuid, DescriptionBoxOptions{
//   .label = riegeli::ExternalRef::From("mylabel"),
// }, &writer, &superbox_size));
// CHECK_OK(EncodeBoxHeader(superbox_size, kSuperBoxType, &writer,
//   &superbox_size));
//
// The public `SuperBoxBuilder` class in
// credentio/jumbf/box_builder.h is easier to use.

#ifndef THIRD_PARTY_CREDENTIO_JUMBF_INTERNAL_ENCODE_H_
#define THIRD_PARTY_CREDENTIO_JUMBF_INTERNAL_ENCODE_H_

#include <cstdint>

#include "absl/status/status.h"
#include "absl/strings/cord.h"
#include "jumbf/encode_params.h"
#include "riegeli/base/types.h"
#include "riegeli/bytes/backward_writer.h"
#include "uuid/uuid.h"

namespace jumbf {
// Writes a padding box to `writer`.
absl::Status EncodePaddingBox(uint64_t padding_size,
                              riegeli::BackwardWriter* writer);

// Writes `payload` of the serialized super box to `writer`.
absl::Status EncodeSerializedSuperBox(absl::Cord payload,
                                      riegeli::BackwardWriter* writer);

// Wraps `payload` in a box of type `tbox` and writes it to `writer`.
absl::Status EncodeContentBox(uint32_t tbox, absl::Cord payload,
                              riegeli::BackwardWriter* writer);

// Writes a description box to `writer`.
absl::Status EncodeDescriptionBox(credentio::Uuid type_uuid,
                                  DescriptionBoxOptions options,
                                  riegeli::BackwardWriter* writer);

// Closes a box by writing the header to `writer`.
absl::Status EncodeBoxHeader(riegeli::Position payload_length, uint32_t tbox,
                             riegeli::BackwardWriter* writer);

}  // namespace jumbf

#endif  // THIRD_PARTY_CREDENTIO_JUMBF_INTERNAL_ENCODE_H_