com.idevicesinc.sweetblue.utils

Class BleSetupHelper

java.lang.Object

com.idevicesinc.sweetblue.utils.BleSetupHelper

public class BleSetupHelper
extends java.lang.Object

This class is used to handle the new hairy logic for getting bluetooth low-energy scan results that is introduced with Build.VERSION_CODES.M. With Build.VERSION_CODES.M you need to have Manifest.permission.ACCESS_COARSE_LOCATION or Manifest.permission.ACCESS_FINE_LOCATION in your AndroidManifest.xml, and also enable them at runtime, AND also make sure location services are on.

See more information at https://github.com/iDevicesInc/SweetBlue/wiki/Android-BLE-Issues#android-m-issues

This class is simply a convenience that wraps various helper methods of BleManager (see the "See Also" section, which has enough links that it might give you an idea of why BleSetupHelper was written). As such you don't need to use it, but it comes in handy as a simple addition to most simple apps.

See Also:

BleManager.isLocationEnabledForScanning(), BleManager.isLocationEnabledForScanning_byManifestPermissions(), BleManager.isLocationEnabledForScanning_byRuntimePermissions(), BleManager.isLocationEnabledForScanning_byOsServices(), BleManager.turnOnLocationWithIntent_forPermissions(Activity, int), BleManager.turnOnLocationWithIntent_forOsServices(Activity, int), BleManager.turnOnWithIntent(Activity, int), BleManager.willLocationPermissionSystemDialogBeShown(Activity), https://github.com/iDevicesInc/SweetBlue/wiki/Android-BLE-Issues#android-m-issues

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BleSetupHelper.BluetoothEnablerImpl This class implements all of the enabler logic that can be overridden to alter the look or the messaging of the enabler.
static class	BleSetupHelper.DefaultString Enumerates the built in strings used by the enabler to convey information to users.
static class	BleSetupHelper.ErrorCode Enumerates the various errors that can happen.
static class	BleSetupHelper.Permission Enumerates the various permissions that we will try to enable (if needed)
static class	BleSetupHelper.PermissionInstance This class holds a permission and user defined metadata.
static class	BleSetupHelper.Result This class will be passed into your BleSetupHelper.ResultListener when the enabler finishes
static interface	BleSetupHelper.ResultListener This class holds a permission and user defined metadata.
protected static class	BleSetupHelper.State

Constructor Summary

Constructors

Constructor and Description
BleSetupHelper(BleManager manager, android.app.Activity activity) Constructor for use when you don't want a result listener.
BleSetupHelper(BleManager manager, android.app.Activity activity, BleSetupHelper.BluetoothEnablerImpl enablerImpl, BleSetupHelper.ResultListener listener) Constructor for use when you want a result listener, and to provide your own implementation of the enabler, or add on to the implementation with custom permissions.
BleSetupHelper(BleManager manager, android.app.Activity activity, BleSetupHelper.ResultListener listener) Constructor for use when you want a result listener.

Method Summary

Modifier and Type	Method and Description
void	addCustomPermission(java.lang.Object metadata) Adds a custom permission to the required permission list.
void	addRequiredPermissions() This method will populate the list of required permissions with the standard defaults.
protected void	afterPermissionRequested()
protected boolean	checkIsEnabled(BleSetupHelper.PermissionInstance pi)
protected boolean	checkIsRequired(BleSetupHelper.PermissionInstance pi)
protected void	doneRequestingCustomPermission()
protected void	errorOut(BleSetupHelper.ErrorCode ec)
protected void	errorOut(BleSetupHelper.ErrorCode ec, java.lang.String errorMessage)
protected void	finishCurrentPermission(boolean success)
protected void	handleUIResult(BleSetupHelper.PermissionInstance pi, boolean result)
protected void	postCallback(BleSetupHelper.Result r)
protected void	requestNextPermission()
protected void	requestPermission(BleSetupHelper.PermissionInstance pi)
static void	runEnabler(BleManager manager, android.app.Activity activity, BleSetupHelper.ResultListener listener) This function handles the creation and startup of the enabler using default options.
void	setImpl(BleSetupHelper.BluetoothEnablerImpl impl) This method allows you to set a custom implementation which can be used to implement custom permissions, or to customize the look or text of the dialogs and toasts shown by the enabler.
void	setResultListener(BleSetupHelper.ResultListener resultListener) This method allows you to change the BleSetupHelper.ResultListener after construction of the enabler
protected void	setState(BleSetupHelper.State newState)
protected void	showUIToEnable(BleSetupHelper.PermissionInstance pi)
void	start() This method starts the enabler.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BleSetupHelper

public BleSetupHelper(BleManager manager,
                      android.app.Activity activity)

Constructor for use when you don't want a result listener. Before the enabler will do anything, you must add some permissions via addRequiredPermissions() and/or addCustomPermission(Object), and then call start()

