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
17package android.webkit;
18
19import android.annotation.SystemApi;
20import 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 */
50public 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