Skip to main content

Crate excel_api_sys

Crate excel_api_sys 

Source
Expand description

§excel-api-sys

Raw, no_std, ABI-focused Rust definitions for the 64-bit Microsoft Excel 12 C API. The crate mirrors the checked-in XLCALL.H contract: primitive aliases, constants, C-layout structs/unions, and callback signatures.

This is not a safe ownership layer. XLOPER12 tags and ownership bits describe Excel protocol state; they do not validate pointers, grant Rust ownership, or permit a callback value to escape its lifetime. Direct callers must verify the Excel-issued callback capability, calling convention, tag/union member, pointer alignment and extent, allocation origin, aliasing, and cleanup protocol.

Most XLL authors should depend on excel-api, which provides borrowed views, owned values, return allocation, xlFree RAII, registration, and typed contexts. The supported target is 64-bit Windows Excel; 32-bit Excel and non-Windows hosts are unsupported.

Licensed under either Apache-2.0 or MIT.

§Raw Excel 12 ABI layer

This crate mirrors the checked-in Microsoft XLCALL.H Excel 12 C API contract: fixed-width aliases, constants, XLOPER12-family layouts, and callback function-pointer signatures. It is intended for audited FFI boundaries on 64-bit Windows Excel, not for ordinary application code.

The types and ownership bits describe an ABI; they do not make an allocation safe to retain, mutate, free, or send across threads. In particular, an xlbitDLLFree or xlbitXLFree tag is Excel protocol data, not a Rust ownership type. Prefer excel_api for borrowed callback views, owned values, return allocation, and typed callback contexts.

§Direct-call safety

A direct caller must verify the Excel callback context, extern "system" calling convention, pointer alignment and accessible lengths, union tag, allocation origin, and exact cleanup protocol. The initial support target is 64-bit Excel; 32-bit layouts and non-Windows Excel hosts are unsupported.

use excel_api_sys::{XLOPER12, XLOPER12Value, xltypeNum};

let value = XLOPER12 { xltype: xltypeNum, val: XLOPER12Value { num: 42.0 } };
// SAFETY: this local value is tagged as `num`, so reading that selected
// union member is valid. This does not establish Excel callback legality,
// pointer validity, ownership, or worker-thread legality for a real call.
assert_eq!(unsafe { value.val.num }, 42.0);

Re-exports§

pub use constants::*;
pub use errors::*;
pub use functions::*;
pub use types::*;

Modules§

constants
Raw SDK constants and function IDs.
errors
Excel worksheet error codes.
functions
Raw Excel callback and entry-point function signatures.
types
Raw C-layout Excel structures, unions, and primitive aliases.