Capture Helper for Objective C

class SKTCaptureHelper : public NSObject
#include <SktCaptureHelper.h>

CaptureHelper is the main entry point for the Capture API.

CaptureHelper should be instantiated by calling the static member: sharedInstance, which returns a reference to the unique instance of CaptureHelper.

Public Functions

void setDispatchQueue:(__weak dispatch_queue_t queue)

set the dispatch queue used by Capture when invoking delegates and completion handlers

If Capture Helper dispatch queue is set to the main queue then UI controls can be updated directly from the Capture Helper delegates and completion handlers.

__weak dispatch_queue_t getDispatchQueue()

retrieve the dispatch queue used by Capture when invoking delegates and completion handlers

bool pushDelegate:(id< SKTCaptureHelperDelegate > delegate)

push a delegate in the delegates stack. The last delegate being pushed is the one receiving the notification.

If the delegate on top of the stack is the same as the delegate it will added like if it was a different delegate.

returns true if the delegate has been added, false otherwise.

bool popDelegate:(id< SKTCaptureHelperDelegate > delegate)

pop a delegate from the delegates stack. The last delegate being pushed is the first one to be pop out the stack if it matches the delegate passed in argument.

If it does not match with delegate provided in argument then nothing happen.

returns true if the delegate has been removed, false otherwise.

void openWithAppInfo:completionHandler:(SKTAppInfo * appInfo, void(^)(SKTResult result) block)

Open Capture for this app by providing the App information.

The app must be registered on Socket Mobile developer portal in order to get a AppKey matching to the application.

Parameters
  • appInfo: contains the app information with the AppKey to validate the access to this API.

  • block: called upon completion of opening capture with the result code

void closeWithCompletionHandler:(void(^)(SKTResult result) block)

Close capture when the application needs to free some resources.

Parameters
  • block: called upon completion of closing capture with the result code

NSArray *getDevicesList()

Return the actual list of connected devices. This is mostly useful when displaying somewhere the devices that are actually connected to the host.

Return

the list of devices

void getVersionWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureVersion *version) block)

retrieve the Capture version

Parameters
  • block: called upon completion of getting the Capture version with the result and the version as argument.

void getConfirmationModeWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureDataConfirmation confirmationMode) block)

retrieve the confirmation mode used to configure how the decoded data are confirmed.

Parameters
  • block: called upon completion of getting the confirmation mode with the result and the confirmation mode as argument.

void setConfirmationMode:completionHandler:(SKTCaptureDataConfirmation confirmationMode, void(^)(SKTResult result) block)

set the confirmation mode to define how the decoded data should be confirmed.

Parameters
  • confirmationMode: contains the confirmation mode to set Capture with

  • block: called upon completion of setting the confirmation mode with the result of setting the confirmation mode.

void getSoftScanStatusWithConfirmationHandler:(void(^)(SKTResult result, SKTCaptureSoftScan status) block)

retrieve the SoftScan (Scanning using the host camera) status. The status could be “not supported”, “supported”, “disabled” and “enabled”.

Parameters
  • block: called upon completion of getting the SoftScan status with result and SoftScan status as argument.

void setSoftScanStatus:completionHandler:(SKTCaptureSoftScan status, void(^)(SKTResult result) block)

set the SoftScan (Scanning using the host camera) status. The status could be “not supported”, “supported”, “disabled” and “enabled”.

Parameters
  • status: contains the new SoftScan status.

  • block: called upon completion of setting the SoftScan status with the result as argument.

void getProperty:completionHandler:(SKTCaptureProperty * property, void(^)(SKTResult result, SKTCaptureProperty *property) block)
void setProperty:completionHandler:(SKTCaptureProperty * property, void(^)(SKTResult result, SKTCaptureProperty *property) block)

Public Static Functions

instancetype sharedInstance()

instantiate a capture helper for the entire app

Return

a unique capture helper instance

Protected Attributes

NSDictionary *_extensionProperties

_extensionProperties can be used for Category SKTCaptureHelper class to store some properties.

protocol
#include <SktCaptureHelper.h>

Capture Helper delegates

Asynchronous event and unsolicited events are regrouped here and these delegates would be called at any point of time.

Public Functions

void didReceiveError:withMessage:(SKTResult error, NSString * message)

called when a error needs to be reported to the application

Parameters
  • error: contains the error code

  • message: contains an optional message, can be null

void didNotifyArrivalForDevice:withResult:(SKTCaptureHelperDevice * device, SKTResult result)

called when a device has connected to the host

Parameters
  • device: identifies the device that has just connected

  • result: contains an error if something went wrong during the device connection

void didNotifyRemovalForDevice:withResult:(SKTCaptureHelperDevice * device, SKTResult result)

