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 - text */ 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_MIN = RADIO_METADATA_KEY_RDS_PI, 46 RADIO_METADATA_KEY_MAX = RADIO_METADATA_KEY_ART, 47 }; 48 typedef int radio_metadata_key_t; 49 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 }; 58 typedef int radio_metadata_type_t; 59 60 /* 61 * Return the type of the meta data corresponding to the key specified 62 * 63 * arguments: 64 * - key: the meta data key. 65 * 66 * returns: 67 * the meta data type corresponding to the key or RADIO_METADATA_TYPE_INVALID 68 */ 69 ANDROID_API 70 radio_metadata_type_t radio_metadata_type_of_key(const radio_metadata_key_t key); 71 72 /* 73 * Allocate a meta data buffer for use by radio HAL callback for RADIO_EVENT_TUNED and 74 * RADIO_EVENT_METADATA events. 75 * 76 * arguments: 77 * - metadata: the address where the allocate meta data buffer should be returned. 78 * - channel: channel (frequency) this meta data is associated with. 79 * - sub_channel: sub channel this meta data is associated with. 80 * 81 * returns: 82 * 0 if successfully allocated 83 * -ENOMEM if meta data buffer cannot be allocated 84 */ 85 ANDROID_API 86 int radio_metadata_allocate(radio_metadata_t **metadata, 87 const unsigned int channel, 88 const unsigned int sub_channel); 89 90 /* 91 * De-allocate a meta data buffer. 92 * 93 * arguments: 94 * - metadata: the meta data buffer to be de-allocated. 95 */ 96 ANDROID_API 97 void radio_metadata_deallocate(radio_metadata_t *metadata); 98 99 /* 100 * Add an integer meta data to the buffer. 101 * 102 * arguments: 103 * - metadata: the address of the meta data buffer. I/O. the meta data can be modified if the 104 * buffer is re-allocated 105 * - key: the meta data key. 106 * - value: the meta data value. 107 * 108 * returns: 109 * 0 if successfully added 110 * -EINVAL if the buffer passed is invalid or the key does not match an integer type 111 * -ENOMEM if meta data buffer cannot be re-allocated 112 */ 113 ANDROID_API 114 int radio_metadata_add_int(radio_metadata_t **metadata, 115 const radio_metadata_key_t key, 116 const int value); 117 118 /* 119 * Add an text meta data to the buffer. 120 * 121 * arguments: 122 * - metadata: the address of the meta data buffer. I/O. the meta data can be modified if the 123 * buffer is re-allocated 124 * - key: the meta data key. 125 * - value: the meta data value. 126 * 127 * returns: 128 * 0 if successfully added 129 * -EINVAL if the buffer passed is invalid or the key does not match a text type or text 130 * is too long 131 * -ENOMEM if meta data buffer cannot be re-allocated 132 */ 133 ANDROID_API 134 int radio_metadata_add_text(radio_metadata_t **metadata, 135 const radio_metadata_key_t key, 136 const char *value); 137 138 /* 139 * Add an raw meta data to the buffer. 140 * 141 * arguments: 142 * - metadata: the address of the meta data buffer. I/O. the meta data can be modified if the 143 * buffer is re-allocated 144 * - key: the meta data key. 145 * - value: the meta data value. 146 * 147 * returns: 148 * 0 if successfully added 149 * -EINVAL if the buffer passed is invalid or the key does not match a raw type 150 * -ENOMEM if meta data buffer cannot be re-allocated 151 */ 152 ANDROID_API 153 int radio_metadata_add_raw(radio_metadata_t **metadata, 154 const radio_metadata_key_t key, 155 const unsigned char *value, 156 const unsigned int size); 157 158 /* 159 * add all meta data in source buffer to destinaiton buffer. 160 * 161 * arguments: 162 * - dst_metadata: the address of the destination meta data buffer. if *dst_metadata is NULL, 163 * a new buffer is created. 164 * - src_metadata: the source meta data buffer. 165 * 166 * returns: 167 * 0 if successfully added 168 * -ENOMEM if meta data buffer cannot be re-allocated 169 */ 170 ANDROID_API 171 int radio_metadata_add_metadata(radio_metadata_t **dst_metadata, 172 radio_metadata_t *src_metadata); 173 174 /* 175 * Perform sanity check on a meta data buffer. 176 * 177 * arguments: 178 * - metadata: the meta data buffer. 179 * 180 * returns: 181 * 0 if no error found 182 * -EINVAL if a consistency problem is found in the meta data buffer 183 */ 184 ANDROID_API 185 int radio_metadata_check(const radio_metadata_t *metadata); 186 187 /* 188 * Return the total size used by the meta data buffer. 189 * No sanity check is performed on the meta data buffer. 190 * 191 * arguments: 192 * - metadata: the meta data buffer. 193 * 194 * returns: 195 * 0 if an invalid meta data buffer is passed 196 * the size in bytes otherwise 197 */ 198 ANDROID_API 199 size_t radio_metadata_get_size(const radio_metadata_t *metadata); 200 201 /* 202 * Return the number of meta data entries in the buffer. 203 * No sanity check is performed on the meta data buffer. 204 * 205 * arguments: 206 * - metadata: the meta data buffer. 207 * 208 * returns: 209 * -EINVAL if an invalid meta data buffer is passed 210 * the number of entries otherwise 211 */ 212 ANDROID_API 213 int radio_metadata_get_count(const radio_metadata_t *metadata); 214 215 /* 216 * Get a meta data at a specified index. Used to parse a meta data buffer. 217 * No sanity check is performed on the meta data buffer. 218 * 219 * arguments: 220 * - metadata: the meta data buffer. 221 * - index: the index to read from 222 * - key: where the meta data key should be returned 223 * - type: where the meta data type should be returned 224 * - value: where the address of the meta data value should be returned 225 * - size: where the size of the meta data value should be returned 226 * 227 * returns: 228 * -EINVAL if an invalid argument is passed 229 * 0 otherwise 230 */ 231 ANDROID_API 232 int radio_metadata_get_at_index(const radio_metadata_t *metadata, 233 const unsigned int index, 234 radio_metadata_key_t *key, 235 radio_metadata_type_t *type, 236 void **value, 237 unsigned int *size); 238 239 /* 240 * Get a meta data with the specified key. 241 * No sanity check is performed on the meta data buffer. 242 * This will return the first meta data found with the matching key. 243 * 244 * arguments: 245 * - metadata: the meta data buffer. 246 * - index: the index to read from 247 * - key: the meta data key to look for 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 * -ENOENT if no entry with the specified key is found 255 * 0 otherwise 256 */ 257 ANDROID_API 258 int radio_metadata_get_from_key(const radio_metadata_t *metadata, 259 const radio_metadata_key_t key, 260 radio_metadata_type_t *type, 261 void **value, 262 unsigned int *size); 263 264 #ifdef __cplusplus 265 } 266 #endif 267 268 #endif // ANDROID_RADIO_METADATA_H 269