/* -*- Mode: IDL; 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/. */

#include "nsISupports.idl"

interface nsIDOMWindow;
interface nsIDocShell;
interface nsIContent;

[scriptable, function, uuid(938fcb95-3d63-46be-aa72-94d08fd3b418)]
interface nsIFrameMessageListener : nsISupports
{
  /**
   * This is for JS only.
   * receiveMessage is called with one parameter, which has the following
   * properties:
   *   {
   *     target:  %the target of the message. Either an element owning
   *               the message manager, or message manager itself if no
   *               element owns it%
   *     name:    %message name%,
   *     sync:    %true or false%.
   *     json:    %structured clone of the sent message data%,
   *     json:    %same as .data, deprecated%,
   *     objects: %array of handles or null, always null if sync is false%
   *   }
   * @note objects property isn't implemented yet.
   *
   * if the message is synchronous, possible return value is sent back
   * as JSON (will be changed to use structured clones).
   *
   * When the listener is called, 'this' value is the target of the message.
   */
  void receiveMessage();
};

[scriptable, builtinclass, uuid(9be42627-a5db-456f-8de2-9097da45a8c3)]
interface nsIFrameMessageManager : nsISupports
{
  void addMessageListener(in AString aMessage, in nsIFrameMessageListener aListener);
  void removeMessageListener(in AString aMessage, in nsIFrameMessageListener aListener);
  [implicit_jscontext,optional_argc]
  void sendAsyncMessage([optional] in AString messageName, [optional] in jsval obj);
  [notxpcom] boolean markForCC();
};

[scriptable, builtinclass, uuid(28a36ac7-2868-4fa0-ae24-be957d7dce10)]
interface nsISyncMessageSender : nsIFrameMessageManager
{
  /**
   * Returns an array of JSON objects.
   */
  [implicit_jscontext,optional_argc]
  jsval sendSyncMessage([optional] in AString messageName, [optional] in jsval obj);
};

[scriptable, builtinclass, uuid(a83f4393-e3cf-44da-8867-1f9174c2c595)]
interface nsIContentFrameMessageManager : nsISyncMessageSender
{
  /**
   * The current top level window in the frame or null.
   */
  readonly attribute nsIDOMWindow content;

  /**
   * The top level docshell or null.
   */
  readonly attribute nsIDocShell docShell;

  /**
   * Print a string to stdout.
   */
  void dump(in DOMString aStr);

  /**
   * If leak detection is enabled, print a note to the leak log that this
   * process will intentionally crash.
   */
  void privateNoteIntentionalCrash();

   /**
    * Ascii base64 data to binary data and vice versa
    */
   DOMString atob(in DOMString aAsciiString);
   DOMString btoa(in DOMString aBase64Data);
};

[uuid(f0936c56-e92c-4927-a85b-e289c3d4a01c)]
interface nsIInProcessContentFrameMessageManager : nsIContentFrameMessageManager
{
  [notxpcom] nsIContent getOwnerContent();
};

[scriptable, builtinclass, uuid(09f79e8c-101b-432b-a494-02f9b5e111c0)]
interface nsITreeItemFrameMessageManager : nsIFrameMessageManager
{
  readonly attribute unsigned long childCount;
  nsITreeItemFrameMessageManager getChildAt(in unsigned long aIndex);
};

[scriptable, builtinclass, uuid(a51597f0-d669-4260-83e6-1d426a8ac802)]
interface nsIChromeFrameMessageManager : nsITreeItemFrameMessageManager
{
  /**
   * Load a script in the (remote) frame. aURL must be the absolute URL.
   * data: URLs are also supported. For example data:,dump("foo\n");
   * If aAllowDelayedLoad is true, script will be loaded when the
   * remote frame becomes available. Otherwise the script will be loaded
   * only if the frame is already available.
   */
  void loadFrameScript(in AString aURL, in boolean aAllowDelayedLoad);

  /**
   * Removes aURL from the list of scripts which support delayed load.
   */
  void removeDelayedFrameScript(in AString aURL);
};