called when a device has disconnected from the host

Parameters
  • device: identifies the device that has just disconnected

  • result: contains an error if something went wrong during the device disconnection

void didReceiveDecodedData:fromDevice:withResult:(SKTCaptureDecodedData * decodedData, SKTCaptureHelperDevice * device, SKTResult result)

called when decoded data are received from a device

Parameters
  • decodedData: contains the decoded data

  • device: identifies the device from which the decoded data comes from

  • result: contains an error if something wrong happen while getting the decoded data or if the SoftScan trigger operation has been cancelled

void didChangePowerState:forDevice:(SKTCapturePowerState powerState, SKTCaptureHelperDevice * device)

called when the device power state has changed and if the device notifications has been configured to notify the application for such event.

Parameters
  • powerState: contains the new power state

  • device: identifies the device for which the power state has changed

void didChangeButtonsState:forDevice:(SKTCaptureButtonsState buttonsState, SKTCaptureHelperDevice * device)

called when the device buttons state has changed and if the device notifications has been configured to notify the application for such event.

Parameters
  • buttonsState: contains the actual button state of the device

  • device: identifies the device for which the button state has changed

void didChangeBatteryLevel:forDevice:withResult:(NSInteger batteryPercentage, SKTCaptureHelperDevice * device, SKTResult result)

called when the device battery level has changed and if the device notifications has been configured to notify the application for such event.

Parameters
  • batteryPercentage: contains the new battery level in percentage

  • device: identifies the device for which the battery level has changed

void listenerDidStart()

called when the listener thread in Capture has started.

void didTerminateWithResult:(SKTResult result)

called when a Capture is terminating. The result could give an indication regarding the reason of why such event is sent especially when unsolicitated.

This event indicates the last event an application can receive from Capture. It then then safe to close and free the resources used for Capture.

Parameters
  • result: contains an eventual error code

void didNotifyArrivalForDeviceManager:withResult:(SKTCaptureHelperDeviceManager * deviceManager, SKTResult result)

called when a device manager is available to the host

Parameters
  • deviceManager: identifies the device manager that is just available

  • result: contains an error if something went wrong during the device connection

void didNotifyRemovalForDeviceManager:withResult:(SKTCaptureHelperDeviceManager * deviceManager, SKTResult result)

called when a device manager is unavailable to the host

Parameters
  • deviceManager: identifies the device manage that is just unavailable

  • result: contains an error if something went wrong during the device disconnection

void didDiscoverDevice:fromDeviceManager:(NSString * device, SKTCaptureHelperDeviceManager * deviceManager)

called when a device has been discovered by the DeviceManager

This feature works only for BLE devices such as Socket D600

Parameters
  • device: contains the device discovered indentification

  • deviceManager: from which the device discovery has started

void didDiscoveryEndWithResult:fromDeviceManager:(SKTResult result, SKTCaptureHelperDeviceManager * deviceManager)

called with a device discovery has ended.

This feature works only when used with a BLE DeviceManager

Parameters
  • result: contains the result of the discovery

  • deviceManager: from which the device discovery has started

class SKTCaptureHelperDevice : public NSObject
#include <SktCaptureHelper.h>

CaptureHelperDevice regroups the APIs that are related to the device and its configuration.

There is no need to create a CaptureHelperDevice, as it is created when CaptureHelper notifies a Device Arrival. A reference of a CaptureHelperDevice is kept in a devices list in CaptureHelper.

The main entry point of the Capture SDK is CaptureHelper. To use CaptureHelper, open it with the method openWithAppInfo.

CaptureHelper shares its instance across the application and it is accessible by using the static method [SKTCaptureHelper sharedInstance] It is best to setup the delegates before opening CaptureHelper to make sure to not miss any asynchronous event.

Subclassed by SKTCaptureHelperDeviceManager

Public Functions

instancetype initWithDeviceInfo:(SKTCaptureDeviceInfo * deviceInfo)

initialize the device with the device information coming from Device Arrival notification

void setDispatchQueue:(__weak dispatch_queue_t queue)

set the dispatch queue used by Capture when invoking delegates and completion handlers

If Capture Helper dispatch queue is set to the main queue then UI controls can be updated directly from the Capture Helper delegates and completion handlers.

__weak dispatch_queue_t getDispatchQueue()

retrieve the dispatch queue used by Capture when invoking delegates and completion handlers

void getFriendlyNameWithCompletionHandler:(void(^)(SKTResult result, NSString *name) block)

retrieve the device friendly name

Parameters
  • block: receiving the response with the result and the friendly name of the device if the result is successful

void setFriendlyName:completionHandler:(NSString * name, void(^)(SKTResult result) block)

