Builder class for creating a manifest. More...

#include <c2pa.hpp>

Public Member Functions
	Builder (IContextProvider &context)
	Create a Builder from a context with an empty manifest.

	Builder (IContextProvider &context, const std::string &manifest_json)
	Create a Builder from a context and manifest JSON string.

	Builder (const std::string &manifest_json)
	Create a Builder from a manifest JSON string (will use global settings if any loaded).

	Builder (C2paBuilder *builder)
	Create a Builder from a raw C FFI builder.

	Builder (const Builder &)=delete

Builder &	operator= (const Builder &)=delete

	Builder (Builder &&other) noexcept

Builder &	operator= (Builder &&other) noexcept

	~Builder ()

C2paBuilder *	c2pa_builder () const noexcept
	Get the underlying C2paBuilder pointer.

Builder &	with_definition (const std::string &manifest_json)
	Set or update the manifest definition.

void	set_no_embed ()
	Set the no-embed flag to prevent embedding the manifest in the asset.

void	set_remote_url (const std::string &remote_url)
	Set the remote URL.

void	set_base_path (const std::string &base_path)
	Set the base path for loading resources from files.

void	add_resource (const std::string &uri, std::istream &source)
	Add a resource to the builder from a stream.

void	add_resource (const std::string &uri, const std::filesystem::path &source_path)
	Add a resource to the builder from a file.

void	add_ingredient (const std::string &ingredient_json, const std::string &format, std::istream &source)
	Add an ingredient to the builder from a stream.

void	add_ingredient (const std::string &ingredient_json, const std::filesystem::path &source_path)
	Add an ingredient to the builder from a file.

void	add_action (const std::string &action_json)
	Add an action to the manifest.

void	set_intent (C2paBuilderIntent intent, C2paDigitalSourceType digital_source_type=Empty)
	Set the intent for this Builder, controlling what kind of manifest to create.

std::vector< unsigned char >	sign (const std::string &format, std::istream &source, std::ostream &dest, Signer &signer)
	Sign an input stream and write the signed data to an output stream.

std::vector< unsigned char >	sign (const std::string &format, std::istream &source, std::iostream &dest, Signer &signer)
	Sign an input stream and write the signed data to an I/O stream.

std::vector< unsigned char >	sign (const std::filesystem::path &source_path, const std::filesystem::path &dest_path, Signer &signer)
	Sign a file and write the signed data to an output file.

std::vector< unsigned char >	sign (const std::string &format, std::istream &source, std::iostream &dest)
	Sign using the signer from the Builder's Context.

std::vector< unsigned char >	sign (const std::filesystem::path &source_path, const std::filesystem::path &dest_path)
	Sign a file using the signer from the Builder's Context.

Builder &	with_archive (std::istream &archive)
	Load an archive into this builder.

void	to_archive (std::ostream &dest)
	Write the builder to an archive stream.

void	to_archive (const std::filesystem::path &dest_path)
	Write the builder to an archive file.

std::vector< unsigned char >	data_hashed_placeholder (uintptr_t reserved_size, const std::string &format)
	Create a hashed placeholder from the builder.

std::vector< unsigned char >	sign_data_hashed_embeddable (Signer &signer, const std::string &data_hash, const std::string &format, std::istream *asset=nullptr)
	Sign a Builder using the specified signer and data hash.

bool	needs_placeholder (const std::string &format)
	Check if the given format requires a placeholder embedding step.

std::vector< unsigned char >	placeholder (const std::string &format)
	Create a composed placeholder manifest to embed in the asset.

void	set_data_hash_exclusions (const std::vector< std::pair< uint64_t, uint64_t > > &exclusions)
	Register the byte ranges where the placeholder was embedded (DataHash workflow).

void	update_hash_from_stream (const std::string &format, std::istream &stream)
	Compute and store the asset hash by reading a stream.

std::vector< unsigned char >	sign_embeddable (const std::string &format)
	Sign and return the final manifest bytes, ready for embedding.

Static Public Member Functions
static Builder	from_archive (std::istream &archive)
	Create a Builder from an archived Builder stream.

static Builder	from_archive (const std::filesystem::path &archive_path)
	Create a Builder from an archive.

