Improvements in API (#8)

Author: antoniofagundes

System.Device.UsbStream/Properties/AssemblyInfo.cs

@@ -20,5 +20,5 @@
 /////////////////////////////////////////////////////////////////
 // This attribute is mandatory when building Interop libraries //
 // update this whenever the native assembly signature changes  //
-[assembly: AssemblyNativeVersion("1.0.0.0")]
+[assembly: AssemblyNativeVersion("100.0.0.1")]
 /////////////////////////////////////////////////////////////////

System.Device.UsbStream/System.Device.UsbStream.nfproj

@@ -44,8 +44,12 @@
     </NFMDP_PE_ExcludeClassByName>
   </ItemGroup>
   <ItemGroup>
+    <Compile Include="UsbClient.cs" />
+    <Compile Include="UsbDeviceEventListener.cs" />
+    <Compile Include="UsbStreamDataReceivedEventHandler.cs" />
     <Compile Include="UsbStream.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
+    <Compile Include="UsbStreamDataReceivedEventArgs.cs" />
   </ItemGroup>
   <ItemGroup>
     <Reference Include="mscorlib">

System.Device.UsbStream/UsbClient.cs

@@ -0,0 +1,26 @@
+// Copyright (c) .NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+
+namespace System.Device.Usb
+{
+    /// <summary>
+    /// Provides static methods for the creation of USB client instances.
+    /// </summary>
+    public partial class UsbClient
+    {
+        /// <summary>
+        /// Creates an USB Stream from a WinUSB device that will use the specified name as the device description.
+        /// </summary>
+        /// <param name="classId"><see cref="Guid"/> for the device class that will be used by WinUSB device.</param>
+        /// <param name="name">Name to be used as device description.</param>
+        /// <returns>A new UsbStream that was created with the specified name.</returns>
+        public static UsbStream CreateUsbStream(
+            Guid classId,
+            string name)
+        {
+            return new UsbStream(
+                classId,
+                name);
+        }
+    }
+}

System.Device.UsbStream/UsbDeviceEventListener.cs

@@ -0,0 +1,65 @@
+// Copyright (c) .NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+
+using nanoFramework.Runtime.Events;
+
+namespace System.Device.Usb
+{
+    internal class UsbDeviceEventListener : IEventProcessor, IEventListener
+    {
+        // Map of UsbStream objects
+        private readonly UsbStream _usbStream;
+
+        public UsbDeviceEventListener(UsbStream usbStream)
+        {
+            EventSink.AddEventProcessor(EventCategory.Usb, this);
+            EventSink.AddEventListener(EventCategory.Usb, this);
+
+            _usbStream = usbStream;
+        }
+
+        public BaseEvent ProcessEvent(uint data1, uint data2, DateTime time)
+        {
+            return new UsbDeviceEvent()
+            {
+                // Data1 is packed by PostManagedEvent, so we need to unpack the high word.
+                EventType = (UsbEventType)(data1 & 0xFF),
+
+                // Data2 - Low 8 bits are the interface index
+                InterfaceIndex = (ushort)(data2 & 0xff)
+            };
+        }
+
+        public void InitializeForEventSource()
+        {
+            // This method has to exist
+        }
+
+        public bool OnEvent(BaseEvent ev)
+        {
+            if (ev is UsbDeviceEvent myEvent)
+            {
+                switch (myEvent.EventType)
+                {
+                    case UsbEventType.DeviceDisconnected:
+
+                        // call internal event handler
+                        _usbStream.OnUsbDeviceConnectionChangedInternal(false);
+                        break;
+
+                    case UsbEventType.DeviceConnected:
+                        // call internal event handler
+                        _usbStream.OnUsbDeviceConnectionChangedInternal(true);
+                        break;
+
+                    case UsbEventType.DataAvailable:
+                        // fire event, if subscribed
+                        _usbStream.OnUsbStreamDataReceivedInternal();
+                        break;
+                }
+            }
+
+            return true;
+        }
+    }
+}

System.Device.UsbStream/UsbStream.cs

@@ -12,14 +12,47 @@ namespace System.Device.Usb
     /// </summary>
     public sealed class UsbStream : System.IO.Stream
     {
+        private static bool _streamCreated = false;
+
 #pragma warning disable IDE0052 // required at native code
         private readonly int _streamIndex;
 #pragma warning restore IDE0052 // Remove unread private members
 
+        [System.Diagnostics.DebuggerBrowsable(Diagnostics.DebuggerBrowsableState.Never)]
+        private readonly UsbDeviceEventListener _useDeviceEventListener;
+
         private bool _disposed;
         private int _writeTimeout = Timeout.Infinite;
         private int _readTimeout = Timeout.Infinite;
 
+        // default threshold is 1
+        private int _receivedBytesThreshold = 1;
+        private int _bufferSize = 256;
+
+        /// <summary>
+        /// Event occurs when the connection state of the USB device changes.
+        /// </summary>
+        public event UsbDeviceConnectionChangedEventHandler UsbDeviceConnectionChanged;
+
+        /// <summary>
+        /// Gets a value indicating whether the USB device is connected or not.
+        /// </summary>
+        public static extern bool IsConnected
+        {
+            [MethodImpl(MethodImplOptions.InternalCall)]
+            get;
+        }
+
+        /// <summary>
+        /// Gets the number of bytes of data in the receive buffer.
+        /// </summary>
+        /// <returns>The number of bytes of data in the receive buffer.</returns>
+        public extern int BytesToRead
+        {
+            [MethodImpl(MethodImplOptions.InternalCall)]
+            get;
+        }
+
         /// <inheritdoc/>
         public override bool CanRead => true;
 
@@ -37,6 +70,37 @@ public sealed class UsbStream : System.IO.Stream
         /// <exception cref="PlatformNotSupportedException">This is not support in .NET nanoFramework.</exception>
         public override long Position { get => throw new PlatformNotSupportedException(); set => throw new PlatformNotSupportedException(); }
 
+        /// <summary>
+        /// Gets or sets the size of the <see cref="UsbStream"/> input buffer.
+        /// </summary>
+        /// <value>The size of the input buffer. The default is 256.</value>
+        /// <exception cref="ArgumentOutOfRangeException">The <see cref="ReadBufferSize"/> value is less than or equal to zero.</exception>
+        /// <remarks>
+        /// <para>
+        /// - There is only one work buffer which is used for transmission and reception.
+        /// </para>
+        /// <para>
+        /// - When the <see cref="UsbStream"/> is <see cref="UsbClient.CreateUsbStream(Guid, string)"/> the driver will try to allocate the requested memory for the buffer. On failure to do so, an <see cref="OutOfMemoryException"/> exception will be throw and the <see cref="UsbClient.CreateUsbStream(Guid, string)"/> operation will fail.
+        /// </para>
+        /// </remarks>
+        public int ReadBufferSize
+        {
+            get
+            {
+                return _bufferSize;
+            }
+
+            set
+            {
+                if (value <= 0)
+                {
+                    throw new ArgumentOutOfRangeException();
+                }
+
+                _bufferSize = value;
+            }
+        }
+
         /// <summary>
         /// Gets or sets the number of milliseconds before a time-out occurs when a read operation does not finish.
         /// </summary>
@@ -54,6 +118,22 @@ public override int ReadTimeout
             }
         }
 
