/* * @file CBPeripheral.h * @framework CoreBluetooth * * @discussion Representation of a remote peripheral. * * @copyright 2011 Apple, Inc. All rights reserved. */ #ifndef _CORE_BLUETOOTH_H_ #warning Please do not import this header file directly. Use instead. #endif #import #import #import #import NS_ASSUME_NONNULL_BEGIN /*! * @enum CBPeripheralState * * @discussion Represents the current connection state of a CBPeripheral. * */ typedef NS_ENUM(NSInteger, CBPeripheralState) { CBPeripheralStateDisconnected = 0, CBPeripheralStateConnecting, CBPeripheralStateConnected, CBPeripheralStateDisconnecting NS_AVAILABLE(10_13, 9_0), } NS_AVAILABLE(10_9, 7_0); /*! * @enum CBCharacteristicWriteType * * @discussion Specifies which type of write is to be performed on a CBCharacteristic. * */ typedef NS_ENUM(NSInteger, CBCharacteristicWriteType) { CBCharacteristicWriteWithResponse = 0, CBCharacteristicWriteWithoutResponse, }; @protocol CBPeripheralDelegate; @class CBService, CBCharacteristic, CBDescriptor, CBUUID; /*! * @class CBPeripheral * * @discussion Represents a peripheral. */ NS_CLASS_AVAILABLE(10_7, 5_0) CB_EXTERN_CLASS @interface CBPeripheral : CBPeer /*! * @property delegate * * @discussion The delegate object that will receive peripheral events. */ @property(weak, nonatomic, nullable) id delegate; /*! * @property name * * @discussion The name of the peripheral. */ @property(retain, readonly, nullable) NSString *name; /*! * @property RSSI * * @discussion The most recently read RSSI, in decibels. * * @deprecated Use {@link peripheral:didReadRSSI:error:} instead. */ @property(retain, readonly, nullable) NSNumber *RSSI NS_DEPRECATED(10_7, 10_13, 5_0, 8_0); /*! * @property state * * @discussion The current connection state of the peripheral. */ @property(readonly) CBPeripheralState state; /*! * @property services * * @discussion A list of CBService objects that have been discovered on the peripheral. */ @property(retain, readonly, nullable) NSArray *services; /*! * @property canSendWriteWithoutResponse * * @discussion YES if the remote device has space to send a write without response. If this value is NO, * the value will be set to YES after the current writes have been flushed, and * peripheralIsReadyToSendWriteWithoutResponse: will be called. */ @property(readonly) BOOL canSendWriteWithoutResponse NS_AVAILABLE(10_13, 11_0); /*! * @property ancsAuthorized * * @discussion YES if the remote device has been authorized to receive data over ANCS (Apple Notification Service Center) protocol. If this value is NO, * the value will be set to YES after a user authorization occurs and * didUpdateANCSAuthorizationForPeripheral: will be called. */ @property(readonly) BOOL ancsAuthorized NS_AVAILABLE_IOS(13_0); /*! * @method readRSSI * * @discussion While connected, retrieves the current RSSI of the link. * * @see peripheral:didReadRSSI:error: */ - (void)readRSSI; /*! * @method discoverServices: * * @param serviceUUIDs A list of CBUUID objects representing the service types to be discovered. If nil, * all services will be discovered. * * @discussion Discovers available service(s) on the peripheral. * * @see peripheral:didDiscoverServices: */ - (void)discoverServices:(nullable NSArray *)serviceUUIDs; /*! * @method discoverIncludedServices:forService: * * @param includedServiceUUIDs A list of CBUUID objects representing the included service types to be discovered. If nil, * all of services included services will be discovered, which is considerably slower and not recommended. * @param service A GATT service. * * @discussion Discovers the specified included service(s) of service. * * @see peripheral:didDiscoverIncludedServicesForService:error: */ - (void)discoverIncludedServices:(nullable NSArray *)includedServiceUUIDs forService:(CBService *)service; /*! * @method discoverCharacteristics:forService: * * @param characteristicUUIDs A list of CBUUID objects representing the characteristic types to be discovered. If nil, * all characteristics of service will be discovered. * @param service A GATT service. * * @discussion Discovers the specified characteristic(s) of service. * * @see peripheral:didDiscoverCharacteristicsForService:error: */ - (void)discoverCharacteristics:(nullable NSArray *)characteristicUUIDs forService:(CBService *)service; /*! * @method readValueForCharacteristic: * * @param characteristic A GATT characteristic. * * @discussion Reads the characteristic value for characteristic. * * @see peripheral:didUpdateValueForCharacteristic:error: */ - (void)readValueForCharacteristic:(CBCharacteristic *)characteristic; /*! * @method maximumWriteValueLengthForType: * * @discussion The maximum amount of data, in bytes, that can be sent to a characteristic in a single write type. * * @see writeValue:forCharacteristic:type: */ - (NSUInteger)maximumWriteValueLengthForType:(CBCharacteristicWriteType)type NS_AVAILABLE(10_12, 9_0); /*! * @method writeValue:forCharacteristic:type: * * @param data The value to write. * @param characteristic The characteristic whose characteristic value will be written. * @param type The type of write to be executed. * * @discussion Writes value to characteristic's characteristic value. * If the CBCharacteristicWriteWithResponse type is specified, {@link peripheral:didWriteValueForCharacteristic:error:} * is called with the result of the write request. * If the CBCharacteristicWriteWithoutResponse type is specified, and canSendWriteWithoutResponse is false, the delivery * of the data is best-effort and may not be guaranteed. * * @see peripheral:didWriteValueForCharacteristic:error: * @see peripheralIsReadyToSendWriteWithoutResponse: * @see canSendWriteWithoutResponse * @see CBCharacteristicWriteType */ - (void)writeValue:(NSData *)data forCharacteristic:(CBCharacteristic *)characteristic type:(CBCharacteristicWriteType)type; /*! * @method setNotifyValue:forCharacteristic: * * @param enabled Whether or not notifications/indications should be enabled. * @param characteristic The characteristic containing the client characteristic configuration descriptor. * * @discussion Enables or disables notifications/indications for the characteristic value of characteristic. If characteristic * allows both, notifications will be used. * When notifications/indications are enabled, updates to the characteristic value will be received via delegate method * @link peripheral:didUpdateValueForCharacteristic:error: @/link. Since it is the peripheral that chooses when to send an update, * the application should be prepared to handle them as long as notifications/indications remain enabled. * * @see peripheral:didUpdateNotificationStateForCharacteristic:error: * @seealso CBConnectPeripheralOptionNotifyOnNotificationKey */ - (void)setNotifyValue:(BOOL)enabled forCharacteristic:(CBCharacteristic *)characteristic; /*! * @method discoverDescriptorsForCharacteristic: * * @param characteristic A GATT characteristic. * * @discussion Discovers the characteristic descriptor(s) of characteristic. * * @see peripheral:didDiscoverDescriptorsForCharacteristic:error: */ - (void)discoverDescriptorsForCharacteristic:(CBCharacteristic *)characteristic; /*! * @method readValueForDescriptor: * * @param descriptor A GATT characteristic descriptor. * * @discussion Reads the value of descriptor. * * @see peripheral:didUpdateValueForDescriptor:error: */ - (void)readValueForDescriptor:(CBDescriptor *)descriptor; /*! * @method writeValue:forDescriptor: * * @param data The value to write. * @param descriptor A GATT characteristic descriptor. * * @discussion Writes data to descriptor's value. Client characteristic configuration descriptors cannot be written using * this method, and should instead use @link setNotifyValue:forCharacteristic: @/link. * * @see peripheral:didWriteValueForCharacteristic:error: */ - (void)writeValue:(NSData *)data forDescriptor:(CBDescriptor *)descriptor; /*! * @method openL2CAPChannel: * * @param PSM The PSM of the channel to open * * @discussion Attempt to open an L2CAP channel to the peripheral using the supplied PSM. * * @see peripheral:didWriteValueForCharacteristic:error: */ - (void)openL2CAPChannel:(CBL2CAPPSM)PSM NS_AVAILABLE(10_14, 11_0); @end /*! * @protocol CBPeripheralDelegate * * @discussion Delegate for CBPeripheral. * */ @protocol CBPeripheralDelegate @optional /*! * @method peripheralDidUpdateName: * * @param peripheral The peripheral providing this update. * * @discussion This method is invoked when the @link name @/link of peripheral changes. */ - (void)peripheralDidUpdateName:(CBPeripheral *)peripheral NS_AVAILABLE(10_9, 6_0); /*! * @method peripheral:didModifyServices: * * @param peripheral The peripheral providing this update. * @param invalidatedServices The services that have been invalidated * * @discussion This method is invoked when the @link services @/link of peripheral have been changed. * At this point, the designated CBService objects have been invalidated. * Services can be re-discovered via @link discoverServices: @/link. */ - (void)peripheral:(CBPeripheral *)peripheral didModifyServices:(NSArray *)invalidatedServices NS_AVAILABLE(10_9, 7_0); /*! * @method peripheralDidUpdateRSSI:error: * * @param peripheral The peripheral providing this update. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link readRSSI: @/link call. * * @deprecated Use {@link peripheral:didReadRSSI:error:} instead. */ - (void)peripheralDidUpdateRSSI:(CBPeripheral *)peripheral error:(nullable NSError *)error NS_DEPRECATED(10_7, 10_13, 5_0, 8_0); /*! * @method peripheral:didReadRSSI:error: * * @param peripheral The peripheral providing this update. * @param RSSI The current RSSI of the link. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link readRSSI: @/link call. */ - (void)peripheral:(CBPeripheral *)peripheral didReadRSSI:(NSNumber *)RSSI error:(nullable NSError *)error NS_AVAILABLE(10_13, 8_0); /*! * @method peripheral:didDiscoverServices: * * @param peripheral The peripheral providing this information. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link discoverServices: @/link call. If the service(s) were read successfully, they can be retrieved via * peripheral's @link services @/link property. * */ - (void)peripheral:(CBPeripheral *)peripheral didDiscoverServices:(nullable NSError *)error; /*! * @method peripheral:didDiscoverIncludedServicesForService:error: * * @param peripheral The peripheral providing this information. * @param service The CBService object containing the included services. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link discoverIncludedServices:forService: @/link call. If the included service(s) were read successfully, * they can be retrieved via service's includedServices property. */ - (void)peripheral:(CBPeripheral *)peripheral didDiscoverIncludedServicesForService:(CBService *)service error:(nullable NSError *)error; /*! * @method peripheral:didDiscoverCharacteristicsForService:error: * * @param peripheral The peripheral providing this information. * @param service The CBService object containing the characteristic(s). * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link discoverCharacteristics:forService: @/link call. If the characteristic(s) were read successfully, * they can be retrieved via service's characteristics property. */ - (void)peripheral:(CBPeripheral *)peripheral didDiscoverCharacteristicsForService:(CBService *)service error:(nullable NSError *)error; /*! * @method peripheral:didUpdateValueForCharacteristic:error: * * @param peripheral The peripheral providing this information. * @param characteristic A CBCharacteristic object. * @param error If an error occurred, the cause of the failure. * * @discussion This method is invoked after a @link readValueForCharacteristic: @/link call, or upon receipt of a notification/indication. */ - (void)peripheral:(CBPeripheral *)peripheral didUpdateValueForCharacteristic:(CBCharacteristic *)characteristic error:(nullable NSError *)error; /*! * @method peripheral:didWriteValueForCharacteristic:error: * * @param peripheral The peripheral providing this information. * @param characteristic A CBCharacteristic object. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a {@link writeValue:forCharacteristic:type:} call, when the CBCharacteristicWriteWithResponse type is used. */ - (void)peripheral:(CBPeripheral *)peripheral didWriteValueForCharacteristic:(CBCharacteristic *)characteristic error:(nullable NSError *)error; /*! * @method peripheral:didUpdateNotificationStateForCharacteristic:error: * * @param peripheral The peripheral providing this information. * @param characteristic A CBCharacteristic object. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link setNotifyValue:forCharacteristic: @/link call. */ - (void)peripheral:(CBPeripheral *)peripheral didUpdateNotificationStateForCharacteristic:(CBCharacteristic *)characteristic error:(nullable NSError *)error; /*! * @method peripheral:didDiscoverDescriptorsForCharacteristic:error: * * @param peripheral The peripheral providing this information. * @param characteristic A CBCharacteristic object. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link discoverDescriptorsForCharacteristic: @/link call. If the descriptors were read successfully, * they can be retrieved via characteristic's descriptors property. */ - (void)peripheral:(CBPeripheral *)peripheral didDiscoverDescriptorsForCharacteristic:(CBCharacteristic *)characteristic error:(nullable NSError *)error; /*! * @method peripheral:didUpdateValueForDescriptor:error: * * @param peripheral The peripheral providing this information. * @param descriptor A CBDescriptor object. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link readValueForDescriptor: @/link call. */ - (void)peripheral:(CBPeripheral *)peripheral didUpdateValueForDescriptor:(CBDescriptor *)descriptor error:(nullable NSError *)error; /*! * @method peripheral:didWriteValueForDescriptor:error: * * @param peripheral The peripheral providing this information. * @param descriptor A CBDescriptor object. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link writeValue:forDescriptor: @/link call. */ - (void)peripheral:(CBPeripheral *)peripheral didWriteValueForDescriptor:(CBDescriptor *)descriptor error:(nullable NSError *)error; /*! * @method peripheralIsReadyToSendWriteWithoutResponse: * * @param peripheral The peripheral providing this update. * * @discussion This method is invoked after a failed call to @link writeValue:forCharacteristic:type: @/link, when peripheral is again * ready to send characteristic value updates. * */ - (void)peripheralIsReadyToSendWriteWithoutResponse:(CBPeripheral *)peripheral; /*! * @method peripheral:didOpenL2CAPChannel:error: * * @param peripheral The peripheral providing this information. * @param channel A CBL2CAPChannel object. * @param error If an error occurred, the cause of the failure. * * @discussion This method returns the result of a @link openL2CAPChannel: @link call. */ - (void)peripheral:(CBPeripheral *)peripheral didOpenL2CAPChannel:(nullable CBL2CAPChannel *)channel error:(nullable NSError *)error; @end NS_ASSUME_NONNULL_END