c2pa::detail Namespace Reference

Classes
struct	StreamSeekTraits
	Traits (templated): how to seek and get position for a given stream type. More...
struct	StreamSeekTraits< std::iostream >
struct	StreamSeekTraits< std::istream >
struct	StreamSeekTraits< std::ostream >

Functions
bool	error_indicates_manifest_not_found (const char *message) noexcept
	True if the C2PA error message indicates no JUMBF / manifest in the asset (ManifestNotFound).
std::vector< std::string >	c_mime_types_to_vector (const char *const *mime_types, uintptr_t count)
	Converts a C array of C strings to a std::vector of std::string.
constexpr std::ios_base::seekdir	whence_to_seekdir (C2paSeekMode whence) noexcept
	Maps C2PA seek mode to std::ios seek direction.
template<typename Stream >
bool	is_stream_usable (Stream *s) noexcept
	Check if stream is in valid state for I/O operations.
template<typename Stream >
intptr_t	stream_seeker (StreamContext *context, intptr_t offset, C2paSeekMode whence)
template<typename Stream >
intptr_t	stream_reader (StreamContext *context, uint8_t *buffer, intptr_t size)
template<typename Stream , typename Op >
intptr_t	stream_op (StreamContext *context, Op op)
template<typename Stream >
intptr_t	stream_writer (StreamContext *context, const uint8_t *buffer, intptr_t size)
	Writer impl.
template<typename Stream >
intptr_t	stream_flusher (StreamContext *context)
	Flusher impl.
template<typename StreamType >
std::unique_ptr< StreamType >	open_file_binary (const std::filesystem::path &path)
	Open a binary file stream with error handling.
std::string	extract_file_extension (const std::filesystem::path &path) noexcept
	Extract file extension without the leading dot.
std::string	normalize_format (const std::string &format)
	Trim and lowercase a caller-supplied format; empty when format is blank.
std::string	resolve_format (const std::string &format)
	Resolve a format that must be stated explicitly. These paths never infer the container type from content, so a blank format is rejected.
template<typename T >
std::string	c_string_to_string (T *c_result)
	Convert C string result to C++ string with cleanup.
std::vector< unsigned char >	to_byte_vector (const unsigned char *data, int64_t size)
	Convert C byte array result to C++ vector.

Variables
constexpr const char *	kDetectFormatFromContent = ""
	Format asking the library to determine the container type from content.
constexpr const char *	kFormatWhitespace = " \t\n\r\f\v"
	ASCII whitespace ignored around a format.

Function Documentation

c_mime_types_to_vector()

std::vector< std::string > c2pa::detail::c_mime_types_to_vector ( const char *const *  mime_types, uintptr_t  count  )

inline

Converts a C array of C strings to a std::vector of std::string.

Parameters

mime_types	Pointer to an array of C strings (const char*).
count	Number of elements in the array.

Returns

A std::vector containing the strings from the input array.

This function takes ownership of the input array and frees it using c2pa_free_string_array().

                                                                                                   {
  std::vector<std::string> result;
  if (mime_types == nullptr) { return result; }
 
  try {
    result.reserve(count);
    for(uintptr_t i = 0; i < count; i++) {
      if (mime_types[i] != nullptr) {
        result.emplace_back(mime_types[i]);
      }
    }
  } catch (...) {
    c2pa_free_string_array(mime_types, count);
    throw;
  }
 
  c2pa_free_string_array(mime_types, count);
  return result;
}

c_string_to_string()

template<typename T >

std::string c2pa::detail::c_string_to_string ( T *  c_result )

inline

Convert C string result to C++ string with cleanup.

Parameters

c_result

Raw C string from C API

Returns

C++ string (throws if null)

                                                 {
    if (c_result == nullptr) {
        throw C2paException();
    }
    std::string str(c_result);
    c2pa_free(c_result);
    return str;
}

error_indicates_manifest_not_found()

bool c2pa::detail::error_indicates_manifest_not_found ( const char *  message )

inlinenoexcept

