// Copyright © 2014 The CefSharp Authors. All rights reserved.
//
// Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

using System;
using System.IO;
using CefSharp.Callback;

namespace CefSharp
{
    /// <summary>
    /// Class used to implement a custom resource handler. The methods of this class will always be called on the CEF IO thread.
    /// Blocking the CEF IO thread will adversely affect browser performance. We suggest you execute your code in a Task (or similar).
    /// To implement async handling, spawn a new Task (or similar), keep a reference to the callback. When you have a 
    /// fully populated stream, execute the callback. Once the callback Executes, GetResponseHeaders will be called where you
    /// can modify the response including headers, or even redirect to a new Url. Set your responseLength and headers
    /// Populate the dataOut stream in ReadResponse. For those looking for a sample implementation or upgrading from 
    /// a previous version <see cref="ResourceHandler"/>. For those upgrading, inherit from ResourceHandler instead of IResourceHandler
    /// add the override keywoard to existing methods e.g. ProcessRequestAsync.
    /// </summary>
    public interface IResourceHandler : IDisposable
    {
        /// <summary>
        /// Open the response stream.
        /// - To handle the request immediately set <paramref name="handleRequest"/> to true and return true.
        /// - To decide at a later time set <paramref name="handleRequest"/> to false, return true, and execute <paramref name="callback"/>
        /// to continue or cancel the request.
        /// - To cancel the request immediately set <paramref name="handleRequest"/> to true and return false.
        /// This method will be called in sequence but not from a dedicated thread.
        /// For backwards compatibility set <paramref name="handleRequest"/> to false and return false and the <see cref="ProcessRequest(IRequest, ICallback)"/> method
        /// will be called.
        /// </summary>
        /// <param name="request">request </param>
        /// <param name="handleRequest">see main summary</param>
        /// <param name="callback">callback </param>
        /// <returns>see main summary</returns>
        bool Open(IRequest request, out bool handleRequest, ICallback callback);

        /// <summary>
        /// Begin processing the request.  
        /// </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>
        [Obsolete("This method is deprecated and will be removed in the next version. Use Open instead.")]
        bool ProcessRequest(IRequest request, ICallback callback);

        /// <summary>
        /// Retrieve response header information. If the response length is not known
        /// set <paramref name="responseLength"/> to -1 and ReadResponse() will be called until it
        /// returns false. If the response length is known set <paramref name="responseLength"/>
        /// to a positive value and ReadResponse() will be called until it returns
        /// false or the specified number of bytes have been read.
        /// 
        /// It is also possible to set <paramref name="response"/> to a redirect http status code
        /// and pass the new URL via a Location header. Likewise with <paramref name="redirectUrl"/> it
        /// is valid to set a relative or fully qualified URL as the Location header
        /// value. If an error occured while setting up the request you can call
        /// <see cref="IResponse.ErrorCode"/> on <paramref name="response"/> to indicate the error condition.
        /// </summary>
        /// <param name="response">Use the response object to set the mime type, http status code and other optional header values.</param>
        /// <param name="responseLength">If the response length is not known set responseLength to -1</param>
        /// <param name="redirectUrl">To redirect the request to a new URL set this to the new URL. Can be either a relative or fully qualified URL.</param>
        void GetResponseHeaders(IResponse response, out long responseLength, out string redirectUrl);

        /// <summary>
        /// Skip response data when requested by a Range header.
        /// Skip over and discard bytesToSkip bytes of response data.
        /// - If data is available immediately set bytesSkipped to the number of of bytes skipped and return true.
        /// - To read the data at a later time set bytesSkipped to 0, return true and execute callback when the data is available.
        /// - To indicate failure set bytesSkipped to &lt; 0 (e.g. -2 for ERR_FAILED) and return false.
        /// This method will be called in sequence but not from a dedicated thread.
        /// </summary>
        /// <param name="bytesToSkip">number of bytes to be skipped</param>
        /// <param name="bytesSkipped">
        /// If data is available immediately set bytesSkipped to the number of of bytes skipped and return true.
        /// To read the data at a later time set bytesSkipped to 0, return true and execute callback when the data is available.
        /// </param>
        /// <param name="callback">To read the data at a later time set bytesSkipped to 0,
        /// return true and execute callback when the data is available.</param>
        /// <returns>See summary</returns>
        bool Skip(Int64 bytesToSkip, out Int64 bytesSkipped, IResourceSkipCallback callback);

        /// <summary>
        /// Read response data. If data is available immediately copy up to
        /// dataOut.Length bytes into dataOut, set bytesRead to the number of
        /// bytes copied, and return true. To read the data at a later time keep a
        /// pointer to dataOut, set bytesRead to 0, return true and execute
        /// callback when the data is available (dataOut will remain valid until
        /// the callback is executed). To indicate response completion set bytesRead
        /// to 0 and return false. To indicate failure set bytesRead to &lt; 0 (e.g. -2
        /// for ERR_FAILED) and return false. This method will be called in sequence
        /// but not from a dedicated thread.
        /// 
        /// For backwards compatibility set bytesRead to -1 and return false and the ReadResponse method will be called.
        /// </summary>
        /// <param name="dataOut">If data is available immediately copy up to <see cref="Stream.Length"/> bytes into dataOut.</param>
        /// <param name="bytesRead">To indicate response completion set bytesRead to 0 and return false.</param>
        /// <param name="callback">set <paramref name="bytesRead"/> to 0, return true and execute callback when the data is available
        /// (dataOut will remain valid until the callback is executed). If you have no need
        /// of the callback then Dispose of it immeduately.</param>
        /// <returns>return true or false depending on the criteria, see summary.</returns>
        bool Read(Stream dataOut, out int bytesRead, IResourceReadCallback callback);

        /// <summary>
        /// Read response data. If data is available immediately copy to
        /// dataOut, set bytesRead to the number of bytes copied, and return true.
        /// To read the data at a later time set bytesRead to 0, return true and call ICallback.Continue() when the
        /// data is available. To indicate response completion return false.
        /// </summary>
        /// <param name="dataOut">Stream to write to</param>
        /// <param name="bytesRead">Number of bytes copied to the stream</param>
        /// <param name="callback">The callback used to Continue or Cancel the request (async).</param>
        /// <returns>If data is available immediately copy to dataOut, set bytesRead to the number of bytes copied,
        /// and return true.To indicate response completion return false.</returns>
        /// <remarks>Depending on this size of your response this method may be called multiple times</remarks>
        [Obsolete("This method is deprecated and will be removed in the next version. Use Skip and Read instead.")]
        bool ReadResponse(Stream dataOut, out int bytesRead, ICallback callback);

        /// <summary>
        /// Request processing has been canceled.
        /// </summary>
        void Cancel();
    }
}