Skip to main content

Crate excel_api

Crate excel_api 

Source
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 XLOPER12 return 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§

ExcelCallDescriptor
Verified contract metadata for one narrowly exposed Excel C API call.
ExcelOwnedValue
A callback-scoped owner for one result root written by Excel.
ExcelReturn
Opaque local owner of one stable Excel ABI return tree.
ExcelReturnCode
Exact Excel C API return code, including any documented bit flags.
ExcelXlFreeTransfer
A pre-commit XLFree transfer token.
SdkExcel12vBackend
Production backend that resolves and invokes Excel’s Excel12v entry point.

Enums§

AbortCheckMode
Controls whether an xlAbort poll retains or clears a pending break.
CallPermission
Capability required by one typed Excel C API descriptor.
CoerceTarget
The Excel root type requested from XL_COERCE.
ExcelCallError
Failure of descriptor validation, typed invocation, or result handling.
ExcelOwnedConversionError
The result of a consuming deep copy followed by the mandatory release.
ExcelReleaseError
A failure reported while attempting the one permitted xlFree call.
ExcelReleasePolicy
Whether an Excel C API result has an outstanding xlFree obligation.
ResultRoot
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.