Global Zig Reference Documentation

Global

Current Version: 11.6.1

Chilkat.Global

Unlock Chilkat and configure library-wide defaults, diagnostics, and async behavior.

Chilkat.Global is the Chilkat class for library-wide initialization, licensing, default behavior, diagnostics, and thread-pool control. Its most important method is UnlockBundle, which should be called once at application startup before using other Chilkat classes. It also provides settings for DNS caching, ANSI code page behavior, NTLM version, IPv6 preference, verbose TLS logging, async task execution, thread-pool limits, thread-pool logging, and special PKCS#7 encoding behavior.

Library unlocking

Call UnlockBundle once during application startup to unlock Chilkat components for use throughout the process.

Global defaults

Configure process-wide defaults such as ANSI code page handling, DNS caching behavior, IPv6 preference, and NTLM version selection.

Diagnostics and logging

Enable additional diagnostic behavior such as verbose TLS logging and thread-pool logging when troubleshooting difficult runtime issues.

Async thread pool

Control the limits and behavior of Chilkat's internal thread pool used by asynchronous task-based methods.

Network-related behavior

Adjust DNS and IP-version preferences that can affect how Chilkat classes resolve names and establish network connections.

Compatibility options

Set specialized process-wide options for interoperability scenarios, such as special PKCS#7 encoding behavior.

Common pattern: Create a Chilkat.Global object at application startup, call UnlockBundle once, then set any process-wide defaults before creating and using other Chilkat objects. Treat these settings as application-wide configuration, not per-object state.

For an extended overview, see Global Class Overview.

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 global = try chilkat.Global.init();
defer global.deinit();

pub fn init() Allocator.Error!Global

Creates the underlying native Chilkat object. Global 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: Global) 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.CkGlobal.HCkGlobal) Global

Wraps a handle obtained from the C API (chilkat.c.CkGlobal), 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 = global.someMethod(allocator, ...) catch |err| {
    const why = try global.getLastErrorText(allocator);
    defer allocator.free(why);
    std.debug.print("{s}\n", .{why});
    return err;
};
defer allocator.free(text);

Properties

AnsiCodePage

// read/write
pub fn getAnsiCodePage(self: Global) i32
pub fn setAnsiCodePage(self: Global, value: i32) void

Introduced in version 9.5.0.49

The default ANSI code page is determined at runtime based on the computer where the application happens to be running. For example, the ANSI code page for an application running on a Japanese computer is likely to be Shift_JIS (code page 932), whereas on a US-English computer it would be iso-8859-1 (or Windows-1252 which is essentially a superset of iso-8859-1).

If there is a desire for the Chilkat library to use a specific ANSI code page regardless of locale, then this property should be set to the desired code page. The default value of this property is the ANSI code page of the local computer.

Global Zig Reference Documentation

Global

Current Version: 11.6.1

Unlock Chilkat and configure library-wide defaults, diagnostics, and async behavior.

Library unlocking

Global defaults

Diagnostics and logging

Async thread pool

Network-related behavior

Compatibility options

Object Creation

Errors and memory

Properties

AnsiCodePage

AutoQBDecode

DebugLogFilePath

DefaultNtlmVersion

DnsTimeToLive

EnableDnsCaching

LastErrorHtml

LastErrorText

LastErrorXml

LastMethodSuccess

MaxThreads

PreferIpv6

ThreadPoolLogPath

UncommonOptions

UnlockStatus

UsePkcsConstructedEncoding

VerboseLogging

VerboseTls

Version

Methods

DnsClearCache

FinalizeThreadPool

ThreadPoolLogLine

UnlockBundle