1/*
2 * Copyright 2018 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 androidx.browser.customtabs;
18
19import android.net.Uri;
20import android.os.Bundle;
21
22/**
23 * A callback class for custom tabs client to get messages regarding events in their custom tabs. In
24 * the implementation, all callbacks are sent to the UI thread for the client.
25 */
26public class CustomTabsCallback {
27    /**
28     * Sent when the tab has started loading a page.
29     */
30    public static final int NAVIGATION_STARTED = 1;
31
32    /**
33     * Sent when the tab has finished loading a page.
34     */
35    public static final int NAVIGATION_FINISHED = 2;
36
37    /**
38     * Sent when the tab couldn't finish loading due to a failure.
39     */
40    public static final int NAVIGATION_FAILED = 3;
41
42    /**
43     * Sent when loading was aborted by a user action before it finishes like clicking on a link
44     * or refreshing the page.
45     */
46    public static final int NAVIGATION_ABORTED = 4;
47
48    /**
49     * Sent when the tab becomes visible.
50     */
51    public static final int TAB_SHOWN = 5;
52
53    /**
54     * Sent when the tab becomes hidden.
55     */
56    public static final int TAB_HIDDEN = 6;
57
58    /**
59     * To be called when a navigation event happens.
60     *
61     * @param navigationEvent The code corresponding to the navigation event.
62     * @param extras Reserved for future use.
63     */
64    public void onNavigationEvent(int navigationEvent, Bundle extras) {}
65
66    /**
67     * Unsupported callbacks that may be provided by the implementation.
68     *
69     * <p>
70     * <strong>Note:</strong>Clients should <strong>never</strong> rely on this callback to be
71     * called and/or to have a defined behavior, as it is entirely implementation-defined and not
72     * supported.
73     *
74     * <p> This can be used by implementations to add extra callbacks, for testing or experimental
75     * purposes.
76     *
77     * @param callbackName Name of the extra callback.
78     * @param args Arguments for the calback
79     */
80    public void extraCallback(String callbackName, Bundle args) {}
81
82    /**
83     * Called when {@link CustomTabsSession} has requested a postMessage channel through
84     * {@link CustomTabsService#requestPostMessageChannel(
85     * CustomTabsSessionToken, android.net.Uri)} and the channel
86     * is ready for sending and receiving messages on both ends.
87     *
88     * @param extras Reserved for future use.
89     */
90    public void onMessageChannelReady(Bundle extras) {}
91
92    /**
93     * Called when a tab controlled by this {@link CustomTabsSession} has sent a postMessage.
94     * If postMessage() is called from a single thread, then the messages will be posted in the
95     * same order. When received on the client side, it is the client's responsibility to preserve
96     * the ordering further.
97     *
98     * @param message The message sent.
99     * @param extras Reserved for future use.
100     */
101    public void onPostMessage(String message, Bundle extras) {}
102
103    /**
104     * Called when a relationship validation result is available.
105     *
106     * @param relation Relation for which the result is available. Value previously passed to
107     *                 {@link CustomTabsSession#validateRelationship(int, Uri, Bundle)}. Must be one
108     *                 of the {@code CustomTabsService#RELATION_* } constants.
109     * @param requestedOrigin Origin requested. Value previously passed to
110     *                        {@link CustomTabsSession#validateRelationship(int, Uri, Bundle)}.
111     * @param result Whether the relation was validated.
112     * @param extras Reserved for future use.
113     */
114    public void onRelationshipValidationResult(@CustomTabsService.Relation int relation, Uri requestedOrigin,
115                                               boolean result, Bundle extras) {}
116}
117