set the device friendly name. The device friendly name has a limit of 32 UTF8 characters including the null terminated character, an error is generated if the friendly name is too long.

Parameters
  • name: friendly name to set the device with

  • block: receiving the result of setting the new friendly name

void getBluetoothAddressWithCompletionHandler:(void(^)(SKTResult result, NSArray *address) block)

get the device Bluetooth address

Parameters
  • block: receiving the result of getting the device Bluetooth Address if the result is successful

void getTypeWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureDeviceType deviceType ) block)

get the device Type

Parameters
  • block: receiving the result and the device Type if the result is successful

void getFirmwareVersionWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureVersion *version) block)

get the device Firmware version

Parameters
  • block: receiving the result and the device Firmware version if the result is successful

void getBatteryLevelWithCompletionHandler:(void(^)(SKTResult result, NSInteger levelInPercentage) block)

get the device battery level

NOTE: to avoid pulling the battery level, some devices support a battery level change notification.

Parameters
  • block: receiving the result and the device battery level if the result is successful

void getPowerStateWithCompletionHandler:(void(^)(SKTResult result, SKTCapturePowerState powerState) block)

get the device power state

NOTE: to avoid pulling the power state, some devices support a power state change notification.

Parameters
  • block: receiving the result and the device power state if the result is successful

void getButtonsStateWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureButtonsState buttonsState) block)

get the device buttons state

NOTE: some devices support buttons state change notifications

Parameters
  • block: receiving the result and the device buttons state if the result is successful

void getStandConfigWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureStandConfig config) block)

get the device stand configuration

Parameters
  • block: receiving the result and the device stand configuration if the result is successful

void setStandConfig:completionHandler:(SKTCaptureStandConfig config, void(^)(SKTResult result) block)

set the device stand configuration

Parameters
  • config: stand configuration to set the device with

  • block: receiving the result of changing the device stand configuration

void getDecodeActionWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureLocalDecodeAction decodeAction) block)

get the device decode action

Parameters
  • block: receiving the result and the device decode action if the result is successful

void setDecodeAction:completionHandler:(SKTCaptureLocalDecodeAction decodeAction, void(^)(SKTResult result) block)

set the device decode action

Parameters
  • decodeAction: decode action to set the device with

  • block: receiving the result of changing the device decode action

void getDataAcknowledgmentWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureDeviceDataAcknowledgment dataAcknowledgment) block)

get the device local data acknowledgment

Parameters
  • block: receiving the result and the device local acknowledgment if the result is successful

void setDataAcknowledgment:completionHandler:(SKTCaptureDeviceDataAcknowledgment dataAcknowledgment, void(^)(SKTResult result) block)

set the device local data acknowledgment

Parameters
  • dataAcknowledgment: set how the device acknwoledges data locally on the device

  • block: receiving the result of changing the device stand configuration

void getPostambleWithCompletionHandler:(void(^)(SKTResult result, NSString *postamble) block)

get the device postamble

Parameters
  • block: receiving the result and the device postamble if the result is successful

void setPostamble:completionHandler:(NSString * postamble, void(^)(SKTResult result) block)

set the device postamble

Parameters
  • postamble: postamble to set the device with

  • block: receiving the result of changing the device postamble

void getDataSourceInfo:completionHandler:(SKTCaptureDataSourceID dataSourceId, void(^)(SKTResult result, SKTCaptureDataSource *dataSource) block)

get the device data source information

Parameters
  • dataSourceId: contains the data source ID for which the information would be retrieved

  • block: receiving the result and the device data source information if the result is successful

void setDataSourceInfo:completionHandler:(SKTCaptureDataSource * dataSource, void(^)(SKTResult result) block)

set the device data source

Parameters
  • dataSource: dataSource to enable or disable

  • block: receiving the result of changing the device data source

void setTrigger:completionHandler:(SKTCaptureTrigger trigger, void(^)(SKTResult result) block)

set the device trigger

this operation can programmatically starts a device read operation, or it can disable the device trigger button until it gets re-enable again by using this function too.

Parameters
  • trigger: contains the command to apply

  • block: receiving the result of setting the trigger

void setDataConfirmationWithLed:withBeep:withRumble:completionHandler:(SKTCaptureDataConfirmationLed led, SKTCaptureDataConfirmationBeep beep, SKTCaptureDataConfirmationRumble rumble, void(^)(SKTResult result) block)

set the decoded data confirmation

This function is required to acknowledge the decoded data that has been received when the data confirmation mode has been set to SKTCaptureDataConfirmationModeApp

This function could also be called at any point of time if something needs to be reported to the user. By example making the scanner beep or vibrate to get the user to look at a screen.

NOTE: Good AND Bad settings can not be used together.

