Struct xmp_toolkit::XmpFile
source · [−]pub struct XmpFile { /* private fields */ }
Expand description
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
sourceimpl XmpFile
impl XmpFile
sourcepub fn open_file<P: AsRef<Path>>(
&mut self,
path: P,
flags: OpenFileOptions
) -> Result<(), XmpFileError>
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. SeeOpenFileOptions
.
sourcepub fn xmp(&mut self) -> Option<XmpMeta>
pub fn xmp(&mut self) -> Option<XmpMeta>
Retrieves the XMP metadata from an open file.
If no XMP is present, will return None
.
sourcepub fn can_put_xmp(&self, meta: &XmpMeta) -> bool
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.
sourcepub fn put_xmp(&mut self, meta: &XmpMeta)
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.
sourcepub fn close(&mut self)
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
Auto Trait Implementations
impl RefUnwindSafe for XmpFile
impl !Send for XmpFile
impl !Sync for XmpFile
impl Unpin for XmpFile
impl UnwindSafe for XmpFile
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more