Selim Gurun | 4c8093a | 2015-03-10 17:40:06 -0700 | [diff] [blame] | 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 | |
Selim Gurun | 0a814b6 | 2015-05-13 10:15:55 -0700 | [diff] [blame] | 19 | import android.annotation.SystemApi; |
Selim Gurun | 4c8093a | 2015-03-10 17:40:06 -0700 | [diff] [blame] | 20 | import android.os.Handler; |
| 21 | |
| 22 | /** |
Selim Gurun | 32c3516 | 2016-07-27 11:41:22 -0700 | [diff] [blame] | 23 | * <p>The Java representation of the |
Selim Gurun | 0a814b6 | 2015-05-13 10:15:55 -0700 | [diff] [blame] | 24 | * <a href="https://html.spec.whatwg.org/multipage/comms.html#messageport"> |
Nate Fischer | f02f846 | 2017-09-11 15:16:33 -0700 | [diff] [blame] | 25 | * HTML5 message ports.</a> |
Selim Gurun | 4c8093a | 2015-03-10 17:40:06 -0700 | [diff] [blame] | 26 | * |
Selim Gurun | 32c3516 | 2016-07-27 11:41:22 -0700 | [diff] [blame] | 27 | * <p>A Message port represents one endpoint of a Message Channel. In Android |
Selim Gurun | 4c8093a | 2015-03-10 17:40:06 -0700 | [diff] [blame] | 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} |
Nate Fischer | f02f846 | 2017-09-11 15:16:33 -0700 | [diff] [blame] | 31 | * for creating a message channel. |
Selim Gurun | 4c8093a | 2015-03-10 17:40:06 -0700 | [diff] [blame] | 32 | * |
Selim Gurun | 32c3516 | 2016-07-27 11:41:22 -0700 | [diff] [blame] | 33 | * <p>When a message port is first created or received via transfer, it does not |
Selim Gurun | 4c8093a | 2015-03-10 17:40:06 -0700 | [diff] [blame] | 34 | * have a WebMessageCallback to receive web messages. The messages are queued until |
Nate Fischer | f02f846 | 2017-09-11 15:16:33 -0700 | [diff] [blame] | 35 | * a WebMessageCallback is set. |
Selim Gurun | 0a814b6 | 2015-05-13 10:15:55 -0700 | [diff] [blame] | 36 | * |
Selim Gurun | 32c3516 | 2016-07-27 11:41:22 -0700 | [diff] [blame] | 37 | * <p>A message port should be closed when it is not used by the embedder application |
Selim Gurun | 0a814b6 | 2015-05-13 10:15:55 -0700 | [diff] [blame] | 38 | * anymore. A closed port cannot be transferred or cannot be reopened to send |
Nate Fischer | f02f846 | 2017-09-11 15:16:33 -0700 | [diff] [blame] | 39 | * messages. Close can be called multiple times. |
Selim Gurun | 0a814b6 | 2015-05-13 10:15:55 -0700 | [diff] [blame] | 40 | * |
Selim Gurun | 32c3516 | 2016-07-27 11:41:22 -0700 | [diff] [blame] | 41 | * <p>When a port is transferred to JS, it cannot be used to send or receive messages |
Selim Gurun | 0a814b6 | 2015-05-13 10:15:55 -0700 | [diff] [blame] | 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 |
Nate Fischer | f02f846 | 2017-09-11 15:16:33 -0700 | [diff] [blame] | 45 | * the ownership is also transferred. |
Selim Gurun | 0a814b6 | 2015-05-13 10:15:55 -0700 | [diff] [blame] | 46 | * |
Selim Gurun | 32c3516 | 2016-07-27 11:41:22 -0700 | [diff] [blame] | 47 | * <p>It is possible to transfer both ports of a channel to JS, for example for |
Nate Fischer | f02f846 | 2017-09-11 15:16:33 -0700 | [diff] [blame] | 48 | * communication between subframes. |
Selim Gurun | 4c8093a | 2015-03-10 17:40:06 -0700 | [diff] [blame] | 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 | /** |
Selim Gurun | 0a814b6 | 2015-05-13 10:15:55 -0700 | [diff] [blame] | 72 | * Constructor. |
| 73 | * @hide |
| 74 | */ |
| 75 | @SystemApi |
| 76 | public WebMessagePort() { } |
| 77 | |
| 78 | /** |
Selim Gurun | 4c8093a | 2015-03-10 17:40:06 -0700 | [diff] [blame] | 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 | } |