1/*
2 * Copyright (C) 2014 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 android.webkit;
18
19import android.net.Uri;
20
21/**
22 * This class defines a permission request and is used when web content
23 * requests access to protected resources. The permission request related events
24 * are delivered via {@link WebChromeClient#onPermissionRequest} and
25 * {@link WebChromeClient#onPermissionRequestCanceled}.
26 *
27 * Either {@link #grant(String[]) grant()} or {@link #deny()} must be called in UI
28 * thread to respond to the request.
29 *
30 * New protected resources whose names are not defined here may be requested in
31 * future versions of WebView, even when running on an older Android release. To
32 * avoid unintentionally granting requests for new permissions, you should pass the
33 * specific permissions you intend to grant to {@link #grant(String[]) grant()},
34 * and avoid writing code like this example:
35 * <pre>
36 * permissionRequest.grant(permissionRequest.getResources())  // This is wrong!!!
37 * </pre>
38 * See the WebView's release notes for information about new protected resources.
39 */
40public abstract class PermissionRequest {
41    /**
42     * Resource belongs to video capture device, like camera.
43     */
44    public final static String RESOURCE_VIDEO_CAPTURE = "android.webkit.resource.VIDEO_CAPTURE";
45    /**
46     * Resource belongs to audio capture device, like microphone.
47     */
48    public final static String RESOURCE_AUDIO_CAPTURE = "android.webkit.resource.AUDIO_CAPTURE";
49    /**
50     * Resource belongs to protected media identifier.
51     * After the user grants this resource, the origin can use EME APIs to generate the license
52     * requests.
53     */
54    public final static String RESOURCE_PROTECTED_MEDIA_ID =
55            "android.webkit.resource.PROTECTED_MEDIA_ID";
56    /**
57     * Resource will allow sysex messages to be sent to or received from MIDI devices. These
58     * messages are privileged operations, e.g. modifying sound libraries and sampling data, or
59     * even updating the MIDI device's firmware.
60     *
61     * Permission may be requested for this resource in API levels 21 and above, if the Android
62     * device has been updated to WebView 45 or above.
63     */
64    public final static String RESOURCE_MIDI_SYSEX = "android.webkit.resource.MIDI_SYSEX";
65
66    /**
67     * Call this method to get the origin of the web page which is trying to access
68     * the restricted resources.
69     *
70     * @return the origin of web content which attempt to access the restricted
71     *         resources.
72     */
73    public abstract Uri getOrigin();
74
75    /**
76     * Call this method to get the resources the web page is trying to access.
77     *
78     * @return the array of resources the web content wants to access.
79     */
80    public abstract String[] getResources();
81
82    /**
83     * Call this method to grant origin the permission to access the given resources.
84     * The granted permission is only valid for this WebView.
85     *
86     * @param resources the resources granted to be accessed by origin, to grant
87     *        request, the requested resources returned by {@link #getResources()}
88     *        must be equals or a subset of granted resources.
89     *        This parameter is designed to avoid granting permission by accident
90     *        especially when new resources are requested by web content.
91     */
92    public abstract void grant(String[] resources);
93
94    /**
95     * Call this method to deny the request.
96     */
97    public abstract void deny();
98}
99