/**
* Subtype of {@link Peripheral} that represents a Bluetooth Peripheral profile
* @interface BluetoothPeripheral
* @property {boolean} requiresPairing - Indicates if a peripheral model requires a Bluetooth pairing before it can be used.
* @property {string} instructions - Text to be presented to the user when BLE.read is called.
* @property {string} readingInstructions - Text to be presented to the user when the BLE.ON_READY_TO_READ event is received.
* @property {string} pairingInstructions - Text to be presented to the user when BLE.pair is called.
*/
/**
* Callback response from BLE.getPassiveReadPeripheralIDs
* @callback PassiveReadPeripheralIDsCallback
* @property {number[]} peripheralIDs - Array of peripheral IDs that are currently being passively read.
*/
/**
* Callback for Passive Bluetooth callbacks
* @callback PassiveBluetoothCallback
* @property event - Name of the event being returned
* @property payload - payload of the event
* @property {number} payload.peripheralID - Id of the peripheral the callback event is related to
* @property {Record[]} payload.records - Records returned by the passive bluetooth manager
* @property {string} payload.error - error returned from the passive read failure
*
*/
/**
* Passive Bluetooth Options
* @interface PassiveBluetoothOptions
* @property {Number[]} peripheralIDs - Array of peripheral IDs to scan for
* @property {NotificationOptions} notificationOptions
*/
document.addEventListener("deviceready", () => {
exports.BLE.setBluetoothPassiveListener();
});
/**
* @exports BLE
* Represents Validic Bluetooth functionality
*/
exports.BLE = {
/**
* Bluetooth event names that can be subscribed to for using window.addEventListener to receive bluetooth events.
* @enum {string}
*/
EventName: {
ON_PAIR_SUCCESS: "validicOnPairSuccessful",
ON_PAIR_FAIL: "validicOnPairFailed",
ON_PAIR_START: "validicOnPairingStarted",
ON_READ_SUCCESS: "validicOnReadSuccessful",
ON_READ_FAIL: "validicOnReadFailed",
ON_READY_TO_READ: "validicOnReadyToRead",
ON_READ_CANCEL: "validicOnReadCancelled",
ON_PASSIVE_DID_READ: "validicOnBluetoothPassiveDidRead",
ON_PASSIVE_DID_FAIL: "validicOnBluetoothPassiveDidFail",
ON_PASSIVE_DID_CANCEL: "validicOnBluetoothPassiveDidCancel",
ON_PASSIVE_READY_TO_READ: "validicOnBluetoothPassiveIsReadyToRead",
},
/**
* Gets an array of supported peripherals for use with bluetooth.
* @param {PeripheralsCallback} success - Callback function containing an array of peripheral devices.
*/
getSupportedPeripherals: function (success) {
cordova.exec(
success,
null,
"ValidicMobileBLE",
"BLE_getSupportedPeripherals",
[]
);
},
/**
* Gets an array of supported peripherals matching a peripheral type.
* @param {number} type - Type of peripheral to return list for. See ValidicMobile.PeripheralType.
* @param {PeripheralsOfTypeCallback} success - Callback function containing an array of all peripherals matching given type.
* @param {FailCallback} error callback function indicating invalid type.
* */
getPeripheralsOfType: function (type, success, error) {
cordova.exec(
success,
error,
"ValidicMobileBLE",
"BLE_getPeripheralsOfType",
[type]
);
},
/**
* Gets information about a peripheral with a given id.
* @param {number} id - Id of peripheral to retrieve information about.
* @param {PeripheralCallback} success - Callback function including peripheral information.
* @param {FailCallback} error - Callback function indicating an error trying to receive info about peripheral or if id is not an integer.
*/
getPeripheral: function (id, success, error) {
cordova.exec(success, error, "ValidicMobileBLE", "BLE_getPeripheral", [
id,
]);
},
/**
* Pairs a bluetooth device.
* @param id {number} id of the device to pair with.
* @param {EventCallback} success - All bluetooth pair success methods flow through this callback.
* @param {EventCallback} fail - All bluetooth pair failure/cancel methods flow through this callback.
*/
pair: function (id, success, fail) {
var successful = function (obj) {
if (success != null && success != "undefined") {
success(obj);
}
if (obj.hasOwnProperty("event")) {
cordova.fireWindowEvent(obj.event, obj.payload);
}
};
var error = function (obj) {
if (fail != null && fail != "undefined") {
fail(obj);
}
if (obj.hasOwnProperty("event")) {
cordova.fireWindowEvent(obj.event, obj.payload);
}
};
cordova.exec(successful, error, "ValidicMobileBLE", "BLE_pair", [id]);
},
/**
* Reads from a paired bluetooth device.
* @param {number} id - Peripheral Id to read from.
* @param {EventCallback} success - All bluetooth read success callbacks flow through this callback.
* @param {EventCallback} fail - All bluetooth read fail and cancel callbacks flow through this callback.
*/
read: function (id, success, fail) {
var successful = function (obj) {
if (success != null && success != "undefined") {
success(obj);
}
if (obj.hasOwnProperty("event")) {
cordova.fireWindowEvent(obj.event, obj.payload);
}
};
var error = function (obj) {
if (fail != null && fail != "undefined") {
fail(obj);
}
if (obj.hasOwnProperty("event")) {
cordova.fireWindowEvent(obj.event, obj.payload);
}
};
cordova.exec(successful, error, "ValidicMobileBLE", "BLE_read", [id]);
},
/**
* Cancels a bluetooth reading or pairing. Listeners should receive an onReadCancel event after cancelling
* reading or pairing.
*/
cancel: function () {
cordova.exec(null, null, "ValidicMobileBLE", "BLE_cancel", []);
},
/**
* Indicates a reading is being taken from a paired peripheral.
* @param {InProgressCallback} success - Callback containing a boolean value containing true when a reading is being taken, otherwise false.
*/
isInProgress: function (success) {
cordova.exec(success, null, "ValidicMobileBLE", "BLE_inProgress", []);
},
/**
* Set list of Bluetooth peripheral IDs which should be passively read. Once set, the library will listen for and read from
* these devices when the app is in foreground or background.
* To stop passive Bluetooth read, pass an empty array of IDs or null.
* @param {PassiveBluetoothOptions} params - Options for passive Bluetooth Scanning. For
* @param {Object} success -
* @param {FailCallback} error - Invalid parameters were given.
*/
setPassiveReadPeripheralIDs: function (params, success, error) {
cordova.exec(
success,
error,
"ValidicMobileBLE",
"BLE_setPassiveReadPeripheralIDs",
[params]
);
},
/**
* @param {PassiveReadPeripheralIDsCallback} success - Response containing array of currently subscribed sample types.
*/
getPassiveReadPeripheralIDs: function (success) {
cordova.exec(
success,
null,
"ValidicMobileBLE",
"BLE_getPassiveReadPeripheralIDs",
[]
);
},
/**
* Registers listener for passive bluetooth read events. It is recommended to use event listeners instead.
* @param {PassiveBluetoothCallback} success - Function invoked when passive bluetooth records have been processed and submitted
* or when peripheral becomes ready to read.
* @param {PassiveBluetoothCallback} fail - Function invoked when passive bluetooth read is attempted but fails.
*/
setBluetoothPassiveListener: function (success, fail) {
var successful = function (obj) {
if (success != null && success != "undefined") {
success(obj);
}
if (obj.hasOwnProperty("event")) {
cordova.fireWindowEvent(obj.event, obj.payload);
}
};
var error = function (obj) {
if (fail != null && fail != "undefined") {
fail(obj);
}
if (obj.hasOwnProperty("event")) {
cordova.fireWindowEvent(obj.event, obj.payload);
}
};
cordova.exec(
successful,
error,
"ValidicMobileBLE",
"BLE_setBluetoothPassiveListener",
[]
);
},
};