Skip to main content

excel_api_sys/
types.rs

1use core::ffi::c_void;
2
3/// Excel 12 Boolean storage (`INT32` in `XLCALL.H`).
4pub type BOOL = i32;
5/// Excel 12 wide character (`WCHAR` in `XLCALL.H`).
6pub type XCHAR = u16;
7/// Excel 12 row index.
8pub type RW = i32;
9/// Excel 12 column index.
10pub type COL = i32;
11/// Excel 12 sheet identifier (`DWORD_PTR` in `XLCALL.H`).
12pub type IDSHEET = usize;
13/// Windows byte used by the Excel C API.
14pub type BYTE = u8;
15/// Windows word used by the Excel C API.
16pub type WORD = u16;
17/// Opaque Windows handle used by `xltypeBigData` results.
18pub type HANDLE = *mut c_void;
19
20/// Pointer aliases used by the SDK declarations.
21pub type LPXLREF12 = *mut XLREF12;
22/// Mutable pointer to a variable-length multi-reference header.
23///
24/// The pointer has no Rust ownership or bounds guarantee.
25pub type LPXLMREF12 = *mut XLMREF12;
26/// Mutable pointer to a variable-length `FP12` header.
27///
28/// The pointer has no Rust ownership or bounds guarantee.
29pub type LPFP12 = *mut FP12;
30/// Mutable pointer to an `XLOPER12` value.
31///
32/// The pointer has no Rust ownership or callback-lifetime guarantee.
33pub type LPXLOPER12 = *mut XLOPER12;
34
35/// One rectangular Excel 12 reference.
36#[repr(C)]
37#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
38pub struct XLREF12 {
39    /// First row, inclusive, in Excel's zero-based raw coordinate system.
40    pub rwFirst: RW,
41    /// Last row, inclusive, in Excel's zero-based raw coordinate system.
42    pub rwLast: RW,
43    /// First column, inclusive, in Excel's zero-based raw coordinate system.
44    pub colFirst: COL,
45    /// Last column, inclusive, in Excel's zero-based raw coordinate system.
46    pub colLast: COL,
47}
48
49/// Variable-length table of Excel 12 references.
50///
51/// The SDK declares `reftbl[1]`, but an allocation contains `count` entries.
52/// This raw definition intentionally preserves the one-element C tail.
53#[repr(C)]
54#[derive(Clone, Copy, Debug)]
55pub struct XLMREF12 {
56    /// Number of valid rectangular references in the trailing allocation.
57    pub count: WORD,
58    /// First element of the C flexible-array tail.
59    ///
60    /// # Safety
61    ///
62    /// Only index past this element after proving the allocation is large
63    /// enough for `count` `XLREF12` values and remains valid for the access.
64    pub reftbl: [XLREF12; 1],
65}
66
67/// Variable-length rectangular floating-point array.
68///
69/// The SDK declares `array[1]`, but an allocation contains `rows * columns`
70/// entries. This raw definition intentionally preserves the one-element C
71/// tail.
72#[repr(C)]
73#[derive(Clone, Copy, Debug)]
74pub struct FP12 {
75    /// Number of rows in the flexible-array payload.
76    pub rows: i32,
77    /// Number of columns in the flexible-array payload.
78    pub columns: i32,
79    /// First element of the C flexible-array tail.
80    ///
81    /// # Safety
82    ///
83    /// Only index past this element after validating the `rows * columns`
84    /// allocation extent and pointer lifetime.
85    pub array: [f64; 1],
86}
87
88/// Inline single-area reference member of `XLOPER12`.
89#[repr(C)]
90#[derive(Clone, Copy, Debug)]
91pub struct XLOPER12SRef {
92    /// Number of areas represented by this inline member; the supported single
93    /// reference form has exactly one.
94    pub count: WORD,
95    /// Named `ref` in the C header; `reference` avoids the Rust keyword.
96    pub reference: XLREF12,
97}
98
99/// External multi-area reference member of `XLOPER12`.
100#[repr(C)]
101#[derive(Clone, Copy, Debug)]
102pub struct XLOPER12MRef {
103    /// Pointer to the externally allocated multi-reference table.
104    ///
105    /// Its validity, allocation origin, and cleanup protocol are determined by
106    /// the enclosing `XLOPER12` tag and Excel callback contract.
107    pub lpmref: LPXLMREF12,
108    /// Excel sheet identifier for the referenced areas.
109    pub idSheet: IDSHEET,
110}
111
112/// Rectangular mixed-value array member of `XLOPER12`.
113#[repr(C)]
114#[derive(Clone, Copy, Debug)]
115pub struct XLOPER12Array {
116    /// Pointer to the first raw `XLOPER12` array element.
117    ///
118    /// The pointer must be interpreted only with a valid `xltypeMulti` tag and
119    /// a proven `rows * columns` extent.
120    pub lparray: LPXLOPER12,
121    /// Number of array rows.
122    pub rows: RW,
123    /// Number of array columns.
124    pub columns: COL,
125}
126
127/// Variant storage within the `xltypeFlow` member.
128#[repr(C)]
129#[derive(Clone, Copy)]
130pub union XLOPER12FlowValue {
131    /// Flow-control nesting level.
132    pub level: i32,
133    /// Toolbar-control identifier.
134    pub tbctrl: i32,
135    /// Sheet identifier for the applicable flow operation.
136    pub idSheet: IDSHEET,
137}
138
139/// Flow-control member of `XLOPER12`.
140#[repr(C)]
141#[derive(Clone, Copy)]
142pub struct XLOPER12Flow {
143    /// Tagged flow-control payload.
144    pub valflow: XLOPER12FlowValue,
145    /// Row associated with the flow operation.
146    pub rw: RW,
147    /// Column associated with the flow operation.
148    pub col: COL,
149    /// SDK flow-control discriminator.
150    pub xlflow: BYTE,
151}
152
153/// Pointer-or-handle storage within the `xltypeBigData` member.
154#[repr(C)]
155#[derive(Clone, Copy)]
156pub union XLOPER12BigDataHandle {
157    /// Input buffer passed to Excel.
158    pub lpbData: *mut BYTE,
159    /// Handle returned by Excel.
160    pub hdata: HANDLE,
161}
162
163/// Binary-data member of `XLOPER12`.
164#[repr(C)]
165#[derive(Clone, Copy)]
166pub struct XLOPER12BigData {
167    /// Pointer-or-handle payload selected by the enclosing operation.
168    pub h: XLOPER12BigDataHandle,
169    /// Windows `long` is 32-bit on the supported MSVC target.
170    pub cbData: i32,
171}
172
173/// Complete value union from the SDK's `XLOPER12` definition.
174#[repr(C)]
175#[derive(Clone, Copy)]
176pub union XLOPER12Value {
177    /// IEEE-754 numeric payload for `xltypeNum`.
178    pub num: f64,
179    /// Pointer to an Excel UTF-16 string representation.
180    ///
181    /// Its prefix/terminator convention and lifetime are selected by the
182    /// enclosing `xltype` and callback contract.
183    pub str: *mut XCHAR,
184    /// Excel Boolean payload for `xltypeBool`.
185    pub xbool: BOOL,
186    /// Excel error code payload for `xltypeErr`.
187    pub err: i32,
188    /// Excel integer payload for `xltypeInt`.
189    pub w: i32,
190    /// Inline single-reference payload for `xltypeSRef`.
191    pub sref: XLOPER12SRef,
192    /// External multi-reference payload for `xltypeRef`.
193    pub mref: XLOPER12MRef,
194    /// Mixed-value array payload for `xltypeMulti`.
195    pub array: XLOPER12Array,
196    /// Flow-control payload for `xltypeFlow`.
197    pub flow: XLOPER12Flow,
198    /// Big-data payload for `xltypeBigData`.
199    pub bigdata: XLOPER12BigData,
200}
201
202/// Excel 12's universal raw value container.
203#[repr(C)]
204#[derive(Clone, Copy)]
205pub struct XLOPER12 {
206    /// Untagged payload union; read only the member selected by [`Self::xltype`].
207    pub val: XLOPER12Value,
208    /// Excel type tag plus protocol ownership bits.
209    ///
210    /// This field does not itself transfer ownership. Its low type bits select
211    /// the valid union member; ownership bits must be interpreted under the
212    /// documented Excel callback or return protocol.
213    pub xltype: u32,
214}
215
216#[cfg(test)]
217mod tests {
218    use core::mem::{align_of, offset_of, size_of};
219
220    use super::*;
221
222    #[test]
223    fn fixed_width_primitives_match_the_sdk() {
224        assert_eq!(size_of::<BOOL>(), 4);
225        assert_eq!(size_of::<XCHAR>(), 2);
226        assert_eq!(size_of::<RW>(), 4);
227        assert_eq!(size_of::<COL>(), 4);
228        assert_eq!(size_of::<IDSHEET>(), size_of::<usize>());
229    }
230
231    #[test]
232    fn flexible_array_headers_preserve_one_c_element() {
233        assert_eq!(offset_of!(XLMREF12, reftbl), 4);
234        assert_eq!(size_of::<XLMREF12>(), 20);
235        assert_eq!(offset_of!(FP12, array), 8);
236        assert_eq!(size_of::<FP12>(), 16);
237    }
238
239    #[cfg(all(target_os = "windows", target_arch = "x86_64"))]
240    #[test]
241    fn xloper12_has_windows_x64_sdk_layout() {
242        assert_eq!(size_of::<XLOPER12Value>(), 24);
243        assert_eq!(align_of::<XLOPER12Value>(), 8);
244        assert_eq!(offset_of!(XLOPER12, val), 0);
245        assert_eq!(offset_of!(XLOPER12, xltype), 24);
246        assert_eq!(size_of::<XLOPER12>(), 32);
247        assert_eq!(align_of::<XLOPER12>(), 8);
248    }
249}