using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Net;

namespace Nuclex.Networking.Gallery3.Requests {

  /// <summary>Request that can be sent to a server</summary>
  /// <remarks>
  ///   <para>
  ///     The destination of the request and any authentication options are
  ///     set at construction time by the factory for the request. This
  ///     interface merely services to customize the request for its purpose.
  ///   </para>
  ///   <para>
  ///     By using an interface to construct requests, it is easy to mock
  ///     any request being constructed by the Gallery 3 connector in order
  ///     to verify the code in unit tests without relying on a server.
  ///   </para>
  /// </remarks>
  public interface IRequest {

    /// <summary>HTTP request method</summary>
    /// <remarks>
    ///   Can be "GET", "POST", "PUT" or "DELETE". Not all server support
    ///   the "PUT" and "DELETE" methods, so these methods are passed to
    ///   Gallery 3 as a "POST" request with a custom header:
    ///   "X-Gallery-Request-Method".
    /// </remarks>
    string Method { get; set; }

    /// <summary>The type/format of the content in a "POST" request</summary>
    /// <remarks>
    ///   Should be "application/x-www-form-urlencoded" for any request.
    /// </remarks>
    string ContentType { get; set; }

    /// <summary>Adds a custom header field to the request</summary>
    /// <param name="name">Name of the header that will be added</param>
    /// <param name="value">Value that will be assigned to the header field</param>
    void AddHeader(string name, string value);

    /// <summary>Attaches content to a POST request</summary>
    /// <param name="data">Data that will be attached to the request as content</param>
    void AttachContent(byte[] data);

    /// <summary>Sends the request to the server and returns the response</summary>
    /// <returns>A JSON reader through which the response can be read</returns>
    ResponseType GetJsonResponse<ResponseType>();

  }

} // namespace Nuclex.Networking.Gallery3.Requests