Update readme & abstract local file creation

Author: devlead

README.md

@@ -1,2 +1,79 @@
 # OSC.Net
-.NET Standard Library for Open Spherical Camera API
+.NET Standard Library for Open Spherical Camera API 2.0
+
+## Example
+```csharp
+var cameraClient = new CameraClient();
+cameraClient.TakePicture("test.jpg");
+```
+
+## Client
+
+The library exposes `CameraClient` class which implements an `ICameraClient` interface, which has a set of extension methods on it i.e. `TakePicture()`.
+
+### Create client default IP (192.168.42.1) and Port (80)
+```csharp
+var cameraClient = new CameraClient();
+```
+
+### Create client supply IP and Port
+```csharp
+var cameraClient = new CameraClient(new IPEndPoint(IPAddress.Parse("192.168.42.1"), 80));
+```
+
+### Create client supply Uri
+```csharp
+var cameraClient = new CameraClient(new Uri("http://192.168.42.1"));
+```
+
+### HttpClientFactoryHandler
+
+All `CameraClient` constructors takes an optional `HttpClientFactoryHandler` `createClient`parameter which allows you to override how the internally used HttpClient is created.
+
+Example usage with `System.Net` `IHttpClientFactory` 
+```csharp
+var serviceProvider = new ServiceCollection().AddHttpClient().BuildServiceProvider();
+            var httpClientFactory = serviceProvider.GetService<IHttpClientFactory>();
+
+var httpClientFactory = serviceProvider.GetService<IHttpClientFactory>();
+
+var cameraClient = new CameraClient(createClient: httpClientFactory.CreateClient);
+```
+
+### CreateFileHandler
+
+All `CameraClient` constructors takes an optional `CreateFileHandler` `createFile`parameter which allows you to override how local files are created.
+
+```csharp
+var cameraClient = new CameraClient(
+    createFile: path => File.Open(path, FileMode.Create, FileAccess.Write, FileShare.None));
+```
+
+## Take Picture
+
+### Take picture and get uri to image
+
+```csharp
+var pictureUri = await client.TakePicture();
+```
+
+### Take picture and download image to supplied stream
+
+```csharp
+var imageStream = new MemoryStream();
+await client.TakePicture(imageStream);
+```
+
+### Take picture and save to supplied local path
+```csharp
+await client.TakePicture("test.jpg");
+```
+
+### useLocalFileUri
+
+All `TakePicture` methods takes an optional `useLocalFileUri` bool parameter, by default it's false. If set to true it'll use `ICameraClient.EndPoint` for construction an absolute uri to images. This is useful if using camera through proxy or firewall.
+
+## Supported cameras
+
+This library has been tested with
+* [Insta360 One X](https://www.insta360.com/product/insta360-onex/)

src/OSC.Net.Console/Program.cs

@@ -20,8 +20,8 @@ public static async Task Main(string[] args)
                 Environment.GetEnvironmentVariable("OSC.Net.Console.EndPoint"),
                 UriKind.Absolute,
                 out var endpoint)
-                ? new CameraClient(endpoint, httpClientFactory.CreateClient)
-                : new CameraClient(httpClientFactory.CreateClient);
+                ? new CameraClient(endpoint, createClient: httpClientFactory.CreateClient)
+                : new CameraClient(createClient: httpClientFactory.CreateClient);
 
 
             var currentDateTime = await client.GetDateTime();

src/OSC.Net/CameraClient.cs

@@ -1,7 +1,9 @@
 using System;
+using System.IO;
 using System.Net;
 using System.Net.Http;
 using OSC.Net.Http;
