14c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun/* 24c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * Copyright (C) 2015 The Android Open Source Project 34c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 44c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * Licensed under the Apache License, Version 2.0 (the "License"); 54c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * you may not use this file except in compliance with the License. 64c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * You may obtain a copy of the License at 74c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 84c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * http://www.apache.org/licenses/LICENSE-2.0 94c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 104c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * Unless required by applicable law or agreed to in writing, software 114c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * distributed under the License is distributed on an "AS IS" BASIS, 124c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 134c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * See the License for the specific language governing permissions and 144c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * limitations under the License. 154c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun */ 164c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun 174c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurunpackage android.webkit; 184c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun 190a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurunimport android.annotation.SystemApi; 204c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurunimport android.os.Handler; 214c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun 224c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun/** 2332c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * <p>The Java representation of the 240a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * <a href="https://html.spec.whatwg.org/multipage/comms.html#messageport"> 2532c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * HTML5 message ports.</a> </p> 264c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 2732c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * <p>A Message port represents one endpoint of a Message Channel. In Android 284c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * webview, there is no separate Message Channel object. When a message channel 294c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * is created, both ports are tangled to each other and started, and then 304c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * returned in a MessagePort array, see {@link WebView#createWebMessageChannel} 3132c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * for creating a message channel. </p> 324c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 3332c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * <p>When a message port is first created or received via transfer, it does not 344c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * have a WebMessageCallback to receive web messages. The messages are queued until 3532c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * a WebMessageCallback is set. </p> 360a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * 3732c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * <p>A message port should be closed when it is not used by the embedder application 380a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * anymore. A closed port cannot be transferred or cannot be reopened to send 3932c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * messages. Close can be called multiple times. </p> 400a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * 4132c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * <p>When a port is transferred to JS, it cannot be used to send or receive messages 420a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * at the Java side anymore. Different from HTML5 Spec, a port cannot be transferred 430a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * if one of these has ever happened: i. a message callback was set, ii. a message was 440a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * posted on it. A transferred port cannot be closed by the application, since 4532c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * the ownership is also transferred. </p> 460a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * 4732c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * <p>It is possible to transfer both ports of a channel to JS, for example for 4832c3516369768c73d7f4f6aea0e1b4adce41e6d3Selim Gurun * communication between subframes.</p> 494c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun */ 504c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurunpublic abstract class WebMessagePort { 514c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun 524c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun /** 534c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * The listener for handling MessagePort events. The message callback 544c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * methods are called on the main thread. If the embedder application 554c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * wants to receive the messages on a different thread, it can do this 564c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * by passing a Handler in 574c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * {@link WebMessagePort#setWebMessageCallback(WebMessageCallback, Handler)}. 584c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * In the latter case, the application should be extra careful for thread safety 594c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * since WebMessagePort methods should be called on main thread. 604c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun */ 614c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun public static abstract class WebMessageCallback { 624c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun /** 634c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * Message callback for receiving onMessage events. 644c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 654c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * @param port the WebMessagePort that the message is destined for 664c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * @param message the message from the entangled port. 674c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun */ 684c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun public void onMessage(WebMessagePort port, WebMessage message) { } 694c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun } 704c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun 714c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun /** 720a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * Constructor. 730a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun * @hide 740a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun */ 750a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun @SystemApi 760a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun public WebMessagePort() { } 770a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun 780a814b61e3a4e6bf17675b943edcf8c8b29d8787Selim Gurun /** 794c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * Post a WebMessage to the entangled port. 804c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 814c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * @param message the message from Java to JS. 824c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 834c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * @throws IllegalStateException If message port is already transferred or closed. 844c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun */ 854c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun public abstract void postMessage(WebMessage message); 864c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun 874c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun /** 884c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * Close the message port and free any resources associated with it. 894c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun */ 904c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun public abstract void close(); 914c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun 924c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun /** 934c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * Sets a callback to receive message events on the main thread. 944c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 954c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * @param callback the message callback. 964c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun */ 974c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun public abstract void setWebMessageCallback(WebMessageCallback callback); 984c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun 994c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun /** 1004c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * Sets a callback to receive message events on the handler that is provided 1014c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * by the application. 1024c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * 1034c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * @param callback the message callback. 1044c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun * @param handler the handler to receive the message messages. 1054c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun */ 1064c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun public abstract void setWebMessageCallback(WebMessageCallback callback, Handler handler); 1074c8093afe3da4f6d3b9a43510d0b6601aeadb582Selim Gurun} 108