iOS Developer Library

Developer

CBMutableCharacteristic Class Reference

Options
Deployment Target:

On This Page
Language:

CBMutableCharacteristic

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.

Inheritance


Conforms To


Import Statement


Swift

import CoreBluetooth

Objective-C

@import CoreBluetooth;

Availability


Available in iOS 6.0 and later.
  • Returns a newly initialized mutable characteristic with specified permissions, properties, and value.

    Declaration

    Swift

    init!(type UUID: CBUUID!, properties properties: CBCharacteristicProperties, value value: NSData!, permissions permissions: CBAttributePermissions)

    Objective-C

    - (instancetype)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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • UUID UUID Property

    The Bluetooth-specific UUID of the characteristic.

    Declaration

    Swift

    var UUID: CBUUID!

    Objective-C

    @property(retain, readwrite, nonatomic) CBUUID *UUID

    Discussion

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • value value Property

    The value of the characteristic.

    Declaration

    Swift

    var value: NSData!

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • A list of descriptors that describe the characteristic.

    Declaration

    Swift

    var descriptors: [AnyObject]!

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • The properties of the characteristic.

    Declaration

    Swift

    var properties: CBCharacteristicProperties

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • The permissions of the characteristic value.

    Declaration

    Swift

    var permissions: CBAttributePermissions

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    var subscribedCentrals: [AnyObject]! { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    struct CBAttributePermissions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var Readable: CBAttributePermissions { get } static var Writeable: CBAttributePermissions { get } static var ReadEncryptionRequired: CBAttributePermissions { get } static var WriteEncryptionRequired: CBAttributePermissions { get } }

    Objective-C

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

    Constants

    • Readable

      CBAttributePermissionsReadable

      The characteristic’s value has read-only permission.

      Available in iOS 6.0 and later.

    • Writeable

      CBAttributePermissionsWriteable

      The characteristic’s value has write-only permission.

      Available in iOS 6.0 and later.

    • ReadEncryptionRequired

      CBAttributePermissionsReadEncryptionRequired

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

      Available in iOS 6.0 and later.

    • WriteEncryptionRequired

      CBAttributePermissionsWriteEncryptionRequired

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

      Available in iOS 6.0 and later.

    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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.