+using OSC.Net.IO;
 
 namespace OSC.Net
 {
@@ -10,7 +12,11 @@ namespace OSC.Net
     /// </summary>
     public class CameraClient : ICameraClient
     {
+        private static Stream DefaultCreateFile(string path)
+            => File.Open(path, FileMode.Create, FileAccess.Write, FileShare.None);
+
         private static HttpClient DefaultCreateClient(string name) => new HttpClient();
+
         /// <summary>
         /// The Default Camera Ip Address.
         /// </summary>
@@ -30,6 +36,7 @@ public class CameraClient : ICameraClient
         public static readonly IPEndPoint DefaultIpEndPoint = new IPEndPoint(IPAddress.Parse(DefaultIp), DefaultPort);
 
         private HttpClientFactoryHandler CreateClient { get; }
+        private CreateFileHandler CreateFile { get; }
 
         /// <inheritdoc />
         public Uri EndPoint { get; }
@@ -42,31 +49,38 @@ HttpClient ICameraClient.GetHttpClient()
             return client;
         }
 
+        /// <inheritdoc />
+        Stream ICameraClient.CreateFile(string path) => CreateFile(path);
+
         /// <summary>
         /// Initializes a new instance of the <see cref="CameraClient"/> class using <see cref="DefaultIpEndPoint"/>.
         /// </summary>
+        /// <param name="createFile">Optional handler to override local file creation.</param>
         /// <param name="createClient">Optional handler to override http client creation.</param>
-        public CameraClient(HttpClientFactoryHandler createClient = null) : this(DefaultIpEndPoint, createClient)
+        public CameraClient(CreateFileHandler createFile = null, HttpClientFactoryHandler createClient = null) : this(DefaultIpEndPoint, createFile, createClient)
         {
         }
 
         /// <summary>
         /// Initializes a new instance of the <see cref="CameraClient"/> class.
         /// </summary>
         /// <param name="ipEndPoint">The camera ip address and port.</param>
+        /// <param name="createFile">Optional handler to override local file creation.</param>
         /// <param name="createClient">Optional handler to override http client creation.</param>
-        public CameraClient(IPEndPoint ipEndPoint, HttpClientFactoryHandler createClient = null) : this(new Uri($"http://{ipEndPoint}"), createClient)
+        public CameraClient(IPEndPoint ipEndPoint, CreateFileHandler createFile = null, HttpClientFactoryHandler createClient = null) : this(new Uri($"http://{ipEndPoint}"), createFile, createClient)
         {
         }
 
         /// <summary>
         /// Initializes a new instance of the <see cref="CameraClient"/> class.
         /// </summary>
         /// <param name="endPoint">The camera http end point.</param>
+        /// <param name="createFile">Optional handler to override local file creation.</param>
         /// <param name="createClient">Optional handler to override http client creation.</param>
-        public CameraClient(Uri endPoint, HttpClientFactoryHandler createClient = null)
+        public CameraClient(Uri endPoint, CreateFileHandler createFile = null, HttpClientFactoryHandler createClient = null)
         {
             EndPoint = endPoint;
+            CreateFile = createFile ?? DefaultCreateFile;
             CreateClient = createClient ?? DefaultCreateClient;
         }
     }

src/OSC.Net/Commands.TakePicture.cs

@@ -67,7 +67,7 @@ public static async Task TakePicture(this ICameraClient client, Stream targetStr
         /// <param name="useLocalFileUri">Optional flag for if absolute uri returned from camera should be used or absolute uri created from <see cref="ICameraClient.EndPoint"/> and relative uri, useful if called through a proxy. Default value <c>false</c></param>
         public static async Task TakePicture(this ICameraClient client, string path, bool useLocalFileUri = false)
         {
-            using (var targetStream = File.Open(path, FileMode.Create, FileAccess.Write, FileShare.None))
+            using (var targetStream = client.CreateFile(path))
             {
                 await client.TakePicture(targetStream, useLocalFileUri);
             }

src/OSC.Net/ICameraClient.cs

@@ -1,4 +1,5 @@
 using System;
+using System.IO;
 using System.Net.Http;
 
 namespace OSC.Net
@@ -18,5 +19,12 @@ public interface ICameraClient
         /// </summary>
         /// <returns></returns>
         HttpClient GetHttpClient();
+
+        /// <summary>
+        /// Creates a new file for given path.
+        /// </summary>
+        /// <param name="path">Local path.</param>
+        /// <returns><see cref="Stream"/> to file.</returns>
+        Stream CreateFile(string path);
     }
 }

src/OSC.Net/IO/CreateFileHandler.cs

@@ -0,0 +1,11 @@
+using System.IO;
+
+namespace OSC.Net.IO
+{
+    /// <summary>
+    /// Handler used to override file creation.
+    /// </summary>
+    /// <param name="path">Local file path.</param>
+    /// <returns>Stream to file.</returns>
+    public delegate Stream CreateFileHandler(string path);
+}