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}