1/*
2 * Copyright (C) 2019 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.tv.tuner@1.0;
18
19import IFilter;
20
21/**
22 * Descrambler is used to descramble input data.
23 *
24 */
25interface IDescrambler {
26    /**
27     * Set a demux as source of the descrambler
28     *
29     * It is used by the client to specify a demux as source of this
30     * descrambler. A descrambler instance can have only one source, and
31     * this method can be only called once.
32     *
33     * @param demuxId the id of the demux to be used as descrambler's source.
34     * @return result Result status of the operation.
35     *         SUCCESS if successful,
36     *         INVALID_STATE if failed for wrong state.
37     *         UNKNOWN_ERROR if failed for other reasons.
38     */
39    setDemuxSource(DemuxId demuxId) generates (Result result);
40
41    /**
42     * Set a key token to link descrambler to a key slot
43     *
44     * It is used by the client to link a hardware key slot to a descrambler.
45     * A descrambler instance can have only one key slot to link, but a key
46     * slot can hold a few keys for different purposes.
47     *
48     * @param keyToken the token to be used to link the key slot.
49     * @return result Result status of the operation.
50     *         SUCCESS if successful,
51     *         INVALID_STATE if failed for wrong state.
52     *         UNKNOWN_ERROR if failed for other reasons.
53     */
54    setKeyToken(TunerKeyToken keyToken) generates (Result result);
55
56    /**
57     * Add packets' PID to the descrambler for descrambling
58     *
59     * It is used by the client to specify Package ID (PID) of packets which the
60     * descrambler start to descramble. Multiple PIDs can be added into one
61     * descrambler instance because descambling can happen simultaneously on
62     * packets from different PIDs.
63     *
64     * @param pid the PID of packets to start to be descrambled.
65     * @param filter an optional filter instance to identify upper stream.
66     * @return result Result status of the operation.
67     *         SUCCESS if successful,
68     *         INVALID_STATE if failed for wrong state.
69     *         UNKNOWN_ERROR if failed for other reasons.
70     */
71    addPid(DemuxPid pid, IFilter optionalSourceFilter) generates (Result result);
72
73    /**
74     * Remove packets' PID from the descrambler
75     *
76     * It is used by the client to specify Package ID (PID) of packets which the
77     * descrambler stop to descramble.
78     *
79     * @param pid the PID of packets to stop to be descrambled.
80     * @param filter an optional filter instance to identify upper stream.
81     * @return result Result status of the operation.
82     *         SUCCESS if successful,
83     *         INVALID_STATE if failed for wrong state.
84     *         UNKNOWN_ERROR if failed for other reasons.
85     */
86    removePid(DemuxPid pid, IFilter optionalSourceFilter) generates (Result result);
87
88    /**
89     * Release the descrambler instance
90     *
91     * It is used by the client to release the descrambler instance. HAL clear
92     * underneath resource. client mustn't access the instance any more.
93     *
94     * @return result Result status of the operation.
95     *         SUCCESS if successful,
96     *         UNKNOWN_ERROR if failed for other reasons.
97     */
98    close() generates (Result result);
99};
100