/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 * The nsIEventSource interface is the interface for server-sent
 * DOM events as described in
 * http://dev.w3.org/html5/eventsource/#eventsource
 *
 */

#include "nsISupports.idl"

interface nsIDOMEventListener;
interface nsIPrincipal;
interface nsIScriptContext;
interface nsPIDOMWindow;

[scriptable, uuid(a3d3181e-47c1-4f2e-b2c7-94775a86f5c5)]
interface nsIEventSource : nsISupports
{
  readonly attribute DOMString url;

  // ready state
  const unsigned short CONNECTING = 0;
  const unsigned short OPEN = 1;
  const unsigned short CLOSED = 2;
  readonly attribute long readyState;

  // if true then cross-site Access-Control requests are made using credentials
  // such as cookies and authorization headers. Never affects same-site
  // requests.
  readonly attribute boolean withCredentials;

  // event handler attributes
  attribute nsIDOMEventListener onopen;
  attribute nsIDOMEventListener onmessage;
  attribute nsIDOMEventListener onerror;

  /**
   * Close the connection, if any, and set the readyState attribute to CLOSED.
   * If the connection is already closed, the method does nothing.
   */
  void close();

  /**
   * Initialize the object for use from C++ code with the principal, script
   * context, and owner window that should be used.
   *
   * @param principal The principal to use for the request. This must not be
   *                  null.
   * @param scriptContext The script context to use for the request. May be
   *                      null.
   * @param ownerWindow The associated window for the request. May be null.
   * @param url The EventSource's url. This must not be empty.
   * @param withCredentials When set to true attempts to make cross-site
   *                        Access-Control requests with credentials such as
   *                        cookies and authorization headers. Never affects
   *                        same-site requests.
   */
  [noscript] void init(in nsIPrincipal principal,
                       in nsIScriptContext scriptContext,
                       in nsPIDOMWindow ownerWindow,
                       in DOMString url,
                       in boolean withCredentials);
};