ParcelFileDescriptor.java revision 4390758f277645de6e81f6482d582473383cc917
1/* 2 * Copyright (C) 2006 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 17package android.os; 18import java.io.File; 19import java.io.FileDescriptor; 20import java.io.FileInputStream; 21import java.io.FileNotFoundException; 22import java.io.FileOutputStream; 23import java.io.IOException; 24import java.net.Socket; 25 26/** 27 * The FileDescriptor returned by {@link Parcel#readFileDescriptor}, allowing 28 * you to close it when done with it. 29 */ 30public class ParcelFileDescriptor implements Parcelable { 31 private final FileDescriptor mFileDescriptor; 32 private boolean mClosed; 33 //this field is to create wrapper for ParcelFileDescriptor using another 34 //PartialFileDescriptor but avoid invoking close twice 35 //consider ParcelFileDescriptor A(fileDescriptor fd), ParcelFileDescriptor B(A) 36 //in this particular case fd.close might be invoked twice. 37 private final ParcelFileDescriptor mParcelDescriptor; 38 39 /** 40 * For use with {@link #open}: if {@link #MODE_CREATE} has been supplied 41 * and this file doesn't already exist, then create the file with 42 * permissions such that any application can read it. 43 */ 44 public static final int MODE_WORLD_READABLE = 0x00000001; 45 46 /** 47 * For use with {@link #open}: if {@link #MODE_CREATE} has been supplied 48 * and this file doesn't already exist, then create the file with 49 * permissions such that any application can write it. 50 */ 51 public static final int MODE_WORLD_WRITEABLE = 0x00000002; 52 53 /** 54 * For use with {@link #open}: open the file with read-only access. 55 */ 56 public static final int MODE_READ_ONLY = 0x10000000; 57 58 /** 59 * For use with {@link #open}: open the file with write-only access. 60 */ 61 public static final int MODE_WRITE_ONLY = 0x20000000; 62 63 /** 64 * For use with {@link #open}: open the file with read and write access. 65 */ 66 public static final int MODE_READ_WRITE = 0x30000000; 67 68 /** 69 * For use with {@link #open}: create the file if it doesn't already exist. 70 */ 71 public static final int MODE_CREATE = 0x08000000; 72 73 /** 74 * For use with {@link #open}: erase contents of file when opening. 75 */ 76 public static final int MODE_TRUNCATE = 0x04000000; 77 78 /** 79 * For use with {@link #open}: append to end of file while writing. 80 */ 81 public static final int MODE_APPEND = 0x02000000; 82 83 /** 84 * Create a new ParcelFileDescriptor accessing a given file. 85 * 86 * @param file The file to be opened. 87 * @param mode The desired access mode, must be one of 88 * {@link #MODE_READ_ONLY}, {@link #MODE_WRITE_ONLY}, or 89 * {@link #MODE_READ_WRITE}; may also be any combination of 90 * {@link #MODE_CREATE}, {@link #MODE_TRUNCATE}, 91 * {@link #MODE_WORLD_READABLE}, and {@link #MODE_WORLD_WRITEABLE}. 92 * 93 * @return Returns a new ParcelFileDescriptor pointing to the given 94 * file. 95 * 96 * @throws FileNotFoundException Throws FileNotFoundException if the given 97 * file does not exist or can not be opened with the requested mode. 98 */ 99 public static ParcelFileDescriptor open(File file, int mode) 100 throws FileNotFoundException { 101 String path = file.getPath(); 102 SecurityManager security = System.getSecurityManager(); 103 if (security != null) { 104 security.checkRead(path); 105 if ((mode&MODE_WRITE_ONLY) != 0) { 106 security.checkWrite(path); 107 } 108 } 109 110 if ((mode&MODE_READ_WRITE) == 0) { 111 throw new IllegalArgumentException( 112 "Must specify MODE_READ_ONLY, MODE_WRITE_ONLY, or MODE_READ_WRITE"); 113 } 114 115 FileDescriptor fd = Parcel.openFileDescriptor(path, mode); 116 return fd != null ? new ParcelFileDescriptor(fd) : null; 117 } 118 119 /** 120 * Create a new ParcelFileDescriptor that is a dup of an existing 121 * FileDescriptor. This obeys standard POSIX semantics, where the 122 * new file descriptor shared state such as file position with the 123 * original file descriptor. 124 */ 125 public static ParcelFileDescriptor dup(FileDescriptor orig) throws IOException { 126 FileDescriptor fd = Parcel.dupFileDescriptor(orig); 127 return fd != null ? new ParcelFileDescriptor(fd) : null; 128 } 129 130 /** 131 * Create a new ParcelFileDescriptor from the specified Socket. 132 * 133 * @param socket The Socket whose FileDescriptor is used to create 134 * a new ParcelFileDescriptor. 135 * 136 * @return A new ParcelFileDescriptor with the FileDescriptor of the 137 * specified Socket. 138 */ 139 public static ParcelFileDescriptor fromSocket(Socket socket) { 140 FileDescriptor fd = socket.getFileDescriptor$(); 141 return fd != null ? new ParcelFileDescriptor(fd) : null; 142 } 143 144 /** 145 * Create two ParcelFileDescriptors structured as a data pipe. The first 146 * ParcelFileDescriptor in the returned array is the read side; the second 147 * is the write side. 148 */ 149 public static ParcelFileDescriptor[] createPipe() throws IOException { 150 FileDescriptor[] fds = new FileDescriptor[2]; 151 int res = createPipeNative(fds); 152 if (res == 0) { 153 ParcelFileDescriptor[] pfds = new ParcelFileDescriptor[2]; 154 pfds[0] = new ParcelFileDescriptor(fds[0]); 155 pfds[1] = new ParcelFileDescriptor(fds[1]); 156 return pfds; 157 } 158 throw new IOException("Unable to create pipe: errno=" + -res); 159 } 160 161 private static native int createPipeNative(FileDescriptor[] outFds); 162 163 /** 164 * @hide Please use createPipe() or ContentProvider.openPipeHelper(). 165 * Gets a file descriptor for a read-only copy of the given data. 166 * 167 * @param data Data to copy. 168 * @param name Name for the shared memory area that may back the file descriptor. 169 * This is purely informative and may be {@code null}. 170 * @return A ParcelFileDescriptor. 171 * @throws IOException if there is an error while creating the shared memory area. 172 */ 173 @Deprecated 174 public static ParcelFileDescriptor fromData(byte[] data, String name) throws IOException { 175 if (data == null) return null; 176 MemoryFile file = new MemoryFile(name, data.length); 177 if (data.length > 0) { 178 file.writeBytes(data, 0, 0, data.length); 179 } 180 file.deactivate(); 181 FileDescriptor fd = file.getFileDescriptor(); 182 return fd != null ? new ParcelFileDescriptor(fd) : null; 183 } 184 185 /** 186 * Retrieve the actual FileDescriptor associated with this object. 187 * 188 * @return Returns the FileDescriptor associated with this object. 189 */ 190 public FileDescriptor getFileDescriptor() { 191 return mFileDescriptor; 192 } 193 194 /** 195 * Return the total size of the file representing this fd, as determined 196 * by stat(). Returns -1 if the fd is not a file. 197 */ 198 public native long getStatSize(); 199 200 /** 201 * This is needed for implementing AssetFileDescriptor.AutoCloseOutputStream, 202 * and I really don't think we want it to be public. 203 * @hide 204 */ 205 public native long seekTo(long pos); 206 207 /** 208 * Return the native fd int for this ParcelFileDescriptor. The 209 * ParcelFileDescriptor still owns the fd, and it still must be closed 210 * through this API. 211 */ 212 public int getFd() { 213 if (mClosed) { 214 throw new IllegalStateException("Already closed"); 215 } 216 return getFdNative(); 217 } 218 219 private native int getFdNative(); 220 221 /** 222 * Return the native fd int for this ParcelFileDescriptor and detach it 223 * from the object here. You are now responsible for closing the fd in 224 * native code. 225 */ 226 public int detachFd() { 227 if (mClosed) { 228 throw new IllegalStateException("Already closed"); 229 } 230 if (mParcelDescriptor != null) { 231 int fd = mParcelDescriptor.detachFd(); 232 mClosed = true; 233 return fd; 234 } 235 int fd = getFd(); 236 mClosed = true; 237 Parcel.clearFileDescriptor(mFileDescriptor); 238 return fd; 239 } 240 241 /** 242 * Close the ParcelFileDescriptor. This implementation closes the underlying 243 * OS resources allocated to represent this stream. 244 * 245 * @throws IOException 246 * If an error occurs attempting to close this ParcelFileDescriptor. 247 */ 248 public void close() throws IOException { 249 synchronized (this) { 250 if (mClosed) return; 251 mClosed = true; 252 } 253 if (mParcelDescriptor != null) { 254 // If this is a proxy to another file descriptor, just call through to its 255 // close method. 256 mParcelDescriptor.close(); 257 } else { 258 Parcel.closeFileDescriptor(mFileDescriptor); 259 } 260 } 261 262 /** 263 * An InputStream you can create on a ParcelFileDescriptor, which will 264 * take care of calling {@link ParcelFileDescriptor#close 265 * ParcelFileDescriptor.close()} for you when the stream is closed. 266 */ 267 public static class AutoCloseInputStream extends FileInputStream { 268 private final ParcelFileDescriptor mFd; 269 270 public AutoCloseInputStream(ParcelFileDescriptor fd) { 271 super(fd.getFileDescriptor()); 272 mFd = fd; 273 } 274 275 @Override 276 public void close() throws IOException { 277 try { 278 mFd.close(); 279 } finally { 280 super.close(); 281 } 282 } 283 } 284 285 /** 286 * An OutputStream you can create on a ParcelFileDescriptor, which will 287 * take care of calling {@link ParcelFileDescriptor#close 288 * ParcelFileDescriptor.close()} for you when the stream is closed. 289 */ 290 public static class AutoCloseOutputStream extends FileOutputStream { 291 private final ParcelFileDescriptor mFd; 292 293 public AutoCloseOutputStream(ParcelFileDescriptor fd) { 294 super(fd.getFileDescriptor()); 295 mFd = fd; 296 } 297 298 @Override 299 public void close() throws IOException { 300 try { 301 mFd.close(); 302 } finally { 303 super.close(); 304 } 305 } 306 } 307 308 @Override 309 public String toString() { 310 return "{ParcelFileDescriptor: " + mFileDescriptor + "}"; 311 } 312 313 @Override 314 protected void finalize() throws Throwable { 315 try { 316 if (!mClosed) { 317 close(); 318 } 319 } finally { 320 super.finalize(); 321 } 322 } 323 324 public ParcelFileDescriptor(ParcelFileDescriptor descriptor) { 325 super(); 326 mParcelDescriptor = descriptor; 327 mFileDescriptor = mParcelDescriptor.mFileDescriptor; 328 } 329 330 /*package */ParcelFileDescriptor(FileDescriptor descriptor) { 331 super(); 332 if (descriptor == null) { 333 throw new NullPointerException("descriptor must not be null"); 334 } 335 mFileDescriptor = descriptor; 336 mParcelDescriptor = null; 337 } 338 339 /* Parcelable interface */ 340 public int describeContents() { 341 return Parcelable.CONTENTS_FILE_DESCRIPTOR; 342 } 343 344 /** 345 * {@inheritDoc} 346 * If {@link Parcelable#PARCELABLE_WRITE_RETURN_VALUE} is set in flags, 347 * the file descriptor will be closed after a copy is written to the Parcel. 348 */ 349 public void writeToParcel(Parcel out, int flags) { 350 out.writeFileDescriptor(mFileDescriptor); 351 if ((flags&PARCELABLE_WRITE_RETURN_VALUE) != 0 && !mClosed) { 352 try { 353 close(); 354 } catch (IOException e) { 355 // Empty 356 } 357 } 358 } 359 360 public static final Parcelable.Creator<ParcelFileDescriptor> CREATOR 361 = new Parcelable.Creator<ParcelFileDescriptor>() { 362 public ParcelFileDescriptor createFromParcel(Parcel in) { 363 return in.readFileDescriptor(); 364 } 365 public ParcelFileDescriptor[] newArray(int size) { 366 return new ParcelFileDescriptor[size]; 367 } 368 }; 369 370} 371