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 #pragma once 18 19 #include <sys/cdefs.h> 20 #include <stdint.h> 21 22 #include <android/api-level.h> 23 #include <android/versioning.h> 24 25 __BEGIN_DECLS 26 27 /** 28 * Enums and types that represent parameters in ApexCodecs. 29 * 30 * NOTE: Many of the constants and types mirror the ones in the Codec 2.0 API. 31 */ 32 33 /** 34 * Enum that represents the query type for the supported values. 35 * 36 * Introduced in API 36. 37 */ 38 typedef enum ApexCodec_SupportedValuesQueryType : uint32_t { 39 /** Query all possible supported values regardless of current configuration */ 40 APEXCODEC_SUPPORTED_VALUES_QUERY_POSSIBLE, 41 /** Query supported values at current configuration */ 42 APEXCODEC_SUPPORTED_VALUES_QUERY_CURRENT, 43 } ApexCodec_SupportedValuesQueryType; 44 45 /** 46 * Enum that represents the type of the supported values. 47 * 48 * Introduced in API 36. 49 */ 50 typedef enum ApexCodec_SupportedValuesType : uint32_t { 51 /** The supported values are empty. */ 52 APEXCODEC_SUPPORTED_VALUES_EMPTY, 53 /** 54 * The supported values are represented by a range defined with {min, max, step, num, den}. 55 * 56 * If step is 0 and num and denom are both 1, the supported values are any value, for which 57 * min <= value <= max. 58 * 59 * Otherwise, the range represents a geometric/arithmetic/multiply-accumulate series, where 60 * successive supported values can be derived from previous values (starting at min), using the 61 * following formula: 62 * v[0] = min 63 * v[i] = v[i-1] * num / denom + step for i >= 1, while min < v[i] <= max. 64 */ 65 APEXCODEC_SUPPORTED_VALUES_RANGE, 66 /** The supported values are represented by a list of values. */ 67 APEXCODEC_SUPPORTED_VALUES_VALUES, 68 /** The supported values are represented by a list of flags. */ 69 APEXCODEC_SUPPORTED_VALUES_FLAGS, 70 } ApexCodec_SupportedValuesType; 71 72 /** 73 * Enum that represents numeric types of the supported values. 74 * 75 * Introduced in API 36. 76 */ 77 typedef enum ApexCodec_SupportedValuesNumberType : uint32_t { 78 APEXCODEC_SUPPORTED_VALUES_TYPE_NONE = 0, 79 APEXCODEC_SUPPORTED_VALUES_TYPE_INT32 = 1, 80 APEXCODEC_SUPPORTED_VALUES_TYPE_UINT32 = 2, 81 // RESERVED = 3, 82 APEXCODEC_SUPPORTED_VALUES_TYPE_INT64 = 4, 83 APEXCODEC_SUPPORTED_VALUES_TYPE_UINT64 = 5, 84 // RESERVED = 6, 85 APEXCODEC_SUPPORTED_VALUES_TYPE_FLOAT = 7, 86 } ApexCodec_SupportedValuesNumberType; 87 88 /** 89 * Union of primitive types. 90 * 91 * Introduced in API 36. 92 */ 93 typedef union { 94 int32_t i32; 95 uint32_t u32; 96 int64_t i64; 97 uint64_t u64; 98 float f; 99 } ApexCodec_Value; 100 101 /** 102 * Enum that represents the failure code of ApexCodec_SettingResults. 103 * 104 * Introduced in API 36. 105 */ 106 typedef enum ApexCodec_SettingResultFailure : uint32_t { 107 /** parameter type is not supported */ 108 APEXCODEC_SETTING_RESULT_BAD_TYPE, 109 /** parameter is not supported on the specific port */ 110 APEXCODEC_SETTING_RESULT_BAD_PORT, 111 /** parameter is not supported on the specific stream */ 112 APEXCODEC_SETTING_RESULT_BAD_INDEX, 113 /** parameter is read-only */ 114 APEXCODEC_SETTING_RESULT_READ_ONLY, 115 /** parameter mismatches input data */ 116 APEXCODEC_SETTING_RESULT_MISMATCH, 117 /** strict parameter does not accept value for the field at all */ 118 APEXCODEC_SETTING_RESULT_BAD_VALUE, 119 /** strict parameter field value conflicts with another settings */ 120 APEXCODEC_SETTING_RESULT_CONFLICT, 121 /** strict parameter field is out of range due to other settings */ 122 APEXCODEC_SETTING_RESULT_UNSUPPORTED, 123 /** 124 * field does not accept the requested parameter value at all. It has been corrected to 125 * the closest supported value. This failure mode is provided to give guidance as to what 126 * are the currently supported values for this field (which may be a subset of the at-all- 127 * potential values) 128 */ 129 APEXCODEC_SETTING_RESULT_INFO_BAD_VALUE, 130 /** 131 * requested parameter value is in conflict with an/other setting(s) 132 * and has been corrected to the closest supported value. This failure 133 * mode is given to provide guidance as to what are the currently supported values as well 134 * as to optionally provide suggestion to the client as to how to enable the requested 135 * parameter value. 136 */ 137 APEXCODEC_SETTING_RESULT_INFO_CONFLICT, 138 } ApexCodec_SettingResultFailure; 139 140 /* forward-declaration for an opaque struct */ 141 struct ApexCodec_SupportedValues; 142 143 /** 144 * Struct that represents a field and its supported values of a parameter. 145 * 146 * The offset and size of the field are where the field is located in the blob representation of 147 * the parameter, as used in the ApexCodec_Configurable_query() and ApexCodec_Configurable_config(), 148 * for example. 149 * 150 * Introduced in API 36. 151 */ 152 typedef struct ApexCodec_ParamFieldValues { 153 /** index of the param */ 154 uint32_t index; 155 /** offset of the param field */ 156 uint32_t offset; 157 /** size of the param field */ 158 uint32_t size; 159 /** currently supported values of the param field */ 160 struct ApexCodec_SupportedValues *_Nullable values; 161 } ApexCodec_ParamFieldValues; 162 163 /** 164 * Enum that represents the attributes of a parameter. 165 * 166 * Introduced in API 36. 167 */ 168 typedef enum ApexCodec_ParamAttribute : uint32_t { 169 /** parameter is required to be specified */ 170 APEXCODEC_PARAM_IS_REQUIRED = 1u << 0, 171 /** parameter retains its value */ 172 APEXCODEC_PARAM_IS_PERSISTENT = 1u << 1, 173 /** parameter is strict */ 174 APEXCODEC_PARAM_IS_STRICT = 1u << 2, 175 /** 176 * parameter is read-only; the value may change if other parameters are changed, 177 * but the client cannot modify the value directly. 178 */ 179 APEXCODEC_PARAM_IS_READ_ONLY = 1u << 3, 180 /** parameter shall not be visible to clients */ 181 APEXCODEC_PARAM_IS_HIDDEN = 1u << 4, 182 /** parameter shall not be used by framework (other than testing) */ 183 APEXCODEC_PARAM_IS_INTERNAL = 1u << 5, 184 /** 185 * parameter is publicly const (hence read-only); the parameter never changes. 186 */ 187 APEXCODEC_PARAM_IS_CONSTANT = 1u << 6 | APEXCODEC_PARAM_IS_READ_ONLY, 188 } ApexCodec_ParamAttribute; 189 190 __END_DECLS