gecko/dom/ipc/PBrowser.ipdl

/* -*- Mode: C++; c-basic-offset: 4; indent-tabs-mode: nil; tab-width: 8 -*- */
/* vim: set sw=4 ts=8 et tw=80 ft=cpp : */

/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is Mozilla Content App.
 *
 * The Initial Developer of the Original Code is
 *   The Mozilla Foundation.
 * Portions created by the Initial Developer are Copyright (C) 2009
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

include protocol PContent;
include protocol PContentDialog;
include protocol PDocumentRenderer;
include protocol PContentPermissionRequest;
include protocol PRenderFrame;
include protocol POfflineCacheUpdate;

include "TabMessageUtils.h";
include "gfxMatrix.h";
include "mozilla/net/NeckoMessageUtils.h";
include "IPC/nsGUIEventIPC.h";

using gfxMatrix;
using IPC::URI;
using nsCompositionEvent;
using nsIMEUpdatePreference;
using nsIntSize;
using nsQueryContentEvent;
using nsRect;
using nsSelectionEvent;
using nsTextEvent;
using RemoteDOMEvent;

namespace mozilla {
namespace dom {

rpc protocol PBrowser
{
    manager PContent;

    manages PContentDialog;
    manages PDocumentRenderer;
    manages PContentPermissionRequest;
    manages PRenderFrame;
    manages POfflineCacheUpdate;

both:
    AsyncMessage(nsString aMessage, nsString aJSON);

parent:
    /**
     * When child sends this message, parent should move focus to
     * the next or previous focusable element.
     */
    MoveFocus(bool forward);

    Event(RemoteDOMEvent aEvent);

    rpc CreateWindow() returns (PBrowser window);

    sync SyncMessage(nsString aMessage, nsString aJSON)
      returns (nsString[] retval);

    /**
     * The IME sequence number (seqno) parameter is used to make sure
     * that a notification is discarded if it arrives at the chrome process
     * too late. If the notification is late and we accept it, we will have
     * an out-of-date view of the content process, which means events that we
     * dispatch based on this out-of-date view will be wrong also.
     * (see Bug 599550 and Bug 591047 comments 44, 50, and 54)
     *
     * Chrome increments seqno and includes it in each IME event sent to
     * content, and content sends its current seqno back to chrome with each
     * notification. A notification is up-to-date only if the content
     * seqno is the same as the current chrome seqno, meaning no additional
     * event was sent to content before the notification was received
     *
     * On blur, chrome returns the current seqno to content, and content
     * uses it to discard subsequent events until the content seqno and
     * chrome seqno-on-blur match again. These events, meant for the blurred
     * textfield, are discarded to prevent events going to the wrong target
     */

    /**
     * Notifies chrome that there is a focus change involving an editable
     * object (input, textarea, document, contentEditable. etc.)
     *
     *  focus        PR_TRUE if editable object is receiving focus
     *               PR_FALSE if losing focus
     *  preference   Native widget preference for IME updates
     *  seqno        Current seqno value on the chrome side
     */
    sync NotifyIMEFocus(PRBool focus)
      returns (nsIMEUpdatePreference preference, PRUint32 seqno);

    /**
     * Notifies chrome that there has been a change in text content
     * One call can encompass both a delete and an insert operation
     * Only called when NotifyIMEFocus returns PR_TRUE for mWantUpdates
     *
     *  offset       Starting offset of the change
     *  end          Ending offset of the range deleted
     *  newEnd       New ending offset after insertion
     *
     *  for insertion, offset == end
     *  for deletion, offset == newEnd
     */
    NotifyIMETextChange(PRUint32 offset, PRUint32 end, PRUint32 newEnd);

    /**
     * Notifies chrome that there has been a change in selection
     * Only called when NotifyIMEFocus returns PR_TRUE for mWantUpdates
     *
     *  seqno        Current seqno value on the content side
     *  anchor       Offset where the selection started
     *  focus        Offset where the caret is
     */
    NotifyIMESelection(PRUint32 seqno, PRUint32 anchor, PRUint32 focus);

    /**
     * Notifies chrome to refresh its text cache 
     * Only called when NotifyIMEFocus returns PR_TRUE for mWantHints
     *
     *  text         The entire content of the text field
     */
    NotifyIMETextHint(nsString text);

    /**
     * Instructs chrome to end any pending composition
     *
     *  cancel       PR_TRUE if composition should be cancelled
     *  composition  Text to commit before ending the composition
     *
     *  if cancel is PR_TRUE,
     *    widget should return empty string for composition
     *  if cancel is PR_FALSE,
     *    widget should return the current composition text
     */
    sync EndIMEComposition(PRBool cancel) returns (nsString composition);

    sync GetIMEEnabled() returns (PRUint32 value);

    SetInputMode(PRUint32 value, nsString type, nsString actionHint, PRUint32 reason);

    sync GetIMEOpenState() returns (PRBool value);

    SetIMEOpenState(PRBool value);

    /**
     * Gets the DPI of the screen corresponding to this browser.
     */
    sync GetDPI() returns (float value);

    PContentPermissionRequest(nsCString aType, URI uri);

    PContentDialog(PRUint32 aType, nsCString aName, nsCString aFeatures,
                   PRInt32[] aIntParams, nsString[] aStringParams);

    /**
     * Create a layout frame (encapsulating a remote layer tree) for
     * the page that is currently loaded in the <browser>.
     */
    async PRenderFrame();

    /** 
     * Starts an offline application cache update.
     * @param manifestURI
     *   URI of the manifest to fetch, the application cache group ID
     * @param documentURI
     *   URI of the document that referred the manifest
     * @param clientID
     *   The group cache version identifier to use
     * @param stickDocument
     *   True if the update was initiated by a document load that referred
     *   a manifest.
     *   False if the update was initiated by applicationCache.update() call.
     *
     *   Tells the update to carry the documentURI to a potential separate 
     *   update of implicit (master) items.
     *
     *   Why this argument? If the document was not found in an offline cache 
     *   before load and refers a manifest and this manifest itself has not 
     *   been changed since the last fetch, we will not do the application 
     *   cache group update. But we must cache the document (identified by the
     *   documentURI). This argument will ensure that a previously uncached 
     *   document will get cached and that we don't re-cache a document that 
     *   has already been cached (stickDocument=false).
     */
    POfflineCacheUpdate(URI manifestURI, URI documentURI, nsCString clientID,
                        bool stickDocument);

    __delete__();

child:
    /**
     * Notify the remote browser that it has been Show()n on this
     * side, with the given |visibleRect|.  This message is expected
     * to trigger creation of the remote browser's "widget".
     *
     * |Show()| and |Move()| take IntSizes rather than Rects because
     * content processes always render to a virtual <0, 0> top-left
     * point.
     */
    Show(nsIntSize size);

    LoadURL(nsCString uri);

    Move(nsIntSize size);

    /**
     * Sending an activate message moves focus to the child.
     */
    Activate();

    /**
     * @see nsIDOMWindowUtils sendMouseEvent.
     */
    MouseEvent(nsString aType,
               float aX,
               float aY,
               PRInt32 aButton,
               PRInt32 aClickCount,
               PRInt32 aModifiers,
               bool aIgnoreRootScrollFrame);

    /**
     * @see nsIDOMWindowUtils sendKeyEvent.
     */
    KeyEvent(nsString aType,
             PRInt32 aKeyCode,
             PRInt32 aCharCode,
             PRInt32 aModifiers,
             bool aPreventDefault);

    CompositionEvent(nsCompositionEvent event);

    TextEvent(nsTextEvent event);

    SelectionEvent(nsSelectionEvent event);

    /**
     * Activate event forwarding from client to parent.
     */
    ActivateFrameEvent(nsString aType, bool capture);

    LoadRemoteScript(nsString aURL);

    /**
     * Create a asynchronous request to render whatever document is
     * loaded in the child when this message arrives.  When the
     * request finishes, PDocumentRenderer:__delete__ is sent back to
     * this side to notify completion.
     *
     * |documentRect| is the area of the remote document to draw,
     * transformed by |transform|.  The rendered area will have the
     * default background color |bgcolor|.  |renderFlags| are the
     * nsIPresShell::RenderDocument() flags to use on the remote side,
     * and if true, |flushLayout| will do just that before rendering
     * the document.  The rendered image will be of size |renderSize|.
     */
    PDocumentRenderer(nsRect documentRect, gfxMatrix transform,
                      nsString bgcolor,
                      PRUint32 renderFlags, bool flushLayout,
                      nsIntSize renderSize);

    /**
     * Sent by the chrome process when it no longer wants this remote
     * <browser>.  The child side cleans up in response, then
     * finalizing its death by sending back __delete__() to the
     * parent.
     */
    Destroy();

/*
 * FIXME: write protocol!

state LIVE:
    send LoadURL goto LIVE;
//etc.
    send Destroy goto DYING;

state DYING:
    discard send blah;
// etc.
    recv __delete__;
 */
};

}
}