Skip to main content

excel_api_sys/
constants.rs

1//! Raw constants from `XLCALL.H` and the Excel 12 registration ABI.
2
3// XLOPER12 type tags.
4pub const xltypeNum: u32 = 0x0001;
5pub const xltypeStr: u32 = 0x0002;
6pub const xltypeBool: u32 = 0x0004;
7pub const xltypeRef: u32 = 0x0008;
8pub const xltypeErr: u32 = 0x0010;
9pub const xltypeFlow: u32 = 0x0020;
10pub const xltypeMulti: u32 = 0x0040;
11pub const xltypeMissing: u32 = 0x0080;
12pub const xltypeNil: u32 = 0x0100;
13pub const xltypeSRef: u32 = 0x0400;
14pub const xltypeInt: u32 = 0x0800;
15pub const xlbitXLFree: u32 = 0x1000;
16pub const xlbitDLLFree: u32 = 0x4000;
17pub const xltypeBigData: u32 = xltypeStr | xltypeInt;
18
19/// Mask covering every base `XLOPER12` type bit, excluding ownership bits.
20pub const XLTYPE_MASK: u32 = 0x0FFF;
21
22// Excel error values.
23pub const xlerrNull: i32 = 0;
24pub const xlerrDiv0: i32 = 7;
25pub const xlerrValue: i32 = 15;
26pub const xlerrRef: i32 = 23;
27pub const xlerrName: i32 = 29;
28pub const xlerrNum: i32 = 36;
29pub const xlerrNA: i32 = 42;
30pub const xlerrGettingData: i32 = 43;
31
32// Flow-control values.
33pub const xlflowHalt: i32 = 1;
34pub const xlflowGoto: i32 = 2;
35pub const xlflowRestart: i32 = 8;
36pub const xlflowPause: i32 = 16;
37pub const xlflowResume: i32 = 64;
38
39// Excel4/Excel12 return codes. Multiple failure bits may be combined.
40pub const xlretSuccess: i32 = 0;
41pub const xlretAbort: i32 = 1;
42pub const xlretInvXlfn: i32 = 2;
43pub const xlretInvCount: i32 = 4;
44pub const xlretInvXloper: i32 = 8;
45pub const xlretStackOvfl: i32 = 16;
46pub const xlretFailed: i32 = 32;
47pub const xlretUncalced: i32 = 64;
48pub const xlretNotThreadSafe: i32 = 128;
49pub const xlretInvAsynchronousContext: i32 = 256;
50pub const xlretNotClusterSafe: i32 = 512;
51
52// Cluster connector entry-point return codes.
53pub const xlHpcRetSuccess: i32 = 0;
54pub const xlHpcRetSessionIdInvalid: i32 = -1;
55pub const xlHpcRetCallFailed: i32 = -2;
56
57// Event identifiers.
58pub const xleventCalculationEnded: i32 = 1;
59pub const xleventCalculationCanceled: i32 = 2;
60
61// Function-number category bits.
62pub const xlCommand: i32 = 0x8000;
63pub const xlSpecial: i32 = 0x4000;
64pub const xlIntl: i32 = 0x2000;
65pub const xlPrompt: i32 = 0x1000;
66
67// C API-only function numbers used by the foundation milestones.
68pub const xlFree: i32 = xlSpecial;
69pub const xlStack: i32 = 1 | xlSpecial;
70pub const xlCoerce: i32 = 2 | xlSpecial;
71pub const xlSet: i32 = 3 | xlSpecial;
72pub const xlSheetId: i32 = 4 | xlSpecial;
73pub const xlSheetNm: i32 = 5 | xlSpecial;
74pub const xlAbort: i32 = 6 | xlSpecial;
75pub const xlGetInst: i32 = 7 | xlSpecial;
76pub const xlGetHwnd: i32 = 8 | xlSpecial;
77pub const xlGetName: i32 = 9 | xlSpecial;
78pub const xlEnableXLMsgs: i32 = 10 | xlSpecial;
79pub const xlDisableXLMsgs: i32 = 11 | xlSpecial;
80pub const xlDefineBinaryName: i32 = 12 | xlSpecial;
81pub const xlGetBinaryName: i32 = 13 | xlSpecial;
82pub const xlAsyncReturn: i32 = 16 | xlSpecial;
83pub const xlEventRegister: i32 = 17 | xlSpecial;
84pub const xlRunningOnCluster: i32 = 18 | xlSpecial;
85pub const xlGetInstPtr: i32 = 19 | xlSpecial;
86
87// Worksheet/XLM function numbers required through manual registration.
88/// Current date/time as an Excel serial value (`XLCALL.H`: `xlfNow = 74`).
89pub const xlfNow: i32 = 74;
90pub const xlfSetName: i32 = 88;
91pub const xlfCaller: i32 = 89;
92pub const xlfRegister: i32 = 149;
93pub const xlfUnregister: i32 = 201;
94pub const xlfRegisterId: i32 = 267;
95pub const xlUDF: i32 = 255;
96
97/// Historical XLM `ON.TIME` command (`XLCALL.H`: `148 | xlCommand`).
98///
99/// This raw constant does not by itself establish a modern supported contract.
100pub const xlcOnTime: i32 = 148 | xlCommand;
101
102// Excel 12 capacity limits. Rows and columns are counts; MAX_ROW/MAX_COLUMN
103// are zero-based indices.
104pub const EXCEL12_MAX_ROWS: i32 = 1_048_576;
105pub const EXCEL12_MAX_COLUMNS: i32 = 16_384;
106pub const EXCEL12_MAX_ROW: i32 = EXCEL12_MAX_ROWS - 1;
107pub const EXCEL12_MAX_COLUMN: i32 = EXCEL12_MAX_COLUMNS - 1;
108pub const EXCEL12_MAX_STRING_CODE_UNITS: usize = 32_767;
109pub const EXCEL12_MAX_ARGUMENTS: i32 = 255;
110
111// Registration data type codes used by the Excel 12 milestones.
112pub const XLL_TYPE_BOOL: &str = "A";
113pub const XLL_TYPE_DOUBLE: &str = "B";
114pub const XLL_TYPE_XCHAR_NULL_TERMINATED: &str = "C%";
115pub const XLL_TYPE_XCHAR_COUNTED: &str = "D%";
116pub const XLL_TYPE_DOUBLE_POINTER: &str = "E";
117pub const XLL_TYPE_XCHAR_NULL_TERMINATED_IN_PLACE: &str = "F%";
118pub const XLL_TYPE_XCHAR_COUNTED_IN_PLACE: &str = "G%";
119pub const XLL_TYPE_WORD: &str = "H";
120pub const XLL_TYPE_I16: &str = "I";
121pub const XLL_TYPE_I32: &str = "J";
122pub const XLL_TYPE_FP12: &str = "K%";
123pub const XLL_TYPE_BOOL_POINTER: &str = "L";
124pub const XLL_TYPE_I16_POINTER: &str = "M";
125pub const XLL_TYPE_I32_POINTER: &str = "N";
126pub const XLL_TYPE_ARRAY12: &str = "O%";
127/// Value-only `XLOPER12`; references are dereferenced before the call.
128pub const XLL_TYPE_XLOPER12_VALUE: &str = "Q";
129/// Reference-preserving `XLOPER12`.
130pub const XLL_TYPE_XLOPER12_REFERENCE: &str = "U";
131pub const XLL_TYPE_ASYNC_HANDLE: &str = "X";
132/// Void return required for asynchronous UDF registration.
133pub const XLL_TYPE_ASYNC_VOID: &str = ">";
134
135// Legacy registration codes are exposed only to make the P/Q and R/U
136// distinction explicit. Legacy XLOPER structures and Excel4 are unsupported.
137pub const XLL_TYPE_LEGACY_XLOPER_VALUE: &str = "P";
138pub const XLL_TYPE_LEGACY_XLOPER_REFERENCE: &str = "R";
139
140pub const XLL_MODIFIER_VOLATILE: char = '!';
141pub const XLL_MODIFIER_MACRO_SHEET: char = '#';
142pub const XLL_MODIFIER_THREAD_SAFE: char = '$';
143pub const XLL_MODIFIER_CLUSTER_SAFE: char = '&';
144/// Historical void/modify-first-argument prefix; modern synchronous
145/// modify-in-place registration uses a return digit from `1` through `9`.
146pub const XLL_MODIFIER_VOID: char = '>';
147pub const XLL_MODIFY_IN_PLACE_FIRST: char = '1';
148pub const XLL_MODIFY_IN_PLACE_LAST: char = '9';
149
150// Compatibility spellings retained from the initial scaffold.
151pub const XLTYPE_NUM: u32 = xltypeNum;
152pub const XLTYPE_STR: u32 = xltypeStr;
153pub const XLTYPE_BOOL: u32 = xltypeBool;
154pub const XLTYPE_REF: u32 = xltypeRef;
155pub const XLTYPE_ERR: u32 = xltypeErr;
156pub const XLTYPE_FLOW: u32 = xltypeFlow;
157pub const XLTYPE_MULTI: u32 = xltypeMulti;
158pub const XLTYPE_MISSING: u32 = xltypeMissing;
159pub const XLTYPE_NIL: u32 = xltypeNil;
160pub const XLTYPE_SREF: u32 = xltypeSRef;
161pub const XLTYPE_INT: u32 = xltypeInt;
162pub const XLTYPE_BIG_DATA: u32 = xltypeBigData;
163pub const XLBIT_XL_FREE: u32 = xlbitXLFree;
164pub const XLBIT_DLL_FREE: u32 = xlbitDLLFree;
165pub const XLRET_SUCCESS: i32 = xlretSuccess;
166pub const XLRET_ABORT: i32 = xlretAbort;
167pub const XLRET_INV_XLFN: i32 = xlretInvXlfn;
168pub const XLRET_INV_COUNT: i32 = xlretInvCount;
169pub const XLRET_INV_XLOPER: i32 = xlretInvXloper;
170pub const XLRET_STACK_OVFL: i32 = xlretStackOvfl;
171pub const XLRET_FAILED: i32 = xlretFailed;
172pub const XLRET_UNCALCED: i32 = xlretUncalced;
173pub const XLRET_NOT_THREAD_SAFE: i32 = xlretNotThreadSafe;
174pub const XLRET_INV_ASYNC_CONTEXT: i32 = xlretInvAsynchronousContext;
175pub const XLRET_NOT_CLUSTER_SAFE: i32 = xlretNotClusterSafe;
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180
181    #[test]
182    fn type_and_ownership_bits_do_not_overlap() {
183        assert_eq!(xltypeRef, 0x0008);
184        assert_eq!(xltypeInt, 0x0800);
185        assert_eq!(xltypeBigData, xltypeStr | xltypeInt);
186        assert_eq!(xlbitXLFree & XLTYPE_MASK, 0);
187        assert_eq!(xlbitDLLFree & XLTYPE_MASK, 0);
188    }
189
190    #[test]
191    fn modern_general_registration_modes_remain_distinct() {
192        assert_eq!(XLL_TYPE_XLOPER12_VALUE, "Q");
193        assert_eq!(XLL_TYPE_XLOPER12_REFERENCE, "U");
194        assert_ne!(XLL_TYPE_XLOPER12_VALUE, XLL_TYPE_XLOPER12_REFERENCE);
195    }
196
197    #[test]
198    fn on_time_and_now_match_checked_in_xlcall_header() {
199        assert_eq!(xlfNow, 74);
200        assert_eq!(xlcOnTime, 32_916);
201        assert_eq!(xlcOnTime, 0x8094);
202    }
203
204    #[test]
205    fn excel12_limits_are_internally_consistent() {
206        assert_eq!(EXCEL12_MAX_ROW + 1, EXCEL12_MAX_ROWS);
207        assert_eq!(EXCEL12_MAX_COLUMN + 1, EXCEL12_MAX_COLUMNS);
208        assert_eq!(EXCEL12_MAX_STRING_CODE_UNITS, 32_767);
209        assert_eq!(EXCEL12_MAX_ARGUMENTS, 255);
210    }
211}