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

/* 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 protocol PBlob;
include protocol PColorPicker;
include protocol PContent;
include protocol PContentBridge;
include protocol PDocAccessible;
include protocol PDocumentRenderer;
include protocol PDatePicker;
include protocol PFilePicker;
include protocol PIndexedDBPermissionRequest;
include protocol PRenderFrame;
include protocol PTimePicker;
include protocol PPluginWidget;
include DOMTypes;
include JavaScriptTypes;
include URIParams;
include BrowserConfiguration;


using class IPC::Principal from "mozilla/dom/PermissionMessageUtils.h";
using class mozilla::gfx::Matrix from "mozilla/gfx/Matrix.h";
using struct gfxSize from "gfxPoint.h";
using CSSRect from "Units.h";
using CSSSize from "Units.h";
using mozilla::LayoutDeviceIntRect from "Units.h";
using mozilla::LayoutDeviceIntPoint from "Units.h";
using mozilla::ScreenIntPoint from "Units.h";
using ScreenIntSize from "Units.h";
using struct mozilla::layers::FrameMetrics from "FrameMetrics.h";
using struct mozilla::layers::ScrollableLayerGuid from "FrameMetrics.h";
using struct mozilla::layers::ZoomConstraints from "FrameMetrics.h";
using mozilla::layers::MaybeZoomConstraints from "FrameMetrics.h";
using FrameMetrics::ViewID from "FrameMetrics.h";
using struct mozilla::void_t from "ipc/IPCMessageUtils.h";
using mozilla::WindowsHandle from "ipc/IPCMessageUtils.h";
using nscolor from "nsColor.h";
using class mozilla::WidgetCompositionEvent from "ipc/nsGUIEventIPC.h";
using struct mozilla::widget::IMENotification from "nsIWidget.h";
using struct nsIMEUpdatePreference from "nsIWidget.h";
using mozilla::gfx::IntSize from "mozilla/gfx/Point.h";
using mozilla::gfx::IntPoint from "mozilla/gfx/Point.h";
using mozilla::gfx::IntRect from "mozilla/gfx/Rect.h";
using class mozilla::ContentCache from "ipc/nsGUIEventIPC.h";
using class mozilla::WidgetKeyboardEvent from "ipc/nsGUIEventIPC.h";
using class mozilla::WidgetMouseEvent from "ipc/nsGUIEventIPC.h";
using class mozilla::WidgetWheelEvent from "ipc/nsGUIEventIPC.h";
using class mozilla::WidgetDragEvent from "ipc/nsGUIEventIPC.h";
using struct nsRect from "nsRect.h";
using class mozilla::WidgetSelectionEvent from "ipc/nsGUIEventIPC.h";
using class mozilla::WidgetTouchEvent from "ipc/nsGUIEventIPC.h";
using struct mozilla::dom::RemoteDOMEvent from "mozilla/dom/TabMessageUtils.h";
using mozilla::dom::ScreenOrientationInternal from "mozilla/dom/ScreenOrientation.h";
using struct mozilla::layers::TextureFactoryIdentifier from "mozilla/layers/CompositorTypes.h";
using mozilla::CSSPoint from "Units.h";
using mozilla::CSSToScreenScale from "Units.h";
using mozilla::CommandInt from "mozilla/EventForwards.h";
using mozilla::Modifiers from "mozilla/EventForwards.h";
using mozilla::layers::GeckoContentController::APZStateChange from "mozilla/layers/GeckoContentController.h";
using mozilla::WritingMode from "mozilla/WritingModes.h";
using mozilla::layers::AsyncDragMetrics from "mozilla/layers/AsyncDragMetrics.h";
using mozilla::layers::TouchBehaviorFlags from "mozilla/layers/APZUtils.h";
using nsIWidget::TouchPointerState from "nsIWidget.h";
using struct LookAndFeelInt from "mozilla/widget/WidgetMessageUtils.h";
using class mozilla::dom::ipc::StructuredCloneData from "ipc/IPCMessageUtils.h";
using mozilla::EventMessage from "mozilla/EventForwards.h";
using nsEventStatus from "mozilla/EventForwards.h";
using nsSizeMode from "nsIWidgetListener.h";

namespace mozilla {
namespace dom {

struct NativeKeyBinding
{
  CommandInt[] singleLineCommands;
  CommandInt[] multiLineCommands;
  CommandInt[] richTextCommands;
};

union MaybeNativeKeyBinding
{
  NativeKeyBinding;
  void_t;
};

struct ShowInfo
{
  nsString name;
  bool fullscreenAllowed;
  bool isPrivate;
  bool fakeShowInfo;
  float dpi;
  double defaultScale;
};

prio(normal upto urgent) sync protocol PBrowser
{
    manager PContent or PContentBridge;

    manages PColorPicker;
    manages PDocAccessible;
    manages PDocumentRenderer;
    manages PFilePicker;
    manages PDatePicker;
    manages PTimePicker;
    manages PIndexedDBPermissionRequest;
    manages PRenderFrame;
    manages PPluginWidget;

both:
    AsyncMessage(nsString aMessage, ClonedMessageData aData, CpowEntry[] aCpows,
                 Principal aPrincipal);

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

parent:
    /**
     * Tell the parent process a new accessible document has been created.
     * aParentDoc is the accessible document it was created in if any, and
     * aParentAcc is the id of the accessible in that document the new document
     * is a child of.
     */
    PDocAccessible(nullable PDocAccessible aParentDoc, uint64_t aParentAcc);

    /*
     * Creates a new remoted nsIWidget connection for windowed plugins
     * in e10s mode. This is always initiated from the child in response
     * to windowed plugin creation.
     */
    sync PPluginWidget();

    /**
     * Return native data of root widget
     */
    sync GetWidgetNativeData() returns (WindowsHandle value);

    /**
     * Sends an NS_NATIVE_CHILD_OF_SHAREABLE_WINDOW to be adopted by the
     * widget's shareable window on the chrome side. Only used on Windows.
     */
    async SetNativeChildOfShareableWindow(uintptr_t childWindow);

    /**
     * When content moves focus from a native plugin window that's a child
     * of the native browser window we need to move native focus to the
     * browser. Otherwise the plugin window will never relinquish focus.
     */
    sync DispatchFocusToTopLevelWindow();

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

    Event(RemoteDOMEvent aEvent);

    sync SyncMessage(nsString aMessage, ClonedMessageData aData,
                     CpowEntry[] aCpows, Principal aPrincipal)
      returns (StructuredCloneData[] retval);

    prio(high) sync RpcMessage(nsString aMessage, ClonedMessageData aData,
                               CpowEntry[] aCpows, Principal aPrincipal)
      returns (StructuredCloneData[] retval);

    /**
     * Notifies chrome that there is a focus change involving an editable
     * object (input, textarea, document, contentEditable. etc.)
     *
     *  contentCache Cache of content
     *  notification Whole data of the notification
     *  preference   Native widget preference for IME updates
     */
    prio(urgent) sync NotifyIMEFocus(ContentCache contentCache,
                                     IMENotification notification)
      returns (nsIMEUpdatePreference preference);

    /**
     * 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
     *
     *  contentCache Cache of content
     *  notification Whole data of the notification
     */
    prio(urgent) async NotifyIMETextChange(ContentCache contentCache,
                                           IMENotification notification);

    /**
     * Notifies chrome that there is a IME compostion rect updated
     *
     *  contentCache Cache of content
     */
    prio(urgent) async NotifyIMECompositionUpdate(ContentCache contentCache,
                                                  IMENotification notification);

    /**
     * Notifies chrome that there has been a change in selection
     * Only called when NotifyIMEFocus returns PR_TRUE for mWantUpdates
     *
     *  contentCache Cache of content
     *  notification Whole data of the notification
     */
    prio(urgent) async NotifyIMESelection(ContentCache contentCache,
                                          IMENotification notification);

    /**
     * Notifies chrome of updating its content cache.
     * This is useful if content is modified but we don't need to notify IME.
     *
     *  contentCache Cache of content
     */
    prio(urgent) async UpdateContentCache(ContentCache contentCache);

    /**
     * Notifies IME of mouse button event on a character in focused editor.
     *
     * Returns true if the mouse button event is consumd by IME.
     */
    prio(urgent) sync NotifyIMEMouseButtonEvent(IMENotification notification)
      returns (bool consumedByIME);

    /**
     * Notifies chrome to position change
     *
     *  contentCache Cache of content
     */
    prio(urgent) async NotifyIMEPositionChange(ContentCache contentCache,
                                               IMENotification notification);

    /**
     * Requests chrome to commit or cancel composition of IME.
     *
     *  cancel                Set true if composition should be cancelled.
     *
     *  isCommitted           Returns true if the request causes composition
     *                        being committed synchronously.
     *  committedString       Returns committed string.  The may be non-empty
     *                        string even if cancel is true because IME may
     *                        try to restore selected string which was
     *                        replaced with the composition.
     */
    prio(urgent) sync RequestIMEToCommitComposition(bool cancel)
                        returns (bool isCommitted, nsString committedString);

    /**
     * OnEventNeedingAckHandled() is called after a child process dispatches a
     * composition event or a selection event which is sent from the parent
     * process.
     *
     * message      The message value of the handled event.
     */
    prio(urgent) async OnEventNeedingAckHandled(EventMessage message);

    /**
     * Tells chrome to start plugin IME.  If this results in a string getting
     * committed, the result is in aCommitted (otherwise aCommitted is empty).
     *
     * aKeyboardEvent     The event with which plugin IME is to be started
     * panelX and panelY  Location in screen coordinates of the IME input panel
     *                    (should be just under the plugin)
     * aCommitted         The string committed during IME -- otherwise empty
     */
    prio(urgent) sync StartPluginIME(WidgetKeyboardEvent aKeyboardEvent,
                                     int32_t panelX, int32_t panelY)
                                     returns (nsString aCommitted);

    /**
     * Tells chrome (and specifically the appropriate widget) whether or not
     * a plugin (inside the widget) has the keyboard focus.  Should be sent
     * when the keyboard focus changes too or from a plugin.
     *
     * aFocused  Whether or not a plugin is focused
     */
    prio(urgent) async SetPluginFocused(bool aFocused);

    /**
     * Request that the parent process move focus to the browser's frame. If
     * canRaise is true, the window can be raised if it is inactive.
     */
    RequestFocus(bool canRaise);

    /**
     * Indicate, based on the current state, that some commands are enabled and
     * some are disabled.
     */
    EnableDisableCommands(nsString action,
                          nsCString[] enabledCommands,
                          nsCString[] disabledCommands);

    prio(urgent) sync GetInputContext() returns (int32_t IMEEnabled,
                                                 int32_t IMEOpen);

    prio(urgent) async SetInputContext(int32_t IMEEnabled,
                                       int32_t IMEOpen,
                                       nsString type,
                                       nsString inputmode,
                                       nsString actionHint,
                                       int32_t cause,
                                       int32_t focusChange);

    sync IsParentWindowMainWidgetVisible() returns (bool visible);

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

    /**
     * Gets the default scaling factor of the screen corresponding to this browser.
     */
    sync GetDefaultScale() returns (double value);

    /**
     * Gets maximum of touch points at current device.
     */
    sync GetMaxTouchPoints() returns (uint32_t value);

    /**
     * Set the native cursor.
     * @param value
     *   The widget cursor to set.
     * @param force
     *   Invalidate any locally cached cursor settings and force an
     *   update.
     */
    SetCursor(uint32_t value, bool force);

    /**
     * Set the native cursor using a custom image.
     * @param cursorData
     *   Serialized image data.
     * @param width
     *   Width of the image.
     * @param height
     *   Height of the image.
     * @param stride
     *   Stride used in the image data.
     * @param format
     *   Image format, see gfx::SurfaceFormat for possible values.
     * @param hotspotX
     *   Horizontal hotspot of the image, as specified by the css cursor property.
     * @param hotspotY
     *   Vertical hotspot of the image, as specified by the css cursor property.
     * @param force
     *   Invalidate any locally cached cursor settings and force an
     *   update.
     */
    SetCustomCursor(nsCString cursorData, uint32_t width, uint32_t height,
                    uint32_t stride, uint8_t format,
                    uint32_t hotspotX, uint32_t hotspotY, bool force);

    /**
     * Used to set the current text of the status tooltip.
     * Nowadays this is mainly used for link locations on hover.
     */
    SetStatus(uint32_t type, nsString status);

    /**
     * Show/hide a tooltip when the mouse hovers over an element in the content
     * document.
     */
    ShowTooltip(uint32_t x, uint32_t y, nsString tooltip);
    HideTooltip();

    /**
     * Create an asynchronous color picker on the parent side,
     * but don't open it yet.
     */
    PColorPicker(nsString title, nsString initialColor);

    PFilePicker(nsString aTitle, int16_t aMode);

    PDatePicker(nsString aTitle);

    PTimePicker(nsString aTitle);

    /**
     * Initiates an asynchronous request for one of the special indexedDB
     * permissions for the provided principal.
     *
     * @param principal
     *   The principal of the request.
     *
     * NOTE: The principal is untrusted in the parent process. Only
     *       principals that can live in the content process should
     *       provided.
     */
    PIndexedDBPermissionRequest(Principal principal);

    /**
     * window.open from inside <iframe mozbrowser> is special.  When the child
     * process calls window.open, it creates a new PBrowser (in its own
     * process), then calls BrowserFrameOpenWindow on it.
     *
     * The parent process gets a chance to accept or reject the window.open
     * call, and windowOpened is set to true if we ended up going through with
     * the window.open.
     *
     * @param opener the PBrowser whose content called window.open.
     */
    sync BrowserFrameOpenWindow(PBrowser opener, nsString aURL,
                                nsString aName, nsString aFeatures)
      returns (bool windowOpened);

    /**
     * Instructs the TabParent to forward a request to zoom to a rect given in
     * CSS pixels. This rect is relative to the document.
     */
    ZoomToRect(uint32_t aPresShellId, ViewID aViewId, CSSRect aRect);

    /**
     * We know for sure that content has either preventDefaulted or not
     * preventDefaulted. This applies to an entire batch of touch events. It is
     * expected that, if there are any DOM touch listeners, touch events will be
     * batched and only processed for panning and zooming if content does not
     * preventDefault.
     */
    ContentReceivedInputBlock(ScrollableLayerGuid aGuid, uint64_t aInputBlockId, bool aPreventDefault);

    /**
     * Notifies the APZ code of the results of the gecko hit-test for a
     * particular input block. Each target corresponds to one touch point in the
     * touch event.
     */
    SetTargetAPZC(uint64_t aInputBlockId, ScrollableLayerGuid[] aTargets);

    /**
     * Notifies the APZ code of the allowed touch-behaviours for a particular
     * input block. Each item in the aFlags array corresponds to one touch point
     * in the touch event.
     */
    SetAllowedTouchBehavior(uint64_t aInputBlockId, TouchBehaviorFlags[] aFlags);

    /**
     * Updates the zoom constraints for a scrollable frame in this tab.
     * The zoom controller code lives on the parent side and so this allows it to
     * have up-to-date zoom constraints.
     */
    UpdateZoomConstraints(uint32_t aPresShellId, ViewID aViewId,
                          MaybeZoomConstraints aConstraints);

    /**
     * Tells the containing widget whether the given input block results in a
     * swipe. Should be called in response to a WidgetWheelEvent that has
     * mFlags.mCanTriggerSwipe set on it.
     */
    RespondStartSwipeEvent(uint64_t aInputBlockId, bool aStartSwipe);

    /**
     * Brings up the auth prompt dialog.
     * Called when this is the PBrowserParent for a nested remote iframe.
     * aCallbackId corresponds to an nsIAuthPromptCallback that lives in the
     * root process.  It will be passed back to the root process with either the
     * OnAuthAvailable or OnAuthCancelled message.
     */
    AsyncAuthPrompt(nsCString uri, nsString realm, uint64_t aCallbackId);

    __delete__();

    ReplyKeyEvent(WidgetKeyboardEvent event);

    DispatchAfterKeyboardEvent(WidgetKeyboardEvent event);

    sync RequestNativeKeyBindings(WidgetKeyboardEvent event)
        returns (MaybeNativeKeyBinding bindings);

    SynthesizeNativeKeyEvent(int32_t aNativeKeyboardLayout,
                             int32_t aNativeKeyCode,
                             uint32_t aModifierFlags,
                             nsString aCharacters,
                             nsString aUnmodifiedCharacters,
                             uint64_t aObserverId);
    SynthesizeNativeMouseEvent(LayoutDeviceIntPoint aPoint,
                               uint32_t aNativeMessage,
                               uint32_t aModifierFlags,
                               uint64_t aObserverId);
    SynthesizeNativeMouseMove(LayoutDeviceIntPoint aPoint,
                              uint64_t aObserverId);
    SynthesizeNativeMouseScrollEvent(LayoutDeviceIntPoint aPoint,
                                     uint32_t aNativeMessage,
                                     double aDeltaX,
                                     double aDeltaY,
                                     double aDeltaZ,
                                     uint32_t aModifierFlags,
                                     uint32_t aAdditionalFlags,
                                     uint64_t aObserverId);
    SynthesizeNativeTouchPoint(uint32_t aPointerId,
                               TouchPointerState aPointerState,
                               ScreenIntPoint aPointerScreenPoint,
                               double aPointerPressure,
                               uint32_t aPointerOrientation,
                               uint64_t aObserverId);
    SynthesizeNativeTouchTap(ScreenIntPoint aPointerScreenPoint,
                             bool aLongTap,
                             uint64_t aObserverId);
    ClearNativeTouchSequence(uint64_t aObserverId);
