Vibration API

A simple API to make the device vibrate with the given settings.

We are missing mdocs for some earlier implementation code:

• Platform
• Battery
• Device Info
• Geocoding
• Permissions
• Platform
• Preferences

Description

All exceptions should end in "Exception"

Sensors API Magnetometer indicating the devices orientation relative to Earth's magnetic field.

API Level:

• iOS: CMMotionManager -> Create 1 Instance only
• Android: Sensor Listeners
• UWP: Windows.Device.Sensors

API:

bool IsListening {get;}
void Start(SensorSpeed speed, Action<MagnetometerData> handler);
void Stop();

struct MagnetometerData
{
   bool MagneticFieldX{ get; }
  bool MagneticFieldY{get;}
bool MagneticFieldZ{get;}
}

Description

Right now we have DeviceInfo, which also holds a bunch of information about the Application too.

This way we can have:

AppInfo.Version and DeviceInfo.Version :)

Would be really nice.

Ability to Share text via a share sheet.

Things to consider:

• Title
• Chooser Title
• Message
• Link
• Activities to Exclude on iOS?

Each of these work a bit different so we should look at this.

Simple battery % and charging state.

class Battery {
    // range from [0.0, 1.0]
    // -1 is unknown or invalid
    double ChargeLevel { get; }

    BatteryState State { get; }

    event EventHandler<BatteryChangedEventArgs> BatteryChanged;
}

class BatteryChangedEventArgs : EventArgs {
    ctor(double level, BatteryStatus status);

    double ChargeLevel { get; }
    BatteryState State { get; }
}

enum BatteryState {
    Unknown,
    Charging,
    Discharging,
    Full,
    NotCharging
}

Native platform features:

iOS Notes:

• Discharging can be mapped from unplugged.
• NotCharging can be ignored.

UWP Notes:

• NotCharging can be mapped from idle.
• Full can be mapped if ChargeLevel >= 100.
• Unknown can be mapped if ChargeLevel <= 0 || notPresent

Fingerprint API

Description

API for Fingerprint scanning.

VS bug #735680

A simple API to open the default dialer, preloaded with a number and name.

static class PhoneDialer {
    static bool IsSupported { get; }
    // should throw a NotSupportedOnDeviceException if the device is not capable.
    static void Open(string number);
}

For the discussion around exceptions, see #19

Bug report best practices: Submitting Issues

Description

Steps to Reproduce

1. Go to browser branch
2. run mdocs
3. all support libs will have docs generated

Some platforms will require some sort of initialization or otherwise platform specific calls. This is the area they should be dealt with.

Platform - Android Only

public static class Platform
{
    internal static Activity CurrentActivity { get; }
    internal static Context CurrentContext { get; }

    // Should be called from the MainActivity in general
    public static void Init (Activity activity, Bundle bundle);

    // Should be called from the activity where permission requests occurred
    public static void OnRequestPermissionsResult (int requestCode, string[] permissions, Permission[] grantResults);
}

Clipboard manipulation:

class Clipboard {
    void SetText(string text);
    void SetText(string text, string label);
    bool HasText { get; }
    Task<string> GetTextAsync();
}

• UWP: https://docs.microsoft.com/en-us/windows/uwp/app-to-app/copy-and-paste
• Android: https://developer.android.com/reference/android/content/ClipboardManager.html
• iOS https://developer.apple.com/documentation/uikit/uipasteboard

I see that keystore/keychain is planned -- I have an implementation of this done for iOS/Android, and I don't think it would take much effort to add UWP. Wasn't sure how far along on that you were or if perhaps this feature was meant for something larger (like Xamarin.Auth), but if you're just looking for the basic keystore/keychain implementation im happy to send a PR :-)

The Geolocation API is meant to be extremely simple at this point.

Geocoding API's: #28

static class Geolocation {
    // Android and iOS have a concept of a last known position that should return very quickly compared to firing up the GPS and waiting for a position.
    // This should return null if there is no known last position.
    // UWP has something interesting about consent-less location:
    // https://docs.microsoft.com/en-us/uwp/api/Windows.Devices.Geolocation.Geolocator#Windows_Devices_Geolocation_Geolocator_AllowFallbackToConsentlessPositions
    static Task<Position> GetLastKnownPositionAsync();

    // We should throw different exceptions depending on the error: For example a DeviceFeatureUnavailableException or something similar if the device has no GPS abilities.
    static Task<Position> GetPositionAsync(GeolocationAccuracy desiredAccuracy, TimeSpan timeout, CancellationToken token = default(CancellationToken));
}

