xref: /webkit/webkit/src/main/java/androidx/webkit/WebMessageCompat.java

/*
 * 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 androidx.annotation.IntDef;
import androidx.annotation.RequiresFeature;
import androidx.annotation.RestrictTo;

import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.Objects;

/**
 * The Java representation of the HTML5 PostMessage event. See
 * <a href="https://html.spec.whatwg.org/multipage/comms.html#the-messageevent-interfaces">
 *     https://html.spec.whatwg.org/multipage/comms.html#the-messageevent-interfaces</a>
 * for definition of a MessageEvent in HTML5.
 */
public class WebMessageCompat {

    /**
     * Indicates the payload of WebMessageCompat is String.
     */
    public static final int TYPE_STRING = 0;
    /**
     * Indicates the payload of WebMessageCompat is JavaScript ArrayBuffer.
     */
    public static final int TYPE_ARRAY_BUFFER = 1;
    private final WebMessagePortCompat @Nullable [] mPorts;
    private final @Nullable String mString;
    private final byte @Nullable [] mArrayBuffer;
    private final @Type int mType;

    /**
     * Creates a WebMessage with String payload.
     *
     * @param data the string of the message.
     */
    public WebMessageCompat(@Nullable String data) {
        this(data, null);
    }

    /**
     * Creates a WebMessage with String payload.
     *
     * @param data  the string data of the message.
     * @param ports the ports that are sent with the message.
     */
    public WebMessageCompat(@Nullable String data, WebMessagePortCompat @Nullable [] ports) {
        mString = data;
        mArrayBuffer = null;
        mPorts = ports;
        mType = TYPE_STRING;
    }

    /**
     * Creates a WebMessage with JavaScript ArrayBuffer payload.
     *
     * @param arrayBuffer the array buffer data of the message.
     */
    @RequiresFeature(name = WebViewFeature.WEB_MESSAGE_ARRAY_BUFFER,
            enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
    public WebMessageCompat(byte @NonNull [] arrayBuffer) {
        this(arrayBuffer, null);
    }

    /**
     * Creates a WebMessage with JavaScript ArrayBuffer payload.
     *
     * @param arrayBuffer the array buffer data of the message.
     * @param ports       the ports that are sent with the message.
     */
    @RequiresFeature(name = WebViewFeature.WEB_MESSAGE_ARRAY_BUFFER,
            enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported")
    public WebMessageCompat(byte @NonNull [] arrayBuffer,
            WebMessagePortCompat @Nullable [] ports) {
        Objects.requireNonNull(arrayBuffer);
        mArrayBuffer = arrayBuffer;
        mString = null;
        mPorts = ports;
        mType = TYPE_ARRAY_BUFFER;
    }

    /**
     * Returns the payload type of the message.
     *
     * @return the payload type of WebMessageCompat.
     */
    public @Type int getType() {
        return mType;
    }

    /**
     * Returns the ArrayBuffer data of message. A ArrayBuffer or Transferable ArrayBuffer can be
     * received from JavaScript. This should only be called when {@link #getType()} returns
     * {@link #TYPE_ARRAY_BUFFER}. Example:
     * <pre class="prettyprint">
     * WebMessageCompat message = ... // The WebMessageCompat received or prepared.
     * if (message.getType() == WebMessageCompat.TYPE_ARRAY_BUFFER) {
     *     byte[] arrayBuffer = message.getArrayBuffer();
     *     // Access arrayBuffer data here.
     * }
     * </pre>
     *
     * @return ArrayBuffer payload data.
     */
    public byte @NonNull [] getArrayBuffer() {
        checkType(TYPE_ARRAY_BUFFER);
        // Required for null check. ArrayBuffer is always non-null when mType == TYPE_ARRAY_BUFFER.
        Objects.requireNonNull(mArrayBuffer);
        return mArrayBuffer;
    }

    /**
     * Returns the String data of the message. This should only be called when {@link #getType()}
     * returns {@link #TYPE_STRING}. Example:
     * <pre class="prettyprint">
     * WebMessageCompat message = ... // The WebMessageCompat received or prepared.
     * if (message.getType() == WebMessageCompat.TYPE_STRING) {
     *     String string = message.getData();
     *     // Access string data here.
     * }
     * </pre>
     *
     * @return String payload data.
     */
    public @Nullable String getData() {
        checkType(TYPE_STRING);
        return mString;
    }

    /**
     * Returns the ports that are sent with the message, or {@code null} if no port
     * is sent.
     */
    public WebMessagePortCompat @Nullable [] getPorts() {
        return mPorts;
    }

    private @NonNull String typeToString(@Type int type) {
        switch (type) {
            case TYPE_STRING:
                return "String";
            case TYPE_ARRAY_BUFFER:
                return "ArrayBuffer";
            default:
                return "Unknown";
        }
    }

    private void checkType(@Type int typeForGetter) {
        if (typeForGetter != mType) {
            throw new IllegalStateException("Wrong data accessor type detected. "
                    + typeToString(mType) + " expected, but got " + typeToString(typeForGetter));
        }
    }

    @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
    @IntDef({TYPE_STRING, TYPE_ARRAY_BUFFER})
    @Retention(RetentionPolicy.SOURCE)
    public @interface Type {
    }
}