Power Management
================

It is important to know the power state of the scanner as it is for the
host to make sure it does not need to be recharged during the time the scanner
is needed and the operation has a chance to change batteries or charge the scanner.

The application can check the battery level of the scanner using Capture SDK.
Additionally, many Socket Mobile scanners support battery level change notification.

Following are some examples on how to configure the scanner for these features.


Reading the Battery Level
^^^^^^^^^^^^^^^^^^^^^^^^^
Here is example code showing how to request the scanner battery level
information::

  SKTCaptureHelperDevice* device = _lastDeviceConnected;
  [device getBatteryLevelWithCompletionHandler:^(SKTResult result, NSInteger levelInPercentage) {
      NSLog(@"Getting the device battery level returns %ld", result);
      if(result == SKTCaptureE_NOERROR){
          [self displayBatteryLevel:levelInPercentage forDevice:device];
      }
  }];

  #pragma mark - Utility methods
  -(void)displayBatteryLevel:(NSInteger)batteryLevelInPercentage forDevice:(SKTCaptureHelperDevice*)device{
      dispatch_async(dispatch_get_main_queue(), ^{
          _statusLabel.text = [NSString stringWithFormat:@"%@ Battery: %ld%%",device.friendlyName, (long)batteryLevelInPercentage];
      });
  }

The ``lastDevice`` is a ``CaptureHelperDevice`` instance that has been set in the
``didNotifyArrivalForDevice`` delegate.

The utility method `displayBatteryLevel:forDevice:` makes sure the update of the
UI control is done in the main thread context by using the code:
``dispatch_async(dispatch_get_main_queue(), ^{...});``.

Set up the Battery Level Change Notification
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Setting up the scanner to make it send a notification each time the battery
level changes is a 2 step process. Since this setting is persistent in the
scanner, the first time the scanner connects to the application we query the
notification setting, if the battery level change notification is not activated
then we activate it.
The initial battery level needs to be read at this time because it could take a long
time before the first battery level change notification is received.
::

  [device getNotificationsWithCompletionHandler:^(SKTResult result, SKTCaptureNotifications notifications) {
      NSLog(@"getting the device notifications settings returns %ld",(long)result);
      if (result == SKTCaptureE_NOERROR){
          if((notifications & SKTCaptureNotificationsBatteryLevelChange) !=
             SKTCaptureNotificationsBatteryLevelChange){
              NSLog(@"the battery level change is not set, do it now...");
              notifications |= SKTCaptureNotificationsBatteryLevelChange;
              [device setNotifications:notifications completionHandler:^(SKTResult result) {
                  NSLog(@"setting the notifications returns %ld", (long)result);
              }];
          }
          else {
              NSLog(@"The battery level change notification is already set!");
          }
      }
  }];

  [device getBatteryLevelWithCompletionHandler:^(SKTResult result, NSInteger levelInPercentage) {
      NSLog(@"Getting the device battery level returns %ld", result);
      if(result == SKTCaptureE_NOERROR){
          [self displayBatteryLevel:levelInPercentage forDevice:device];
      }
  }];



The ``device`` is a ``CaptureHelperDevice`` instance that has been received in the
argument of the ``didNotifyArrivalForDevice`` delegate.

Notice that we also use this ``didNotifyArrivalForDevice`` delegate to ask for the
current battery level so it can be displayed right away.

In order to receive the battery level change notifications, we need to provide a
handler for the ``didChangeBatteryLevel`` delegate::

  -(void)didChangeBatteryLevel:(NSInteger) batteryPercentage forDevice:(SKTCaptureHelperDevice*) device withResult:(SKTResult)result{
      if(result == SKTCaptureE_NOERROR){
          NSLog(@"Receive a battery level change notification: %ld%%", batteryPercentage);
          [self displayBatteryLevel:batteryPercentage forDevice:device];
      }
  }

Power State Change and other Events
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The same principle can be followed for the other events of the device, such as
the ``didChangePowerState`` delegate which notifies the application each time
the scanner is plugged into a power source, or unplugged or dropped in the
charger cradle.

Other events such as buttons state can be tracked by implementing the
``didChangeButtonsState`` delegate.