blob: ae6cbb57db15ffd12368456b345437e1c4d7abcd [file] [log] [blame]
/* 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();
};