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