Implement PostMessage API for Webview

Bug: 10237116

This CL implements the postmessage API for webview. It provides
a way for java applications to post messages to JS frames and
establish message channels, and then do full-duplex communication
after that.

Change-Id: Idbc2918552a4c9fd28ae1ddf19bd360e71f8a4a2

4 files changed, 185 insertions, 0 deletions

diff --git a/core/java/android/webkit/WebMessage.java b/core/java/android/webkit/WebMessage.java
new file mode 100644
index 0000000..7683a40
--- /dev/null
+++ b/core/java/android/webkit/WebMessage.java
@@ -0,0 +1,62 @@
+/*
+ * Copyright (C) 2015 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.webkit;
+
+/**
+ * The Java representation of the HTML5 PostMessage event. See
+ * https://html.spec.whatwg.org/multipage/comms.html#the-messageevent-interfaces
+ * for definition of a MessageEvent in HTML5.
+ *
+ */
+public class WebMessage {
+
+    private String mData;
+    private WebMessagePort[] mPorts;
+
+    /**
+     * Creates a WebMessage.
+     * @param data  the data of the message.
+     */
+    public WebMessage(String data) {
+        mData = data;
+    }
+
+    /**
+     * Creates a WebMessage.
+     * @param data  the data of the message.
+     * @param ports  the ports that are sent with the message.
+     */
+    public WebMessage(String data, WebMessagePort[] ports) {
+        mData = data;
+        mPorts = ports;
+    }
+
+    /**
+     * Returns the data of the message.
+     */
+    public String getData() {
+        return mData;
+    }
+
+    /**
+     * Returns the ports that are sent with the message, or null if no port
+     * is sent.
+     */
+    public WebMessagePort[] getPorts() {
+        return mPorts;
+    }
+}
diff --git a/core/java/android/webkit/WebMessagePort.java b/core/java/android/webkit/WebMessagePort.java
new file mode 100644
index 0000000..eab27bd
--- /dev/null
+++ b/core/java/android/webkit/WebMessagePort.java
@@ -0,0 +1,86 @@
+/*
+ * Copyright (C) 2015 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.webkit;
+
+import android.os.Handler;
+
+/**
+ * The Java representation of the HTML5 Message Port. See
+ * https://html.spec.whatwg.org/multipage/comms.html#messageport
+ * for definition of MessagePort in HTML5.
+ *
+ * A Message port represents one endpoint of a Message Channel. In Android
+ * webview, there is no separate Message Channel object. When a message channel
+ * is created, both ports are tangled to each other and started, and then
+ * returned in a MessagePort array, see {@link WebView#createWebMessageChannel}
+ * for creating a message channel.
+ *
+ * When a message port is first created or received via transfer, it does not
+ * have a WebMessageCallback to receive web messages. The messages are queued until
+ * a WebMessageCallback is set.
+ */
+public abstract class WebMessagePort {
+
+    /**
+     * The listener for handling MessagePort events. The message callback
+     * methods are called on the main thread. If the embedder application
+     * wants to receive the messages on a different thread, it can do this
+     * by passing a Handler in
+     *  {@link WebMessagePort#setWebMessageCallback(WebMessageCallback, Handler)}.
+     * In the latter case, the application should be extra careful for thread safety
+     * since WebMessagePort methods should be called on main thread.
+     */
+    public static abstract class WebMessageCallback {
+        /**
+         * Message callback for receiving onMessage events.
+         *
+         * @param port  the WebMessagePort that the message is destined for
+         * @param message  the message from the entangled port.
+         */
+        public void onMessage(WebMessagePort port, WebMessage message) { }
+    }
+
+    /**
+     * Post a WebMessage to the entangled port.
+     *
+     * @param message  the message from Java to JS.
+     *
+     * @throws IllegalStateException If message port is already transferred or closed.
+     */
+    public abstract void postMessage(WebMessage message);
+
+    /**
+     * Close the message port and free any resources associated with it.
+     */
+    public abstract void close();
+
+    /**
+     * Sets a callback to receive message events on the main thread.
+     *
+     * @param callback  the message callback.
+     */
+    public abstract void setWebMessageCallback(WebMessageCallback callback);
+
+    /**
+     * Sets a callback to receive message events on the handler that is provided
+     * by the application.
+     *
+     * @param callback  the message callback.
+     * @param handler   the handler to receive the message messages.
+     */
+    public abstract void setWebMessageCallback(WebMessageCallback callback, Handler handler);
+}
diff --git a/core/java/android/webkit/WebView.java b/core/java/android/webkit/WebView.java
index 01a506c..67ad642 100644
--- a/core/java/android/webkit/WebView.java
+++ b/core/java/android/webkit/WebView.java
@@ -27,6 +27,7 @@ import android.graphics.Picture;
 import android.graphics.Rect;
 import android.graphics.drawable.Drawable;
 import android.net.http.SslCertificate;
+import android.net.Uri;
 import android.os.Build;
 import android.os.Bundle;
 import android.os.Looper;
@@ -1825,6 +1826,37 @@ public class WebView extends AbsoluteLayout
     }
 
     /**
+     * Creates a message channel to communicate with JS and returns the message
+     * ports that represent the endpoints of this message channel. The HTML5 message
+     * channel functionality is described here:
+     * https://html.spec.whatwg.org/multipage/comms.html#messagechannel
+     *
+     * The returned message channels are entangled and already in started state.
+     *
+     * @return the two message ports that form the message channel.
+     */
+    public WebMessagePort[] createWebMessageChannel() {
+        checkThread();
+        if (TRACE) Log.d(LOGTAG, "createWebMessageChannel");
+        return mProvider.createWebMessageChannel();
+    }
+
+    /**
+     * Post a message to main frame. The embedded application can restrict the
+     * messages to a certain target origin. See
+     *    https://html.spec.whatwg.org/multipage/comms.html#posting-messages
+     * for how target origin can be used.
+     *
+     * @param message the WebMessage
+     * @param targetOrigin the target origin.
+     */
+    public void postMessageToMainFrame(WebMessage message, Uri targetOrigin) {
+        checkThread();
+        if (TRACE) Log.d(LOGTAG, "postMessageToMainFrame. TargetOrigin=" + targetOrigin);
+        mProvider.postMessageToMainFrame(message, targetOrigin);
+    }
+
+    /**
      * Gets the WebSettings object used to control the settings for this
      * WebView.
      *
diff --git a/core/java/android/webkit/WebViewProvider.java b/core/java/android/webkit/WebViewProvider.java
index 379a732..0cdb875 100644
--- a/core/java/android/webkit/WebViewProvider.java
+++ b/core/java/android/webkit/WebViewProvider.java
@@ -25,6 +25,7 @@ import android.graphics.Picture;
 import android.graphics.Rect;
 import android.graphics.drawable.Drawable;
 import android.net.http.SslCertificate;
+import android.net.Uri;
 import android.os.Bundle;
 import android.os.Message;
 import android.print.PrintDocumentAdapter;
@@ -227,6 +228,10 @@ public interface WebViewProvider {
 
     public void removeJavascriptInterface(String interfaceName);
 
+    public WebMessagePort[] createWebMessageChannel();
+
+    public void postMessageToMainFrame(WebMessage message, Uri targetOrigin);
+
     public WebSettings getSettings();
 
     public void setMapTrackballToArrowKeys(boolean setMap);