Home | History | Annotate | Download | only in system
      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_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 int 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 int 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 unsigned int channel,
     94                             const unsigned int 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 int 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 unsigned int 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 unsigned int index,
    259                                 radio_metadata_key_t *key,
    260                                 radio_metadata_type_t *type,
    261                                 void **value,
    262                                 unsigned int *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                                 unsigned int *size);
    288 
    289 #ifdef __cplusplus
    290 }
    291 #endif
    292 
    293 #endif  // ANDROID_RADIO_METADATA_H
    294