Expand description
§excel-api
Safe Rust building blocks for native 64-bit Microsoft Excel XLL add-ins.
excel-api is the high-level companion to excel-api-sys: callback inputs are
borrowed for exactly their Excel callback lifetime, owned semantic values are
pointer-free, return planning allocates stable DLL-owned XLOPER12 storage, and
typed contexts restrict Excel calls to documented callback capabilities.
§Quick start
use excel_api::prelude::*;
#[cfg(feature = "macros")]
#[excel_function(
name = "RUST.ADD", thunk = "rust_add",
arguments(left = "First addend.", right = "Second addend.")
)]
fn add(left: f64, right: f64) -> f64 { left + right }
The default macros feature re-exports excel_function and excel_command.
xlcontime-research is an experimental, doc-hidden compatibility probe; it is
not a supported autonomous wake mechanism. RTD, COM/Ribbon UI, task panes, and
autonomous notification are outside the stable core.
Async UDFs and the cooperative dispatcher are preview features: automated coverage is present, while their full Excel lifecycle/pump validation remains pending. Enqueueing dispatcher work never wakes Excel.
See the repository user guide, the minimal XLL example, and the crate Rustdoc for API-specific ownership and callback restrictions.
Supported target: 64-bit Windows Excel using the Excel 12 C API. 32-bit Excel and arbitrary background-thread Excel calls are unsupported.
Licensed under either Apache-2.0 or MIT.
§Overview
excel-api is the safe, high-level layer for native 64-bit Microsoft Excel
XLL add-ins. It builds on excel_api_sys but does not make raw ABI
ownership safe by convention: callback inputs are represented by
callback-borrowed types such as ExcelValueRef, while data that must outlive
a callback is represented by owned semantic types such as ExcelValue and
ExcelString.
Prefer the prelude for ordinary XLL authoring. The
excel_function! and
excel_command! attributes generate registration
metadata and panic-contained ABI thunks when the default macros feature is
enabled. Start with the repository’s examples/minimal-xll example and the
user guide.
§Ownership and callback lifetime
Excel owns callback arguments and may reclaim them when the callback returns;
they must never be retained. Convert a borrowed value with FromExcel when
work must outlive the callback. Return values are planned as pointer-free
ReturnPlans and materialized into DLL-owned storage through
ExcelReturn, which xlAutoFree12 later releases. Results returned by an
Excel C API call are represented by ExcelOwnedValue and are released with
xlFree according to their documented policy.
§Callback capabilities and threads
Typed contexts are capabilities, not claims about a thread: use
WorksheetContext, ThreadSafeContext, MacroContext, or
LifecycleContext only when Excel has issued the matching callback. Worker
threads must not call Excel. Async UDFs are preview: their worker bodies
own their data and publish through xlAsyncReturn only under the documented
lifecycle generation. The cooperative dispatcher is also preview: an
enqueue never wakes Excel, and work runs only when a legal callback drains it.
§Platform and features
The stable target is 64-bit Windows Excel using the Excel 12 C API. 32-bit
Excel and arbitrary background-thread Excel calls are unsupported. The
default macros feature re-exports the authoring attributes. The
xlcontime-research feature is experimental, doc-hidden compatibility
research and is not a supported wake mechanism. RTD, general COM, Ribbon,
custom task panes, and autonomous notification are outside this crate’s
stable 1.0 scope.
§Minimal shape
The code below is an XLL entry point shape, so it is no_run: loading and
registration require a real Excel process.
use excel_api::prelude::*;
#[cfg(feature = "macros")]
#[excel_function(
name = "RUST.ADD",
thunk = "rust_add",
category = "Rust",
description = "Adds two numbers.",
arguments(left = "First addend.", right = "Second addend.")
)]
fn add(left: f64, right: f64) -> f64 {
left + right
}Re-exports§
pub use async_udf::AsyncCancellationToken;pub use async_udf::AsyncCompletionError;pub use async_udf::AsyncExecuteError;pub use async_udf::AsyncExecutor;pub use async_udf::AsyncJob;pub use async_udf::AsyncSubmitError;pub use async_udf::ThreadPoolExecutor;pub use borrowed::DecodeError;pub use borrowed::ExcelArrayColumns;pub use borrowed::ExcelArrayElements;pub use borrowed::ExcelArrayRows;pub use borrowed::ExcelArrayView;pub use borrowed::ExcelMissing;pub use borrowed::ExcelMultiReference;pub use borrowed::ExcelNil;pub use borrowed::ExcelReference;pub use borrowed::ExcelReferenceArea;pub use borrowed::ExcelReferenceAreas;pub use borrowed::ExcelSingleReference;pub use borrowed::ExcelStr;pub use borrowed::ExcelValueRef;pub use borrowed::RawExcelValue;pub use context::LifecycleContext;pub use context::MacroContext;pub use context::ThreadSafeContext;pub use context::WorksheetContext;pub use convert::ConversionLimits;pub use convert::FromExcel;pub use convert::IntoExcel;pub use diagnostics::DiagnosticCode;pub use diagnostics::DiagnosticEvent;pub use diagnostics::DiagnosticSeverity;pub use diagnostics::DiagnosticSink;pub use diagnostics::set_user_sink;pub use dispatcher::DispatchCallbackKind;pub use dispatcher::DispatchCancelOutcome;pub use dispatcher::DispatchCompletionError;pub use dispatcher::DispatchConfig;pub use dispatcher::DispatchDiagnostics;pub use dispatcher::DispatchDrainReport;pub use dispatcher::DispatchEnqueueError;pub use dispatcher::DispatchExecutionError;pub use dispatcher::DispatchGeneration;pub use dispatcher::DispatchOperation;pub use dispatcher::DispatchRequirement;pub use dispatcher::DispatchResult;pub use dispatcher::DispatchTicket;pub use dispatcher::current_generation as current_dispatch_generation;pub use dispatcher::diagnostics as dispatch_diagnostics;pub use dispatcher::enqueue as enqueue_dispatch;pub use error::ConversionError;pub use error::ExcelError;pub use error::OwnedValueError;pub use error::ReturnError;pub use error::ReturnMaterializationError;pub use error::ThunkError;pub use error::Utf16ConversionError;pub use metadata::CountedUtf16Arg;pub use metadata::ExcelReferenceArg;pub use metadata::ExcelValueArg;pub use metadata::NullTerminatedUtf16Arg;pub use registration::AddInDescriptor;pub use registration::CommandRegistration;pub use registration::ExcelArgumentType;pub use registration::ExcelReturnType;pub use registration::FunctionFlags;pub use registration::FunctionRegistration;pub use registration::FunctionSignature;pub use registration::RegistrationError;pub use return_plan::ExcelReturnArray;pub use return_plan::ExcelReturnValue;pub use return_plan::PlannedArray;pub use return_plan::PlannedArrayElement;pub use return_plan::PlannedText;pub use return_plan::PlannedValue;pub use return_plan::ReturnLimits;pub use return_plan::ReturnOwnershipStrategy;pub use return_plan::ReturnPlan;pub use return_plan::ReturnStorageTotals;pub use return_plan::ReturnText;pub use runtime::LifecycleError;pub use runtime::LifecycleOutcome;pub use runtime::Runtime;pub use runtime::RuntimeDiagnostics;pub use runtime::RuntimePhase;pub use value::ExcelArray;pub use value::ExcelArrayColumn;pub use value::ExcelString;pub use value::ExcelValue;pub use value::OptionalValue;
Modules§
- async_
udf - Preview bounded asynchronous-UDF scheduling and cancellation primitives. Owned, bounded asynchronous UDF scheduling and completion.
- borrowed
- Callback-borrowed Excel values that cannot outlive their issuing callback. Read-only views over values supplied by Excel for one callback invocation.
- context
- Typed capability tokens for legal Excel callback contexts.
- convert
- Conversion between callback-borrowed and owned semantic values.
- diagnostics
- Bounded, panic-contained runtime diagnostics. Bounded, non-panicking diagnostics for supportability-critical paths.
- dispatcher
- Preview cooperative callback-drained dispatcher with no autonomous wake. Bounded cooperative dispatch under genuine Excel callback capabilities.
- error
- Error types returned by safe value, conversion, and return-planning APIs.
- metadata
- Owned metadata arguments used to describe registered functions and commands. Explicit argument families used by worksheet-function metadata.
- prelude
- Common imports for XLL authors.
- registration
- Manual registration descriptors and signature validation.
- return_
plan - Pointer-free planning of DLL-owned
XLOPER12return storage. Pure, deterministic planning for future Excel ABI return storage. - runtime
- Runtime initialization, registration, close, and cleanup state. Idempotent XLL lifecycle runtime.
- value
- Owned semantic Excel values with no callback-scoped pointers.
Structs§
- Excel
Call Descriptor - Verified contract metadata for one narrowly exposed Excel C API call.
- Excel
Owned Value - A callback-scoped owner for one result root written by Excel.
- Excel
Return - Opaque local owner of one stable Excel ABI return tree.
- Excel
Return Code - Exact Excel C API return code, including any documented bit flags.
- Excel
XlFree Transfer - A pre-commit XLFree transfer token.
- SdkExcel12v
Backend - Production backend that resolves and invokes Excel’s
Excel12ventry point.
Enums§
- Abort
Check Mode - Controls whether an
xlAbortpoll retains or clears a pending break. - Call
Permission - Capability required by one typed Excel C API descriptor.
- Coerce
Target - The Excel root type requested from
XL_COERCE. - Excel
Call Error - Failure of descriptor validation, typed invocation, or result handling.
- Excel
Owned Conversion Error - The result of a consuming deep copy followed by the mandatory release.
- Excel
Release Error - A failure reported while attempting the one permitted
xlFreecall. - Excel
Release Policy - Whether an Excel C API result has an outstanding
xlFreeobligation. - Result
Root - Whether Excel must supply a result root for a call.
Constants§
- XLF_
CALLER - Returns information about the caller of a worksheet function or macro.
- XLF_
REGISTER - Descriptor for lifecycle-only
xlfRegister. - XLF_
SET_ NAME - Descriptor for lifecycle-only
xlfSetName. - XLF_
UNREGISTER - Descriptor for lifecycle-only
xlfUnregister. - XL_
ABORT - Polls the Excel cancellation/break request. This is not a calculation-state query.
- XL_
COERCE - Converts a C API value to an explicitly requested Excel root type.
- XL_
EVENT_ REGISTER - Descriptor for lifecycle-only event registration.
- XL_FREE
- Descriptor for the Excel-owned-result cleanup operation
xlFree. - XL_
GET_ NAME - Descriptor for lifecycle-only
xlGetName. - XL_
SHEET_ ID - Resolves a sheet name (or the active/front sheet when omitted) to its internal ID.
- XL_
SHEET_ NM - Resolves an internal/external reference to its sheet name.
Functions§
- install_
async_ executor - Installs the executor for the next generated asynchronous-UDF open generation.
- install_
dispatcher - Installs bounds for the next cooperative-dispatcher runtime generation.
- xl_
auto_ ⚠free12 - Reusable implementation of the Excel 12 DLL-owned return cleanup callback.
Attribute Macros§
- excel_
command - Mark a Rust function for future command registration.
- excel_
function - Generate deterministic worksheet-function registration metadata and an ABI thunk.