tv/tuner/1.0/IDemux.hal

package android.hardware.tv.tuner@1.0;

import IDemuxCallback;

/**
 * Demultiplexer(Demux) takes a single multiplexed input and splits it into
 * one or more output.
 *
 */
interface IDemux {

    /**
     * Set a frontend resource as data input of the demux
     *
     * It is used by the client to specify a hardware frontend as data source of
     * this demux instance. A demux instance can have only one data source.
     *
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_STATE if failed for wrong state.
     *         UNKNOWN_ERROR if failed for other reasons.
     */
    setFrontendDataSource(FrontendId frontendId) generates (Result result);

    /**
     * Add a filter to the demux
     *
     * It is used by the client to add a filter to the demux.
     *
     * @param type the type of the filter to be added.
     * @param bufferSize the buffer size of the filter to be added. It's used to
     * create a FMQ(Fast Message Queue) to hold data output from the filter.
     * @param cb the callback for the filter to be used to send notifications
     * back to the client.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_STATE if failed for wrong state.
     *         UNKNOWN_ERROR if failed for other reasons.
     * @return filterId the ID of the newly added filter.
     */
    addFilter(DemuxFilterType type, uint32_t bufferSize, IDemuxCallback cb)
        generates (Result result, DemuxFilterId filterId);

    /**
     * Get the descriptor of the filter's FMQ
     *
     * It is used by the client to get the descriptor of the filter's Fast
     * Message Queue. The data in FMQ is filtered out from MPEG transport
     * stream. The data is origanized to data blocks which may have
     * different length. The length's information of one or multiple data blocks
     * is sent to client throught DemuxFilterEvent.
     *
     * @param filterId the ID of the filter.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_ARGUMENT if failed for wrong filter ID.
     *         INVALID_STATE if failed for wrong state.
     *         UNKNOWN_ERROR if failed for other reasons.
     * @return queue the descriptor of the filter's FMQ
     */
    getFilterQueueDesc(DemuxFilterId filterId)
        generates (Result result, fmq_sync<uint8_t> queue);

    /**
     * Configure the filter.
     *
     * It is used by the client to configure the filter so that it can filter out
     * intended data.
     *
     * @param filterId the ID of the filter.
     * @param settings the settings of the filter.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_ARGUMENT if failed for wrong filter ID.
     *         INVALID_STATE if failed for wrong state.
     *         UNKNOWN_ERROR if failed for other reasons.
     */
    configureFilter(DemuxFilterId filterId, DemuxFilterSettings settings)
        generates(Result result);

    /**
     * Start the filter.
     *
     * It is used by the client to ask the filter to start filterring data.
     *
     * @param filterId the ID of the filter.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_ARGUMENT if failed for wrong filter ID.
     *         INVALID_STATE if failed for wrong state.
     *         UNKNOWN_ERROR if failed for other reasons.
     */
    startFilter(DemuxFilterId filterId) generates (Result result);

    /**
     * Stop the filter.
     *
     * It is used by the client to ask the filter to stop filterring data.
     * It won't discard the data already filtered out by the filter. The filter
     * will be stopped and removed automatically if the demux is closed.
     *
     * @param filterId the ID of the filter.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_ARGUMENT if failed for wrong filter ID.
     *         INVALID_STATE if failed for wrong state.
     *         UNKNOWN_ERROR if failed for other reasons.
     */
    stopFilter(DemuxFilterId filterId) generates (Result result);

    /**
     * Flush the filter.
     *
     * It is used by the client to ask the filter to flush the data which is
     * already produced but not consumed yet.
     *
     * @param filterId the ID of the filter.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_ARGUMENT if failed for wrong filter ID.
     *         INVALID_STATE if failed for wrong state.
     *         UNKNOWN_ERROR if failed for other reasons.
     */
    flushFilter(DemuxFilterId filterId) generates (Result result);

    /**
     * Remove a filter from the demux
     *
     * It is used by the client to remove a filter from the demux.
     *
     * @param filterId the ID of the removed filter.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_ARGUMENT if failed for wrong filter ID.
     *         INVALID_STATE if failed for wrong state.
     *         UNKNOWN_ERROR if failed for other reasons.
     */
    removeFilter(DemuxFilterId filterId) generates (Result result);

    /**
     * Get hardware sync ID for audio and video.
     *
     * It is used by the client to get the hardware sync ID for audio and video.
     *
     * @param filterId the ID of the filter.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_ARGUMENT if failed for a wrong filter ID.
     *         UNKNOWN_ERROR if failed for other reasons.
     * @return avSyncHwId the id of hardware A/V sync.
     */
    getAvSyncHwId(DemuxFilterId filterId)
        generates (Result result, AvSyncHwId avSyncHwId);

    /**
     * Get current time stamp to use for A/V sync
     *
     * It is used by the client to get current time stamp for A/V sync. HW is
     * supported to increment and maintain current time stamp.
     *
     * @param avSyncHwId the hardware id of A/V sync.
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         INVALID_ARGUMENT if failed for a wrong hardware ID of A/V sync.
     *         UNKNOWN_ERROR if failed for other reasons.
     * @return time the current time stamp of hardware A/V sync. The time stamp
     * based on 90KHz has the same format as PTS (Presentation Time Stamp).
     */
    getAvSyncTime(AvSyncHwId avSyncHwId)
        generates (Result result, uint64_t time);

    /**
     * Close the Demux instance
     *
     * It is used by the client to release the demux instance. HAL clear
     * underneath resource. client mustn't access the instance any more.
     *
     * @return result Result status of the operation.
     *         SUCCESS if successful,
     *         UNKNOWN_ERROR if failed for other reasons.
     */
    close() generates (Result result);
};