Skip to content

fix: Add deprecation warnings #274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tmathern merged 1 commit into from
Oct 20, 2026
Merged

fix: Add deprecation warnings #274

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion docs/embeddable-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,9 +189,21 @@ These methods perform the signing workflow: placeholder creation, hashing, and s
| `Builder::update_hash_from_stream(format, stream)` | Reads the asset stream and computes the hard-binding hash. Automatically selects the appropriate path based on format: `BmffHash` for BMFF (skips manifest box), `BoxHash` for chunk-based formats (creates assertion if needed), or `DataHash` (skips exclusion ranges). Takes a `std::istream&`. |
| `Builder::sign_embeddable(format)` | Signs the manifest and returns bytes ready to embed. For placeholder workflows, it pads the output to match the placeholder size for in-place patching. For BoxHash workflows, the output is the actual signed manifest size (not padded), suitable for appending as a new chunk. |

### Deprecated methods

The c2pa-rs 0.92.0 removes C FFI functions behind some `Builder` methods. These methods will be removed when c2pa-c moves to c2pa-rs 0.92.0.

| Deprecated method | Replacement |
|-------------------|-------------|
| `data_hashed_placeholder(reserved_size, format)` | `needs_placeholder(format)`, then `placeholder(format)`. The reserve size comes from the signer on the Context. |
| `sign_data_hashed_embeddable(signer, data_hash, format, asset)` | `set_data_hash_exclusions(exclusions)`, `update_hash_from_stream(format, stream)`, then `sign_embeddable(format)`. The signer comes from the Context. |
| `format_embeddable(format, data)` | `sign_embeddable(format)`, which returns bytes already formatted for `format`. |

