1/*
2 * Copyright (C) 2017 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.ContentProvider;
20import android.content.ContentResolver;
21import android.os.Parcel;
22import android.os.Parcelable;
23
24import com.android.internal.util.Preconditions;
25
26/**
27 * Specialization of {@link SecurityException} that is thrown when authentication is needed from the
28 * end user before viewing the content.
29 * <p>
30 * This exception is only appropriate where there is a concrete action the user can take to
31 * authorize and make forward progress, such as confirming or entering authentication credentials,
32 * or granting access via other means.
33 * <p class="note">
34 * Note: legacy code that receives this exception may treat it as a general
35 * {@link SecurityException}, and thus there is no guarantee that the action contained will be
36 * invoked by the user.
37 * </p>
38 */
39public final class AuthenticationRequiredException extends SecurityException implements Parcelable {
40    private static final String TAG = "AuthenticationRequiredException";
41
42    private final PendingIntent mUserAction;
43
44    /** {@hide} */
45    public AuthenticationRequiredException(Parcel in) {
46        this(new SecurityException(in.readString()), PendingIntent.CREATOR.createFromParcel(in));
47    }
48
49    /**
50     * Create an instance ready to be thrown.
51     *
52     * @param cause original cause with details designed for engineering
53     *            audiences.
54     * @param userAction primary action that will initiate the recovery. This
55     *            must launch an activity that is expected to set
56     *            {@link Activity#setResult(int)} before finishing to
57     *            communicate the final status of the recovery. For example,
58     *            apps that observe {@link Activity#RESULT_OK} may choose to
59     *            immediately retry their operation.
60     */
61    public AuthenticationRequiredException(Throwable cause, PendingIntent userAction) {
62        super(cause.getMessage());
63        mUserAction = Preconditions.checkNotNull(userAction);
64    }
65
66    /**
67     * Return primary action that will initiate the authorization.
68     */
69    public PendingIntent getUserAction() {
70        return mUserAction;
71    }
72
73    @Override
74    public int describeContents() {
75        return 0;
76    }
77
78    @Override
79    public void writeToParcel(Parcel dest, int flags) {
80        dest.writeString(getMessage());
81        mUserAction.writeToParcel(dest, flags);
82    }
83
84    public static final Creator<AuthenticationRequiredException> CREATOR =
85            new Creator<AuthenticationRequiredException>() {
86        @Override
87        public AuthenticationRequiredException createFromParcel(Parcel source) {
88            return new AuthenticationRequiredException(source);
89        }
90
91        @Override
92        public AuthenticationRequiredException[] newArray(int size) {
93            return new AuthenticationRequiredException[size];
94        }
95    };
96}
97