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 GattCharacteristicpublic sealed 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.

Prerelease. Returns the descriptors for this GattCharacteristic instance.

Prerelease. Returns the descriptors with the specified cache mode for this GattCharacteristic instance.

Prerelease. Returns the descriptors whose UUIDs match descriptorUuid.

Prerelease. Returns the descriptors whose UUIDs match descriptorUuid with the specified cacheMode.

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.

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

Prerelease. Performs a Characteristic Value write to a Bluetooth LE device.

Prerelease. 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 ushortpublic ushort AttributeHandle { get; }

    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 GattCharacteristicPropertiespublic GattCharacteristicProperties CharacteristicProperties { get; }

    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>public IVectorView<GattPresentationFormat> PresentationFormats { get; }

    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 GattProtectionLevelpublic GattProtectionLevel ProtectionLevel { get; set; }

    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 GattDeviceServicepublic GattDeviceService Service { get; }

    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 stringpublic string UserDescription { get; }

    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 Guidpublic Guid Uuid { get; }

    Property Value

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

      The GATT Characteristic UUID for this GattCharacteristic.

Methods

  • ConvertShortIdToUuid(UInt16)
    ConvertShortIdToUuid(UInt16)
    ConvertShortIdToUuid(UInt16)
    ConvertShortIdToUuid(UInt16)

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

    public static Guid ConvertShortIdToUuid(UInt16 shortId)public static Guid ConvertShortIdToUuid(UInt16 shortId)Public Static Function ConvertShortIdToUuid(shortId As UInt16) As Guidpublic static Guid ConvertShortIdToUuid(UInt16 shortId)

    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 )public IVectorView<GattDescriptor> GetAllDescriptors()

    Returns

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

  • GetDescriptors(Guid)
    GetDescriptors(Guid)
    GetDescriptors(Guid)
    GetDescriptors(Guid)

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

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

    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.

  • GetDescriptorsAsync()
    GetDescriptorsAsync()
    GetDescriptorsAsync()
    GetDescriptorsAsync()

    Prerelease. Returns the descriptors for this GattCharacteristic instance.

    public IAsyncOperation<GattDescriptorsResult> GetDescriptorsAsync()public IAsyncOperation<GattDescriptorsResult> GetDescriptorsAsync()Public Function GetDescriptorsAsync() As IAsyncOperation( Of GattDescriptorsResult )public IAsyncOperation<GattDescriptorsResult> GetDescriptorsAsync()

    Returns

    • An asynchronous operation that completes with the descriptors for this GattCharacteristic instance.

  • GetDescriptorsAsync(BluetoothCacheMode)
    GetDescriptorsAsync(BluetoothCacheMode)
    GetDescriptorsAsync(BluetoothCacheMode)
    GetDescriptorsAsync(BluetoothCacheMode)

    Prerelease. Returns the descriptors with the specified cache mode for this GattCharacteristic instance.

    public IAsyncOperation<GattDescriptorsResult> GetDescriptorsAsync(BluetoothCacheMode cacheMode)public IAsyncOperation<GattDescriptorsResult> GetDescriptorsAsync(BluetoothCacheMode cacheMode)Public Function GetDescriptorsAsync(cacheMode As BluetoothCacheMode) As IAsyncOperation( Of GattDescriptorsResult )public IAsyncOperation<GattDescriptorsResult> GetDescriptorsAsync(BluetoothCacheMode cacheMode)

    Parameters

    Returns

    • An asynchronous operation that completes with the descriptors.

  • GetDescriptorsForUuidAsync(Guid)
    GetDescriptorsForUuidAsync(Guid)
    GetDescriptorsForUuidAsync(Guid)
    GetDescriptorsForUuidAsync(Guid)

    Prerelease. Returns the descriptors whose UUIDs match descriptorUuid.

    public IAsyncOperation<GattDescriptorsResult> GetDescriptorsForUuidAsync(Guid descriptorUuid)public IAsyncOperation<GattDescriptorsResult> GetDescriptorsForUuidAsync(Guid descriptorUuid)Public Function GetDescriptorsForUuidAsync(descriptorUuid As Guid) As IAsyncOperation( Of GattDescriptorsResult )public IAsyncOperation<GattDescriptorsResult> GetDescriptorsForUuidAsync(Guid descriptorUuid)

    Parameters

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

      The UUID for the descriptors to be retrieved.

    Returns

    • An asynchronous operation that completes with the descriptors whose UUIDs match descriptorUuid.

  • GetDescriptorsForUuidAsync(Guid, BluetoothCacheMode)
    GetDescriptorsForUuidAsync(Guid, BluetoothCacheMode)
    GetDescriptorsForUuidAsync(Guid, BluetoothCacheMode)
    GetDescriptorsForUuidAsync(Guid, BluetoothCacheMode)

    Prerelease. Returns the descriptors whose UUIDs match descriptorUuid with the specified cacheMode.

    public IAsyncOperation<GattDescriptorsResult> GetDescriptorsForUuidAsync(Guid descriptorUuid, BluetoothCacheMode cacheMode)public IAsyncOperation<GattDescriptorsResult> GetDescriptorsForUuidAsync(Guid descriptorUuid, BluetoothCacheMode cacheMode)Public Function GetDescriptorsForUuidAsync(descriptorUuid As Guid, cacheMode As BluetoothCacheMode) As IAsyncOperation( Of GattDescriptorsResult )public IAsyncOperation<GattDescriptorsResult> GetDescriptorsForUuidAsync(Guid descriptorUuid, BluetoothCacheMode cacheMode)

    Parameters

    Returns

    • Returns an asynchronous operation that completes with the descriptors for the 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 )public IAsyncOperation<GattReadClientCharacteristicConfigurationDescriptorResult> ReadClientCharacteristicConfigurationDescriptorAsync()

    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 )public IAsyncOperation<GattReadResult> ReadValueAsync()

    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(BluetoothCacheMode)
    ReadValueAsync(BluetoothCacheMode)
    ReadValueAsync(BluetoothCacheMode)
    ReadValueAsync(BluetoothCacheMode)

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

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

    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(GattClientCharacteristicConfigurationDescriptorValue)
    WriteClientCharacteristicConfigurationDescriptorAsync(GattClientCharacteristicConfigurationDescriptorValue)
    WriteClientCharacteristicConfigurationDescriptorAsync(GattClientCharacteristicConfigurationDescriptorValue)
    WriteClientCharacteristicConfigurationDescriptorAsync(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(GattClientCharacteristicConfigurationDescriptorValue clientCharacteristicConfigurationDescriptorValue)public IAsyncOperation<GattCommunicationStatus> WriteClientCharacteristicConfigurationDescriptorAsync(GattClientCharacteristicConfigurationDescriptorValue clientCharacteristicConfigurationDescriptorValue)Public Function WriteClientCharacteristicConfigurationDescriptorAsync(clientCharacteristicConfigurationDescriptorValue As GattClientCharacteristicConfigurationDescriptorValue) As IAsyncOperation( Of GattCommunicationStatus )public IAsyncOperation<GattCommunicationStatus> WriteClientCharacteristicConfigurationDescriptorAsync(GattClientCharacteristicConfigurationDescriptorValue clientCharacteristicConfigurationDescriptorValue)

    Parameters

    Returns

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

  • WriteClientCharacteristicConfigurationDescriptorWithResultAsync(GattClientCharacteristicConfigurationDescriptorValue)
    WriteClientCharacteristicConfigurationDescriptorWithResultAsync(GattClientCharacteristicConfigurationDescriptorValue)
    WriteClientCharacteristicConfigurationDescriptorWithResultAsync(GattClientCharacteristicConfigurationDescriptorValue)
    WriteClientCharacteristicConfigurationDescriptorWithResultAsync(GattClientCharacteristicConfigurationDescriptorValue)

    Prerelease. 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<GattWriteResult> WriteClientCharacteristicConfigurationDescriptorWithResultAsync(GattClientCharacteristicConfigurationDescriptorValue clientCharacteristicConfigurationDescriptorValue)public IAsyncOperation<GattWriteResult> WriteClientCharacteristicConfigurationDescriptorWithResultAsync(GattClientCharacteristicConfigurationDescriptorValue clientCharacteristicConfigurationDescriptorValue)Public Function WriteClientCharacteristicConfigurationDescriptorWithResultAsync(clientCharacteristicConfigurationDescriptorValue As GattClientCharacteristicConfigurationDescriptorValue) As IAsyncOperation( Of GattWriteResult )public IAsyncOperation<GattWriteResult> WriteClientCharacteristicConfigurationDescriptorWithResultAsync(GattClientCharacteristicConfigurationDescriptorValue clientCharacteristicConfigurationDescriptorValue)

    Parameters

    Returns

    • Returns an asynchronous operation that completes with a GattWriteResult object.

  • WriteValueAsync(IBuffer)
    WriteValueAsync(IBuffer)
    WriteValueAsync(IBuffer)
    WriteValueAsync(IBuffer)

    Performs a Characteristic Value write to a Bluetooth LE device.

    public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(IBuffer value)public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(IBuffer value)Public Function WriteValueAsync(value As IBuffer) As IAsyncOperation( Of GattCommunicationStatus )public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(IBuffer value)

    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(IBuffer, GattWriteOption)
    WriteValueAsync(IBuffer, GattWriteOption)
    WriteValueAsync(IBuffer, GattWriteOption)
    WriteValueAsync(IBuffer, GattWriteOption)

    Performs a Characteristic Value write to a Bluetooth LE device.

    public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(IBuffer value, GattWriteOption writeOption)public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(IBuffer value, GattWriteOption writeOption)Public Function WriteValueAsync(value As IBuffer, writeOption As GattWriteOption) As IAsyncOperation( Of GattCommunicationStatus )public IAsyncOperation<GattCommunicationStatus> WriteValueAsync(IBuffer value, GattWriteOption writeOption)

    Parameters

    Returns

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

  • WriteValueWithResultAsync(IBuffer)
    WriteValueWithResultAsync(IBuffer)
    WriteValueWithResultAsync(IBuffer)
    WriteValueWithResultAsync(IBuffer)

    Prerelease. Performs a Characteristic Value write to a Bluetooth LE device.

    public IAsyncOperation<GattWriteResult> WriteValueWithResultAsync(IBuffer value)public IAsyncOperation<GattWriteResult> WriteValueWithResultAsync(IBuffer value)Public Function WriteValueWithResultAsync(value As IBuffer) As IAsyncOperation( Of GattWriteResult )public IAsyncOperation<GattWriteResult> WriteValueWithResultAsync(IBuffer value)

    Parameters

    • value

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

    Returns

    • An asynchronous operation that completes with a GattWriteResult object.

  • WriteValueWithResultAsync(IBuffer, GattWriteOption)
    WriteValueWithResultAsync(IBuffer, GattWriteOption)
    WriteValueWithResultAsync(IBuffer, GattWriteOption)
    WriteValueWithResultAsync(IBuffer, GattWriteOption)

    Prerelease. Performs a Characteristic Value write to a Bluetooth LE device.

    public IAsyncOperation<GattWriteResult> WriteValueWithResultAsync(IBuffer value, GattWriteOption writeOption)public IAsyncOperation<GattWriteResult> WriteValueWithResultAsync(IBuffer value, GattWriteOption writeOption)Public Function WriteValueWithResultAsync(value As IBuffer, writeOption As GattWriteOption) As IAsyncOperation( Of GattWriteResult )public IAsyncOperation<GattWriteResult> WriteValueWithResultAsync(IBuffer value, GattWriteOption writeOption)

    Parameters

    Returns

    • An asynchronous operation that completes with a GattWriteResult object.

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 ValueChangedpublic event TypedEventHandler 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.ContractVersionAttribute
Windows.Foundation.Metadata.DualApiPartitionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute

Details

Assembly

Windows.Devices.Bluetooth.GenericAttributeProfile.dll