1 /*
2  * Copyright (C) 2009 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 
17 package android.webkit;
18 
19 import android.annotation.SystemApi;
20 
21 import java.util.Set;
22 
23 /**
24  * This class is used to manage permissions for the WebView's Geolocation
25  * JavaScript API.
26  *
27  * Geolocation permissions are applied to an origin, which consists of the
28  * host, scheme and port of a URI. In order for web content to use the
29  * Geolocation API, permission must be granted for that content's origin.
30  *
31  * This class stores Geolocation permissions. An origin's permission state can
32  * be either allowed or denied. This class uses Strings to represent
33  * an origin.
34  *
35  * When an origin attempts to use the Geolocation API, but no permission state
36  * is currently set for that origin,
37  * {@link WebChromeClient#onGeolocationPermissionsShowPrompt(String,GeolocationPermissions.Callback) WebChromeClient.onGeolocationPermissionsShowPrompt()}
38  * is called. This allows the permission state to be set for that origin.
39  *
40  * The methods of this class can be used to modify and interrogate the stored
41  * Geolocation permissions at any time.
42  */
43 // Within WebKit, Geolocation permissions may be applied either temporarily
44 // (for the duration of the page) or permanently. This class deals only with
45 // permanent permissions.
46 public class GeolocationPermissions {
47     /**
48      * A callback interface used by the host application to set the Geolocation
49      * permission state for an origin.
50      */
51     public interface Callback {
52         /**
53          * Sets the Geolocation permission state for the supplied origin.
54          *
55          * @param origin the origin for which permissions are set
56          * @param allow whether or not the origin should be allowed to use the
57          *              Geolocation API
58          * @param retain whether the permission should be retained beyond the
59          *               lifetime of a page currently being displayed by a
60          *               WebView
61          */
invoke(String origin, boolean allow, boolean retain)62         public void invoke(String origin, boolean allow, boolean retain);
63     };
64 
65     /**
66      * Gets the singleton instance of this class. This method cannot be
67      * called before the application instantiates a {@link WebView} instance.
68      *
69      * @return the singleton {@link GeolocationPermissions} instance
70      */
getInstance()71     public static GeolocationPermissions getInstance() {
72       return WebViewFactory.getProvider().getGeolocationPermissions();
73     }
74 
75     /**
76      * Gets the set of origins for which Geolocation permissions are stored.
77      *
78      * @param callback a {@link ValueCallback} to receive the result of this
79      *                 request. This object's
80      *                 {@link ValueCallback#onReceiveValue(T) onReceiveValue()}
81      *                 method will be invoked asynchronously with a set of
82      *                 Strings containing the origins for which Geolocation
83      *                 permissions are stored.
84      */
85     // Note that we represent the origins as strings. These are created using
86     // WebCore::SecurityOrigin::toString(). As long as all 'HTML 5 modules'
87     // (Database, Geolocation etc) do so, it's safe to match up origins based
88     // on this string.
getOrigins(ValueCallback<Set<String> > callback)89     public void getOrigins(ValueCallback<Set<String> > callback) {
90         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
91     }
92 
93     /**
94      * Gets the Geolocation permission state for the specified origin.
95      *
96      * @param origin the origin for which Geolocation permission is requested
97      * @param callback a {@link ValueCallback} to receive the result of this
98      *                 request. This object's
99      *                 {@link ValueCallback#onReceiveValue(T) onReceiveValue()}
100      *                 method will be invoked asynchronously with a boolean
101      *                 indicating whether or not the origin can use the
102      *                 Geolocation API.
103      */
getAllowed(String origin, ValueCallback<Boolean> callback)104     public void getAllowed(String origin, ValueCallback<Boolean> callback) {
105         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
106     }
107 
108     /**
109      * Clears the Geolocation permission state for the specified origin.
110      *
111      * @param origin the origin for which Geolocation permissions are cleared
112      */
clear(String origin)113     public void clear(String origin) {
114         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
115     }
116 
117     /**
118      * Allows the specified origin to use the Geolocation API.
119      *
120      * @param origin the origin for which Geolocation API use is allowed
121      */
allow(String origin)122     public void allow(String origin) {
123         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
124     }
125 
126     /**
127      * Clears the Geolocation permission state for all origins.
128      */
clearAll()129     public void clearAll() {
130         // Must be a no-op for backward compatibility: see the hidden constructor for reason.
131     }
132 
133     /**
134      * This class should not be instantiated directly, applications must only use
135      * {@link #getInstance()} to obtain the instance.
136      * Note this constructor was erroneously public and published in SDK levels prior to 16, but
137      * applications using it would receive a non-functional instance of this class (there was no
138      * way to call createHandler() and createUIHandler(), so it would not work).
139      * @hide Only for use by WebViewProvider implementations
140      */
141     @SystemApi
GeolocationPermissions()142     public GeolocationPermissions() {}
143 }
144