1 /*
2  * Copyright (C) 2016 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 
17 package com.android.tv.data.epg;
18 
19 import android.support.annotation.AnyThread;
20 import android.support.annotation.NonNull;
21 import android.support.annotation.WorkerThread;
22 
23 import com.android.tv.data.Lineup;
24 import com.android.tv.data.api.Channel;
25 import com.android.tv.data.api.Program;
26 import com.android.tv.dvr.data.SeriesInfo;
27 
28 import com.google.auto.value.AutoValue;
29 
30 import java.util.Collection;
31 import java.util.List;
32 import java.util.Map;
33 import java.util.Set;
34 
35 /** An interface used to retrieve the EPG data. This class should be used in worker thread. */
36 @WorkerThread
37 public interface EpgReader {
38 
39     /** Value class that holds a EpgChannelId and its corresponding {@link Channel} */
40     @AutoValue
41     abstract class EpgChannel {
createEpgChannel( Channel channel, String epgChannelId, boolean dbUpdateNeeded)42         public static EpgChannel createEpgChannel(
43                 Channel channel, String epgChannelId, boolean dbUpdateNeeded) {
44             return new AutoValue_EpgReader_EpgChannel(channel, epgChannelId, dbUpdateNeeded);
45         }
46 
getChannel()47         public abstract Channel getChannel();
48 
getEpgChannelId()49         public abstract String getEpgChannelId();
50 
getDbUpdateNeeded()51         public abstract boolean getDbUpdateNeeded();
52     }
53 
54     /** Checks if the reader is available. */
isAvailable()55     boolean isAvailable();
56 
57     /**
58      * Returns the timestamp of the current EPG. The format should be YYYYMMDDHHmmSS as a long
59      * value. ex) 20160308141500
60      */
getEpgTimestamp()61     long getEpgTimestamp();
62 
63     /** Sets the region code. */
setRegionCode(String regionCode)64     void setRegionCode(String regionCode);
65 
66     /** Returns the lineups list. */
getLineups(@onNull String postalCode)67     List<Lineup> getLineups(@NonNull String postalCode);
68 
69     /**
70      * Returns the list of channel numbers (unsorted) for the given lineup. The result is used to
71      * choose the most appropriate lineup among others by comparing the channel numbers of the
72      * existing channels on the device.
73      */
getChannelNumbers(@onNull String lineupId)74     List<String> getChannelNumbers(@NonNull String lineupId);
75 
76     /**
77      * Returns the list of channels for the given lineup. The returned channels should map into the
78      * existing channels on the device. This method is usually called after selecting the lineup.
79      */
getChannels(Set<Channel> inputChannels, @NonNull String lineupId)80     Set<EpgChannel> getChannels(Set<Channel> inputChannels, @NonNull String lineupId);
81 
82     /** Pre-loads and caches channels for a given lineup. */
preloadChannels(@onNull String lineupId)83     void preloadChannels(@NonNull String lineupId);
84 
85     /** Clears cached channels for a given lineup. */
86     @AnyThread
clearCachedChannels(@onNull String lineupId)87     void clearCachedChannels(@NonNull String lineupId);
88 
89     /**
90      * Returns the programs for the given channel. Must call {@link #getChannels(Set, String)}
91      * beforehand. Note that the {@code Program} doesn't have valid program ID because it's not
92      * retrieved from TvProvider.
93      */
getPrograms(EpgChannel epgChannel)94     List<Program> getPrograms(EpgChannel epgChannel);
95 
96     /**
97      * Returns the programs for the given channels. Note that the {@code Program} doesn't have valid
98      * program ID because it's not retrieved from TvProvider. This method is only used to get
99      * programs for a short duration typically.
100      */
getPrograms( @onNull Set<EpgChannel> epgChannels, long duration)101     Map<EpgChannel, Collection<Program>> getPrograms(
102             @NonNull Set<EpgChannel> epgChannels, long duration);
103 
104     /** Returns the series information for the given series ID. */
getSeriesInfo(@onNull String seriesId)105     SeriesInfo getSeriesInfo(@NonNull String seriesId);
106 }
107