4.8. The ScannerProvider API

The Scanner Provider is the entrypoint of an SDK. Its purpose is to check if the SDK is able to interact with a device, and handle the Scanner creation.

In most cases, users will not need to interact with a provider directly, but adding compatibility to more devices will require adding a new provider.

This page regroups all provider-related interfaces and helper classes.

4.8.1. The ScannerProvider interface

The core methods of a provider common between, all types of devices.

getScanner(Context ctx, ProviderCallback cb, ScannerSearchOptions options) → void

This method will make the provider check whether it is compatible with any scanning device while matching requirements imposed by the search options. If it is able to connect to a device, the provider will use the callback to notify its availability and return a Scanner instance.

Parameters:

  • ctx (Context) – The application context.

  • cb (ProviderCallback) – The ProviderCallback used to notify the Scanner Service whether this SDK is available (as in, is able to connect to any scanning device), and the current status of Scanner instance creation.

  • options (ScannerSearchOptions) – The search options the provider may use to further refine its compatibility checks.

getKey() → String
Returns:

The unique key which identifies this provider.

See also

Check the documentation of the ProviderCallback interface for details on how the provider will communicate its status with the Scanner Service.

4.8.2. The IntentScannerProvider abstract class

In order to facilitate discovery for integrated devices, the IntentScannerProvider abstract class provides an implementation of the ScannerProvider.getScanner() to check various Android mechanisms and figure out if the current device is compatible with the SDK.

A provider for an integrated scanner should extend this class and override the following methods:

createNewScanner(Context ctx, ScannerSearchOptions options) → Scanner

This method is called by ScannerProvider.getScanner() to create the Scanner instance.

Parameters:

  • ctx (Context) – The application context.

  • options (ScannerSearchOptions) – The search options the provider used to confirm compatibility.

Returns:

The Scanner instance of the implementation used by this SDK.

configureProvider() → void

This method is called by ScannerProvider.getScanner() to set what should be tested to know if the device is compatible with an SDK. There are four different mechanisms that can be tested, if multiple of them are set, all must be valid for the SDK to be considered compatible.

The following variables may be set in configureProvider() to influence the compatibility check:

String intentToTest = null

If set, the provider will be compatible only if the given Android Intent has a matching listener on the device.

List<String> specificDevices = new ArrayList<>(0)

If set, the provider will be compatible only if the value of android.os.Build.MODEL exactly matches one of the values contained in the list.

String appPackageToTest = null

If set, the provider will be compatible only if the given application package name is found and enabled on the device.

String serviceToTest = null

If set, the provider will be compatible only if the given service package name can be started by the library.

4.8.3. The case of Bluetooth, and the BtSppScannerProvider interface

Because bluetooth devices require extra steps to detect, the provider discovery for such devices is a bit different. A single SerialBtScannerProvider class implements the ScannerProvider interface to handle system-level bluetooth configuration, and the actual providers for SDKs targetting bluetooth devices need to implement the BtSppScannerProvider interface.

A bluetooth provider must implement the following methods:

getKey() → String
Returns:

The unique key which identifies this provider.

canManageDevice(BluetoothScanner device, ManagementCallback callback) → void

Tests whether a scanner is compatible with the provider. Must complete in under 50ms.

Parameters:

  • device (BluetoothScanner) – The “raw” bluetooth device for which to test SDK compatibility

  • callback (ManagementCallback) – The callback used to notify whether the compatibility check was successful or not.

getInputHandler() → ScannerDataParser
Returns:

The parser which should be used to parse bluetooth messages from compatible devices.

See also

Check the documentation of the ManagementCallback interace for details on how the bluetooth provider will communicate its status with the Scanner Service.