Basics
=======

Getting the Decoded Data
------------------------
Using Capture Helper to retrieve the decoded data from a scanner is as simple as
deriving from ``SKTCaptureHelperDelegate`` protocol and
implementing the ``didReceiveDecodedData`` delegate.

.. note::

  If the UI should be updated with the decoded data received, the updating code
  should be in the main dispatch queue using the
  ``dispatch_async(dipatch_get_main_queue(),^{...});``


Here is an example of such implementation for handling the decoded data with
Capture Helper::

  #import "ViewController.h"
  #import "SktCaptureHelper.h"

  @interface ViewController () <SKTCaptureHelperDelegate>
  @property (weak, nonatomic) IBOutlet UILabel *statusLabel;
  @property (weak, nonatomic) IBOutlet UITextView *decodedDataTextView;
  @property (weak, nonatomic) IBOutlet UIButton *clearButton;

  @end

  @implementation ViewController

  - (void)viewDidLoad {
      [super viewDidLoad];
      // Do any additional setup after loading the view, typically from a nib.
      _decodedDataTextView.text = @"";
      _decodedDataTextView.layer.borderWidth = 2;
      _decodedDataTextView.layer.cornerRadius = 10;

      _clearButton.layer.cornerRadius = 10;
      _clearButton.layer.borderWidth = 2;
      _clearButton.backgroundColor = UIColor.whiteColor;
      _clearButton.layer.borderColor = UIColor.blueColor.CGColor;

      [SKTCaptureHelper.sharedInstance pushDelegate:self];
      [SKTCaptureHelper.sharedInstance openWithCompletionHandler:^(SKTResult result) {
          NSLog(@"Opening Capture Helper returned: %ld", (long)result);
      }];
  }

  @end




And the decoded data handler might look like this::

  /**
   * called when decoded data are received from a device
   *
   * @param decodedData contains the decoded data
   * @param device identifies the device from which the decoded data comes from
   * @param result contains an error if something wrong happen while getting the decoded data
   * or if the SoftScan trigger operation has been cancelled
   */
  -(void)didReceiveDecodedData:(SKTCaptureDecodedData*) decodedData fromDevice:(SKTCaptureHelperDevice*) device withResult:(SKTResult) result{
      NSLog(@"receive decoded data: %@", [decodedData stringFromDecodedData]);
      dispatch_async(dispatch_get_main_queue(), ^{
          self.decodedDataTextView.text = [self.decodedDataTextView.text stringByAppendingString: [decodedData stringFromDecodedData]];
          self.decodedDataTextView.text = [self.decodedDataTextView.text stringByAppendingString: @"\n"];
      });

  }


.. note::
  Here the UI can be updated because it is in block that runs in the context of
  the main queue, using ``dispatch_async(dispatch_get_main_queue(), ^{....});``
  code.


Device Arrival
--------------
The Device arrival is fired when a scanner is connected to the host.

This event can be useful for several things such as:

* confirming to the user the scanner is present and ready
* switching to a view that is ready to receive the decoded data
* checking the scanner configuration before setting its configuration

Here is an example of a Device Arrival handler::

  -(void)didNotifyArrivalForDevice:(SKTCaptureHelperDevice*) device withResult:(SKTResult) result{
      NSLog(@"Receive device arrival for %@", device.friendlyName);
      dispatch_async(dispatch_get_main_queue(), ^{
          _statusLabel.text = device.friendlyName;
      });
  }

.. note::
  Here the UI can be updated because it is in block that runs in the context of
  the main queue, using ``dispatch_async(dispatch_get_main_queue(), ^{....});``
  code.

This assumes the View class has been derived from ``CaptureHelperDelegate``::

  #import "ViewController.h"
  #import "SktCaptureHelper.h"

  @interface ViewController () <SKTCaptureHelperDelegate>
  @property (weak, nonatomic) IBOutlet UILabel *statusLabel;

  @end

Contactless Reader/Writer (D600) Auto Discovery And Connect
-----------------------------------------------------------
Please see the section
:ref:`Starting Contactless Reader/Writer Auto Discovery Mode<contactlessreaderwriterautodiscoveryconnnectobjclabel>`
to get more details about this mode.

Get the Error
-------------
It is a good idea to be notified when an unexpected error occurs. One possible
scenario where this could happen is when the user scans too many barcodes before
the application has time to consume them.

Here is an example of the error event handler to the error and the message in a
the traces, which might be not enough in real application::

  /**
   * called when a error needs to be reported to the application
   *
   * @param error contains the error code
   * @param message contains an optional message, can be null
   */
  -(void)didReceiveError:(SKTResult) error withMessage:(NSString*) message{
      NSLog(@"Receive error %d from Capture: %@", error, message);
  }

This delegate is defined by the ``CaptureHelperDelegate`` protocol from which
the class should derive.

Getting a Device Property such as Battery Level
-----------------------------------------------
Capture Helper helps to retrieve information about a particular scanner or to
configure a scanner through a Capture Helper Device object that is received in
the Device Arrival event and in the DecodedData event or other events involving
a scanner.

The Capture Helper Device object is also received in argument of the Device
Removal event but since the device is disconnected from the host, only limited
operations can be done with this Capture Helper Device instance.

Here is an example of getting the device's battery level::

    // ask for the device Battery Level
    [device getBatteryLevelWithCompletionHandler:^(SKTResult result, NSInteger levelInPercentage) {
        [self displayBatteryLevel: levelInPercentage];
    }];

    ...

    #pragma mark - Utility methods

    -(void)displayBatteryLevel:(NSInteger)batteryLevelInPercentage {
        dispatch_async(dispatch_get_main_queue(), ^{
            _statusLabel.text = [NSString stringWithFormat:@"Battery: %ld%%", (long)batteryLevelInPercentage];
        });
    }

With ``device`` being defined as a ``CaptureHelperDevice`` object.

Please refer to the other topics for more information about configuring the
device or retrieving the device properties.