Show TOC

OpenScan SDK Concepts, Usage and GuidanceLocate this document in the navigation structure

The OpenScan SDK provides the interface to support third-party scanning devices for Agentry applications running on supported Android, iOS, WPF, and Windows Mobile devices.

This capability is supported through multi-channel input support. Multi-channel input support refers to the ability for Agentry Client to receive data from external and third-party sources, such as bar code scanners, RFID readers, magnetic stripe readers, and camera-based scanners. Each of these data sources is defined as an alternate input channel.

Agentry Core receives input from alternate input channels at any time. Input from a channel can be triggered via a button within the application (called soft-triggering). It can also be triggered by an external hardware event, as the user swiping a credit card, or pressing an external on-device scanning button (called hard-triggering). Regardless of the triggering method, Agentry core receives data that is routed to a detail screen control, which then handles the data.

Core is separated from device hardware, and device management, and simply supplies the data interface.

Alternate Input Data

Input data is the main touch point between Core and the input hardware. The hardware device packages data into a form that Core can digest, and then delivers the package to Core.

The incoming data is packaged in a Core-defined AlternateInputChannelData class. The base implementation of this class provides information about the type of media scanned, and a string representation of that data.


A hard-triggered input device is any input device that can provide data to Core at any time, without the Agentry application needing to do something to enable or activate the input device first. Examples include a magnetic stripe reader that would trigger whenever the user swipes a card, or a Bluetooth bar code scanner that has its own button for activating it.

When such a device is triggered:
  1. The platform's input channel implementation packages the input data into an AlternateInputChannelData object, and then provides the input data back to Core asynchronously via a method in the UI Manager. The UI Manager takes ownership of the data (for example, is responsible for deleting it).
  2. The UI manager then passes the data on to the currently open screen set. The UI manager retains ownership of the data, since the screen set needs to be able to freely pass it to child screens, controls, and screen sets embedded in those controls, without needing to attend to passing ownership between parent and child screen sets.
  3. The screen set, in turn, passes the data to the currently active screen.
  4. The screen then passes the data on to any controls that can handle alternate input data until one of the controls successfully processes the data. The first control to get a shot at the data is the control that currently has the "alternate input focus" (known as "scan focus" in the Win32 client). This is a separate concept from the "input focus" that controls have relative to the keyboard. If that control rejects the data, then the next eligible control in the focus order gets a shot at it; this repeats until a control accepts the data.

The controls handle the data via a method that has a similar nature to the existing AgentryControl::processInput method (such as AgentryControl::processAlternateInput). That method vets and accepts the data, converts it into a form appropriate for the control, sets the control's value (likely by calling processInput), and returns a value indicating whether the data was accepted, and whether the control retains scan focus. (In general, only tile controls should retain alternate input focus after handling data, if they have another embedded control that can handle alternate input data.) The processAlternateInput method is defined by a new interface that is implemented by controls that can handle alternate input; this interface define any other methods needed to get at related settings from the editor and any other needed information.

The value returned by the control regarding how it handle the input data is parsed by the control's parent screen, which uses it to manage which control gets the alternate input focus next. In addition, the screen returns a similar value back to the screen set that called it, as that screen set may need to return the value to an enclosing tile control, which would in turn return it to its own parent screen, and so on until it gets back to the UI Manager. The UI Manager itself simply destroys the data object once the topmost screen set returns, without regard to the return value from that screen set.


A soft-triggered input device only provides data to Agentry when Agentry requests it. For example, a camera-based barcode scanner, which is only activated when the user clicks a button on the screen.

To activate such a device, the widgets of alternate-input-enabled controls must present the user with some sort of button to trigger the device. Such widgets must consult with platform-specific alternate input channels to determine whether a button is necessary and what it should look like.

When the button is clicked, the widget must call back to its control to inform it that alternate input has started. The control then informs its parent screen to set the alternate input focus to itself. If that parent screen is part of a tile, then the parent screen must inform its owning tile control, so that the tile control can also take scan focus for its own parent screen. This way, when the alternate input data arrives to the screen set, it will be properly routed to the control that originally triggered it.

The widget then does whatever platform-specific operation is necessary to acquire the input data. Once the data is available, it should be routed through the UI Manager in the same manner as described in Hard-triggering.

Once a widget has triggered an alternate input device, Core may need to cancel it. For example, in case of a change of input focus or scan focus (perhaps resulting from another control-initiated alternate input); or activation of a different screen in the screen set; and so forth. Some clients could resolve the situation themselves on the UI side, but not all can. In several cases, it may be easier to put the detection at a locus point in Core rather than having every button in the UI check such things. When such an event occurs, Core calls a method on the UI Manager, which informs the platform that it should shut down any active soft- triggered scans. In addition, Core triggers a call to the IControlObserver::update method of the control that has the scan focus, in case it needs to refresh its state (for example, it may have disabled its scan button while the scan was active, and must re-enable it).