1 /* 2 * Copyright (C) 2015 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 #ifndef ANDROID_RADIO_METADATA_H 18 #define ANDROID_RADIO_METADATA_H 19 20 #include <stdbool.h> 21 #include <cutils/compiler.h> 22 #include <system/radio.h> 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /* maximum length for text metadata including NUL terminator */ 29 #define RADIO_METADATA_TEXT_LEN_MAX 1024 30 31 /* radio meta data key values */ 32 enum { 33 RADIO_METADATA_KEY_INVALID = -1, 34 RADIO_METADATA_KEY_RDS_PI = 0, /* RDS PI - int */ 35 RADIO_METADATA_KEY_RDS_PS = 1, /* RDS PS - text */ 36 RADIO_METADATA_KEY_RDS_PTY = 2, /* RDS PTY - int */ 37 RADIO_METADATA_KEY_RBDS_PTY = 3, /* RBDS PTY - int */ 38 RADIO_METADATA_KEY_RDS_RT = 4, /* RDS RT - text */ 39 RADIO_METADATA_KEY_TITLE = 5, /* Song title - text */ 40 RADIO_METADATA_KEY_ARTIST = 6, /* Artist name - text */ 41 RADIO_METADATA_KEY_ALBUM = 7, /* Album name - text */ 42 RADIO_METADATA_KEY_GENRE = 8, /* Musical genre - text */ 43 RADIO_METADATA_KEY_ICON = 9, /* Station icon - raw */ 44 RADIO_METADATA_KEY_ART = 10, /* Album art - raw */ 45 RADIO_METADATA_KEY_CLOCK = 11, /* Clock - radio_metadata_clock_t */ 46 RADIO_METADATA_KEY_MIN = RADIO_METADATA_KEY_RDS_PI, 47 RADIO_METADATA_KEY_MAX = RADIO_METADATA_KEY_CLOCK, 48 }; 49 typedef int32_t radio_metadata_key_t; 50 51 enum { 52 RADIO_METADATA_TYPE_INVALID = -1, 53 RADIO_METADATA_TYPE_INT = 0, /* signed 32 bit integer */ 54 RADIO_METADATA_TYPE_TEXT = 1, /* text in UTF-8 format, NUL terminated. 55 RADIO_METADATA_TEXT_LEN_MAX length including NUL. */ 56 RADIO_METADATA_TYPE_RAW = 2, /* raw binary data (icon or art) */ 57 RADIO_METADATA_TYPE_CLOCK = 3, /* clock data, see radio_metadata_clock_t */ 58 }; 59 typedef int32_t radio_metadata_type_t; 60 61 typedef struct radio_metadata_clock { 62 uint64_t utc_seconds_since_epoch; /* Seconds since epoch at GMT + 0. */ 63 int32_t timezone_offset_in_minutes; /* Minutes offset from the GMT. */ 64 } radio_metadata_clock_t; 65 66 /* 67 * Return the type of the meta data corresponding to the key specified 68 * 69 * arguments: 70 * - key: the meta data key. 71 * 72 * returns: 73 * the meta data type corresponding to the key or RADIO_METADATA_TYPE_INVALID 74 */ 75 ANDROID_API 76 radio_metadata_type_t radio_metadata_type_of_key(const radio_metadata_key_t key); 77 78 /* 79 * Allocate a meta data buffer for use by radio HAL callback for RADIO_EVENT_TUNED and 80 * RADIO_EVENT_METADATA events. 81 * 82 * arguments: 83 * - metadata: the address where the allocate meta data buffer should be returned. 84 * - channel: channel (frequency) this meta data is associated with. 85 * - sub_channel: sub channel this meta data is associated with. 86 * 87 * returns: 88 * 0 if successfully allocated 89 * -ENOMEM if meta data buffer cannot be allocated 90 */ 91 ANDROID_API 92 int radio_metadata_allocate(radio_metadata_t **metadata, 93 const uint32_t channel, 94 const uint32_t sub_channel); 95 96 /* 97 * De-allocate a meta data buffer. 98 * 99 * arguments: 100 * - metadata: the meta data buffer to be de-allocated. 101 */ 102 ANDROID_API 103 void radio_metadata_deallocate(radio_metadata_t *metadata); 104 105 /* 106 * Add an integer meta data to the buffer. 107 * 108 * arguments: 109 * - metadata: the address of the meta data buffer. I/O. the meta data can be modified if the 110 * buffer is re-allocated 111 * - key: the meta data key. 112 * - value: the meta data value. 113 * 114 * returns: 115 * 0 if successfully added 116 * -EINVAL if the buffer passed is invalid or the key does not match an integer type 117 * -ENOMEM if meta data buffer cannot be re-allocated 118 */ 119 ANDROID_API 120 int radio_metadata_add_int(radio_metadata_t **metadata, 121 const radio_metadata_key_t key, 122 const int32_t value); 123 124 /* 125 * Add an text meta data to the buffer. 126 * 127 * arguments: 128 * - metadata: the address of the meta data buffer. I/O. the meta data can be modified if the 129 * buffer is re-allocated 130 * - key: the meta data key. 131 * - value: the meta data value. 132 * 133 * returns: 134 * 0 if successfully added 135 * -EINVAL if the buffer passed is invalid or the key does not match a text type or text 136 * is too long 137 * -ENOMEM if meta data buffer cannot be re-allocated 138 */ 139 ANDROID_API 140 int radio_metadata_add_text(radio_metadata_t **metadata, 141 const radio_metadata_key_t key, 142 const char *value); 143 144 /* 145 * Add an raw meta data to the buffer. 146 * 147 * arguments: 148 * - metadata: the address of the meta data buffer. I/O. the meta data can be modified if the 149 * buffer is re-allocated 150 * - key: the meta data key. 151 * - value: the meta data value. 152 * 153 * returns: 154 * 0 if successfully added 155 * -EINVAL if the buffer passed is invalid or the key does not match a raw type 156 * -ENOMEM if meta data buffer cannot be re-allocated 157 */ 158 ANDROID_API 159 int radio_metadata_add_raw(radio_metadata_t **metadata, 160 const radio_metadata_key_t key, 161 const unsigned char *value, 162 const size_t size); 163 164 /* 165 * Add a clock meta data to the buffer. 166 * 167 * arguments: 168 * - metadata: the address of the meta data buffer. I/O. the meta data can be modified if the 169 * buffer is re-allocated. 170 * - key: the meta data key. 171 * - value: the meta data value. 172 * 173 * returns: 174 * 0 if successfully added 175 * - EINVAL if the buffer passed is invalid or the key does not match a raw type 176 * - ENOMEM if meta data buffer cannot be re-allocated 177 */ 178 ANDROID_API 179 int radio_metadata_add_clock(radio_metadata_t **metadata, 180 const radio_metadata_key_t key, 181 const radio_metadata_clock_t *clock); 182 183 /* 184 * add all meta data in source buffer to destinaiton buffer. 185 * 186 * arguments: 187 * - dst_metadata: the address of the destination meta data buffer. if *dst_metadata is NULL, 188 * a new buffer is created. 189 * - src_metadata: the source meta data buffer. 190 * 191 * returns: 192 * 0 if successfully added 193 * -ENOMEM if meta data buffer cannot be re-allocated 194 */ 195 ANDROID_API 196 int radio_metadata_add_metadata(radio_metadata_t **dst_metadata, 197 radio_metadata_t *src_metadata); 198 199 /* 200 * Perform sanity check on a meta data buffer. 201 * 202 * arguments: 203 * - metadata: the meta data buffer. 204 * 205 * returns: 206 * 0 if no error found 207 * -EINVAL if a consistency problem is found in the meta data buffer 208 */ 209 ANDROID_API 210 int radio_metadata_check(const radio_metadata_t *metadata); 211 212 /* 213 * Return the total size used by the meta data buffer. 214 * No sanity check is performed on the meta data buffer. 215 * 216 * arguments: 217 * - metadata: the meta data buffer. 218 * 219 * returns: 220 * 0 if an invalid meta data buffer is passed 221 * the size in bytes otherwise 222 */ 223 ANDROID_API 224 size_t radio_metadata_get_size(const radio_metadata_t *metadata); 225 226 /* 227 * Return the number of meta data entries in the buffer. 228 * No sanity check is performed on the meta data buffer. 229 * 230 * arguments: 231 * - metadata: the meta data buffer. 232 * 233 * returns: 234 * -EINVAL if an invalid meta data buffer is passed 235 * the number of entries otherwise 236 */ 237 ANDROID_API 238 int radio_metadata_get_count(const radio_metadata_t *metadata); 239 240 /* 241 * Get a meta data at a specified index. Used to parse a meta data buffer. 242 * No sanity check is performed on the meta data buffer. 243 * 244 * arguments: 245 * - metadata: the meta data buffer. 246 * - index: the index to read from 247 * - key: where the meta data key should be returned 248 * - type: where the meta data type should be returned 249 * - value: where the address of the meta data value should be returned 250 * - size: where the size of the meta data value should be returned 251 * 252 * returns: 253 * -EINVAL if an invalid argument is passed 254 * 0 otherwise 255 */ 256 ANDROID_API 257 int radio_metadata_get_at_index(const radio_metadata_t *metadata, 258 const uint32_t index, 259 radio_metadata_key_t *key, 260 radio_metadata_type_t *type, 261 void **value, 262 size_t *size); 263 264 /* 265 * Get a meta data with the specified key. 266 * No sanity check is performed on the meta data buffer. 267 * This will return the first meta data found with the matching key. 268 * 269 * arguments: 270 * - metadata: the meta data buffer. 271 * - index: the index to read from 272 * - key: the meta data key to look for 273 * - type: where the meta data type should be returned 274 * - value: where the address of the meta data value should be returned 275 * - size: where the size of the meta data value should be returned 276 * 277 * returns: 278 * -EINVAL if an invalid argument is passed 279 * -ENOENT if no entry with the specified key is found 280 * 0 otherwise 281 */ 282 ANDROID_API 283 int radio_metadata_get_from_key(const radio_metadata_t *metadata, 284 const radio_metadata_key_t key, 285 radio_metadata_type_t *type, 286 void **value, 287 size_t *size); 288 289 /* 290 * Get channel and sub channel associated with metadata. 291 * 292 * arguments: 293 * - metadata: the meta data buffer 294 * - channel: address where to return the channel. 295 * - sub_channel: address where to return the sub channel. 296 * 297 * returns: 298 * 0 if successfully added 299 * -EINVAL if the buffer passed is invalid 300 */ 301 ANDROID_API 302 int radio_metadata_get_channel(radio_metadata_t *metadata, 303 uint32_t *channel, 304 uint32_t *sub_channel); 305 306 #ifdef __cplusplus 307 } 308 #endif 309 310 #endif // ANDROID_RADIO_METADATA_H 311