gecko-dev/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 PDocumentRendererShmem;
include protocol PDocumentRendererNativeID;
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 nsIntSize;
using nsCompositionEvent;
using nsTextEvent;
using nsQueryContentEvent;
using nsSelectionEvent;
using RemoteDOMEvent;
using nsIMEUpdatePreference;

namespace mozilla {
namespace dom {

rpc protocol PBrowser
{
    manager PContent;

    manages PContentDialog;
    manages PDocumentRenderer;
    manages PDocumentRendererShmem;
    manages PDocumentRendererNativeID;
    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);

    SetIMEEnabled(PRUint32 value);

    sync GetIMEOpenState() returns (PRBool value);

    SetIMEOpenState(PRBool 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);

    PDocumentRenderer(PRInt32 x, PRInt32 y, PRInt32 w, PRInt32 h, nsString bgcolor, PRUint32 flags, bool flush);

    // @param matrix the transformation matrix the context we're going to draw into should have.
    PDocumentRendererShmem(PRInt32 x, PRInt32 y, PRInt32 w, PRInt32 h, nsString bgcolor, PRUint32 flags, bool flush,
                           gfxMatrix matrix, Shmem buf);

    // @param matrix the transformation matrix the context we're going to draw into should have.
    PDocumentRendererNativeID(PRInt32 x, PRInt32 y, PRInt32 w, PRInt32 h, nsString bgcolor, PRUint32 flags, bool flush,
                              gfxMatrix matrix, PRUint32 nativeID);

    /**
     * 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__;
 */
};

}
}