excel_api_sys/lib.rs
1#![no_std]
2#![warn(missing_docs)]
3#![doc = include_str!("../README.md")]
4//!
5//! # Raw Excel 12 ABI layer
6//!
7//! This crate mirrors the checked-in Microsoft `XLCALL.H` Excel 12 C API
8//! contract: fixed-width aliases, constants, `XLOPER12`-family layouts, and
9//! callback function-pointer signatures. It is intended for audited FFI
10//! boundaries on 64-bit Windows Excel, not for ordinary application code.
11//!
12//! The types and ownership bits describe an ABI; they do **not** make an
13//! allocation safe to retain, mutate, free, or send across threads. In
14//! particular, an `xlbitDLLFree` or `xlbitXLFree` tag is Excel protocol data,
15//! not a Rust ownership type. Prefer [`excel_api`](https://docs.rs/excel-api)
16//! for borrowed callback views, owned values, return allocation, and typed
17//! callback contexts.
18//!
19//! # Direct-call safety
20//!
21//! A direct caller must verify the Excel callback context, `extern "system"`
22//! calling convention, pointer alignment and accessible lengths, union tag,
23//! allocation origin, and exact cleanup protocol. The initial support target is
24//! 64-bit Excel; 32-bit layouts and non-Windows Excel hosts are unsupported.
25//!
26//! ```no_run
27//! use excel_api_sys::{XLOPER12, XLOPER12Value, xltypeNum};
28//!
29//! let value = XLOPER12 { xltype: xltypeNum, val: XLOPER12Value { num: 42.0 } };
30//! // SAFETY: this local value is tagged as `num`, so reading that selected
31//! // union member is valid. This does not establish Excel callback legality,
32//! // pointer validity, ownership, or worker-thread legality for a real call.
33//! assert_eq!(unsafe { value.val.num }, 42.0);
34//! ```
35#![allow(non_camel_case_types, non_snake_case, non_upper_case_globals)]
36
37/// Raw SDK constants and function IDs.
38///
39/// The individual identifiers intentionally preserve `XLCALL.H` spelling and
40/// are a mechanically audited compatibility surface; see the module-level
41/// ownership and ABI rules above rather than treating a constant as a safe API.
42#[allow(missing_docs)]
43pub mod constants;
44/// Excel worksheet error codes.
45pub mod errors;
46/// Raw Excel callback and entry-point function signatures.
47pub mod functions;
48/// Raw C-layout Excel structures, unions, and primitive aliases.
49pub mod types;
50
51pub use constants::*;
52pub use errors::*;
53pub use functions::*;
54pub use types::*;