1 /* 2 ** Copyright 2015, 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.view; 18 19 import android.app.Activity; 20 import android.app.ActivityManagerNative; 21 import android.os.IBinder; 22 import android.os.Parcel; 23 import android.os.Parcelable; 24 import android.os.RemoteException; 25 26 import com.android.internal.view.IDragAndDropPermissions; 27 28 /** 29 * {@link DragAndDropPermissions} controls the access permissions for the content URIs associated 30 * with a {@link DragEvent}. 31 * <p> 32 * Permission are granted when this object is created by {@link 33 * android.app.Activity#requestDragAndDropPermissions(DragEvent) 34 * Activity.requestDragAndDropPermissions}. 35 * Which permissions are granted is defined by the set of flags passed to {@link 36 * View#startDragAndDrop(android.content.ClipData, View.DragShadowBuilder, Object, int) 37 * View.startDragAndDrop} by the app that started the drag operation. 38 * </p> 39 * <p> 40 * The life cycle of the permissions is bound to the activity used to call {@link 41 * android.app.Activity#requestDragAndDropPermissions(DragEvent) requestDragAndDropPermissions}. The 42 * permissions are revoked when this activity is destroyed, or when {@link #release()} is called, 43 * whichever occurs first. 44 * </p> 45 * <p> 46 * If you anticipate that your application will receive a large number of drops (e.g. document 47 * editor), you should try to call {@link #release()} on the obtained permissions as soon as they 48 * are no longer required. Permissions can be added to your activity's 49 * {@link Activity#onSaveInstanceState} bundle and later retrieved in order to manually release 50 * the permissions once they are no longer needed. 51 * </p> 52 */ 53 public final class DragAndDropPermissions implements Parcelable { 54 55 private final IDragAndDropPermissions mDragAndDropPermissions; 56 57 private IBinder mPermissionOwnerToken; 58 59 /** 60 * Create a new {@link DragAndDropPermissions} object to control the access permissions for 61 * content URIs associated with {@link DragEvent}. 62 * @param dragEvent Drag event 63 * @return {@link DragAndDropPermissions} object or null if there are no content URIs associated 64 * with the {@link DragEvent}. 65 * @hide 66 */ obtain(DragEvent dragEvent)67 public static DragAndDropPermissions obtain(DragEvent dragEvent) { 68 if (dragEvent.getDragAndDropPermissions() == null) { 69 return null; 70 } 71 return new DragAndDropPermissions(dragEvent.getDragAndDropPermissions()); 72 } 73 74 /** @hide */ DragAndDropPermissions(IDragAndDropPermissions dragAndDropPermissions)75 private DragAndDropPermissions(IDragAndDropPermissions dragAndDropPermissions) { 76 mDragAndDropPermissions = dragAndDropPermissions; 77 } 78 79 /** 80 * Take the permissions and bind their lifetime to the activity. 81 * @param activityToken Binder pointing to an Activity instance to bind the lifetime to. 82 * @return True if permissions are successfully taken. 83 * @hide 84 */ take(IBinder activityToken)85 public boolean take(IBinder activityToken) { 86 try { 87 mDragAndDropPermissions.take(activityToken); 88 } catch (RemoteException e) { 89 return false; 90 } 91 return true; 92 } 93 94 /** 95 * Take the permissions. Must call {@link #release} explicitly. 96 * @return True if permissions are successfully taken. 97 * @hide 98 */ takeTransient()99 public boolean takeTransient() { 100 try { 101 mPermissionOwnerToken = ActivityManagerNative.getDefault(). 102 newUriPermissionOwner("drop"); 103 mDragAndDropPermissions.takeTransient(mPermissionOwnerToken); 104 } catch (RemoteException e) { 105 return false; 106 } 107 return true; 108 } 109 110 /** 111 * Revoke permissions explicitly. 112 */ release()113 public void release() { 114 try { 115 mDragAndDropPermissions.release(); 116 mPermissionOwnerToken = null; 117 } catch (RemoteException e) { 118 } 119 } 120 121 public static final Parcelable.Creator<DragAndDropPermissions> CREATOR = 122 new Parcelable.Creator<DragAndDropPermissions> () { 123 @Override 124 public DragAndDropPermissions createFromParcel(Parcel source) { 125 return new DragAndDropPermissions(source); 126 } 127 128 @Override 129 public DragAndDropPermissions[] newArray(int size) { 130 return new DragAndDropPermissions[size]; 131 } 132 }; 133 134 @Override describeContents()135 public int describeContents() { 136 return 0; 137 } 138 139 @Override writeToParcel(Parcel destination, int flags)140 public void writeToParcel(Parcel destination, int flags) { 141 destination.writeStrongInterface(mDragAndDropPermissions); 142 destination.writeStrongBinder(mPermissionOwnerToken); 143 } 144 DragAndDropPermissions(Parcel in)145 private DragAndDropPermissions(Parcel in) { 146 mDragAndDropPermissions = IDragAndDropPermissions.Stub.asInterface(in.readStrongBinder()); 147 mPermissionOwnerToken = in.readStrongBinder(); 148 } 149 } 150