class Position {
    Position();
    Position(double latitude, double longitude);
    Position(double latitude, double longitude, DateTimeOffset timestamp);
    Position(Position position);

    DateTimeOffset Timestamp { get; set; }
    double Latitude { get; set; }
    double Longitude { get; set; }

    static double CalculateDistance(Position positionStart, Position positionEnd);
    static double CalculateDistance(
        double latitudeStart, double latitudeEnd, 
        double longitudeStart, double longitudeEnd);
}

enum GeolocationAccuracy {
    Lowest,
    Low,
    Medium,
    High,
    Best
}

The accuracy enum values should map to the following table of platform specific accuracy choices:

class GeolocationException {
    GeolocationException(GeolocationErrorType errorType);
    GeolocationException(GeolocationErrorType, Exception innerException);

    GeolocationErrorType ErrorType { get; }
}

enum GeolocationErrorType {
    PositionUnavailable,
    Unauthorized
}

We should have the following repository docs:

• Contributing document
• Issue Template
• Pull Request Template

Keep in mind, GitHub has conventions for these documents so that they appear appropriately to users in the Web UI (eg: When creating an issue, the issue is prepopulated with the template).

Sensors APIs (Compass, Accelerometer, Gyroscope, Magnetometer)

INPROGRESS

(Enhancement)
Now that Xamarin.Mac is the same thing as Xamarin.iOS (xamarin-macios), supporting macOS should be low hanging fruit, right?

For example, with clipboard support.

A simple way to convert from a position to an address.

Geolocation API's: #7

_NOTE: the Position type is used from #7 _

static class Geocoding {
    // Requires a map key string on UWP
    // should throw an exception on UWP if this isn’t specified via the static MapKey property.
    static Task<IEnumerable<Address>> GetAddressesAsync(Position position);
    static Task<IEnumerable<Position>> GetPositionsForAddressAsync(string address);
}

// UWP-only partial
static class Geocoding {
    // UWP Only, and should only be in the UWP assembly
    // Users can call `Geolocation.MapKey = "blah"` from their UWP specific code (like where Inits are called).
    static string MapKey { get; set; }
}

class Address{
    double Latitude { get; set; }
    double Longitude { get; set; }

    string AdminArea { get; set; }
    string CountryCode { get; set; }
    string CountryName { get; set; }
    string FeatureName { get; set; }
    string Locality { get; set; }
    string PostalCode { get; set; }
    string SubAdminArea { get; set; }
    string SubLocality { get; set; }
    string SubThoroughfare { get; set; }
    string Thoroughfare { get; set; }
}

NFC API

Read only API - iOS allows only reading NDEF tags.

• Android: Android.Nfc
• iOS: CoreNFC
• UWP:

A simple API to send an email.

static class Email {
    static bool IsAttachmentSupported { get; }
    static bool IsHtmlMessageSupported { get; }

    // should throw a NotSupportedOnDeviceException if the device is not capable.
    Task ComposeAsync(EmailMessage message);

class EmailMessage {
    EmailMessage(string subject, string body, params string[] to);

    string Subject { get; set }
    string Body { get; set }
    bool IsMessageHtml { get; set }
    IList<string> To  { get; set; }
    IList<string> Bcc { get; set; }
    IList<string> Cc { get; set; }
    IList<EmailAttachment> Attachments { get; set; }

