/* 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@2.0;

interface ITunerSession {
    /**
     * Tune to a specified program.
     *
     * Automatically cancels pending scan, step or tune.
     * If the method returns OK, tuneFailed or currentProgramInfoChanged
     * callback must be called.
     *
     * @param program Program to tune to.
     * @return result OK if successfully started tuning.
     *                NOT_SUPPORTED if the program selector doesn't contain any
     *                supported identifier.
     *                INVALID_ARGUMENTS if the program selector contains
     *                identifiers in invalid format (i.e. out of range).
     */
    tune(ProgramSelector program) generates (Result result);

    /**
     * Tune to the next valid program.
     *
     * Automatically cancels pending scan, step or tune.
     * If the method returns OK, tuneFailed or currentProgramInfoChanged
     * callback must be called.
     *
     * The skipSubChannel parameter is used to skip digital radio subchannels:
     *  - HD Radio SPS;
     *  - DAB secondary service.
     *
     * As an implementation detail, the HAL has the option to perform an actual
     * scan or select the next program from the list retrieved in the
     * background, if one is not stale.
     *
     * @param directionUp True to change towards higher numeric values
     *                    (frequency, channel number), false towards lower.
     * @param skipSubChannel Don't tune to subchannels.
     * @return result OK if the scan has successfully started.
     */
    scan(bool directionUp, bool skipSubChannel) generates (Result result);

    /**
     * Tune to the adjacent channel, which may not be occupied by any program.
     *
     * Automatically cancels pending scan, step or tune.
     * If the method returns OK, tuneFailed or currentProgramInfoChanged
     * callback must be called.
     *
     * @param directionUp True to change towards higher numeric values
     *                    (frequency, channel number), false towards lower.
     * @return result OK successfully started tuning.
     *                NOT_SUPPORTED if tuning to an unoccupied channel is not
     *                supported (i.e. for satellite radio).
     */
    step(bool directionUp) generates (Result result);

    /**
     * Cancel a scan, step or tune operation.
     *
     * If there is no such operation running, the call must be ignored.
     */
    cancel();

    /**
     * Generic method for setting vendor-specific parameter values.
     * The framework does not interpret the parameters, they are passed
     * in an opaque manner between a vendor application and HAL.
     *
     * Framework does not make any assumptions on the keys or values, other than
     * ones stated in VendorKeyValue documentation (a requirement of key
     * prefixes).
     *
     * For each pair in the result vector, the key must be one of the keys
     * contained in the input (possibly with wildcards expanded), and the value
     * must be a vendor-specific result status (i.e. the string "OK" or an error
     * code). The implementation may choose to return an empty vector, or only
     * return a status for a subset of the provided inputs, at its discretion.
     *
     * Application and HAL must not use keys with unknown prefix. In particular,
     * it must not place a key-value pair in results vector for unknown key from
     * parameters vector - instead, an unknown key should simply be ignored.
     * In other words, results vector may contain a subset of parameter keys
     * (however, the framework doesn't enforce a strict subset - the only
     * formal requirement is vendor domain prefix for keys).
     *
     * @param parameters Vendor-specific key-value pairs.
     * @return results Operation completion status for parameters being set.
     */
    setParameters(vec<VendorKeyValue> parameters)
            generates (vec<VendorKeyValue> results);

    /**
     * Generic method for retrieving vendor-specific parameter values.
     * The framework does not interpret the parameters, they are passed
     * in an opaque manner between a vendor application and HAL.
     *
     * Framework does not cache set/get requests, so it's allowed for
     * getParameter to return a different value than previous setParameter call.
     *
     * The syntax and semantics of keys are up to the vendor (as long as prefix
     * rules are obeyed). For instance, vendors may include some form of
     * wildcard support. In such case, result vector may be of different size
     * than requested keys vector. However, wildcards are not recognized by
     * framework and they are passed as-is to the HAL implementation.
     *
     * Unknown keys must be ignored and not placed into results vector.
     *
     * @param keys Parameter keys to fetch.
     * @return parameters Vendor-specific key-value pairs.
     */
    getParameters(vec<string> keys) generates (vec<VendorKeyValue> parameters);

    /**
     * Closes the session.
     *
     * The call must not fail and must only be issued once.
     *
     * After the close call is executed, no other calls to this interface
     * are allowed.
     */
    close();
};