1 /* 2 * Copyright 2024 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.photopicker.features.search.data 18 19 import android.os.CancellationSignal 20 import androidx.paging.PagingSource 21 import com.android.photopicker.data.model.Media 22 import com.android.photopicker.data.model.MediaPageKey 23 import com.android.photopicker.features.search.model.SearchSuggestion 24 import com.android.photopicker.features.search.model.UserSearchStateInfo 25 import kotlinx.coroutines.flow.StateFlow 26 27 /** 28 * Powers UI with data for the search feature. This class owns the responsibility to: 29 * - fetch data on demand 30 * - cache data if required 31 * - keep track of data updates in the data source 32 * - detect and refresh stale data 33 */ 34 interface SearchDataService { 35 companion object { 36 const val TAG: String = "PhotopickerSearchDataService" 37 } 38 39 /** 40 * A [StateFlow] that emits a value when current profile changes or the current profile's 41 * available provider changes. It hold that value of the current profile's search enabled state 42 * [UserSearchStateInfo]. 43 */ 44 val userSearchStateInfo: StateFlow<UserSearchStateInfo> 45 46 /** 47 * Get search suggestions for the user in zero state and as the user is typing. 48 * 49 * @param prefix The search text typed so far by the user. If the user is in zero-state (has not 50 * typed anything), the prefix will be null. 51 * @param limit Maximum number of search suggestions. 52 * @param cancellationSignal used to indicate that the fetch suggestions operation should be 53 * cancelled. If the user has cleared the search text or the prefix has changed, UI layer can 54 * choose to stop the get suggestions operation to save resources. 55 * @return A list of [SearchSuggestion]-s. 56 */ getSearchSuggestionsnull57 suspend fun getSearchSuggestions( 58 prefix: String, 59 limit: Int = 200, 60 cancellationSignal: CancellationSignal? = null, 61 ): List<SearchSuggestion> 62 63 /** 64 * Get search results for a search suggestion. This method should be used when the user searches 65 * for an item by selecting a search suggestion. 66 * 67 * @param suggestion The search suggestion the user selected. 68 * @return The [PagingSource] that fetches a page using [MediaPageKey]. A page in the paging 69 * source contains a [List] of [Media] items. 70 */ 71 fun getSearchResults( 72 suggestion: SearchSuggestion, 73 cancellationSignal: CancellationSignal? = null, 74 ): PagingSource<MediaPageKey, Media> 75 76 /** 77 * Get search results for a search text query. This method should be used when the user searches 78 * for an item by entering something in the search bar. 79 * 80 * @param searchText The search text that the user entered. 81 * @return The [PagingSource] that fetches a page using [MediaPageKey]. A page in the paging 82 * source contains a [List] of [Media] items. 83 */ 84 fun getSearchResults( 85 searchText: String, 86 cancellationSignal: CancellationSignal? = null, 87 ): PagingSource<MediaPageKey, Media> 88 } 89