Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ protected async Task<byte[]> ReadNativeAsync(CancellationToken cancellationToken

if (args.Status != GattStatus.Success)
{
reject(new CharacteristicReadException($"Read characteristic {Id} failed with GATT status {args.Status}.", Id, Service.Id, (int)args.Status));
reject(new CharacteristicReadException($"Read characteristic {Id} failed with GATT status {args.Status}.", Id, Service.Id, (int)args.Status, (int)args.Status));
return;
}

Expand Down Expand Up @@ -113,7 +113,7 @@ await TaskBuilder.FromEvent<bool, EventHandler<CharacteristicWriteCallbackEventA

if (args.Exception != null)
{
reject(new CharacteristicWriteException($"Write characteristic {Id} failed with GATT status {args.Status}.", Id, Service.Id, (int)args.Status));
reject(new CharacteristicWriteException($"Write characteristic {Id} failed with GATT status {args.Status}.", Id, Service.Id, (int)args.Status, (int)args.Status));
return;
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ protected Task<IReadOnlyList<Descriptor>> GetDescriptorsNativeAsync(Cancellation

if (args.Error != null)
{
reject(new CharacteristicReadException($"Discover descriptors error: {args.Error.Description}", Id, Service.Id, (int)args.Error.Code));
reject(new CharacteristicReadException($"Discover descriptors error: {args.Error.Description}", Id, Service.Id, (int)args.Error.Code, args.Error.GetAttStatus()));
}
else
{
Expand Down Expand Up @@ -140,7 +140,7 @@ protected Task<byte[]> ReadNativeAsync(CancellationToken cancellationToken)

if (args.Error != null)
{
reject(new CharacteristicReadException($"Read async error: {args.Error.Description}", Id, Service.Id, (int)args.Error.Code));
reject(new CharacteristicReadException($"Read async error: {args.Error.Description}", Id, Service.Id, (int)args.Error.Code, args.Error.GetAttStatus()));
}
else
{
Expand Down Expand Up @@ -190,7 +190,7 @@ await TaskBuilder.FromEvent<bool, EventHandler<CBCharacteristicEventArgs>, Event
return;

if (args.Error != null)
reject(new CharacteristicWriteException($"Write async error: {args.Error.Description}", Id, Service.Id, (int)args.Error.Code));
reject(new CharacteristicWriteException($"Write async error: {args.Error.Description}", Id, Service.Id, (int)args.Error.Code, args.Error.GetAttStatus()));
else
complete(true);
},
Expand Down Expand Up @@ -295,7 +295,7 @@ protected Task StartUpdatesNativeAsync(CharacteristicUpdateMode mode, Cancellati

if (args.Error != null)
{
reject(new CharacteristicReadException($"Start Notifications: Error {args.Error.Description}", Id, Service.Id, (int)args.Error.Code));
reject(new CharacteristicReadException($"Start Notifications: Error {args.Error.Description}", Id, Service.Id, (int)args.Error.Code, args.Error.GetAttStatus()));
}
else
{
Expand Down Expand Up @@ -338,7 +338,7 @@ protected Task StopUpdatesNativeAsync(CancellationToken cancellationToken)

if (args.Error != null)
{
reject(new CharacteristicReadException($"Stop Notifications: Error {args.Error.Description}", Id, Service.Id, (int)args.Error.Code));
reject(new CharacteristicReadException($"Stop Notifications: Error {args.Error.Description}", Id, Service.Id, (int)args.Error.Code, args.Error.GetAttStatus()));
}
else
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,7 @@ private void ThrowIfWriteFailed(GattWriteResult result)
$"Write characteristic {Id} failed with status {result.Status}{detail}.",
Id,
Service.Id,
result.ProtocolError,
result.ProtocolError);
}

Expand Down
4 changes: 4 additions & 0 deletions DSoft.System.BluetoothLe/DSoft.System.BluetoothLe.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,10 @@
Device.CreateBondAsync and Device.RemoveBondAsync request and remove a bond on Android; removal is
best effort, through a hidden platform method, and reports false where Android refuses it. Both
return false on Apple platforms and Windows.
CharacteristicReadException, CharacteristicWriteException, DescriptorReadException and
DescriptorWriteException carry the GATT status in GattStatus, classified as GattFailure, so an app can
recognise Insufficient Authentication (0x05) and Insufficient Encryption (0x0F) on Android, Apple
platforms and Windows. All four implement IGattStatusException. NativeStatus and messages are unchanged.

4.0.1 - restores the stand-in seam that 4.0 removed. Device and Service can again be derived outside
the library: protected Device(Guid id, string name, int rssi = 0) replaces the parameterless
Expand Down
4 changes: 2 additions & 2 deletions DSoft.System.BluetoothLe/Descriptor/Descriptor.android.cs
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ protected Task WriteNativeAsync(byte[] data, CancellationToken cancellationToken
return;

if (args.Exception != null)
reject(new DescriptorWriteException($"Write descriptor {Id} failed with GATT status {args.Status}.", Id, (int)args.Status));
reject(new DescriptorWriteException($"Write descriptor {Id} failed with GATT status {args.Status}.", Id, (int)args.Status, (int)args.Status));
else
complete(true);
}),
Expand Down Expand Up @@ -71,7 +71,7 @@ protected async Task<byte[]> ReadNativeAsync(CancellationToken cancellationToken

if (args.Exception != null)
{
reject(new DescriptorReadException($"Read descriptor {Id} failed with GATT status {args.Status}.", Id, (int)args.Status));
reject(new DescriptorReadException($"Read descriptor {Id} failed with GATT status {args.Status}.", Id, (int)args.Status, (int)args.Status));
return;
}

Expand Down
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
using System;
using System;
using System.Threading;
using System.Threading.Tasks;
using CoreBluetooth;
using System.BluetoothLe;
using Foundation;
using System.BluetoothLe.Extensions;
using System.BluetoothLe.Utils;

namespace System.BluetoothLe
Expand Down Expand Up @@ -66,7 +67,7 @@ protected Task<byte[]> ReadNativeAsync(CancellationToken cancellationToken)
return;

if (args.Error != null)
reject(new DescriptorReadException($"Read descriptor async error: {args.Error.Description}", Id, (int)args.Error.Code));
reject(new DescriptorReadException($"Read descriptor async error: {args.Error.Description}", Id, (int)args.Error.Code, args.Error.GetAttStatus()));
else
complete(Value);
},
Expand Down Expand Up @@ -102,7 +103,7 @@ protected Task WriteNativeAsync(byte[] data, CancellationToken cancellationToken
return;

if (args.Error != null)
reject(new DescriptorWriteException(args.Error.Description, Id, (int)args.Error.Code));
reject(new DescriptorWriteException(args.Error.Description, Id, (int)args.Error.Code, args.Error.GetAttStatus()));
else
complete(true);
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ protected async Task<byte[]> ReadNativeAsync(CancellationToken cancellationToken
throw new DescriptorReadException(
$"Read descriptor {Id} failed with status {readResult.Status}{ProtocolErrorDetail(readResult.ProtocolError)}.",
Id,
readResult.ProtocolError,
readResult.ProtocolError);
}

Expand All @@ -55,6 +56,7 @@ protected async Task WriteNativeAsync(byte[] data, CancellationToken cancellatio
throw new DescriptorWriteException(
$"Write descriptor {Id} failed with status {result.Status}{ProtocolErrorDetail(result.ProtocolError)}.",
Id,
result.ProtocolError,
result.ProtocolError);
}
}
Expand Down
80 changes: 80 additions & 0 deletions DSoft.System.BluetoothLe/Enums/GattFailure.shared.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
namespace System.BluetoothLe
{
/// <summary>
/// What a failed GATT operation's status says went wrong, for the statuses an app needs to act on.
/// </summary>
/// <remarks>
/// The raw code is on <see cref="IGattStatusException.GattStatus"/>. The security failures matter most: a
/// peripheral that requires a bonded, encrypted link answers an unbonded central with one of them, and the
/// app should ask the user to pair - or to forget the device and pair again, if the peripheral has lost its
/// keys - rather than report a generic fault.
/// </remarks>
public enum GattFailure
{
/// <summary>
/// No GATT status was reported: the operation could not be started, the device disconnected, or the
/// platform failed it for a reason of its own.
/// </summary>
None,

/// <summary>A GATT status that is none of the others. Inspect <see cref="IGattStatusException.GattStatus"/>.</summary>
Other,

/// <summary>ATT error 0x05, Insufficient Authentication: the link must be authenticated (bonded) first.</summary>
InsufficientAuthentication,

/// <summary>ATT error 0x08, Insufficient Authorization: the peripheral refuses this central the operation.</summary>
InsufficientAuthorization,

/// <summary>ATT error 0x0F, Insufficient Encryption: the link must be encrypted first.</summary>
InsufficientEncryption
}

/// <summary>
/// A failed read or write that can carry the GATT status the peripheral or the platform's GATT layer
/// reported. Implemented by <see cref="CharacteristicReadException"/>, <see cref="CharacteristicWriteException"/>,
/// <see cref="DescriptorReadException"/> and <see cref="DescriptorWriteException"/>, so one catch can recognise a
/// security failure from any of them.
/// </summary>
/// <example>
/// <code>
/// catch (BleException ex) when (ex is IGattStatusException { GattFailure: GattFailure.InsufficientAuthentication or GattFailure.InsufficientEncryption })
/// {
/// // Ask the user to pair.
/// }
/// </code>
/// </example>
public interface IGattStatusException
{
/// <summary>
/// The GATT status code, where one was reported: on Android the <c>GattStatus</c> from the callback, on
/// Apple platforms the <c>CBATTError</c> code when the error is in <c>CBATTErrorDomain</c>, and on Windows
/// the protocol error. ATT error codes have the same value on every platform; Android can also report
/// codes of its own GATT layer, such as 0x85. <see langword="null"/> when no status was reported.
/// </summary>
int? GattStatus { get; }

/// <summary><see cref="GattStatus"/>, classified.</summary>
GattFailure GattFailure { get; }
}

internal static class GattStatusCodes
{
public static GattFailure Classify(int? gattStatus)
{
switch (gattStatus)
{
case null:
return GattFailure.None;
case 0x05:
return GattFailure.InsufficientAuthentication;
case 0x08:
return GattFailure.InsufficientAuthorization;
case 0x0F:
return GattFailure.InsufficientEncryption;
default:
return GattFailure.Other;
}
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ namespace System.BluetoothLe
/// <summary>
/// Thrown when reading a characteristic, or enabling notifications on one, fails.
/// </summary>
public class CharacteristicReadException : BleException
public class CharacteristicReadException : BleException, IGattStatusException
{
/// <summary>The characteristic the operation was attempted on, where it is known.</summary>
public Guid CharacteristicId { get; }
Expand All @@ -19,6 +19,14 @@ public class CharacteristicReadException : BleException
/// </summary>
public int? NativeStatus { get; }

/// <inheritdoc/>
/// <remarks>Separate from <see cref="NativeStatus"/>, which keeps its earlier meaning: on Apple platforms
/// that is the <c>NSError</c> code whatever its domain, while this is set only for ATT errors.</remarks>
public int? GattStatus { get; }

/// <inheritdoc/>
public GattFailure GattFailure => GattStatusCodes.Classify(GattStatus);

/// <inheritdoc cref="CharacteristicReadException(string, Guid, Guid, int?)"/>
public CharacteristicReadException(string message) : base(message)
{
Expand All @@ -35,5 +43,19 @@ public CharacteristicReadException(string message, Guid characteristicId, Guid s
ServiceId = serviceId;
NativeStatus = nativeStatus;
}

/// <summary>
/// Creates the exception with the platform status and the GATT status attached.
/// </summary>
/// <param name="message">The message, unchanged from the earlier constructors.</param>
/// <param name="characteristicId">The characteristic, as <see cref="CharacteristicId"/>.</param>
/// <param name="serviceId">The owning service, as <see cref="ServiceId"/>.</param>
/// <param name="nativeStatus">The raw platform status, as <see cref="NativeStatus"/>.</param>
/// <param name="gattStatus">The GATT status, as <see cref="GattStatus"/>.</param>
public CharacteristicReadException(string message, Guid characteristicId, Guid serviceId, int? nativeStatus, int? gattStatus)
: this(message, characteristicId, serviceId, nativeStatus)
{
GattStatus = gattStatus;
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ namespace System.BluetoothLe
/// <c>WriteAsync</c> with no reason attached, while Android threw <see cref="CharacteristicReadException"/>
/// from the write path. Both are now this type on every platform.
/// </remarks>
public class CharacteristicWriteException : BleException
public class CharacteristicWriteException : BleException, IGattStatusException
{
/// <summary>The characteristic the write was attempted on, where it is known.</summary>
public Guid CharacteristicId { get; }
Expand All @@ -24,6 +24,14 @@ public class CharacteristicWriteException : BleException
/// </summary>
public int? NativeStatus { get; }

/// <inheritdoc/>
/// <remarks>Separate from <see cref="NativeStatus"/>, which keeps its earlier meaning: on Apple platforms
/// that is the <c>NSError</c> code whatever its domain, while this is set only for ATT errors.</remarks>
public int? GattStatus { get; }

/// <inheritdoc/>
public GattFailure GattFailure => GattStatusCodes.Classify(GattStatus);

/// <inheritdoc cref="CharacteristicWriteException(string, Guid, Guid, int?)"/>
public CharacteristicWriteException(string message) : base(message)
{
Expand All @@ -40,5 +48,19 @@ public CharacteristicWriteException(string message, Guid characteristicId, Guid
ServiceId = serviceId;
NativeStatus = nativeStatus;
}

/// <summary>
/// Creates the exception with the platform status and the GATT status attached.
/// </summary>
/// <param name="message">The message, unchanged from the earlier constructors.</param>
/// <param name="characteristicId">The characteristic, as <see cref="CharacteristicId"/>.</param>
/// <param name="serviceId">The owning service, as <see cref="ServiceId"/>.</param>
/// <param name="nativeStatus">The raw platform status, as <see cref="NativeStatus"/>.</param>
/// <param name="gattStatus">The GATT status, as <see cref="GattStatus"/>.</param>
public CharacteristicWriteException(string message, Guid characteristicId, Guid serviceId, int? nativeStatus, int? gattStatus)
: this(message, characteristicId, serviceId, nativeStatus)
{
GattStatus = gattStatus;
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,22 @@ namespace System.BluetoothLe
/// <summary>
/// Thrown when reading a descriptor fails.
/// </summary>
public class DescriptorReadException : BleException
public class DescriptorReadException : BleException, IGattStatusException
{
/// <summary>The descriptor the read was attempted on, where it is known.</summary>
public Guid DescriptorId { get; }

/// <summary>The raw platform status code, where the platform supplied one.</summary>
public int? NativeStatus { get; }

/// <inheritdoc/>
/// <remarks>Separate from <see cref="NativeStatus"/>, which keeps its earlier meaning: on Apple platforms
/// that is the <c>NSError</c> code whatever its domain, while this is set only for ATT errors.</remarks>
public int? GattStatus { get; }

/// <inheritdoc/>
public GattFailure GattFailure => GattStatusCodes.Classify(GattStatus);

/// <inheritdoc cref="DescriptorReadException(string, Guid, int?)"/>
public DescriptorReadException(string message) : base(message)
{
Expand All @@ -24,5 +32,18 @@ public DescriptorReadException(string message, Guid descriptorId, int? nativeSta
DescriptorId = descriptorId;
NativeStatus = nativeStatus;
}

/// <summary>
/// Creates the exception with the platform status and the GATT status attached.
/// </summary>
/// <param name="message">The message, unchanged from the earlier constructors.</param>
/// <param name="descriptorId">The descriptor, as <see cref="DescriptorId"/>.</param>
/// <param name="nativeStatus">The raw platform status, as <see cref="NativeStatus"/>.</param>
/// <param name="gattStatus">The GATT status, as <see cref="GattStatus"/>.</param>
public DescriptorReadException(string message, Guid descriptorId, int? nativeStatus, int? gattStatus)
: this(message, descriptorId, nativeStatus)
{
GattStatus = gattStatus;
}
}
}
Loading