// 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 #import @protocol GNCPeripheralManagerDelegate; NS_ASSUME_NONNULL_BEGIN /** Protocol which helps create a fake of a @c CBPeripheralManager to inject for testing. */ @protocol GNCPeripheralManager /** Shadow property of a @c CBPeripheralManagerDelegate. */ @property(weak, nonatomic, nullable) id peripheralDelegate; @property(nonatomic, assign, readonly) CBManagerState state; @property(nonatomic, assign, readonly) BOOL isAdvertising; /** * Publishes a service and any of its associated characteristics and characteristic descriptors to * the local GATT database. * * When you add a service to the database, the peripheral manager calls the * @c gnc_peripheralManager:didAddService:error: method of its delegate object. If the service * contains any included services, you must first publish them. * * @param service The service you want to publish. */ - (void)addService:(CBMutableService *)service; /** * Removes a specified published service from the local GATT database. * * Because apps on the local peripheral device share the GATT database, more than one instance of a * service may exist in the database. As a result, this method removes only the instance of the * service that your app added to the database (using the @c addService: method). If any other * services contains this service, you must first remove them. * * @param service The service you want to remove. */ - (void)removeService:(CBMutableService *)service; /** * Removes all published services from the local GATT database. * * Use this when you want to remove all services you’ve previously published, for example, if your * app has a toggle button to expose GATT services. * * Because apps on the local peripheral device share the GATT database, this method removes only the * services that you added using the @c addService: method. This call doesn’t remove any services * published by other apps on the local peripheral device. */ - (void)removeAllServices; /** * Advertises peripheral manager data. * * When you start advertising peripheral data, the peripheral manager calls the * @c gnc_peripheralManagerDidStartAdvertising:error: method of its delegate object. * * Core Bluetooth advertises data on a “best effort” basis, due to limited space and because there * may be multiple apps advertising simultaneously. While in the foreground, your app can use up to * 28 bytes of space in the initial advertisement data for any combination of the supported * advertising data keys. If no this space remains, there’s an additional 10 bytes of space in the * scan response, usable only for the local name (represented by the value of the * @c CBAdvertisementDataLocalNameKey key). Note that these sizes don’t include the 2 bytes of * header information required for each new data type. * * Any service UUIDs contained in the value of the @c CBAdvertisementDataServiceUUIDsKey key that * don’t fit in the allotted space go to a special “overflow” area. These services are discoverable * only by an iOS device explicitly scanning for them. * * While your app is in the background, the local name isn’t advertised and all service UUIDs are in * the overflow area. * * For details about the format of advertising and response data, see the Bluetooth 4.0 * specification, Volume 3, Part C, Section 11. * * @param advertisementData An optional dictionary containing the data you want to advertise. The * peripheral manager only supports two keys: * @c CBAdvertisementDataLocalNameKey and * @c CBAdvertisementDataServiceUUIDsKey. */ - (void)startAdvertising:(nullable NSDictionary *)advertisementData; /** * Responds to a read or write request from a connected central. * * When the peripheral manager receives a request from a connected central to read or write a * characteristic’s value, it calls the @c gnc_peripheralManager:didReceiveReadRequest: or * @c gnc_peripheralManager:didReceiveWriteRequests: method of its delegate object. To respond to * the corresponding read or write request, you call this method whenever you recevie one of these * delegate method callbacks. * * @param request The read or write request received from the connected central. For more * information about read and write requests, see @c CBATTRequest. * @param result The result of attempting to fulfill the request. */ - (void)respondToRequest:(CBATTRequest *)request withResult:(CBATTError)result; /** * Stops advertising peripheral manager data. * * Call this method when you no longer want to advertise peripheral manager data. */ - (void)stopAdvertising; /** * Publishes an L2CAP channel with optional encryption. * * @param encryptionRequired A boolean value indicating whether encryption is required for the L2CAP channel. */ - (void)publishL2CAPChannelWithEncryption:(BOOL)encryptionRequired; /** * Unpublishes an L2CAP channel. * * @param PSM The @c PSM (Protocol/Service Multiplexer) value assigned to the published channel. */ - (void)unpublishL2CAPChannel:(CBL2CAPPSM)PSM; @end /** * Protocol which helps the @c GNCPeripheralManager wrap a @c CBPeripheralManagerDelegate for * testing. */ @protocol GNCPeripheralManagerDelegate /** * Tells the delegate the peripheral manager’s state updated. * * You implement this required method to ensure that Bluetooth low energy is available to use on the * local peripheral device. * * Issue commands to the peripheral manager only when the peripheral manager is in the powered-on * state, as indicated by the @c CBPeripheralManagerStatePoweredOn constant. A state with a value * lower than @c CBPeripheralManagerStatePoweredOn implies that advertising has stopped and that any * connected centrals have been disconnected. If the state moves below * @c CBPeripheralManagerStatePoweredOff, advertising has stopped you must explicitly restart it. In * addition, the powered off state clears the local database; in this case you must explicitly * re-add all services. For a complete list and discussion of the possible values representing the * state of the peripheral manager, see the @c CBPeripheralManagerState enumeration in * @c CBPeripheralManager. * * @param peripheral The peripheral manager whose state has changed. */ - (void)gnc_peripheralManagerDidUpdateState:(id)peripheral; /** * Tells the delegate the peripheral manager started advertising the local peripheral device’s data. * * Called when your app calls the @c startAdvertising: method to advertise the local peripheral * device’s data. If successful, the @c error parameter is @c nil. If a problem prevents advertising * the data, the @c error parameter returns the cause of the failure. * * @param peripheral The peripheral manager that is starting advertising. * @param error The reason the call failed, or @c nil if no error occurred. */ @optional - (void)gnc_peripheralManagerDidStartAdvertising:(id)peripheral error:(nullable NSError *)error; /** * Tells the delegate the peripheral manager published a service to the local GATT database. * * Called when your app calls the @c addService: method to publish a service to the local * peripheral’s GATT database. If the service published successfully to the local database, the * @c error parameter is @c nil. If unsuccessful, the @c error parameter provides the cause of the * failure. * * @param peripheral The peripheral manager adding the service. * @param service The service added to the local GATT database. * @param error The reason the call failed, or @c nil if no error occurred. */ @optional - (void)gnc_peripheralManager:(id)peripheral didAddService:(CBService *)service error:(nullable NSError *)error; /** * Tells the delegate that a local peripheral received an Attribute Protocol (ATT) read request for * a characteristic with a dynamic value. * * When you receive this callback, call the @c respondToRequest:withResult: method of the * @c GNCPeripheralManager class exactly once to respond to the read request. * * @param peripheral The peripheral manager that received the request. * @param request A @c CBATTRequest object that represents a request to read a characteristic’s * value. */ @optional - (void)gnc_peripheralManager:(id)peripheral didReceiveReadRequest:(CBATTRequest *)request; /** * Called when an L2CAP channel has been published by the peripheral. * * @param peripheral The peripheral that published the L2CAP channel. * @param PSM The @c PSM (Protocol/Service Multiplexer) value assigned to the published channel. * @param error An error object indicating why the channel failed to publish, or @c nil if * successful. */ @optional - (void)gnc_peripheralManager:(id)peripheral didPublishL2CAPChannel:(CBL2CAPPSM)PSM error:(nullable NSError *)error; /** * Called when an L2CAP channel has been unpublished by the peripheral. * * @param peripheral The peripheral that unpublished the L2CAP channel. * @param PSM The @c PSM (Protocol/Service Multiplexer) value assigned to the unpublished channel. * @param error An error object indicating why the channel failed to unpublish, or @c nil if * successful. */ @optional - (void)gnc_peripheralManager:(id)peripheral didUnpublishL2CAPChannel:(CBL2CAPPSM)PSM error:(NSError *)error; /** * Called when an L2CAP channel has been opened by the peripheral. * * @param peripheral The peripheral that opened the L2CAP channel. * @param channel The opened L2CAP channel, or nil if an error occurred. * @param error An error object indicating why the channel failed to * open, or @c nil if successful. */ @optional - (void)gnc_peripheralManager:(id)peripheral didOpenL2CAPChannel:(nullable CBL2CAPChannel *)channel error:(nullable NSError *)error; @end @interface CBPeripheralManager () @end NS_ASSUME_NONNULL_END