1/*
2 * Copyright 2016 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
17package android.hardware.broadcastradio@1.0;
18
19enum Result : int32_t {
20    OK,
21    NOT_INITIALIZED,
22    INVALID_ARGUMENTS,
23    INVALID_STATE,
24    TIMEOUT,
25};
26
27/**
28 * Radio hardware module class. A given radio hardware module HAL is of one
29 * class only. The platform can not have more than one hardware module of
30 * each class. Current version of the framework only supports RADIO_CLASS_AM_FM.
31 */
32enum Class : uint32_t {
33    /** FM (including HD radio) and AM */
34    AM_FM = 0,
35    /** Satellite Radio */
36    SAT   = 1,
37    /** Digital Radio (DAB) */
38    DT    = 2,
39};
40
41/** value for field "type" of radio band described in struct radio_hal_band_config */
42enum Band : uint32_t {
43    /** Amplitude Modulation band: LW, MW, SW */
44    AM     = 0,
45    /** Frequency Modulation band: FM */
46    FM     = 1,
47    /** FM HD Radio / DRM (IBOC) */
48    FM_HD  = 2,
49    /** AM HD Radio / DRM (IBOC) */
50    AM_HD  = 3,
51};
52
53/** RDS variant implemented. A struct FmBandConfig can list none or several. */
54enum Rds : uint32_t {
55    NONE   = 0,
56    WORLD  = (1<<0),
57    US = (1<<1),
58};
59
60
61/* FM deemphasis variant implemented.
62 * A struct FmBandConfig can list one or more. */
63enum Deemphasis : uint32_t {
64    D50   = (1<<0),
65    D75   = (1<<1),
66};
67
68/** Scanning direction for scan() and step() tuner APIs */
69enum Direction : uint32_t {
70    UP,
71    DOWN
72};
73
74/** Unique handle allocated to a radio module */
75typedef uint32_t Handle;
76
77
78/** Additional attributes for an FM band configuration */
79struct FmBandConfig {
80    /** deemphasis variant */
81    Deemphasis deemphasis;
82    /** stereo supported */
83    bool       stereo;
84    /** RDS variants supported */
85    Rds        rds;
86    /** Traffic Announcement supported */
87    bool       ta;
88    /** Alternate Frequency supported */
89    bool       af;
90    /** Emergency announcements supported */
91    bool       ea;
92};
93
94/** Additional attributes for an AM band configuration */
95struct AmBandConfig {
96    /** Stereo supported */
97    bool       stereo;
98};
99
100/* Radio band configuration. Describes a given band supported by the radio
101 * module. The HAL can expose only one band per type with the the maximum range
102 * supported and all options. The framework will derive the actual regions were
103 * this module can operate and expose separate band configurations for
104 * applications to chose from. */
105struct BandConfig {
106    Band type;
107    bool antennaConnected;
108    uint32_t lowerLimit;
109    uint32_t upperLimit;
110    vec<uint32_t> spacings;
111    union Ext {
112        FmBandConfig fm;
113        AmBandConfig am;
114    } ext;
115};
116
117/* Exposes properties of a given hardware radio module.
118 * NOTE: current framework implementation supports only one audio source
119 * (num_audio_sources = 1). The source corresponds to AUDIO_DEVICE_IN_FM_TUNER.
120 * If more than one tuner is supported (num_tuners > 1), only one can be
121 * connected to the audio source. */
122struct Properties {
123    /** Class of this module. E.g AM_FM */
124    Class           classId;
125    /** implementor name */
126    string          implementor;
127    /** product name */
128    string          product;
129    /** product version */
130    string          version;
131    /** serial number (for subscription services) */
132    string          serial;
133    /** number of tuners controllable independently */
134    uint32_t        numTuners;
135    /** number of audio sources driven simultaneously */
136    uint32_t        numAudioSources;
137    /** the hardware supports capture of audio source from audio HAL */
138    bool            supportsCapture;
139    /** band descriptors */
140    vec<BandConfig> bands;
141};
142
143enum MetadataType : int32_t {
144    INVALID    = -1,
145    /** Signed 32 bit integer  */
146    INT        = 0,
147    /** String */
148    TEXT       = 1,
149    /**
150     * Raw binary data (icon or art).
151     *
152     * The data should be a valid PNG, JPEG, GIF or BMP file.
153     * Invalid format must be handled gracefully as if the field was missing.
154     */
155    RAW        = 2,
156    /** clock data, see MetaDataClock */
157    CLOCK      = 3,
158};
159
160enum MetadataKey : int32_t {
161    INVALID      = -1,
162    /** RDS PI                 - int32_t  */
163    RDS_PI       = 0,
164    /** RDS PS                 - string */
165    RDS_PS       = 1,
166    /** RDS PTY                - int32_t  */
167    RDS_PTY      = 2,
168    /** RBDS PTY               - int32_t  */
169    RBDS_PTY     = 3,
170    /** RDS RT                 - string  */
171    RDS_RT       = 4,
172    /** Song title             - string  */
173    TITLE        = 5,
174    /** Artist name            - string  */
175    ARTIST       = 6,
176    /** Album name             - string  */
177    ALBUM        = 7,
178    /** Musical genre          - string  */
179    GENRE        = 8,
180    /** Station icon           - raw (int32_t for HAL 1.1) */
181    ICON         = 9,
182    /** Album art              - raw (int32_t for HAL 1.1) */
183    ART          = 10,
184    /** Clock                  - MetaDataClock */
185    CLOCK        = 11,
186};
187
188struct MetaDataClock {
189     /** Seconds since epoch at GMT + 0. */
190    uint64_t utcSecondsSinceEpoch;
191    /** Minutes offset from the GMT. */
192    int32_t timezoneOffsetInMinutes;
193};
194
195struct MetaData {
196    MetadataType type;
197    MetadataKey key;
198    /** Value used for type MetadataType.INT */
199    int32_t intValue;
200    /** Value used for type MetadataType.CLOCK */
201    MetaDataClock  clockValue;
202    /** Value used for type MetadataType.TEXT */
203    string  stringValue;
204    /** Value used for type MetadataType.RAW */
205    vec<uint8_t> rawValue;
206};
207
208
209/* Radio program information. Returned by the HAL with event RADIO_EVENT_TUNED.
210 * Contains information on currently tuned channel.
211 */
212struct ProgramInfo {
213    uint32_t     channel;   /** current channel. (e.g kHz for band type AM_FM) */
214    uint32_t     subChannel; /** current sub channel. (FM_HD) */
215
216    /**
217     * Tuned to a program (not a noise). It's the same condition that would
218     * stop scan operation.
219     */
220    bool         tuned;
221
222    bool         stereo;    /** program is stereo or not */
223    bool         digital;   /** digital program or not (e.g HD Radio program) */
224
225    /**
226     * Signal quality measured in 0% to 100% range.
227     *
228     * Despite the name, this is not a signal strength.
229     * The purpose of this field is primarily informative.
230     */
231    uint32_t signalStrength;
232
233    /** Metadata: PTY, song title etc. */
234    vec<MetaData> metadata;
235};
236
237