    // should throw a NotSupportedOnDeviceException if the device is not capable.
    void Attach(string attachmentName, string contentType, Stream stream);
    // should throw a NotSupportedOnDeviceException if the device is not capable.
    void Attach(string attachmentName, string contentType, string filename);
    // should throw a NotSupportedOnDeviceException if the device is not capable.
    void Attach(string attachmentName, string contentType, byte[] data);
}

class EmailAttachment {
    string Name { get; set; }
    string ContentType { get; set; }
    string FileName { get; set; }
    Stream Stream { get; set; }
}

For the discussion around exceptions, see #19

Are you interested in Tizen support?
As I can see more and more xam-plugins now supports tizen platform.

There's been a lot of discussion around handling checking of device capabilities and feature availability at runtime. This should be a central place to formulate our strategy around these types of API's.

Keep in mind we want to grow the API surface as conservatively as possible. Once an API is public in our first stable release, it lives forever.

We also want to remember that the reason for adding any API's is to make developers' experiences delightful in consuming our library.

Purpose

The purpose of any sort of Status or Availability query on a feature is to see if it's usable or not when called. This means in almost every case, the developer doesn't really care about the actual state of availability, but rather that they can use the feature.

There's one exception to this: When something might be unavailable, but could be made available through code (eg: prompting the user, etc).

NOTE: This is not to be confused with missing or lack of granted permissions for a feature.

Strategies

Capabilities class

One strategy was to introduce a Capabilities class. I dislike this strategy for a couple of reasons:

1. It's separated from the actual class being used, and much less discoverable. If I'm working with Location, if while I'm typing Location. I see Location.Availability, it might prompt me with the idea that I should or at least could check to see if the feature works at runtime before using it.
2. Capabilities is in a sense tightly coupled to pretty much every other class.

One suggestion is we could have a property in each class which just calls into the Capabilities class. I also dislike this idea as it introduces ambiguity (we'll end up with people writing code like if (Geolocation.IsAvailable && Capabilities.HasGeolocation) to be safe. It also means more code paths to test and maintain.

Exceptions

Regardless of the strategy we use around checking for feature/capability availability, users won't be required to check these before attempting to use them, so we will still need to throw exceptions such as NotSupportedException at runtime if a particular API is unavailable at the time of invocation.

So, the exception strategy is to simply omit any API for checking availability and have the developer rely on exception handling to detect when things are not supported or available.

The benefit to this approach is we can always add other API's for checking availability down the road as this exception work will be done regardless.

Where this approach becomes a bit messy is with statuses where a developer may be able to do something to enable or have the user enable a feature and try again. For example, this becomes a bit messy:

Position p;

try {
    p = await Geolocation.GetPositionAsync ();
} catch (GeolocationDisabledException) {
    // Prompt user to enable geolocation
    await DoSomethingToGetTheUserToEnable ();

    // Try getting location again
    try {
        p = await Geolocation.GetPositionAsync ();
    } catch (Exception ex) {
        // Not gonna happen
    }
}

Status or Availability properties

Given the purpose of these API's, most cases where such an availability API would be useful could be distilled down to mostly a true/false basis. However, we want to avoid bool still as using an enum allows for more possible values in the future if necessary.

Most cases could use a simple enum such as:

public enum SmsStatus {
	Unavailable,
	Ready
}

And the class would implement a simple property:

public static partial class Sms {
	public static SmsStatus Status { get; }
}

In cases where we might want to provide another status to indicate something is unavailable but may be able to be made available we would introduce another status value:

public enum GeolocationStatus {
	Unavailable,
	Disabled,
	Ready
}

And the class implements:

public static partial class Geolocation {
	public static GeolocationStatus Status { get; }
}

In this case, GeolocationStatus.Disabled would indicate to the developer that the device may be capable of providing location data, but that feature is for some reason disabled (perhaps the user turned off location services on android). This could be a queue for the developer to prompt the user to enable location services.

There are also other possibilities for the naming convention here:

• Status
• Availability
• SupportLevel

VS bug #735684

This may be something that will be very useful.

@jamesmontemagno has done this in his plugin: https://github.com/jamesmontemagno/SettingsPlugin/blob/master/src/Plugin.Settings.Android/Settings.cs#L53-L60

Sensors API Accelerometer to indicate the instantaneous acceleration of the device in three dimensional space.

API Level:

• iOS: CMMotionManager -> Create 1 Instance only
• Android: Sensor Listeners
• UWP: Windows.Device.Sensors

API:

bool IsListening {get;}
void Start(SensorSpeed speed, Action<AccelerometerData> handler);
void Stop();

struct AccelerometerData
{
   bool AccelerationX { get; }
  bool AccelerationY {get;}
bool AccelerationZ {get;}
}

We want to document our API's with mdoc, and from that generate msxml docs to ship in the nupkg for providing intelligence information.

• App Information
• Battery
• Clipboard
• Data Transfer
• Device Information
• File System Helpers
• Geocoding
• Open Browser
• Preferences
• Screen Lock
• SMS

Bug report best practices: Submitting Issues

Description

Steps to Reproduce

1. Look at the author field of the nuspec

Expected Behavior

<Authors>Microsoft</Authors>

Actual Behavior

<Authors>Xamarin Inc.</Authors>

Basic information about a Device and its Operating system.

DeviceInfo

Properties

• string Model (readonly)
• string Manufacturer (readonly)
• string DeviceName (readonly)
• string Version (readonly)
• Version VersionNumber (readonly)
• string AppVersion (readonly)
• string AppBuild (readonly)
• string Platform (readonly)

  These values returned will match those which Xamarin.Forms uses.

• string Idiom (readonly)
• bool IsDevice (readonly)

DeviceInfo.Idioms

Consts

• string Car = nameof (Car)
• string Desktop = nameof (Desktop)
• string Phone = nameof (Phone)
• string Tablet = nameof (Tablet)
• string Television = nameof (Television)
• string Watch = nameof (Watch)

DeviceInfo.Platforms

Consts

• string Android = nameof (Android)
• string iOS = nameof (iOS)
• string UWP = “Windows” // must match Forms

Open links in browser (shell out to native, or use embedded system browser), with some customizability.

Some discussed points:

• Only implement what most browsers support (no custom views, buttons, etc)
• Colors are OK to implement
• Android Support CustomTabs dependency is ok

UIThreadRunInvoker class offers unified API for calling methods on Main/UI thread from background threads (async methods).

UIThreadRunInvoker.BeginOnUIThread(Action action);

calls:

• on Android

Platform.CurrentActivity(Action action);

• on iOS

UIKit.UIAPplication.SharedApplication.BeginInvokeOnMainThread(Action action);

To investigate is call to CoreFoundation.DispatchQueue.MainQueue.DispatchAsync(Action)

• on UWP

Windows.ApplicationModel.Core.CoreAPplication.MainView.CoreWindow.Dispatcher.RunAsync(Action)

Next steps (if API survives) is to add overloads for Func<> arguments/parameters...

Description

API for turning on and off Flashlight

API

static class Flashlight
{
    static void On();
    static void Off();

    static FlashlightState State { get; }
}

enum FlashlightState
{
    Unknown,
    On,
    Off
}

A simple API to send an SMS.

static class Sms {
    // whether or not the device can open a compose dialog
    static bool IsComposeSupported { get; }

    // whether or not the device can send in the background
    static bool IsSendSupported { get; }

    // open the compose window, throw if not supported
    static Task ComposeAsync(SmsMessage message);

    // send a message in the background, throw if not supported
    // this is supported only on Android and UWP
    static Task SendAsync(SmsMessage message);
}

class SmsMessage {
    SmsMessage(string body, string recipient);

    string Body { get; set; }
    string Recipient { get; set; }
}

For the discussion around exceptions, see #19

Sensors API Gyroscope to the instantaneous rotation around the device's three primary axes.

API Level:

• iOS: CMMotionManager -> Create 1 Instance only
• Android: Sensor Listeners
• UWP: Windows.Device.Sensors

API:

bool IsListening {get;}
void Start(SensorSpeed speed, Action<GyrometerData> handler);
void Stop();

struct GyrometerData
{
   bool AngularVelocityX { get; }
  bool AngularVelocityY {get;}
bool AngularVelocityX {get;}
}

Would we want a Screenshot of the current window/screen?

VS bug #735683

There are some patterns in several API's that we might want to have some common exception types for.

Feature Availability

Things like GPS, Cameras, Phone, SMS, etc are not always available on a given device. When a method is called which tries to make use of such a device, we should throw a consistent exception to let the developer know the feature is unsupported on the current device:

NotSupportedOnDeviceException : NotSupportedException

There may also be the case where a feature is technically supported by the device, but not enabled:

NotEnabledOnDeviceException : InvalidOperationException

Open to ideas on naming, and other common exceptions we may require...

The CONTRIBUTING.md file needs some information about our usage of mdoc and how to do an mdoc update, as well as what is expected on pull requests with mdoc.

Issues moved to #25 (phone dialler), #26 (sms), #27 (email)

Make devices speak arbitrary text

TextToSpeech

public static class TextToSpeech
{
    public static int MaxSpeechInputLength { get; }

    public static Task SpeakAsync (string text, CancellationToken cancelToken = default(CancellationToken));
    public static Task SpeakAsync (string text, SpeakSettings settings, CancellationToken cancelToken = default(CancellationToken));

    public static Task GetLocalesAsync ();
}

SpeakSettings (struct)

public struct SpeakSettings
{
    public Locale Locale;
    public float? Pitch;
    public float? SpeakRate;
    public float? Volume;
}

Locale

public static class Locale
{
    public string Language { get; }
    public string Country { get; }
    public string Name { get; }
}

Some simple and helpful abstractions for common Filesystem problems

static class FileSystem {
    // Returns a path to a directory that can be used to temporarily store data.
    // Potentially cleared by the user (eg: on Android in the device settings) or by the OS when space runs low.
    static string CacheDirectory { get; }

    // Returns a path to a directory that contains app data.
    // This directory may not be visible to the user.
    static string AppDataDirectory { get; }

    // Returns a path to a directory that contains user-visible data.
    // This directory may be visible/editable to the user.
    static string UserDataDirectory { get; }

    // Opens a file Stream to a file embedded in the app package.
    //     Android: Asset
    //     iOS: NSBundle.MainBundle
    //     UWP: Package.InstalledLocation
    static Task<Stream> OpenAppPackageFileAsync(string filename);
}

This may either be the unique device identifier and/or the installation Id.

APIs:

• iOS: identifierForVendor This is a unique ID for all of a vendors apps installed on the device.
• Android: Build.Serial now replaced in API 26 with Build.GetSerial() not every manufacturer fills this out though and previously I used the Secure.AndroidId
• UWP: GetSystemIdForPublisher with backup of GetPackageSpecificToken

If you are leave a comment here can you please describe why and how you are using it.

A really simple way to check if we have an internet connection.

Connectivity

Properties

• bool IsConnected (readonly)
• IEnumerable ConnectionTypes (readonly)

Events

• EventHandler ConnectivityChanged
• EventHandler ConnectivityTypeChanged

ConnectionType (enum)

• Cellular
• WiFi
• Desktop
• Wimax
• Other
• Bluetooth

ConnectivityChangedEventArgs : EventArgs

Constructors

• ConnectivityChangedEventArgs (bool isConnected)

Properties

• bool IsConnected (readonly)

ConnectivityTypeChangedEventArgs : ConnectivityChangedEventArgs

Constructors

• ConnectivityTypeChangedEventArgs (bool isConnected, IEnumerable types)

Properties

• IEnumerable ConnectionTypes (readonly)

Storage Secure (Secured) API

1. Task<string> LoadAsync(string filename)
2. Task SaveAsync(string filename, string content)

Description

The logic does not set the sms_body if the recipient isn't filled out.

Steps to Reproduce

1. Launch sample
2. Go to SMS
3. Fill in only body

Expected Behavior

Should open sms app and have body filled in

Actual Behavior

Default Sms app opens

Basic Information

• Version with issue: Latest
• Last known good version: None
• IDE: VS2017
• Platform Target Frameworks:
  • Android: Nougat tested

Extra info:

https://gist.github.com/mustafasevgi/8c6b638ffd5fca90d45d may be the better route here.

Would be nifty to abstract where we could into simple bools for devices capabilities:

bool HasTelephony { get; }
bool HasMicrophone { get; }
bool HasBluetooth { get; }
bool HasBluetoothLE { get; }
bool HasCamera { get; }
bool HasBiometric { get; }
bool HasIR { get; }
bool HasGPS { get; }
bool HasNFC { get; }
bool HasCompass { get; }
bool HasAccelerometer { get; }
bool HasBarometer { get; }
bool HasGyroscope { get; }
bool HasProximity { get; }
bool HasHeartrate { get; }
bool HasStepCounter { get; }
bool HasStepDetector { get; }

I think list would be a good start.

Discussion:

Should it be called BeginInvokeOnMainThread or InvokeOnMainThread

Via C# docs:

• Delegate.Invoke: Executes synchronously, on the same thread.
• Delegate.BeginInvoke: Executes asynchronously, on a threadpool thread.
• Control.Invoke: Executes on the UI thread, but calling thread waits for completion before continuing.
• Control.BeginInvoke: Executes on the UI thread, and calling thread doesn't wait for completion.

API Review to ensure we do what we say:
Today we are:

• Android: Post to looper
• iOS: calls BeginInvokeOnMainThread and calls (action.Invoke)
• uwp we run async on the dispatcher

Check and Request permissions.

Internally we need to ensure we have API’s for a couple of things:

• internal bool EnsurePermissionDeclared (string permission) checks if Info.plist on iOS, or AndroidManifest.xml, or x on UWP has the permission declared/defined and throws an exception with a meaningful error message including a link to documentation of how to ensure permissions are defined in the appropriate file for the given platform at runtime.

Permissions

public static class Permissions 
{
    public static Task<PermissionStatus> CheckPermissionAsync (string permission);
    public static Task<IDictionary<string, PermissionStatus>> CheckPermissionsAsync (params string[] permissions);

    public static Task<PermissionStatus> RequestPermissionAsync (string permission);
    public static Task<IDictionary<string, PermissionStatus>> RequestPermissionsAsync (params string[] permissions);
}

PermissionStatus (enum)

public enum PermissionStatus {
    Unknown,
    Denied,
    Disabled,
    Restricted,
    Granted,
}

Please add a quick introduction about how solution is structured.
The multi-targeting libraries are new to lot of people, a contribution guide will help greatly for new contributors

Would we want to have an API that detects if the user shakes the device?

VS bug #735682

Description

Steps to Reproduce

1. Have surface fully charged and plugged in
2. API reports NotCharging
3. API returns Power source battery

Expected Behavior

Report Full

Actual Behavior

NotCharging Returned