+        /// <summary>
+        /// Gets or sets the number of bytes in the internal input buffer before a <see cref="DataReceived"/> event occurs.
+        /// </summary>
+        /// <value>The number of bytes in the internal input buffer before a <see cref="DataReceived"/> event is fired. The default is 1.</value>
+        /// <exception cref="ArgumentOutOfRangeException">The <see cref="ReceivedBytesThreshold"/> value is less than or equal
+        /// to zero.</exception>
+        public int ReceivedBytesThreshold
+        {
+            get => _receivedBytesThreshold;
+
+            set
+            {
+                NativeReceivedBytesThreshold(value);
+            }
+        }
+
         /// <summary>
         /// Gets or sets the number of milliseconds before a time-out occurs when a write operation does not finish.
         /// </summary>
@@ -75,11 +155,20 @@ internal UsbStream(
             Guid classId,
             string name)
         {
+            // at this time there is support for a single instance of the UsbStream
+            if (_streamCreated)
+            {
+                throw new InvalidOperationException();
+            }
+
             // need to convert GUID to proper format to help processing at native end
             _streamIndex = NativeOpen(
                 $"{{{classId}}}",
                 name);
 
+            _useDeviceEventListener = new UsbDeviceEventListener(this);
+
+            _streamCreated = true;
             _disposed = false;
         }
 
