1/*
2 * Copyright (C) 2016 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;
18
19import android.system.ErrnoException;
20import android.system.OsConstants;
21
22/**
23 * Callback that handles file system requests from ProxyFileDescriptor.
24 *
25 * All callback methods except for onRelease should throw {@link android.system.ErrnoException}
26 * with proper errno on errors. See
27 * <a href="http://man7.org/linux/man-pages/man3/errno.3.html">errno(3)</a> and
28 * {@link android.system.OsConstants}.
29 *
30 * Typical errnos are
31 *
32 * <ul>
33 * <li>{@link android.system.OsConstants#EIO} for general I/O issues
34 * <li>{@link android.system.OsConstants#ENOENT} when the file is not found
35 * <li>{@link android.system.OsConstants#EBADF} if the file doesn't allow read/write operations
36 *     based on how it was opened.  (For example, trying to write a file that was opened read-only.)
37 * <li>{@link android.system.OsConstants#ENOSPC} if you cannot handle a write operation to
38 *     space/quota limitations.
39 * </ul>
40 * @see android.os.storage.StorageManager#openProxyFileDescriptor(int, ProxyFileDescriptorCallback,
41 *     Handler)
42 */
43public abstract class ProxyFileDescriptorCallback {
44    /**
45     * Returns size of bytes provided by the file descriptor.
46     * @return Size of bytes.
47     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
48     */
49    public long onGetSize() throws ErrnoException {
50        throw new ErrnoException("onGetSize", OsConstants.EBADF);
51    }
52
53    /**
54     * Provides bytes read from file descriptor.
55     * It needs to return exact requested size of bytes unless it reaches file end.
56     * @param offset Offset in bytes from the file head specifying where to read bytes. If a seek
57     *     operation is conducted on the file descriptor, then a read operation is requested, the
58     *     offset refrects the proper position of requested bytes.
59     * @param size Size for read bytes.
60     * @param data Byte array to store read bytes.
61     * @return Size of bytes returned by the function.
62     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
63     */
64    public int onRead(long offset, int size, byte[] data) throws ErrnoException {
65        throw new ErrnoException("onRead", OsConstants.EBADF);
66    }
67
68    /**
69     * Handles bytes written to file descriptor.
70     * @param offset Offset in bytes from the file head specifying where to write bytes. If a seek
71     *     operation is conducted on the file descriptor, then a write operation is requested, the
72     *     offset refrects the proper position of requested bytes.
73     * @param size Size for write bytes.
74     * @param data Byte array to be written to somewhere.
75     * @return Size of bytes processed by the function.
76     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
77     */
78    public int onWrite(long offset, int size, byte[] data) throws ErrnoException {
79        throw new ErrnoException("onWrite", OsConstants.EBADF);
80    }
81
82    /**
83     * Ensures all the written data are stored in permanent storage device.
84     * For example, if it has data stored in on memory cache, it needs to flush data to storage
85     * device.
86     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
87     */
88    public void onFsync() throws ErrnoException {
89        throw new ErrnoException("onFsync", OsConstants.EINVAL);
90    }
91
92    /**
93     * Invoked after the file is closed.
94     */
95    abstract public void onRelease();
96}
97