// 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 < 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 < 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();
|
}
|
}
|
