Interface for types that can provide C2PA context functionality. More...

#include <c2pa.hpp>

Inheritance diagram for c2pa::IContextProvider:

Public Member Functions
virtual	~IContextProvider () noexcept=default

virtual C2paContext *	c_context () const noexcept=0
	Get the underlying C2PA context pointer for FFI operations.

virtual bool	is_valid () const noexcept=0
	Check if this provider has a valid context.

Protected Member Functions
	IContextProvider ()=default

	IContextProvider (const IContextProvider &)=delete

IContextProvider &	operator= (const IContextProvider &)=delete

Detailed Description

Interface for types that can provide C2PA context functionality.

This interface can be implemented by external libraries to provide custom context implementations (e.g. AdobeContext wrappers). Reader and Builder accept a shared_ptr<IContextProvider> and extend the provider's lifetime for as long as the Reader/Builder exists.

Progress callback lifetime (post-0322d67): If the native C2paContext* held by the provider was configured with a progress callback, the provider MUST keep the heap-owned ProgressCallbackFunc alive at least as long as the native context. The native side stores only a raw pointer into that heap block and will call it until the context is freed. Destroy order inside the provider: free the native C2paContext* first (stops further callback invocations), then release the callback storage. The built-in Context class enforces this via member declaration order; external providers that adopt a native context built via ContextBuilder::release() must do the same.

Move semantics: Move construction and move assignment are defaulted. After move, the moved-from object is left in a valid but unspecified state: is_valid() may be false and c_context() may return nullptr. Implementations that own a C2paContext* (e.g. Context) must set the source's handle to nullptr on move to avoid double-free; callers must not use a moved-from provider without checking is_valid() first.

Implementation Requirements for is_valid()

The is_valid() method exists to support implementations that may have:

Optional or lazy context initialization
Contexts that can be invalidated or moved
A "no context" state as part of their lifecycle

Why Both c_context() and is_valid()?

While c_context() can return nullptr, is_valid() provides:

A boolean check without pointer inspection (yes/no answer for intialization)
Forward compatibility for implementations with complex context lifecycles (lazy load)

Impact on Reader and Builder

Reader and Builder constructors validate that a provider both exists and is_valid() returns true before using c_context(). This ensures that:

External implementations cannot be used in an uninitialized state
A consistent validation pattern exists across all context-using classes
Errors are caught early at construction time rather than during operations

Standard Context Implementation: The built-in Context class always returns true from is_valid() after successful construction, as it validates the context pointer in its constructor. External implementations may have different invariants.

Constructor & Destructor Documentation

◆ ~IContextProvider()

virtual c2pa::IContextProvider::~IContextProvider ( )

virtualdefaultnoexcept

◆ IContextProvider() [1/2]

c2pa::IContextProvider::IContextProvider ( )

protecteddefault

◆ IContextProvider() [2/2]

c2pa::IContextProvider::IContextProvider ( const IContextProvider & )

protecteddelete

Member Function Documentation

◆ c_context()

virtual C2paContext * c2pa::IContextProvider::c_context ( ) const

pure virtualnoexcept

Get the underlying C2PA context pointer for FFI operations.

Returns: Pointer to C2paContext, or nullptr if not available.

Note: Provider retains ownership; pointer valid for provider's lifetime.

Implemented in c2pa::Context.

◆ is_valid()

virtual bool c2pa::IContextProvider::is_valid ( ) const

pure virtualnoexcept

Check if this provider has a valid context.

Returns: true if context is available, false otherwise.

Note: For standard Context objects, this always returns true after construction. External implementations may return false to indicate uninitialized or invalidated state. Reader and Builder constructors check this before use.

Warning: Implementations must ensure is_valid() == true implies c_context() != nullptr.

Implemented in c2pa::Context.

◆ operator=()

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