/*
 * Copyright (C) 2019 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.tv.tuner@1.0;

import IDemux;
import IDescrambler;
import IFrontend;
import ILnb;

/**
 * Top level interface to manage Frontend, Demux and Decrambler hardware
 * resouces which are needed for Android TV.
 */
interface ITuner {
    /**
     * Get Frontend IDs
     *
     * It is used by the client to get all available frontends' IDs.
     *
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNKNOWN_ERROR if tuning failed for other reasons.
     * @return frontendIds an array of FrontendId for the available frontends.
     */
    getFrontendIds() generates (Result result, vec<FrontendId> frontendIds);

    /**
     * Create a new instance of Frontend given a frontendId.
     *
     * It is used by the client to create a frontend instance.
     *
     * @param frontendId the id of the frontend to be opened.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNAVAILABLE if no resource.
     *         UNKNOWN_ERROR if creation failed for other reasons.
     * @return frontend the newly created frontend interface.
     */
    openFrontendById(FrontendId frontendId) generates (Result result, IFrontend frontend);

    /**
     * Create a new instance of Demux.
     *
     * It is used by the client to create a Demux instance.
     *
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNKNOWN_ERROR if creation failed for other reasons.
     * @return demuxId newly created demux id.
     * @return demux the newly created demux interface.
     */
    openDemux() generates (Result result, DemuxId demuxId, IDemux demux);

    /**
     * Retrieve the Demux's Capabilities.
     *
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNKNOWN_ERROR if the inquiry failed for other reasons.
     * @return caps the Demux's Capabilities.
     */
    getDemuxCaps() generates (Result result, DemuxCapabilities caps);

    /**
     * Create a new instance of Descrambler.
     *
     * It is used by the client to create a Descrambler instance.
     *
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNKNOWN_ERROR if creation failed for other reasons.
     * @return descrambler the newly created descrambler interface.
     */
    openDescrambler() generates (Result result, IDescrambler descrambler);

    /**
     * Retrieve the frontend's information.
     *
     * @param frontendId the id of the frontend to be inquiried.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNKNOWN_ERROR if the inquiry failed for other reasons.
     * @return info the frontend's information.
     */
    getFrontendInfo(FrontendId frontendId) generates (Result result, FrontendInfo info);

    /**
     * Get low-noise block downconverter (LNB) IDs.
     *
     * It is used by the client to get all available LNBs' IDs.
     *
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNKNOWN_ERROR if tuning failed for other reasons.
     * @return frontendIds an array of LnbId for the available LNBs.
     */
    getLnbIds() generates (Result result, vec<LnbId> lnbIds);

    /**
     * Create a new instance of Lnb given a lnbId.
     *
     * It is used by the client to create a Lnb instance for satellite Frontend.
     *
     * @param lnbId the id of the LNB to be opened.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNAVAILABLE if no resource.
     *         UNKNOWN_ERROR if creation failed for other reasons.
     * @return lnb the newly created Lnb interface.
     */
    openLnbById(LnbId lnbId) generates (Result result, ILnb lnb);

    /**
     * Create a new instance of Lnb given a LNB name.
     *
     * It is used by the client to create a LNB instance for external device.
     *
     * @param lnbName the name for an external LNB to be opened. The app
     *        provides the name. Frammework doesn't depend on the name, instead
     *        use lnbId return from this call.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNAVAILABLE if no resource.
     *         UNKNOWN_ERROR if creation failed for other reasons.
     * @return lnbId the id of the LNB to be opened.
     * @return lnb the newly created Lnb interface.
     */
    openLnbByName(string lnbName) generates (Result result, LnbId lnbId, ILnb lnb);
};