Deprecation warning

Please note that this is outdated documentation for an older release of the Scandit Barcode Scanner SDK.

We encourage you to migrate to 6.x and take advantage of our latest / advanced features and improved performance.

You'll find the updated documentation at: Data Capture SDK Documentation for iOS

Using the Scandit Scan Case in your app

This guide show how to scan barcodes with the Scandit scan case using the SBSScanCase API.

Using the SBSScanCase API is relatively easy: all you need to do is to create an SBSScanCase object and implement the SBSScanCaseDelegate protocol.

Creating an instance of SBSScanCase

In order to create an instance of SBSScanCase, you first need to set the app key (if you haven't already), create a SBSScanCaseSettings, and enable the symbologies you need. At this point you can create a SBSScanCase.

[SBSLicense setAppKey:ScanditBarcodeScannerAppKey];
SBSScanCaseSettings *settings = [[SBSScanCaseSettings alloc] init];
[settings setSymbology:SBSSymbologyUPC12 enabled:YES];
self.scanCase = [SBSScanCase acquireWithSettings:settings delegate:self];

Scanning with SBSScanCase is driven by it's state property. SBSScanCase initially starts in SBSScanCaseStateStandby and can be set to one of the following three states:

  • SBSScanCaseStateOff: camera is off, torch is off.
  • SBSScanCaseStateStandby: camera is on but with throttled frame-rate, scanner is off, torch is off.
  • SBSScanCaseStateActive: camera is on, scanner is on, torch is on.

In order to start scanning, you just need to change the state to SBSScanCaseStateActive:

self.scanCase.state = SBSScanCaseStateActive;

Implementing the SBSScanCaseDelegate protocol

SBSScanCaseDelegate consists of three methods. Please note that all these methods are called from a private queue, so you are responsible to switch to the main thread if needed. Let's check them one by one.

The first method is called when SBSScanCase finished the initialization process and it's ready to be used.

- (void)didInitializeScanCase:(SBSScanCase *)scanCase {
// SBSScanCase is ready, and the state is SBSScanCaseStateStandby

Whenever a new code is scanned the following method is called. If you want to keep scanning new codes, return SBSScanCaseStateActive, if you want to temporary pause the scanner return SBSScanCaseStateStandby. You can also return SBSScanCaseStateOff if you don't plan to scan new codes relatively soon.

Please note that changing from SBSScanCaseStateOff to SBSScanCaseStateActive takes more time than switching from SBSScanCaseStateStandby to SBSScanCaseStateActive.

- (SBSScanCaseState)scanCase:(SBSScanCase *)scanCase
didScan:(SBSScanCaseSession *)session {
dispatch_async(dispatch_get_main_queue(), ^(void) {
// switch to the main thread if you need to (like for interacting with UIKit)

Whenever the state of SBSScanCase changes the following method is called. There are multiple reasons for which the state can be changed:

  • SBSScanCaseStateChangeReasonManual: the state has been changed programmatically by changing the SBSScanCase::state property or by returning a different state from the scanCase:didScan: (SBSScanCaseDelegate-p) delegate method.
  • SBSScanCaseStateChangeReasonTimeout: the state has been changed because of a timeout (check the timeout section).
  • SBSScanCaseStateChangeReasonVolumeButton: the state has been changed by the volume button (check the volume button section).
- (void)scanCase:(SBSScanCase *)scanCase
// state: the new state of the SBSScanCase
// reason: the reason for the state change

Enabling the volume button to start scanning

It is possible to use the volume button to scan. Keeping the volume button pressed will keep the scan case in SBSScanCaseStateActive state, while releasing the button will change the state to SBSScanCaseStateStandby. To enable this feature, all you need to do is:

self.scanCase.volumeButtonToScanEnabled = YES;

You know when the state changes, because of the volume button, in scanCase:didChangeState:reason: (SBSScanCaseDelegate-p), the reason will be SBSScanCaseStateChangeReasonVolumeButton.

Using timeouts to switch state

It is possible to switch from one state to another one automatically after a specific timeout. This could be useful, for instance, to switch the scanner off after a long time of inactivity in order to save power.

The following code changes the state from SBSScanCaseStateStandby to SBSScanCaseStateOff after approximately 60 seconds.

[self.scanCase setTimeout:60 tolerance:5 fromState:SBSScanCaseStateStandby toState:SBSScanCaseStateOff];

You know when the state changes because of a timeout in scanCase:didChangeState:reason: (SBSScanCaseDelegate-p), the reason will be SBSScanCaseStateChangeReasonTimeout.

You could, for instance, display an alert to inform the user that the scanned has been switched off:

- (void)scanCase:(SBSScanCase *)scanCase
switch (state) {
dispatch_async(dispatch_get_main_queue(), ^(void) {
NSString *alertTitle = @"State changed to SBSScanCaseStateOff to save power";
UIAlertController *alertController = [UIAlertController alertControllerWithTitle:alertTitle
UIAlertAction *okAction = [UIAlertAction actionWithTitle:@"OK"
[alertController addAction:okAction];
[self presentViewController:alertController animated:YES completion:nil];