448 lines
17 KiB
Objective-C
448 lines
17 KiB
Objective-C
/*
|
|
* @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 <CoreBluetooth/CoreBluetooth.h> instead.
|
|
#endif
|
|
|
|
#import <CoreBluetooth/CBDefines.h>
|
|
#import <CoreBluetooth/CBPeer.h>
|
|
#import <CoreBluetooth/CBL2CAPChannel.h>
|
|
|
|
#import <Foundation/Foundation.h>
|
|
|
|
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<CBPeripheralDelegate> 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 <code>CBService</code> objects that have been discovered on the peripheral.
|
|
*/
|
|
@property(retain, readonly, nullable) NSArray<CBService *> *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
|
|
* <link>peripheralIsReadyToSendWriteWithoutResponse:</link> 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
|
|
* <link>didUpdateANCSAuthorizationForPeripheral:</link> 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 <code>CBUUID</code> objects representing the service types to be discovered. If <i>nil</i>,
|
|
* all services will be discovered.
|
|
*
|
|
* @discussion Discovers available service(s) on the peripheral.
|
|
*
|
|
* @see peripheral:didDiscoverServices:
|
|
*/
|
|
- (void)discoverServices:(nullable NSArray<CBUUID *> *)serviceUUIDs;
|
|
|
|
/*!
|
|
* @method discoverIncludedServices:forService:
|
|
*
|
|
* @param includedServiceUUIDs A list of <code>CBUUID</code> objects representing the included service types to be discovered. If <i>nil</i>,
|
|
* all of <i>service</i>s 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 <i>service</i>.
|
|
*
|
|
* @see peripheral:didDiscoverIncludedServicesForService:error:
|
|
*/
|
|
- (void)discoverIncludedServices:(nullable NSArray<CBUUID *> *)includedServiceUUIDs forService:(CBService *)service;
|
|
|
|
/*!
|
|
* @method discoverCharacteristics:forService:
|
|
*
|
|
* @param characteristicUUIDs A list of <code>CBUUID</code> objects representing the characteristic types to be discovered. If <i>nil</i>,
|
|
* all characteristics of <i>service</i> will be discovered.
|
|
* @param service A GATT service.
|
|
*
|
|
* @discussion Discovers the specified characteristic(s) of <i>service</i>.
|
|
*
|
|
* @see peripheral:didDiscoverCharacteristicsForService:error:
|
|
*/
|
|
- (void)discoverCharacteristics:(nullable NSArray<CBUUID *> *)characteristicUUIDs forService:(CBService *)service;
|
|
|
|
/*!
|
|
* @method readValueForCharacteristic:
|
|
*
|
|
* @param characteristic A GATT characteristic.
|
|
*
|
|
* @discussion Reads the characteristic value for <i>characteristic</i>.
|
|
*
|
|
* @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 <i>value</i> to <i>characteristic</i>'s characteristic value.
|
|
* If the <code>CBCharacteristicWriteWithResponse</code> type is specified, {@link peripheral:didWriteValueForCharacteristic:error:}
|
|
* is called with the result of the write request.
|
|
* If the <code>CBCharacteristicWriteWithoutResponse</code> 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 <i>characteristic</i>. If <i>characteristic</i>
|
|
* 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 <i>characteristic</i>.
|
|
*
|
|
* @see peripheral:didDiscoverDescriptorsForCharacteristic:error:
|
|
*/
|
|
- (void)discoverDescriptorsForCharacteristic:(CBCharacteristic *)characteristic;
|
|
|
|
/*!
|
|
* @method readValueForDescriptor:
|
|
*
|
|
* @param descriptor A GATT characteristic descriptor.
|
|
*
|
|
* @discussion Reads the value of <i>descriptor</i>.
|
|
*
|
|
* @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 <i>data</i> to <i>descriptor</i>'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 <NSObject>
|
|
|
|
@optional
|
|
|
|
/*!
|
|
* @method peripheralDidUpdateName:
|
|
*
|
|
* @param peripheral The peripheral providing this update.
|
|
*
|
|
* @discussion This method is invoked when the @link name @/link of <i>peripheral</i> 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 <i>peripheral</i> have been changed.
|
|
* At this point, the designated <code>CBService</code> objects have been invalidated.
|
|
* Services can be re-discovered via @link discoverServices: @/link.
|
|
*/
|
|
- (void)peripheral:(CBPeripheral *)peripheral didModifyServices:(NSArray<CBService *> *)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
|
|
* <i>peripheral</i>'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 <code>CBService</code> 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 <i>service</i>'s <code>includedServices</code> 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 <code>CBService</code> 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 <i>service</i>'s <code>characteristics</code> 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 <code>CBCharacteristic</code> 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 <code>CBCharacteristic</code> 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 <code>CBCharacteristicWriteWithResponse</code> 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 <code>CBCharacteristic</code> 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 <code>CBCharacteristic</code> 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 <i>characteristic</i>'s <code>descriptors</code> 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 <code>CBDescriptor</code> 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 <code>CBDescriptor</code> 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 <i>peripheral</i> 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 <code>CBL2CAPChannel</code> 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
|