WebMessagePortCompat

@AnyThread
public abstract class WebMessagePortCompat

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 createWebMessageChannel 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

Public methods
abstract void
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_CLOSE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
close()

Close the message port and free any resources associated with it.
abstract void
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_POST_MESSAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
postMessage(@NonNull WebMessageCompat message)

Post a WebMessage to the entangled port.
abstract void
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
setWebMessageCallback(
 @NonNull WebMessagePortCompat.WebMessageCallbackCompat callback
)

Sets a callback to receive message events on the main thread.
abstract void
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
setWebMessageCallback(
 @Nullable Handler handler,
 @NonNull WebMessagePortCompat.WebMessageCallbackCompat callback
)

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

Public methods

close

Added in 1.1.0
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_CLOSE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public abstract void close()

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

Throws
java.lang.UnsupportedOperationException

if the WEB_MESSAGE_PORT_CLOSE feature is not supported. This should be checked before use with isFeatureSupported.

postMessage

Added in 1.1.0
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_POST_MESSAGE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public abstract void postMessage(@NonNull WebMessageCompat message)

Post a WebMessage to the entangled port.

When posting a WebMessageCompat with type TYPE_ARRAY_BUFFER, this method should check if isFeatureSupported returns true for WEB_MESSAGE_ARRAY_BUFFER. Example: 

if (message.getType() == WebMessageCompat.TYPE_ARRAY_BUFFER) {
    if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_MESSAGE_ARRAY_BUFFER) {
        // ArrayBuffer message is supported, send message here.
        port.postMessage(message);
    }
}
Parameters
@NonNull WebMessageCompat message

the message from Java to JS.
Throws
java.lang.IllegalStateException

If message port is already transferred or closed.
java.lang.UnsupportedOperationException

if the WEB_MESSAGE_PORT_POST_MESSAGE feature is not supported. This should be checked before use with isFeatureSupported.

setWebMessageCallback

Added in 1.1.0
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public abstract void setWebMessageCallback(
 @NonNull WebMessagePortCompat.WebMessageCallbackCompat callback
)

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

Parameters
@NonNull WebMessagePortCompat.WebMessageCallbackCompat callback

the message callback.
Throws
java.lang.UnsupportedOperationException

if the WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK feature is not supported. This should be checked before use with isFeatureSupported.

setWebMessageCallback

Added in 1.1.0
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
public abstract void setWebMessageCallback(
 @Nullable Handler handler,
 @NonNull 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.

Parameters
@Nullable Handler handler

the handler to receive the message events.
@NonNull WebMessagePortCompat.WebMessageCallbackCompat callback

the message callback.