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.module
17 
18 import android.app.WallpaperColors
19 import android.app.WallpaperManager.SetWallpaperFlags
20 import android.graphics.Bitmap
21 import android.graphics.Point
22 import android.graphics.Rect
23 import android.text.TextUtils
24 import androidx.annotation.IntDef
25 import com.android.wallpaper.model.LiveWallpaperInfo
26 import com.android.wallpaper.model.LiveWallpaperPrefMetadata
27 import com.android.wallpaper.model.StaticWallpaperPrefMetadata
28 import com.android.wallpaper.model.WallpaperInfo
29 import com.android.wallpaper.picker.customization.shared.model.WallpaperDestination
30 import com.android.wallpaper.picker.data.WallpaperModel.LiveWallpaperModel
31 import com.android.wallpaper.picker.data.WallpaperModel.StaticWallpaperModel
32 
33 /** Interface for persisting and retrieving wallpaper specific preferences. */
34 interface WallpaperPreferences {
35 
36     /** Returns the wallpaper presentation mode. */
getWallpaperPresentationModenull37     @PresentationMode fun getWallpaperPresentationMode(): Int
38 
39     /** Sets the presentation mode of the current wallpaper. */
40     fun setWallpaperPresentationMode(@PresentationMode presentationMode: Int)
41 
42     /** Returns the home attributions as a list. */
43     fun getHomeWallpaperAttributions(): List<String?>?
44 
45     /**
46      * Sets the attributions for the current home wallpaper. Clears existing attributions if any
47      * exist.
48      */
49     fun setHomeWallpaperAttributions(attributions: List<String?>?)
50 
51     /** Returns the home wallpaper's action URL or null if there is none. */
52     fun getHomeWallpaperActionUrl(): String?
53 
54     /** Sets the home wallpaper's action URL. */
55     fun setHomeWallpaperActionUrl(actionUrl: String?)
56 
57     /** Returns the home wallpaper's collection ID or null if there is none. */
58     fun getHomeWallpaperCollectionId(): String?
59 
60     /** Sets the home wallpaper's collection ID. */
61     fun setHomeWallpaperCollectionId(collectionId: String?)
62 
63     /** Removes all home metadata from SharedPreferences. */
64     fun clearHomeWallpaperMetadata()
65 
66     /** Set homescreen static image wallpaper metadata to SharedPreferences. */
67     fun setHomeStaticImageWallpaperMetadata(metadata: StaticWallpaperPrefMetadata)
68 
69     /** Set homescreen live wallpaper metadata to SharedPreferences. */
70     fun setHomeLiveWallpaperMetadata(metadata: LiveWallpaperPrefMetadata)
71 
72     /** Returns the home wallpaper's bitmap hash code or 0 if there is none. */
73     fun getHomeWallpaperHashCode(): Long
74 
75     /** Sets the home wallpaper's bitmap hash code if it is an individual image. */
76     fun setHomeWallpaperHashCode(hashCode: Long)
77 
78     /** Gets the home wallpaper's service name, which is present for live wallpapers. */
79     fun getHomeWallpaperServiceName(): String?
80 
81     /** Sets the home wallpaper's service name, which is present for live wallpapers. */
82     fun setHomeWallpaperServiceName(serviceName: String?)
83 
84     /**
85      * Gets the home wallpaper's ID, which is provided by WallpaperManager for static wallpapers.
86      */
87     fun getHomeWallpaperManagerId(): Int
88 
89     /**
90      * Sets the home wallpaper's ID, which is provided by WallpaperManager for static wallpapers.
91      */
92     fun setHomeWallpaperManagerId(homeWallpaperId: Int)
93 
94     /** Gets the home wallpaper's remote identifier. */
95     fun getHomeWallpaperRemoteId(): String?
96 
97     /**
98      * Sets the home wallpaper's remote identifier to SharedPreferences. This should be a string
99      * which uniquely identifies the currently set home wallpaper in the context of a remote
100      * wallpaper collection.
101      */
102     fun setHomeWallpaperRemoteId(wallpaperRemoteId: String?)
103 
104     /** Gets the home wallpaper's identifier used to index into the list of recent wallpapers. */
105     fun getHomeWallpaperRecentsKey(): String?
106 
107     /** Sets the home wallpaper's identifier used to index into the list of recent wallpapers. */
108     fun setHomeWallpaperRecentsKey(recentsKey: String?)
109 
110     /** Gets the home wallpaper's effects. */
111     fun getHomeWallpaperEffects(): String?
112 
113     /** Sets the home wallpaper's effects to SharedPreferences. */
114     fun setHomeWallpaperEffects(wallpaperEffects: String?)
115 
116     /** Returns the lock screen attributions as a list. */
117     fun getLockWallpaperAttributions(): List<String?>?
118 
119     /**
120      * Sets the attributions for the current lock screen wallpaper. Clears existing attributions if
121      * any exist.
122      */
123     fun setLockWallpaperAttributions(attributions: List<String?>?)
124 
125     /** Returns the lock wallpaper's action URL or null if there is none. */
126     fun getLockWallpaperActionUrl(): String?
127 
128     /** Sets the lock wallpaper's action URL. */
129     fun setLockWallpaperActionUrl(actionUrl: String?)
130 
131     /** Returns the lock wallpaper's collection ID or null if there is none. */
132     fun getLockWallpaperCollectionId(): String?
133 
134     /** Sets the lock wallpaper's collection ID. */
135     fun setLockWallpaperCollectionId(collectionId: String?)
136 
137     /** Removes all lock screen metadata from SharedPreferences. */
138     fun clearLockWallpaperMetadata()
139 
140     /** Set lockscreen static image wallpaper metadata to SharedPreferences. */
141     fun setLockStaticImageWallpaperMetadata(metadata: StaticWallpaperPrefMetadata)
142 
143     /** Set lockscreen live wallpaper metadata to SharedPreferences. */
144     fun setLockLiveWallpaperMetadata(metadata: LiveWallpaperPrefMetadata)
145 
146     /** Returns the lock screen wallpaper's bitmap hash code or 0 if there is none. */
147     fun getLockWallpaperHashCode(): Long
148 
149     /** Sets the lock screen wallpaper's bitmap hash code if it is an individual image. */
150     fun setLockWallpaperHashCode(hashCode: Long)
151 
152     /** Gets the lock wallpaper's service name, which is present for live wallpapers. */
153     fun getLockWallpaperServiceName(): String?
154 
155     /** Sets the lock wallpaper's service name, which is present for live wallpapers. */
156     fun setLockWallpaperServiceName(serviceName: String?)
157 
158     /**
159      * Gets the lock wallpaper's ID, which is provided by WallpaperManager for static wallpapers.
160      */
161     fun getLockWallpaperManagerId(): Int
162 
163     /**
164      * Sets the lock wallpaper's ID, which is provided by WallpaperManager for static wallpapers.
165      */
166     fun setLockWallpaperManagerId(lockWallpaperId: Int)
167 
168     /** Gets the lock wallpaper's remote identifier. */
169     fun getLockWallpaperRemoteId(): String?
170 
171     /**
172      * Sets the lock wallpaper's remote identifier to SharedPreferences. This should be a string
173      * which uniquely identifies the currently set lock wallpaper in the context of a remote
174      * wallpaper collection.
175      */
176     fun setLockWallpaperRemoteId(wallpaperRemoteId: String?)
177 
178     /** Gets lock home wallpaper's identifier used to index into the list of recent wallpapers. */
179     fun getLockWallpaperRecentsKey(): String?
180 
181     /** Sets lock home wallpaper's identifier used to index into the list of recent wallpapers. */
182     fun setLockWallpaperRecentsKey(recentsKey: String?)
183 
184     /** Gets the lock wallpaper's effects. */
185     // TODO (b/307939748): Log lock wallpaper effects. We need this function for snapshot logging
186     fun getLockWallpaperEffects(): String?
187 
188     /** Sets the lock wallpaper's effects to SharedPreferences. */
189     fun setLockWallpaperEffects(wallpaperEffects: String?)
190 
191     /** Persists the timestamp of a daily wallpaper rotation that just occurred. */
192     fun addDailyRotation(timestamp: Long)
193 
194     /**
195      * Returns the timestamp of the last wallpaper daily rotation or -1 if there has never been a
196      * daily wallpaper rotation on the user's device.
197      */
198     fun getLastDailyRotationTimestamp(): Long
199 
200     /**
201      * Returns the daily wallpaper enabled timestamp in milliseconds since Unix epoch, or -1 if
202      * daily wallpaper is not currently enabled.
203      */
204     fun getDailyWallpaperEnabledTimestamp(): Long
205 
206     /**
207      * Persists the timestamp when daily wallpaper feature was last enabled.
208      *
209      * @param timestamp Milliseconds since Unix epoch.
210      */
211     fun setDailyWallpaperEnabledTimestamp(timestamp: Long)
212 
213     /**
214      * Clears the persisted daily rotation timestamps and the "daily wallpaper enabled" timestamp.
215      * Called if daily rotation is disabled.
216      */
217     fun clearDailyRotations()
218 
219     /**
220      * Returns the timestamp of the most recent daily logging event, in milliseconds since Unix
221      * epoch. Returns -1 if the very first daily logging event has not occurred yet.
222      */
223     fun getLastDailyLogTimestamp(): Long
224 
225     /**
226      * Sets the timestamp of the most recent daily logging event.
227      *
228      * @param timestamp Milliseconds since Unix epoch.
229      */
230     fun setLastDailyLogTimestamp(timestamp: Long)
231 
232     /**
233      * Returns the timestamp of the last time the app was noted to be active; i.e. the last time an
234      * activity entered the foreground (milliseconds since Unix epoch).
235      */
236     fun getLastAppActiveTimestamp(): Long
237 
238     /**
239      * Sets the timestamp of the last time the app was noted to be active; i.e. the last time an
240      * activity entered the foreground.
241      *
242      * @param timestamp Milliseconds since Unix epoch.
243      */
244     fun setLastAppActiveTimestamp(timestamp: Long)
245 
246     /**
247      * Sets the last rotation status for daily wallpapers with a timestamp.
248      *
249      * @param status Last status code of daily rotation.
250      * @param timestamp Milliseconds since Unix epoch.
251      */
252     fun setDailyWallpaperRotationStatus(status: Int, timestamp: Long)
253 
254     /**
255      * Sets the status of whether a wallpaper is currently pending being set (i.e., user tapped the
256      * UI to set a wallpaper but it has not yet been actually set on the device). Does so in a
257      * synchronous manner so a caller may be assured that the underlying store has been updated when
258      * this method returns.
259      */
260     fun setPendingWallpaperSetStatusSync(@PendingWallpaperSetStatus setStatus: Int)
261 
262     /** Gets the status of whether a wallpaper is currently pending being set. */
263     @PendingWallpaperSetStatus fun getPendingWallpaperSetStatus(): Int
264 
265     /**
266      * Sets the status of whether a wallpaper is currently pending being set (i.e., user tapped the
267      * UI to set a wallpaper but it has not yet been actually set on the device). Does so in an
268      * asynchronous manner so writing the preference to the underlying store doesn't block the
269      * calling thread.
270      */
271     fun setPendingWallpaperSetStatus(@PendingWallpaperSetStatus setStatus: Int)
272 
273     /**
274      * Sets whether a daily wallpaper update is pending. Writes status to memory and also to disk
275      * before returning.
276      */
277     fun setPendingDailyWallpaperUpdateStatusSync(
278         @PendingDailyWallpaperUpdateStatus updateStatus: Int,
279     )
280 
281     /** Returns whether a daily wallpaper update is pending. */
282     @PendingDailyWallpaperUpdateStatus fun getPendingDailyWallpaperUpdateStatus(): Int
283 
284     /**
285      * Sets whether a daily wallpaper update is pending. Writes status to memory immediately and to
286      * disk after returning.
287      */
288     fun setPendingDailyWallpaperUpdateStatus(@PendingDailyWallpaperUpdateStatus updateStatus: Int)
289 
290     /** Return the count of wallpaper picker launch. */
291     fun getAppLaunchCount(): Int
292 
293     /** Return the date for the first time to launch wallpaper picker. */
294     fun getFirstLaunchDateSinceSetup(): Int
295 
296     /** Increments the number of wallpaper picker launch. */
297     fun incrementAppLaunched()
298 
299     /** Returns the date for the first time to apply a wallpaper. */
300     fun getFirstWallpaperApplyDateSinceSetup(): Int
301 
302     /**
303      * Sets wallpapers colors of wallpaper's id.
304      *
305      * @param storedWallpaperId wallpaper id.
306      * @param wallpaperColors Colors extracted from an image via quantization.
307      */
308     fun storeWallpaperColors(storedWallpaperId: String?, wallpaperColors: WallpaperColors?)
309 
310     /**
311      * Returns the wallpaper colors from wallpaper's id.
312      *
313      * @param storedWallpaperId wallpaper id.
314      */
315     fun getWallpaperColors(storedWallpaperId: String): WallpaperColors?
316 
317     /**
318      * Update currently set daily wallpaper info.
319      *
320      * @param destination The wallpaper destination, 1: home, 2: lockscreen, 3: both.
321      * @param collectionId wallpaper category.
322      * @param wallpaperId wallpaper id.
323      */
324     fun updateDailyWallpaperSet(
325         @WallpaperPersister.Destination destination: Int,
326         collectionId: String?,
327         wallpaperId: String?,
328     )
329 
330     /**
331      * Stores the given live wallpaper in the recent wallpapers list
332      *
333      * @param which flag indicating the wallpaper destination
334      * @param wallpaperId unique identifier for this wallpaper
335      * @param wallpaper [LiveWallpaperInfo] for the applied wallpaper
336      * @param colors WallpaperColors to be used as placeholder for quickswitching
337      */
338     fun storeLatestWallpaper(
339         @SetWallpaperFlags which: Int,
340         wallpaperId: String,
341         wallpaper: LiveWallpaperInfo,
342         colors: WallpaperColors,
343     )
344 
345     /**
346      * Stores the given static wallpaper data in the recent wallpapers list.
347      *
348      * @param which flag indicating the wallpaper destination
349      * @param wallpaperId unique identifier for this wallpaper
350      * @param wallpaper [WallpaperInfo] for the applied wallpaper
351      * @param croppedWallpaperBitmap wallpaper bitmap exactly as applied to WallaperManager
352      * @param colors WallpaperColors to be used as placeholder for quickswitching
353      */
354     fun storeLatestWallpaper(
355         @SetWallpaperFlags which: Int,
356         wallpaperId: String,
357         wallpaper: WallpaperInfo,
358         croppedWallpaperBitmap: Bitmap,
359         colors: WallpaperColors,
360     )
361 
362     /**
363      * Stores the given static wallpaper data in the recent wallpapers list.
364      *
365      * @param which flag indicating the wallpaper destination
366      * @param wallpaperId unique identifier for this wallpaper
367      * @param attributions List of attribution items.
368      * @param actionUrl The action or "explore" URL for the wallpaper.
369      * @param collectionId identifier of this wallpaper's collection.
370      * @param croppedWallpaperBitmap wallpaper bitmap exactly as applied to WallaperManager
371      * @param colors [WallpaperColors] to be used as placeholder for quickswitching
372      */
373     fun storeLatestWallpaper(
374         @SetWallpaperFlags which: Int,
375         wallpaperId: String,
376         attributions: List<String>?,
377         actionUrl: String?,
378         collectionId: String?,
379         croppedWallpaperBitmap: Bitmap,
380         colors: WallpaperColors,
381     )
382 
383     /**
384      * Add a static wallpaper to recent wallpapers as json array, saved in preferences.
385      *
386      * @param destination destination where the wallpaper is set to
387      * @param wallpaperModel static wallpaper model
388      * @param bitmap full sie bitmap of the static wallpaper
389      * @param cropHints crop hints of the static wallpaper
390      */
391     suspend fun addStaticWallpaperToRecentWallpapers(
392         destination: WallpaperDestination,
393         wallpaperModel: StaticWallpaperModel,
394         bitmap: Bitmap,
395         cropHints: Map<Point, Rect>?,
396     )
397 
398     /**
399      * Add a live wallpaper to recent wallpapers as json array, saved in preferences.
400      *
401      * @param destination destination where the wallpaper is set to
402      * @param wallpaperModel live wallpaper model
403      */
404     suspend fun addLiveWallpaperToRecentWallpapers(
405         destination: WallpaperDestination,
406         wallpaperModel: LiveWallpaperModel,
407     )
408 
409     /** Sets whether the preview tooltip should be shown. */
410     fun setHasSmallPreviewTooltipBeenShown(hasTooltipBeenShown: Boolean)
411 
412     /** Gets whether the preview tooltip should be shown. */
413     fun getHasSmallPreviewTooltipBeenShown(): Boolean
414 
415     /** Sets whether the preview tooltip should be shown. */
416     fun setHasFullPreviewTooltipBeenShown(hasTooltipBeenShown: Boolean)
417 
418     /** Gets whether the preview tooltip should be shown. */
419     fun getHasFullPreviewTooltipBeenShown(): Boolean
420 
421     /** The possible wallpaper presentation modes, i.e., either "static" or "rotating". */
422     @IntDef(PRESENTATION_MODE_STATIC, PRESENTATION_MODE_ROTATING) annotation class PresentationMode
423 
424     /** Possible status of whether a wallpaper set operation is pending or not. */
425     @IntDef(WALLPAPER_SET_NOT_PENDING, WALLPAPER_SET_PENDING)
426     annotation class PendingWallpaperSetStatus
427 
428     /** Possible status of whether a wallpaper set operation is pending or not. */
429     @IntDef(DAILY_WALLPAPER_UPDATE_NOT_PENDING, DAILY_WALLPAPER_UPDATE_PENDING)
430     annotation class PendingDailyWallpaperUpdateStatus
431 
432     companion object {
433         /**
434          * Generates a default key to look up a wallpaper in the list of recent wallpapers.
435          *
436          * This key can be used as a fallback when [.getHomeWallpaperRecentsKey] or
437          * [.getLockWallpaperRecentsKey] return null.
438          *
439          * @param remoteId wallpaper's remote id
440          * @param hashCode wallpaper's hash code
441          * @return the recents key
442          */
443         fun generateRecentsKey(remoteId: String?, hashCode: Long): String? {
444             return if (!TextUtils.isEmpty(remoteId)) {
445                 remoteId
446             } else if (hashCode > 0) {
447                 hashCode.toString()
448             } else {
449                 null
450             }
451         }
452 
453         const val PRESENTATION_MODE_STATIC = 1
454         const val PRESENTATION_MODE_ROTATING = 2
455         const val WALLPAPER_SET_NOT_PENDING = 0
456         const val WALLPAPER_SET_PENDING = 1
457         const val DAILY_WALLPAPER_UPDATE_NOT_PENDING = 0
458         const val DAILY_WALLPAPER_UPDATE_PENDING = 1
459     }
460 }
461