child:
    NativeSynthesisResponse(uint64_t aObserverId, nsCString aResponse);


parent:

    /**
     * Child informs the parent that the graphics objects are ready for
     * compositing.  This is sent when all pending changes have been
     * sent to the compositor and are ready to be shown on the next composite.
     * @see PCompositor
     * @see RequestNotifyAfterRemotePaint
     */
    async RemotePaintIsReady();

    sync GetRenderFrameInfo(PRenderFrame aRenderFrame)
        returns (TextureFactoryIdentifier textureFactoryIdentifier,
                 uint64_t layersId);

    /**
     * Sent by the child to the parent to inform it that an update to the
     * dimensions has been requested, likely through win.moveTo or resizeTo
     */
    async SetDimensions(uint32_t aFlags, int32_t aX, int32_t aY, int32_t aCx, int32_t aCy);

    prio(high) sync DispatchWheelEvent(WidgetWheelEvent event);
    prio(high) sync DispatchMouseEvent(WidgetMouseEvent event);
    prio(high) sync DispatchKeyboardEvent(WidgetKeyboardEvent event);

    // Start an APZ drag on a scrollbar
    async StartScrollbarDrag(AsyncDragMetrics aDragMetrics);

    InvokeDragSession(IPCDataTransfer[] transfers, uint32_t action,
                      nsCString visualData, uint32_t width, uint32_t height,
                      uint32_t stride, uint8_t format, int32_t dragAreaX, int32_t dragAreaY);

    async AudioChannelActivityNotification(uint32_t aAudioChannel,
                                           bool aActive);

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(ScreenIntSize size,
         ShowInfo info,
         TextureFactoryIdentifier textureFactoryIdentifier,
         uint64_t layersId,
         nullable PRenderFrame renderFrame,
         bool parentIsActive);

    LoadURL(nsCString uri, BrowserConfiguration config, ShowInfo info);

    OpenURI(URIParams uri, uint32_t flags);

    CacheFileDescriptor(nsString path, FileDescriptor fd);

    UpdateDimensions(CSSRect rect, CSSSize size, nsSizeMode sizeMode,
                     ScreenOrientationInternal orientation,
                     LayoutDeviceIntPoint chromeDisp) compressall;

    UpdateFrame(FrameMetrics frame);

    // The following methods correspond to functions on the GeckoContentController
    // interface in gfx/layers/apz/public/GeckoContentController.h. Refer to documentation
    // in that file for these functions.
    RequestFlingSnap(ViewID aScrollID, CSSPoint aDestination);
    AcknowledgeScrollUpdate(ViewID aScrollId, uint32_t aScrollGeneration);
    HandleDoubleTap(CSSPoint aPoint, Modifiers aModifiers, ScrollableLayerGuid aGuid);
    HandleSingleTap(CSSPoint aPoint, Modifiers aModifiers, ScrollableLayerGuid aGuid);
    HandleLongTap(CSSPoint point, Modifiers aModifiers, ScrollableLayerGuid aGuid, uint64_t aInputBlockId);
    NotifyAPZStateChange(ViewID aViewId, APZStateChange aChange, int aArg);
    NotifyFlushComplete();


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

    Deactivate();

    ParentActivated(bool aActivated);

    /**
     * StopIMEStateManagement() is called when the process loses focus and
     * should stop managing IME state.
     */
    StopIMEStateManagement();

    /**
     * MenuKeyboardListenerInstalled() is called when menu keyboard listener
     * is installed in the parent process.
     */
    MenuKeyboardListenerInstalled(bool aInstalled);

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

    /**
     * When two consecutive mouse move events would be added to the message queue,
     * they are 'compressed' by dumping the oldest one.
     */
    RealMouseMoveEvent(WidgetMouseEvent event, ScrollableLayerGuid aGuid, uint64_t aInputBlockId) compress;
    /**
     * Mouse move events with |reason == eSynthesized| are sent via a separate
     * message because they do not generate DOM 'mousemove' events, and the
     * 'compress' attribute on RealMouseMoveEvent() could result in a
     * |reason == eReal| event being dropped in favour of an |eSynthesized|
     * event, and thus a DOM 'mousemove' event to be lost.
     */
    SynthMouseMoveEvent(WidgetMouseEvent event, ScrollableLayerGuid aGuid, uint64_t aInputBlockId);
    RealMouseButtonEvent(WidgetMouseEvent event, ScrollableLayerGuid aGuid, uint64_t aInputBlockId);
    RealKeyEvent(WidgetKeyboardEvent event, MaybeNativeKeyBinding keyBinding);
    MouseWheelEvent(WidgetWheelEvent event, ScrollableLayerGuid aGuid, uint64_t aInputBlockId);
    RealTouchEvent(WidgetTouchEvent aEvent,
                   ScrollableLayerGuid aGuid,
                   uint64_t aInputBlockId,
                   nsEventStatus aApzResponse);
    RealTouchMoveEvent(WidgetTouchEvent aEvent,
                       ScrollableLayerGuid aGuid,
                       uint64_t aInputBlockId,
                       nsEventStatus aApzResponse);
    RealDragEvent(WidgetDragEvent aEvent, uint32_t aDragAction, uint32_t aDropEffect);

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

    /**
     * APZ notification for mouse scroll testing events.
     */
    MouseScrollTestEvent(ViewID aScrollId, nsString aEvent);

    CompositionEvent(WidgetCompositionEvent event);

    SelectionEvent(WidgetSelectionEvent event);

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

    LoadRemoteScript(nsString aURL, bool aRunInGlobalScope);

    /**
     * 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, Matrix transform,
                      nsString bgcolor,
                      uint32_t renderFlags, bool flushLayout,
                      IntSize 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();


    /**
     * Tell the child side if it has to update it's touchable region
     * to the parent.
     */
    SetUpdateHitRegion(bool aEnabled);

    /**
     * Update the child side docShell active (resource use) state.
     */
    SetDocShellIsActive(bool aIsActive, bool aIsHidden);

    /**
     * Notify the child that it shouldn't paint the offscreen displayport.
     * This is useful to speed up interactive operations over async
     * scrolling performance like resize, tabswitch, pageload.
     *
     * Each enable call must be matched with a disable call. The child
     * will remain in the suppress mode as long as there's
     * a single unmatched call.
     */
    async SuppressDisplayport(bool aEnabled);

    /**
     * Navigate by key (Tab/Shift+Tab/F6/Shift+f6).
     */
    NavigateByKey(bool aForward, bool aForDocumentNavigation);

    /**
     * The parent (chrome thread) requests that the child inform it when
     * the graphics objects are ready to display.
     * @see PCompositor
     * @see RemotePaintIsReady
     */
    async RequestNotifyAfterRemotePaint();

    /**
     * Tell the child that the UI resolution changed for the containing
     * window.
     * To avoid some sync messages from child to parent, we also send the dpi
     * and default scale with the notification.
     * If we don't know the dpi and default scale, we just pass in a negative
     * value (-1) but in the majority of the cases this saves us from two
     * sync requests from the child to the parent.
     */
    UIResolutionChanged(float dpi, double scale);

    /**
     * Tell the child that the system theme has changed, and that a repaint
     * is necessary.
     */
    ThemeChanged(LookAndFeelInt[] lookAndFeelIntCache);

    /**
     * Tell the child of an app's offline status
     */
    AppOfflineStatus(uint32_t id, bool offline);

    /**
     * Tell the browser that its frame loader has been swapped
     * with another.
     */
    SwappedWithOtherRemoteLoader();

    /**
     * A potential accesskey was just pressed. Look for accesskey targets
     * using the list of provided charCodes.
     *
     * @param charCode array of potential character codes
     * @param isTrusted true if triggered by a trusted key event
     * @param modifierMask indicates which accesskey modifiers are pressed
     */
    HandleAccessKey(uint32_t[] charCodes, bool isTrusted, int32_t modifierMask);

/*
 * FIXME: write protocol!

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

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

}
}