GattCharacteristic GattCharacteristic GattCharacteristic GattCharacteristic Class

Represents a Characteristic of a GATT service. The GattCharacteristic object represents a GATT Characteristic of a particular service, and is obtained from the Characteristics property of the GattDeviceService object.

Syntax

Declaration

public sealed class GattCharacteristicpublic sealed class GattCharacteristicPublic NotInheritable Class GattCharacteristic

Properties summary

Gets the handle used to uniquely identify GATT-based characteristic attributes as declared on the Bluetooth LE device.

Gets the GATT characteristic properties, as defined by the GATT profile.

If the ExtendedProperties flag is present it also represents the properties of the Extended Characteristic Properties Descriptor.

Gets the list of presentation format descriptors associated with this GattCharacteristic, in the order specified by the Aggregate Format Descriptor.

The list shall be empty if no PresentationFormat or Aggregate Format descriptors are found.

Gets or sets the desired GATT security options for over the air communication with the device.

Windows will negotiate the maximum security possible with the device as part of the pairing process, and specifying a lower level of security won’t degrade the existing security level.

Gets the GattDeviceService of which this characteristic is a member.

Get the user friendly description for this GattCharacteristic, if the User Description Descriptor is present, otherwise this will be an empty string.

Gets the GATT Characteristic UUID for this GattCharacteristic.

Methods summary

Converts a Bluetooth SIG defined short Id to a full GATT UUID.

Gets the collection of all descriptors belonging to this GattCharacteristic instance.

Returns a vector of descriptors, that are identified by the specified UUID, and belong to this GattCharacteristic instance.

Reads the current value of the ClientCharacteristicConfigurationDescriptor.

Performs a Characteristic Value read from the value cache maintained by Windows.

Performs a Characteristic Value read either from the value cache maintained by Windows, or directly from the device.

Writes the ClientCharacteristicConfigurationDescriptor to the Bluetooth LE device, and if the value to be written represents an indication or a notification and a ValueChanged event handler is registered, enables receiving ValueChanged events from the device.

Performs a Characteristic Value write to a Bluetooth LE device.

Performs a Characteristic Value write to a Bluetooth LE device.

Events summary

An App can register an event handler in order to receive events when notification or indications are received from a device, after setting the Client Characteristic Configuration Descriptor.

Properties

  • AttributeHandle
    AttributeHandle
    AttributeHandle
    AttributeHandle

    Gets the handle used to uniquely identify GATT-based characteristic attributes as declared on the Bluetooth LE device.

    public ushort AttributeHandle { get; }public ushort AttributeHandle { get; }Public ReadOnly Property AttributeHandle As ushort

    Property Value

    • ushort
      ushort
      ushort
      ushort

      Handle that uniquely identifies GATT-based characteristic attributes.

  • CharacteristicProperties
    CharacteristicProperties
    CharacteristicProperties
    CharacteristicProperties

    Gets the GATT characteristic properties, as defined by the GATT profile.

    If the ExtendedProperties flag is present it also represents the properties of the Extended Characteristic Properties Descriptor.

    public GattCharacteristicProperties CharacteristicProperties { get; }public GattCharacteristicProperties CharacteristicProperties { get; }Public ReadOnly Property CharacteristicProperties As GattCharacteristicProperties

    Property Value

  • PresentationFormats
    PresentationFormats
    PresentationFormats
    PresentationFormats

    Gets the list of presentation format descriptors associated with this GattCharacteristic, in the order specified by the Aggregate Format Descriptor.

    The list shall be empty if no PresentationFormat or Aggregate Format descriptors are found.

    public IVectorView<GattPresentationFormat> PresentationFormats { get; }public IVectorView<GattPresentationFormat> PresentationFormats { get; }Public ReadOnly Property PresentationFormats As IVectorView<GattPresentationFormat>

    Property Value

    • An array of GattPresentationFormat objects that contain the list of presentation format descriptors associated with this GattCharacteristic, in the order specified by the Aggregate Format Descriptor.

  • ProtectionLevel
    ProtectionLevel
    ProtectionLevel
    ProtectionLevel

    Gets or sets the desired GATT security options for over the air communication with the device.

    Windows will negotiate the maximum security possible with the device as part of the pairing process, and specifying a lower level of security won’t degrade the existing security level.

    public GattProtectionLevel ProtectionLevel { get; set; }public GattProtectionLevel ProtectionLevel { get; set; }Public ReadWrite Property ProtectionLevel As GattProtectionLevel

    Property Value

  • Service
    Service
    Service
    Service

    Gets the GattDeviceService of which this characteristic is a member.

    public GattDeviceService Service { get; }public GattDeviceService Service { get; }Public ReadOnly Property Service As GattDeviceService

    Property Value

  • UserDescription
    UserDescription
    UserDescription
    UserDescription

    Get the user friendly description for this GattCharacteristic, if the User Description Descriptor is present, otherwise this will be an empty string.

    public string UserDescription { get; }public string UserDescription { get; }Public ReadOnly Property UserDescription As string

    Property Value

    • string
      string
      string
      string

      The user friendly description for this GattCharacteristic, if the User Description Descriptor is present, otherwise this will be an empty string.

  • Uuid
    Uuid
    Uuid
    Uuid

    Gets the GATT Characteristic UUID for this GattCharacteristic.

    public Guid Uuid { get; }public Guid Uuid { get; }Public ReadOnly Property Uuid As Guid

    Property Value

    • System.Guid
      System.Guid
      System.Guid
      System.Guid

      The GATT Characteristic UUID for this GattCharacteristic.

