1 /* 2 * Copyright (c) 2021, 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 com.android.car.telemetry.scriptexecutorinterface; 18 19 import android.os.PersistableBundle; 20 21 /** 22 * Listener for {@code IScriptExecutor#invokeScript}. 23 * 24 * An invocation of a script by Script Executor will result in a call of only one 25 * of the three methods below. If a script fully completes its objective, onScriptFinished 26 * is called. If a script's invocation completes normally, onSuccess is called. 27 * onError is called if any error happens before or during script execution and we 28 * should abandon this run of the script. 29 */ 30 interface IScriptExecutorListener { 31 /** 32 * Called by ScriptExecutor when the script declares itself as "finished". 33 * 34 * @param result final results of the script that will be uploaded. 35 */ onScriptFinished(in PersistableBundle result)36 void onScriptFinished(in PersistableBundle result); 37 38 /** 39 * Called by ScriptExecutor when a function completes successfully and also provides 40 * optional state that the script wants CarTelemetryService to persist. 41 * 42 * @param stateToPersist key-value pairs to persist 43 */ onSuccess(in @ullable PersistableBundle stateToPersist)44 void onSuccess(in @nullable PersistableBundle stateToPersist); 45 46 /** 47 * Called by ScriptExecutor to report errors that prevented the script 48 * from running or completing execution successfully. 49 * 50 * @param errorType type of the error message as defined in this aidl file. 51 * @param messsage the human-readable message containing information helpful for analysis or debugging. 52 * @param stackTrace the stack trace of the error if available. 53 */ onError(int errorType, String message, @nullable String stackTrace)54 void onError(int errorType, String message, @nullable String stackTrace); 55 56 /** 57 * Called by ScriptExecutor when a function completes successfully and produces a 58 * metrics report. The script is not "finished" yet. 59 * It can also provide optional state that the script wants CarTelemetryService to persist. 60 * 61 * @param report metrics report that will be uploaded. 62 * @param stateToPersist key-value pairs to persist 63 */ onMetricsReport( in PersistableBundle report, in @nullable PersistableBundle stateToPersist)64 void onMetricsReport( 65 in PersistableBundle report, 66 in @nullable PersistableBundle stateToPersist); 67 68 /** 69 * Any changes to the following ERROR_TYPE_* constants must be also reflected in the following files: 70 * p/s/C/packages/ScriptExecutor/src/ScriptExecutorListener.h 71 * p/s/C/car-lib/src/android/car/telemetry/telemetry.proto 72 */ 73 74 /** 75 * Default error type. 76 */ 77 const int ERROR_TYPE_UNSPECIFIED = 0; 78 79 /** 80 * Used when an error occurs in the ScriptExecutor code. 81 */ 82 const int ERROR_TYPE_SCRIPT_EXECUTOR_ERROR = 1; 83 84 /** 85 * Used when an error occurs while executing the Lua script (such as 86 * errors returned by lua_pcall) 87 */ 88 const int ERROR_TYPE_LUA_RUNTIME_ERROR = 2; 89 90 /** 91 * Used to log errors by a script itself, for instance, when a script received 92 * inputs outside of expected range. 93 */ 94 const int ERROR_TYPE_LUA_SCRIPT_ERROR = 3; 95 96 /** 97 * Used to log errors due to publisher failure. 98 */ 99 const int ERROR_TYPE_PUBLISHER_FAILED = 4; 100 } 101 102