moved readconsoleinputstream to samples folder; added readme; updated root readme.

README.md

@@ -19,6 +19,7 @@ You'll also find assorted Console tools, samples, including the following:
 * [ColorTool](https://github.com/Microsoft/Console/tree/master/tools/ColorTool) - A tool for changing the color scheme of the Windows console.
 * [EchoCon](https://github.com/Microsoft/console/tree/master/samples/ConPTY/EchoCon) - A C++ sample application that illustrates how to use the new Win32 Pseudo Console (ConPTY).
 * [MiniTerm](https://github.com/Microsoft/console/tree/master/samples/ConPTY/MiniTerm) - A C# sample terminal that illustrates how to use ConPTY.
+* [ReadConsoleInputStream](https://github.com/Microsoft/console/tree/master/samples/ReadConsoleInputStream) - A C# sample console application that shows how to use the console APIs to stream stdin while asynchronously watching for console events (buffer size, viewport size, mouse input etc.)
 
 ### Tool Build Status
 

samples/ReadConsoleInputStream/README.md

@@ -0,0 +1,16 @@
+# ReadConsoleInputStream Demo
+
+This is a demo that shows how we can have a stream-oriented view of characters from the console while also listening to console events like mouse, menu, focus, buffer/viewport resize events. This is partcularly useful when working with VT100 streams and ConPTY.
+
+This has always been tricky to do because ReadConsoleW/A doesn't allow retrieving events. Only ReadConsoleInputW/A returns events, but isn't stream-oriented. Using both doesn't work because ReadConsoleW/A flushes the input queue, meaning calls to ReadConsoleInputW/A will wait forever.
+
+I do this by deriving a new Stream class which wraps ReadConsoleInputW and accepts a provider/consumer implementation of BlockingCollection<Kernel32.INPUT_RECORD>. This allows asynchronous monitoring of console events while simultaneously streaming the character input. I also use Mark Gravell's great System.IO.Pipelines utility classes and David Hall's excellent P/Invoke wrappers  to make this demo cleaner to read; both are pulled from NuGet.
+
+**Note:**
+
+In versions of windows 10 prior to 1809, the buffer resize event only fires for enlarging the viewport, as this would cause the buffer to be enlarged too. Now it fires even when shrinking the viewport, which won't change the buffer size.
+
+NuGet packages used (GitHub links):
+
+* [Pipelines.Sockets.Unofficial](https://github.com/mgravell/Pipelines.Sockets.Unofficial)
+* [Vanara P/Invoke](https://github.com/dahall/Vanara)