static std::vector< unsigned char >	format_embeddable (const std::string &format, std::vector< unsigned char > &data)
	Convert unformatted manifest data to an embeddable format.

static std::vector< std::string >	supported_mime_types ()
	Get a list of mime types that the Builder supports.

Detailed Description

Builder class for creating a manifest.

This class is used to create a manifest from a json std::string and add resources and ingredients to the manifest.

Constructor & Destructor Documentation

◆ Builder() [1/6]

c2pa::Builder::Builder ( IContextProvider & context )

explicit

Create a Builder from a context with an empty manifest.

Parameters

context Context provider; used at construction to configure settings.

Exceptions

C2paException if context.is_valid() returns false, or for other errors encountered by the C2PA library.

◆ Builder() [2/6]

c2pa::Builder::Builder	(	IContextProvider &	context,
		const std::string &	manifest_json
	)

Create a Builder from a context and manifest JSON string.

Parameters

context	Context provider; used at construction to configure settings.
manifest_json	The manifest JSON string.

Exceptions

C2paException if context.is_valid() returns false, or for other errors encountered by the C2PA library.

◆ Builder() [3/6]

c2pa::Builder::Builder ( const std::string & manifest_json )

Create a Builder from a manifest JSON string (will use global settings if any loaded).

Parameters

manifest_json The manifest JSON string.

Exceptions

C2paException for errors encountered by the C2PA library.

Deprecated:: Use Builder(IContextProvider& context, manifest_json) instead.

◆ Builder() [4/6]

c2pa::Builder::Builder ( C2paBuilder * builder )

explicit

Create a Builder from a raw C FFI builder.

Parameters

builder Raw C2paBuilder pointer to wrap.

Exceptions

C2paException if builder is nullptr.

◆ Builder() [5/6]

c2pa::Builder::Builder ( const Builder & )

delete

◆ Builder() [6/6]

c2pa::Builder::Builder ( Builder && other )

inlinenoexcept

852 : builder(std::exchange(other.builder, nullptr)) {

853 }

◆ ~Builder()

c2pa::Builder::~Builder ( )

Member Function Documentation

◆ add_action()

void c2pa::Builder::add_action ( const std::string & action_json )

Add an action to the manifest.

Parameters

action_json JSON string containing the action data.

Exceptions

C2paException for errors encountered by the C2PA library.

◆ add_ingredient() [1/2]

void c2pa::Builder::add_ingredient	(	const std::string &	ingredient_json,
		const std::filesystem::path &	source_path
	)

Add an ingredient to the builder from a file.

Parameters

ingredient_json	Any fields of the ingredient you want to define.
source_path	The path to the ingredient file.

Exceptions

C2paException for errors encountered by the C2PA library.

Note: Prefer using the streaming APIs if possible.

◆ add_ingredient() [2/2]

void c2pa::Builder::add_ingredient	(	const std::string &	ingredient_json,
		const std::string &	format,
		std::istream &	source
	)

Add an ingredient to the builder from a stream.

Parameters

ingredient_json	Any fields of the ingredient you want to define.
format	The mime format of the ingredient.
source	The input stream to read the ingredient from.

Exceptions

C2paException for errors encountered by the C2PA library.

◆ add_resource() [1/2]

void c2pa::Builder::add_resource	(	const std::string &	uri,
		const std::filesystem::path &	source_path
	)

Add a resource to the builder from a file.

Parameters

uri	The URI identifier for the resource.
source_path	The path to the resource file.

Exceptions

C2paException for errors encountered by the C2PA library.

Note: Prefer using the streaming APIs if possible.

◆ add_resource() [2/2]

void c2pa::Builder::add_resource	(	const std::string &	uri,
		std::istream &	source
	)

Add a resource to the builder from a stream.

Parameters

uri	The URI identifier for the resource.
source	The input stream to read the resource from.

Exceptions

C2paException for errors encountered by the C2PA library.

◆ c2pa_builder()

C2paBuilder * c2pa::Builder::c2pa_builder ( ) const

noexcept

Get the underlying C2paBuilder pointer.

Returns: Pointer managed by this wrapper.

◆ data_hashed_placeholder()

std::vector< unsigned char > c2pa::Builder::data_hashed_placeholder	(	uintptr_t	reserved_size,
		const std::string &	format
	)

