Number types

While the C standard allows for variation in the size of most integer types, Koffi enforces the same definition for most primitive types, listed below:

Koffi also accepts BigInt values when converting from JS to C integers. If the value exceeds the range of the C type, Koffi will convert the number to an undefined value. In the reverse direction, BigInt values are automatically used when needed for big 64-bit integers.

Koffi defines a few more types that can change size depending on the OS and the architecture:

Primitive types can be specified by name (in a string) or through koffi.types:

// These two lines do the same:
let struct1 = koffi.struct({ dummy: 'long' });
let struct2 = koffi.struct({ dummy: koffi.types.long });

String types

Koffi can convert JS strings to and from UTF-8, UTF-16 or UTF-32.

Koffi also supports wide strings (wchar_t * or wstring), which use:

• UTF-16 on Windows (where wchar_t is 2 bytes)
• UTF-32 on other platforms (where wchar_t is 4 bytes)

Enum types

New in Koffi 3.0

C enumeration values are stored as integers. The underlying integer type is implementation-defined but Koffi tries to match usual platform behavior.

On POSIX platforms, Koffi follows the following rules:

• If no negative value exists: unsigned int by default, uint64_t if needed
• If any negative value exists: int by default, int64_t if needed

On Windows, things are simpler, and int is used all the time. Koffi will throw an error if any enumeration value does not fit in a 32-bit integer.

// For OpenResult, the underlying type will be unsigned int on POSIX, int on Windows
const OpenResult = koffi.enumeration('OpenResult', {
    Success: 0,
    MissingFile: 1,
    AccessDenied: 2,
    OtherError: 3
});

// For RelativePosition, the underlying type will be int everywhere
const RelativePosition = koffi.enumeration('RelativePosition', {
    Left: -1,
    Center: 0,
    Right: 1
});

// For IntLimits, the underlying type will be int64_t on POSIX, and fail on Windows
const Int64Limits = koffi.enumeration('Int64Limits', {
    Min: -9223372036854775808n,
    Max: 9223372036854775807n
});

You can access the constants in values member of the type object.

console.log(OpenResult.values.MissingFile); // Prints 1
console.log(RelativePosition.values.Left); // Prints -1

You can specify the storage type explicitly as the last argument: koffi.enumeration(name, values, type).

// This one explictly uses int64_t as the underlying type, despite the fact that the values fit inside an int.
const ExplicitEnum = koffi.enumeration('ExplicitEnum', {
    Zero: 0,
    One: 1,
    Two: 2
}, 'int64_t');

Endian-sensitive integers

Koffi defines a bunch of endian-sensitive types, which can be used when dealing with binary data (network payloads, binary file formats, etc.).

You can find an example that uses these types to extract information from a PNG header with transparent endian conversion.