For the full replacement flow, see [Using the DataHash placeholder](#using-the-datahash-placeholder).

## Using the DataHash placeholder

Use this workflow for JPEG, PNG, and other non-BMFF formats.
Use this workflow for JPEG, PNG, and other non-BMFF formats.

<!-- If `prefer_box_hash` is enabled, these formats use BoxHash instead and do not require a placeholder — see [Using BoxHash directly](#using-boxhash-directly).

Expand Down
36 changes: 29 additions & 7 deletions include/c2pa.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -538,7 +538,9 @@ namespace c2pa
/// @param format The mimetype of the string.
/// @throws C2paException for errors encountered by the C2PA library.
/// @deprecated Use Context constructors or Context::ContextBuilder instead for better thread safety.
[[deprecated("Use Context::from_json() or Context::from_settings() instead")]]
/// Will be removed when c2pa-c moves to c2pa-rs 0.92.0.
[[deprecated("Use Context(json), Context(settings), or Context::ContextBuilder instead. "
"Will be removed when c2pa-c moves to c2pa-rs 0.92.0.")]]
void C2PA_CPP_API load_settings(const std::string& data, const std::string& format);

/// @defgroup StreamWrappers Stream wrappers for C2PA C API
Expand Down Expand Up @@ -852,16 +854,20 @@ namespace c2pa
/// @param format The mime format of the stream.
/// @param stream The input stream to read from.
/// @throws C2paException for errors encountered by the C2PA library.
/// @deprecated Use Reader(IContextProvider& context, format, stream) instead.
[[deprecated("Use Reader(IContextProvider& context, format, stream) instead")]]
/// @deprecated Use Reader(std::shared_ptr<IContextProvider>, format, stream) instead.
/// Will be removed when c2pa-c moves to c2pa-rs 0.92.0.
[[deprecated("Use Reader(std::shared_ptr<IContextProvider>, format, stream) instead. "
"Will be removed when c2pa-c moves to c2pa-rs 0.92.0.")]]
Reader(const std::string &format, std::istream &stream);

/// @brief Create a Reader from a file path (will use global settings if any loaded).
/// @param source_path The path to the file to read.
/// @throws C2paException for errors encountered by the C2PA library.
/// @deprecated Use Reader(IContextProvider& context, source_path) instead.
/// @deprecated Use Reader(std::shared_ptr<IContextProvider>, source_path) instead.
/// Will be removed when c2pa-c moves to c2pa-rs 0.92.0.
/// @note Prefer using the streaming APIs if possible.
[[deprecated("Use Reader(IContextProvider& context, source_path) instead")]]
[[deprecated("Use Reader(std::shared_ptr<IContextProvider>, source_path) instead. "
"Will be removed when c2pa-c moves to c2pa-rs 0.92.0.")]]
Reader(const std::filesystem::path &source_path);

/// @brief Try to open a Reader from a context and file path when the asset may lack C2PA data.
Expand Down Expand Up @@ -1175,8 +1181,10 @@ namespace c2pa
/// @brief Create a Builder from a manifest JSON string (will use global settings if any loaded).
/// @param manifest_json The manifest JSON string.
/// @throws C2paException for errors encountered by the C2PA library.
/// @deprecated Use Builder(IContextProvider& context, manifest_json) instead.
[[deprecated("Use Builder(IContextProvider& context, manifest_json) instead")]]
/// @deprecated Use Builder(std::shared_ptr<IContextProvider>, manifest_json) instead.
/// Will be removed when c2pa-c moves to c2pa-rs 0.92.0.
[[deprecated("Use Builder(std::shared_ptr<IContextProvider>, manifest_json) instead. "
"Will be removed when c2pa-c moves to c2pa-rs 0.92.0.")]]
Builder(const std::string &manifest_json);

/// @brief Create a Builder from a raw C FFI builder.
Expand Down Expand Up @@ -1373,6 +1381,10 @@ namespace c2pa
/// @param format The mime format or extension of the asset.
/// @return A vector containing the hashed placeholder bytes.
/// @throws C2paException for errors encountered by the C2PA library.
/// @deprecated Use needs_placeholder() and placeholder(format), with the signer configured
/// on the Builder's Context. Will be removed when c2pa-c moves to c2pa-rs 0.92.0.
[[deprecated("Use needs_placeholder() and placeholder(format), with the signer configured "
"on the Builder's Context. Will be removed when c2pa-c moves to c2pa-rs 0.92.0.")]]
std::vector<unsigned char> data_hashed_placeholder(uintptr_t reserved_size, const std::string &format);

/// @brief Sign a Builder using the specified signer and data hash.
Expand All @@ -1382,12 +1394,22 @@ namespace c2pa
/// @param asset Optional asset to hash according to the data_hash information.
/// @return A vector containing the signed embeddable data.
/// @throws C2paException for errors encountered by the C2PA library.
/// @deprecated Use set_data_hash_exclusions(), update_hash_from_stream(), then
/// sign_embeddable(format); the signer comes from the Builder's Context.
/// Will be removed when c2pa-c moves to c2pa-rs 0.92.0.
[[deprecated("Use set_data_hash_exclusions(), update_hash_from_stream(), then sign_embeddable(format); "
"the signer comes from the Builder's Context. "
"Will be removed when c2pa-c moves to c2pa-rs 0.92.0.")]]
std::vector<unsigned char> sign_data_hashed_embeddable(Signer &signer, const std::string &data_hash, const std::string &format, std::istream *asset = nullptr);

/// @brief Convert unformatted manifest data to an embeddable format.
/// @param format The format for embedding.
/// @param data Unformatted manifest data from sign_data_hashed_embeddable using "c2pa" format.
/// @return A formatted copy of the data.
/// @deprecated Use sign_embeddable(format), which returns manifest bytes already formatted
/// for embedding. Will be removed when c2pa-c moves to c2pa-rs 0.92.0.
[[deprecated("Use sign_embeddable(format), which returns manifest bytes already formatted "
"for embedding. Will be removed when c2pa-c moves to c2pa-rs 0.92.0.")]]
static std::vector<unsigned char> format_embeddable(const std::string &format, std::vector<unsigned char> &data);

/// @brief Check if the given format requires a placeholder embedding step.
Expand Down
2 changes: 1 addition & 1 deletion src/c2pa_core.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ namespace c2pa
/// @param data the std::string to load.
/// @param format the mime format of the string.
/// @throws a C2pa::C2paException for errors encountered by the C2PA library.
[[deprecated("Use Settings on Builder and Reader instead")]]
[[deprecated("Use Context(json), Context(settings), or Context::ContextBuilder instead. Will be removed when c2pa-c moves to c2pa-rs 0.92.0.")]]
void load_settings(const std::string &data, const std::string &format)
{
auto result = c2pa_load_settings(data.c_str(), format.c_str());
Expand Down
Loading