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