XMPFilesMBS.CanPutXMP(xmpPacket as string) as boolean

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

CanPutXMP() reports whether this file can be updated with a specific XMP packet.

Use 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.

See also:

• CanPutXMP(xmpPacket as XMPMetaMBS) as boolean

Some examples using this method:

• /XMP/Create EXIF
• /XMP/Create XMP
• /XMP/Modify EXIF
• /XMP/Modifying Complex Properties

XMPFilesMBS.CanPutXMP(xmpPacket as XMPMetaMBS) as boolean

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

CanPutXMP() reports whether this file can be updated with a specific XMP packet,
passed in a string object.

See also:

• CanPutXMP(xmpPacket as string) as boolean

XMPFilesMBS.CloseFile(closeFlags as Integer)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

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

If the file is opened for update (passing kOpenForUpdate), the disk file remains
open until CloseFile() is called. The disk file is only updated once, when CloseFile() is called, regardless of how many calls are made to PutXMP().

closeFlags: Option flags for optional closing actions. This bit-flag constant is
defined:

• kUpdateSafely - Write into a temporary file then swap for crash safety.

XMPFilesMBS.Constructor

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Default constructor initializes an object that is associated with no file.

The destructor does not call CloseFile(); pending updates are lost when the destructor is run.

See also:

• Constructor(path as folderitem, format as Integer=&h20202020, OpenFlags as Integer=0)
• Constructor(path as string, format as Integer=&h20202020, OpenFlags as Integer=0)

XMPFilesMBS.Constructor(path as folderitem, format as Integer=&h20202020, OpenFlags as Integer=0)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	10.5	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Opens a file for metadata access.

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 kOpenOnlyXMP is passed. If the file handler supports native thumbnails and kOpenCacheTNail is passed, the native thumbnail is cached.
If the file is opened for read-only access (passing kOpenForRead), the disk file is closed immediately after reading the data from it; the XMPFiles object, however, remains in the open state. You must call CloseFile() when finished using it. Other methods, such as GetXMP(), can only be used between the OpenFile() and CloseFile() calls. The XMPFiles destructor does not call CloseFile(); if you call it without closing, any pending updates are lost.
If the file is opened for update (passing kOpenForUpdate), the disk file remains open until CloseFile() is called. The disk file is only updated once, when CloseFile() is called, regardless of how many calls are made to PutXMP().
Typically, the XMP is not parsed and legacy reconciliation is not performed until GetXMP() 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.

path: The path for the file, appropriate for the local operating system.
format: The format of the file. If the format is unknown (kUnknownFile) the format is determined from the file content. The first handler to check is guessed from the file's extension. Passing a specific format value is generally just a hint about what file handler to try first (instead of the one based on the extension). If kOpenStrictly is set, then any format other than kUnknownFile requires that the file actually be that format; otherwise an exception is thrown.
openFlags: 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. A logical OR of these bit-flag constants:

• kOpenForRead - Open for read-only access.
• kOpenForUpdate - Open for reading and writing.
• kOpenOnlyXMP - Only the XMP is wanted, no reconciliation.
• kOpenCacheTNail - Cache thumbnail if possible, GetThumbnail will be called.
• kOpenStrictly - Be strict about locating XMP and reconciling with other forms. By default, a best effort is made to locate the correct XMP and to reconcile XMP with other forms (if reconciliation is done). This option forces stricter rules, resulting in exceptions for errors. The definition of strictness is specific to each handler, there might be no difference.
• kOpenUseSmartHandler - Require the use of a smart handler.
• kOpenUsePacketScanning - Force packet scanning, do not use a smart handler.

Throws an exception for serious problems.

See also:

• Constructor
• Constructor(path as string, format as Integer=&h20202020, OpenFlags as Integer=0)

XMPFilesMBS.Constructor(path as string, format as Integer=&h20202020, OpenFlags as Integer=0)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Alternate constructor associates the new XMPFiles object with a specific file.

Calls OpenFile() to open the specified file after performing a default construct.

path: The path for the file, specified as an UTF-8 string. (use FolderItem.NativePath)
format: A format hint for the file, if known.
openFlags: Options for how the file is to be opened (for read or read/write, for example). Use a logical OR of these bit-flag constants:

• kOpenForRead
• kOpenForUpdate
• kOpenOnlyXMP
• kOpenCacheTNail
• kOpenStrictly
• kOpenUseSmartHandler
• kOpenUsePacketScanning
• kOpenLimitedScanning
• kOpenInBackground

The destructor does not call CloseFile(); pending updates are lost when the destructor is run.

See also:

• Constructor
• Constructor(path as folderitem, format as Integer=&h20202020, OpenFlags as Integer=0)

XMPFilesMBS.GetFileInfo(byref path as string, byref openFlags as UInt32, byref format as UInt32, byref handlerFlags as UInt32) as boolean

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

GetFileInfo() retrieves basic information about an opened file.

path: A buffer in which to return the path passed to OpenFile(). Can be
null if value is not wanted.

openFlags: A variable in which to return the option flags passed to
OpenFile.
format: A variable in which to return the file format.
handlerFlags: [out] A variable in which to return the handler's capability flags.

Returns true if the file object is in the open state; that is, OpenFile() has been called but CloseFile() has not. False otherwise. Even if the file object is open, the actual disk file might be closed in the host file-system sense; see OpenFile().

XMPFilesMBS.GetXMP(byref xmp as XMPMetaMBS, byref xmppacket as string, byref PacketInfo as XMPPacketInfoMBS) as boolean

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

GetXMP() retrieves the XMP metadata from an open file.