True if the C2PA error message indicates no JUMBF / manifest in the asset (ManifestNotFound).

                                                                             {
    return message != nullptr && std::strstr(message, "ManifestNotFound") != nullptr;
}

extract_file_extension()

std::string c2pa::detail::extract_file_extension ( const std::filesystem::path &  path )

inlinenoexcept

Extract file extension without the leading dot.

Parameters

path	Filesystem path

Returns

Extension string (e.g., "jpg" not ".jpg")

                                                                                {
    auto ext = path.extension().string();
    return ext.empty() ? "" : ext.substr(1);
}

is_stream_usable()

template<typename Stream >

bool c2pa::detail::is_stream_usable ( Stream *  s )

inlinenoexcept

Check if stream is in valid state for I/O operations.

                                                 {
    return s && !s->bad();
}

normalize_format()

std::string c2pa::detail::normalize_format ( const std::string &  format )

inline

Trim and lowercase a caller-supplied format; empty when format is blank.

Empty means detection from content, so this alone is enough wherever a blank format is allowed to request that.

                                                                         {
    const auto first = format.find_first_not_of(kFormatWhitespace);
    if (first == std::string::npos) {
        return {};  // Empty or all whitespace.
    }
    const auto last = format.find_last_not_of(kFormatWhitespace);
    std::string normalized(std::string_view(format).substr(first, last - first + 1));
    std::transform(normalized.begin(), normalized.end(), normalized.begin(),
                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
    return normalized;
}

open_file_binary()

template<typename StreamType >

std::unique_ptr< StreamType > c2pa::detail::open_file_binary ( const std::filesystem::path &  path )

inline

Open a binary file stream with error handling.

Template Parameters

StreamType

std::ifstream or std::ofstream

Parameters

path	Path to the file

Returns

Unique pointer to opened stream

{
    auto stream = std::make_unique<StreamType>(
        path,
        std::ios_base::binary
    );
    if (!stream->is_open()) {
        throw C2paException("Failed to open file: " + path.string());
    }
    return stream;
}

resolve_format()

std::string c2pa::detail::resolve_format ( const std::string &  format )

inline

Resolve a format that must be stated explicitly. These paths never infer the container type from content, so a blank format is rejected.

Returns

format trimmed and lowercased.

Exceptions

C2paException

if format is blank.

                                                                       {
    std::string normalized = normalize_format(format);
    if (normalized.empty()) {
        throw C2paException("An explicit format is required.");
    }
    return normalized;
}

stream_flusher()

template<typename Stream >

intptr_t c2pa::detail::stream_flusher

(

StreamContext *

context

)

Flusher impl.

                                                {
    return stream_op<Stream>(context, [](Stream* s) {
        s->flush();
        return 0;
    });
}

stream_op()

template<typename Stream , typename Op >

intptr_t c2pa::detail::stream_op	(	StreamContext *	context,
		Op	op
	)

Get stream from context, used by writer and flusher. Exceptions must not unwind into Rust/C, so any throw is converted to an IoError return.

                                                  {
    try {
        auto* stream = reinterpret_cast<Stream*>(context);
        if (!is_stream_usable(stream)) {
            return stream_error_return(StreamError::IoError);
        }
        const intptr_t result = op(stream);
        if (stream->fail()) {
            return stream_error_return(StreamError::InvalidArgument);
        }
        if (stream->bad()) {
            return stream_error_return(StreamError::IoError);
        }
        return result;
    } catch (...) {
        return stream_error_return(StreamError::IoError);
    }
}

stream_reader()

template<typename Stream >

intptr_t c2pa::detail::stream_reader	(	StreamContext *	context,
		uint8_t *	buffer,
		intptr_t	size
	)

Reader impl. Exceptions must not unwind into Rust/C, so any throw is converted to an IoError return.

                                                                               {
    if (!context || !buffer) {
        return stream_error_return(StreamError::InvalidArgument);
    }
    if (size < 0) {
        return stream_error_return(StreamError::InvalidArgument);
    }
    if (size == 0) {
        return 0;
    }
    try {
        auto* stream = reinterpret_cast<Stream*>(context);
        if (!is_stream_usable(stream)) {
            return stream_error_return(StreamError::IoError);
        }
        stream->read(reinterpret_cast<char*>(buffer), size);
        if (stream->fail()) {
            if (!stream->eof()) {
                return stream_error_return(StreamError::InvalidArgument);
            }
        }
        if (stream->bad()) {
            return stream_error_return(StreamError::IoError);
        }
        return static_cast<intptr_t>(stream->gcount());
    } catch (...) {
        return stream_error_return(StreamError::IoError);
    }
}

stream_seeker()

template<typename Stream >

intptr_t c2pa::detail::stream_seeker	(	StreamContext *	context,
		intptr_t	offset,
		C2paSeekMode	whence
	)

Seeker impl. Exceptions must not unwind into Rust/C, so any throw is converted to an IoError return.

                                                                                     {
    try {
        auto* stream = reinterpret_cast<Stream*>(context);
        if (!is_stream_usable(stream)) {
            return stream_error_return(StreamError::IoError);
        }
        const std::ios_base::seekdir dir = whence_to_seekdir(whence);
        stream->clear();
        StreamSeekTraits<Stream>::seek(stream, offset, dir);
        if (stream->fail()) {
            return stream_error_return(StreamError::InvalidArgument);
        }
        if (stream->bad()) {
            return stream_error_return(StreamError::IoError);
        }
        const int64_t pos = StreamSeekTraits<Stream>::tell(stream);
        if (pos < 0) {
            return stream_error_return(StreamError::IoError);
        }
        return static_cast<intptr_t>(pos);
    } catch (...) {
        return stream_error_return(StreamError::IoError);
    }
}

stream_writer()

template<typename Stream >

intptr_t c2pa::detail::stream_writer	(	StreamContext *	context,
		const uint8_t *	buffer,
		intptr_t	size
	)

Writer impl.

                                                                                     {
    return stream_op<Stream>(context, [buffer, size](Stream* s) {
        s->write(reinterpret_cast<const char*>(buffer), size);
        return size;
    });
}

to_byte_vector()

std::vector< unsigned char > c2pa::detail::to_byte_vector ( const unsigned char *  data, int64_t  size  )

inline

Convert C byte array result to C++ vector.

Parameters

data	Raw byte array from C API
size	Size of the byte array (result from C API call)

Returns

Vector containing the bytes (throws if null or negative size)

This helper extracts the pattern of checking C API results, copying to a vector, and freeing the C-allocated memory. The C API contract is: if result < 0, the operation failed. A null data pointer with size == 0 is a valid empty result (the C API returns null for empty byte arrays).

                                                                                        {
    if (size < 0 || (data == nullptr && size > 0)) {
        c2pa_free(data);  // May be null or allocated, c2pa_free handles both
        throw C2paException();
    }
    if (size == 0) {
        c2pa_free(data);
        return {};
    }
 
    auto result = std::vector<unsigned char>(data, data + size);
    c2pa_free(data);
    return result;
}

whence_to_seekdir()

constexpr std::ios_base::seekdir c2pa::detail::whence_to_seekdir ( C2paSeekMode  whence )

constexprnoexcept

Maps C2PA seek mode to std::ios seek direction.

                                                                             {
    switch (whence) {
        case C2paSeekMode::Start:   return std::ios_base::beg;
        case C2paSeekMode::Current: return std::ios_base::cur;
        case C2paSeekMode::End:     return std::ios_base::end;
        default:                    return std::ios_base::beg;
    }
}

Variable Documentation

kDetectFormatFromContent

constexpr const char* c2pa::detail::kDetectFormatFromContent = ""

inlineconstexpr

Format asking the library to determine the container type from content.

The C API rejects a null format, so absent must be spelled empty.

kFormatWhitespace

constexpr const char* c2pa::detail::kFormatWhitespace = " \t\n\r\f\v"

inlineconstexpr

ASCII whitespace ignored around a format.

Formats are MIME types or extensions, so non-ASCII spaces are deliberately excluded.