/*
 * 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.
     * @return result OK if scan successfully started
     *                NOT_INITIALIZED if another error occurs
     * @return info Current program information.
     */
    getProgramInformation() generates(Result result, ProgramInfo info);
};