CBCharacteristic Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreBluetooth.framework
Availability
Available in iOS 5.0 and later.
Companion guide
Declared in
CBCharacteristic.h
Related sample code

Overview

CBCharacteristic and its subclass CBMutableCharacteristic represent further information about a peripheral’s service. CBCharacteristic objects in particular represent the characteristics of a remote peripheral’s service (remote peripheral devices are represented by CBPeripheral objects). A characteristic contains a single value and any number of descriptors describing that value. The properties of a characteristic determine how the value of the characteristic can be used and how the descriptors can be accessed.

Tasks

Identifying a Characteristic

Accessing Characteristic Data

Properties

descriptors

A list of the descriptors that have been discovered in this characteristic. (read-only)

@property(retain, readonly) NSArray *descriptors
Discussion

The value of this property is an array of CBDescriptor objects that represent a characteristic’s descriptors. Characteristic descriptors provide more information about a characteristic’s value. For example, they may describe the value in human-readable form and describe how the value should be formatted for presentation purposes. For more information about characteristic descriptors, see CBDescriptor Class Reference.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCharacteristic.h

isBroadcasted

You should not use this property. (read-only)

@property(readonly) BOOL isBroadcasted
Availability
  • Available in iOS 5.0 and later.
Declared In
CBCharacteristic.h

isNotifying

A Boolean value indicating whether the characteristic is currently notifying a subscribed central of its value. (read-only)

@property(readonly) BOOL isNotifying
Discussion

YES if you have enabled notifications or indications for the characteristic by successfully calling the setNotifyValue:forCharacteristic: method of the CBPeripheral class. If the value of this property is YES, the peripheral updates the subscribed central that it is connected to whenever the characteristic’s value has changed. If the value of the property is NO, notifications (or indications) have not been enabled for the characteristic, and the peripheral does not update the central that it is connected to whenever the characteristic’s value has changed.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCharacteristic.h

properties

The properties of the characteristic. (read-only)

@property(readonly, nonatomic) CBCharacteristicProperties properties
Discussion

The properties of a characteristic determine how the characteristic’s value and descriptors can be used and accessed. For a list of the possible values representing the properties of a characteristic, see “Characteristic Properties.”

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCharacteristic.h

service

The service that this characteristic belongs to. (read-only)

@property(weak, readonly, nonatomic) CBService *service
Availability
  • Available in iOS 5.0 and later.
Declared In
CBCharacteristic.h

UUID

The Bluetooth-specific UUID of the characteristic. (read-only)

@property(readonly, nonatomic) CBUUID *UUID
Discussion

This property is a 128-bit UUID that identifies the characteristic.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCharacteristic.h

value

The value of the characteristic. (read-only)

@property(retain, readonly) NSData *value
Discussion

This property contains the value of the characteristic. For example, a temperature measurement characteristic of a health thermometer service may have a value that indicates a temperature in Celsius.

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCharacteristic.h

Constants

Characteristic Properties

Values representing the possible properties of a characteristic. Since characteristic properties can be combined, a characteristic may have multiple property values set.

typedef enum {
   CBCharacteristicPropertyBroadcast = 0x01,
   CBCharacteristicPropertyRead = 0x02,
   CBCharacteristicPropertyWriteWithoutResponse = 0x04,
   CBCharacteristicPropertyWrite = 0x08,
   CBCharacteristicPropertyNotify = 0x10,
   CBCharacteristicPropertyIndicate = 0x20,
   CBCharacteristicPropertyAuthenticatedSignedWrites = 0x40,
   CBCharacteristicPropertyExtendedProperties = 0x80,
   CBCharacteristicPropertyNotifyEncryptionRequired = 0x100,
   CBCharacteristicPropertyIndicateEncryptionRequired = 0x200,
} CBCharacteristicProperties;
Constants
CBCharacteristicPropertyBroadcast

The characteristic’s value can be broadcast using a characteristic configuration descriptor.

This property is not allowed for local characteristics published via the addService: method of the CBPeripheralManager class. This means that you cannot use this property when you initialize a new CBMutableCharacteristic object via the initWithType:properties:value:permissions: method of the CBMutableCharacteristic class.

Available in iOS 5.0 and later.

Declared in CBCharacteristic.h.

CBCharacteristicPropertyRead

The characteristic’s value can be read.

Use the readValueForCharacteristic: method of the CBPeripheral class to read the value of a characteristic.

Available in iOS 5.0 and later.

Declared in CBCharacteristic.h.

CBCharacteristicPropertyWriteWithoutResponse

The characteristic’s value can be written, without a response from the peripheral to indicate that the write was successful.

Use the writeValue:forCharacteristic:type: method of the CBPeripheral class to write to a characteristic’s value, using the CBCharacteristicWriteWithoutResponse constant as the parameter for type:. If a characteristic has this property set, no error is sent back to the central when writing to the characteristic’s value is unsuccessful.

Available in iOS 5.0 and later.

Declared in CBCharacteristic.h.

CBCharacteristicPropertyWrite

The characteristic’s value can be written, with a response from the peripheral to indicate that the write was successful.

If a characteristic has this property set, an error is sent to back to the central when writing to the characteristic’s value is unsuccessful. This property allows for values to be written to a characteristic’s value that are longer than those permitted by the CBCharacteristicPropertyWriteWithoutResponse constant. Use the writeValue:forCharacteristic:type: method of the CBPeripheral class to write to a characteristic’s value, using the CBCharacteristicWriteWithResponse constant as the parameter for type:.

Available in iOS 5.0 and later.

Declared in CBCharacteristic.h.

CBCharacteristicPropertyNotify

Notifications of the characteristic’s value are permitted, without a response from the central to indicate that the notification was received.

Available in iOS 5.0 and later.

Declared in CBCharacteristic.h.

CBCharacteristicPropertyIndicate

Indications of the characteristic’s value are permitted, with a response from the central to indicate that the indication was received.

Available in iOS 5.0 and later.

Declared in CBCharacteristic.h.

CBCharacteristicPropertyAuthenticatedSignedWrites

Signed writes of the characteristic’s value are permitted, without a response from the peripheral to indicate that the write was successful.

If a characteristic has this property set, no error is sent back to the central when writing to the characteristic’s value is unsuccessful.

Available in iOS 5.0 and later.

Declared in CBCharacteristic.h.

CBCharacteristicPropertyExtendedProperties

Additional characteristic properties are defined in the characteristic extended properties descriptor.

This property is not allowed for local characteristics published using the addService: method of the CBPeripheralManager class. That is, you cannot use this property when you initialize a CBMutableCharacteristic object using the initWithType:properties:value:permissions: method of the CBMutableCharacteristic class.

Available in iOS 5.0 and later.

Declared in CBCharacteristic.h.

CBCharacteristicPropertyNotifyEncryptionRequired

Only trusted devices can enable notifications of the characteristic’s value.

Available in iOS 6.0 and later.

Declared in CBCharacteristic.h.

CBCharacteristicPropertyIndicateEncryptionRequired

Only trusted devices can enable indications of the characteristic’s value.

Available in iOS 6.0 and later.

Declared in CBCharacteristic.h.