/*
 * Copyright (C) 2017 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.1;

import @1.0::ITuner;

interface ITuner extends @1.0::ITuner {

    /**
     * Tune to a specified program.
     *
     * For AM/FM, it must be called when a valid configuration has been applied.
     * Automatically cancels pending scan, step or tune.
     *
     * If method returns OK, ITunerCallback.tuneComplete_1_1() MUST be called:
     * - once successfully tuned;
     * - after a time out;
     * - after a full band scan, if no station found.
     *
     * The tuned field of ProgramInfo should indicate if tuned to a valid
     * station or not.
     *
     * @param program Program to tune to.
     * @return result OK if successfully started tunning.
     *                INVALID_ARGUMENTS if invalid arguments are passed.
     *                NOT_INITIALIZED if another error occurs.
     */
    tuneByProgramSelector(ProgramSelector program) generates (Result result);

    /**
     * Cancels announcement.
     *
     * If it was traffic announcement, trafficAnnouncement(false) callback
     * should be called (just like it was ended in a normal way). Similarly for
     * emergency announcement. If there was no announcement, then no action
     * should be taken.
     *
     * There is a race condition between calling cancelAnnouncement and the
     * actual announcement being finished, so trafficAnnouncement /
     * emergencyAnnouncement callback should be tracked with proper locking.
     *
     * @return result OK if successfully cancelled announcement or there was
     *                no announcement.
     *                NOT_INITIALIZED if another error occurs.
     */
    cancelAnnouncement() 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_1_1() generates (Result result, ProgramInfo info);

    /**
     * Initiates a background scan to update internally cached program list.
     *
     * HAL client may not need to initiate the scan explicitly with this call,
     * ie. HAL implementation MAY perform the scan on boot. It's a common
     * practice in devices with two physical tuners with background scanning.
     *
     * Device must call backgroundScanComplete if the result is OK, even if the
     * scan fails later (it must pass proper result through the callback).
     * Otherwise, backgroundScanComplete must not be called as a result of this
     * certain attempt. It may still be called as a response to another call to
     * startBackgroundScan, former or latter.
     *
     * Device may utilize an already running (but not finished) scan for
     * subsequent calls to startBackgroundScan, issuing a single
     * backgroundScanComplete callback.
     *
     * If a device supports continuous background scanning, it may succeed
     * (return OK and call backgroundScanComplete) without any additional
     * operation performed.
     *
     * Foreground scanning may be implemented in the front end app with
     * @1.0::ITuner scan operation.
     *
     * @return result OK if the scan was properly scheduled (this does not mean
     *                it successfully finished).
     *                UNAVAILABLE if the background scan is unavailable,
     *                ie. temporarily due to ongoing foreground
     *                playback in single-tuner device.
     *                NOT_INITIALIZED other error, ie. HW failure.
     */
    startBackgroundScan() generates (ProgramListResult result);

    /**
     * Retrieve station list.
     *
     * This call does not trigger actual scan, but operates on the list cached
     * internally at the driver level.
     *
     * @param vendorFilter vendor-specific filter for the stations to be retrieved.
     *               An empty vector MUST result in full list for a given tuner.
     * @return result OK if the list was successfully retrieved.
     *                INVALID_ARGUMENTS if invalid arguments are passed
     *                NOT_READY if the scan is in progress.
     *                NOT_STARTED if the scan has not been started, client may
     *                call startBackgroundScan to fix this.
     *                NOT_INITIALIZED if any other error occurs.
     * @return programList List of stations available for user.
     */
    getProgramList(vec<VendorKeyValue> vendorFilter)
        generates (ProgramListResult result, vec<ProgramInfo> programList);

    /**
     * Forces the analog playback for the supporting radio technology.
     *
     * User may disable digital playback for FM HD Radio or hybrid FM/DAB with
     * this option. This is purely user choice, ie. does not reflect digital-
     * analog handover managed from the HAL implementation side.
     *
     * Some radio technologies may not support this, ie. DAB.
     *
     * @param isForced true to force analog, false for a default behaviour.
     * @return result OK if the setting was successfully done.
     *                INVALID_STATE if the switch is not supported at current
     *                configuration.
     *                NOT_INITIALIZED if any other error occurs.
     */
    setAnalogForced(bool isForced) generates (Result result);

    /**
     * Checks, if the analog playback is forced, see setAnalogForced.
     *
     * The isForced value is only valid if result was OK.
     *
     * @return result OK if the call succeeded and isForced is valid.
     *                INVALID_STATE if the switch is not supported at current
     *                configuration.
     *                NOT_INITIALIZED if any other error occurs.
     * @return isForced true if analog is forced, false otherwise.
     */
    isAnalogForced() generates (Result result, bool isForced);
};