1 /*
2  * Copyright (C) 2017 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 package com.android.wallpaper.model;
17 
18 import android.content.Context;
19 
20 import androidx.annotation.IntDef;
21 
22 /**
23  * Interface for objects which initialize daily wallpaper rotations.
24  */
25 public interface WallpaperRotationInitializer {
26 
27     /**
28      * OK to download on both metered (i.e., cellular) and unmetered (i.e., wifi) networks.
29      */
30     int NETWORK_PREFERENCE_CELLULAR_OK = 0;
31     /**
32      * Only download wallpapers on unmetered (i.e., wifi) networks.
33      */
34     int NETWORK_PREFERENCE_WIFI_ONLY = 1;
35     int ROTATION_NOT_INITIALIZED = 0;
36     int ROTATION_HOME_ONLY = 1;
37     int ROTATION_HOME_AND_LOCK = 2;
38 
39     /**
40      * Starts a daily wallpaper rotation.
41      *
42      * @param appContext The application's context.
43      * @return Whether rotation started successfully.
44      */
startRotation(Context appContext)45     boolean startRotation(Context appContext);
46 
47     /**
48      * Sets the first wallpaper in a daily rotation to the device. Must be called before a call to
49      * {@code startRotation(appContext)}.
50      *
51      * @param appContext        The application's context.
52      * @param networkPreference The user's network preference for downloading wallpapers in rotation.
53      * @param listener          Called when the first wallpaper in rotation has been downloaded and set to the
54      *                          device.
55      */
setFirstWallpaperInRotation(Context appContext, @NetworkPreference int networkPreference, Listener listener)56     void setFirstWallpaperInRotation(Context appContext, @NetworkPreference int networkPreference,
57                                      Listener listener);
58 
59     /**
60      * Gets the current state of the possible wallpaper rotation represented by this object.
61      */
fetchRotationInitializationState(Context context, RotationStateListener listener)62     void fetchRotationInitializationState(Context context, RotationStateListener listener);
63 
64     /**
65      * Checks and returns the last-known rotation intialization state without doing a full refresh,
66      * which would perform some disk I/O. Therefore, this method can be called safely from the main
67      * thread but the data returned here could be stale.
68      */
69     @RotationInitializationState
getRotationInitializationStateDirty(Context context)70     int getRotationInitializationStateDirty(Context context);
71 
72     /**
73      * Possible network preferences for downloading wallpapers in rotation.
74      */
75     @IntDef({
76             NETWORK_PREFERENCE_CELLULAR_OK,
77             NETWORK_PREFERENCE_WIFI_ONLY})
78     @interface NetworkPreference {
79     }
80 
81     /**
82      * Possible states of rotation initialization.
83      */
84     @IntDef({
85             ROTATION_NOT_INITIALIZED,
86             ROTATION_HOME_ONLY,
87             ROTATION_HOME_AND_LOCK})
88     @interface RotationInitializationState {
89     }
90 
91     /**
92      * Listener interface for clients to asynchronously receive the rotation initialization state of
93      * this rotation initializer.
94      */
95     interface RotationStateListener {
onRotationStateReceived(@otationInitializationState int rotationInitializationState)96         void onRotationStateReceived(@RotationInitializationState int rotationInitializationState);
97     }
98 
99     /**
100      * Listener interface which can be implemented to listen for the initialization status of a
101      * wallpaper rotation.
102      */
103     interface Listener {
onFirstWallpaperInRotationSet()104         void onFirstWallpaperInRotationSet();
105 
onError()106         void onError();
107     }
108 }
109