Xmp Zig Reference Documentation

Xmp

Current Version: 11.6.1

Chilkat.Xmp

Read, modify, add, remove, and save XMP metadata in JPG and TIFF files.

Chilkat.Xmp is a legacy class for working with embedded XMP metadata in JPG and TIFF image files. It can load image files or image data from memory, locate embedded XMP documents, return XMP metadata as Chilkat.Xml, create new XMP documents, add or update simple string and integer properties, manage arrays and structured properties, add namespace mappings, remove selected XMP properties or entire embedded XMP documents, and save the updated image back to a file or byte buffer.

Legacy class: Chilkat.Xmp is maintained for existing JPG/TIFF XMP workflows, but it is not planned to be extended to support additional file types.

Load JPG or TIFF metadata

Load a JPG or TIFF file from disk or memory and inspect how many embedded XMP documents were found.

Access XMP as XML

Retrieve embedded XMP documents as Chilkat.Xml objects for inspection, editing, or direct XML-level processing.

Add simple properties

Add or update namespace-qualified string and integer properties such as dc:subject, photoshop:Credit, or tiff:XResolution.

Arrays and structures

Work with XMP arrays such as bag, seq, and alt, and manage structured property values.

Namespaces

Use built-in namespace mappings or add custom namespace-to-URI mappings for application-specific XMP properties.

Remove and save

Remove properties, arrays, structures, or embedded XMP documents, then persist changes to a file or return the updated image as a byte buffer.

Common pattern: Load a JPG or TIFF with LoadAppFile or LoadFromBuffer, retrieve an embedded XMP document with GetEmbedded or create one with NewXmp, modify it using the add/remove property methods, then call SaveAppFile or SaveToBuffer to persist the updated image metadata.

Persistence note: Changes made to the XMP XML object are not written back to the image file until SaveAppFile is called. For memory workflows, use SaveToBuffer to obtain the updated JPG or TIFF bytes.

Object Creation

// Add the package once:
//     zig fetch --save https://chilkatdownload.com/11.6.1/chilkat-zig-11.6.1.tar.gz
// and in build.zig:
//     const chilkat = b.dependency("chilkat", .{ .target = target, .optimize = optimize });
//     exe.root_module.addImport("chilkat", chilkat.module("chilkat"));
const chilkat = @import("chilkat");

// Once per process, before any other Chilkat call:
try chilkat.unlockBundle("Anything for 30-day trial");

const xmp = try chilkat.Xmp.init();
defer xmp.deinit();

pub fn init() Allocator.Error!Xmp

Creates the underlying native Chilkat object. Xmp is a one-pointer struct passed by value; copying it copies the handle (two names for one object). Returns error.OutOfMemory if the library could not allocate the object. Use an object from one thread at a time; it may be handed from one thread to another.

pub fn deinit(self: Xmp) void

Releases the native object. Call it exactly once per object (usually with defer); the handle is invalid afterwards. Objects returned by methods are owned by the caller too and are released the same way.

pub fn fromHandle(h: *chilkat.c.CkXmp.HCkXmp) Xmp

Wraps a handle obtained from the C API (chilkat.c.CkXmp), taking ownership of it. The struct's handle field goes the other way, for anything the Zig API does not cover.

Errors and memory

Methods that can fail return an error union: a method whose only outcome is success or failure returns Error!void; a method producing a string returns (Error || Allocator.Error)![:0]u8; a method producing an object returns Error!T. chilkat.Error is error{ChilkatFailed}; the reason for a failure is in getLastErrorText, and the object remains usable. Properties never fail, and methods that answer a question (hasMember, isUnlocked, ...) return a plain bool.

String arguments are [:0]const u8 (UTF-8; string literals can be passed as is). String results are copies allocated with the allocator argument and owned by the caller, so they stay valid across later calls on the same object.

const text = xmp.someMethod(allocator, ...) catch |err| {
    const why = try xmp.getLastErrorText(allocator);
    defer allocator.free(why);
    std.debug.print("{s}\n", .{why});
    return err;
};
defer allocator.free(text);

Properties

DebugLogFilePath

// read/write
pub fn getDebugLogFilePath(self: Xmp, allocator: Allocator) Allocator.Error![:0]u8
pub fn setDebugLogFilePath(self: Xmp, value: [:0]const u8) void

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

A timeout property set to 0, indicating an infinite timeout.
A hang occurring within an event callback in the application code.
An internal bug in the Chilkat code causing the hang.

More Information and Examples

Xmp Zig Reference Documentation

Xmp

Current Version: 11.6.1

Read, modify, add, remove, and save XMP metadata in JPG and TIFF files.

Load JPG or TIFF metadata

Access XMP as XML

Add simple properties

Arrays and structures

Namespaces

Remove and save

Object Creation

Errors and memory

Properties

DebugLogFilePath

LastErrorHtml

LastErrorText

LastErrorXml

LastMethodSuccess

NumEmbedded

StructInnerDescrip

UncommonOptions

VerboseLogging

Version

Methods

AddArray

AddNsMapping

AddSimpleInt

AddSimpleStr

AddStructProp

Append

GetArray

GetEmbedded

GetProperty

GetSimpleInt

GetSimpleStr

GetStructPropNames

GetStructValue

LoadAppFile

NewXmp

RemoveAllEmbedded

RemoveArray

RemoveEmbedded

RemoveNsMapping

RemoveSimple

RemoveStruct

RemoveStructProp

SaveAppFile