Parameters
  • led: contains the led to light (None, Green, Red)

  • beep: contains the beep to perform (None, Good, Bad)

  • rumble: contains the rumble to perform (None, Good, Bad)

  • block: receiving the result of setting the decoded data confirmation

void setNotifications:completionHandler:(SKTCaptureNotifications notifications, void(^)(SKTResult result) block)

set the device notifications

Parameters
  • notifications: select the notifications to receive

  • block: receiving the result of setting the notifications

void getNotificationsWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureNotifications notifications) block)

get the device notifications selection

Parameters
  • block: receiving the result and the device notifications setting if the result is successful

void getDeviceSpecificCommand:completionHandler:(NSData * command, void(^)(SKTResult result, NSData *commandResult) block)

send a specific command to the device

These commands are specific to a device, therefore the device should first be identified before sending such commands otherwise an unpredicable result could happen if they are sent to a different device.

Parameters
  • command: an array of bytes that holds the specific command to send to the device

  • block: receiving the result and the device specific command response if the result is successful

void setOverlayView:completionHandler:(NSDictionary * overlay, void(^)(SKTResult result) block)

set the device overlay view

Parameters
  • overlay: overlay settings

  • block: receiving the result of setting the overlay view

void setDataFormat:completionHandler:(SKTCaptureDataFormat dataFormat, void(^)(SKTResult result) block)

Set a data format to the device

Examples: ID-Only, TagType-and-ID, Data-Only, TagType-and-Data NOTE: Only tagType-and-ID , TagType-and-Data formats are accepted. The other two will purposely return an error

void getDataFormatWithCompletionHandler:(void(^)(SKTResult result, SKTCaptureDataFormat dataFormat) block)

Get current data format from the device

void getProperty:completionHandler:(SKTCaptureProperty * property, void(^)(SKTResult result, SKTCaptureProperty *property) block)
void setProperty:completionHandler:(SKTCaptureProperty * property, void(^)(SKTResult result, SKTCaptureProperty *property) block)

Property

property SKTCaptureHelperDevice::friendlyName

device friendly name

property SKTCaptureHelperDevice::deviceType

device type as a SKT Capture device type numeric value

property SKTCaptureHelperDevice::guid

device GUID (for the same device the GUID changes at each connection)

property SKTCaptureHelperDevice::batteryLevel

device battery level expressed as a percentage: 84%

Protected Attributes

NSDictionary *_extensionProperties

_extensionProperties can be used by the Category class of SKTCaptureHelperDevice to store some properties

class SKTCaptureHelperDeviceManager : public SKTCaptureHelperDevice
#include <SktCaptureHelper.h>

DeviceManager manages the BLE devices, and provides an API to start the discovery of BLE devices (only looking for Socket Mobile D600). It also handles the favorites. Setting a particular D600 as favorite will make the DeviceManager try to connect to it automatically.

Public Functions

void startDiscoveryWithTimeout:completionHandler:(NSInteger timeInSeconds, void(^)(SKTResult result) block)

start a discovery of devices manages by this manager (BLE)

The discovery starts immediately and this method returns also immediately with the result in the block function.

If there are some devices around a

Parameters
  • timeInSeconds: contains the number of seconds the discovery should last

  • block: receiving the result of starting the discovery

void setFavoriteDevices:completionHandler:(NSString * favorites, void(^)(SKTResult result) block)

set the favorites for the auto connection. If favorites are set, the DeviceManager tries to discover BLE device (only looking for Socket D600 device) and try to connect to the one matching to the favorite information

Parameters
  • favorites: contains the D600 peripheral identifier (UUID) semi-colon separated in case there are more than one device to connect to

  • block: called when the favorites has been set with the result as argument

void getFavoriteDevicesWithCompletionHandler:(void(^)(SKTResult result, NSString *favorites) block)

retrieve the list of favorites devices. the favorites is a string of semi-colon separated peripheral UUID identifier.

Parameters
  • block: called when getting the favorites has completed with the result and the actual favorites string as argument.

void getDeviceUniqueIdentifierFromDeviceGuid:completionHandler:(NSString * deviceGuid, void(^)(SKTResult result, NSString *deviceUniqueIdentifier) block)

retrieve the device unique identifier from the device GUID. The unique identifier can be use to add it into the favorites list.

Parameters
  • deviceGuid: contains the device GUID to identify the device to get the unique identifier from

  • block: called when getting the device unique identifier has completed with the result and the unique identifier as argument.

file SktCaptureHelper.h
#include <Foundation/Foundation.h>#include “SKTCapture.h”

Date

4/25/17.

Copyright

© 2017 Socket Mobile, Inc.

dir /home/jenkins/engineering/engineering/workspace/nning__captureconsole-ios_master/CaptureHelperObjectiveC