ParcelFileDescriptor.java revision 540f86aa42877ac73f6f2f24dac49382432aa078
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 from the specified Socket. 121 * 122 * @param socket The Socket whose FileDescriptor is used to create 123 * a new ParcelFileDescriptor. 124 * 125 * @return A new ParcelFileDescriptor with the FileDescriptor of the 126 * specified Socket. 127 */ 128 public static ParcelFileDescriptor fromSocket(Socket socket) { 129 FileDescriptor fd = getFileDescriptorFromSocket(socket); 130 return fd != null ? new ParcelFileDescriptor(fd) : null; 131 } 132 133 // Extracts the file descriptor from the specified socket and returns it untouched 134 private static native FileDescriptor getFileDescriptorFromSocket(Socket socket); 135 136 /** 137 * Create two ParcelFileDescriptors structured as a data pipe. The first 138 * ParcelFileDescriptor in the returned array is the read side; the second 139 * is the write side. 140 */ 141 public static ParcelFileDescriptor[] createPipe() throws IOException { 142 FileDescriptor[] fds = new FileDescriptor[2]; 143 int res = createPipeNative(fds); 144 if (res == 0) { 145 ParcelFileDescriptor[] pfds = new ParcelFileDescriptor[2]; 146 pfds[0] = new ParcelFileDescriptor(fds[0]); 147 pfds[1] = new ParcelFileDescriptor(fds[1]); 148 return pfds; 149 } 150 throw new IOException("Unable to create pipe: errno=" + -res); 151 } 152 153 private static native int createPipeNative(FileDescriptor[] outFds); 154 155 /** 156 * @hide Please use createPipe() or ContentProvider.openPipeHelper(). 157 * Gets a file descriptor for a read-only copy of the given data. 158 * 159 * @param data Data to copy. 160 * @param name Name for the shared memory area that may back the file descriptor. 161 * This is purely informative and may be {@code null}. 162 * @return A ParcelFileDescriptor. 163 * @throws IOException if there is an error while creating the shared memory area. 164 */ 165 @Deprecated 166 public static ParcelFileDescriptor fromData(byte[] data, String name) throws IOException { 167 if (data == null) return null; 168 MemoryFile file = new MemoryFile(name, data.length); 169 if (data.length > 0) { 170 file.writeBytes(data, 0, 0, data.length); 171 } 172 file.deactivate(); 173 FileDescriptor fd = file.getFileDescriptor(); 174 return fd != null ? new ParcelFileDescriptor(fd) : null; 175 } 176 177 /** 178 * Retrieve the actual FileDescriptor associated with this object. 179 * 180 * @return Returns the FileDescriptor associated with this object. 181 */ 182 public FileDescriptor getFileDescriptor() { 183 return mFileDescriptor; 184 } 185 186 /** 187 * Return the total size of the file representing this fd, as determined 188 * by stat(). Returns -1 if the fd is not a file. 189 */ 190 public native long getStatSize(); 191 192 /** 193 * This is needed for implementing AssetFileDescriptor.AutoCloseOutputStream, 194 * and I really don't think we want it to be public. 195 * @hide 196 */ 197 public native long seekTo(long pos); 198 199 /** 200 * Close the ParcelFileDescriptor. This implementation closes the underlying 201 * OS resources allocated to represent this stream. 202 * 203 * @throws IOException 204 * If an error occurs attempting to close this ParcelFileDescriptor. 205 */ 206 public void close() throws IOException { 207 synchronized (this) { 208 if (mClosed) return; 209 mClosed = true; 210 } 211 if (mParcelDescriptor != null) { 212 // If this is a proxy to another file descriptor, just call through to its 213 // close method. 214 mParcelDescriptor.close(); 215 } else { 216 Parcel.closeFileDescriptor(mFileDescriptor); 217 } 218 } 219 220 /** 221 * An InputStream you can create on a ParcelFileDescriptor, which will 222 * take care of calling {@link ParcelFileDescriptor#close 223 * ParcelFileDescriptor.close()} for you when the stream is closed. 224 */ 225 public static class AutoCloseInputStream extends FileInputStream { 226 private final ParcelFileDescriptor mFd; 227 228 public AutoCloseInputStream(ParcelFileDescriptor fd) { 229 super(fd.getFileDescriptor()); 230 mFd = fd; 231 } 232 233 @Override 234 public void close() throws IOException { 235 try { 236 mFd.close(); 237 } finally { 238 super.close(); 239 } 240 } 241 } 242 243 /** 244 * An OutputStream you can create on a ParcelFileDescriptor, which will 245 * take care of calling {@link ParcelFileDescriptor#close 246 * ParcelFileDescriptor.close()} for you when the stream is closed. 247 */ 248 public static class AutoCloseOutputStream extends FileOutputStream { 249 private final ParcelFileDescriptor mFd; 250 251 public AutoCloseOutputStream(ParcelFileDescriptor fd) { 252 super(fd.getFileDescriptor()); 253 mFd = fd; 254 } 255 256 @Override 257 public void close() throws IOException { 258 try { 259 mFd.close(); 260 } finally { 261 super.close(); 262 } 263 } 264 } 265 266 @Override 267 public String toString() { 268 return "{ParcelFileDescriptor: " + mFileDescriptor + "}"; 269 } 270 271 @Override 272 protected void finalize() throws Throwable { 273 try { 274 if (!mClosed) { 275 close(); 276 } 277 } finally { 278 super.finalize(); 279 } 280 } 281 282 public ParcelFileDescriptor(ParcelFileDescriptor descriptor) { 283 super(); 284 mParcelDescriptor = descriptor; 285 mFileDescriptor = mParcelDescriptor.mFileDescriptor; 286 } 287 288 /*package */ParcelFileDescriptor(FileDescriptor descriptor) { 289 super(); 290 if (descriptor == null) { 291 throw new NullPointerException("descriptor must not be null"); 292 } 293 mFileDescriptor = descriptor; 294 mParcelDescriptor = null; 295 } 296 297 /* Parcelable interface */ 298 public int describeContents() { 299 return Parcelable.CONTENTS_FILE_DESCRIPTOR; 300 } 301 302 /** 303 * {@inheritDoc} 304 * If {@link Parcelable#PARCELABLE_WRITE_RETURN_VALUE} is set in flags, 305 * the file descriptor will be closed after a copy is written to the Parcel. 306 */ 307 public void writeToParcel(Parcel out, int flags) { 308 out.writeFileDescriptor(mFileDescriptor); 309 if ((flags&PARCELABLE_WRITE_RETURN_VALUE) != 0 && !mClosed) { 310 try { 311 close(); 312 } catch (IOException e) { 313 // Empty 314 } 315 } 316 } 317 318 public static final Parcelable.Creator<ParcelFileDescriptor> CREATOR 319 = new Parcelable.Creator<ParcelFileDescriptor>() { 320 public ParcelFileDescriptor createFromParcel(Parcel in) { 321 return in.readFileDescriptor(); 322 } 323 public ParcelFileDescriptor[] newArray(int size) { 324 return new ParcelFileDescriptor[size]; 325 } 326 }; 327 328} 329