ContextBuilder for creating customized Context instances.
More...
#include <c2pa.hpp>
ContextBuilder for creating customized Context instances.
Provides a builder pattern for configuring contexts with multiple settings. Note: create_context() consumes the builder.
- Note
- For most use cases, prefer direct construction via the Context constructors. The ContextBuilder is useful when you need to layer multiple configuration sources (e.g. with_settings() followed by with_json()).
◆ ContextBuilder() [1/3]
| c2pa::Context::ContextBuilder::ContextBuilder |
( |
| ) |
|
◆ ~ContextBuilder()
| c2pa::Context::ContextBuilder::~ContextBuilder |
( |
| ) |
|
|
noexcept |
◆ ContextBuilder() [2/3]
◆ ContextBuilder() [3/3]
| c2pa::Context::ContextBuilder::ContextBuilder |
( |
const ContextBuilder & |
| ) |
|
|
delete |
◆ create_context()
| Context c2pa::Context::ContextBuilder::create_context |
( |
| ) |
|
Create a Context from the current builder configuration.
- Returns
- A new Context instance.
- Exceptions
-
- Note
- This consumes the builder. After calling this, is_valid() returns false.
◆ is_valid()
| bool c2pa::Context::ContextBuilder::is_valid |
( |
| ) |
const |
|
noexcept |
Check if the builder is in a valid state.
- Returns
- true if the builder can be used, false if moved from.
◆ operator=() [1/2]
◆ operator=() [2/2]
◆ release()
Release ownership of the underlying C2paContextBuilder handle and its progress-callback heap block (if any) to the caller.
After this call is_valid() returns false. The previous C2paContextBuilder* overload was unsound when a progress callback was pending: the C++ builder destructor would free the heap ProgressCallbackFunc while the native side still held its pointer, yielding a use-after-free on the first progress tick. Callers must keep ReleasedBuilder::callback_owner alive for as long as the native context built from ReleasedBuilder::builder exists.
- Returns
- ReleasedBuilder holding both the native builder and (optionally) the owning unique_ptr for the progress callback. Fields are null when moved-from.
◆ with_http_resolver()
| ContextBuilder & c2pa::Context::ContextBuilder::with_http_resolver |
( |
void * |
user_data, |
|
|
C2paHttpResolverCallback |
callback |
|
) |
| |
Set a custom HTTP resolver callback on the context being built.
The callback is invoked synchronously whenever the SDK needs to make an HTTP request (remote manifest fetch, OCSP, timestamp, etc.). The callback receives a C2paHttpRequest and must fill in a C2paHttpResponse. The response body must be allocated with malloc(); the underlying native library will call free().
- Parameters
-
| user_data | Opaque user pointer passed to every callback invocation (may be nullptr). |
| callback | Function pointer matching C2paHttpResolverCallback. |
- Returns
- Reference to this ContextBuilder for method chaining.
- Exceptions
-
| C2paException | if the resolver could not be set or callback is null. |
◆ with_json()
| ContextBuilder & c2pa::Context::ContextBuilder::with_json |
( |
const std::string & |
json | ) |
|
Configure settings with JSON string.
- Parameters
-
| json | JSON configuration string. |
- Returns
- Reference to this ContextBuilder for method chaining.
- Exceptions
-
◆ with_json_settings_file()
| ContextBuilder & c2pa::Context::ContextBuilder::with_json_settings_file |
( |
const std::filesystem::path & |
settings_path | ) |
|
Configure settings from a JSON settings file.
- Parameters
-
| settings_path | Full path to the JSON settings file. |
- Returns
- Reference to this ContextBuilder for method chaining.
- Exceptions
-
◆ with_progress_callback()
Attach a progress callback to the context being built.
The callback is invoked at each major phase of signing and reading operations performed with the resulting context. Return false from the callback to abort the current operation with an OperationCancelled error.
Phases emitted during a typical sign cycle (in order): VerifyingIngredient → VerifyingManifest → VerifyingSignature → VerifyingAssetHash → Thumbnail → Hashing → Signing → Embedding → (if verify_after_sign) VerifyingManifest → … → VerifyingIngredient
Phases emitted during reading: Reading → VerifyingManifest → VerifyingSignature → VerifyingAssetHash → VerifyingIngredient
- Parameters
-
| callback | A callable matching ProgressCallbackFunc. The callback is heap-allocated and owned by the resulting Context. Calling this method more than once on the same builder replaces the previous callback. The callable must not throw when invoked (see ProgressCallbackFunc). |
- Returns
- Reference to this ContextBuilder for method chaining.
- Exceptions
-
◆ with_settings()
Configure with Settings object.
- Parameters
-
| settings | Settings to use (will be copied into the context). Must be valid (is_valid() true). |
- Returns
- Reference to this ContextBuilder for method chaining.
- Exceptions
-
| C2paException | if settings are invalid or settings.is_valid() is false. |
◆ with_signer()
Set a Signer on the context being built.
After this call the source Signer object is consumed and must not be reused, as it becomes part to the context and tied to it. If settings also contain a signer, the programmatic signer set through this API will be used for signing.
- Parameters
-
| signer | Signer to put into the context. |
- Returns
- Reference to this ContextBuilder for method chaining.
- Exceptions
-
The documentation for this class was generated from the following file:
1.9.8