CBMutableCharacteristic Class Reference

Inherits from
Conforms to
Availability
Available in iOS 6.0 and later.
Companion guide
Declared in
CBCharacteristic.h
Related sample code

Overview

CBMutableCharacteristic objects represent the characteristics of a local peripheral’s service (local peripheral devices are represented by CBPeripheralManager objects). This class adds write access to many of the properties in the CBCharacteristic class it inherits from.

You use this class to create a characteristic and to set its properties and permissions as desired. After you create a characteristic and add it to a local service, you can publish it (and the service) to the peripheral’s local database using the addService: method of the CBPeripheralManager class. After you publish a characteristic, the characteristic is cached and you can no longer make changes to it.

Tasks

Initializing a Mutable Characteristic

Managing a Mutable Characteristic

Properties

descriptors

A list of descriptors that describe the characteristic.

@property(retain, readwrite) 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 6.0 and later.
Declared In
CBCharacteristic.h

permissions

The permissions of the characteristic value.

@property(assign, readwrite, nonatomic) CBAttributePermissions permissions
Discussion

Characteristic permissions represent the read, write, and encryption permissions for a characteristic’s value. For a complete list and discussion of the characteristic permissions that may be set, see “Characteristic Value Permissions.”

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

properties

The properties of the characteristic.

@property(assign, readwrite, nonatomic) CBCharacteristicProperties properties
Discussion

The properties of a characteristic determine how the characteristic’s value and descriptors can be used and accessed. The characteristic properties CBCharacteristicPropertyBroadcast and CBCharacteristicPropertyExtendedProperties are not allowed for mutable characteristics. That is, you cannot set these properties when you initialize a CBMutableCharacteristic object using the initWithType:properties:value:permissions: method. For a list of the possible values representing the properties of a characteristic, see the CBCharacteristicProperties enumeration in CBCharacteristic Class Reference.

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

subscribedCentrals

A list of centrals currently subscribed to the characteristic’s value. (read-only)

@property(retain, readonly) NSArray *subscribedCentrals
Discussion

The value of this property is an array of CBCentral objects that are currently subscribed to the characteristic’s value. The array is empty if the characteristic is not configured to support notifications or indications. Even if the characteristic is configured to support notifications or indications, the array is empty if no centrals are currently subscribing to the characteristic’s value.

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

UUID

The Bluetooth-specific UUID of the characteristic.

@property(assign, readwrite, nonatomic) CBUUID *UUID
Discussion

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

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

value

The value of the characteristic.

@property(retain, readwrite) 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 6.0 and later.
Declared In
CBCharacteristic.h

Instance Methods

initWithType:properties:value:permissions:

Returns a newly initialized mutable characteristic with specified permissions, properties, and value.

- (id)initWithType:(CBUUID *)UUID properties:(CBCharacteristicProperties)properties value:(NSData *)value permissions:(CBAttributePermissions)permissions
Parameters
UUID

A 128-bit UUID that identifies the characteristic.

properties

The properties of the characteristic.

value

The characteristic value to be cached. If nil, the value is dynamic and will be requested on demand.

permissions

The permissions of the characteristic value.

Return Value

A newly initialized mutable characteristic.

Discussion

If you specify a value for the characteristic, the value is cached and its properties and permissions are set to CBCharacteristicPropertyRead and CBAttributePermissionsReadable, respectively. Therefore, if you need the value of a characteristic to be writeable, or if you expect the value to change during the lifetime of the published service to which the characteristic belongs, you must specify the value to be nil. So doing ensures that the value is treated dynamically and requested by the peripheral manager whenever the peripheral manager receives a read or write request from a central. When the peripheral manager receives a read or write request from a central, it calls the peripheralManager:didReceiveReadRequest: or the peripheralManager:didReceiveWriteRequests: methods of its delegate object, respectively.

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

Constants

Characteristic Value Permissions

Values representing the read, write, and encryption permissions for a characteristic’s value.

typedef enum {
   CBAttributePermissionsReadable = 0x01,
   CBAttributePermissionsWriteable = 0x02,
   CBAttributePermissionsReadEncryptionRequired = 0x04,
   CBAttributePermissionsWriteEncryptionRequired = 0x08,
} CBAttributePermissions;
Constants
CBAttributePermissionsReadable

The characteristic’s value has read-only permission.

Available in iOS 6.0 and later.

Declared in CBCharacteristic.h.

CBAttributePermissionsWriteable

The characteristic’s value has write-only permission.

Available in iOS 6.0 and later.

Declared in CBCharacteristic.h.

CBAttributePermissionsReadEncryptionRequired

The characteristic’s value is readable only by trusted devices.

Available in iOS 6.0 and later.

Declared in CBCharacteristic.h.

CBAttributePermissionsWriteEncryptionRequired

The characteristic’s value is writeable only by trusted devices.

Available in iOS 6.0 and later.

Declared in CBCharacteristic.h.

Discussion

When you initialize a new mutable characteristic, you set the read, write, and encryption permissions for the characteristic’s value. Setting the read and write permissions for a characteristic’s value is different from specifying the read and write properties for a characteristic’s value. Specifying the read and write properties for a characteristic’s value lets the client (a central) know what read and write permissions of the characteristic’s value are set. Specifying the read and write permissions for a characteristic’s value actually sets the permissions for the server (the peripheral) to allow the type of read or write specified by the characteristic’s properties. Therefore, if you specify read or write properties when initializing a mutable characteristic, you must also specify corresponding read or write permissions for that characteristic. If you want to enforce encryption requirements for reads and writes on a characteristic’s value, you must do so by specifying the relevant permission (CBAttributePermissionsReadEncryptionRequired or CBAttributePermissionsWriteEncryptionRequired). You may set more than one permission for a characteristic’s value.