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