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
Nested types |
|---|
public abstract class WebMessagePortCompat.WebMessageCallbackCompatThe listener for handling MessagePort events. |
Public methods |
|
|---|---|
abstract void |
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_CLOSE, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")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")Post a WebMessage to the entangled port. |
abstract void |
@RequiresFeature(name = WebViewFeature.WEB_MESSAGE_PORT_SET_MESSAGE_CALLBACK, enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")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")Sets a callback to receive message events on the handler that is provided by the application. |
Public methods
close
@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 |
postMessage
@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 |
setWebMessageCallback
@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 |
setWebMessageCallback
@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. |
| Throws | |
|---|---|
java.lang.UnsupportedOperationException |
if the |