Capture Helper for Objective C

class SKTCaptureHelper
#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.

Inherits from NSObject

Public Functions

virtual 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.

virtual __weak dispatch_queue_t getDispatchQueue()

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

virtual 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.

virtual 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.

virtual 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

virtual 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

virtual 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

virtual 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.

virtual 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.

virtual 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.

virtual 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.

virtual 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.

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

Public Static Functions

virtual 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.

Inherits from <SKTCaptureHelperDeviceNSObject>

Public Functions

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual void listenerDidStart()

called when the listener thread in Capture has started.

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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
#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.

Inherits from NSObject

Subclassed by SKTCaptureHelperDeviceManager

Public Functions

virtual instancetype initWithDeviceInfo:(SKTCaptureDeviceInfo * deviceInfo)

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

virtual 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.

virtual __weak dispatch_queue_t getDispatchQueue()

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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

virtual 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

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

Get current data format from the device

virtual void getProperty:completionHandler:(SKTCaptureProperty * property, void(^)(SKTResult result, SKTCaptureProperty *property) block)
virtual 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
#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.

Inherits from SKTCaptureHelperDevice

Public Functions

virtual 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

virtual 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

virtual 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.

virtual 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