mirror of
https://github.com/kidfromjupiter/nearby.git
synced 2026-09-16 15:36:12 -04:00
197 lines
8.9 KiB
Objective-C
197 lines
8.9 KiB
Objective-C
// Copyright 2023 Google LLC
|
||
//
|
||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||
// you may not use this file except in compliance with the License.
|
||
// You may obtain a copy of the License at
|
||
//
|
||
// https://www.apache.org/licenses/LICENSE-2.0
|
||
//
|
||
// Unless required by applicable law or agreed to in writing, software
|
||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
// See the License for the specific language governing permissions and
|
||
// limitations under the License.
|
||
|
||
#import <CoreBluetooth/CoreBluetooth.h>
|
||
#import <Foundation/Foundation.h>
|
||
|
||
@protocol GNCCentralManagerDelegate;
|
||
@protocol GNCPeripheral;
|
||
|
||
NS_ASSUME_NONNULL_BEGIN
|
||
|
||
/** Protocol which helps create a fake of a @c CBCentralManager to inject for testing. */
|
||
@protocol GNCCentralManager
|
||
|
||
/** Shadow property of a @c CBCentralManagerDelegate. */
|
||
@property(weak, nonatomic, nullable) id<GNCCentralManagerDelegate> centralDelegate;
|
||
|
||
/**
|
||
* The current state of the manager.
|
||
*
|
||
* This state is initially set to @c CBManagerStateUnknown. When the state updates, the manager
|
||
* calls its delegate’s @c gnc_centralManagerDidUpdateState: method.
|
||
*/
|
||
@property(nonatomic, assign, readonly) CBManagerState state;
|
||
|
||
/**
|
||
* Scans for peripherals that are advertising services.
|
||
*
|
||
* You can provide an array of @c CBUUID objects, representing service UUIDs, in the @c serviceUUIDs
|
||
* parameter. When you do, the central manager returns only peripherals that advertise the services
|
||
* you specify. If the @c serviceUUIDs parameter is @c nil, this method returns all discovered
|
||
* peripherals, regardless of their supported services.
|
||
*
|
||
* @note The recommended practice is to populate the @c serviceUUIDs parameter rather than leaving
|
||
* it @c nil.
|
||
*
|
||
* If the central manager is actively scanning with one set of parameters and it receives another
|
||
* set to scan, the new parameters override the previous set. When the central manager discovers a
|
||
* peripheral, it calls the @c gnc_centralManager:didDiscoverPeripheral:advertisementData:RSSI:
|
||
* method of its delegate object.
|
||
*
|
||
* Your app can scan for Bluetooth devices in the background by specifying the @c bluetooth-central
|
||
* background mode. To do this, your app must explicitly scan for one or more services by specifying
|
||
* them in the @c serviceUUIDs parameter. The CBCentralManager scan option has no effect while
|
||
* scanning in the background.
|
||
*
|
||
* @param serviceUUIDs An array of @c CBUUID objects that the app is interested in. Each @c CBUUID
|
||
* object represents the UUID of a service that a peripheral advertises.
|
||
* @param options A dictionary of options for customizing the scan.
|
||
*/
|
||
- (void)scanForPeripheralsWithServices:(nullable NSArray<CBUUID *> *)serviceUUIDs
|
||
options:(nullable NSDictionary<NSString *, id> *)options;
|
||
|
||
/**
|
||
* Establishes a local connection to a peripheral.
|
||
*
|
||
* After successfully establishing a local connection to a peripheral, the central manager object
|
||
* calls the @c gnc_centralManager:didConnectPeripheral: method of its delegate object. If the
|
||
* connection attempt fails, the central manager object calls the
|
||
* @c gnc_centralManager:didFailToConnectPeripheral:error: method of its delegate object instead.
|
||
* Attempts to connect to a peripheral don’t time out. To explicitly cancel a pending connection to
|
||
* a peripheral, call the @c cancelPeripheralConnection: method. Deallocating @c peripheral also
|
||
* implicitly calls @c cancelPeripheralConnection:.
|
||
*
|
||
* @param peripheral The peripheral to which the central is attempting to connect.
|
||
* @param options A dictionary to customize the behavior of the connection.
|
||
*/
|
||
- (void)connectPeripheral:(id<GNCPeripheral>)peripheral
|
||
options:(nullable NSDictionary<NSString *, id> *)options;
|
||
|
||
/**
|
||
* Cancels an active or pending local connection to a peripheral.
|
||
*
|
||
* This method is nonblocking, and any @c CBPeripheral class commands that are still pending to
|
||
* @c peripheral may not complete. Because other apps may still have a connection to the peripheral,
|
||
* canceling a local connection doesn’t guarantee that the underlying physical link is immediately
|
||
* disconnected. From the app’s perspective, however, the peripheral is effectively disconnected,
|
||
* and the central manager object calls the @c centralManager:didDisconnectPeripheral:error: method
|
||
* of its delegate object.
|
||
*
|
||
* @param peripheral The peripheral to which the central manager is either trying to connect or has
|
||
* already connected.
|
||
*/
|
||
- (void)cancelPeripheralConnection:(id<GNCPeripheral>)peripheral;
|
||
|
||
/** Asks the central manager to stop scanning for peripherals. */
|
||
- (void)stopScan;
|
||
|
||
@end
|
||
|
||
/**
|
||
* Protocol which helps the @c GNCCentralManager wrap a @c CBCentralManagerDelegate for
|
||
* testing.
|
||
*/
|
||
@protocol GNCCentralManagerDelegate <NSObject>
|
||
|
||
/**
|
||
* Tells the delegate the central manager’s state updated.
|
||
*
|
||
* You implement this required method to ensure that the central device supports Bluetooth low
|
||
* energy and that it’s available to use. You should issue commands to the central manager only when
|
||
* the central manager’s @c state indicates it’s powered on. A state with a value lower than
|
||
* @c CBManagerStatePoweredOn implies that scanning has stopped, which in turn disconnects any
|
||
* previously-connected peripherals. If the state moves below @c CBManagerStatePoweredOff, all
|
||
* @c CBPeripheral objects obtained from this central manager become invalid; you must retrieve or
|
||
* discover these peripherals again.
|
||
*
|
||
* @param central The central manager whose state has changed.
|
||
*/
|
||
- (void)gnc_centralManagerDidUpdateState:(id<GNCCentralManager>)central;
|
||
|
||
/**
|
||
* Tells the delegate the central manager discovered a peripheral while scanning for devices.
|
||
*
|
||
* You must retain a local copy of the peripheral if you want to perform commands on it. Use the
|
||
* RSSI data to determine the proximity of a discoverable peripheral device, and whether you want to
|
||
* connect to it automatically.
|
||
*
|
||
* @param central The central manager that provides the update.
|
||
* @param peripheral The discovered peripheral.
|
||
* @param advertisementData A dictionary containing any advertisement data.
|
||
* @param RSSI The current received signal strength indicator (RSSI) of the peripheral, in decibels.
|
||
*/
|
||
- (void)gnc_centralManager:(id<GNCCentralManager>)central
|
||
didDiscoverPeripheral:(id<GNCPeripheral>)peripheral
|
||
advertisementData:(NSDictionary<NSString *, id> *)advertisementData
|
||
RSSI:(NSNumber *)RSSI;
|
||
|
||
/**
|
||
* Tells the delegate that the central manager connected to a peripheral.
|
||
*
|
||
* The manager invokes this method when a call to @c connectPeripheral:options: succeeds. You
|
||
* typically implement this method to set the peripheral’s delegate and discover its services.
|
||
*
|
||
* @param central The central manager that provides this information.
|
||
* @param peripheral The now-connected peripheral.
|
||
*/
|
||
- (void)gnc_centralManager:(id<GNCCentralManager>)central
|
||
didConnectPeripheral:(id<GNCPeripheral>)peripheral;
|
||
|
||
/**
|
||
* Tells the delegate the central manager failed to create a connection with a peripheral.
|
||
*
|
||
* The manager invokes this method when a connection initiated with the
|
||
* @c connectPeripheral:options: method fails to complete. Because connection attempts don’t time
|
||
* out, a failed connection usually indicates a transient issue, in which case you may attempt
|
||
* connecting to the peripheral again.
|
||
*
|
||
* @param central The central manager that provides this information.
|
||
* @param peripheral The peripheral that failed to connect.
|
||
* @param error The cause of the failure, or @c nil if no error occurred.
|
||
*/
|
||
- (void)gnc_centralManager:(id<GNCCentralManager>)central
|
||
didFailToConnectPeripheral:(id<GNCPeripheral>)peripheral
|
||
error:(nullable NSError *)error;
|
||
|
||
/**
|
||
* Tells the delegate that the central manager disconnected from a peripheral.
|
||
*
|
||
* The manager invokes this method when disconnecting a peripheral previously connected with the
|
||
* @c connectPeripheral:options: method. The error parameter contains the reason for the
|
||
* disconnection, unless the disconnect resulted from a call to @c cancelPeripheralConnection:.
|
||
*
|
||
* All services, characteristics, and characteristic descriptors of a peripheral become invalidated
|
||
* after it disconnects.
|
||
*
|
||
* @param central The central manager that provides this information.
|
||
* @param peripheral The now-disconnected peripheral.
|
||
* @param error The cause of the failure, or @c nil if no error occurred.
|
||
*/
|
||
- (void)gnc_centralManager:(id<GNCCentralManager>)central
|
||
didDisconnectPeripheral:(id<GNCPeripheral>)peripheral
|
||
error:(nullable NSError *)error;
|
||
|
||
@end
|
||
|
||
/**
|
||
* Declares that @c CBCentralManager implements the @c GNCCentralManager protocol.
|
||
*
|
||
* This allows us to directly use a @c CBCentralManager as a @c GNCCentralManager.
|
||
*/
|
||
@interface CBCentralManager () <GNCCentralManager>
|
||
@end
|
||
|
||
NS_ASSUME_NONNULL_END
|