public abstract class

WebMessagePortCompat

extends java.lang.Object

 java.lang.Object

↳androidx.webkit.WebMessagePortCompat

Subclasses:

WebMessagePortImpl

Gradle dependencies

compile group: 'androidx.webkit', name: 'webkit', version: '1.5.0-alpha01'

  • groupId: androidx.webkit
  • artifactId: webkit
  • version: 1.5.0-alpha01

Artifact androidx.webkit:webkit:1.5.0-alpha01 it located at Google repository (https://maven.google.com/)

Androidx artifact mapping:

androidx.webkit:webkit com.android.support:webkit

Overview

The Java representation of the HTML5 message ports.

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 WebViewCompat.createWebMessageChannel(WebView) for creating a message channel.

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.

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.

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.

It is possible to transfer both ports of a channel to JS, for example for communication between subframes.

Summary

Constructors
publicWebMessagePortCompat()

Methods
public abstract voidclose()

Close the message port and free any resources associated with it.

public abstract WebMessagePortgetFrameworkPort()

Internal getter returning the private implementing this class.

public abstract java.lang.reflect.InvocationHandlergetInvocationHandler()

Internal getter returning the private java.lang.reflect.InvocationHandler implementing this class.

public abstract voidpostMessage(WebMessageCompat message)

Post a WebMessage to the entangled port.

public abstract voidsetWebMessageCallback(Handler handler, WebMessagePortCompat.WebMessageCallbackCompat callback)

Sets a callback to receive message events on the handler that is provided by the application.

public abstract voidsetWebMessageCallback(WebMessagePortCompat.WebMessageCallbackCompat callback)

Sets a callback to receive message events on the main thread.

from java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructors

public WebMessagePortCompat()

Methods

public abstract void postMessage(WebMessageCompat message)

Post a WebMessage to the entangled port.

This method should only be called if WebViewFeature.isFeatureSupported(String) returns true for WebViewFeature.WEB_MESSAGE_PORT_POST_MESSAGE.

Parameters:

message: the message from Java to JS.

public abstract void close()

Close the message port and free any resources associated with it.

This method should only be called if WebViewFeature.isFeatureSupported(String) returns true for WebViewFeature.WEB_MESSAGE_PORT_CLOSE.

public abstract void setWebMessageCallback(WebMessagePortCompat.WebMessageCallbackCompat callback)

Sets a callback to receive message events on the main thread.

This method should only be called if WebViewFeature.isFeatureSupported(String) returns true for WebViewFeature.WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK.

Parameters:

callback: the message callback.

public abstract void setWebMessageCallback(Handler handler, WebMessagePortCompat.WebMessageCallbackCompat callback)

Sets a callback to receive message events on the handler that is provided by the application. If the handler is null the message events are received on the main thread.

This method should only be called if WebViewFeature.isFeatureSupported(String) returns true for WebViewFeature.WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK.

Parameters:

handler: the handler to receive the message events.
callback: the message callback.

public abstract WebMessagePort getFrameworkPort()

Internal getter returning the private implementing this class. This is only available on devices with an Android versions supporting WebMessagePorts.

public abstract java.lang.reflect.InvocationHandler getInvocationHandler()

Internal getter returning the private java.lang.reflect.InvocationHandler implementing this class. This is only available on devices where the support library glue in the WebView APK supports WebMessagePortCompat.

Source

/*
 * Copyright 2018 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 androidx.webkit;

import android.os.Handler;
import android.webkit.WebMessagePort;

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.RequiresApi;
import androidx.annotation.RequiresFeature;
import androidx.annotation.RestrictTo;

import java.lang.reflect.InvocationHandler;

/**
 * <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 WebViewCompat#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 WebMessagePortCompat {
    /**
     * 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 WebMessagePortCompat#setWebMessageCallback(Handler, WebMessageCallbackCompat)}.
     * In the latter case, the application should be extra careful for thread safety
     * since WebMessagePort methods should be called on main thread.
     */
    public abstract static class WebMessageCallbackCompat {
        /**
         * Message callback for receiving onMessage events.
         *
         * <p>This method is called only if {@link WebViewFeature#WEB_MESSAGE_CALLBACK_ON_MESSAGE}
         * is supported. You can check whether that flag is supported using
         * {@link WebViewFeature#isFeatureSupported(String)}.
         *
         * @param port  the WebMessagePort that the message is destined for
         * @param message  the message from the entangled port.
         */
        public void onMessage(@NonNull WebMessagePortCompat port,
                @Nullable WebMessageCompat message) { }
    }

    /**
     * @hide disallow app devs to extend this class.
     */
    @RestrictTo(RestrictTo.Scope.LIBRARY)
    public WebMessagePortCompat() { }

    /**
     * Post a WebMessage to the entangled port.
     *
     * <p>
     * This method should only be called if
     * {@link WebViewFeature#isFeatureSupported(String)}
     * returns true for {@link WebViewFeature#WEB_MESSAGE_PORT_POST_MESSAGE}.
     *
     * @param message  the message from Java to JS.
     *
     * @throws IllegalStateException If message port is already transferred or closed.
     */
    @RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_POST_MESSAGE,
            enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
    public abstract void postMessage(@NonNull WebMessageCompat message);

    /**
     * Close the message port and free any resources associated with it.
     *
     * <p>
     * This method should only be called if
     * {@link WebViewFeature#isFeatureSupported(String)}
     * returns true for {@link WebViewFeature#WEB_MESSAGE_PORT_CLOSE}.
     */
    @RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_CLOSE,
            enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
    public abstract void close();

    /**
     * Sets a callback to receive message events on the main thread.
     *
     * <p>
     * This method should only be called if
     * {@link WebViewFeature#isFeatureSupported(String)}
     * returns true for {@link WebViewFeature#WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK}.
     *
     * @param callback  the message callback.
     */
    @RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK,
            enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
    public abstract void setWebMessageCallback(@NonNull WebMessageCallbackCompat callback);

    /**
     * Sets a callback to receive message events on the handler that is provided
     * by the application. If the handler is null the message events are received on the main
     * thread.
     *
     * <p>
     * This method should only be called if
     * {@link WebViewFeature#isFeatureSupported(String)}
     * returns true for {@link WebViewFeature#WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK}.
     *
     * @param handler   the handler to receive the message events.
     * @param callback  the message callback.
     */
    @RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK,
            enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
    public abstract void setWebMessageCallback(@Nullable Handler handler,
            @NonNull WebMessageCallbackCompat callback);

    /**
     * Internal getter returning the private {@link WebMessagePort} implementing this class. This is
     * only available on devices with an Android versions supporting WebMessagePorts.
     * @hide
     */
    @RequiresApi(23)
    @RestrictTo(RestrictTo.Scope.LIBRARY)
    @NonNull
    public abstract WebMessagePort getFrameworkPort();

    /**
     * Internal getter returning the private {@link java.lang.reflect.InvocationHandler}
     * implementing this class. This is only available on devices where the support library glue in
     * the WebView APK supports {@link WebMessagePortCompat}.
     * @hide
     */
    @NonNull
    @RestrictTo(RestrictTo.Scope.LIBRARY)
    public abstract InvocationHandler getInvocationHandler();

}