1 /* 2 * Copyright (C) 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 android.widget.photopicker; 18 19 import android.annotation.FlaggedApi; 20 import android.annotation.NonNull; 21 import android.annotation.RequiresApi; 22 import android.net.Uri; 23 import android.os.Build; 24 25 import java.util.List; 26 27 /** 28 * Callback to define mechanisms by which can apps can receive notifications about 29 * different events from embedded photopicker for the corresponding Session 30 * ({@link EmbeddedPhotoPickerSession}). 31 * 32 * <p> PhotoPicker will invoke the methods of this interface on the Executor provided by 33 * the caller in {@link EmbeddedPhotoPickerProvider#openSession} 34 * 35 * <p> Any methods on a single instance of this object will always be invoked in a non-concurrent 36 * or thread safe way. In other words, all methods are invoked in a serial execution manner 37 * on the executor passed by the caller. Hence callers wouldn't need any buffer or locking 38 * mechanism on their end. 39 * 40 * @see EmbeddedPhotoPickerProvider 41 * 42 */ 43 @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) 44 @FlaggedApi("com.android.providers.media.flags.enable_embedded_photopicker") 45 public interface EmbeddedPhotoPickerClient { 46 47 /** 48 * Reports that session of app with photopicker was established successfully. 49 * Also shares {@link EmbeddedPhotoPickerSession} handle containing the view 50 * with the caller that should be used to notify the session of UI events. 51 */ onSessionOpened(@onNull EmbeddedPhotoPickerSession session)52 void onSessionOpened(@NonNull EmbeddedPhotoPickerSession session); 53 54 /** 55 * Reports that terminal error has occurred in the session. Any further events 56 * notified on this session will be ignored. The embedded photopicker view will be 57 * torn down along with session upon error. 58 */ onSessionError(@onNull Throwable cause)59 void onSessionError(@NonNull Throwable cause); 60 61 /** 62 * Reports that URI permission has been granted to the item selected by the user. 63 * 64 * <p> It is possible that the permission to the URI was revoked if the item was unselected 65 * by user before the URI is actually accessed by the caller. Hence callers must 66 * handle {@code SecurityException} when attempting to read or use the URI in 67 * response to this callback. 68 */ onUriPermissionGranted(@onNull List<Uri> uris)69 void onUriPermissionGranted(@NonNull List<Uri> uris); 70 71 /** 72 * Reports that URI permission has been revoked of the item deselected by the 73 * user. 74 */ onUriPermissionRevoked(@onNull List<Uri> uris)75 void onUriPermissionRevoked(@NonNull List<Uri> uris); 76 77 /** 78 * Reports that the user is done with their selection and should collapse the picker. 79 * 80 * <p> This doesn't necessarily mean that the session should be closed, but rather the user 81 * has indicated that they are done selecting images and should go back to the app. </p> 82 */ onSelectionComplete()83 void onSelectionComplete(); 84 } 85