1 /*
2  * Copyright (C) 2024 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.os;
18 
19 import android.annotation.FlaggedApi;
20 import android.annotation.IntDef;
21 import android.annotation.NonNull;
22 import android.annotation.Nullable;
23 import android.os.profiling.Flags;
24 
25 import java.lang.annotation.Retention;
26 import java.lang.annotation.RetentionPolicy;
27 
28 /**
29  * Encapsulates results of a single profiling request operation.
30  */
31 @FlaggedApi(Flags.FLAG_TELEMETRY_APIS)
32 public final class ProfilingResult implements Parcelable {
33 
34     /** @see #getErrorCode */
35     final @ErrorCode int mErrorCode;
36 
37     /** @see #getResultFilePath */
38     @Nullable final String mResultFilePath;
39 
40     /** @see #getTag */
41     @Nullable final String mTag;
42 
43     /** @see #getErrorMessage */
44     @Nullable final String mErrorMessage;
45 
46     /** The request was executed and succeeded. */
47     public static final int ERROR_NONE = 0;
48 
49     /** The request was denied due to system level rate limiting. */
50     public static final int ERROR_FAILED_RATE_LIMIT_SYSTEM = 1;
51 
52     /** The request was denied due to process level rate limiting. */
53     public static final int ERROR_FAILED_RATE_LIMIT_PROCESS = 2;
54 
55     /** The request was denied due to profiling already in progress. */
56     public static final int ERROR_FAILED_PROFILING_IN_PROGRESS = 3;
57 
58     /** The request was executed and failed for a reason not specified below. */
59     public static final int ERROR_FAILED_EXECUTING = 4;
60 
61     /** The request was executed but post processing failed and the result was discarded. */
62     public static final int ERROR_FAILED_POST_PROCESSING = 5;
63 
64     /** The request was executed and failed due to a lack of disk space. */
65     public static final int ERROR_FAILED_NO_DISK_SPACE = 6;
66 
67     /** The request failed due to invalid ProfilingRequest. */
68     public static final int ERROR_FAILED_INVALID_REQUEST = 7;
69 
70     /** The request was denied or failed for an unspecified reason. */
71     public static final int ERROR_UNKNOWN = 8;
72 
73     /** @hide */
74     @IntDef(value = {
75             ERROR_NONE,
76             ERROR_FAILED_RATE_LIMIT_SYSTEM,
77             ERROR_FAILED_RATE_LIMIT_PROCESS,
78             ERROR_FAILED_PROFILING_IN_PROGRESS,
79             ERROR_FAILED_EXECUTING,
80             ERROR_FAILED_POST_PROCESSING,
81             ERROR_FAILED_NO_DISK_SPACE,
82             ERROR_UNKNOWN,
83     })
84     @Retention(RetentionPolicy.SOURCE)
85     @interface ErrorCode {}
86 
ProfilingResult(@rrorCode int errorCode, String resultFilePath, String tag, String errorMessage)87     ProfilingResult(@ErrorCode int errorCode, String resultFilePath, String tag,
88             String errorMessage) {
89         mErrorCode = errorCode;
90         mResultFilePath = resultFilePath;
91         mTag = tag;
92         mErrorMessage = errorMessage;
93     }
94 
ProfilingResult(@onNull Parcel in)95     private ProfilingResult(@NonNull Parcel in) {
96         mErrorCode = in.readInt();
97         mResultFilePath = in.readString();
98         mTag = in.readString();
99         mErrorMessage = in.readString();
100     }
101 
102     @Override
writeToParcel(@onNull Parcel dest, int flags)103     public void writeToParcel(@NonNull Parcel dest, int flags) {
104         dest.writeInt(mErrorCode);
105         dest.writeString(mResultFilePath);
106         dest.writeString(mTag);
107         dest.writeString(mErrorMessage);
108     }
109 
110     @Override
describeContents()111     public int describeContents() {
112         return 0;
113     }
114 
115     public @NonNull static final Creator<ProfilingResult> CREATOR =
116             new Creator<ProfilingResult>() {
117                 @Override
118                 public ProfilingResult createFromParcel(Parcel in) {
119                     return new ProfilingResult(in);
120                 }
121 
122                 @Override
123                 public ProfilingResult[] newArray(int size) {
124                     return new ProfilingResult[size];
125                 }
126             };
127 
128     /**
129      * The result ErrorCode for the profiling request indicating the failure reason if applicable.
130      */
getErrorCode()131     public @ErrorCode int getErrorCode() {
132         return mErrorCode;
133     }
134 
135     /**
136      * The file path of the profiling result data.
137      *
138      * Will be null if {@see #getErrorCode} returns code other than {@see #ERROR_NONE}.
139      */
getResultFilePath()140     public @Nullable String getResultFilePath() {
141         return mResultFilePath;
142     }
143 
144     /**
145      * The tag defined by the caller at request time.
146      */
getTag()147     public @Nullable String getTag() {
148         return mTag;
149     }
150 
151     /**
152      * Additional details about failures that occurred, if applicable.
153      */
getErrorMessage()154     public @Nullable String getErrorMessage() {
155         return mErrorMessage;
156     }
157 }
158