Struct XmpFile 

pub struct XmpFile { /* private fields */ }

High-level API for working with XMP metadata in files

This struct provides a file-like API similar to the original xmp-toolkit-rs, but works across all platforms including Wasm.

Platform Support

• Native platforms (iOS, Android, macOS, Windows): Can use open_file()
• Wasm: Use from_bytes() or from_reader() with in-memory data

File Update Behavior

When a file is opened with XmpOptions::for_update, changes made via XmpFile::put_xmp are not written to disk immediately. The file remains open and changes are only written when XmpFile::close or XmpFile::try_close is called.

Example

use xmpkit::{XmpFile, XmpOptions, XmpMeta, XmpValue};

let mut file = XmpFile::new();
file.open_with("image.jpg", XmpOptions::default().for_update())?;

if let Some(mut meta) = file.get_xmp().cloned() {
    meta.set_property(
        "http://ns.adobe.com/xap/1.0/",
        "CreatorTool",
        XmpValue::String("MyApp".to_string()),
    )?;
    file.put_xmp(meta);
}

// Changes are written to disk when try_close() is called
file.try_close()?;

Implementations

impl XmpFile

pub fn new() -> Self

Create a new empty XmpFile

Use open_file() or from_*() methods to load metadata from a file.

pub fn open_with<P: AsRef<Path>>( &mut self, path: P, options: XmpOptions, ) -> XmpResult<()>

Open a file from a path with options (native platforms only)

Platform Support

• Native platforms (iOS, Android, macOS, Windows)
• Wasm: Not supported (use from_bytes() or from_reader() instead)

Example

use xmpkit::{XmpFile, XmpOptions};

let mut file = XmpFile::new();
file.open_with("image.jpg", XmpOptions::default().for_update())?;

pub fn scan_for_xmp_packet(file_data: &[u8]) -> XmpResult<Option<XmpMeta>>

Scan file content for XMP packet (packet scanning mode)

This method searches for XMP packets in file content by looking for the <?xpacket marker. Used when packet scanning is requested.

pub fn open<P: AsRef<Path>>(&mut self, path: P) -> XmpResult<()>

Open a file from a path (native platforms only)

Platform Support

• Native platforms (iOS, Android, macOS, Windows)
• Wasm: Not supported (use from_bytes() or from_reader() instead)

Example

use xmpkit::XmpFile;

let mut file = XmpFile::new();
file.open("image.jpg")?;

pub fn from_bytes(&mut self, data: &[u8]) -> XmpResult<()>

Open a file from bytes (all platforms, including Wasm)

This is the recommended method for Wasm environments.

Example

use xmpkit::XmpFile;

let jpeg_data: &[u8] = /* your JPEG file data */;
let mut file = XmpFile::new();
file.from_bytes(jpeg_data)?;

pub fn from_bytes_with( &mut self, data: &[u8], options: XmpOptions, ) -> XmpResult<()>

Open a file from bytes with options (all platforms, including Wasm)

This method allows you to specify opening options, such as forcing packet scanning or requiring a smart handler.

Example

use xmpkit::{XmpFile, XmpOptions};

let data: &[u8] = /* your file data */;
let mut file = XmpFile::new();
file.from_bytes_with(data, XmpOptions::default().use_packet_scanning())?;

pub fn from_reader<R: Read + Seek>(&mut self, reader: R) -> XmpResult<()>

Open a file from a reader (all platforms, including Wasm)

This is the most flexible method, accepting any type that implements Read + Seek. Use this when you have a custom reader or need maximum flexibility.

Example

use std::io::Cursor;
use xmpkit::XmpFile;

let data: Vec<u8> = /* your JPEG file data */;
let cursor = Cursor::new(data);
let mut file = XmpFile::new();
file.from_reader(cursor)?;

pub fn from_reader_with<R: Read + Seek>( &mut self, reader: R, options: XmpOptions, ) -> XmpResult<()>

Open a file from a reader with options (all platforms, including Wasm)

This method allows you to specify opening options when reading from a reader.

Example

use std::io::Cursor;
use xmpkit::{XmpFile, XmpOptions};

let data: Vec<u8> = /* your file data */;
let cursor = Cursor::new(data);
let mut file = XmpFile::new();
file.from_reader_with(cursor, XmpOptions::default().strict())?;

pub fn get_xmp(&self) -> Option<&XmpMeta>

Get the XMP metadata

Returns None if no metadata has been loaded or found.

pub fn get_xmp_mut(&mut self) -> Option<&mut XmpMeta>