Create a hashed placeholder from the builder.

Parameters

reserved_size	The size required for a signature from the intended signer (in bytes).
format	The mime format or extension of the asset.

Returns: A vector containing the hashed placeholder bytes.

Exceptions

C2paException for errors encountered by the C2PA library.

◆ format_embeddable()

static std::vector< unsigned char > c2pa::Builder::format_embeddable	(	const std::string &	format,
		std::vector< unsigned char > &	data
	)

static

Convert unformatted manifest data to an embeddable format.

Parameters

format	The format for embedding.
data	Unformatted manifest data from sign_data_hashed_embeddable using "c2pa" format.

Returns: A formatted copy of the data.

◆ from_archive() [1/2]

static Builder c2pa::Builder::from_archive ( const std::filesystem::path & archive_path )

static

Create a Builder from an archive.

Parameters

archive_path The path to the archive file.

Returns: A new Builder instance loaded from the archive.

Exceptions

C2paException for errors encountered by the C2PA library.

Note: Prefer using the streaming APIs if possible.

◆ from_archive() [2/2]

static Builder c2pa::Builder::from_archive ( std::istream & archive )

static

Create a Builder from an archived Builder stream.

Parameters

archive The input stream to read the archive from.

Returns: A new Builder instance loaded from the archive.

Exceptions

C2paException for errors encountered by the C2PA library.

◆ needs_placeholder()

bool c2pa::Builder::needs_placeholder ( const std::string & format )

Check if the given format requires a placeholder embedding step.

Returns false for BoxHash-capable formats when prefer_box_hash is enabled in the context settings (no placeholder needed — hash covers the full asset). Always returns true for BMFF formats (MP4, etc.) regardless of settings.

Parameters

format The MIME type or extension of the asset (e.g. "image/jpeg", "video/mp4").

Returns: true if placeholder() must be called and embedded before sign_embeddable(); false otherwise.

Exceptions

C2paException on error.

◆ operator=() [1/2]

Builder & c2pa::Builder::operator= ( Builder && other )

inlinenoexcept

                                                     {
            if (this != &other) {
                c2pa_free(builder);
                builder = std::exchange(other.builder, nullptr);
            }
            return *this;
        }

◆ operator=() [2/2]

Builder & c2pa::Builder::operator= ( const Builder & )

delete

◆ placeholder()

std::vector< unsigned char > c2pa::Builder::placeholder ( const std::string & format )

Create a composed placeholder manifest to embed in the asset.

The signer (and its reserve size) are obtained from the Builder's Context. For BMFF assets, the placeholder includes a BmffHash assertion with default exclusions for the manifest UUID box. Returns empty bytes for formats that do not need a placeholder (BoxHash). The placeholder size is stored internally so sign_embeddable() returns bytes of exactly the same size, enabling in-place patching.

Parameters

format The MIME type or extension of the asset (e.g. "image/jpeg", "video/mp4").

Returns: Composed placeholder bytes ready to embed into the asset.

Exceptions

C2paException on error.

◆ set_base_path()

void c2pa::Builder::set_base_path ( const std::string & base_path )

Set the base path for loading resources from files.

When set, resources are loaded from files relative to this path. If not set, resources are loaded from memory.

Parameters

base_path The base directory path.

Exceptions

C2paException for errors encountered by the C2PA library.

Deprecated:: This method is planned to be deprecated in a future release. Usage should be limited and temporary. Use add_resource instead.

◆ set_data_hash_exclusions()

void c2pa::Builder::set_data_hash_exclusions ( const std::vector< std::pair< uint64_t, uint64_t > > & exclusions )

Register the byte ranges where the placeholder was embedded (DataHash workflow).

Call this after embedding the placeholder bytes into the asset and before update_hash_from_stream(). The exclusions replace the dummy ranges set by placeholder() so the asset hash covers all bytes except the manifest slot. Exclusions are (start, length) pairs in asset byte coordinates.

Parameters

exclusions Vector of (start, length) pairs describing the embedded placeholder region.

Exceptions

C2paException if no DataHash assertion exists or on other error.

◆ set_intent()

void c2pa::Builder::set_intent	(	C2paBuilderIntent	intent,
		C2paDigitalSourceType	digital_source_type = `Empty`
	)

