🤝 Callback Mechanics: Bridging uCalc and Native Code

Callbacks are the primary mechanism for creating a bridge between the dynamic uCalc scripting environment and your high-performance, native host application code (C#, C++, VB.NET). A callback allows an expression to call a function in your compiled code, pass it arguments, and receive a value back.

This is essential for:

• Implementing complex logic that is too cumbersome for an expression string.
• Integrating with existing application code.
• Accessing system resources like files, databases, or UI elements.

1. The Callback Object

When you define a function with a callback using DefineFunction or DefineOperator, your native function doesn't receive arguments directly. Instead, it receives a single, special object: the Callback object (often referred to as cb in examples). This object is the sole interface for communicating with the engine.

Inside your callback, you use the cb object to:

1. Get Arguments: Retrieve the values passed from the expression.
2. Return a Value: Send a result back to the expression.
3. Access Context: Get a handle to the parent uCalc instance or the Item that triggered the call.

2. Retrieving Arguments & Returning Values

Retrieving Arguments

The Callback object provides a family of type-safe methods for retrieving arguments.

• Arg(): The generic default, gets the nth argument as a double.
• ArgStr(): Gets the nth argument as a string.
• ArgInt32(): Gets the nth argument as a 32-bit integer.
• ArgBool(): Gets the nth argument as a boolean.

⚠️ Important: Argument indexing is 1-based, not 0-based. The first argument is at index 1, the second at index 2, and so on.

Returning a Value

You do not use your language's standard return keyword to send a value back to uCalc. You must use the Return... methods on the Callback object.

• Return(): Returns a double.
• ReturnStr(): Returns a string.

3. Language-Specific Calling Conventions

How you declare a callback function in your native code depends on the language and platform.

C# and VB.NET

In .NET, a callback is a delegate. The uCalc library provides a DELEGATE_CALLBACK type. You simply create a method with the correct signature and pass its address.

public void MyCallback(uCalc.Callback cb) { /* ... */ }uc.DefineFunction("f()", MyCallback);

For more details, see the C# and VB language topics.

C++

On Windows when compiling for x86 (32-bit), you must use the ucalc_call calling convention, which is an alias for __stdcall.

void ucalc_call MyCallback(uCalc::Callback &cb) { /* ... */ }

For Windows x64, or other platforms like Linux and macOS, this calling convention is not necessary and can be omitted.

void MyCallback(uCalc::Callback &cb) { /* ... */ }

For more details, see the C++ language topic.