ParcelFileDescriptor.java revision 3dec7d563a2f3e1eb967ce2054a00b6620e3558c 
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 new ParcelFileDescriptor(fd);
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 new ParcelFileDescriptor(fd);
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     * Retrieve the actual FileDescriptor associated with this object.
138     *
139     * @return Returns the FileDescriptor associated with this object.
140     */
141    public FileDescriptor getFileDescriptor() {
142        return mFileDescriptor;
143    }
144
145    /**
146     * Return the total size of the file representing this fd, as determined
147     * by stat().  Returns -1 if the fd is not a file.
148     */
149    public native long getStatSize();
150
151    /**
152     * This is needed for implementing AssetFileDescriptor.AutoCloseOutputStream,
153     * and I really don't think we want it to be public.
154     * @hide
155     */
156    public native long seekTo(long pos);
157
158    /**
159     * Close the ParcelFileDescriptor. This implementation closes the underlying
160     * OS resources allocated to represent this stream.
161     *
162     * @throws IOException
163     *             If an error occurs attempting to close this ParcelFileDescriptor.
164     */
165    public void close() throws IOException {
166        mClosed = true;
167        if (mParcelDescriptor != null) {
168            // If this is a proxy to another file descriptor, just call through to its
169            // close method.
170            mParcelDescriptor.close();
171        } else {
172            Parcel.closeFileDescriptor(mFileDescriptor);
173        }
174    }
175
176    /**
177     * An InputStream you can create on a ParcelFileDescriptor, which will
178     * take care of calling {@link ParcelFileDescriptor#close
179     * ParcelFileDescritor.close()} for you when the stream is closed.
180     */
181    public static class AutoCloseInputStream extends FileInputStream {
182        private final ParcelFileDescriptor mFd;
183
184        public AutoCloseInputStream(ParcelFileDescriptor fd) {
185            super(fd.getFileDescriptor());
186            mFd = fd;
187        }
188
189        @Override
190        public void close() throws IOException {
191            mFd.close();
192        }
193    }
194
195    /**
196     * An OutputStream you can create on a ParcelFileDescriptor, which will
197     * take care of calling {@link ParcelFileDescriptor#close
198     * ParcelFileDescritor.close()} for you when the stream is closed.
199     */
200    public static class AutoCloseOutputStream extends FileOutputStream {
201        private final ParcelFileDescriptor mFd;
202
203        public AutoCloseOutputStream(ParcelFileDescriptor fd) {
204            super(fd.getFileDescriptor());
205            mFd = fd;
206        }
207
208        @Override
209        public void close() throws IOException {
210            mFd.close();
211        }
212    }
213
214    @Override
215    public String toString() {
216        return "{ParcelFileDescriptor: " + mFileDescriptor + "}";
217    }
218
219    @Override
220    protected void finalize() throws Throwable {
221        try {
222            if (!mClosed) {
223                close();
224            }
225        } finally {
226            super.finalize();
227        }
228    }
229
230    public ParcelFileDescriptor(ParcelFileDescriptor descriptor) {
231        super();
232        mParcelDescriptor = descriptor;
233        mFileDescriptor = mParcelDescriptor.mFileDescriptor;
234    }
235
236    /*package */ParcelFileDescriptor(FileDescriptor descriptor) {
237        super();
238        mFileDescriptor = descriptor;
239        mParcelDescriptor = null;
240    }
241
242    /* Parcelable interface */
243    public int describeContents() {
244        return Parcelable.CONTENTS_FILE_DESCRIPTOR;
245    }
246
247    public void writeToParcel(Parcel out, int flags) {
248        out.writeFileDescriptor(mFileDescriptor);
249        if ((flags&PARCELABLE_WRITE_RETURN_VALUE) != 0 && !mClosed) {
250            try {
251                close();
252            } catch (IOException e) {
253                // Empty
254            }
255        }
256    }
257
258    public static final Parcelable.Creator<ParcelFileDescriptor> CREATOR
259            = new Parcelable.Creator<ParcelFileDescriptor>() {
260        public ParcelFileDescriptor createFromParcel(Parcel in) {
261            return in.readFileDescriptor();
262        }
263        public ParcelFileDescriptor[] newArray(int size) {
264            return new ParcelFileDescriptor[size];
265        }
266    };
267
268}
269