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 * Digtal Video Record (DVR) interface provides record control on Demux's
23 * output buffer and playback control on Demux's input buffer.
24 */
25interface IDvr {
26    /**
27     * Get the descriptor of the DVR's FMQ
28     *
29     * It is used by the client to get the descriptor of the DVR's Fast
30     * Message Queue. The FMQ is used to transfer record or playback data
31     * between the client and the HAL.
32     *
33     * @return result Result status of the operation.
34     *         SUCCESS if successful,
35     *         UNKNOWN_ERROR if failed for other reasons.
36     * @return queue the descriptor of the DVR's FMQ
37     */
38    getQueueDesc() generates (Result result, fmq_sync<uint8_t> queue);
39
40    /**
41     * Configure the DVR.
42     *
43     * It is used by the client to configure the DVR interface.
44     *
45     * @param settings the settings of the DVR interface.
46     * @return result Result status of the operation.
47     *         SUCCESS if successful,
48     *         INVALID_STATE if failed for wrong state.
49     *         UNKNOWN_ERROR if failed for other reasons.
50     */
51    configure(DvrSettings settings) generates (Result result);
52
53    /**
54     * Attach one filter to DVR interface for recording.
55     *
56     * It is used by the client to add the data filtered out from the filter
57     * to record.
58     *
59     * @param filter the instance of the attached filter.
60     * @return result Result status of the operation.
61     *         SUCCESS if successful,
62     *         INVALID_STATE if failed for wrong state.
63     *         UNKNOWN_ERROR if failed for other reasons.
64     */
65    attachFilter(IFilter filter) generates (Result result);
66
67    /**
68     * Detach one filter from the DVR's recording.
69     *
70     * It is used by the client to remove the data of the filter from DVR's
71     * recording.
72     *
73     * @param filter the instance of the detached filter.
74     * @return result Result status of the operation.
75     *         SUCCESS if successful,
76     *         INVALID_STATE if failed for wrong state.
77     *         UNKNOWN_ERROR if failed for other reasons.
78     */
79    detachFilter(IFilter filter) generates (Result result);
80
81    /**
82     * Start DVR.
83     *
84     * It is used by the client to ask the DVR to start consuming playback data
85     * or producing data for record.
86     *
87     * @return result Result status of the operation.
88     *         SUCCESS if successful,
89     *         INVALID_STATE if failed for wrong state.
90     *         UNKNOWN_ERROR if failed for other reasons.
91     */
92    start() generates (Result result);
93
94    /**
95     * Stop DVR.
96     *
97     * It is used by the client to ask the DVR to stop consuming playback data
98     * or producing data for record.
99     *
100     * @return result Result status of the operation.
101     *         SUCCESS if successful,
102     *         INVALID_STATE if failed for wrong state.
103     *         UNKNOWN_ERROR if failed for other reasons.
104     */
105    stop() generates (Result result);
106
107    /**
108     * Flush DVR data.
109     *
110     * It is used by the client to ask the DVR to flush the data which is
111     * not consumed by HAL for playback or the client for record yet.
112     *
113     * @return result Result status of the operation.
114     *         SUCCESS if successful,
115     *         INVALID_STATE if failed for wrong state.
116     *         UNKNOWN_ERROR if failed for other reasons.
117     */
118    flush() generates (Result result);
119
120    /**
121     * close the DVR instance to release resource for DVR.
122     *
123     * It is used by the client to close the DVR instance, and HAL clears
124     * underneath resource for this DVR instance. Client mustn't access the
125     * instance any more and all methods should return a failure.
126     *
127     * @return result Result status of the operation.
128     *         SUCCESS if successful,
129     *         INVALID_STATE if failed for wrong state.
130     *         UNKNOWN_ERROR if failed for other reasons.
131     */
132    close() generates (Result result);
133};
134