Set the intent for this Builder, controlling what kind of manifest to create.

Parameters

intent	The intent type: Create, Edit, or Update.
digital_source_type	Required for Create intent. Describes how the asset was produced. Defaults to Empty.

Exceptions

C2paException if the intent cannot be set.

◆ set_no_embed()

void c2pa::Builder::set_no_embed ( )

Set the no-embed flag to prevent embedding the manifest in the asset.

When set, the manifest will be stored externally rather than embedded.

◆ set_remote_url()

void c2pa::Builder::set_remote_url ( const std::string & remote_url )

Set the remote URL.

Parameters

remote_url The remote URL to set.

Exceptions

C2paException for errors encountered by the C2PA library.

◆ sign() [1/5]

std::vector< unsigned char > c2pa::Builder::sign	(	const std::filesystem::path &	source_path,
		const std::filesystem::path &	dest_path
	)

Sign a file using the signer from the Builder's Context.

The signer may have been set programmatically via ContextBuilder::with_signer(), or configured in settings JSON. If both programmatic and settings signers are present, the programmatic signer takes priority.

Parameters

source_path	The path to the file to sign.
dest_path	The path to write the signed file to.

Returns: A vector containing the signed manifest bytes.

Exceptions

C2paException if the context has no signer or on other errors.

◆ sign() [2/5]

std::vector< unsigned char > c2pa::Builder::sign	(	const std::filesystem::path &	source_path,
		const std::filesystem::path &	dest_path,
		Signer &	signer
	)

Sign a file and write the signed data to an output file.

Parameters

source_path	The path to the file to sign.
dest_path	The path to write the signed file to.
signer	The signer object to use for signing.

Returns: A vector containing the signed manifest bytes.

Exceptions

C2paException for errors encountered by the C2PA library.

Note: Prefer using the streaming APIs if possible.

◆ sign() [3/5]

std::vector< unsigned char > c2pa::Builder::sign	(	const std::string &	format,
		std::istream &	source,
		std::iostream &	dest
	)

Sign using the signer from the Builder's Context.

The Signer may have been set programmatically via ContextBuilder::with_signer(), or configured in settings JSON. If both programmatic and settings signers are present, the programmatic signer takes priority.

Parameters

format	The mime format of the output.
source	The input stream to sign.
dest	The I/O stream to write the signed data to.

Returns: A vector containing the signed manifest bytes.

Exceptions

C2paException if the context has no signer or on other errors.

◆ sign() [4/5]

std::vector< unsigned char > c2pa::Builder::sign	(	const std::string &	format,
		std::istream &	source,
		std::iostream &	dest,
		Signer &	signer
	)

Sign an input stream and write the signed data to an I/O stream.

Parameters

format	The mime format of the output.
source	The input stream to sign.
dest	The I/O stream to write the signed data to.
signer	The Signer object to use for signing.

Returns: A vector containing the signed manifest bytes.

Exceptions

C2paException for errors encountered by the C2PA library.

◆ sign() [5/5]

std::vector< unsigned char > c2pa::Builder::sign	(	const std::string &	format,
		std::istream &	source,
		std::ostream &	dest,
		Signer &	signer
	)

Sign an input stream and write the signed data to an output stream.

Parameters

format	The mime format of the output stream.
source	The input stream to sign.
dest	The output stream to write the signed data to.
signer	The Signer object to use for signing.

Returns: A vector containing the signed manifest bytes.

Exceptions

C2paException for errors encountered by the C2PA library.

Deprecated:: Use sign(const string&, std::istream&, std::iostream&, Signer&) instead.

◆ sign_data_hashed_embeddable()

std::vector< unsigned char > c2pa::Builder::sign_data_hashed_embeddable	(	Signer &	signer,
		const std::string &	data_hash,
		const std::string &	format,
		std::istream *	asset = `nullptr`
	)

Sign a Builder using the specified signer and data hash.

Parameters

signer	The signer to use for signing.
data_hash	The data hash ranges to sign (must contain hashes unless an asset is provided).
format	The mime format for embedding. Use "c2pa" for an unformatted result.
asset	Optional asset to hash according to the data_hash information.

Returns: A vector containing the signed embeddable data.

Exceptions

C2paException for errors encountered by the C2PA library.

◆ sign_embeddable()

