Crate xmp_toolkit
source · [−]Expand description
XMP Toolkit bindings for Rust
This crate provides a binding of the Adobe XMP Toolkit SDK to Rust.
The portions of the binding that are present are believed to be well-tested and correct, but it is not (as of yet) a complete binding.
Contributions that …
- extend the supported platforms (see Officially-supported platforms below)
- extend the supported API surface
… are especially welcomed. Please read the Contributing Guide for more information.
Rust language support
As of this writing, this crate requires Rust version 1.56 or newer. (The CI builds use this version of Rust.) This may be increased to a newer version at any time, but will be noted in the changelog.
This crate follows all of the typical Rust conventions (cargo build
, cargo test
, etc.). There is a build.rs
script which will ensure that the C++ portions of the library are built as needed. It may need to be updated for platforms that haven’t already been tested.
Officially-supported platforms
The following platforms are officially supported and tested.
- Windows latest (64-bit Intel)
- MacOS latest (64-bit Intel)
- Ubuntu latest (64-bit Intel)
All pull requests are validated via GitHub-hosted runners on GitHub Actions and must pass validation on each platform before being merged. These use the latest
version of each OS as defined by GitHub at the time.
Unofficially-supported platforms
The following platforms are believed and intended to work, but are not officially supported:
- MacOS latest (64-bit ARM)
- Ubuntu latest (64-bit ARM)
GitHub does not currently provide GitHub-hosted runners for these platforms and our team has not arranged for self-hosted runners at this time. Since we can not validate each pull request via validation, there is a risk of undetected breakage for any release.
We welcome bug reports and PRs regarding build issues on these and other platforms and will address them to the best of our ability.
Usage
Add this to your Cargo.toml
:
[dependencies]
xmp_toolkit = "0.7.0"
Breaking changes in 0.x series
Upgrading to 0.7 from earlier versions
The XmpMeta::array_property
method has been renamed to XmpMeta::property_array
to make it consistent with the other typed property getters.
The XmpMeta::does_property_exist
method has been renamed to XmpMeta::contains_property
for consistency with other Rust container types.
Upgrading to 0.6 from earlier versions
The XmpMeta::property
method has been changed to return Option<XmpValue<String>>
instead of Option<String>
. You may need to add a .value
dereference to get the
string value from existing calls to the property
accessor. The XMP value flags
(known as XMP_OptionBits
in the C++ XMP Toolkit) are now available via accessors
on the new XmpValue
struct.
The XmpMeta::set_property
and XmpMeta::set_property_date
methods have been changed
to require XmpValue<String>
and XmpValue<XmpDateTime>
, respectively. This allows
you to pass XMP value flags when setting values. XmpValue<T>
implements From<T>
,
so in most cases, the default/pre-existing behavior can be retained by adding .into()
at the call sites.
The XmpDateTime
struct has been meaningfully implemented, meaning it has changed
from an opaque type to a struct containing the date, time, and time zone values as
present in the C++ toolkit.
This version also increases the minimum supported Rust version (MSRV) to 1.56.0.
Upgrading to 0.5 from earlier releases
Prior versions of the Rust XMP Toolkit mostly ignored the possibility that the C++ XMP Toolkit could throw exceptions. Among other things, this created the possibility of unexpected behavior if the C++ runtime attempted to unwind the stack through Rust code.
This version introduces XmpError
and XmpResult
types which mirror the information from the underlying C++ XMP_Error
type and retrofits existing APIs to use them appropriately. (A few APIs which returned Option<...>
were left unchanged; those APIs now map error conditions to a None
response.)
Upgrading to 0.4 from earlier releases
The xmp_const
module has been removed and a new xmp_ns
module has been added, containing constants for many common XMP namespaces. Replace xmp_const::XMP_NS_XMP
with xmp_ns::XMP
.
The OpenFileOptions
mod has been reworked as an opaque type, removing the need for the bitflags crate dependency. Create by using OpenFileOptions::default()
and then calling methods on the struct to add options as needed.
License
The xmp_toolkit
crate is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
See LICENSE-APACHE and LICENSE-MIT.
Note that some components and dependent crates are licensed under different terms; please check the license terms for each crate and component for details.
Modules
Structs
XmpFile::open_file()
.XmpDateTime
.XmpDateTime
struct allows easy conversion between ISO8601 format
(the “native” representation of dates and times in XMP) and other formats.XmpFile
struct allows access to the main (document-level) metadata in
a file.XmpMeta
struct allows you to inspect and modify the data model
of an XMP packet.XmpDateTime
.XmpTime
.Enums
Type Definitions
Result
type for XMP Toolkit operations.