1/*
2 * Copyright (C) 2007 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.app;
18
19import android.os.Binder;
20import android.os.RemoteException;
21import android.os.IBinder;
22import android.view.IWindowManager;
23import android.view.IOnKeyguardExitResult;
24import android.view.WindowManagerGlobal;
25
26/**
27 * Class that can be used to lock and unlock the keyboard. Get an instance of this
28 * class by calling {@link android.content.Context#getSystemService(java.lang.String)}
29 * with argument {@link android.content.Context#KEYGUARD_SERVICE}. The
30 * actual class to control the keyboard locking is
31 * {@link android.app.KeyguardManager.KeyguardLock}.
32 */
33public class KeyguardManager {
34    private IWindowManager mWM;
35
36    /**
37     * @deprecated Use {@link android.view.WindowManager.LayoutParams#FLAG_DISMISS_KEYGUARD}
38     * and/or {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WHEN_LOCKED}
39     * instead; this allows you to seamlessly hide the keyguard as your application
40     * moves in and out of the foreground and does not require that any special
41     * permissions be requested.
42     *
43     * Handle returned by {@link KeyguardManager#newKeyguardLock} that allows
44     * you to disable / reenable the keyguard.
45     */
46    public class KeyguardLock {
47        private IBinder mToken = new Binder();
48        private String mTag;
49
50        KeyguardLock(String tag) {
51            mTag = tag;
52        }
53
54        /**
55         * Disable the keyguard from showing.  If the keyguard is currently
56         * showing, hide it.  The keyguard will be prevented from showing again
57         * until {@link #reenableKeyguard()} is called.
58         *
59         * A good place to call this is from {@link android.app.Activity#onResume()}
60         *
61         * Note: This call has no effect while any {@link android.app.admin.DevicePolicyManager}
62         * is enabled that requires a password.
63         *
64         * <p>This method requires the caller to hold the permission
65         * {@link android.Manifest.permission#DISABLE_KEYGUARD}.
66         *
67         * @see #reenableKeyguard()
68         */
69        public void disableKeyguard() {
70            try {
71                mWM.disableKeyguard(mToken, mTag);
72            } catch (RemoteException ex) {
73            }
74        }
75
76        /**
77         * Reenable the keyguard.  The keyguard will reappear if the previous
78         * call to {@link #disableKeyguard()} caused it to be hidden.
79         *
80         * A good place to call this is from {@link android.app.Activity#onPause()}
81         *
82         * Note: This call has no effect while any {@link android.app.admin.DevicePolicyManager}
83         * is enabled that requires a password.
84         *
85         * <p>This method requires the caller to hold the permission
86         * {@link android.Manifest.permission#DISABLE_KEYGUARD}.
87         *
88         * @see #disableKeyguard()
89         */
90        public void reenableKeyguard() {
91            try {
92                mWM.reenableKeyguard(mToken);
93            } catch (RemoteException ex) {
94            }
95        }
96    }
97
98    /**
99     * Callback passed to {@link KeyguardManager#exitKeyguardSecurely} to notify
100     * caller of result.
101     */
102    public interface OnKeyguardExitResult {
103
104        /**
105         * @param success True if the user was able to authenticate, false if
106         *   not.
107         */
108        void onKeyguardExitResult(boolean success);
109    }
110
111
112    KeyguardManager() {
113        mWM = WindowManagerGlobal.getWindowManagerService();
114    }
115
116    /**
117     * @deprecated Use {@link android.view.WindowManager.LayoutParams#FLAG_DISMISS_KEYGUARD}
118     * and/or {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WHEN_LOCKED}
119     * instead; this allows you to seamlessly hide the keyguard as your application
120     * moves in and out of the foreground and does not require that any special
121     * permissions be requested.
122     *
123     * Enables you to lock or unlock the keyboard. Get an instance of this class by
124     * calling {@link android.content.Context#getSystemService(java.lang.String) Context.getSystemService()}.
125     * This class is wrapped by {@link android.app.KeyguardManager KeyguardManager}.
126     * @param tag A tag that informally identifies who you are (for debugging who
127     *   is disabling he keyguard).
128     *
129     * @return A {@link KeyguardLock} handle to use to disable and reenable the
130     *   keyguard.
131     */
132    @Deprecated
133    public KeyguardLock newKeyguardLock(String tag) {
134        return new KeyguardLock(tag);
135    }
136
137    /**
138     * Return whether the keyguard is currently locked.
139     *
140     * @return true if keyguard is locked.
141     */
142    public boolean isKeyguardLocked() {
143        try {
144            return mWM.isKeyguardLocked();
145        } catch (RemoteException ex) {
146            return false;
147        }
148    }
149
150    /**
151     * Return whether the keyguard requires a password to unlock.
152     *
153     * @return true if keyguard is secure.
154     */
155    public boolean isKeyguardSecure() {
156        try {
157            return mWM.isKeyguardSecure();
158        } catch (RemoteException ex) {
159            return false;
160        }
161    }
162
163    /**
164     * If keyguard screen is showing or in restricted key input mode (i.e. in
165     * keyguard password emergency screen). When in such mode, certain keys,
166     * such as the Home key and the right soft keys, don't work.
167     *
168     * @return true if in keyguard restricted input mode.
169     *
170     * @see android.view.WindowManagerPolicy#inKeyguardRestrictedKeyInputMode
171     */
172    public boolean inKeyguardRestrictedInputMode() {
173        try {
174            return mWM.inKeyguardRestrictedInputMode();
175        } catch (RemoteException ex) {
176            return false;
177        }
178    }
179
180    /**
181     * @deprecated Use {@link android.view.WindowManager.LayoutParams#FLAG_DISMISS_KEYGUARD}
182     * and/or {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WHEN_LOCKED}
183     * instead; this allows you to seamlessly hide the keyguard as your application
184     * moves in and out of the foreground and does not require that any special
185     * permissions be requested.
186     *
187     * Exit the keyguard securely.  The use case for this api is that, after
188     * disabling the keyguard, your app, which was granted permission to
189     * disable the keyguard and show a limited amount of information deemed
190     * safe without the user getting past the keyguard, needs to navigate to
191     * something that is not safe to view without getting past the keyguard.
192     *
193     * This will, if the keyguard is secure, bring up the unlock screen of
194     * the keyguard.
195     *
196     * <p>This method requires the caller to hold the permission
197     * {@link android.Manifest.permission#DISABLE_KEYGUARD}.
198     *
199     * @param callback Let's you know whether the operation was succesful and
200     *   it is safe to launch anything that would normally be considered safe
201     *   once the user has gotten past the keyguard.
202     */
203    @Deprecated
204    public void exitKeyguardSecurely(final OnKeyguardExitResult callback) {
205        try {
206            mWM.exitKeyguardSecurely(new IOnKeyguardExitResult.Stub() {
207                public void onKeyguardExitResult(boolean success) throws RemoteException {
208                    callback.onKeyguardExitResult(success);
209                }
210            });
211        } catch (RemoteException e) {
212
213        }
214    }
215}
216