Methods

  • ConvertShortIdToUuid(System.UInt16)
    ConvertShortIdToUuid(System.UInt16)
    ConvertShortIdToUuid(System.UInt16)
    ConvertShortIdToUuid(System.UInt16)

    Converts a Bluetooth SIG defined short Id to a full GATT UUID.

    public static Guid ConvertShortIdToUuid(System.UInt16)public static Guid ConvertShortIdToUuid(System.UInt16)Public Static Function ConvertShortIdToUuid(System.UInt16) As Guid

    Parameters

    • shortId
      System.UInt16
      System.UInt16
      System.UInt16
      System.UInt16

      A 16-bit Bluetooth GATT Service UUID.

    Returns

    • System.Guid
      System.Guid
      System.Guid
      System.Guid

      The corresponding 128-bit GATT Characteristic UUID, that uniquely identifies this characteristic.

  • GetAllDescriptors()
    GetAllDescriptors()
    GetAllDescriptors()
    GetAllDescriptors()

    Gets the collection of all descriptors belonging to this GattCharacteristic instance.

    public IVectorView<GattDescriptor> GetAllDescriptors()public IVectorView<GattDescriptor> GetAllDescriptors()Public Function GetAllDescriptors() As IVectorView( Of GattDescriptor )

    Returns

    • The collection of all descriptors belonging to this GattCharacteristic instance.

  • GetDescriptors(System.Guid)
    GetDescriptors(System.Guid)
    GetDescriptors(System.Guid)
    GetDescriptors(System.Guid)

    Returns a vector of descriptors, that are identified by the specified UUID, and belong to this GattCharacteristic instance.

    public IVectorView<GattDescriptor> GetDescriptors(System.Guid)public IVectorView<GattDescriptor> GetDescriptors(System.Guid)Public Function GetDescriptors(System.Guid) As IVectorView( Of GattDescriptor )

    Parameters

    • descriptorUuid
      System.Guid
      System.Guid
      System.Guid
      System.Guid

      The UUID for the descriptors to be retrieved.

    Returns

    • A vector of descriptors whose UUIDs match descriptorUuid.

  • ReadClientCharacteristicConfigurationDescriptorAsync()
    ReadClientCharacteristicConfigurationDescriptorAsync()
    ReadClientCharacteristicConfigurationDescriptorAsync()
    ReadClientCharacteristicConfigurationDescriptorAsync()

    Reads the current value of the ClientCharacteristicConfigurationDescriptor.

    public IAsyncOperation<GattReadClientCharacteristicConfigurationDescriptorResult> ReadClientCharacteristicConfigurationDescriptorAsync()public IAsyncOperation<GattReadClientCharacteristicConfigurationDescriptorResult> ReadClientCharacteristicConfigurationDescriptorAsync()Public Function ReadClientCharacteristicConfigurationDescriptorAsync() As IAsyncOperation( Of GattReadClientCharacteristicConfigurationDescriptorResult )

    Returns

  • ReadValueAsync()
    ReadValueAsync()
    ReadValueAsync()
    ReadValueAsync()

    Performs a Characteristic Value read from the value cache maintained by Windows.

    public IAsyncOperation<GattReadResult> ReadValueAsync()public IAsyncOperation<GattReadResult> ReadValueAsync()Public Function ReadValueAsync() As IAsyncOperation( Of GattReadResult )

    Returns

    • The object required to manage the asynchronous operation, which, upon completion, returns a GattReadResult object, which in turn contains the completion status of the asynchronous operation and, if successful, the data read from the device.

  • ReadValueAsync(Windows.Devices.Bluetooth.BluetoothCacheMode)
    ReadValueAsync(Windows.Devices.Bluetooth.BluetoothCacheMode)
    ReadValueAsync(Windows.Devices.Bluetooth.BluetoothCacheMode)
    ReadValueAsync(Windows.Devices.Bluetooth.BluetoothCacheMode)

    Performs a Characteristic Value read either from the value cache maintained by Windows, or directly from the device.

    public IAsyncOperation<GattReadResult> ReadValueAsync(Windows.Devices.Bluetooth.BluetoothCacheMode)public IAsyncOperation<GattReadResult> ReadValueAsync(Windows.Devices.Bluetooth.BluetoothCacheMode)Public Function ReadValueAsync(Windows.Devices.Bluetooth.BluetoothCacheMode) As IAsyncOperation( Of GattReadResult )

    Parameters

    Returns

    • The object required to manage the asynchronous operation, which, upon completion, returns a GattReadResult object, which in turn contains the completion status of the asynchronous operation and, if successful, the data read from the device.

  • WriteClientCharacteristicConfigurationDescriptorAsync(Windows.Devices.Bluetooth.GenericAttributeProfile.GattClientCharacteristicConfigurationDescriptorValue)
    WriteClientCharacteristicConfigurationDescriptorAsync(Windows.Devices.Bluetooth.GenericAttributeProfile.GattClientCharacteristicConfigurationDescriptorValue)
    WriteClientCharacteristicConfigurationDescriptorAsync(Windows.Devices.Bluetooth.GenericAttributeProfile.GattClientCharacteristicConfigurationDescriptorValue)
    WriteClientCharacteristicConfigurationDescriptorAsync(Windows.Devices.Bluetooth.GenericAttributeProfile.GattClientCharacteristicConfigurationDescriptorValue)

    Writes the ClientCharacteristicConfigurationDescriptor to the Bluetooth LE device, and if the value to be written represents an indication or a notification and a ValueChanged event handler is registered, enables receiving ValueChanged events from the device.

    public IAsyncOperation<GattCommunicationStatus> WriteClientCharacteristicConfigurationDescriptorAsync(Windows.Devices.Bluetooth.GenericAttributeProfile.GattClientCharacteristicConfigurationDescriptorValue)public IAsyncOperation<GattCommunicationStatus> WriteClientCharacteristicConfigurationDescriptorAsync(Windows.Devices.Bluetooth.GenericAttributeProfile.GattClientCharacteristicConfigurationDescriptorValue)Public Function WriteClientCharacteristicConfigurationDescriptorAsync(Windows.Devices.Bluetooth.GenericAttributeProfile.GattClientCharacteristicConfigurationDescriptorValue) As IAsyncOperation( Of GattCommunicationStatus )

    Parameters

    Returns

    • The object that manages the asynchronous operation, which, upon completion, returns the status with which the operation completed.

  • WriteValueAsync(Windows.Storage.Streams.IBuffer)
    WriteValueAsync(Windows.Storage.Streams.IBuffer)
    WriteValueAsync(Windows.Storage.Streams.IBuffer)
    WriteValueAsync(Windows.Storage.Streams.IBuffer)

    Performs a Characteristic Value write to a Bluetooth LE device.

    public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(Windows.Storage.Streams.IBuffer)public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(Windows.Storage.Streams.IBuffer)Public Function WriteValueAsync(Windows.Storage.Streams.IBuffer) As IAsyncOperation( Of GattCommunicationStatus )

    Parameters

    • value

      A Windows.Storage.Streams.IBuffer object which contains the data to be written to the Bluetooth LE device.

    Returns

    • The object that manages the asynchronous operation, which, upon completion, returns the status with which the operation completed.

  • WriteValueAsync(Windows.Storage.Streams.IBuffer,Windows.Devices.Bluetooth.GenericAttributeProfile.GattWriteOption)
    WriteValueAsync(Windows.Storage.Streams.IBuffer,Windows.Devices.Bluetooth.GenericAttributeProfile.GattWriteOption)
    WriteValueAsync(Windows.Storage.Streams.IBuffer,Windows.Devices.Bluetooth.GenericAttributeProfile.GattWriteOption)
    WriteValueAsync(Windows.Storage.Streams.IBuffer,Windows.Devices.Bluetooth.GenericAttributeProfile.GattWriteOption)

    Performs a Characteristic Value write to a Bluetooth LE device.

    public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(Windows.Storage.Streams.IBuffer,Windows.Devices.Bluetooth.GenericAttributeProfile.GattWriteOption)public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(Windows.Storage.Streams.IBuffer,Windows.Devices.Bluetooth.GenericAttributeProfile.GattWriteOption)Public Function WriteValueAsync(Windows.Storage.Streams.IBuffer,Windows.Devices.Bluetooth.GenericAttributeProfile.GattWriteOption) As IAsyncOperation( Of GattCommunicationStatus )

    Parameters

    Returns

    • The object that manages the asynchronous operation, which, upon completion, returns the status with which the operation completed.

Events

  • ValueChanged
    ValueChanged
    ValueChanged
    ValueChanged

    An App can register an event handler in order to receive events when notification or indications are received from a device, after setting the Client Characteristic Configuration Descriptor.

    public event TypedEventHandler ValueChangedpublic event TypedEventHandler ValueChangedPublic Event ValueChanged

    Remarks

    The GattValueChangedEventArgs object represents the arguments received by a ValueChanged event handler used to process characteristic value change notification and indication events sent by a Bluetooth LE device.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.DualApiPartitionAttribute
Windows.Foundation.Metadata.StaticAttribute

Details

Assembly

Windows.Devices.Bluetooth.GenericAttributeProfile.dll