1 /* 2 * Copyright (C) 2015 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.webkit; 18 19 import android.annotation.SystemApi; 20 import android.os.Handler; 21 22 /** 23 * The Java representation of the 24 * <a href="https://html.spec.whatwg.org/multipage/comms.html#messageport"> 25 * HTML5 message ports.</a> 26 * 27 * A Message port represents one endpoint of a Message Channel. In Android 28 * webview, there is no separate Message Channel object. When a message channel 29 * is created, both ports are tangled to each other and started, and then 30 * returned in a MessagePort array, see {@link WebView#createWebMessageChannel} 31 * for creating a message channel. 32 * 33 * When a message port is first created or received via transfer, it does not 34 * have a WebMessageCallback to receive web messages. The messages are queued until 35 * a WebMessageCallback is set. 36 * 37 * A message port should be closed when it is not used by the embedder application 38 * anymore. A closed port cannot be transferred or cannot be reopened to send 39 * messages. Close can be called multiple times. 40 * 41 * When a port is transferred to JS, it cannot be used to send or receive messages 42 * at the Java side anymore. Different from HTML5 Spec, a port cannot be transferred 43 * if one of these has ever happened: i. a message callback was set, ii. a message was 44 * posted on it. A transferred port cannot be closed by the application, since 45 * the ownership is also transferred. 46 * 47 * It is possible to transfer both ports of a channel to JS, for example for 48 * communication between subframes. 49 */ 50 public abstract class WebMessagePort { 51 52 /** 53 * The listener for handling MessagePort events. The message callback 54 * methods are called on the main thread. If the embedder application 55 * wants to receive the messages on a different thread, it can do this 56 * by passing a Handler in 57 * {@link WebMessagePort#setWebMessageCallback(WebMessageCallback, Handler)}. 58 * In the latter case, the application should be extra careful for thread safety 59 * since WebMessagePort methods should be called on main thread. 60 */ 61 public static abstract class WebMessageCallback { 62 /** 63 * Message callback for receiving onMessage events. 64 * 65 * @param port the WebMessagePort that the message is destined for 66 * @param message the message from the entangled port. 67 */ 68 public void onMessage(WebMessagePort port, WebMessage message) { } 69 } 70 71 /** 72 * Constructor. 73 * @hide 74 */ 75 @SystemApi 76 public WebMessagePort() { } 77 78 /** 79 * Post a WebMessage to the entangled port. 80 * 81 * @param message the message from Java to JS. 82 * 83 * @throws IllegalStateException If message port is already transferred or closed. 84 */ 85 public abstract void postMessage(WebMessage message); 86 87 /** 88 * Close the message port and free any resources associated with it. 89 */ 90 public abstract void close(); 91 92 /** 93 * Sets a callback to receive message events on the main thread. 94 * 95 * @param callback the message callback. 96 */ 97 public abstract void setWebMessageCallback(WebMessageCallback callback); 98 99 /** 100 * Sets a callback to receive message events on the handler that is provided 101 * by the application. 102 * 103 * @param callback the message callback. 104 * @param handler the handler to receive the message messages. 105 */ 106 public abstract void setWebMessageCallback(WebMessageCallback callback, Handler handler); 107 } 108
