Using Callbacks

Some API methods use a callback to notify the script of a change in the state of the devices. This section describe their signatures and how they work.

Working with Callbacks

Starting with v0.7.0, there are 3 ways to handle callbacks in your scripts. You can change this mode using the setMode() method. Prior to this version only the CBM_DIRECT mode was used.

-- Convenience variable
local CONST = passerelle;

-- This is the default mode
passerelle.setMode(CONST.CBM_DIRECT);

-- Declare a callback
function pageChanged(model, index, page, activate)
    -- Do something here
end

-- Register the callback for the first FIP
passerelle.registerPageCallback("SFIP", 1, pageChanged);

Callback Modes

Value	Constant	Description
1	CBM_DIRECT	default mode, direct call to the callback from a different thread
2	CBM_EVENT	event-based call using poll()
3	CBM_FSUIPC	FSUIPC specific call, still need a call to poll()

Changing Mode

You have now the choice to use a synchronous handling of callbacks. For this, just change the mode to CB_EVENT. This mode can also be used with FSUIPC if you are not using event.offset().

-- Use synchranous handling
passerelle.setMode(CONST.CBM_EVENT);

while true do
    -- Execute callbacks if any
    passerelle.poll();

    -- Do something in your main loop

    -- Wait a bit to save CPU usage
    passerelle.sleep(50);
end

FSUIPC Specific Handling

In FSUIPC, you can register for an event on a specific address using event.offset(). In this case the code is still very simple.

passerelle.setMode(CONST.CBM_FSUIPC);

-- Keep the callback registration here

-- Handling of offset events
function offsetHandler(offset, value)
    if (offset == 0x736D) then
        passerelle.poll();
    end
end

-- Register the handler
event.offset("0x736D", "UB", offsetHandler);

Callback Signatures

function PageCallback(model, index, page, activate)

Called for every page change event. There is no down/up notification, only a key-presses notification. This function will be called with activate to false if a page were previously active and a second time with activate to true for the page to be activated unless the activated page is the FIP demo page.

Parameter	Type	Description
model	char(4)	model code
index	integer(1..n)	index of the device of type model
page	integer	numerical value to identify the page
activate	boolean	has the page been activated

---

function SoftButtonCallback(model, index, state)

Called for every button event. There is a notification for every down and up state change.

Parameter	Type	Description
model	char(4)	model code
index	integer(1..n)	index of the device of type model
state	integer	bits mask representing the buttons state

---

function DeviceChangeCallback(model, index, added)

Called when a supported device is added or removed from the computer.

Parameter	Type	Description
model	char(4)	model code
index	integer(1..n)	index of the device of type model
added	boolean	true is a device is added