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.RequiresApi; 21 import android.content.Context; 22 import android.hardware.display.DisplayManager; 23 import android.os.Build; 24 import android.os.IBinder; 25 import android.view.AttachedSurfaceControl; 26 27 import androidx.annotation.NonNull; 28 29 import java.util.concurrent.Executor; 30 31 /** 32 * This interface provides an api that callers can use to get a session of embedded PhotoPicker 33 * ({@link EmbeddedPhotoPickerSession}). 34 * 35 * <p> Callers can get instance of this class using 36 * {@link EmbeddedPhotoPickerProviderFactory#create(Context)}. 37 * 38 * <p> Under the hood, a service connection with photopicker is established by the implementation 39 * of this api. To help establish this connection, a caller must include in their Manifest: 40 * <pre>{@code 41 * <queries> 42 * <intent> 43 * <action android:name="com.android.photopicker.core.embedded.EmbeddedService.BIND"/> 44 * </intent> 45 * </queries> 46 * }</pre> 47 * 48 * <p> When a session opens successfully, they would receive an instance of 49 * {@link EmbeddedPhotoPickerSession} and {@link android.view.SurfaceControlViewHost.SurfacePackage} 50 * via the {@link EmbeddedPhotoPickerClient#onSessionOpened api} 51 * 52 * <p> Callers pass an instance of {@link EmbeddedPhotoPickerClient} which is used by service to 53 * notify about different events (like sessionError, uri granted/revoked etc) to them. 54 * One-to-one relationship of client to session must be maintained by a caller i.e. they shouldn't 55 * reuse same callback for more than one openSession requests. 56 * 57 * <p> The {@link EmbeddedPhotoPickerSession} instance can be used to notify photopicker about 58 * different events (like resize, configChange etc). 59 * 60 * <p> This api is supported on api versions Android U+. 61 * 62 * @see EmbeddedPhotoPickerClient 63 * @see EmbeddedPhotoPickerSession 64 * @see EmbeddedPhotoPickerProviderFactory 65 * 66 * todo(b/358513325): Move this to new package when its ready 67 */ 68 @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) 69 @FlaggedApi("com.android.providers.media.flags.enable_embedded_photopicker") 70 public interface EmbeddedPhotoPickerProvider { 71 72 /** 73 * Open a new session for displaying content with an initial size of 74 * width x height pixels. {@link EmbeddedPhotoPickerClient} will receive all incoming 75 * communication from the PhotoPicker. All incoming calls to {@link EmbeddedPhotoPickerClient} 76 * will be made through the provided {@code clientExecutor} 77 * 78 * @param hostToken Token used for constructing {@link android.view.SurfaceControlViewHost}. 79 * Use {@link AttachedSurfaceControl#getInputTransferToken()} to 80 * get token of attached 81 * {@link android.view.SurfaceControlViewHost.SurfacePackage}. 82 * @param displayId Application display id. Use 83 * {@link DisplayManager#getDisplays()} to get the id. 84 * @param width width of the view, in pixels. 85 * @param height height of the view, in pixels. 86 * @param featureInfo {@link EmbeddedPhotoPickerFeatureInfo} object containing all 87 * the required features for the given session. 88 * @param clientExecutor {@link Executor} to invoke callbacks. 89 * @param callback {@link EmbeddedPhotoPickerClient} object to receive callbacks 90 * from photopicker. 91 */ openSession( @onNull IBinder hostToken, int displayId, int width, int height, @NonNull EmbeddedPhotoPickerFeatureInfo featureInfo, @NonNull Executor clientExecutor, @NonNull EmbeddedPhotoPickerClient callback)92 void openSession( 93 @NonNull IBinder hostToken, 94 int displayId, 95 int width, 96 int height, 97 @NonNull EmbeddedPhotoPickerFeatureInfo featureInfo, 98 @NonNull Executor clientExecutor, 99 @NonNull EmbeddedPhotoPickerClient callback); 100 } 101 102