From ff22bf4ddb52192a6ffe7686f048abd995b04f58 Mon Sep 17 00:00:00 2001 From: Matthew Leibowitz Date: Tue, 5 May 2015 03:10:56 +0200 Subject: [PATCH] Added some documentation to the portableAPI: - Microsoft.Band.Portable - Microsoft.Band.Portable.Notifications --- .../BandClientManager.cs | 19 ++++++++ .../Microsoft.Band.Portable/IBandClient.cs | 44 +++++++++++++++++++ .../IBandDeviceInfo.cs | 9 ++++ .../Notifications/BandNotificationManager.cs | 39 ++++++++++++++++ .../Notifications/MessageFlags.cs | 9 ++++ .../Notifications/VibrationType.cs | 30 +++++++++++++ .../Microsoft.Band.Portable/UserConsent.cs | 12 +++++ 7 files changed, 162 insertions(+) diff --git a/Microsoft.Band.Portable/Microsoft.Band.Portable/BandClientManager.cs b/Microsoft.Band.Portable/Microsoft.Band.Portable/BandClientManager.cs index af2c1c7..a331fa8 100644 --- a/Microsoft.Band.Portable/Microsoft.Band.Portable/BandClientManager.cs +++ b/Microsoft.Band.Portable/Microsoft.Band.Portable/BandClientManager.cs @@ -14,6 +14,9 @@ namespace Microsoft.Band.Portable { + /// + /// Provides access to paired Band devices and the ability to connect to them. + /// public class BandClientManager { private static Lazy instance; @@ -23,11 +26,21 @@ static BandClientManager() instance = new Lazy(() => new BandClientManager()); } + /// + /// Gets the value representing the current instance of the client manager. + /// + /// + /// The current instance of the client manager. + /// public static BandClientManager Instance { get { return instance.Value; } } + /// + /// Returns a collection of the Band devices that are paired with the current device. + /// + /// A collection of the paired Bands. public async Task> GetPairedBandsAsync() { #if __ANDROID__ @@ -41,6 +54,12 @@ public async Task> GetPairedBandsAsync() #endif } + /// + /// Connects to the Band device specified by the device information, + /// and returns a client that is used for communication. + /// + /// The Band device information to connect to. + /// The client instance that is used to communicate with the connected Band device. public async Task ConnectAsync(BandDeviceInfo info) { #if __ANDROID__ diff --git a/Microsoft.Band.Portable/Microsoft.Band.Portable/IBandClient.cs b/Microsoft.Band.Portable/Microsoft.Band.Portable/IBandClient.cs index af003df..d94001d 100644 --- a/Microsoft.Band.Portable/Microsoft.Band.Portable/IBandClient.cs +++ b/Microsoft.Band.Portable/Microsoft.Band.Portable/IBandClient.cs @@ -25,6 +25,9 @@ namespace Microsoft.Band.Portable { + /// + /// Represents a connected Band device. + /// public class BandClient { private readonly Lazy sensors; @@ -46,6 +49,12 @@ internal BandClient(NativeBandClient client) } #endif + /// + /// Gets the value representing the current instance of the sensor manager. + /// + /// + /// The current instance of the sensor manager. + /// public BandSensorManager SensorManager { get @@ -56,6 +65,12 @@ public BandSensorManager SensorManager } } + /// + /// Gets the value representing the current instance of the notification manager. + /// + /// + /// The current instance of the notification manager. + /// public BandNotificationManager NotificationManager { get @@ -66,6 +81,12 @@ public BandNotificationManager NotificationManager } } + /// + /// Gets the value representing the current instance of the tile manager. + /// + /// + /// The current instance of the tile manager. + /// public BandTileManager TileManager { get @@ -76,6 +97,12 @@ public BandTileManager TileManager } } + /// + /// Gets the value representing the current instance of the personalization manager. + /// + /// + /// The current instance of the personalization manager. + /// public BandPersonalizationManager PersonalizationManager { get @@ -86,6 +113,12 @@ public BandPersonalizationManager PersonalizationManager } } + /// + /// Gets a value indicating whether this instance is connected to a Band device. + /// + /// + /// true if this instance is connected to a Band device; otherwise, false. + /// public bool IsConnected { get @@ -102,6 +135,10 @@ public bool IsConnected } } + /// + /// Returns the firmware version of the Band. + /// + /// A string representing the firmware version of the Band. public async Task GetFirmwareVersionAsync() { CheckDisposed(); @@ -117,6 +154,10 @@ public async Task GetFirmwareVersionAsync() #endif } + /// + /// Returns the hardware version of the Band. + /// + /// A string representing the hardware version of the Band. public async Task GetHardwareVersionAsync() { CheckDisposed(); @@ -132,6 +173,9 @@ public async Task GetHardwareVersionAsync() #endif } + /// + /// Disconnects from the current Band device. + /// public async Task DisconnectAsync() { CheckDisposed(); diff --git a/Microsoft.Band.Portable/Microsoft.Band.Portable/IBandDeviceInfo.cs b/Microsoft.Band.Portable/Microsoft.Band.Portable/IBandDeviceInfo.cs index c0b7a6e..c98c87c 100644 --- a/Microsoft.Band.Portable/Microsoft.Band.Portable/IBandDeviceInfo.cs +++ b/Microsoft.Band.Portable/Microsoft.Band.Portable/IBandDeviceInfo.cs @@ -9,6 +9,9 @@ namespace Microsoft.Band.Portable { + /// + /// Represents a paired device. + /// public class BandDeviceInfo { #if __ANDROID__ || __IOS__ || WINDOWS_PHONE_APP @@ -20,6 +23,12 @@ internal BandDeviceInfo(NativeBandDeviceInfo info) } #endif + /// + /// Gets the name of the Band device this instance represents. + /// + /// + /// The name of the Band device. + /// public string Name { get diff --git a/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/BandNotificationManager.cs b/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/BandNotificationManager.cs index 5ed68f5..ef552be 100644 --- a/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/BandNotificationManager.cs +++ b/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/BandNotificationManager.cs @@ -8,6 +8,9 @@ namespace Microsoft.Band.Portable.Notifications { + /// + /// Represents the notification manager for a connected Band device. + /// public class BandNotificationManager { private readonly BandClient client; @@ -23,16 +26,42 @@ internal BandNotificationManager(BandClient client, NativeBandNotificationManage } #endif + /// + /// Sends a message to a specific tile to the connected Band device with the provided tile ID, title, + /// body and timestamp. + /// + /// The tile identifier. + /// The message title. + /// The message body. + /// The message timestamp. public async Task SendMessageAsync(Guid tileId, string title, string body, DateTime timestamp) { await SendMessageAsync(tileId, title, body, timestamp, false); } + /// + /// Sends a message to a specific tile to the connected Band device with the provided tile ID, title, body, + /// timestamp and, optionally, with a dialog. + /// + /// The tile identifier. + /// The message title. + /// The message body. + /// The message timestamp. + /// Display a dialog if set to true; otherwise, don't. public async Task SendMessageAsync(Guid tileId, string title, string body, DateTime timestamp, bool showDialog) { await SendMessageAsync(tileId, title, body, timestamp, showDialog ? MessageFlags.ShowDialog : MessageFlags.None); } + /// + /// Sends a message to a specific tile to the connected Band device with the provided tile ID, title, body, + /// timestamp and with message flags to control how the message is provided. + /// + /// The tile identifier. + /// The message title. + /// The message body. + /// The message timestamp. + /// The message flags to control how the message is provided to the Band device. public async Task SendMessageAsync(Guid tileId, string title, string body, DateTime timestamp, MessageFlags messageFlags) { #if __ANDROID__ || __IOS__ @@ -42,6 +71,12 @@ public async Task SendMessageAsync(Guid tileId, string title, string body, DateT #endif } + /// + /// Shows a dialog on the connected Band device. + /// + /// The tile identifier. + /// The message title. + /// The message body. public async Task ShowDialogAsync(Guid tileId, string title, string body) { #if __ANDROID__ || __IOS__ @@ -51,6 +86,10 @@ public async Task ShowDialogAsync(Guid tileId, string title, string body) #endif } + /// + /// Vibrates the connected Band device using the specified vibration type. + /// + /// Type of vibration to use. public async Task VibrateAsync(VibrationType vibrationType) { #if __ANDROID__ || __IOS__ diff --git a/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/MessageFlags.cs b/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/MessageFlags.cs index b8b832f..fe9ac79 100644 --- a/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/MessageFlags.cs +++ b/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/MessageFlags.cs @@ -1,8 +1,17 @@ namespace Microsoft.Band.Portable.Notifications { + /// + /// Represents flags that control how a message is sent to a Band device. + /// public enum MessageFlags { + /// + /// Use the default message style. + /// None, + /// + /// Show dialog when sending a message. + /// ShowDialog } } diff --git a/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/VibrationType.cs b/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/VibrationType.cs index 2645132..87484af 100644 --- a/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/VibrationType.cs +++ b/Microsoft.Band.Portable/Microsoft.Band.Portable/Notifications/VibrationType.cs @@ -1,15 +1,45 @@ namespace Microsoft.Band.Portable.Notifications { + /// + /// Represents a type of vibration that can be sent to a Band device. + /// public enum VibrationType { + /// + /// The ramp down vibration type. + /// RampDown, + /// + /// The ramp up vibration type. + /// RampUp, + /// + /// The notification one-tone vibration type. + /// NotificationOneTone, + /// + /// The notification two-tone vibration type. + /// NotificationTwoTone, + /// + /// The notification alarm vibration type. + /// NotificationAlarm, + /// + /// The notification timer vibration type. + /// NotificationTimer, + /// + /// The one-tone high vibration type. + /// OneToneHigh, + /// + /// The three-tone high vibration type. + /// ThreeToneHigh, + /// + /// The two-tone high vibration type. + /// TwoToneHigh } } diff --git a/Microsoft.Band.Portable/Microsoft.Band.Portable/UserConsent.cs b/Microsoft.Band.Portable/Microsoft.Band.Portable/UserConsent.cs index 96614bd..13a0540 100644 --- a/Microsoft.Band.Portable/Microsoft.Band.Portable/UserConsent.cs +++ b/Microsoft.Band.Portable/Microsoft.Band.Portable/UserConsent.cs @@ -1,9 +1,21 @@ namespace Microsoft.Band.Portable { + /// + /// Represents the result of a request for user consent. + /// public enum UserConsent { + /// + /// The user declined consent. + /// Declined, + /// + /// The user granted consent. + /// Granted, + /// + /// The user has not yet reponded to a request. + /// Unspecified } }