diff --git a/include/c2pa.hpp b/include/c2pa.hpp index 74c82392..a6d608ed 100644 --- a/include/c2pa.hpp +++ b/include/c2pa.hpp @@ -48,6 +48,8 @@ namespace c2pa { + /// @typedef SignerInfo + /// @brief Type alias for C2paSignerInfo from the C API. typedef C2paSignerInfo SignerInfo; // Forward declarations for context types @@ -69,28 +71,38 @@ namespace c2pa }; /// @brief Set errno from StreamError and return error sentinel. + /// @param e The StreamError value to convert to errno. /// @return OperationResult::Error (-1) for use as C API error return. inline int stream_error_return(StreamError e) noexcept { errno = static_cast(e); return static_cast(OperationResult::Error); } - /// C2paException class for C2pa errors. + /// @brief Exception class for C2pa errors. /// This class is used to throw exceptions for errors encountered by the C2pa library via c2pa_error(). class C2PA_CPP_API C2paException : public std::exception { public: + /// @brief Default constructor. + /// @details Creates an exception and retrieves the error message from the C2PA library. C2paException(); + /// @brief Construct an exception with a custom error message. + /// @param message The error message. explicit C2paException(std::string message); ~C2paException() override = default; C2paException(const C2paException&) = default; + C2paException& operator=(const C2paException&) = default; + C2paException(C2paException&&) = default; + C2paException& operator=(C2paException&&) = default; + /// @brief Get the exception message. + /// @return Null-terminated error message string. const char* what() const noexcept override; private: @@ -340,40 +352,44 @@ namespace c2pa C2paContext* context; }; - /// Returns the version of the C2pa library. + /// @brief Get the version of the C2PA library. + /// @return Version string. std::string C2PA_CPP_API version(); - /// Loads C2PA settings from a std::string in a given format. - /// @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 Context::from_json() or Context::from_settings() instead for better thread safety. + /// @brief Load C2PA settings from a string in a given format. + /// @param data The configuration data to load. + /// @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")]] void C2PA_CPP_API load_settings(const std::string& data, const std::string& format); - /// Reads a file and returns the manifest json as a C2pa::String. - /// @param source_path the path to the file to read. - /// @param data_dir the directory to store binary resources (optional). - /// @return a std::string containing the manifest json if a manifest was found. - /// @throws a C2pa::C2paException for errors encountered by the C2PA library. + /// @brief Read a file and return the manifest JSON. + /// @param source_path The path to the file to read. + /// @param data_dir Optional directory to store binary resources. + /// @return Optional string containing the manifest JSON if a manifest was found. + /// @throws C2paException for errors encountered by the C2PA library. + /// @deprecated Use Reader object instead. [[deprecated("Use Reader object instead")]] std::optional C2PA_CPP_API read_file(const std::filesystem::path &source_path, const std::optional data_dir = std::nullopt); - /// Reads a file and returns an ingredient JSON as a C2pa::String. - /// @param source_path the path to the file to read. - /// @param data_dir the directory to store binary resources. - /// @return a std::string containing the ingredient json. - /// @throws a C2pa::C2paException for errors encountered by the C2PA library. + /// @brief Read a file and return an ingredient JSON. + /// @param source_path The path to the file to read. + /// @param data_dir The directory to store binary resources. + /// @return String containing the ingredient JSON. + /// @throws C2paException for errors encountered by the C2PA library. + /// @deprecated Use Reader and Builder.add_ingredient instead. [[deprecated("Use Reader and Builder.add_ingredient")]] std::string C2PA_CPP_API read_ingredient_file(const std::filesystem::path &source_path, const std::filesystem::path &data_dir); - /// Adds the manifest and signs a file. - /// @param source_path the path to the asset to be signed. - /// @param dest_path the path to write the signed file to. - /// @param manifest the manifest json to add to the file. - /// @param signer_info the signer info to use for signing. - /// @param data_dir the directory to store binary resources (optional). - /// @throws a C2pa::C2paException for errors encountered by the C2PA library. + /// @brief Add a manifest and sign a file. + /// @param source_path The path to the asset to be signed. + /// @param dest_path The path to write the signed file to. + /// @param manifest The manifest JSON to add to the file. + /// @param signer_info The signer info to use for signing. + /// @param data_dir Optional directory to store binary resources. + /// @throws C2paException for errors encountered by the C2PA library. + /// @deprecated Use Builder.sign instead. [[deprecated("Use Builder.sign instead")]] void C2PA_CPP_API sign_file(const std::filesystem::path &source_path, const std::filesystem::path &dest_path, @@ -391,12 +407,18 @@ namespace c2pa /// - seeker(context, offset, whence): seek to offset (whence = Start/Current/End); return new position or -1 (set errno). /// - flusher(context): flush; return 0 on success, -1 on error (set errno). - /// @brief Istream Class wrapper for C2paStream. + /// @brief Input stream IStream wrapper for C2paStream. /// @details This class is used to wrap an input stream for use with the C2PA library. class C2PA_CPP_API CppIStream : public C2paStream { public: + /// @brief Pointer to the underlying C2paStream. C2paStream *c_stream; + + /// @brief Construct an input stream wrapper from a std::istream-derived object. + /// @tparam IStream Type derived from std::istream. + /// @param istream The input stream to wrap (must be open and valid). + /// @throws C2paException if stream wrapper creation fails. template explicit CppIStream(IStream &istream) { static_assert(std::is_base_of::value, @@ -408,27 +430,57 @@ namespace c2pa } CppIStream(const CppIStream &) = delete; + CppIStream &operator=(const CppIStream &) = delete; + CppIStream(CppIStream &&) = delete; + CppIStream &operator=(CppIStream &&) = delete; ~CppIStream(); private: + /// @brief Reader callback implementation. + /// @param context Stream context pointer. + /// @param buffer Buffer to read into. + /// @param size Number of bytes to read. + /// @return Number of bytes read, or -1 on error (sets errno). static intptr_t reader(StreamContext *context, uint8_t *buffer, intptr_t size); + + /// @brief Writer callback implementation (not used for input streams). + /// @param context Stream context pointer. + /// @param buffer Buffer to write from. + /// @param size Number of bytes to write. + /// @return -1 (always fails for input streams). static intptr_t writer(StreamContext *context, const uint8_t *buffer, intptr_t size); + + /// @brief Seeker callback implementation. + /// @param context Stream context pointer. + /// @param offset Offset to seek to. + /// @param whence Seek mode (Start/Current/End). + /// @return New stream position, or -1 on error (sets errno). static intptr_t seeker(StreamContext *context, intptr_t offset, C2paSeekMode whence); + + /// @brief Flusher callback implementation (no-op for input streams). + /// @param context Stream context pointer. + /// @return 0 on success. static intptr_t flusher(StreamContext *context); friend class Reader; }; - /// @brief Ostream Class wrapper for C2paStream. + /// @brief Output stream OStream wrapper for C2paStream. /// @details This class is used to wrap an output stream for use with the C2PA library. class C2PA_CPP_API CppOStream : public C2paStream { public: + /// @brief Pointer to the underlying C2paStream. C2paStream *c_stream; + + /// @brief Construct an output stream wrapper from a std::ostream-derived object. + /// @tparam OStream Type derived from std::ostream. + /// @param ostream The output stream to wrap (must be open and valid). + /// @throws C2paException if stream wrapper creation fails. template explicit CppOStream(OStream &ostream) { static_assert(std::is_base_of::value, "Stream must be derived from std::ostream"); @@ -439,16 +491,40 @@ namespace c2pa } CppOStream(const CppOStream &) = delete; + CppOStream &operator=(const CppOStream &) = delete; + CppOStream(CppOStream &&) = delete; + CppOStream &operator=(CppOStream &&) = delete; ~CppOStream(); private: + /// @brief Reader callback implementation (not used for output streams). + /// @param context Stream context pointer. + /// @param buffer Buffer to read into. + /// @param size Number of bytes to read. + /// @return -1 (always fails for output streams). static intptr_t reader(StreamContext *context, uint8_t *buffer, intptr_t size); + + /// @brief Writer callback implementation. + /// @param context Stream context pointer. + /// @param buffer Buffer to write from. + /// @param size Number of bytes to write. + /// @return Number of bytes written, or -1 on error (sets errno). static intptr_t writer(StreamContext *context, const uint8_t *buffer, intptr_t size); + + /// @brief Seeker callback implementation. + /// @param context Stream context pointer. + /// @param offset Offset to seek to. + /// @param whence Seek mode (Start/Current/End). + /// @return New stream position, or -1 on error (sets errno). static intptr_t seeker(StreamContext *context, intptr_t offset, C2paSeekMode whence); + + /// @brief Flusher callback implementation. + /// @param context Stream context pointer. + /// @return 0 on success, -1 on error (sets errno). static intptr_t flusher(StreamContext *context); }; @@ -457,7 +533,13 @@ namespace c2pa class C2PA_CPP_API CppIOStream : public C2paStream { public: + /// @brief Pointer to the underlying C2paStream. C2paStream *c_stream; + + /// @brief Construct an I/O stream wrapper from a std::iostream-derived object. + /// @tparam IOStream Type derived from std::iostream. + /// @param iostream The I/O stream to wrap (must be open and valid). + /// @throws C2paException if stream wrapper creation fails. template CppIOStream(IOStream &iostream) { static_assert(std::is_base_of::value, "Stream must be derived from std::iostream"); @@ -468,16 +550,40 @@ namespace c2pa } CppIOStream(const CppIOStream &) = delete; + CppIOStream &operator=(const CppIOStream &) = delete; + CppIOStream(CppIOStream &&) = delete; + CppIOStream &operator=(CppIOStream &&) = delete; ~CppIOStream(); private: + /// @brief Reader callback implementation. + /// @param context Stream context pointer. + /// @param buffer Buffer to read into. + /// @param size Number of bytes to read. + /// @return Number of bytes read, or -1 on error (sets errno). static intptr_t reader(StreamContext *context, uint8_t *buffer, intptr_t size); + + /// @brief Writer callback implementation. + /// @param context Stream context pointer. + /// @param buffer Buffer to write from. + /// @param size Number of bytes to write. + /// @return Number of bytes written, or -1 on error (sets errno). static intptr_t writer(StreamContext *context, const uint8_t *buffer, intptr_t size); + + /// @brief Seeker callback implementation. + /// @param context Stream context pointer. + /// @param offset Offset to seek to. + /// @param whence Seek mode (Start/Current/End). + /// @return New stream position, or -1 on error (sets errno). static intptr_t seeker(StreamContext *context, intptr_t offset, C2paSeekMode whence); + + /// @brief Flusher callback implementation. + /// @param context Stream context pointer. + /// @return 0 on success, -1 on error (sets errno). static intptr_t flusher(StreamContext *context); }; @@ -494,49 +600,50 @@ namespace c2pa public: /// @brief Create a Reader from a context and stream. - /// @param context Context provider; used at construction to configure settings + /// @param context Context provider; used at construction to configure settings. /// @param format The mime format of the stream. /// @param stream The input stream to read from. - /// @throws C2pa::C2paException if context.is_valid() returns false, + /// @throws C2paException if context.is_valid() returns false, /// or for other errors encountered by the C2PA library. Reader(IContextProvider& context, const std::string &format, std::istream &stream); /// @brief Create a Reader from a context and file path. /// @param context Context provider; used at construction only to configure settings. - /// @param source_path the path to the file to read. - /// @throws C2pa::C2paException if context.is_valid() returns false, + /// @param source_path The path to the file to read. + /// @throws C2paException if context.is_valid() returns false, /// or for other errors encountered by the C2PA library. - /// @note Prefer using the streaming APIs if possible + /// @note Prefer using the streaming APIs if possible. Reader(IContextProvider& context, const std::filesystem::path &source_path); /// @brief Create a Reader from a stream (will use global settings if any loaded). - /// @details The validation_status field in the json contains validation results. + /// @details The validation_status field in the JSON contains validation results. /// @param format The mime format of the stream. /// @param stream The input stream to read from. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @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")]] 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 C2pa::C2paException for errors encountered by the C2PA library. + /// @throws C2paException for errors encountered by the C2PA library. /// @deprecated Use Reader(IContextProvider& context, source_path) instead. - /// @note Prefer using the streaming APIs if possible + /// @note Prefer using the streaming APIs if possible. [[deprecated("Use Reader(IContextProvider& context, source_path) instead")]] Reader(const std::filesystem::path &source_path); // Non-copyable Reader(const Reader&) = delete; + Reader& operator=(const Reader&) = delete; - // Move semantics Reader(Reader&& other) noexcept : c2pa_reader(other.c2pa_reader), owned_stream(std::move(other.owned_stream)), cpp_stream(std::move(other.cpp_stream)) { other.c2pa_reader = nullptr; } + Reader& operator=(Reader&& other) noexcept { if (this != &other) { if (c2pa_reader != nullptr) { @@ -552,35 +659,37 @@ namespace c2pa ~Reader(); - /// @brief Returns if the reader was created from an embedded manifest. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @brief Check if the reader was created from an embedded manifest. + /// @return true if the manifest was embedded in the asset, false if external. + /// @throws C2paException for errors encountered by the C2PA library. [[nodiscard]] inline bool is_embedded() const { return c2pa_reader_is_embedded(c2pa_reader); } /// @brief Returns the remote url of the manifest if this `Reader` - /// obtained the manifest remotely. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// obtained the manifest remotely + /// @return Optional string containing the remote URL, or std::nullopt if manifest was embedded. + /// @throws C2paException for errors encountered by the C2PA library. [[nodiscard]] std::optional remote_url() const; - /// @brief Get the manifest as a json string. - /// @return The manifest as a json string. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @brief Get the manifest as a JSON string. + /// @return The manifest as a JSON string. + /// @throws C2paException for errors encountered by the C2PA library. std::string json() const; - /// @brief Get a resource from the reader and write it to a file. - /// @param uri The uri of the resource. - /// @param path The path to write the resource to. + /// @brief Get a resource from the reader and write it to a file. + /// @param uri The URI of the resource. + /// @param path The file path to write the resource to. /// @return The number of bytes written. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. - /// @note Prefer using the streaming APIs if possible + /// @throws C2paException for errors encountered by the C2PA library. + /// @note Prefer using the streaming APIs if possible. int64_t get_resource(const std::string &uri, const std::filesystem::path &path); - /// @brief Get a resource from the reader and write it to an output stream. - /// @param uri The uri of the resource. + /// @brief Get a resource from the reader and write it to an output stream. + /// @param uri The URI of the resource. /// @param stream The output stream to write the resource to. /// @return The number of bytes written. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @throws C2paException for errors encountered by the C2PA library. int64_t get_resource(const std::string &uri, std::ostream &stream); /// @brief Get the raw C2paReader pointer. @@ -588,55 +697,67 @@ namespace c2pa /// @note This is intended for internal API use and compatibility with C APIs. C2paReader* get_api_internal_raw_reader() const { return c2pa_reader; } - /// @brief Returns a vector of mime types that the SDK is able to - /// read manifests from. + /// @brief Get a list of mime types that the SDK can read manifests from. + /// @return Vector of supported MIME type strings. static std::vector supported_mime_types(); }; - /// @brief Signer Callback function type. - /// @param data the data to sign. - /// @return the signature as a vector of bytes. + /// @brief Signer callback function type. /// @details This function type is used to create a callback function for signing. + /// The callback receives data to sign and returns the signature. + /// @param data The data to sign. + /// @return The signature as a vector of bytes. using SignerFunc = std::vector(const std::vector &); - /// @brief Signer class for creating a signer. + /// @brief Signer class for creating a Signer /// @details This class is used to create a signer from a signing algorithm, certificate, and TSA URI. + /// Supports both callback-based and direct signing methods. class C2PA_CPP_API Signer { private: C2paSigner *signer; - /// tsa_uri checks + /// @brief Validate a TSA URI string. + /// @param tsa_uri The TSA URI to validate. + /// @return Validated C-string pointer. static const char *validate_tsa_uri(const std::string &tsa_uri); + + /// @brief Validate an optional TSA URI. + /// @param tsa_uri The optional TSA URI to validate. + /// @return Validated C-string pointer, or nullptr if nullopt. static const char *validate_tsa_uri(const std::optional &tsa_uri); public: - /// @brief Create a Signer from a callback function, signing algorithm, certificate, and TSA URI. - /// @param callback the callback function to use for signing. - /// @param alg The signing algorithm to use. - /// @param sign_cert The certificate to use for signing. - /// @param tsa_uri The TSA URI to use for time-stamping. + /// @brief Create a Signer from a callback function. + /// @param callback The callback function to use for signing. + /// @param alg The signing algorithm to use (e.g., C2paSigningAlg::PS256). + /// @param sign_cert The signing certificate in PEM format. + /// @param tsa_uri The timestamp authority URI for time-stamping. + /// @throws C2paException if signer creation fails. Signer(SignerFunc *callback, C2paSigningAlg alg, const std::string &sign_cert, const std::string &tsa_uri); - /// @brief Create a signer from a signer pointer and takes ownership of that pointer - /// @param c_signer The signer pointer to use here (should be non null) + /// @brief Create a signer from a Signer pointer and take ownership of that pointer. + /// @param c_signer The C2paSigner pointer (must be non-null). Signer(C2paSigner *c_signer) : signer(c_signer) {} - /// @brief Crates a signer from signer information - /// @param alg Signer algorithm - /// @param sign_cert Signing certificate - /// @param private_key Private key - /// @param tsa_uri URL for timestamping authority + /// @brief Create a Signer from signing credentials. + /// @param alg Signing algorithm name (e.g., "ps256", "es256"). + /// @param sign_cert Signing certificate in PEM format. + /// @param private_key Private key in PEM format. + /// @param tsa_uri Optional timestamp authority URI. + /// @throws C2paException if signer creation fails. Signer(const std::string &alg, const std::string &sign_cert, const std::string &private_key, const std::optional &tsa_uri = std::nullopt); - // Non-copyable Signer(const Signer&) = delete; + Signer& operator=(const Signer&) = delete; - // Move semantics (for ownership transfer) + /// @brief Move constructor. + /// @param other Signer to move from. Signer(Signer&& other) noexcept : signer(other.signer) { other.signer = nullptr; } + Signer& operator=(Signer&& other) noexcept { if (this != &other) { c2pa_free(signer); @@ -648,11 +769,12 @@ namespace c2pa ~Signer(); - /// @brief Get the size to reserve for a signature for this signer. - /// @return Reserved size for the signature. + /// @brief Get the size to reserve for a signature for this Signer. + /// @return Reserved size for the signature in bytes. uintptr_t reserve_size(); - /// @brief Get the C2paSigner + /// @brief Get the underlying C2paSigner pointer. + /// @return Pointer to the C2paSigner object. C2paSigner *c2pa_signer() const noexcept; }; @@ -666,32 +788,32 @@ namespace c2pa public: /// @brief Create a Builder from a context with an empty manifest. /// @param context Context provider; used at construction to configure settings. - /// @throws C2pa::C2paException if context.is_valid() returns false, + /// @throws C2paException if context.is_valid() returns false, /// or for other errors encountered by the C2PA library. explicit Builder(IContextProvider& context); /// @brief Create a Builder from a context and manifest JSON string. /// @param context Context provider; used at construction to configure settings. /// @param manifest_json The manifest JSON string. - /// @throws C2pa::C2paException if context.is_valid() returns false, + /// @throws C2paException if context.is_valid() returns false, /// or for other errors encountered by the C2PA library. Builder(IContextProvider& context, const std::string &manifest_json); - /// @brief Create a Builder from a manifest JSON std::string (will use global settings if any loaded). + /// @brief Create a Builder from a manifest JSON string (will use global settings if any loaded). /// @param manifest_json The manifest JSON string. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @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")]] Builder(const std::string &manifest_json); - // Non-copyable Builder(const Builder&) = delete; + Builder& operator=(const Builder&) = delete; - // Move semantics Builder(Builder&& other) noexcept : builder(other.builder) { other.builder = nullptr; } + Builder& operator=(Builder&& other) noexcept { if (this != &other) { if (builder != nullptr) @@ -714,139 +836,143 @@ namespace c2pa /// @throws C2pa::C2paException for errors encountered by the C2PA library. Builder& with_definition(const std::string &manifest_json); - /// @brief Set the no embed flag. + /// @brief Set the no-embed flag to prevent embedding the manifest in the asset. + /// @details When set, the manifest will be stored externally rather than embedded. void set_no_embed(); /// @brief Set the remote URL. - /// @param remote_url The remote URL to set. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @param remote_url The remote URL to set. + /// @throws C2paException for errors encountered by the C2PA library. void set_remote_url(const std::string &remote_url); /// @brief Set the base path for loading resources from files. - /// Loads from memory if this is not set. - /// @param base_path The base path to set. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @details When set, resources are loaded from files relative to this path. + /// If not set, resources are loaded from memory. + /// @param base_path The base directory path. + /// @throws 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. + /// Usage should be limited and temporary. Use add_resource instead. void set_base_path(const std::string &base_path); - /// @brief Add a resource to the builder. - /// @param uri The uri of the resource. + /// @brief Add a resource to the builder from a stream. + /// @param uri The URI identifier for the resource. /// @param source The input stream to read the resource from. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @throws C2paException for errors encountered by the C2PA library. void add_resource(const std::string &uri, std::istream &source); - /// @brief Add a resource to the builder. - /// @param uri The uri of the resource. - /// @param source_path The path to the resource file. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. - /// @note Prefer using the streaming APIs if possible + /// @brief Add a resource to the builder from a file. + /// @param uri The URI identifier for the resource. + /// @param source_path The path to the resource file. + /// @throws C2paException for errors encountered by the C2PA library. + /// @note Prefer using the streaming APIs if possible. void add_resource(const std::string &uri, const std::filesystem::path &source_path); - /// @brief Add an ingredient to the builder. - /// @param ingredient_json Any fields of the ingredient you want to define. - /// @param format The format of the ingredient file. + /// @brief Add an ingredient to the builder from a stream. + /// @param ingredient_json Any fields of the ingredient you want to define. + /// @param format The mime format of the ingredient. /// @param source The input stream to read the ingredient from. - /// @throws C2pa::C2paException for errors encountered by the C2pa library. + /// @throws C2paException for errors encountered by the C2PA library. void add_ingredient(const std::string &ingredient_json, const std::string &format, std::istream &source); - /// @brief Add an ingredient to the builder. - /// @param ingredient_json Any fields of the ingredient you want to define. - /// @param source_path The path to the ingredient file. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. - /// @note Prefer using the streaming APIs if possible + /// @brief Add an ingredient to the builder from a file. + /// @param ingredient_json Any fields of the ingredient you want to define. + /// @param source_path The path to the ingredient file. + /// @throws C2paException for errors encountered by the C2PA library. + /// @note Prefer using the streaming APIs if possible. void add_ingredient(const std::string &ingredient_json, const std::filesystem::path &source_path); - /// @brief Add an action to the manifest the Builder is constructing. - /// @param action_json JSON std::string containing the action data. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @brief Add an action to the manifest. + /// @param action_json JSON string containing the action data. + /// @throws C2paException for errors encountered by the C2PA library. void add_action(const std::string &action_json); /// @brief Sign an input stream and write the signed data to an output stream. - /// @param format The format of the output stream. + /// @param format The mime format of the output stream. /// @param source The input stream to sign. /// @param dest The output stream to write the signed data to. - /// @param signer + /// @param signer The Signer object to use for signing. /// @return A vector containing the signed manifest bytes. - /// @throws C2pa::C2paException for errors encountered by the C2PA library - /// @deprecated Use `sign(const string&, std::istream&, std::iostream&, Signer&)` + /// @throws C2paException for errors encountered by the C2PA library. + /// @deprecated Use sign(const string&, std::istream&, std::iostream&, Signer&) instead. std::vector sign(const std::string &format, std::istream &source, std::ostream &dest, Signer &signer); - /// @brief Sign an input stream and write the signed data to an output stream. - /// @param format The format of the output stream. + /// @brief Sign an input stream and write the signed data to an I/O stream. + /// @param format The mime format of the output. /// @param source The input stream to sign. - /// @param dest The in/output stream to write the signed data to. - /// @param signer + /// @param dest The I/O stream to write the signed data to. + /// @param signer The Signer object to use for signing. /// @return A vector containing the signed manifest bytes. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @throws C2paException for errors encountered by the C2PA library. std::vector sign(const std::string &format, std::istream &source, std::iostream &dest, Signer &signer); /// @brief Sign a file and write the signed data to an output file. /// @param source_path The path to the file to sign. /// @param dest_path The path to write the signed file to. - /// @param signer A signer object to use when signing. + /// @param signer The signer object to use for signing. /// @return A vector containing the signed manifest bytes. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. - /// @note Prefer using the streaming APIs if possible + /// @throws C2paException for errors encountered by the C2PA library. + /// @note Prefer using the streaming APIs if possible. std::vector sign(const std::filesystem::path &source_path, const std::filesystem::path &dest_path, Signer &signer); - /// @brief Create a Builder from an archived Builder. - /// @param archive The input stream to read the archive from. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @brief Create a Builder from an archived Builder stream. + /// @param archive The input stream to read the archive from. + /// @return A new Builder instance loaded from the archive. + /// @throws C2paException for errors encountered by the C2PA library. static Builder from_archive(std::istream &archive); - /// @brief Create a Builder from an archive - /// @param archive_path the path to the archive file - /// @throws C2pa::C2paException for errors encountered by the C2PA library - /// @note Prefer using the streaming APIs if possible + /// @brief Create a Builder from an archive. + /// @param archive_path The path to the archive file. + /// @return A new Builder instance loaded from the archive. + /// @throws C2paException for errors encountered by the C2PA library. + /// @note Prefer using the streaming APIs if possible. static Builder from_archive(const std::filesystem::path &archive_path); - /// @brief Load an archive into this builder, replacing its current definition - /// with the reloaded archived builder state. + /// @brief Load an archive into this builder. + /// @details Replaces the current definition with the archived builder state. /// @param archive The input stream to read the archive from. /// @return Reference to this builder for method chaining. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @throws C2paException for errors encountered by the C2PA library. /// @note This allows setting a context before loading the archive, preserving context settings. Builder& with_archive(std::istream &archive); /// @brief Write the builder to an archive stream. /// @param dest The output stream to write the archive to. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @throws C2paException for errors encountered by the C2PA library. void to_archive(std::ostream &dest); /// @brief Write the builder to an archive file. /// @param dest_path The path to write the archive file to. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. - /// @note Prefer using the streaming APIs if possible + /// @throws C2paException for errors encountered by the C2PA library. + /// @note Prefer using the streaming APIs if possible. void to_archive(const std::filesystem::path &dest_path); /// @brief Create a hashed placeholder from the builder. - /// @param reserved_size The size required for a signature from the intended signer. - /// @param format The format of the mime type or extension of the asset. - /// @return A vector containing the hashed placeholder. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @param reserved_size The size required for a signature from the intended signer (in bytes). + /// @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. std::vector data_hashed_placeholder(uintptr_t reserved_size, const std::string &format); /// @brief Sign a Builder using the specified signer and data hash. /// @param signer The signer to use for signing. - /// @param data_hash The data hash ranges to sign. This must contain hashes unless an asset is provided. - /// @param format The mime format for embedding into. Use "c2pa" for an unformatted result. - /// @param asset An optional asset to hash according to the data_hash information. - /// @return A vector containing the signed data. - /// @throws C2pa::C2paException for errors encountered by the C2PA library. + /// @param data_hash The data hash ranges to sign (must contain hashes unless an asset is provided). + /// @param format The mime format for embedding. Use "c2pa" for an unformatted result. + /// @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. std::vector sign_data_hashed_embeddable(Signer &signer, const std::string &data_hash, const std::string &format, std::istream *asset = nullptr); - /// @brief convert an unformatted manifest data to an embeddable format. - /// @param format The format for embedding into. - /// @param data An unformatted manifest data block from sign_data_hashed_embeddable using "c2pa" format. + /// @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. static std::vector format_embeddable(const std::string &format, std::vector &data); - /// @brief Returns a vector of mime types that the SDK is able to sign. + /// @brief Get a list of mime types that the Builder supports. + /// @return Vector of supported MIME type strings. static std::vector supported_mime_types(); private: - // Private constructor for Builder from an archive (todo: find a better way to handle this) explicit Builder(std::istream &archive); }; }