std::vector< unsigned char > c2pa::Builder::sign_embeddable ( const std::string & format )

Sign and return the final manifest bytes, ready for embedding.

Operates in two modes:

Placeholder mode (after placeholder()): zero-pads the signed manifest to the pre-committed placeholder size, enabling in-place patching of the asset.
Direct mode (no placeholder): returns the actual signed manifest size. Requires a valid hard binding assertion (set via update_hash_from_stream()). The signer is obtained from the Builder's Context.
Parameters

format The MIME type or extension of the asset (e.g. "image/jpeg", "video/mp4").

Returns
Signed manifest bytes ready to embed into the asset.

Exceptions

C2paException on error.

◆ supported_mime_types()

static std::vector< std::string > c2pa::Builder::supported_mime_types ( )

static

Get a list of mime types that the Builder supports.

Returns: Vector of supported MIME type strings.

◆ to_archive() [1/2]

void c2pa::Builder::to_archive ( const std::filesystem::path & dest_path )

Write the builder to an archive file.

Parameters

dest_path The path to write the archive file to.

Exceptions

C2paException for errors encountered by the C2PA library.

Note: Prefer using the streaming APIs if possible.

◆ to_archive() [2/2]

void c2pa::Builder::to_archive ( std::ostream & dest )

Write the builder to an archive stream.

Parameters

dest	The output stream to write the archive to.

Exceptions

C2paException for errors encountered by the C2PA library.

◆ update_hash_from_stream()

void c2pa::Builder::update_hash_from_stream	(	const std::string &	format,
		std::istream &	stream
	)

Compute and store the asset hash by reading a stream.

Automatically detects the hard binding type from the builder state:

DataHash: uses exclusion ranges already registered via set_data_hash_exclusions().
BmffHash: uses path-based exclusions from the BMFF assertion (UUID box, mdat).
BoxHash: hashes each format-specific box individually. Call set_data_hash_exclusions() before this for DataHash workflows.
Parameters

format The MIME type or extension of the asset (e.g. "image/jpeg", "video/mp4").

stream The asset stream to hash. Must include the embedded placeholder bytes.

Exceptions

C2paException on error.

◆ with_archive()

Builder & c2pa::Builder::with_archive ( std::istream & archive )

Load an archive into this builder.

Replaces the current definition with the archived builder state.

Parameters

archive The input stream to read the archive from.

Returns: Reference to this builder for method chaining.

Exceptions

C2paException for errors encountered by the C2PA library.

Note: This allows setting a context before loading the archive, preserving context settings.

◆ with_definition()

Builder & c2pa::Builder::with_definition ( const std::string & manifest_json )

Set or update the manifest definition.

Parameters

manifest_json The manifest JSON string.

Returns: Reference to this Builder for method chaining.

Exceptions

C2pa::C2paException for errors encountered by the C2PA library.

The documentation for this class was generated from the following file:

c2pa.hpp

format	The MIME type or extension of the asset (e.g. "image/jpeg", "video/mp4").
stream	The asset stream to hash. Must include the embedded placeholder bytes.

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Builder() [1/6]

◆ Builder() [2/6]

◆ Builder() [3/6]

◆ Builder() [4/6]

◆ Builder() [5/6]

◆ Builder() [6/6]

◆ ~Builder()

Member Function Documentation

◆ add_action()

◆ add_ingredient() [1/2]

◆ add_ingredient() [2/2]

◆ add_resource() [1/2]

◆ add_resource() [2/2]

◆ c2pa_builder()

◆ data_hashed_placeholder()

◆ format_embeddable()

◆ from_archive() [1/2]

◆ from_archive() [2/2]

◆ needs_placeholder()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ placeholder()

◆ set_base_path()

◆ set_data_hash_exclusions()

◆ set_intent()

◆ set_no_embed()

◆ set_remote_url()

◆ sign() [1/5]

◆ sign() [2/5]

◆ sign() [3/5]

◆ sign() [4/5]

◆ sign() [5/5]

◆ sign_data_hashed_embeddable()

◆ sign_embeddable()

◆ supported_mime_types()

◆ to_archive() [1/2]

◆ to_archive() [2/2]

◆ update_hash_from_stream()

◆ with_archive()

◆ with_definition()