1/*
2 * Copyright (C) 2014 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.hdmi;
18
19import android.annotation.SystemApi;
20import android.hardware.hdmi.HdmiRecordSources.RecordSource;
21
22/**
23 * Listener for hdmi record feature including one touch record and timer recording.
24 * @hide
25 */
26@SystemApi
27public abstract class HdmiRecordListener {
28    public HdmiRecordListener() {}
29
30    /**
31     * Called when TV received one touch record request from record device. The client of this
32     * should use {@link HdmiRecordSources} to return it.
33     *
34     * @param recorderAddress
35     * @return record source to be used for recording. Null if no device is available.
36     */
37    public abstract RecordSource onOneTouchRecordSourceRequested(int recorderAddress);
38
39    /**
40     * Called when one touch record is started or failed during initialization.
41     *
42     * @param recorderAddress An address of recorder that reports result of one touch record
43     *            request
44     * @param result result code. For more details, please look at all constants starting with
45     *            "ONE_TOUCH_RECORD_". Only
46     *            {@link HdmiControlManager#ONE_TOUCH_RECORD_RECORDING_CURRENTLY_SELECTED_SOURCE},
47     *            {@link HdmiControlManager#ONE_TOUCH_RECORD_RECORDING_DIGITAL_SERVICE},
48     *            {@link HdmiControlManager#ONE_TOUCH_RECORD_RECORDING_ANALOGUE_SERVICE}, and
49     *            {@link HdmiControlManager#ONE_TOUCH_RECORD_RECORDING_EXTERNAL_INPUT} mean normal
50     *            start of recording; otherwise, describes failure.
51     */
52    public void onOneTouchRecordResult(int recorderAddress, int result) {
53    }
54
55    /**
56     * Called when timer recording is started or failed during initialization.
57     *
58     * @param recorderAddress An address of recorder that reports result of timer recording
59     *            request
60     * @param data timer status data. For more details, look at {@link TimerStatusData}.
61     */
62    public void onTimerRecordingResult(int recorderAddress, TimerStatusData data) {
63    }
64
65    /**
66     * [Timer overlap warning] [Media Info] [Timer Programmed Info]
67     * @hide
68     */
69    @SystemApi
70    public static class TimerStatusData {
71        private boolean mOverlapped;
72        private int mMediaInfo;
73        private boolean mProgrammed;
74
75        private int mProgrammedInfo;
76        private int mNotProgrammedError;
77        private int mDurationHour;
78        private int mDurationMinute;
79
80        private int mExtraError;
81
82        static TimerStatusData parseFrom(int result) {
83            TimerStatusData data = new TimerStatusData();
84            // Timer Overlap Warning - 1 bit
85            data.mOverlapped = ((result >> 31) & 0x1) != 0;
86            // Media Info - 2 bits;
87            data.mMediaInfo = (result >> 29) & 0x3;
88            // Programmed Indicator - 1 bit;
89            data.mProgrammed = ((result >> 28) & 0x1) != 0;
90            if (data.mProgrammed) {
91                data.mProgrammedInfo = (result >> 24) & 0xF;
92                data.mDurationHour = bcdByteToInt((byte) ((result >> 16) & 0xFF));
93                data.mDurationMinute = bcdByteToInt((byte) ((result >> 8) & 0xFF));
94            } else {
95                // Programmed Info - 4 bits
96                data.mNotProgrammedError = (result >> 24) & 0xF;
97                data.mDurationHour = bcdByteToInt((byte) ((result >> 16) & 0xFF));
98                data.mDurationMinute = bcdByteToInt((byte) ((result >> 8) & 0xFF));
99            }
100
101            // The last byte is used for extra error.
102            data.mExtraError = result & 0xFF;
103            return data;
104        }
105
106        // Most significant 4 bits is used for 10 digits and
107        // Least significant 4 bits is used for 1 digits.
108        private static int bcdByteToInt(byte value) {
109            return ((value >> 4) & 0xF) * 10 + value & 0xF;
110        }
111
112        private TimerStatusData() {}
113
114        /**
115         * Indicates if there is another timer block already set which overlaps with this new
116         * recording request.
117         */
118        public boolean isOverlapped() {
119            return mOverlapped;
120        }
121
122        /**
123         * Indicates if removable media is present and its write protect state.
124         * It should be one of the following values.
125         * <ul>
126         *   <li>{@link HdmiControlManager#TIMER_STATUS_MEDIA_INFO_PRESENT_NOT_PROTECTED}
127         *   <li>{@link HdmiControlManager#TIMER_STATUS_MEDIA_INFO_PRESENT_PROTECTED}
128         *   <li>{@link HdmiControlManager#TIMER_STATUS_MEDIA_INFO_NOT_PRESENT}
129         * </ul>
130         */
131        public int getMediaInfo() {
132            return mMediaInfo;
133        }
134
135        /**
136         * Selector for [Timer Programmed Info].
137         * If it is {@code true}, {@link #getProgrammedInfo()} would have meaningful value and
138         * ignore result of {@link #getNotProgammedError()}.
139         */
140        public boolean isProgrammed() {
141            return mProgrammed;
142        }
143
144        /**
145         * Information indicating any non-fatal issues with the programming request.
146         * It's set only if {@link #isProgrammed()} returns true.
147         * It should be one of the following values.
148         * <ul>
149         *   <li>{@link HdmiControlManager#TIMER_STATUS_PROGRAMMED_INFO_ENOUGH_SPACE}
150         *   <li>{@link HdmiControlManager#TIMER_STATUS_PROGRAMMED_INFO_NOT_ENOUGH_SPACE}
151         *   <li>{@link HdmiControlManager#TIMER_STATUS_PROGRAMMED_INFO_MIGHT_NOT_ENOUGH_SPACE}
152         *   <li>{@link HdmiControlManager#TIMER_STATUS_PROGRAMMED_INFO_NO_MEDIA_INFO}
153         * </ul>
154         *
155         * @throws IllegalStateException if it's called when {@link #isProgrammed()}
156         *                               returns false
157         */
158        public int getProgrammedInfo() {
159            if (!isProgrammed()) {
160                throw new IllegalStateException(
161                        "No programmed info. Call getNotProgammedError() instead.");
162            }
163            return mProgrammedInfo;
164        }
165
166        /**
167         * Information indicating any fatal issues with the programming request.
168         * It's set only if {@link #isProgrammed()} returns false.
169         * it should be one of the following values.
170         * <ul>
171         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_NO_FREE_TIME}
172         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_DATE_OUT_OF_RANGE}
173         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_INVALID_SEQUENCE}
174         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_INVALID_EXTERNAL_PHYSICAL_NUMBER}
175         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_CA_NOT_SUPPORTED}
176         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_NO_CA_ENTITLEMENTS}
177         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_UNSUPPORTED_RESOLUTION}
178         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_PARENTAL_LOCK_ON}
179         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_CLOCK_FAILURE}
180         *   <li>{@link HdmiControlManager#TIMER_STATUS_NOT_PROGRAMMED_DUPLICATED}
181         * </ul>
182         *
183         * @throws IllegalStateException if it's called when {@link #isProgrammed()}
184         *                               returns true
185         */
186        public int getNotProgammedError() {
187            if (isProgrammed()) {
188                throw new IllegalStateException(
189                        "Has no not-programmed error. Call getProgrammedInfo() instead.");
190            }
191            return mNotProgrammedError;
192        }
193
194        /**
195         * Duration hours.
196         * Optional parameter: Contains an estimate of the space left on the media, expressed as a
197         * time. This parameter may be returned when:
198         *  - [Programmed Info] is “Not enough space available”; or
199         *  - [Not Programmed Info] is “Duplicate: already programmed”
200         */
201        public int getDurationHour() {
202            return mDurationHour;
203        }
204
205        /**
206         * Duration minutes.
207         * Optional parameter: Contains an estimate of the space left on the media, expressed as a
208         * time. This parameter may be returned when:
209         *  - [Programmed Info] is “Not enough space available”; or
210         *  - [Not Programmed Info] is “Duplicate: already programmed”
211         */
212        public int getDurationMinute() {
213            return mDurationMinute;
214        }
215
216        /**
217         * Extra error code.
218         * <ul>
219         * <li>{@link HdmiControlManager#TIMER_RECORDING_RESULT_EXTRA_NO_ERROR}
220         *     No extra errors. Other values of this class might be available.
221         * <li>{@link HdmiControlManager#TIMER_RECORDING_RESULT_EXTRA_CHECK_RECORDER_CONNECTION}
222         *     Check record connection. Other values of this class should be ignored.
223         * <li>{@link HdmiControlManager#TIMER_RECORDING_RESULT_EXTRA_FAIL_TO_RECORD_SELECTED_SOURCE}
224         *     Fail to record selected source. Other values of this class should be ignored.
225         * <li>{@link HdmiControlManager#TIMER_RECORDING_RESULT_EXTRA_CEC_DISABLED}
226         *     Cec disabled. Other values of this class should be ignored.
227         * </ul>
228         */
229        public int getExtraError() {
230            return mExtraError;
231        }
232    }
233
234    /**
235     * Called when receiving result for clear timer recording request.
236     *
237     * @param recorderAddress An address of recorder that reports result of clear timer recording
238     *            request
239     * @param result result of clear timer. It should be one of
240     *            {@link HdmiControlManager#CLEAR_TIMER_STATUS_TIMER_NOT_CLEARED_RECORDING}
241     *            {@link HdmiControlManager#CLEAR_TIMER_STATUS_TIMER_NOT_CLEARED_NO_MATCHING},
242     *            {@link HdmiControlManager#CLEAR_TIMER_STATUS_TIMER_NOT_CLEARED_NO_INFO_AVAILABLE},
243     *            {@link HdmiControlManager#CLEAR_TIMER_STATUS_TIMER_CLEARED},
244     *            {@link HdmiControlManager#CLEAR_TIMER_STATUS_CHECK_RECORDER_CONNECTION},
245     *            {@link HdmiControlManager#CLEAR_TIMER_STATUS_FAIL_TO_CLEAR_SELECTED_SOURCE},
246     *            {@link HdmiControlManager#CLEAR_TIMER_STATUS_CEC_DISABLE}.
247     */
248    public void onClearTimerRecordingResult(int recorderAddress, int result) {
249    }
250}
251