initial HAL definition for bradcast radio (e.g FM radio)
Bug: 31973526
Change-Id: Ibdc3f2558104eb56bcb744c431d1213ce3459ed8
diff --git a/broadcastradio/1.0/ITuner.hal b/broadcastradio/1.0/ITuner.hal
new file mode 100644
index 0000000..5e2bffe
--- /dev/null
+++ b/broadcastradio/1.0/ITuner.hal
@@ -0,0 +1,113 @@
+/*
+ * Copyright (C) 2015 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.broadcastradio@1.0;
+
+import ITunerCallback;
+
+interface ITuner {
+
+ /*
+ * Apply current radio band configuration (band, range, channel spacing...).
+ * Automatically cancels pending scan, step or tune.
+ * ITunerCallback.configChange() method MUST be called once the
+ * configuration is applied or a failure occurs or after a time out.
+ * @param config The band configuration to apply.
+ * @return result OK if configuration could be applied
+ * NOT_INITIALIZED in case of initialization error.
+ * INVALID_ARGUMENTS if configuration requested is invalid
+ *
+ */
+ setConfiguration(BandConfig config) generates(Result result);
+
+ /*
+ * Retrieve current radio band configuration.
+ * @return result OK if valid configuration is returned,
+ * NOT_INITIALIZED in case of initialization error.
+ * @param config Current band configuration
+ */
+ getConfiguration() generates(Result result, BandConfig config);
+
+ /*
+ * Start scanning up to next valid station.
+ * Shall be called only when a valid configuration has been applied.
+ * Automatically cancels pending scan, step or tune.
+ * ITunerCallback.tuneComplete() MUST be called once locked on a station
+ * or after a time out or full band scan if no station found.
+ * The status should indicate if a valid station is tuned or not.
+ * @param direction UP or DOWN.
+ * @param skipSubChannel valid for HD radio or digital radios only:
+ * ignore sub channels (e.g SPS for HD radio).
+ * @return result OK if scan successfully started
+ * INVALID_STATE if called out of sequence
+ * NOT_INITIALIZED if another error occurs
+ */
+ scan(Direction direction, bool skipSubChannel) generates(Result result);
+
+ /*
+ * Move one channel spacing up or down.
+ * Must be called when a valid configuration has been applied.
+ * Automatically cancels pending scan, step or tune.
+ * ITunerCallback.tuneComplete() MUST be called once locked on a station
+ * or after a time out or full band scan if no station found.
+ * The status should indicate if a valid station is tuned or not.
+ * @param direction UP or DOWN.
+ * @param skipSubChannel valid for HD radio or digital radios only:
+ * ignore sub channels (e.g SPS for HD radio).
+ * @return result OK if scan successfully started
+ * INVALID_STATE if called out of sequence
+ * NOT_INITIALIZED if another error occurs
+ */
+ step(Direction direction, bool skipSubChannel) generates(Result result);
+
+ /*
+ * Tune to specified channel.
+ * Must be called when a valid configuration has been applied.
+ * Automatically cancels pending scan, step or tune.
+ * ITunerCallback.tuneComplete() MUST be called once locked on a station
+ * or after a time out or full band scan if no station found.
+ * The status should indicate if a valid station is tuned or not.
+ * @param channel Channel to tune to. A frequency in kHz for AM/FM/HD Radio
+ * bands.
+ * @param subChannel Valid for HD radio or digital radios only
+ * (e.g SPS number for HD radio)..
+ * @return result OK if scan successfully started
+ * INVALID_ARGUMENTS if invalid arguments are passed
+ * INVALID_STATE if called out of sequence
+ * NOT_INITIALIZED if another error occurs
+ */
+ tune(uint32_t channel, uint32_t subChannel) generates(Result result);
+
+ /*
+ * Cancel a scan, step or tune operation.
+ * Shall be called only while a scan, step or tune operation is pending.
+ * ITunerCallback.tuneComplete() MUST NOT be sent by the HAL.
+ * @return result OK if scan successfully started
+ * INVALID_STATE if called out of sequence
+ * NOT_INITIALIZED if another error occurs
+ */
+ cancel() generates(Result result);
+
+ /*
+ * Retrieve current station information.
+ * @param withMetadata True if Metadata should be returned, false otherwise.
+ * @return result OK if scan successfully started
+ * NOT_INITIALIZED if another error occurs
+ * @return info Current program information.
+ */
+ getProgramInformation(bool withMetadata)
+ generates(Result result, ProgramInfo info);
+};