@@ -97,6 +186,7 @@ protected override void Dispose(bool disposing)
                 NativeClose();
 
                 _disposed = true;
+                _streamCreated = false;
             }
         }
 
@@ -107,7 +197,8 @@ protected override void Dispose(bool disposing)
         /// <inheritdoc/>
         /// <exception cref="ObjectDisposedException">This <see cref="UsbStream"/> has been disposed.</exception>
         /// <exception cref="InvalidOperationException">If the USB device is not connected.</exception>
-        /// <remarks>Device connectivity can be checked with </remarks>
+        /// <exception cref="TimeoutException">No bytes were available to read.</exception>
+        /// <remarks>Device connectivity can be checked with <see cref="IsConnected"/>. </remarks>
         public override int Read(
             byte[] buffer,
             int offset,
@@ -122,6 +213,7 @@ public override int Read(
         /// <inheritdoc/>
         /// <exception cref="NotImplementedException"></exception>
         /// <exception cref="InvalidOperationException">If the USB device is not connected.</exception>
+        /// <exception cref="TimeoutException">No bytes were available to read.</exception>
         public override int Read(SpanByte buffer)
         {
             return Read(
@@ -143,6 +235,7 @@ public override long Seek(
         /// <inheritdoc/>
         /// <exception cref="ObjectDisposedException">This <see cref="UsbStream"/> has been disposed.</exception>
         /// <exception cref="InvalidOperationException">If the USB device is not connected.</exception>
+        /// <exception cref="TimeoutException">The operation did not complete before the time-out period ended.</exception>
         public override void Write(
             byte[] buffer,
             int offset,
@@ -163,6 +256,27 @@ private static void CheckValidTimeout(int value)
             }
         }
 
+        #region event and delegate related methods
+
+        /// <summary>
+        /// Indicates that data has been received through the <see cref="UsbClient"/> object.
+        /// </summary>
+        public event UsbStreamDataReceivedEventHandler DataReceived;
+
+        internal void OnUsbDeviceConnectionChangedInternal(bool isConnected)
+        {
+            // fire event, if subscribed
+            UsbDeviceConnectionChanged?.Invoke(this, new DeviceConnectionEventArgs(isConnected));
+        }
+
+        internal void OnUsbStreamDataReceivedInternal()
+        {
+            // fire event, if subscribed
+            DataReceived?.Invoke(this, new UsbStreamDataReceivedEventArgs());
+        }
+
+        #endregion
+
         #region Native Methods
 
         [MethodImpl(MethodImplOptions.InternalCall)]
@@ -177,6 +291,9 @@ private static void CheckValidTimeout(int value)
         [MethodImpl(MethodImplOptions.InternalCall)]
         private extern int NativeRead(byte[] buffer, int offset, int count);
 
+        [MethodImpl(MethodImplOptions.InternalCall)]
+        internal extern void NativeReceivedBytesThreshold(int value);
+
         #endregion
     }
 }

System.Device.UsbStream/UsbStreamDataReceivedEventArgs.cs

@@ -0,0 +1,15 @@
+// Copyright (c) .NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+
+namespace System.Device.Usb
+{
+    /// <summary>
+    /// Provides data for the <see cref="UsbStream.DataReceived"/> event.
+    /// </summary>
+    public class UsbStreamDataReceivedEventArgs : EventArgs
+    {
+        internal UsbStreamDataReceivedEventArgs()
+        {
+        }
+    }
+}

System.Device.UsbStream/UsbStreamDataReceivedEventHandler.cs

@@ -0,0 +1,14 @@
+// Copyright (c) .NET Foundation and Contributors
+// See LICENSE file in the project root for full license information.
+
+namespace System.Device.Usb
+{
+    /// <summary>
+    /// Represents the method that will handle the <see cref="UsbStream.DataReceived"/> event of a <see cref="UsbStream"/> object.
+    /// </summary>
+    /// <param name="sender">The sender of the event, which is the <see cref="UsbStream"/> object.</param>
+    /// <param name="e">A <see cref="UsbStreamDataReceivedEventArgs"/> object that contains the event data.</param>
+    public delegate void UsbStreamDataReceivedEventHandler(
+        object sender,
+        UsbStreamDataReceivedEventArgs e);
+}