Get mutable reference to XMP metadata

Returns None if no metadata has been loaded or found.

pub fn put_xmp(&mut self, meta: XmpMeta)

Put XMP metadata

Replaces any existing metadata.

Update Behavior

• If the file was opened with XmpOptions::for_update, changes are not written to disk immediately. Call XmpFile::close or XmpFile::try_close to write changes to disk.
• If the file was opened read-only, this only updates the in-memory metadata.

Example

use xmpkit::{XmpFile, XmpOptions, XmpMeta, XmpValue};

let mut file = XmpFile::new();
file.open_with("image.jpg", XmpOptions::default().for_update())?;

let mut meta = file.get_xmp().cloned().unwrap_or_else(XmpMeta::new);
meta.set_property(
    "http://ns.adobe.com/xap/1.0/",
    "CreatorTool",
    XmpValue::String("MyApp".to_string()),
)?;
file.put_xmp(meta);

// Write changes to disk
file.try_close()?;

pub fn close(&mut self)

Explicitly closes an opened file.

Performs any necessary output to the file and closes it. Files that are opened for update are written to only when closing.

If the file is opened for read-only access (using XmpOptions::for_read), the disk file is closed immediately after reading the data from it; the XmpFile struct, however, remains in the open state. You must call XmpFile::close when finished using it.

Platform Support

• Native platforms: Writes changes to disk if opened for update
• Wasm: Only cleans up internal state (file writing not supported)

Errors

This method ignores errors for backward compatibility. If you want to handle errors, use XmpFile::try_close instead.

Example

use xmpkit::{XmpFile, XmpOptions};

let mut file = XmpFile::new();
file.open_with("image.jpg", XmpOptions::default().for_update())?;
// ... modify metadata ...
file.close(); // Ignores errors

pub fn try_close(&mut self) -> XmpResult<()>

Explicitly closes an opened file with error handling.

Performs any necessary output to the file and closes it. Files that are opened for update are written to only when closing.

If the file is opened for read-only access (using XmpOptions::for_read), the disk file is closed immediately after reading the data from it; the XmpFile struct, however, remains in the open state. You must call XmpFile::try_close when finished using it.

Platform Support

• Native platforms: Writes changes to disk if opened for update
• Wasm: Only cleans up internal state (file writing not supported)

Errors

Returns an error if writing the file fails (native platforms only).

Example

use xmpkit::{XmpFile, XmpOptions};

let mut file = XmpFile::new();
file.open_with("image.jpg", XmpOptions::default().for_update())?;
// ... modify metadata ...
file.try_close()?; // Returns error if write fails

pub fn save<P: AsRef<Path>>(&self, path: P) -> XmpResult<()>

Write XMP metadata to a file path (native platforms only)

Platform Support

• Native platforms (iOS, Android, macOS, Windows)
• Wasm: Not supported (use write_to_bytes() or write_to_writer() instead)

Example

use xmpkit::{XmpFile, XmpMeta};

let mut file = XmpFile::new();
file.open("image.jpg")?;
// ... modify metadata ...
file.save("output.jpg")?;

pub fn write_to_bytes(&self) -> XmpResult<Vec<u8>>

Write XMP metadata to bytes (all platforms, including Wasm)

This is the recommended method for Wasm environments.

Example

use xmpkit::XmpFile;

let input_data: &[u8] = /* your JPEG file data */;
let mut file = XmpFile::new();
file.from_bytes(input_data)?;
// ... modify metadata ...
let output_data = file.write_to_bytes()?;

pub fn write_to_writer<W: Write + Seek>(&self, writer: W) -> XmpResult<()>

Write XMP metadata to a writer (all platforms, including Wasm)

This is the most flexible method, accepting any type that implements Write + Seek.

Note

This method requires the original file data to be available. The file data is only stored when:

• The file was opened with XmpOptions::for_update
• The file was opened with packet scanning mode
• No handler was found and packet scanning fallback was used

For read-only operations where a handler was found, the file data is not stored to save memory. In this case, use XmpFile::open_with with XmpOptions::for_update if you need to write changes.

Example

use std::io::Cursor;
use xmpkit::{XmpFile, XmpOptions};

let mut file = XmpFile::new();
// Open with for_update to enable writing
file.open_with("image.jpg", XmpOptions::default().for_update())?;
// ... modify metadata ...
let mut output = Vec::new();
let cursor = Cursor::new(&mut output);
file.write_to_writer(cursor)?;

Trait Implementations

impl Default for XmpFile

fn default() -> Self

Returns the “default value” for a type.