Improve ResourceHandler documentation, add a minor simplification and…

… update the FlashResourceHandler example to demo how simple it is to use a ResourceHandler when extending FlashResourceHandler

CefSharp.Example/FlashResourceHandler.cs

@@ -10,9 +10,6 @@ namespace CefSharp.Example
 {
     public class FlashResourceHandler : ResourceHandler
     {
-        private MemoryStream stream;
-        private string mime;
-
         public override bool ProcessRequestAsync(IRequest request, ICallback callback)
         {
             Task.Run(() =>
@@ -25,31 +22,26 @@ public override bool ProcessRequestAsync(IRequest request, ICallback callback)
 
                     // Get the stream associated with the response.
                     var receiveStream = httpWebResponse.GetResponseStream();
-                    mime = httpWebResponse.ContentType;
+                    var mime = httpWebResponse.ContentType;
 
-                    stream = new MemoryStream();
+                    var stream = new MemoryStream();
                     receiveStream.CopyTo(stream);
                     httpWebResponse.Close();
+
+                    //Reset the stream position to 0 so the stream can be copied into the underlying unmanaged buffer
+                    stream.Position = 0;
+
+                    //Populate the response values - No longer need to implement GetResponseHeaders (unless you need to perform a redirect)
+                    ResponseLength = stream.Length;
+                    MimeType = mime;
+                    StatusCode = (int)HttpStatusCode.OK;
+                    Stream = stream;                    
                
                     callback.Continue();
                 }
             });
 
             return true;
         }
-
-        public override Stream GetResponse(IResponse response, out long responseLength, out string redirectUrl)
-        {
-            responseLength = stream.Length;
-            redirectUrl = null;
-
-            response.MimeType = mime;
-            response.StatusCode = (int)HttpStatusCode.OK;
-
-            //Reset the stream position to 0 so the stream can be copied into the underlying unmanaged buffer
-            stream.Position = 0;
-
-            return stream;
-        }
     }
 }

CefSharp/ResourceHandler.cs

@@ -11,7 +11,10 @@
 namespace CefSharp
 {
     /// <summary>
-    /// Class ResourceHandler.
+    /// Default implementation of <see cref="IResourceHandler"/>. This latest implementation provides some simplification, at
+    /// a minimum you only need to override ProcessRequestAsync. See the project source on GitHub for working examples.
+    /// used to implement a custom request handler interface. The methods of this class will always be called on the IO thread. 
+    /// Static helper methods are included like FromStream and FromString that make dealing with fixed resources easy.
     /// </summary>
     public class ResourceHandler : IResourceHandler
     {
@@ -28,27 +31,31 @@ public class ResourceHandler : IResourceHandler
         /// <summary>
         /// Gets or sets the Mime Type.
         /// </summary>
-        /// <value>The Mime Type.</value>
         public string MimeType { get; set; }
 
         /// <summary>
         /// Gets or sets the resource stream.
         /// </summary>
-        /// <value>The stream.</value>
         public Stream Stream { get; set; }
 
         /// <summary>
         /// Gets or sets the http status code.
         /// </summary>
-        /// <value>The http status code.</value>
         public int StatusCode { get; set; }
 
         /// <summary>
         /// Gets or sets the status text.
         /// </summary>
-        /// <value>The status text.</value>
         public string StatusText { get; set; }
 
+        /// <summary>
+        /// Gets or sets ResponseLength, when you know the size of your
+        /// Stream (Response) set this property. This is optional.
+        /// If you use a MemoryStream and don't provide a value
+        /// here then it will be cast and it's size used
+        /// </summary>
+        public long? ResponseLength { get; set; }
+
         /// <summary>
         /// Gets or sets the headers.
         /// </summary>
@@ -85,13 +92,37 @@ private ResourceHandler(string mimeType, ResourceHandlerType type)
             Type = type;
         }
 
+        /// <summary>
+        /// Begin processing the request. If you have the data in memory you can execute the callback
+        /// immediately and return true. For Async processing you would typically spawn a Task to perform processing,
+        /// then return true. When the processing is complete execute callback.Continue(); In your processing Task, simply set
+        /// the StatusCode, StatusText, MimeType, ResponseLength and Stream
+        /// </summary>
+        /// <param name="request">The request object.</param>
+        /// <param name="callback">The callback used to Continue or Cancel the request (async).</param>
+        /// <returns>To handle the request return true and call
+        /// <see cref="ICallback.Continue"/> once the response header information is available
+        /// <see cref="ICallback.Continue"/> can also be called from inside this method if
+        /// header information is available immediately).
+        /// To cancel the request return false.</returns>
         public virtual bool ProcessRequestAsync(IRequest request, ICallback callback)
         {
             callback.Continue();
 
             return true;
         }
 
+        /// <summary>
+        /// Populate the response stream, response length. When this method is called
+        /// the response should be fully populated with data.
+        /// It is possible to redirect to another url at this point in time.
+        /// NOTE: It's no longer manditory to implement this method, you can simply populate the
+        /// properties of this instance and they will be set by the default implementation. 
+        /// </summary>
+        /// <param name="response">The response object used to set Headers, StatusCode, etc</param>
+        /// <param name="responseLength">length of the response</param>
+        /// <param name="redirectUrl">If set the request will be redirect to specified Url</param>
+        /// <returns>The response stream</returns>
         public virtual Stream GetResponse(IResponse response, out long responseLength, out string redirectUrl)
         {
             redirectUrl = null;
@@ -102,15 +133,26 @@ public virtual Stream GetResponse(IResponse response, out long responseLength, o
             response.StatusText = StatusText;
             response.ResponseHeaders = Headers;
 
-            var memoryStream = Stream as MemoryStream;
-            if (memoryStream != null)
+            if(ResponseLength.HasValue)
             {
-                responseLength = memoryStream.Length;
+                responseLength = ResponseLength.Value;
+            }
+            else
+            { 
+                //If no ResponseLength provided then attempt to infer the length
+                var memoryStream = Stream as MemoryStream;
+                if (memoryStream != null)
+                {
+                    responseLength = memoryStream.Length;
+                }
             }
 
             return Stream;
         }
 
+        /// <summary>
+        /// Called if the request is cancelled
+        /// </summary>
         public virtual void Cancel()
         {