| /* |
| * 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.annotation.SystemApi; |
| import android.os.Handler; |
| |
| /** |
| * <p>The Java representation of the |
| * <a href="https://html.spec.whatwg.org/multipage/comms.html#messageport"> |
| * HTML5 message ports.</a> |
| * |
| * <p>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. |
| * |
| * <p>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. |
| * |
| * <p>A message port should be closed when it is not used by the embedder application |
| * anymore. A closed port cannot be transferred or cannot be reopened to send |
| * messages. Close can be called multiple times. |
| * |
| * <p>When a port is transferred to JS, it cannot be used to send or receive messages |
| * at the Java side anymore. Different from HTML5 Spec, a port cannot be transferred |
| * if one of these has ever happened: i. a message callback was set, ii. a message was |
| * posted on it. A transferred port cannot be closed by the application, since |
| * the ownership is also transferred. |
| * |
| * <p>It is possible to transfer both ports of a channel to JS, for example for |
| * communication between subframes. |
| */ |
| 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) { } |
| } |
| |
| /** |
| * Constructor. |
| * @hide |
| */ |
| @SystemApi |
| public WebMessagePort() { } |
| |
| /** |
| * 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); |
| } |