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 17 package android.os; 18 19 import android.system.ErrnoException; 20 import 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 */ 43 public 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 */ onGetSize()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 */ onRead(long offset, int size, byte[] data)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 */ onWrite(long offset, int size, byte[] data)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 */ onFsync()88 public void onFsync() throws ErrnoException { 89 throw new ErrnoException("onFsync", OsConstants.EINVAL); 90 } 91 92 /** 93 * Invoked after the file is closed. 94 */ onRelease()95 abstract public void onRelease(); 96 } 97