Struct xmp_toolkit::XmpFile

pub struct XmpFile { /* private fields */ }

The XmpFile struct allows access to the main (document-level) metadata in a file.

This provides convenient access to the main, or document level, XMP for a file. Use it to obtain metadata from a file, which you can then manipulate with the xmp_meta struct; and to write new or changed metadata back out to a file.

The functions allow you to open a file, read and write the metadata, then close the file. While open, portions of the file might be maintained in RAM data structures. Memory usage can vary considerably depending on file format and access options.

A file can be opened for read-only or read-write access, with typical exclusion for both modes.

Implementations

impl XmpFile

pub fn new() -> XmpFile

Creates a new file struct that is associated with no file.

pub fn open_file<P: AsRef<Path>>(
    &mut self,
    path: P,
    flags: OpenFileOptions
) -> Result<(), XmpFileError>

Opens a file for the requested forms of metadata access.

Opening the file, at a minimum, causes the raw XMP packet to be read from the file. If the file handler supports legacy metadata reconciliation then legacy metadata is also read, unless kXMPFiles_OpenOnlyXMP is passed.

If the file is opened for read-only access (passing kXMPFiles_OpenForRead), the disk file is closed immediately after reading the data from it; the XMPFiles struct, however, remains in the open state until drop() is called.

If you update the XMP, you must call put_xmp() before the struct is dropped; if you do not, any pending updates are lost.

Typically, the XMP is not parsed and legacy reconciliation is not performed until xmp() is called, but this is not guaranteed. Specific file handlers might do earlier parsing of the XMP. Delayed parsing and early disk file close for read-only access are optimizations to help clients implementing file browsers, so that they can access the file briefly and possibly display a thumbnail, then postpone more expensive XMP processing until later.

Arguments

• path: The path for the file.

• flags: A set of option flags that describe the desired access. By default (zero) the file is opened for read-only access and the format handler decides on the level of reconciliation that will be performed. See OpenFileOptions.

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

Retrieves the XMP metadata from an open file.

If no XMP is present, will return None.

pub fn can_put_xmp(&self, meta: &XmpMeta) -> bool

Reports whether this file can be updated with a specific XMP packet.

Use this functino to determine if the file can probably be updated with a given set of XMP metadata. This depends on the size of the packet, the options with which the file was opened, and the capabilities of the handler for the file format. The function obtains the length of the serialized packet for the provided XMP, but does not keep it or modify it, and does not cause the file to be written when closed.

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

Updates the XMP metadata in this object without writing out the file.

This function supplies new XMP for the file. However, the disk file is not written until the struct is closed with close(). The options provided when the file was opened determine if reconciliation is done with other forms of metadata.

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 (passing OpenFileOptions:OPEN_FOR_READ), the disk file is closed immediately after reading the data from it; the XMPFiles object, however, remains in the open state. You must call close() when finished using it. Other methods, such as xmp(), can only be used between the open_file() and close() calls. The XMPFiles destructor does not call close(); if the struct is dropped without closing, any pending updates are lost.

If the file is opened for update (passing OpenFileOptions::OPEN_FOR_UPDATE), the disk file remains open until close() is called. The disk file is only updated once, when close() is called, regardless of how many calls are made to put_xmp().

Trait Implementations

impl Default for XmpFile

fn default() -> Self

Returns the “default value” for a type.

impl Drop for XmpFile

fn drop(&mut self)

Executes the destructor for this type.