SliceProvider.java revision b31c3281d870e9abb673db239234d580dcc4feff
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 */ 16package androidx.slice; 17 18import android.content.ContentProvider; 19import android.content.ContentResolver; 20import android.content.Context; 21import android.content.Intent; 22import android.content.IntentFilter; 23import android.content.pm.ProviderInfo; 24import android.database.ContentObserver; 25import android.net.Uri; 26import androidx.annotation.NonNull; 27import androidx.annotation.RestrictTo; 28import androidx.core.os.BuildCompat; 29 30import java.util.List; 31 32import androidx.slice.compat.ContentProviderWrapper; 33import androidx.slice.compat.SliceProviderCompat; 34import androidx.slice.compat.SliceProviderWrapperContainer; 35 36/** 37 * A SliceProvider allows an app to provide content to be displayed in system spaces. This content 38 * is templated and can contain actions, and the behavior of how it is surfaced is specific to the 39 * system surface. 40 * <p> 41 * Slices are not currently live content. They are bound once and shown to the user. If the content 42 * changes due to a callback from user interaction, then 43 * {@link ContentResolver#notifyChange(Uri, ContentObserver)} should be used to notify the system. 44 * </p> 45 * <p> 46 * The provider needs to be declared in the manifest to provide the authority for the app. The 47 * authority for most slices is expected to match the package of the application. 48 * </p> 49 * 50 * <pre class="prettyprint"> 51 * {@literal 52 * <provider 53 * android:name="com.android.mypkg.MySliceProvider" 54 * android:authorities="com.android.mypkg" />} 55 * </pre> 56 * <p> 57 * Slices can be identified by a Uri or by an Intent. To link an Intent with a slice, the provider 58 * must have an {@link IntentFilter} matching the slice intent. When a slice is being requested via 59 * an intent, {@link #onMapIntentToUri(Intent)} can be called and is expected to return an 60 * appropriate Uri representing the slice. 61 * 62 * <pre class="prettyprint"> 63 * {@literal 64 * <provider 65 * android:name="com.android.mypkg.MySliceProvider" 66 * android:authorities="com.android.mypkg"> 67 * <intent-filter> 68 * <action android:name="android.intent.action.MY_SLICE_INTENT" /> 69 * </intent-filter> 70 * </provider>} 71 * </pre> 72 * 73 * @see android.app.slice.Slice 74 */ 75public abstract class SliceProvider extends ContentProviderWrapper { 76 77 private static List<SliceSpec> sSpecs; 78 79 @Override 80 public void attachInfo(Context context, ProviderInfo info) { 81 ContentProvider impl; 82 if (BuildCompat.isAtLeastP()) { 83 impl = new SliceProviderWrapperContainer.SliceProviderWrapper(this); 84 } else { 85 impl = new SliceProviderCompat(this); 86 } 87 super.attachInfo(context, info, impl); 88 } 89 90 /** 91 * Implement this to initialize your slice provider on startup. 92 * This method is called for all registered slice providers on the 93 * application main thread at application launch time. It must not perform 94 * lengthy operations, or application startup will be delayed. 95 * 96 * <p>You should defer nontrivial initialization (such as opening, 97 * upgrading, and scanning databases) until the slice provider is used 98 * (via #onBindSlice, etc). Deferred initialization 99 * keeps application startup fast, avoids unnecessary work if the provider 100 * turns out not to be needed, and stops database errors (such as a full 101 * disk) from halting application launch. 102 * 103 * @return true if the provider was successfully loaded, false otherwise 104 */ 105 public abstract boolean onCreateSliceProvider(); 106 107 /** 108 * Implemented to create a slice. Will be called on the main thread. 109 * <p> 110 * onBindSlice should return as quickly as possible so that the UI tied 111 * to this slice can be responsive. No network or other IO will be allowed 112 * during onBindSlice. Any loading that needs to be done should happen 113 * off the main thread with a call to {@link ContentResolver#notifyChange(Uri, ContentObserver)} 114 * when the app is ready to provide the complete data in onBindSlice. 115 * <p> 116 * 117 * @see {@link Slice}. 118 * @see {@link android.app.slice.Slice#HINT_PARTIAL} 119 */ 120 // TODO: Provide alternate notifyChange that takes in the slice (i.e. notifyChange(Uri, Slice)). 121 public abstract Slice onBindSlice(Uri sliceUri); 122 123 /** 124 * Called to inform an app that a slice has been pinned. 125 * <p> 126 * Pinning is a way that slice hosts use to notify apps of which slices 127 * they care about updates for. When a slice is pinned the content is 128 * expected to be relatively fresh and kept up to date. 129 * <p> 130 * Being pinned does not provide any escalated privileges for the slice 131 * provider. So apps should do things such as turn on syncing or schedule 132 * a job in response to a onSlicePinned. 133 * <p> 134 * Pinned state is not persisted through a reboot, and apps can expect a 135 * new call to onSlicePinned for any slices that should remain pinned 136 * after a reboot occurs. 137 * 138 * @param sliceUri The uri of the slice being unpinned. 139 * @see #onSliceUnpinned(Uri) 140 */ 141 public void onSlicePinned(Uri sliceUri) { 142 } 143 144 /** 145 * Called to inform an app that a slices is no longer pinned. 146 * <p> 147 * This means that no other apps on the device care about updates to this 148 * slice anymore and therefore it is not important to be updated. Any syncs 149 * or jobs related to this slice should be cancelled. 150 * @see #onSlicePinned(Uri) 151 */ 152 public void onSliceUnpinned(Uri sliceUri) { 153 } 154 155 /** 156 * This method must be overridden if an {@link IntentFilter} is specified on the SliceProvider. 157 * In that case, this method can be called and is expected to return a non-null Uri representing 158 * a slice. Otherwise this will throw {@link UnsupportedOperationException}. 159 * 160 * @return Uri representing the slice associated with the provided intent. 161 * @see {@link android.app.slice.Slice} 162 */ 163 public @NonNull Uri onMapIntentToUri(Intent intent) { 164 throw new UnsupportedOperationException( 165 "This provider has not implemented intent to uri mapping"); 166 } 167 168 /** 169 * @hide 170 */ 171 @RestrictTo(RestrictTo.Scope.LIBRARY) 172 public static void setSpecs(List<SliceSpec> specs) { 173 sSpecs = specs; 174 } 175 176 /** 177 * @hide 178 */ 179 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) 180 public static List<SliceSpec> getCurrentSpecs() { 181 return sSpecs; 182 } 183} 184