Parameters:

manager - - the BleManager to use. If it becomes null, the enabler will halt

activity - - the Activity to use. If it becomes null, the enabler will halt

BleSetupHelper

public BleSetupHelper(BleManager manager,
                      android.app.Activity activity,
                      BleSetupHelper.ResultListener listener)

Constructor for use when you want a result listener. Before the enabler will do anything, you must add some permissions via addRequiredPermissions() and/or addCustomPermission(Object), and then call start()

Parameters:

manager - - the BleManager to use. If it becomes null, the enabler will halt

activity - - the Activity to use. If it becomes null, the enabler will halt

listener - - the BleSetupHelper.ResultListener that will be called when the enabler finishes

BleSetupHelper

public BleSetupHelper(BleManager manager,
                      android.app.Activity activity,
                      BleSetupHelper.BluetoothEnablerImpl enablerImpl,
                      BleSetupHelper.ResultListener listener)

Constructor for use when you want a result listener, and to provide your own implementation of the enabler, or add on to the implementation with custom permissions. Before the enabler will do anything, you must add some permissions via addRequiredPermissions() and/or addCustomPermission(Object), and then call start()

Parameters:

manager - - the BleManager to use. If it becomes null, the enabler will halt

activity - - the Activity to use. If it becomes null, the enabler will halt

listener - - the BleSetupHelper.ResultListener that will be called when the enabler finishes

enablerImpl - - the BleSetupHelper.BluetoothEnablerImpl that will be used to handle the logic of getting permissions

Method Detail

runEnabler

public static void runEnabler(BleManager manager,
                              android.app.Activity activity,
                              BleSetupHelper.ResultListener listener)

This function handles the creation and startup of the enabler using default options. Assuming you don't want to customize any behavior and you just want the standard permissions requested, this is the quickest & easiest way to use the enabler.

Parameters:

manager - - the BleManager to use. If it becomes null, the enabler will halt

activity - - the Activity to use. If it becomes null, the enabler will halt

listener - - the BleSetupHelper.ResultListener to use. Can be null if you do not want a callback

setImpl

public void setImpl(BleSetupHelper.BluetoothEnablerImpl impl)

This method allows you to set a custom implementation which can be used to implement custom permissions, or to customize the look or text of the dialogs and toasts shown by the enabler.

Parameters:

impl - - the custom implementation

setResultListener

public void setResultListener(BleSetupHelper.ResultListener resultListener)

This method allows you to change the BleSetupHelper.ResultListener after construction of the enabler

Parameters:

resultListener - - the new BleSetupHelper.ResultListener

addRequiredPermissions

public void addRequiredPermissions()

This method will populate the list of required permissions with the standard defaults. You probably always want these to be enabled if you're using the enabler, unless you are only using it for custom permissions or you have a special situation where you don't need all of the standard bluetooth permissions. If you are going to call this, you must call it before start() is called. If you use the static utility method runEnabler(BleManager, Activity, ResultListener), this will be done for you.

addCustomPermission

public void addCustomPermission(java.lang.Object metadata)

Adds a custom permission to the required permission list. In order to use this, you must provide a custom BleSetupHelper.BluetoothEnablerImpl via setImpl(BluetoothEnablerImpl). If you don't, the enabler will error out when it tries to check or enable the custom permission. The metadata object you provide will be passed into all methods that pertain to the custom permission. You can use this to distinguish multiple custom permissions from eachother, or to tack on and track additional information

Parameters:

metadata - - the metadata that will accompany the custom permission

start

public void start()

This method starts the enabler. You can only call this once, and you should have set up all of the required permissions and any other customization you want ahead of time.

setState

protected void setState(BleSetupHelper.State newState)

postCallback

protected void postCallback(BleSetupHelper.Result r)

requestNextPermission

protected void requestNextPermission()

handleUIResult

protected void handleUIResult(BleSetupHelper.PermissionInstance pi,
                              boolean result)

finishCurrentPermission

protected void finishCurrentPermission(boolean success)

doneRequestingCustomPermission

protected void doneRequestingCustomPermission()

afterPermissionRequested

protected void afterPermissionRequested()

checkIsEnabled

protected boolean checkIsEnabled(BleSetupHelper.PermissionInstance pi)

checkIsRequired

protected boolean checkIsRequired(BleSetupHelper.PermissionInstance pi)

requestPermission

protected void requestPermission(BleSetupHelper.PermissionInstance pi)

errorOut

protected void errorOut(BleSetupHelper.ErrorCode ec)

errorOut

protected void errorOut(BleSetupHelper.ErrorCode ec,
                        java.lang.String errorMessage)

showUIToEnable

protected void showUIToEnable(BleSetupHelper.PermissionInstance pi)