broadcastradio/2.0/IBroadcastRadio.hal

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

import ITunerCallback;
import ITunerSession;

/**
 * Represents a hardware broadcast radio module. A single module may contain
 * multiple hardware tuners (i.e. with an additional background tuner), but the
 * layers above the HAL see them as a single logical unit.
 */
interface IBroadcastRadio {
    /**
     * Returns module properties: a description of a module and its
     * capabilities. This method must not fail.
     *
     * @return properties Module description.
     */
    getProperties() generates (Properties properties);

    /**
     * Opens a new tuner session.
     *
     * There may be only one session active at a time. If the new session was
     * requested when the old one was active, the old must be terminated
     * (aggressive open).
     *
     * @param callback The callback interface.
     * @return result OK in case of success.
     * @return session The session interface.
     */
    openSession(ITunerCallback callback)
            generates (Result result, ITunerSession session);

    /**
     * Fetch image from radio module cache.
     *
     * This is out-of-band transport mechanism for images carried with metadata.
     * The metadata vector only passes the identifier, so the client may cache
     * images or even not fetch them.
     *
     * The identifier may be any arbitrary number (i.e. sha256 prefix) selected
     * by the vendor. It must be stable across sessions so the application may
     * cache it.
     *
     * The data must be a valid PNG, JPEG, GIF or BMP file.
     * Image data with an invalid format must be handled gracefully in the same
     * way as a missing image.
     *
     * The image identifier may become invalid after some time from passing it
     * with metadata struct (due to resource cleanup at the HAL implementation).
     * However, it must remain valid for a currently tuned program at least
     * until onCurrentProgramInfoChanged is called.
     *
     * There is still a race condition possible between
     * onCurrentProgramInfoChanged callback and the HAL implementation eagerly
     * clearing the cache (because the next onCurrentProgramInfoChanged came).
     * In such case, client application may expect the new
     * onCurrentProgramInfoChanged callback with updated image identifier.
     *
     * @param id Identifier of an image (value of Constants::INVALID_IMAGE is
     *           reserved and must be treated as invalid image).
     * @return image A binary blob with image data
     *               or a zero-length vector if identifier doesn't exist.
     */
    getImage(uint32_t id) generates (vec<uint8_t> image);
};