The function reports whether XMP is present in the file; you can choose to retrieve any or all of the parsed XMP, the raw XMP packet, or information about the raw XMP packet. The options provided when the file was opened determine if reconciliation is done with other forms of metadata.

xmp: An XMP object in which to return the parsed XMP metadata.
xmppacket: An string in which to return the raw XMP packet as stored in
the file. The encoding of the packet is given in the packetInfo. Returns an
empty string if the low level file handler does not provide the raw packet.
packetInfo: A packetinfo object in which to return the location and form of the raw XMP in the file. PacketInfo.charForm and PacketInfo.writeable reflect the
raw XMP in the file. The parsed XMP property values are always UTF-8. The writeable flag is taken from the packet trailer; it applies only to "format ignorant" writing. The PacketInfo object always reflects the state of the XMP in the file. The offset, length, and character form do not change as a result of calling PutXMP() unless the file is also written. Some file handlers might not return location or contents of the raw packet string. To determine whether one does, check the kReturnsRawPacket bit returned by GetFormatInfo(). If the low-level file handler does not provide the raw packet location, PacketInfo.offset and PacketInfo.length are both 0, PacketInfo.charForm is UTF-8, and PacketInfo.writeable is false.

XMPFilesMBS.OpenFile(path as folderitem, format as Integer=&h20202020, OpenFlags as Integer=0) as boolean

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	10.5	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Alternate constructor associates the new XMPFiles object with a specific file.

Calls OpenFile() to open the specified file after performing a default construct.

path: The path for the file, specified as folderitem.
format: A format hint for the file, if known.
openFlags: Options for how the file is to be opened (for read or read/write, for example). Use a logical OR of these bit-flag constants:

• kOpenForRead
• kOpenForUpdate
• kOpenOnlyXMP
• kOpenCacheTNail
• kOpenStrictly
• kOpenUseSmartHandler
• kOpenUsePacketScanning
• kOpenLimitedScanning
• kOpenInBackground

The destructor does not call CloseFile(); pending updates are lost when the destructor is run.

See also:

• OpenFile(path as string, format as Integer=&h20202020, OpenFlags as Integer=0) as boolean

XMPFilesMBS.OpenFile(path as string, format as Integer=&h20202020, OpenFlags as Integer=0) as boolean

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

Opens a file for metadata access.

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 kOpenOnlyXMP is passed. If the file handler supports native thumbnails and kOpenCacheTNail is passed, the native thumbnail is cached.
If the file is opened for read-only access (passing kOpenForRead), the disk file is closed immediately after reading the data from it; the XMPFiles object, however, remains in the open state. You must call CloseFile() when finished using it. Other methods, such as GetXMP(), can only be used between the OpenFile() and CloseFile() calls. The XMPFiles destructor does not call CloseFile(); if you call it without closing, any pending updates are lost.
If the file is opened for update (passing kOpenForUpdate), the disk file remains open until CloseFile() is called. The disk file is only updated once, when CloseFile() is called, regardless of how many calls are made to PutXMP().
Typically, the XMP is not parsed and legacy reconciliation is not performed until GetXMP() 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.

path: The path for the file, specified as an UTF-8 string. (use FolderItem.NativePath)
format: The format of the file. If the format is unknown (kUnknownFile) the format is determined from the file content. The first handler to check is guessed from the file's extension. Passing a specific format value is generally just a hint about what file handler to try first (instead of the one based on the extension). If kOpenStrictly is set, then any format other than kUnknownFile requires that the file actually be that format; otherwise an exception is thrown.
openFlags: 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. A logical OR of these bit-flag constants:

• kOpenForRead - Open for read-only access.
• kOpenForUpdate - Open for reading and writing.
• kOpenOnlyXMP - Only the XMP is wanted, no reconciliation.
• kOpenCacheTNail - Cache thumbnail if possible, GetThumbnail will be called.
• kOpenStrictly - Be strict about locating XMP and reconciling with other forms. By default, a best effort is made to locate the correct XMP and to reconcile XMP with other forms (if reconciliation is done). This option forces stricter rules, resulting in exceptions for errors. The definition of strictness is specific to each handler, there might be no difference.
• kOpenUseSmartHandler - Require the use of a smart handler.
• kOpenUsePacketScanning - Force packet scanning, do not use a smart handler.

Returns true if the file is succesfully opened and attached to a file handler. False for anticipated problems, such as passing kOpenUseSmartHandler but not having an appropriate smart handler. Throws an exception for serious problems.

See also:

• OpenFile(path as folderitem, format as Integer=&h20202020, OpenFlags as Integer=0) as boolean

XMPFilesMBS.PutXMP(xmpPacket as string)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

PutXMP() updates the XMP metadata in this object without writing out the file,

Overloads the basic form of the function, allowing you to pass the metadata as a string object instead of an XMP object. It is otherwise identical; see details in the canonical form.

See also:

• PutXMP(xmpPacket as XMPMetaMBS)

Some examples using this method:

• /XMP/Create EXIF
• /XMP/Create XMP
• /XMP/Modify EXIF
• /XMP/Modifying Complex Properties

XMPFilesMBS.PutXMP(xmpPacket as XMPMetaMBS)

Type	Topic	Plugin	Version	macOS	Windows	Linux	iOS	Targets
method	XMP	MBS XMP Plugin	9.4	✅ Yes	✅ Yes	✅ Yes	✅ Yes	All

PutXMP() 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 object is closed with CloseFile(). The options provided when the file was opened determine if reconciliation is done with other forms of metadata.

See also:

• PutXMP(xmpPacket as string)